FormCreate

Appearance

FormCreate 组件文档编写规范 ​

本文档基于 input.md 的标准格式，用于规范所有 UI 框架组件文档的编写。

文档结构 ​

1. Front Matter（文档头部） ​

根据不同的 UI 框架，使用对应的 titleTemplate：

Element Plus:

yaml
---
titleTemplate: ":title - Element Plus 组件|FormCreate"
outline: deep
---

Ant Design Vue:

yaml
---
titleTemplate: ":title - Ant Design Vue 组件|FormCreate"
outline: deep
---

Naive UI:

yaml
---
titleTemplate: ":title - Naive UI 组件|FormCreate"
outline: deep
---

TDesign:

yaml
---
titleTemplate: ":title - TDesign 组件|FormCreate"
outline: deep
---

Vant:

yaml
---
titleTemplate: ":title - Vant 组件|FormCreate"
outline: deep
---

Arco Design:

yaml
---
titleTemplate: ":title - Arco Design 组件|FormCreate"
outline: deep
---

说明：

  • titleTemplate: 页面标题模板，:title 会被替换为组件名称，根据 UI 框架调整
  • outline: deep: 启用深度大纲导航

2. 文档标题 ​

markdown
# [组件名称] [组件中文名]

例如：# Input 输入框

3. 规则部分（## 规则） ​

规则部分是文档的核心，需要包含多个示例来展示组件的各种用法。

3.1 基础示例（### 基础示例） ​

展示组件最基本的用法，包含：

  • type: 组件类型
  • title: 字段标签
  • field: 字段名
  • value: 默认值（可选）
  • props: 基本属性配置
  • validate: 验证规则（可选）
  • col: 布局配置（可选）
js
const rule = {
    type:"input",
    title:"商品名称",
    field:"goods_name",
    value:"iphone 7",
    col:{
    	span:12,
    	labelWidth:150
    },
    props: {
        type: "text",
    },
    validate:[
        { required: true, message: '请输入goods_name', trigger: 'blur' },
    ],
}

3.2 Props 配置示例（### Props 配置示例） ​

根据组件的特性，提供多个典型的 Props 配置示例，每个示例使用 #### 标题。

重要：如果组件有多种呈现方式，必须在示例中展示常用类型

例如 Input 组件有多种类型（text、textarea、password、search 等），应该在 Props 配置示例中分别展示：

js
// 示例：文本输入框（text）
const rule = {
    type:"input",
    title:"用户名",
    field:"username",
    props: {
        placeholder: "请输入用户名",
        clearable: true,
        prefixIcon: "User",
    },
}


// 示例：文本域（textarea）
const rule = {
    type:"input",
    title:"商品描述",
    field:"description",
    props: {
        type: "textarea",
        placeholder: "请输入商品描述",
        rows: 4,
        autosize: { minRows: 3, maxRows: 6 },
    },
}


// 示例：密码输入框（password）
const rule = {
    type:"input",
    title:"密码",
    field:"password",
    props: {
        type: "password",
        placeholder: "请输入密码",
        showPassword: true, // 显示/隐藏密码切换按钮
    },
}

示例分类：

  • 多种呈现方式（如果组件支持）：text、textarea、password、search 等常用类型
  • 常用属性组合（如：可清空、图标等）
  • 特殊类型（如：多选、范围选择等）
  • 状态控制（如：禁用、只读等）
  • 限制配置（如：长度限制、数值范围等）

每个示例应该：

  • 有清晰的标题说明用途和类型
  • 展示相关属性的组合使用
  • 包含必要的注释

3.3 Events 事件示例（### Events 事件示例） ​

提供真实业务场景的事件处理示例。

必须包含：

  • 基础事件示例（#### 监听输入变化和焦点事件）：展示所有可用事件的基本用法
  • 真实场景示例：基于实际业务场景的事件处理

事件处理规范：

  • 如果不需要访问 api，直接使用 (value) 或 (event) 参数
  • 如果需要访问 api，必须设置 inject: true，并使用 $inject 参数（注意是 $inject 不是 inject）
