@ucloud-fe/udesign-cli 0.1.3 → 0.2.0

package/skills/cpn-basic-notice/SKILL.md

@@ -219,13 +219,56 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **根据语义选择 styleType**：成功用 success、警告用 warning、错误用 error
+2. **重要提示设置 closable={false}**：不可忽略的提示禁止关闭
+3. **Modal 中常配合 Notice**：在弹窗中使用 Notice 提供额外提示信息
+4. **区分 Notice 和 Message**：Notice 是嵌入式静态提示，Message 是全局弹出式提示
+
+### 常见场景
+
+#### 页面顶部提示
+
+```jsx
+<Notice styleType="warning" closable={false}>
+  当前地域资源配额即将用完，请及时清理或申请扩容。
+</Notice>
+```
+
+#### Modal 中的提示
+
+```jsx
+<Modal visible={visible} title="删除资源" onClose={handleClose}>
+  <Notice styleType="error" closable={false}>
+    删除操作不可撤销，请谨慎操作。
+  </Notice>
+  <Modal.Content>
+    确定要删除该资源吗？
+  </Modal.Content>
+</Modal>
+```
+
+#### 带操作的提示
+
+```jsx
+<Notice
+  styleType="warning"
+  action={<Button size="sm" onClick={handleRenew}>立即续费</Button>}
+>
+  您的资源将于 3 天后到期
+</Notice>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Notice 和 Message 的区别？
+
+A: Notice 是嵌入在页面中的静态提示组件，不会自动消失；Message 是全局弹出的消息提示，会自动消失。
+
+### Q: 如何隐藏前置图标？
+
+A: 将 `icon` 设为 `null` 或 `false`：`<Notice icon={null}>内容</Notice>`。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-number-input/SKILL.md

@@ -549,13 +549,53 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **设置合理的 min/max**：限制输入范围防止非法值
+2. **使用 onNumberChange 而非 onChange**：`onNumberChange` 只在有效值变化时触发，避免中间态
+3. **formatter 和 parser 配对使用**：格式化显示时需要同时提供 parser 解析输入
+4. **使用 suffix 添加单位**：比 formatter 更简单的方式添加单位后缀
+
+### 常见场景
+
+#### 资源数量选择
+
+```jsx
+<Form.Item label="实例数量">
+  <NumberInput
+    value={instanceCount}
+    onChange={setInstanceCount}
+    min={1}
+    max={100}
+    step={1}
+  />
+</Form.Item>
+```
+
+#### 带单位的数值输入
+
+```jsx
+<Form.Item label="磁盘大小">
+  <NumberInput
+    value={diskSize}
+    onChange={setDiskSize}
+    min={10}
+    max={32000}
+    step={10}
+    suffix="GB"
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: onChange 和 onNumberChange 的区别？
+
+A: `onChange` 在每次输入时都会触发（包括输入中间态），`onNumberChange` 只在有效数字确定时触发（按钮点击、回车、失焦）。
+
+### Q: 如何自定义合法值的计算方式？
+
+A: 使用 `computeValidNumber` 属性，传入一个函数接收当前数值和选项，返回合法的数值。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-popover/SKILL.md

