[doc]Add NumKeyboard doc

any-tdf · Sep 20, 2023 · 5ed9fd2 · 5ed9fd2
1 parent f3432d5
commit 5ed9fd2
Show file tree

Hide file tree

Showing 16 changed files with 144 additions and 6 deletions.
diff --git a/doc/components/icon/guide.md b/doc/components/icon/guide.md
@@ -32,6 +32,8 @@ STDF 部分组件内使用的图标源自 [Remix Icon 图标库](https://remixic
 | ri-arrow-left-s-line          | NavBar           |
 | ri-volume-down-line           | NoticeBar        |
 | ri-close-line                 | NoticeBar        |
+| ri-delete-back-2-line         | NumKeyboard      |
+| ri-skip-down-line             | NumKeyboard      |
 | ri-more-line                  | Pagination       |
 | ri-more-fill                  | Pagination       |
 | ri-radio-button-line          | Radio            |

diff --git a/doc/components/icon/guide_en.md b/doc/components/icon/guide_en.md
@@ -32,6 +32,8 @@ Here are the icons and their corresponding components:
 | ri-arrow-left-s-line          | NavBar           |
 | ri-volume-down-line           | NoticeBar        |
 | ri-close-line                 | NoticeBar        |
+| ri-delete-back-2-line         | NumKeyboard      |
+| ri-skip-down-line             | NumKeyboard      |
 | ri-more-line                  | Pagination       |
 | ri-more-fill                  | Pagination       |
 | ri-radio-button-line          | Radio            |

diff --git a/doc/components/numKeyboard/FAQ.md b/doc/components/numKeyboard/FAQ.md
diff --git a/doc/components/numKeyboard/FAQ_en.md b/doc/components/numKeyboard/FAQ_en.md
diff --git a/doc/components/numKeyboard/api.md b/doc/components/numKeyboard/api.md
@@ -0,0 +1,28 @@
+## NumKeyboard Props
+
+| 属性         | 类型    | 默认值                 | 可选值                                          | 必传 | 说明                 |
+| ------------ | ------- | ---------------------- | ----------------------------------------------- | ---- | -------------------- |
+| type         | String  | 'button'               | 'button'/'block'                                | N    | 键盘样式类型。       |
+| visible      | Boolean | false                  | true/false                                      | N    | 是否显示键盘。       |
+| height       | String  | '12'                   | '8'/'10'/'12'/'14'/'16'/'20'                    | N    | 按键高度。           |
+| gap          | String  | '2'                    | '0'/'1'/'2'/'3'/'4'                             | N    | 按键间距。           |
+| p            | String  | '2'                    | '0'/'1'/'2'/'3'/'4'                             | N    | 键盘内边距。         |
+| reverse      | Boolean | false                  | true/false                                      | N    | 数字是否上下反向。   |
+| done         | Boolean | false                  | true/false                                      | N    | 是否显示完成按钮。   |
+| dot          | Boolean | false                  | true/false                                      | N    | 是否显示小数点。     |
+| close        | Boolean | false                  | true/false                                      | N    | 是否显示关闭按钮。   |
+| doneText     | String  | 当前语言的 common.done | -                                               | N    | 完成按钮文案。       |
+| doneDisabled | Boolean | false                  | true/false                                      | N    | 完成按钮是否禁用。   |
+| radius       | String  | 'base'                 | 'none'/'base'/'md'/'lg'/'xl'/'2xl'/'3xl'/'full' | N    | 按键圆角。           |
+| panelClass   | String  | ''                     | Class                                           | N    | 键盘面板注入 Class。 |
+| keyClass     | String  | ''                     | Class                                           | N    | 按键注入 Class。     |
+| doneClass    | String  | ''                     | Class                                           | N    | 完成按键注入 Class。 |
+| popup        | Object  | {}                     | 参考 Popup Props                                | N    | 弹出层配置项。       |
+
+## NumKeyboard Events
+
+| 名称  | 参数                                                                                                               | 描述                   |
+| ----- | ------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| click | event：事件对象，其中 detail 内有两个参数：<br />1. numStr：输入的数字字符内容；<br />2. key：本次点击的键盘 key。 | 每次点击任意按键触发。 |
+| open  | event：事件对象，其中 detail 内有一个参数 keyboardHeight，键盘高度。                                               | 键盘打开时触发。       |
+| close | -                                                                                                                  | 键盘关闭时触发。       |
diff --git a/doc/components/numKeyboard/api_en.md b/doc/components/numKeyboard/api_en.md
@@ -0,0 +1,28 @@
+## NumKeyboard Props
+
+| Property     | Type    | Default                                 | Options                                         | Required | Description                                    |
+| ------------ | ------- | --------------------------------------- | ----------------------------------------------- | -------- | ---------------------------------------------- |
+| type         | String  | 'button'                                | 'button'/'block'                                | No       | The style type of the keyboard.                |
+| visible      | Boolean | false                                   | true/false                                      | No       | Whether the keyboard is visible.               |
+| height       | String  | '12'                                    | '8'/'10'/'12'/'14'/'16'/'20'                    | No       | The height of the keys.                        |
+| gap          | String  | '2'                                     | '0'/'1'/'2'/'3'/'4'                             | No       | The gap between keys.                          |
+| p            | String  | '2'                                     | '0'/'1'/'2'/'3'/'4'                             | No       | The padding inside the keyboard.               |
+| reverse      | Boolean | false                                   | true/false                                      | No       | Whether the numbers are reversed.              |
+| done         | Boolean | false                                   | true/false                                      | No       | Whether to show the done button.               |
+| dot          | Boolean | false                                   | true/false                                      | No       | Whether to show the decimal point.             |
+| close        | Boolean | false                                   | true/false                                      | No       | Whether to show the close button.              |
+| doneText     | String  | The common.done of the current language | -                                               | No       | The text of the done button.                   |
+| doneDisabled | Boolean | false                                   | true/false                                      | No       | Whether the done button is disabled.           |
+| radius       | String  | 'base'                                  | 'none'/'base'/'md'/'lg'/'xl'/'2xl'/'3xl'/'full' | No       | The border radius of the keys.                 |
+| panelClass   | String  | ''                                      | Class                                           | No       | The injected class for the keyboard panel.     |
+| keyClass     | String  | ''                                      | Class                                           | No       | The injected class for the keys.               |
+| doneClass    | String  | ''                                      | Class                                           | No       | The injected class for the done button.        |
+| popup        | Object  | {}                                      | Refer to Popup Props                            | No       | The configuration options for the popup layer. |
+
+## NumKeyboard Events
+
+| Name  | Parameters                                                                                                                                              | Description                            |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| click | event: event object, with two parameters in the detail property: <br />1. numStr: the input number as a string; <br />2. key: the key that was clicked. | Triggered when any key is clicked.     |
+| open  | event: event object, with the keyboardHeight property in the detail property indicating the height of the keyboard.                                     | Triggered when the keyboard is opened. |
+| close | -                                                                                                                                                       | Triggered when the keyboard is closed. |
diff --git a/doc/components/numKeyboard/guide.md b/doc/components/numKeyboard/guide.md
@@ -0,0 +1,33 @@
+## 说明
+
+NumKeyboard 组件是一个虚拟的数字键盘，一般用于输入整数或小数。内部使用了网格布局，布局方式只有 3\*4 或 4\*4 两种，当不显示完成按键时，就只有 3 列，否则就是 4 列。
+
+## 按键
+
+NumKeyboard 组件的按键有 5 种类型，分别是 0-9 数字、删除、小数点、完成、关闭，其中 0-9 数字、删除是必须的，完成、删除、关闭是非必须的。
+
+非必须按键的优先级为：完成 > 小数点 > 关闭，所以当同时需要显示小数点和关闭时，由于关闭的优先级低于小数点，所以关闭按钮将不会显示，如果需要强制显示关闭按钮，只能关闭小数点的显示。请参考示例。
+
+## reverse
+
+通常情况，我们在移动设备上习惯的数字键盘布局是从上到下的顺序，但是在传统物理键盘上数字键盘是按照从下到上的顺序排列的，考虑部分特殊行业人群的使用习惯，NumKeyboard 组件提供了 reverse 参数，当 reverse 为 true 时，数字键盘将会按照从下到上的顺序排列。
+
+## doneDisabled
+
+当 doneDisabled 为 true 时，完成按钮将会被禁用，此时完成按钮的文案将会变成灰色，且不可点击。可用于根据输入内容动态控制业务流程。
+
+## 按键文字大小
+
+按键文字大小会动态的跟随按键的高度变化。
+
+## CSS 注入
+
+通过 injClass 参数可以向 NumKeyboard 的三个地方注入 CSS 名称（不仅限于 Tailwind CSS），这将使组件样式有更多自定义可能性，示例中通过 injClass 实现了自定义背景色与文字颜色。
+
+panelClass 注入后作用到键盘面板，keyClass 注入后作用到所有按键，doneClass 注入后作用到完成按键。
+
+若注入的 class 没生效，请在注入的 class 名称前添加“!” ，可参考 [Tailwind Important modifier](https://tailwindcss.com/docs/configuration#important-modifier)。
+
+## popup
+
+NumKeyboard 是在 Popup 的基础上封装的，通过预先定义一些 Popup 的 Props 实现，因此可以通过传入 Popup 的属性来实现不同的效果。比如示例中通过设置 popup 改变了过渡动画和背景透明度。
diff --git a/doc/components/numKeyboard/guide_en.md b/doc/components/numKeyboard/guide_en.md
@@ -0,0 +1,33 @@
+## Description
+
+The NumKeyboard component is a virtual numeric keyboard used for inputting integers or decimals. It uses a grid layout, with two layout options: 3\*4 or 4\*4. If the completion key is not displayed, there will only be 3 columns; otherwise, there will be 4 columns.
+
+## Keys
+
+The NumKeyboard component has 5 types of keys: digits 0-9, delete, decimal point, completion, and close. Digits 0-9 and delete are required, while completion, delete, and close are optional.
+
+The priority of optional keys is as follows: completion > decimal point > close. Therefore, if both the decimal point and close keys need to be displayed, the close button will not be shown, as the close key has a lower priority than the decimal point. If the close button needs to be forcibly shown, the display of the decimal point will need to be disabled. Please refer to the example.
+
+## Reverse
+
+Normally, on mobile devices, we are accustomed to the layout of the numeric keyboard being arranged from top to bottom. However, on traditional physical keyboards, the numeric keypad is arranged from bottom to top. To accommodate the usage habits of certain industries, the NumKeyboard component provides a reverse parameter. When reverse is set to true, the numeric keyboard will be arranged from bottom to top.
+
+## doneDisabled
+
+When doneDisabled is set to true, the completion button will be disabled. In this case, the completion button will appear grayed out and cannot be clicked. This can be used to dynamically control the business flow based on the input content.
+
+## Key Text Size
+
+The key text size will dynamically adjust according to the height of the key.
+
+## CSS Injection
+
+The injClass parameter can be used to inject CSS class names (not limited to Tailwind CSS) into three parts of the NumKeyboard. This allows for more customization possibilities for the component's style. In the example, custom background color and text color are achieved through injClass.
+
+After the panelClass is injected, it will affect the keyboard panel. After the keyClass is injected, it will affect all keys. After the doneClass is injected, it will affect the completion key.
+
+If the injected class does not take effect, please prepend "!" to the class name being injected. You can refer to the [Tailwind Important modifier](https://tailwindcss.com/docs/configuration#important-modifier) for more information.
+
+## Popup
+
+The NumKeyboard is built on top of the Popup component. Different effects can be achieved by passing in Popup properties. For example, in the example, the transition animation and background transparency are changed by setting popup.
diff --git a/doc/components/numKeyboard/version.md b/doc/components/numKeyboard/version.md
diff --git a/doc/components/numKeyboard/version_en.md b/doc/components/numKeyboard/version_en.md
diff --git a/doc/guide/changelog.md b/doc/guide/changelog.md
@@ -1,3 +1,7 @@
+## 0.3.0
+
+- 新增 NumKeyboard 组件，详见 [NumKeyboard](https://stdf.design/#/components?nav=numKeyboard&tab=0)。
+
 ## 0.2.11
 
 - 修复 Cell，详见 [Cell](https://stdf.design/#/components?nav=cell&tab=4)。

diff --git a/doc/guide/changelog_en.md b/doc/guide/changelog_en.md
@@ -1,3 +1,7 @@
+## 0.3.0
+
+- Add NumKeyboard component, please see [NumKeyboard](https://stdf.design/#/components?nav=numKeyboard&tab=0).
+
 ## 0.2.11
 
 - Fix Cell, please see [Cell](https://stdf.design/#/components?nav=cell&tab=4).

diff --git a/doc/guide/future.md b/doc/guide/future.md
@@ -1,11 +1,11 @@
 ## 新增 💪
 
+- [ ] 按照 Tailwind CSS 变量规则，实现自定义主题色。
+- [ ] 新增 SecurityCode-安全码组件，一般用于输入短信或邮件收到的数字校验码。
 - [x] 开发一款 Vite/Rollup 插件，支持将指定目录下的所有 svg 合并为 SVG symbol。
 - [x] 开发一款 VS Code 插件，支持光标悬浮显示 STDF 组件 API 等功能。
 - [x] 开发一款模板脚手架，支持按照配置初始使用 STDF 的工程，初步考虑支持 Vite、SvelteKit。
-- [ ] 按照 Tailwind CSS 变量规则，实现自定义主题色。
-- [ ] 新增 NumKeyboard-数字键盘组件，一般用于输入数字。
-- [ ] 新增 SecurityCode-安全码组件，一般用于输入短信或邮件收到的数字校验码。
+- [x] 新增 NumKeyboard-数字键盘组件，一般用于输入数字。
 - [x] 新增 Pagination-分页组件。
 
 ---

diff --git a/doc/guide/future_en.md b/doc/guide/future_en.md
@@ -1,11 +1,11 @@
 ## New Features 💪
 
+- [ ] Implement custom theme colors according to Tailwind CSS variable rules.
+- [ ] Add SecurityCode component, which is generally used for entering numeric verification codes received via SMS or email.
 - [x] Develop a Vite/Rollup plugin that supports merging all SVGs in a specified directory into an SVG symbol.
 - [x] Develop a VS Code plugin that supports displaying STDF component API and other functions when hovering over the cursor.
 - [x] Develop a template scaffold that supports initializing STDF projects according to configuration. Initial support for Vite and SvelteKit.
-- [ ] Implement custom theme colors according to Tailwind CSS variable rules.
-- [ ] Add NumKeyboard component, which is generally used for entering numbers.
-- [ ] Add SecurityCode component, which is generally used for entering numeric verification codes received via SMS or email.
+- [x] Add NumKeyboard component, which is generally used for entering numbers.
 - [x] Added Pagination component.
 
 ---

diff --git a/doc/guide/icon.md b/doc/guide/icon.md
@@ -32,6 +32,8 @@ STDF 部分组件内使用的图标源自 [Remix Icon 图标库](https://remixic
 | ri-arrow-left-s-line          | NavBar           |
 | ri-volume-down-line           | NoticeBar        |
 | ri-close-line                 | NoticeBar        |
+| ri-delete-back-2-line         | NumKeyboard      |
+| ri-skip-down-line             | NumKeyboard      |
 | ri-more-line                  | Pagination       |
 | ri-more-fill                  | Pagination       |
 | ri-radio-button-line          | Radio            |

diff --git a/doc/guide/icon_en.md b/doc/guide/icon_en.md
@@ -32,6 +32,8 @@ Here are the icons and their corresponding components:
 | ri-arrow-left-s-line          | NavBar           |
 | ri-volume-down-line           | NoticeBar        |
 | ri-close-line                 | NoticeBar        |
+| ri-delete-back-2-line         | NumKeyboard      |
+| ri-skip-down-line             | NumKeyboard      |
 | ri-more-line                  | Pagination       |
 | ri-more-fill                  | Pagination       |
 | ri-radio-button-line          | Radio            |