feat: 数字键盘 customKey 支持单独定制 title，用于无障碍读屏 (#6956)

* feat: 数字键盘 customKey 支持单独定制 title，用于无障碍读屏

* fix: cr

* feat: 简化对 key 配置的消费逻辑

* docs: update english docs

* fix: cr

* feat: 补充 aria-label

Author: edokeh

src/components/number-keyboard/index.en.md

@@ -23,12 +23,12 @@ tips: It is recommended to open the demo on the mobile side for better preview e
 ### Props
 
 | Name | Description | Type | Default |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- | --- |
 | afterClose | Callback when the keyboard is completely put away | `() => void` | - |
 | afterShow | Callback when the keyboard is completely bounced | `() => void` | - |
 | closeOnConfirm | Whether to automatically close when the ok button is clicked | `boolean` | `true` |
 | confirmText | The text of the confirm button, if `null` is set, it would be shown | `string \| null` | `null` |
-| customKey | Customized button | `string \| [string, string]` | - |
+| customKey | Customized button | `string | { key: string; title: string } | (string | { key: string; title: string })[]` | - |
 | destroyOnClose | Destroy `dom` when not visible | `boolean` | `false` |
 | forceRender | Render content forcely | `boolean` | `false` |
 | getContainer | To get the specified mounted HTML node, the default is `body`, if `null` returned, it would be rendered to the current node | `HTMLElement \| () => HTMLElement \| null` | `() => document.body` |

src/components/number-keyboard/index.zh.md

@@ -23,12 +23,12 @@ tips: 仅移动端下删除按钮支持长按快删（通过 touchStart/touchEnd
 ### 属性
 
 | 属性 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- | --- |
 | afterClose | 键盘完全收起回调 | `() => void` | - |
 | afterShow | 键盘完全弹出回调 | `() => void` | - |
 | closeOnConfirm | 是否在点击确定按钮时自动关闭 | `boolean` | `true` |
 | confirmText | 完成按钮文案，`null` 不展示 | `string \| null` | `null` |
-| customKey | 自定义按钮 | `string \| [string, string]` | - |
+| customKey | 自定义按钮 | `string | { key: string; title: string } | (string | { key: string; title: string })[]` | - |
 | destroyOnClose | 不可见时是否销毁 `DOM` 结构 | `boolean` | `false` |
 | forceRender | 强制渲染内容 | `boolean` | `false` |
 | getContainer | 指定挂载的 HTML 节点，默认为 `body`，如果为 `null` 的话，会渲染到当前节点 | `HTMLElement \| () => HTMLElement \| null` | `() => document.body` |

src/components/number-keyboard/number-keyboard.tsx

@@ -12,11 +12,13 @@ import SafeArea from '../safe-area'
 
 const classPrefix = 'adm-number-keyboard'
 
+type CustomKeyType = string | { key: string; title: string }
+
 export type NumberKeyboardProps = {
   visible?: boolean
   title?: string
   confirmText?: string | null
-  customKey?: string | [string, string]
+  customKey?: CustomKeyType | CustomKeyType[]
   randomOrder?: boolean
   showCloseButton?: boolean
   onInput?: (v: string) => void
@@ -161,27 +163,31 @@ export const NumberKeyboard: FC<NumberKeyboardProps> = p => {
     onKeyPress(e, 'BACKSPACE')
   }
 
-  const renderKey = (key: string, index: number) => {
-    const isNumberKey = /^\d$/.test(key)
-    const isBackspace = key === 'BACKSPACE'
+  const renderKey = (key: CustomKeyType, index: number) => {
+    const keyConfig = typeof key === 'string' ? { key, title: key } : key
+    const realKey = keyConfig.key
+    const isNumberKey = /^\d$/.test(realKey)
+    const isBackspace = realKey === 'BACKSPACE'
+    const title = isBackspace ? locale.Input.clear : keyConfig.title
     const className = classNames(`${classPrefix}-key`, {
       [`${classPrefix}-key-number`]: isNumberKey,
-      [`${classPrefix}-key-sign`]: !isNumberKey && key,
+      [`${classPrefix}-key-sign`]: !isNumberKey && realKey,
       [`${classPrefix}-key-mid`]:
         index === 9 && !!confirmText && keys.length < 12,
     })
 
-    const ariaProps = key
+    const ariaProps = realKey
       ? {
           role: 'button',
-          title: isBackspace ? locale.Input.clear : key,
+          title,
+          'aria-label': title,
           tabIndex: -1,
         }
       : undefined
 
     return (
       <div
-        key={key}
+        key={realKey}
         className={className}
         // 仅为  backspace 绑定，支持长按快速删除
         onTouchStart={isBackspace ? onBackspaceTouchStart : undefined}
@@ -193,11 +199,11 @@ export const NumberKeyboard: FC<NumberKeyboardProps> = p => {
         // backspace touchend 时会 preventDefault 阻止其后续 click 事件
         onClick={(e: MouseEvent<HTMLDivElement>) => {
           stopContinueClear()
-          onKeyPress(e, key)
+          onKeyPress(e, realKey)
         }}
         {...ariaProps}
       >
-        {isBackspace ? <TextDeletionOutline /> : key}
+        {isBackspace ? <TextDeletionOutline /> : realKey}
       </div>
     )
   }

src/components/number-keyboard/tests/number-keyboard.test.tsx

@@ -161,6 +161,28 @@ describe('NumberKeyboard', () => {
     expect(onInput).toBeCalledWith('.')
   })
 
+  test('render with customKey and title', () => {
+    const onInput = jest.fn()
+    render(
+      <NumberKeyboard
+        customKey={['-', { key: '.', title: '小数点' }]}
+        visible
+        onInput={onInput}
+      />
+    )
+    const left = screen.getByText('-')
+    const right = screen.getByText('.')
+    expect(left).toBeInTheDocument()
+    expect(right).toBeInTheDocument()
+    expect(left.title).toBe('-')
+    expect(right.title).toBe('小数点')
+
+    mockClick(left)
+    expect(onInput).toBeCalledWith('-')
+    mockClick(right)
+    expect(onInput).toBeCalledWith('.')
+  })
+
   test('render with multiple customKeys and confirmText', () => {
     render(
       <NumberKeyboard customKey={['-', '.']} visible confirmText='confirm' />

src/components/virtual-input/demos/demo1.tsx

@@ -13,7 +13,12 @@ export default () => {
         <VirtualInput
           placeholder='请输入内容'
           cursor={{ movable: true }}
-          keyboard={<NumberKeyboard confirmText='确定' customKey='.' />}
+          keyboard={
+            <NumberKeyboard
+              confirmText='确定'
+              customKey={{ key: '.', title: '小数点' }}
+            />
+          }
         />
       </DemoBlock>
 
@@ -57,7 +62,7 @@ export default () => {
         />
       </DemoBlock>
 
-      <DemoBlock title='只支持金额数字输入，配合 NumberKeyboard 使用'>
+      <DemoBlock title='只支持两位小数的金额输入，配合 NumberKeyboard 使用'>
         <VirtualInput
           value={value || '0'}
           cursor={{ movable: true }}
@@ -71,7 +76,12 @@ export default () => {
             }
           }}
           placeholder='请输入内容'
-          keyboard={<NumberKeyboard confirmText='确定' customKey='.' />}
+          keyboard={
+            <NumberKeyboard
+              confirmText='确定'
+              customKey={{ key: '.', title: '小数点' }}
+            />
+          }
           style={{
             '--font-size': '40px',
           }}

src/components/virtual-input/index.en.md

@@ -23,6 +23,7 @@ When you need to use it with the virtual keyboard.
 | onFocus | Triggered when element get focus | `() => void` | - |
 | placeholder | The placeholder text | `string` | - |
 | value | The input value | `string` | `''` |
+| cursor | Cursor related configuration, `movable` indicates whether it can be adjusted, `onMove` is the cursor movement callback | `{ movable?: boolean; onMove?: (position: number) => void }` | `{ movable: false }` |
 
 Strictly speaking, VirtualInput is not a form field component. It just displays the data.