@@ -486,13 +486,41 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **children 必须是 React 元素**：Popover 需要获取子元素的 ref，文本节点不可用
+2. **overflow 容器内使用 forwardPopupContainer**：避免弹出层被裁剪
+3. **click 触发时注意关闭时机**：可能需要受控模式手动管理 visible
+4. **默认容器为 body**：如需在特定容器内弹出，使用 getPopupContainer
+
+### 常见场景
+
+#### 自定义操作菜单
+
+```jsx
+<Popover
+  trigger={['click']}
+  placement="bottomLeft"
+  popup={
+    <div>
+      <div onClick={handleEdit}>编辑</div>
+      <div onClick={handleDelete}>删除</div>
+    </div>
+  }
+>
+  <Button icon="more" />
+</Popover>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 弹出层被裁剪或位置偏移？
+
+A: 通常是因为父容器有 `overflow: hidden` 或 `overflow: auto`。使用 `forwardPopupContainer` 自动查找安全容器，或使用 `getPopupContainer` 手动指定。
+
+### Q: Popover 中使用表单元素无法聚焦？
+
+A: 检查 trigger 是否包含 `focus`，可能导致 focus 事件冲突。建议使用 `click` 触发。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-radio/SKILL.md

@@ -284,13 +284,51 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **使用 Radio.Group 管理**：避免单独使用 Radio 管理状态
+2. **使用 options 快速配置**：简单选项直接使用 options 数组
+3. **根据场景选择 styleType**：表单切换用 button、地域选择用 card
+4. **button 样式禁用注意 Tooltip**：需要用 fakeDisabled 处理
+
+### 常见场景
+
+#### 表单中的单选
+
+```jsx
+<Form.Item label="付费方式">
+  <Radio.Group
+    value={payType}
+    onChange={setPayType}
+    styleType="button"
+    options={[
+      { label: '按月', value: 'monthly' },
+      { label: '按年', value: 'yearly' },
+      { label: '按需', value: 'demand' }
+    ]}
+  />
+</Form.Item>
+```
+
+#### 卡片选择
+
+```jsx
+<Radio.Group value={region} onChange={setRegion} styleType="card">
+  <Radio value="cn-bj2" title="北京二">华北地域</Radio>
+  <Radio value="cn-sh2" title="上海二">华东地域</Radio>
+  <Radio value="cn-gd" title="广州">华南地域</Radio>
+</Radio.Group>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Radio.Group 的 onChange 返回什么？
+
+A: 返回当前选中的 Radio 的 `value` 值。
+
+### Q: styleType 为 card 时如何显示标题？
+
+A: 使用 Radio 的 `title` 属性：`<Radio value="a" title="标题">描述内容</Radio>`。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-select/SKILL.md

@@ -1225,13 +1225,57 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **优先使用 options 属性**：比 children 方式性能更好，且支持虚拟列表
+2. **大量选项启用 virtualList**：选项超过 100 条时建议启用
+3. **多选默认可清空**：多选模式下 clearable 自动启用
+4. **搜索时建议自定义 handleSearch**：默认搜索为模糊匹配，如需精确匹配可自定义
+
+### 常见场景
+
+#### 表单中的下拉选择
+
+```jsx
+<Form.Item label="地域" required>
+  <Select
+    value={region}
+    onChange={setRegion}
+    placeholder="请选择地域"
+    options={regionOptions}
+  />
+</Form.Item>
+```
+
+#### 带搜索的多选
+
+```jsx
+<Form.Item label="标签">
+  <Select
+    multiple
+    search
+    showSelectAll
+    value={tags}
+    onChange={setTags}
+    options={tagOptions}
+    placeholder="请选择标签"
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 单选清空后 onChange 回调的值是什么？
+
+A: 清空时回调值为 `undefined`。
+
+### Q: virtualList 为什么不生效？
+
+A: 虚拟列表仅在使用 `options` 属性时生效，children 方式不支持。
+
+### Q: 弹出层位置偏移？
+
+A: 默认使用 `forwardPopupContainer` 自动查找安全容器。如仍有问题，使用 `popoverProps.getPopupContainer` 手动指定。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-slider/SKILL.md

@@ -558,13 +558,56 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **设置合理的 min/max/step**：确保 (max - min) 是 step 的整数倍
+2. **使用 marks 标记关键值**：帮助用户理解值的含义
+3. **使用 onLastChange 处理异步操作**：避免拖拽过程中频繁触发请求
+4. **资源配置建议添加单位**：通过 numberInput.suffix 和 tipFormatter 展示单位
+
+### 常见场景
+
+#### 资源配置选择
+
+```jsx
+<Form.Item label="CPU 核数">
+  <Slider
+    value={cpuCount}
+    onChange={setCpuCount}
+    min={1}
+    max={64}
+    step={1}
+    marks={{ 1: '1', 8: '8', 16: '16', 32: '32', 64: '64' }}
+    numberInput={{ suffix: '核' }}
+  />
+</Form.Item>
+```
+
+#### 带宽选择
+
+```jsx
+<Form.Item label="带宽">
+  <Slider
+    value={bandwidth}
+    onChange={setBandwidth}
+    min={1}
+    max={200}
+    step={1}
+    numberInput={{ suffix: 'Mbps' }}
+    tipFormatter={value => `${value} Mbps`}
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: range 模式下 numberInput 为什么不显示？
+
+A: numberInput 仅在 range 为 false 时生效。range 模式不支持 NumberInput。
+
+### Q: step 设置后为什么报错？
+
+A: 确保 (max - min) 是 step 的整数倍，且 step 大于 0。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-switch/SKILL.md