js
// 基础事件示例
const rule = {
    type:"input",
    title:"搜索关键词",
    field:"keyword",
    props: {
        placeholder: "请输入搜索关键词",
        clearable: true,
    },
    on: {
        change: (value) => {
            console.log('输入值改变:', value);
        },
        blur: (event) => {
            console.log('失去焦点:', event);
        },
        focus: (event) => {
            console.log('获得焦点:', event);
        },
        clear: () => {
            console.log('清空输入');
        },
    },
}


// 需要访问 api 的示例
const rule = {
    type:"input",
    title:"搜索商品",
    field:"keyword",
    props: {
        placeholder: "请输入商品名称搜索",
        clearable: true,
        prefixIcon: "Search",
    },
    inject: true,
    on: {
        change: ($inject, value) => {
            // 使用 $inject.api 访问表单 API
            if (value && value.length >= 2) {
                searchProducts(value).then(res => {
                    $inject.api.setValue('searchResults', res.data);
                });
            }
        },
    },
}

真实场景示例类型：

  • 实时搜索（change 事件）
  • 失焦验证（blur 事件）
  • 自动填充（focus 事件）
  • 联动更新其他字段（change 事件）
  • 清空后重置相关字段（clear 事件）
  • 组合使用多个事件

3.4 Slots 插槽示例（### Slots 插槽示例） ​

展示如何使用组件的插槽功能。

插槽使用规范：

  • 使用 children 数组来定义插槽内容
  • 每个插槽项需要设置 type、slot 和 children
js
const rule = {
    type:"input",
    title:"网址",
    field:"url",
    props: {
        placeholder: "请输入网址",
    },
    children: [
        {
            type: 'div',
            slot: 'prefix',
            children: ['https://']
        },
        {
            type: 'div',
            slot: 'suffix',
            children: ['.com']
        },
    ]
}

4. 完整配置项链接 ​

根据不同的 UI 框架，使用对应的链接格式：

Element Plus:

markdown
完整配置项:[Element_[组件名]](https://element-plus.org/zh-CN/component/[组件路径])

例如：完整配置项:[Element_Input](https://element-plus.org/zh-CN/component/input)

Ant Design Vue:

markdown
完整配置项:[Ant-design-vue_[组件名]](https://next.antdv.com/components/[组件路径]-cn/)

例如：完整配置项:[Ant-design-vue_Input](https://next.antdv.com/components/input-cn/)

Naive UI:

markdown
完整配置项:[Naive_UI_[组件名]](https://www.naiveui.com/zh-CN/os-theme/components/[组件路径])

TDesign:

markdown
完整配置项:[TDesign_[组件名]](https://tdesign.tencent.com/vue/components/[组件路径])

Vant:

markdown
完整配置项:[Vant_[组件名]](https://vant-ui.github.io/vant/#/zh-CN/[组件路径])

Arco Design:

markdown
完整配置项:[Arco_[组件名]](https://arco.design/vue/components/[组件路径])

5. Value 类型说明 ​

markdown
**value** :`[类型]`

例如：**value** :String``

支持的类型：

  • String
  • Number
  • Boolean
  • Array
  • Object
  • 组合类型：String | Number | Array

6. Options 配置（如果组件支持） ​

如果组件使用 options 配置（如 select、checkbox、radio 等），需要添加 Options 表格：

markdown
## Options


| 字段名 | 说明 | 字段类型 | 是否必填 | 默认值 |
| :--- | :--- | :--- | :--- | :--- |
| value | 参数值 | String,Number | true | - |
| label | 字段别名 | String | true | - |
| disabled | 设置为禁用状态 | Boolean | false | false |

7. Props 表格（## Props） ​

完整的 Props 属性表格，从对应 UI 框架的官方文档复制并整理。

表格格式：

markdown
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| -------------- | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | ------ |

注意事项：

  • 保持表格格式统一
  • 类型使用代码格式：`string`
  • 可选值如果是链接，使用 Markdown 链接格式
  • 默认值如果是 —，表示无默认值
  • 不同 UI 框架的 Props 表格格式可能略有不同，保持与官方文档一致

8. Events 表格（## Events） ​

完整的事件列表表格。

表格格式：

markdown
| 事件名称 | 说明 | 回调参数 |
| -------- | --------------------------------------------- | ------------------------- |

注意事项：

  • 回调参数使用代码格式，如：`(event: Event)`
  • 如果没有参数，使用 —

9. Slots 表格（## Slots） ​

完整的插槽列表表格。

表格格式：

markdown
| 插槽名 | 说明 |
| :------ | :-------------------------------------------- |

注意事项：

  • 如果插槽有特殊限制（如只对特定类型有效），在说明中注明

编写规范 ​

代码示例规范 ​

  1. 代码块语言：统一使用 js
  2. 变量命名：使用有意义的变量名，符合业务场景
  3. 注释：关键逻辑添加中文注释
  4. 格式：保持代码格式统一，使用 4 个空格缩进

标题层级规范 ​

  • # 组件名称（一级标题）
  • ## 主要章节（规则、Props、Events、Slots 等）
  • ### 示例分类（基础示例、Props 配置示例等）
  • #### 具体示例（可清空输入框、文本域等）

命名规范 ​

  • 字段名（field）：使用下划线命名，如 goods_name、order_no
  • 标题（title）：使用中文，简洁明了
  • 占位符（placeholder）：使用中文，格式为 "请输入..."

示例选择原则 ​

  1. 覆盖常用场景：优先展示最常用的配置组合
  2. 展示多种类型：如果组件有多种呈现方式（如 input 的 text、textarea、password），必须分别展示
  3. 展示特性：突出组件的独特功能
  4. 真实场景：事件示例要基于真实业务需求
  5. 循序渐进：从简单到复杂，从基础到高级
  6. 框架差异：注意不同 UI 框架的 API 差异，使用对应框架的正确属性名

注意事项 ​

  1. inject 使用：

    • 只有在需要访问 api 时才设置 inject: true
    • 使用 $inject 作为参数名（不是 inject）
    • 通过 $inject.api 访问表单 API

  2. 事件参数：

    • 不需要 api 时：(value) 或 (event)
    • 需要 api 时：($inject, value) 或 ($inject, event)
    • 注意不同 UI 框架的事件参数可能不同（如 ant-design-vue 的 change 事件可能接收 (e) 而不是 (value)）

  3. 链接格式：

    • 根据 UI 框架使用对应的官方文档链接格式
    • 使用完整 URL，确保链接可访问
    • 不同框架的链接格式参考第 4 节

  4. 属性名称差异：

    • 不同 UI 框架的属性名可能不同，使用对应框架的正确属性名
    • 例如：Element Plus 使用 clearable，Ant Design Vue 使用 allowClear
    • 例如：Element Plus 使用 prefixIcon，Ant Design Vue 使用 prefix

  5. 多种呈现方式：

    • 如果组件支持多种类型（如 input 的 text、textarea、password），必须在 Props 配置示例中分别展示
    • 每种类型使用独立的示例，标题明确说明类型
    • 优先展示最常用的类型

  6. 表格对齐：

    • 使用 :--- 左对齐
    • 使用 :---: 居中对齐
    • 使用 ---: 右对齐

检查清单 ​

编写完成后，请检查：

  • [ ] Front Matter 格式正确（使用对应 UI 框架的 titleTemplate）
  • [ ] 标题层级清晰
  • [ ] 基础示例完整
  • [ ] Props 配置示例覆盖常用场景
  • [ ] 如果组件有多种呈现方式，已展示常用类型（如 input 的 text、textarea、password）
  • [ ] Events 事件示例包含基础示例和真实场景
  • [ ] Slots 插槽示例（如果组件支持）
  • [ ] 完整配置项链接正确（使用对应 UI 框架的链接格式）
  • [ ] Value 类型说明准确
  • [ ] Options 表格（如果适用）
  • [ ] Props 表格完整（从对应 UI 框架官方文档复制）
  • [ ] Events 表格完整
  • [ ] Slots 表格完整（如果组件支持）
  • [ ] 代码示例格式统一
  • [ ] 注释清晰易懂
  • [ ] 属性名称符合对应 UI 框架的 API（如 clearable vs allowClear）
  • [ ] 无语法错误

参考文档 ​

FormCreate 是一个开源项目，基于 MIT 许可证发布，欢迎个人和企业用户免费使用

MIT Licensed | Copyright © 2018-present FormCreate
陕ICP备2024036423号-1