Release

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne-components/components-core",
-  "version": "0.4.60",
+  "version": "0.4.61",
   "files": [
     "build"
   ],
@@ -22,9 +22,9 @@
     "@kne/create-deferred": "^0.1.0",
     "@kne/ensure-slash": "^0.1.0",
     "@kne/flex-box": "^0.1.1",
-    "@kne/form-info": "^0.1.5",
+    "@kne/form-info": "^0.1.6",
     "@kne/global-context": "^1.3.2",
-    "@kne/info-page": "^0.2.5",
+    "@kne/info-page": "^0.2.7",
     "@kne/is-empty": "^1.0.1",
     "@kne/phone-number-input": "^0.1.5",
     "@kne/react-enum": "^0.1.12",
@@ -98,7 +98,7 @@
   "devDependencies": {
     "@craco/craco": "^7.1.0",
     "@kne/craco-module-federation": "^1.1.1",
-    "@kne/md-doc": "^0.1.15",
+    "@kne/md-doc": "^0.1.16",
     "@kne/modules-dev": "^2.0.3",
     "@kne/react-error-boundary": "^0.1.1",
     "antd": "6.0.0",

prompts/组件示例编写提示词.md

@@ -99,7 +99,7 @@ render(<BaseExample />);
 ### 简化示例模板（无需远程加载）
 ```javascript
 const { default: YourComponent } = _YourComponent;
-const { Flex, Switch } = antd;
+const { Flex, Switch } = antd; // ⚠️ 使用了 antd 组件必须解构导入
 const { useState } = React;
 
 const BaseExample = () => {
@@ -114,6 +114,17 @@ const BaseExample = () => {
 render(<BaseExample />);
 ```
 
+### 示例代码导入检查清单
+编写示例代码时，请务必检查：
+- [ ] 是否使用了 antd 组件（如 Space、Card、Button、Typography 等）？
+  - 如果是，是否在代码中添加了 `const { 组件名 } = antd;` 解构导入？
+  - 如果是，是否在 example.json 的 scope 中添加了 `{"name": "antd", "packageName": "antd"}`？
+- [ ] 是否使用了其他项目组件（如 Icon、Modal 等）？
+  - 如果是，是否在代码中添加了 `const { default: 组件名 } = _ComponentName;` 导入？
+  - 如果是，是否在 example.json 的 scope 中添加了对应的依赖声明？
+- [ ] 是否使用了 React Hook？
+  - React Hook（如 useState、useEffect）无需导入，直接使用即可
+
 ## 4. scope 依赖声明规则
 | 场景 | name | packageName |
 |------|------|-------------|
@@ -129,6 +140,12 @@ render(<BaseExample />);
 - 在示例代码中直接使用 `React.useState` 或 `useState` 即可，不需要额外的导入
 - React 相关的包（如 `react-icons`）如果需要在示例中使用，建议使用简单的 emoji 或文本替代
 
+**⚠️ 特别注意：Antd 组件引入规范**
+- 如果示例代码中使用了任何 antd 组件（如 `Space`, `Card`, `Button`, `Typography` 等），**必须**在 example.json 的 scope 中声明 `antd` 依赖
+- **必须**在示例代码文件顶部添加 `const { 组件名 } = antd;` 解构导入语句
+- 常见易错点：示例中使用了 antd 组件但忘记在 scope 中声明，或忘记在代码中解构导入，导致 "antd is not defined" 错误
+- 只要示例中有一个组件使用了 antd，就必须在 scope 中声明 antd，即使其他示例没有使用
+
 ## 5. 数据准备
 - 在 `mockPreset/index.js` 中导出mock数据
 - 示例中使用 `import` 引入：`import reportDetail from './report/detail.json'`
@@ -141,11 +158,41 @@ render(<BaseExample />);
 
 ## 7. 示例内容设计原则
 
+### 核心原则
+
+**示例要根据API展示大部分功能，而且需要符合实际业务场景，示例数据也要尽量真实**
+
+这是示例编写的核心要求，所有示例必须满足以下三点：
+
+1. **API覆盖率**：示例必须覆盖组件API文档中的大部分功能，确保每个属性、方法都有对应的示例展示
+2. **真实业务场景**：示例数据和使用场景必须贴近真实业务，避免使用"内容1"、"测试数据"等无意义的占位符
+3. **数据真实性**：使用真实的人名、部门名称、业务状态等，让示例更具参考价值和可复制性
+
 ### 示例规划流程
 1. **分析组件功能**：阅读组件源码，理解组件的核心功能和主要使用场景
-2. **确定示例类型**：根据组件特性规划不同场景的示例，确保覆盖主要使用方式
-3. **设计真实场景**：每个示例都应该模拟真实的业务场景，使用贴近用户的数据
-4. **避免通用占位**：避免使用"内容1"、"示例数据"等通用占位符
+2. **阅读 API 文档**：仔细阅读组件的 API 文档（`doc/api.md`），了解所有可用的属性、方法和配置项
+3. **确定示例类型**：根据组件特性和 API 文档规划不同场景的示例，确保覆盖主要使用方式
+4. **设计真实场景**：每个示例都应该模拟真实的业务场景，使用贴近用户的数据
+5. **避免通用占位**：避免使用"内容1"、"示例数据"等通用占位符
+
+**重要：参考 API 文档设计示例**
+
+示例设计必须以 API 文档为依据，确保示例能够充分展示组件的所有可用 API。具体要求：
+
+- **属性覆盖**：每个常用的属性都应该有对应的示例展示其效果
+- **参数组合**：展示不同属性组合使用的效果，帮助用户理解属性之间的交互
+- **默认值对比**：对比使用默认值和自定义值的差异
+- **边界情况**：展示空值、无效值等边界情况的处理方式
+- **可选功能**：对于可选的功能（如链接、图标等），分别展示开启和关闭的效果
+
+**示例与 API 的对应关系检查表**：
+
+在编写示例时，应该建立以下对应关系：
+- 每个必填属性 → 至少有一个示例展示其必需性
+- 每个常用可选属性 → 至少有一个示例展示其效果
+- 每个特殊属性（如 className、style 等） → 有独立示例展示定制能力
+- 每个复杂属性（如对象、数组、函数等） → 有详细示例展示其用法
+- 每个枚举配置 → 有示例展示配置方式
 
 ### 示例命名规范
 - 使用语义化的文件名，清晰表达示例的核心内容
@@ -207,22 +254,26 @@ api={{
 #### 必须覆盖的内容
 1. **主要组件**：所有导出的主要组件都应该有对应的示例
 2. **核心功能**：组件的核心功能点需要通过示例展示
-3. **常用属性**：常用的属性和配置项需要通过示例展示效果
-4. **典型场景**：至少包含 1-2 个真实的业务场景示例
+3. **所有 API 属性**：根据 API 文档，每个属性都应该在至少一个示例中展示其效果
+4. **常用属性**：常用的属性和配置项需要通过示例展示效果
+5. **典型场景**：至少包含 1-2 个真实的业务场景示例
 
 #### 补充示例的原则
 如果现有示例不足以完整演示 API，应该补充新的示例文件。判断标准：
 - 有子组件没有独立的示例
-- 有重要的 API 参数没有在示例中展示
+- 有 API 文档中列出的属性没有在示例中展示
+- 有重要的 API 参数没有在示例中展示其效果
 - 有特殊使用场景（如自定义字段、组合使用）没有示例
 - 示例代码过于复杂，一个文件展示了太多功能，需要拆分
+- **API 覆盖度不足**：对照 API 文档检查，有未展示的属性或功能
 
 #### 补充示例的步骤
-1. 分析 API 文档，找出未覆盖的组件或功能点
-2. 为每个未覆盖的功能点创建独立的示例文件
-3. 示例文件命名应该清晰表达其展示的功能（如 `number-range.js`、`cascader.js`）
-4. 更新 `example.json`，添加新的示例条目
-5. 确保示例标题和描述准确表达示例内容
+1. **分析 API 文档**：仔细阅读 `doc/api.md`，列出所有属性、方法和配置项
+2. **对照现有示例**：检查每个 API 项是否已有示例展示，标记未覆盖的内容
+3. **设计新示例**：为每个未覆盖的 API 功能点设计独立的示例文件
+4. **示例文件命名**：应该清晰表达其展示的功能（如 `link.js`、`custom-style.js`）
+5. **更新配置**：更新 `example.json`，添加新的示例条目
+6. **验证完整性**：确保示例标题和描述准确表达示例内容，且能展示对应的 API
 
 #### 示例文件数量建议
 - **简单组件**：1-3 个示例文件即可
@@ -233,14 +284,17 @@ api={{
 在完成示例编写后，使用以下清单进行检查：
 
 - [ ] 所有导出的主要组件都有对应的示例
-- [ ] 所有常用的 API 参数都在示例中展示
+- [ ] **所有 API 文档中列出的属性都有示例展示**
+- [ ] **每个常用属性都有独立示例展示其效果**
+- [ ] **每个可选配置（如链接、样式等）都有对比示例**
 - [ ] 至少有一个基础用法示例
 - [ ] 至少有一个真实业务场景的示例
 - [ ] 有组合使用或高级用法的示例（如果适用）
 - [ ] 示例文件命名清晰，能准确表达功能
 - [ ] 示例标题和描述准确表达示例内容
 - [ ] `example.json` 中的配置正确且完整
 - [ ] 所有示例代码都能正常运行
+- [ ] **对照 API 文档，确保没有遗漏的重要功能**
 
 ## 9. FormInfo 组件示例特殊规则