@@ -289,13 +289,48 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **明确语义**：使用 onText/offText 让用户清楚开关的含义
+2. **即时生效的操作使用 Switch**：切换后立即生效的场景适合用 Switch
+3. **表单提交使用 Checkbox**：需要表单提交才生效的场景更适合用 Checkbox
+
+### 常见场景
+
+#### 表单中的开关
+
+```jsx
+<Form.Item label="自动续费">
+  <Switch
+    checked={autoRenew}
+    onChange={setAutoRenew}
+    onText="是"
+    offText="否"
+  />
+</Form.Item>
+```
+
+#### 功能开关
+
+```jsx
+<Form.Item label="启用监控">
+  <Switch
+    checked={monitorEnabled}
+    onChange={enabled => {
+      setMonitorEnabled(enabled);
+      if (enabled) {
+        Message.success('监控已开启');
+      }
+    }}
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Switch 和 Checkbox 的使用场景区别？
+
+A: Switch 适用于切换后立即生效的场景（如开启/关闭功能），Checkbox 适用于需要表单提交后才生效的场景（如同意协议）。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-table/SKILL.md

@@ -2931,13 +2931,59 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **务必设置 rowKey 或保证数据有 key**：避免使用 index 作为 key
+2. **大数据量使用服务端分页**：配合 `doNotHandleCondition` 和 `onConditionChange`
+3. **固定列时设置列宽**：使用 `fixed` 时需要给列设置 `width`
+4. **Loading 包裹 Table**：使用 Loading 组件展示加载状态
+
+### 常见场景
+
+#### 资源列表页
+
+```jsx
+const [loading, setLoading] = useState(true);
+const [dataSource, setDataSource] = useState([]);
+const [selectedRowKeys, setSelectedRowKeys] = useState([]);
+const [page, setPage] = useState(1);
+
+<Loading loading={loading}>
+  <Table
+    rowKey="resourceId"
+    columns={columns}
+    dataSource={dataSource}
+    rowSelection={{
+      selectedRowKeys,
+      onChange: setSelectedRowKeys
+    }}
+    pagination={{
+      current: page,
+      pageSize: 10,
+      total,
+      onChange: setPage
+    }}
+    contextMenu={record => [
+      { label: '编辑', onClick: () => handleEdit(record) },
+      { label: '删除', onClick: () => handleDelete(record) }
+    ]}
+  />
+</Loading>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 表格数据异常、行错乱？
+
+A: 检查 key 是否唯一。务必使用 `rowKey` 指定唯一标识字段，不要依赖 index。
+
+### Q: 如何实现后端分页？
+
+A: 设置 `doNotHandleCondition`，在 `onConditionChange` 和 `pagination.onChange` 中请求后端数据。
+
+### Q: 固定列后横向无法滚动？
+
+A: 检查是否设置了 `scroll.x`，且 `scroll.x` 的值需要大于表格容器宽度。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-tabs/SKILL.md

