@ucloud-fe/udesign-cli 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucloud-fe/udesign-cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "UDesign component library CLI - query components, extract metadata, generate skills",
   "type": "module",
   "bin": {

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

@@ -729,13 +729,51 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **容器必须设置 `container` 属性**：只有 `container` 为 `true` 时，flex 布局属性才会生效
+2. **优先使用预设间距**：使用 `sm`、`md`、`lg` 等预设值保持间距一致性
+3. **滚动场景使用 `cleanMargin`**：当使用 `spacing` 且需要滚动时，设置 `cleanMargin` 避免外边距影响滚动容器
+4. **栅格布局使用 `span`**：使用 12 栅格系统进行响应式布局，需要更精细的可使用小数
+
+### 常见场景
+
+#### 水平垂直居中
+
+```jsx
+<Box container alignItems="center" justifyContent="center" height="300px">
+  <Box>居中内容</Box>
+</Box>
+```
+
+#### 模拟浮动布局
+
+```jsx
+<Box container justifyContent="space-between">
+  <Box>左侧内容</Box>
+  <Box>右侧内容</Box>
+</Box>
+```
+
+#### 卡片布局
+
+```jsx
+<Box container spacing="md" wrap="wrap">
+  <Box span={4}><Card>卡片1</Card></Box>
+  <Box span={4}><Card>卡片2</Card></Box>
+  <Box span={4}><Card>卡片3</Card></Box>
+</Box>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 子元素的 flex、order 等属性不生效？
+
+A: 确保父级 Box 设置了 `container` 为 `true`，否则子组件的 flex 相关属性不会生效。
+
+### Q: 滚动时间距导致布局异常？
+
+A: 使用了 `spacing` 后，内部通过负 margin 实现间距，在滚动容器中可能有影响。设置 `cleanMargin` 即可修复。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -207,13 +207,28 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **最后一项使用 `current` 或 `noAction`**：当前页面的面包屑项不应可点击
+2. **层级不宜过深**：建议面包屑层级控制在 2-4 级
+3. **首项为首页或产品入口**：保持导航一致性
+
+### 常见场景
+
+#### 资源详情页面包屑
+
+```jsx
+<Breadcrumb>
+  <Breadcrumb.Item onClick={() => navigate('/uhost')}>云主机</Breadcrumb.Item>
+  <Breadcrumb.Item current>uhost-xxxx</Breadcrumb.Item>
+</Breadcrumb>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 面包屑项不可点击怎么设置？
+
+A: 使用 `noAction` 属性标记无需跳转的项目，或使用 `current` 标记当前页。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -362,13 +362,75 @@ const Demo = () => {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **主操作使用 `primary`**：每个视觉区域内应只有一个主按钮，避免多个 `primary` 按钮并列
+2. **异步操作务必加 `loading`**：提交表单、发送请求时使用 `loading` 防止重复点击，并在操作完成后关闭
+3. **Tooltip 包裹禁用按钮时使用 `fakeDisabled`**：避免原生 `disabled` 屏蔽所有事件导致 Tooltip 失效
+4. **表单提交按钮设置 `type="submit"`**：如果不想触发表单提交，保持默认的 `type="button"`
+5. **图标按钮建议搭配 `shape`**：纯图标按钮使用 `circle` 或 `square` 形状，视觉效果更好
+6. **按钮排列顺序**：主操作在前（左），辅助操作在后（右）
+
+### 常见场景
+
+#### 表单操作按钮
+
+```jsx
+<div>
+  <Button styleType="primary" onClick={handleSubmit}>提交</Button>
+  <Button styleType="border" onClick={handleCancel}>取消</Button>
+</div>
+```
+
+#### 加载态提交按钮
+
+```jsx
+const [loading, setLoading] = useState(false);
+
+const handleSubmit = async () => {
+  setLoading(true);
+  try {
+    await submitForm();
+  } finally {
+    setLoading(false);
+  }
+};
+
+<Button styleType="primary" loading={loading} onClick={handleSubmit}>
+  提交
+</Button>
+```
+
+#### 图标操作按钮
+
+```jsx
+<Button shape="circle" styleType="primary" icon="plus" onClick={handleAdd} />
+<Button shape="circle" styleType="border" icon="edit" onClick={handleEdit} />
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 禁用按钮外包裹 Tooltip 不显示？
+
+A: 原生 `disabled` 会阻止所有事件，导致 Tooltip 无法获取鼠标事件。解决方案是同时添加 `disabled` 和 `fakeDisabled`：
+
+```jsx
+<Tooltip popup="该操作暂不可用">
+  <Button disabled fakeDisabled>操作</Button>
+</Tooltip>
+```
+
+### Q: loading 状态下按钮的图标会怎样？
+
+A: `loading` 为 `true` 时，原始 `icon` 会被替换为旋转的加载图标。
+
+### Q: 如何创建只有图标没有文字的按钮？
+
+A: 不传 `children`，只传 `icon` 和 `shape`：
+
+```jsx
+<Button shape="circle" icon="plus" styleType="primary" />
+```
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -323,13 +323,45 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **子组件顺序灵活**：Header、Action、Content、Footer 可按需使用和组合
+2. **弹层自动适配**：Card 内部的 Popover、Select 等弹出层会自动使用 Card 的父节点作为容器
+3. **配合 Grid 布局**：多卡片场景使用 Grid 栅格组件排列
+
+### 常见场景
+
+#### 信息展示卡片
+
+```jsx
+<Card>
+  <Card.Header>基本信息</Card.Header>
+  <Card.Action>
+    <Button styleType="primary" onClick={handleEdit}>编辑</Button>
+  </Card.Action>
+  <Card.Content>
+    <p>名称：example-instance</p>
+    <p>状态：运行中</p>
+  </Card.Content>
+</Card>
+```
+
+#### 列表卡片
+
+```jsx
+{items.map(item => (
+  <Card key={item.id}>
+    <Card.Header>{item.title}</Card.Header>
+    <Card.Content>{item.description}</Card.Content>
+  </Card>
+))}
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Card 内部的弹层被遮挡？
+
+A: Card 已通过 Context 自动处理，弹层会使用 Card 的 parentNode 作为容器。如果仍有问题，检查是否有其他外层 overflow 容器影响。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -303,13 +303,31 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **Group 中使用 value/defaultValue**：不要在 Group 内的 Checkbox 上使用 checked
+2. **全选使用 indeterminate**：全选控制时使用 `indeterminate` 展示部分选中状态
+3. **数据量大时使用 options**：比逐个写 Checkbox 更简洁
+
+### 常见场景
+
+#### 表单多选
+
+```jsx
+<Form.Item label="兴趣">
+  <Checkbox.Group value={interests} onChange={setInterests}>
+    <Checkbox value="reading">阅读</Checkbox>
+    <Checkbox value="sports">运动</Checkbox>
+    <Checkbox value="music">音乐</Checkbox>
+  </Checkbox.Group>
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Group 中 Checkbox 的 checked 不生效？
+
+A: 在 Group 中应使用 `value`/`defaultValue` 控制选中，不要在子 Checkbox 上使用 `checked`。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -326,13 +326,38 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **使用 `sharedProps` 统一尺寸**：避免每个子组件重复设置 `size`
+2. **默认 `spacing="smart"` 即可**：会根据 size 自动选择合适间距
+3. **注意 sharedProps 与 Popover 包裹的兼容性**：如果子组件外层包裹了 Popover，sharedProps 可能会被 Popover 接收，此时需手动传递
+
+### 常见场景
+
+#### 搜索栏
+
+```jsx
+<Combine sharedProps={{ size: 'md' }}>
+  <Select value={type} onChange={setType} options={typeOptions} />
+  <Input value={keyword} onChange={e => setKeyword(e.target.value)} placeholder="请输入关键词" />
+  <Button styleType="primary" onClick={handleSearch}>搜索</Button>
+</Combine>
+```
+
+#### 日期范围
+
+```jsx
+<Combine separator="~">
+  <DatePicker value={startDate} onChange={setStartDate} />
+  <DatePicker value={endDate} onChange={setEndDate} />
+</Combine>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: sharedProps 传的 size 没生效？
+
+A: 如果子组件被 Popover、Tooltip 等包裹，sharedProps 会被外层组件拿到。解决方案是在目标组件上直接传入 props。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

package/skills/cpn-basic-date-picker/SKILL.md

@@ -789,13 +789,32 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **明确时区和语言包**：使用前确保导入了 moment 语言包和设置了时区
+2. **使用 format 控制精度**：不需要时间时使用 `YYYY-MM-DD` 格式
+3. **表单场景使用 nullable**：允许用户清空已选日期
+
+### 常见场景
+
+#### 表单中的日期选择
+
+```jsx
+<Form.Item label="开始时间">
+  <DatePicker
+    value={startDate}
+    onChange={setStartDate}
+    format="YYYY-MM-DD HH:mm:ss"
+    size="md"
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 日期选择器默认显示当前时间？
+
+A: 当 `nullable` 为 false（默认）时，空值会默认为当前时刻。设置 `nullable` 允许空值。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -792,13 +792,17 @@ const Demo = () => {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **确保每行有唯一 key**：数据中必须有唯一的 key 字段
+2. **添加行时生成唯一 key**：使用时间戳或 UUID 作为新行的 key
+3. **条件禁用删除**：使用 `getDisabledOfRow` 保护不可删除的行
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 如何限制最大行数？
+
+A: 通过 `addition.disabled` 控制，当达到最大行数时禁用添加按钮。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -198,13 +198,21 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **按需导入字体样式**：使用前确保导入了 `icon.min.css`
+2. **使用 ConfigProvider 全局修改前缀**：如果使用自定义图标库
+3. **加载态使用 spin**：`<Icon type="loading" spin />` 表示加载中
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 图标不显示？
+
+A: 确保已正确导入字体样式文件 `@ucloud-fe/react-components/dist/icon.min.css`，且 `type` 值与图标库中的名称一致。
+
+### Q: 如何使用自定义图标库？
+
+A: 通过 `prefix` 属性或使用 `ConfigProvider` 全局修改图标类名前缀，配合自定义字体图标库使用。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -407,13 +407,50 @@ const Demo = () => (
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **使用 clearable 提升体验**：搜索框等场景建议开启 clearable
+2. **prefix/suffix 增强语义**：使用图标前缀提示用户输入类型
+3. **数字输入使用 NumberInput**：不要用 Input 做数字输入，请使用 `Input.Number` 或 `NumberInput`
+4. **多行文本使用 Textarea**：不要用 Input 做多行输入，请使用 `Input.Textarea` 或 `Textarea`
+5. **受控模式使用 onChange**：`onChange` 返回原生 event，取值用 `e.target.value`
+
+### 常见场景
+
+#### 搜索输入框
+
+```jsx
+<Input
+  prefix={<Icon type="search" />}
+  clearable
+  placeholder="请输入搜索关键词"
+  value={keyword}
+  onChange={e => setKeyword(e.target.value)}
+/>
+```
+
+#### 表单中的输入框
+
+```jsx
+<Form.Item label="名称" required>
+  <Input
+    value={name}
+    onChange={e => setName(e.target.value)}
+    placeholder="请输入名称"
+    size="md"
+  />
+</Form.Item>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: onChange 的参数是什么？
+
+A: `onChange` 接收的是原生的 `ChangeEvent`，需要通过 `e.target.value` 获取输入值，而不是直接的值。
+
+### Q: 如何获取 Input 的焦点？
+
+A: 使用 ref：`<Input ref={inputRef} />`，然后调用 `inputRef.current.focus()`。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -319,13 +319,52 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **包裹具体区域而非整个页面**：Loading 应包裹实际需要加载的区域，而不是整个页面
+2. **使用 tip 提示操作**：长时间加载时添加文字提示提升用户体验
+3. **异步操作必须 finally 关闭 loading**：确保异常情况下也能关闭加载状态
+4. **inline-block 元素注意**：Loading 内部使用 block 布局，包裹 inline-block 元素时注意样式影响
+
+### 常见场景
+
+#### 表格数据加载
+
+```jsx
+const [loading, setLoading] = useState(true);
+const [data, setData] = useState([]);
+
+useEffect(() => {
+  fetchTableData().then(res => {
+    setData(res);
+    setLoading(false);
+  });
+}, []);
+
+<Loading loading={loading}>
+  <Table dataSource={data} columns={columns} />
+</Loading>
+```
+
+#### 页面区域加载
+
+```jsx
+<Loading loading={pageLoading} tip="正在加载页面数据...">
+  <Card>
+    <div>页面内容</div>
+  </Card>
+</Loading>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Loading 默认就显示吗？
+
+A: 不会，`loading` 属性默认为 `false`，需要显式设置为 `true` 才会显示。
+
+### Q: Loading 没有子元素时能用吗？
+
+A: 可以，但通常建议包裹目标区域，这样遮罩会覆盖在内容上方，体验更好。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -369,13 +369,59 @@ const Demo = () => {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **操作反馈优先用 Message**：轻量级的操作成功/失败反馈使用 Message，重要操作使用 Modal
+2. **loading 方法要手动关闭**：`Message.loading()` 返回的关闭函数需要在操作完成后调用
+3. **避免传入复杂内容**：如果需要在 Message 中传入依赖 Context 的内容，需要自行处理依赖
+4. **慎用 config 全局配置**：它会影响所有后续 Message
+
+### 常见场景
+
+#### 操作反馈
+
+```jsx
+const handleDelete = async () => {
+  try {
+    await api.deleteResource(id);
+    Message.success('删除成功');
+  } catch (error) {
+    Message.error('删除失败：' + error.message);
+  }
+};
+```
+
+#### 表单提交反馈
+
+```jsx
+const handleSubmit = async (values) => {
+  const hide = Message.loading('提交中...');
+  try {
+    await api.submitForm(values);
+    Message.success('提交成功');
+  } catch (error) {
+    Message.error('提交失败');
+  } finally {
+    hide();
+  }
+};
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: Message.loading 如何关闭？
+
+A: `Message.loading()` 返回一个关闭函数，调用即可关闭：
+
+```jsx
+const hide = Message.loading('加载中...');
+// 操作完成后
+hide();
+```
+
+### Q: Message 能否不自动关闭？
+
+A: 可以，将 `duration` 设为 `null`：`Message.success('内容', null)`。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->

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

@@ -821,13 +821,84 @@ class Demo extends React.Component {
 <!-- MANUAL_START: best-practices -->
 ## 最佳实践
 
-_（待补充）_
+1. **优先使用声明式**：避免命令式调用带来的上下文丢失和生命周期问题
+2. **重要操作需要二次确认**：删除等不可逆操作使用 Modal 确认
+3. **表单弹窗自定义 footer**：使用自定义 footer 控制提交按钮的 loading 状态
+4. **maskClosable 慎重关闭**：表单弹窗建议设置 `maskClosable={false}` 防止误关闭
+5. **使用 destroyOnClose 清理状态**：表单弹窗关闭后需要重置状态时使用
+
+### 常见场景
+
+#### 确认删除弹窗（声明式）
+
+```jsx
+const [deleteVisible, setDeleteVisible] = useState(false);
+const [deleting, setDeleting] = useState(false);
+
+const handleDelete = async () => {
+  setDeleting(true);
+  try {
+    await api.deleteResource(id);
+    Message.success('删除成功');
+    setDeleteVisible(false);
+  } catch (error) {
+    Message.error('删除失败');
+  } finally {
+    setDeleting(false);
+  }
+};
+
+<Modal
+  visible={deleteVisible}
+  title="确认删除"
+  onClose={() => setDeleteVisible(false)}
+  onOk={handleDelete}
+  okButtonProps={{ loading: deleting, styleType: 'primary' }}
+>
+  <Modal.Content>确定要删除该资源吗？此操作不可撤销。</Modal.Content>
+</Modal>
+```
+
+#### 表单弹窗
+
+```jsx
+<Modal
+  visible={formVisible}
+  title="创建资源"
+  size="lg"
+  onClose={() => setFormVisible(false)}
+  footer={
+    <div>
+      <Button styleType="primary" loading={submitting} onClick={handleSubmit}>提交</Button>
+      <Button onClick={() => setFormVisible(false)}>取消</Button>
+    </div>
+  }
+>
+  <Modal.Content>
+    <Form>
+      <Form.Item label="名称" required>
+        <Input value={name} onChange={e => setName(e.target.value)} />
+      </Form.Item>
+    </Form>
+  </Modal.Content>
+</Modal>
+```
 <!-- MANUAL_END: best-practices -->
 
 <!-- MANUAL_START: faq -->
 ## 常见问题
 
-_（待补充）_
+### Q: 命令式调用弹窗后上下文丢失？
+
+A: 命令式调用会创建独立的 React 渲染实例，无法访问父组件的 Context（如 Redux Store、国际化等）。请改用声明式写法。
+
+### Q: 弹窗内容很多如何处理？
+
+A: 使用 `Modal.Content` 包裹内容，它会自动处理滚动。也可以通过 `bodyStyle` 设置最大高度。
+
+### Q: 如何在弹窗中使用自定义按钮？
+
+A: 通过 `footer` 属性传入自定义底部内容，完全替换默认的确定/取消按钮。
 <!-- MANUAL_END: faq -->
 
 <!-- MANUAL_START: critical -->