feat(Choice): 新增 Choice 选择交互组件 - #1978
Conversation
实现 AI 对话场景中的结构化选择交互组件，包含： 核心功能： - 单选/多选模式 (mode: single/multiple) - 三种布局模式 (layout: list/grid/card) - 四种指示器类型 (indicator: check/radio/number/none) - 受控/非受控模式 - maxCount 多选上限控制 - confirmable 确认按钮 + onConfirm 回调 AI 场景特性： - recommended 推荐标记 (primary/secondary) - disabledReason 禁用原因提示 - loading 骨架屏加载态 - meta 元数据透传 - 嵌套子选项分组 工程实现： - 完整的 TypeScript 类型定义 - CSS-in-JS 样式方案 + Design Token - 语义化 DOM 结构 (SemanticType) - fadeIn/fadeInLeft 渐入动画 - 键盘导航支持 - XProvider 组件配置注册 - 11 个 Demo + 中英文文档 - 28 个单元测试全部通过
对照 issue ant-design#1957 验收标准补充以下缺失项： 1. Tooltip for disabledReason：禁用选项 hover 时通过 antd Tooltip 展示原因 2. locale 国际化：注册 Choice 到 xLocale，支持 confirmText/recommended/maxSelected/disabledHint 3. Design Token 完整化：补充 itemActiveBg/itemRecommendedBorderColor/itemDisabledBorderColor/ titleFontSize/titleLineHeight/labelFontSize/labelLineHeight/descFontSize/descLineHeight/ headerPadding/listPadding/footerPadding/borderRadius/gridColumns/motionDuration 等 token 4. select.test.tsx：新增 19 个选择逻辑专项测试（单选/多选/maxCount/受控/嵌套/ChangeInfo 等） 5. items 默认值处理，避免无 props 渲染时报错 全部 71 个测试通过，TypeScript 类型检查通过
dosubot
Bot
added
documentation
📝 WalkthroughWalkthrough新增完整的 ChangesChoice 组件
Estimated code review effort: 4 (Complex) | ~60 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the new Choice component, designed to present structured options in AI conversation scenarios with support for single/multiple selection, various layouts, loading states, and recommended badges. The review feedback highlights several areas for improvement: the ChangeInfo payload in onConfirm contains misleading empty or hardcoded values; the onChange and related value types should include undefined to correctly type deselection in single mode; default texts for recommended badges and the maxCount footer text are hardcoded and should be internationalized using the locale; and the opacity value 0.6 in the styles should utilize a design token instead of a magic number.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| onConfirm(val, { | ||
| value: val, | ||
| items, | ||
| changedItems: [], | ||
| type: 'select', | ||
| }); |
There was a problem hiding this comment.
传递给 onConfirm 的 ChangeInfo 对象似乎包含不正确或有误导性的值。
changedItems是一个空数组。它应该包含正在被确认的选项，这可以从mergedValue和items中派生出来。type硬编码为'select'。对于确认操作来说，这是有误导性的。最好引入一个'confirm'类型。
为了解决这个问题，我建议：
- 在
interface.ts中扩展ChangeInfo['type']以包含'confirm'。 - 在调用
onConfirm时，使用type: 'confirm'并填充changedItems为当前选中的选项。
const confirmedItems = items.filter((item) => mergedValue.includes(item.key));
onConfirm(val, {
value: val,
items,
changedItems: confirmedItems,
type: 'select', // TODO: 更新 interface.ts 后应改为 'confirm'
});
| * @desc 选中变化回调 | ||
| * @descEN Callback when selection changes | ||
| */ | ||
| onChange?: (value: ChoiceValueType | ChoiceValueType[], info: ChangeInfo) => void; |
There was a problem hiding this comment.
onChange 中 value 参数的类型不正确。在单选模式下取消选择某个项目时，onChange 会以 undefined 作为参数被调用，但类型 ChoiceValueType | ChoiceValueType[] 不包含 undefined。这可能会给组件的 TypeScript 用户导致类型错误。
应将其更改为 ChoiceValueType | ChoiceValueType[] | undefined。
这也适用于：
ChoiceProps['value']ChoiceProps['defaultValue']ChoiceProps['onConfirm']的 value 参数ChangeInfo['value']
| onChange?: (value: ChoiceValueType | ChoiceValueType[], info: ChangeInfo) => void; | |
| onChange?: (value: ChoiceValueType | ChoiceValueType[] | undefined, info: ChangeInfo) => void; |
| {(item.recommended === true || item.recommended === 'primary') && ( | ||
| <div className={`${prefixCls}-item-recommend-badge`}> | ||
| {item.recommendedReason || 'AI Recommended'} | ||
| </div> | ||
| )} | ||
| {item.recommended === 'secondary' && ( | ||
| <div | ||
| className={`${prefixCls}-item-recommend-badge ${prefixCls}-item-recommend-badge-secondary`} | ||
| > | ||
| {item.recommendedReason || 'Recommended'} | ||
| </div> | ||
| )} |
There was a problem hiding this comment.
推荐徽章的默认文案 'AI Recommended' 和 'Recommended' 是硬编码的。该组件支持 i18n，因此这些字符串应该来自语言包文件。
为了解决这个问题，你可以将 locale 对象从 Choice 主组件通过 ChoiceContext 向下传递。
- 在
packages/x/components/choice/context.ts中，将locale添加到ChoiceContextProps。 - 在
packages/x/components/choice/index.tsx中，将locale对象传递到ChoiceContext.Provider的 value 中。 - 在
Item.tsx文件中，从 context 中消费locale并使用相应的键，例如：item.recommendedReason || locale.aiRecommended和item.recommendedReason || locale.recommended。
目前的语言包文件已经包含了 recommended 键，你可能需要为 'AI Recommended' 添加一个新的键。
| if (!footer && !confirmable) return null; | ||
|
|
||
| const selectedCount = mergedValue.length; | ||
| const maxText = mode === 'multiple' && maxCount ? `${selectedCount}/${maxCount}` : null; |
There was a problem hiding this comment.
maxCount 的文本格式是硬编码的。它应该使用语言包中的 maxSelected 键进行国际化，该键支持 {count} 和 {max} 占位符。
| const maxText = mode === 'multiple' && maxCount ? `${selectedCount}/${maxCount}` : null; | |
| const maxText = mode === 'multiple' && maxCount ? locale.maxSelected.replace('{count}', String(selectedCount)).replace('{max}', String(maxCount)) : null; |
| cursor: 'not-allowed', | ||
| background: token.itemDisabledBg, | ||
| borderColor: token.itemDisabledBorderColor, | ||
| opacity: 0.6, |
There was a problem hiding this comment.
透明度值 0.6 是一个魔法数字。最好使用设计令牌（例如 token.opacityDisabled），如果可用的话。或者，为了更好的可维护性和一致性，应在组件的令牌集内将其定义为变量。
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🧹 Nitpick comments (2)
packages/x/components/choice/demo/basic.tsx (1)
54-58: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value为默认导出的组件添加名称。
在 React 中，默认导出匿名箭头函数会导致组件在 React DevTools 中显示为 "Unknown"，降低了可调试性。建议为其提供一个明确的名称。
♻️ 建议的重构
-export default () => ( +const BasicDemo: React.FC = () => ( <App> <Demo /> </App> ); + +export default BasicDemo;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/x/components/choice/demo/basic.tsx` around lines 54 - 58, 为 basic.tsx 中的默认导出组件提供明确名称，将匿名箭头函数改为命名组件并保持现有 App 与 Demo 渲染结构不变，以便 React DevTools 正确显示组件名称。packages/x/components/choice/context.ts (1)
1-14: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value优化类型引入与声明。
建议将
ChoiceItemType提升至文件顶部的import中以提升可读性。另外，由于useSelect内部已将选中值严格归一化为数组（mergedValue），传递给 Context 的selectedKeys类型一定是数组，可以将其类型安全地收窄为ChoiceValueType[]。♻️ 建议修复
import React from 'react'; -import type { ChoiceProps } from './interface'; +import type { ChoiceProps, ChoiceItemType, ChoiceValueType } from './interface'; export interface ChoiceContextProps { prefixCls: string; mode: 'single' | 'multiple'; disabled: boolean; indicator: 'check' | 'radio' | 'number' | 'none'; - selectedKeys: ChoiceProps['value']; + selectedKeys: ChoiceValueType[]; isSelected: (key: string | number) => boolean; - onItemClick: (item: import('./interface').ChoiceItemType, index: number) => void; + onItemClick: (item: ChoiceItemType, index: number) => void; classNames?: ChoiceProps['classNames']; styles?: ChoiceProps['styles']; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/x/components/choice/context.ts` around lines 1 - 14, 优化 ChoiceContextProps 的类型声明：将 ChoiceItemType 和 ChoiceValueType 提升为文件顶部的类型导入，并将 selectedKeys 从 ChoiceProps['value'] 收窄为 ChoiceValueType[]，保持 onItemClick 使用已导入的 ChoiceItemType。
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/x/components/choice/index.tsx`:
- Around line 227-241: 在组件渲染逻辑中为 item.children.map 返回的每个子选项添加与顶层选项一致的 data-key
容器，并使用 child.key 作为该属性值，使 ChoiceRef.scrollTo 能通过选择器定位子选项；保持现有 ChoiceItem 的 item
和 childIndex 传递不变。
- Around line 190-195: 调整根容器的 style 合并顺序，定位到根节点的 style 属性：先合并
contextConfig.style，再合并用户传入的 style，最后保留 styles.root，以确保用户显式样式不会被
contextConfig.style 覆盖，并与组件其它区域的优先级约定一致。
- Around line 163-181: Update the confirm Button in the confirmable Choice block
to include the component-level disabled prop in its disabled condition, so it
remains disabled whenever Choice is disabled or selectedCount is zero. Preserve
the existing onConfirm behavior for enabled choices.
- Around line 66-74: 在组件中更新 useSelect 的解构以取得 isMaxReached，并将其加入
ChoiceContext.Provider 的 value；确保 ChoiceItem 可依据 isMaxReached && !selected 为达到
maxCount 后的未选中项应用禁用样式。
- Around line 200-205: 补充 Choice 的真实 ARIA 语义：在
packages/x/components/choice/index.tsx 的列表容器保留现有 data-role，并根据 mode 添加
role="radiogroup" 或 role="group"；在 packages/x/components/choice/Item.tsx 的条目根据
mode 添加 role="radio" 或 "checkbox"，同时设置反映选中状态的 aria-checked 和禁用状态的 aria-disabled。
In `@packages/x/components/choice/interface.ts`:
- Around line 148-151: Update the onChange callback type in the choice interface
to allow undefined as a possible value, including the single-selection
deselection case, while preserving the existing single- and multi-selection
value types.
- Around line 84-90: Update the ChangeInfo.value type to include undefined,
preserving the existing ChoiceValueType and array variants so single-selection
cancellation is represented correctly.
In `@packages/x/components/choice/Item.tsx`:
- Around line 126-140: Remove the always-visible disabled-reason block from the
item content rendered by the component, while preserving the Tooltip wrapper
around itemNode when disabled and item.disabledReason are present. Keep
item.disabledReason as the Tooltip title so the reason is shown only on hover.
In `@packages/x/components/choice/style/index.ts`:
- Around line 205-217: 合并 `${componentCls}-layout-card` 的重复样式定义：保留前面用于容器网格布局的
display、gridTemplateColumns 和 gap，并将末尾重复块中的必要 `-item`
样式合并到同一个对象中；删除文件末尾重复声明，确保该计算属性键只定义一次。
- Around line 113-117: 在 genChoiceStyle 的根选择器中应用 token.borderRadius 作为容器的
border-radius，使 ConfigProvider 自定义的整体圆角生效；保留 ComponentToken、ChoiceToken 的声明及
prepareComponentToken 中默认值，并确保引用与现有 token 样式生成方式一致。
- Around line 350-357: Update the `${componentCls}-nested` style block to
replace the physical `marginLeft` property with the appropriate logical margin
property, preserving the existing indentation amount and ensuring it mirrors
correctly under the `${componentCls}-rtl` direction.
- Around line 183-184: Remove the unit() wrapper from line-height assignments
for titleLineHeight, labelLineHeight, and descLineHeight, using each token’s raw
unitless value directly. Keep unit() for font-size values unchanged.
---
Nitpick comments:
In `@packages/x/components/choice/context.ts`:
- Around line 1-14: 优化 ChoiceContextProps 的类型声明：将 ChoiceItemType 和
ChoiceValueType 提升为文件顶部的类型导入，并将 selectedKeys 从 ChoiceProps['value'] 收窄为
ChoiceValueType[]，保持 onItemClick 使用已导入的 ChoiceItemType。
In `@packages/x/components/choice/demo/basic.tsx`:
- Around line 54-58: 为 basic.tsx 中的默认导出组件提供明确名称，将匿名箭头函数改为命名组件并保持现有 App 与 Demo
渲染结构不变，以便 React DevTools 正确显示组件名称。
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 2a9e8e21-20c6-47eb-9680-9b095300cdc2
⛔ Files ignored due to path filters (3)
packages/x/components/choice/__tests__/__snapshots__/demo-extend.test.ts.snapis excluded by!**/*.snappackages/x/components/choice/__tests__/__snapshots__/demo.test.ts.snapis excluded by!**/*.snappackages/x/components/choice/__tests__/__snapshots__/index.test.tsx.snapis excluded by!**/*.snap
📒 Files selected for processing (41)
packages/x/components/choice/Item.tsxpackages/x/components/choice/__tests__/demo-extend.test.tspackages/x/components/choice/__tests__/demo.test.tspackages/x/components/choice/__tests__/index.test.tsxpackages/x/components/choice/__tests__/select.test.tsxpackages/x/components/choice/context.tspackages/x/components/choice/demo/_semantic.tsxpackages/x/components/choice/demo/basic.mdpackages/x/components/choice/demo/basic.tsxpackages/x/components/choice/demo/card-layout.mdpackages/x/components/choice/demo/card-layout.tsxpackages/x/components/choice/demo/confirmable.mdpackages/x/components/choice/demo/confirmable.tsxpackages/x/components/choice/demo/controlled.mdpackages/x/components/choice/demo/controlled.tsxpackages/x/components/choice/demo/disabled.mdpackages/x/components/choice/demo/disabled.tsxpackages/x/components/choice/demo/grid-layout.mdpackages/x/components/choice/demo/grid-layout.tsxpackages/x/components/choice/demo/in-bubble.mdpackages/x/components/choice/demo/in-bubble.tsxpackages/x/components/choice/demo/indicator.mdpackages/x/components/choice/demo/indicator.tsxpackages/x/components/choice/demo/loading.mdpackages/x/components/choice/demo/loading.tsxpackages/x/components/choice/demo/multiple.mdpackages/x/components/choice/demo/multiple.tsxpackages/x/components/choice/demo/recommended.mdpackages/x/components/choice/demo/recommended.tsxpackages/x/components/choice/hooks/use-select.tspackages/x/components/choice/index.en-US.mdpackages/x/components/choice/index.tsxpackages/x/components/choice/index.zh-CN.mdpackages/x/components/choice/interface.tspackages/x/components/choice/style/index.tspackages/x/components/index.tspackages/x/components/locale/en_US.tspackages/x/components/locale/index.tsxpackages/x/components/locale/zh_CN.tspackages/x/components/theme/interface/components.tspackages/x/components/x-provider/context.ts
| const { mergedValue, handleItemClick, isSelected } = useSelect({ | ||
| mode, | ||
| value, | ||
| defaultValue, | ||
| onChange, | ||
| maxCount, | ||
| disabled, | ||
| items, | ||
| }); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
isMaxReached 被计算但从未使用，达到 maxCount 后未选中项缺少禁用反馈
useSelect 返回了 isMaxReached（见 hooks/use-select.ts 中 return { mergedValue, handleItemClick, isSelected, isMaxReached };），但此处未解构、也未通过 ChoiceContext 传给 ChoiceItem。结果是：一旦达到 maxCount，未被选中的选项在 UI 上仍呈现为可点击/可用状态（无禁用样式），用户点击后无任何视觉反馈，仅表现为“点击无效”。
🐛 建议修复
- const { mergedValue, handleItemClick, isSelected } = useSelect({
+ const { mergedValue, handleItemClick, isSelected, isMaxReached } = useSelect({
mode,
value,
defaultValue,
onChange,
maxCount,
disabled,
items,
});并将 isMaxReached 加入 ChoiceContext.Provider 的 value，供 ChoiceItem 用于给未选中项追加禁用样式（isMaxReached && !selected）。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/index.tsx` around lines 66 - 74, 在组件中更新
useSelect 的解构以取得 isMaxReached，并将其加入 ChoiceContext.Provider 的 value；确保 ChoiceItem
可依据 isMaxReached && !selected 为达到 maxCount 后的未选中项应用禁用样式。
| {confirmable && ( | ||
| <Button | ||
| type="primary" | ||
| disabled={selectedCount === 0} | ||
| onClick={() => { | ||
| if (onConfirm) { | ||
| const val = mode === 'single' ? mergedValue[0] : mergedValue; | ||
| onConfirm(val, { | ||
| value: val, | ||
| items, | ||
| changedItems: [], | ||
| type: 'select', | ||
| }); | ||
| } | ||
| }} | ||
| > | ||
| {confirmText || locale.confirmText} | ||
| </Button> | ||
| )} |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
确认按钮未考虑组级 disabled，禁用整个 Choice 时仍可点击“确认”
disabled={selectedCount === 0} 只判断了是否有选中项，未结合组件级 disabled prop。当 disabled=true（例如结合受控 value 或 defaultValue 预置了选中项）时，确认按钮依然可点击并触发 onConfirm，与组件整体禁用语义相悖。
🐛 建议修复
- disabled={selectedCount === 0}
+ disabled={disabled || selectedCount === 0}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {confirmable && ( | |
| <Button | |
| type="primary" | |
| disabled={selectedCount === 0} | |
| onClick={() => { | |
| if (onConfirm) { | |
| const val = mode === 'single' ? mergedValue[0] : mergedValue; | |
| onConfirm(val, { | |
| value: val, | |
| items, | |
| changedItems: [], | |
| type: 'select', | |
| }); | |
| } | |
| }} | |
| > | |
| {confirmText || locale.confirmText} | |
| </Button> | |
| )} | |
| {confirmable && ( | |
| <Button | |
| type="primary" | |
| disabled={disabled || selectedCount === 0} | |
| onClick={() => { | |
| if (onConfirm) { | |
| const val = mode === 'single' ? mergedValue[0] : mergedValue; | |
| onConfirm(val, { | |
| value: val, | |
| items, | |
| changedItems: [], | |
| type: 'select', | |
| }); | |
| } | |
| }} | |
| > | |
| {confirmText || locale.confirmText} | |
| </Button> | |
| )} |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/index.tsx` around lines 163 - 181, Update the
confirm Button in the confirmable Choice block to include the component-level
disabled prop in its disabled condition, so it remains disabled whenever Choice
is disabled or selectedCount is zero. Preserve the existing onConfirm behavior
for enabled choices.
| <div | ||
| {...htmlProps} | ||
| ref={composeRef(containerRef, motionRef)} | ||
| className={clsx(mergedCls, motionClassName)} | ||
| style={{ ...style, ...contextConfig.style, ...styles.root }} | ||
| > |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
根容器 style 合并顺序与组件内其它位置不一致，contextConfig.style 会覆盖用户显式传入的 style
对比同文件中 header（Line 123）、description（Line 141）、list（Line 203）、footer（Line 159）的合并顺序均为 {...contextConfig.styles.x, ...styles.x}（组件级配置最终生效），但根节点却是 {...style, ...contextConfig.style, ...styles.root}，即 contextConfig.style 排在用户显式 style 之后，会反过来覆盖用户传入的行内样式，与其它位置的优先级约定相反。
🐛 建议修复
- style={{ ...style, ...contextConfig.style, ...styles.root }}
+ style={{ ...contextConfig.style, ...style, ...styles.root }}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <div | |
| {...htmlProps} | |
| ref={composeRef(containerRef, motionRef)} | |
| className={clsx(mergedCls, motionClassName)} | |
| style={{ ...style, ...contextConfig.style, ...styles.root }} | |
| > | |
| <div | |
| {...htmlProps} | |
| ref={composeRef(containerRef, motionRef)} | |
| className={clsx(mergedCls, motionClassName)} | |
| style={{ ...contextConfig.style, ...style, ...styles.root }} | |
| > |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/index.tsx` around lines 190 - 195, 调整根容器的 style
合并顺序，定位到根节点的 style 属性：先合并 contextConfig.style，再合并用户传入的 style，最后保留
styles.root，以确保用户显式样式不会被 contextConfig.style 覆盖，并与组件其它区域的优先级约定一致。
| <div | ||
| ref={listRef} | ||
| className={mergedListCls} | ||
| style={{ ...contextConfig.styles.list, ...styles.list }} | ||
| data-role={mode === 'single' ? 'radiogroup' : 'group'} | ||
| > |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== outline: packages/x/components/choice/index.tsx =="
ast-grep outline packages/x/components/choice/index.tsx --view expanded || true
echo
echo "== outline: packages/x/components/choice/Item.tsx =="
ast-grep outline packages/x/components/choice/Item.tsx --view expanded || true
echo
echo "== relevant snippets =="
sed -n '1,260p' packages/x/components/choice/index.tsx | nl -ba | sed -n '160,230p'
echo
sed -n '1,220p' packages/x/components/choice/Item.tsx | nl -ba | sed -n '1,180p'
echo
echo "== search for ARIA / role usage in choice components =="
rg -n --no-heading "aria-|role=|data-role|data-selected|data-disabled" packages/x/components/choiceRepository: ant-design/x
Length of output: 733
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== packages/x/components/choice/index.tsx (around list container) =="
sed -n '170,220p' packages/x/components/choice/index.tsx | awk '{printf "%4d %s\n", NR+169, $0}'
echo
echo "== packages/x/components/choice/Item.tsx (entire file) =="
sed -n '1,220p' packages/x/components/choice/Item.tsx | awk '{printf "%4d %s\n", NR, $0}'
echo
echo "== search for aria/role usage in related choice files =="
rg -n --no-heading "aria-|role=|data-role|data-selected|data-disabled" packages/x/components/choiceRepository: ant-design/x
Length of output: 41407
补上 Choice 的真实 ARIA 语义
data-role 只适合测试/样式，当前两个交互节点都没有真实 role/aria-*，辅助技术无法识别分组、单选/复选状态和禁用状态。保留 data-* 的同时，在 packages/x/components/choice/index.tsx 的列表容器加 role="radiogroup"/group"，在 packages/x/components/choice/Item.tsx 的条目加 role="radio"/checkbox"、aria-checked 和 aria-disabled。
📍 Affects 2 files
packages/x/components/choice/index.tsx#L200-L205(this comment)packages/x/components/choice/Item.tsx#L74-L93
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/index.tsx` around lines 200 - 205, 补充 Choice 的真实
ARIA 语义：在 packages/x/components/choice/index.tsx 的列表容器保留现有 data-role，并根据 mode 添加
role="radiogroup" 或 role="group"；在 packages/x/components/choice/Item.tsx 的条目根据
mode 添加 role="radio" 或 "checkbox"，同时设置反映选中状态的 aria-checked 和禁用状态的 aria-disabled。
| {items.map((item, index) => { | ||
| return ( | ||
| <div key={item.key} data-key={item.key}> | ||
| <ChoiceItem item={item} index={index} /> | ||
| {/* Nested children */} | ||
| {item.children && item.children.length > 0 && ( | ||
| <div className={`${prefixCls}-nested`}> | ||
| {item.children.map((child, childIndex) => ( | ||
| <ChoiceItem key={child.key} item={child} index={childIndex} /> | ||
| ))} | ||
| </div> | ||
| )} | ||
| </div> | ||
| ); | ||
| })} |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
嵌套子选项缺少 data-key 容器，导致 ChoiceRef.scrollTo 对子选项静默失效
顶层选项用 <div key={item.key} data-key={item.key}> 包裹，scrollTo（Line 82-85）通过 listRef.current?.querySelector('[data-key="${key}"]') 定位。但 item.children 的渲染（Line 234-236）直接返回 <ChoiceItem key={child.key} item={child} index={childIndex} />，没有任何带 data-key 的包裹元素。调用 choiceRef.current?.scrollTo(childKey) 时 querySelector 找不到对应节点，itemEl 为 undefined，因可选链而静默无效，与 Issue 中“ChoiceRef，用于滚动到指定选项”的验收标准不符。
🐛 建议修复
{item.children.map((child, childIndex) => (
- <ChoiceItem key={child.key} item={child} index={childIndex} />
+ <div key={child.key} data-key={child.key}>
+ <ChoiceItem item={child} index={childIndex} />
+ </div>
))}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {items.map((item, index) => { | |
| return ( | |
| <div key={item.key} data-key={item.key}> | |
| <ChoiceItem item={item} index={index} /> | |
| {/* Nested children */} | |
| {item.children && item.children.length > 0 && ( | |
| <div className={`${prefixCls}-nested`}> | |
| {item.children.map((child, childIndex) => ( | |
| <ChoiceItem key={child.key} item={child} index={childIndex} /> | |
| ))} | |
| </div> | |
| )} | |
| </div> | |
| ); | |
| })} | |
| {items.map((item, index) => { | |
| return ( | |
| <div key={item.key} data-key={item.key}> | |
| <ChoiceItem item={item} index={index} /> | |
| {/* Nested children */} | |
| {item.children && item.children.length > 0 && ( | |
| <div className={`${prefixCls}-nested`}> | |
| {item.children.map((child, childIndex) => ( | |
| <div key={child.key} data-key={child.key}> | |
| <ChoiceItem item={child} index={childIndex} /> | |
| </div> | |
| ))} | |
| </div> | |
| )} | |
| </div> | |
| ); | |
| })} |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/index.tsx` around lines 227 - 241, 在组件渲染逻辑中为
item.children.map 返回的每个子选项添加与顶层选项一致的 data-key 容器，并使用 child.key 作为该属性值，使
ChoiceRef.scrollTo 能通过选择器定位子选项；保持现有 ChoiceItem 的 item 和 childIndex 传递不变。
| {/* Disabled reason (inline) */} | ||
| {disabled && item.disabledReason && ( | ||
| <div className={`${prefixCls}-item-disabled-reason`}>{item.disabledReason}</div> | ||
| )} | ||
| </div> | ||
| ); | ||
|
|
||
| // Wrap with Tooltip for disabled reason on hover | ||
| if (disabled && item.disabledReason) { | ||
| return ( | ||
| <Tooltip title={item.disabledReason} placement="top"> | ||
| {itemNode} | ||
| </Tooltip> | ||
| ); | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
禁用原因被重复渲染：卡片内常驻文案 + Tooltip 悬浮文案内容完全相同
Line 127-129 在 disabled && item.disabledReason 时始终内联渲染原因文本；Line 134-140 又用 Tooltip 包裹整个 itemNode，title 同样是 item.disabledReason。按提交历史描述，Tooltip 是后续为满足验收标准补充的能力，但原有的常驻内联文案没有被替换/移除，导致同一段文案在卡片上永久可见，鼠标悬浮时又在浮层里再次出现，属于重复展示，与“禁用原因提示”应为 hover 提示的设计意图冲突。
🐛 建议修复（二选一，示例保留 Tooltip 方案）
- {/* Disabled reason (inline) */}
- {disabled && item.disabledReason && (
- <div className={`${prefixCls}-item-disabled-reason`}>{item.disabledReason}</div>
- )}
</div>
);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {/* Disabled reason (inline) */} | |
| {disabled && item.disabledReason && ( | |
| <div className={`${prefixCls}-item-disabled-reason`}>{item.disabledReason}</div> | |
| )} | |
| </div> | |
| ); | |
| // Wrap with Tooltip for disabled reason on hover | |
| if (disabled && item.disabledReason) { | |
| return ( | |
| <Tooltip title={item.disabledReason} placement="top"> | |
| {itemNode} | |
| </Tooltip> | |
| ); | |
| } | |
| </div> | |
| ); | |
| // Wrap with Tooltip for disabled reason on hover | |
| if (disabled && item.disabledReason) { | |
| return ( | |
| <Tooltip title={item.disabledReason} placement="top"> | |
| {itemNode} | |
| </Tooltip> | |
| ); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/Item.tsx` around lines 126 - 140, Remove the
always-visible disabled-reason block from the item content rendered by the
component, while preserving the Tooltip wrapper around itemNode when disabled
and item.disabledReason are present. Keep item.disabledReason as the Tooltip
title so the reason is shown only on hover.
| /** | ||
| * @desc 整体圆角 | ||
| * @descEN Container border radius | ||
| */ | ||
| borderRadius?: number; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
borderRadius（整体圆角）token 定义了但从未在样式中使用。
ComponentToken.borderRadius（113-117 行）、ChoiceToken.borderRadius（150-152 行）以及 prepareComponentToken 中的默认值（426-429 行）都声明了该 token，但在 genChoiceStyle 的根选择器（161-170 行）及全文中都没有任何地方消费 token.borderRadius。作为对外暴露的可配置 Design Token，用户通过 ConfigProvider 自定义该值不会产生任何视觉效果，属于一个"空转"的公开配置契约。
♻️ 建议修复：在根容器应用该圆角
[componentCls]: {
'&, & *': {
boxSizing: 'border-box',
},
maxWidth: '100%',
+ borderRadius: unit(token.borderRadius),Also applies to: 150-152, 161-170, 426-429
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/style/index.ts` around lines 113 - 117, 在
genChoiceStyle 的根选择器中应用 token.borderRadius 作为容器的 border-radius，使 ConfigProvider
自定义的整体圆角生效；保留 ComponentToken、ChoiceToken 的声明及 prepareComponentToken
中默认值，并确保引用与现有 token 样式生成方式一致。
| fontSize: unit(token.titleFontSize), | ||
| lineHeight: unit(token.titleLineHeight), |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
@ant-design/cssinjs unit function source code implementation number to px string
💡 Result:
The unit utility function in @ant-design/cssinjs is a helper designed to ensure that numeric values are correctly formatted as CSS pixel strings while allowing non-numeric values to pass through unchanged [1]. Implementation Details: The unit function specifically appends 'px' to input values that are numbers, with the notable exception of 0, which is returned as is [1]. For inputs that are already strings (such as CSS variables like var(--token) or existing units like 1.5rem), the function returns the value without modification [1]. This utility is primarily used within style functions to handle design tokens that might be passed as either raw numbers or CSS variable strings [1][2]. Example Usage: import { unit } from '@ant-design/cssinjs'; unit(16); // Returns '16px' unit(0); // Returns 0 unit('var(--my-spacing)'); // Returns 'var(--my-spacing)' unit('1.5rem'); // Returns '1.5rem' This approach ensures that style definitions remain flexible, accommodating both static numeric values and dynamic CSS variables injected via the design token system [1].
Citations:
- 1: https://context7.com/ant-design/cssinjs/llms.txt
- 2: Refactor Component Style to Adapt CSS Variables ant-design#45618
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file outline =="
ast-grep outline packages/x/components/choice/style/index.ts --view expanded || true
echo
echo "== relevant lines =="
sed -n '160,340p' packages/x/components/choice/style/index.ts | cat -n
echo
echo "== search for unit() in this file =="
rg -n "unit\\(" packages/x/components/choice/style/index.ts
echo
echo "== search for lineHeight token definitions/usages =="
rg -n "titleLineHeight|labelLineHeight|descLineHeight|lineHeightLG|lineHeight[^A-Za-z]" packages/x/components -g '!**/dist/**' -g '!**/build/**'Repository: ant-design/x
Length of output: 17276
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== open package file if present =="
git ls-files | rg '^packages/x/.*/token|^packages/x/.*/style|theme|token' || true
echo
echo "== locate unit import source usage =="
rg -n "from '`@ant-design/cssinjs`'|unit" packages/x -g '*.ts' -g '*.tsx' | head -n 200Repository: ant-design/x
Length of output: 20883
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== choice prepareComponentToken =="
sed -n '400,430p' packages/x/components/choice/style/index.ts | cat -n
echo
echo "== font token map =="
sed -n '1,130p' packages/x/components/theme/interface/maps/font.ts | cat -n
echo
echo "== unitless token config =="
sed -n '1,60p' packages/x/components/theme/useToken.ts | cat -nRepository: ant-design/x
Length of output: 6776
行高不要用 unit() 包裹
titleLineHeight / labelLineHeight / descLineHeight 是无单位的行高倍数（token.lineHeight、token.lineHeightLG），这里用了 unit() 之后会变成 1.5715px 这类值，导致标题/标签/描述的行高异常偏小，文本容易重叠或裁切。
把这几处都改回直接使用 token 值即可。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/style/index.ts` around lines 183 - 184, Remove
the unit() wrapper from line-height assignments for titleLineHeight,
labelLineHeight, and descLineHeight, using each token’s raw unitless value
directly. Keep unit() for font-size values unchanged.
| [`${componentCls}-layout-grid`]: { | ||
| display: 'grid', | ||
| gridTemplateColumns: `repeat(${token.gridColumns}, 1fr)`, | ||
| gap: unit(token.itemGap), | ||
| }, | ||
|
|
||
| // Card layout | ||
| [`${componentCls}-layout-card`]: { | ||
| display: 'grid', | ||
| gridTemplateColumns: `repeat(${token.gridColumns}, 1fr)`, | ||
| gap: unit(token.itemGap), | ||
| }, | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win
关键 bug：${componentCls}-layout-card 键重复声明，导致网格布局样式被整体覆盖。
第 212-216 行与第 381-400 行在同一个对象字面量中两次定义了计算属性键 ${componentCls}-layout-card。JavaScript 对象字面量中同名 key 不会合并，后声明的值会完全替换前一个，因此第 381-400 行的定义会把第 212-216 行的 display: 'grid'、gridTemplateColumns、gap 全部抹除，最终 -layout-card 只保留内部 -item 相关样式，容器本身根本不会以 grid 方式排列。card 布局将无法正常渲染。
🐛 建议修复：合并成一个块
// Card layout
[`${componentCls}-layout-card`]: {
display: 'grid',
gridTemplateColumns: `repeat(${token.gridColumns}, 1fr)`,
gap: unit(token.itemGap),
+
+ [`${componentCls}-item`]: {
+ flexDirection: 'column',
+ alignItems: 'stretch',
+ minHeight: 'auto',
+ padding: token.paddingMD,
+
+ [`${componentCls}-indicator`]: {
+ position: 'absolute',
+ top: token.paddingSM,
+ insetInlineStart: token.paddingSM,
+ },
+
+ [`${componentCls}-item-content`]: {
+ alignItems: 'center',
+ textAlign: 'center',
+ marginTop: token.paddingSM,
+ },
+ },
},并删除文件末尾第 380-401 行的重复块。
Also applies to: 380-401
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/style/index.ts` around lines 205 - 217, 合并
`${componentCls}-layout-card` 的重复样式定义：保留前面用于容器网格布局的 display、gridTemplateColumns
和 gap，并将末尾重复块中的必要 `-item` 样式合并到同一个对象中；删除文件末尾重复声明，确保该计算属性键只定义一次。
| // ======================== Nested ======================== | ||
| [`${componentCls}-nested`]: { | ||
| marginLeft: token.controlHeightSM, | ||
| marginTop: token.paddingXS, | ||
| display: 'flex', | ||
| flexDirection: 'column', | ||
| gap: token.paddingXS, | ||
| }, |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
RTL 缺陷：嵌套子选项使用物理属性 marginLeft。
文件其余位置（如 328、372、391 行）都统一使用逻辑属性（insetInlineEnd/insetInlineStart/marginInlineEnd）以配合第 168-170 行的 &${componentCls}-rtl { direction: 'rtl' }，但 -nested 区块用的是物理属性 marginLeft，在 RTL 场景下不会镜像翻转，导致嵌套子选项的缩进方向在 RTL 布局下出错。PR/Issue 明确要求 RTL 支持，这里与既有约定不一致。
🐛 建议修复
[`${componentCls}-nested`]: {
- marginLeft: token.controlHeightSM,
+ marginInlineStart: token.controlHeightSM,
marginTop: token.paddingXS,
display: 'flex',
flexDirection: 'column',
gap: token.paddingXS,
},📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // ======================== Nested ======================== | |
| [`${componentCls}-nested`]: { | |
| marginLeft: token.controlHeightSM, | |
| marginTop: token.paddingXS, | |
| display: 'flex', | |
| flexDirection: 'column', | |
| gap: token.paddingXS, | |
| }, | |
| // ======================== Nested ======================== | |
| [`${componentCls}-nested`]: { | |
| marginInlineStart: token.controlHeightSM, | |
| marginTop: token.paddingXS, | |
| display: 'flex', | |
| flexDirection: 'column', | |
| gap: token.paddingXS, | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/x/components/choice/style/index.ts` around lines 350 - 357, Update
the `${componentCls}-nested` style block to replace the physical `marginLeft`
property with the appropriate logical margin property, preserving the existing
indentation amount and ensuring it mirrors correctly under the
`${componentCls}-rtl` direction.
kimteayon
left a comment
kimteayon
left a comment
There was a problem hiding this comment.
主要问题
-
[P1] 默认行高被错误转换为像素值
[style/index.ts:184]()x/packages/x/components/choice/style/index.ts
Line 184 in 96f3206
lineHeightLG默认是无单位的1.5，经unit()后变为1.5px；正文同样变为约1.57px。标题、标签和描述的多行内容会严重重叠。应直接使用 token，不要调用unit()。同类问题还在 190、311、317 行。 -
[P1] 选择组件没有实际的可访问性语义
[Item.tsx:78]()x/packages/x/components/choice/Item.tsx
Line 78 in 96f3206
data-role、data-selected、data-disabled对辅助技术没有作用；列表也使用了data-role="radiogroup"。屏幕阅读器无法识别选项、选中状态或禁用状态。需要真正的role、aria-checked、aria-disabled，并处理 radio group 的焦点和方向键交互。 -
[P2] 单选模式可以同时显示多个选中项
)
[use-select.ts:27](
类型和文档允许value={['1', '2']}，但单选模式没有截断数组，includes()会让两个 radio 同时选中；getValue()和onConfirm却只返回第一个值。应使用模式判别类型，或在 single 模式只保留一个值。 -
[P2] 禁用原因 Tooltip 无法触发
[style/index.ts:252]()x/packages/x/components/choice/style/index.ts
Line 252 in 96f3206
Tooltip 直接克隆禁用项作为触发节点，但该节点设置了pointer-events: none，无法接收 hover/focus 事件。应增加可交互包装节点，或调整禁用样式的位置。 -
[P2]
scrollTo不支持嵌套选项
[index.tsx:235]()x/packages/x/components/choice/index.tsx
Line 235 in 96f3206
只有顶层包装元素包含data-key，嵌套ChoiceItem没有，因此scrollTo(childKey)永远静默失败。 -
[P2] 合法字符串 key 可能使
scrollTo抛异常
[index.tsx:83]()x/packages/x/components/choice/index.tsx
Line 83 in 96f3206
key 被直接拼入 CSS selector。包含"、反斜杠等字符时，querySelector会抛DOMException。建议维护 key 到元素的 ref map，避免构造选择器。 -
[P2] 推荐文案绕过了新增的 locale
[Item.tsx:115]()x/packages/x/components/choice/Item.tsx
Line 115 in 96f3206
默认文案硬编码为AI Recommended/Recommended，切换中文 locale 后仍显示英文。PR 新增的locale.Choice.recommended、maxSelected、disabledHint均未实际使用。 -
[P2] 合法的 falsy ReactNode 不会渲染
[Item.tsx:105]()x/packages/x/components/choice/Item.tsx
Line 105 in 96f3206
label类型是ReactNode，但使用 truthy 判断，因此label={0}会消失。description、extra、标题和 footer 也存在相同问题，应使用node != null。
验证结果：Choice 全量测试 71/71 通过、34 个快照通过，TypeScript、Biome 和 git diff --check 均通过。现有测试没有覆盖上述状态和真实 ARIA 属性。
2 participants
🎯 关联 Issue
Close #1957
📋 变更内容
新增
Choice选择交互组件，用于 AI 对话场景中呈现一组结构化选项供用户选择。核心功能
mode: single | multiple）layout: list | grid | card）indicator: check | radio | number | none）maxCount多选上限控制confirmable确认按钮 +onConfirm回调AI 场景特性
recommended推荐标记（primary/secondary）disabledReason禁用原因提示（Tooltip + 行内文本）loading骨架屏加载态meta元数据透传工程实现
fadeIn/fadeInLeft渐入动画✅ 自检
Summary by CodeRabbit
新功能
文档
测试