@@ -612,13 +612,57 @@ const Demo = () => {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **Pane 必须有唯一 key**：这是 Tabs 正常工作的前提
+2. **表单 Tab 使用受控模式**：方便校验时切换到有错误的 tab
+3. **按需销毁内容**：大量内容的 Tab 使用 `destroyInactiveTabPane` 减少内存占用
+4. **首次不需要渲染的使用懒加载**：默认非活动 tab 不会渲染，切换到才渲染
+
+### 常见场景
+
+#### 资源详情页
+
+```jsx
+<Tabs defaultActiveKey="overview">
+  <Tabs.Pane key="overview" tab="概览">
+    <OverviewPanel />
+  </Tabs.Pane>
+  <Tabs.Pane key="monitor" tab="监控">
+    <MonitorPanel />
+  </Tabs.Pane>
+  <Tabs.Pane key="log" tab="日志">
+    <LogPanel />
+  </Tabs.Pane>
+</Tabs>
+```
+
+#### 配置切换
+
+```jsx
+<Tabs
+  activeKey={configTab}
+  onChange={setConfigTab}
+  styleType="ink"
+>
+  <Tabs.Pane key="basic" tab="基础配置">
+    <BasicConfigForm />
+  </Tabs.Pane>
+  <Tabs.Pane key="advanced" tab="高级配置">
+    <AdvancedConfigForm />
+  </Tabs.Pane>
+</Tabs>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: key 被 React 修改导致切换失败？
+
+A: 在某些情况下 React 会修改 key，可以使用 `tabKey` 属性替代。
+
+### Q: Tab 数量多时如何处理？
+
+A: 组件内置了滚动功能，当 tab 数量超出容器宽度时会自动显示滚动按钮。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-tag/SKILL.md

@@ -412,13 +412,48 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **用颜色表达语义**：绿色表示成功/运行，红色表示错误/异常，黄色表示警告
+2. **使用 icon 增强标识**：配合 `circle-fill` 图标标识状态
+3. **标签列表使用 closable**：可删除的标签场景
+4. **使用 customStyle 扩展颜色**：内置颜色不满足时自定义
+
+### 常见场景
+
+#### 资源状态标签
+
+```jsx
+const statusMap = {
+  running: { styleType: 'green', icon: 'circle-fill', text: '运行中' },
+  stopped: { styleType: 'gray', icon: 'circle-fill', text: '已停止' },
+  error: { styleType: 'red', icon: 'circle-fill', text: '异常' }
+};
+
+const { styleType, icon, text } = statusMap[status];
+<Tag styleType={styleType} icon={icon}>{text}</Tag>
+```
+
+#### 标签列表
+
+```jsx
+{tags.map(tag => (
+  <Tag
+    key={tag.id}
+    closable
+    onClose={() => handleRemoveTag(tag.id)}
+    styleType="blue"
+  >
+    {tag.name}
+  </Tag>
+))}
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 有哪些可用的 styleType？
+
+A: 常用的有 `gray`、`green`、`yellow`、`red`、`blue`、`orange`、`purple`、`cyan` 等，以及对应的 `-crisped` 后缀变体。可通过 `Tag.StyleType` 获取完整列表。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-textarea/SKILL.md

@@ -124,13 +124,51 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **使用 rows 控制初始高度**：通过 `rows` 设置合理的初始显示行数
+2. **设置 maxLength 限制长度**：避免用户输入过长内容
+3. **onChange 返回原生 event**：取值用 `e.target.value`，与 Input 一致
+4. **短文本用 Input**：单行文本输入使用 Input，多行才用 Textarea
+
+### 常见场景
+
+#### 表单中的描述输入
+
+```jsx
+<Form.Item label="描述">
+  <Textarea
+    value={description}
+    onChange={e => setDescription(e.target.value)}
+    placeholder="请输入描述信息"
+    rows={4}
+  />
+</Form.Item>
+```
+
+#### 备注输入
+
+```jsx
+<Form.Item label="备注">
+  <Textarea
+    value={remark}
+    onChange={e => setRemark(e.target.value)}
+    placeholder="请输入备注（选填）"
+    rows={3}
+    maxLength={500}
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 如何固定高度不允许拖拽？
+
+A: 设置 `style={{ resize: 'none' }}`。
+
+### Q: onChange 的参数是什么？
+
+A: 与 Input 一致，接收原生 `ChangeEvent`，通过 `e.target.value` 获取值。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-tooltip/SKILL.md

@@ -235,13 +235,50 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **简短提示用 Tooltip**：复杂内容用 Popover
+2. **暗色主题用于操作提示**：按钮等操作元素的提示建议用 dark 主题
+3. **禁用按钮配合 fakeDisabled**：确保 Tooltip 在禁用按钮上也能正常工作
+4. **popup 为 null 时不渲染**：可以通过传入 null 条件性隐藏 Tooltip
+
+### 常见场景
+
+#### 按钮操作说明
+
+```jsx
+<Tooltip popup="上传文件到服务器">
+  <Button icon="upload" shape="circle" />
+</Tooltip>
+```
+
+#### 禁用按钮提示（配合 fakeDisabled）
+
+```jsx
+<Tooltip popup="该操作暂不可用">
+  <Button disabled fakeDisabled>操作</Button>
+</Tooltip>
+```
+
+#### 文本截断提示
+
+```jsx
+<Tooltip popup={fullText}>
+  <span style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', maxWidth: 200 }}>
+    {fullText}
+  </span>
+</Tooltip>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 禁用的按钮无法显示 Tooltip？
+
+A: 原生 `disabled` 会屏蔽所有事件。解决方案是同时添加 `disabled` 和 `fakeDisabled`。
+
+### Q: Tooltip 位置偏移？
+
+A: 参考 Popover 的容器问题，使用 `forwardPopupContainer` 或 `getPopupContainer` 处理。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->