前端组件文档编写规范书

前端组件文档编写规范书一、文档核心结构规范（一）基础信息模块基础信息是组件文档的“身份证”，需清晰展示组件的核心属性，让开发者快速定位组件用途。组件名称：采用PascalCase命名法，如DatePicker、TablePagination，确保与代码中组件类名一致，避免歧义。组件类型：明确分类，如“基础组件”“表单组件”“数据展示组件”“业务组件”，便于开发者按场景检索。适用场景：结合业务场景描述，例如“适用于需要用户选择单个或多个日期的表单场景，如订单创建时间筛选、会议日程预约”，避免模糊表述。版本信息：记录组件当前版本、首次发布版本及更新日志链接，如v2.3.0（2025-03-15），帮助开发者了解迭代历史。维护责任人：标注组件的开发负责人及联系方式，方便问题反馈与协作。（二）API文档模块API是组件的“操作手册”，需精确、完整地定义组件的输入输出，确保开发者正确调用。1.属性（Props）以表格形式呈现，包含以下字段：|属性名|类型|默认值|必填|说明||||||||value|string/number|''|是|组件的绑定值，如输入框内容、选择器选中值||disabled|boolean|false|否|是否禁用组件，禁用后用户无法交互||size|'small'/'medium'/'large'|'medium'|否|组件尺寸，适配不同布局场景|类型标注：使用TypeScript类型语法，支持联合类型、泛型等复杂定义，如(string|number)[]。默认值说明：若默认值为复杂对象或函数，需展示完整代码片段，例如：//自定义列配置默认值defaultColumns:[{key:'name',title:'姓名',width:120},{key:'age',title:'年龄',width:80}]必填标识：严格区分必填与可选属性，避免开发者因遗漏参数导致组件异常。2.事件（Events）清晰描述组件触发的事件及参数，格式如下：事件名：采用kebab-case命名，如change、blur、change。触发时机：明确事件触发的条件，例如“当用户输入内容变化时触发”“当分页页码改变时触发”。参数说明：列出事件回调函数的参数类型及含义，例如：//change事件参数functionhandleChange(value:string,oldValue:string){//value：当前输入值；oldValue：上一次输入值}3.方法（Methods）说明组件对外暴露的可调用方法，包含：方法名：如focus()、reset()。功能描述：方法的作用，例如“让输入框获取焦点”“重置组件到初始状态”。参数与返回值：若方法接收参数或返回数据，需明确类型及示例，例如：//设置组件值setValue(value:string):boolean{//返回值：是否设置成功}4.插槽（Slots）定义组件的自定义内容插槽，包括：插槽名：默认插槽使用default，具名插槽使用具体名称，如header、footer。可用场景：说明插槽的使用场景，例如“自定义表格头部内容”“添加额外的操作按钮”。插槽参数：若插槽提供上下文数据，需展示参数示例，例如：<template#item="{row,index}"><!--row：当前行数据；index：行索引--><span>{{}}({{index}})</span></template>（三）示例代码模块示例是组件的“演示厅”，需覆盖常见使用场景，帮助开发者快速上手。1.基础用法示例展示组件的最简使用方式，包含完整的代码片段及效果说明，例如：<template><Inputv-model="value"placeholder="请输入内容"/></template><scriptsetup>import{ref}from'vue'constvalue=ref('')</script>效果描述：“渲染一个带有占位符的输入框，用户输入内容时双向绑定到value变量”。2.高级用法示例展示组件的复杂配置与组合场景，如表单校验、数据联动、自定义样式等，例如：<template><Form:model="formData":rules="rules"><FormItemlabel="用户名"prop="username"><Inputv-model="formData.username"/></FormItem><FormItemlabel="密码"prop="password"><Inputv-model="formData.password"type="password"/></FormItem><Buttontype="primary"@click="submitForm">提交</Button></Form></template><scriptsetup>import{ref}from'vue'constformData=ref({username:'',password:''})construles=ref({username:[{required:true,message:'请输入用户名',trigger:'blur'}],password:[{required:true,message:'请输入密码',min:6,trigger:'blur'}]})constsubmitForm=()=>{//表单校验逻辑}</script>关键说明：标注代码中的核心配置，如表单校验规则的定义、提交事件的处理逻辑。3.错误用法示例列举常见的错误使用方式及后果，帮助开发者规避问题，例如：<!--错误：v-model绑定值类型与组件要求不符--><Inputv-model="numberValue"/><scriptsetup>import{ref}from'vue'constnumberValue=ref(0)//组件要求value为string类型，会导致类型错误</script>错误原因：“组件value属性仅支持string类型，绑定number类型会导致输入异常”。解决方案：“将绑定值转换为string类型，如constnumberValue=ref('0')”。（四）样式与主题模块说明组件的样式定制方案，满足不同项目的视觉需求。默认样式：展示组件在默认主题下的外观截图，包含不同状态（正常、hover、active、disabled）。CSS类名：列出组件暴露的自定义类名，如el-input__wrapper、el-button--primary，方便通过CSS覆盖样式。主题变量：若支持主题定制，展示可配置的CSS变量，例如：/*自定义按钮主题色*/:root{--el-color-primary:#1890ff;--el-color-primary-light-3:#40a9ff;}响应式适配：说明组件在不同屏幕尺寸下的表现，如“在移动端自动调整为垂直布局”。（五）兼容性与异常处理模块1.浏览器兼容性明确组件支持的浏览器版本，例如：现代浏览器：Chrome90+、Firefox88+、Safari14+移动端：iOSSafari14+、AndroidChrome90+兼容处理：说明对低版本浏览器的降级方案，如“在IE11下部分动画效果失效，但核心功能正常”。2.异常场景处理列举组件可能遇到的异常情况及处理方式，例如：数据为空：当组件绑定值为null或undefined时，显示占位文本“暂无数据”。网络请求失败：若组件依赖接口数据，请求失败时展示错误提示，并提供重试按钮。参数错误：当传入非法参数时，在控制台输出警告信息，如“警告：size属性值无效，已自动使用默认值'medium'”。二、文档编写风格规范（一）语言与术语统一中文表述：使用规范的技术术语，避免口语化表达，如“点击按钮”而非“点一下那个按钮”。术语一致性：统一技术词汇，如“属性”“事件”“方法”，避免混用“参数”“函数”等模糊表述。代码风格：示例代码遵循项目的ESLint规范，缩进、引号、分号保持一致，提高可读性。（二）描述精确性避免模糊词汇：不用“大概”“可能”“也许”等不确定表述，例如不说“组件性能较好”，而是说“组件渲染时间小于20ms，支持1000条数据无卡顿”。量化指标：涉及性能、尺寸等指标时，提供具体数值，如“组件打包后体积约15KB（gzip压缩后）”。场景化描述：结合实际业务场景说明组件特性，例如“当列表数据超过50条时，自动启用虚拟滚动，减少DOM节点数量”。（三）示例完整性可运行性：示例代码需完整可复制，包含必要的导入语句、模板结构和脚本逻辑，确保开发者粘贴到项目中即可运行。注释清晰：在关键代码处添加注释，解释代码的作用，例如：//使用watch监听输入值变化，实时触发校验watch(value,(newVal)=>{validateField('username')})效果展示：每个示例搭配对应的截图或在线演示链接（如CodeSandbox、StackBlitz），让开发者直观看到运行结果。三、文档维护与更新规范（一）版本同步机制迭代同步：组件代码更新后，需在24小时内同步更新文档，确保文档与代码版本一致。更新日志：在文档末尾添加版本更新记录，格式如下：##更新日志-v2.3.0（2025-03-15）：新增`disabled`属性，优化键盘导航体验-v2.2.0（2025-02-20）：修复多选模式下数据回显错误-v2.1.0（2025-01-10）：支持自定义插槽内容（二）审核与发布流程自我审核：文档编写完成后，作者需对照规范检查内容完整性、准确性，确保示例代码可运行。交叉评审：由团队内其他开发者审核文档，从使用者角度提出改进建议。发布上线：审核通过后，将文档部署到内部文档平台或开源仓库，并通知相关团队。（三）反馈与迭代反馈渠道：在文档末尾添加反馈入口，如“如有问题或建议，请提交Issue至GitHub仓库”。定期复盘：每季度对组件文档进行一次全面复盘，收集开发者反馈，优化文档结构与内容。四、文档工具与自动化规范（一）编写工具选择Markdown优先：使用Markdown编写文档，便于版本控制与渲染，推荐搭配Typora、VSCode等编辑器。API自动生成：通过代码注释自动生成API文档，例如使用TypeDoc、VuePress等工具，减少手动编写错误。/***日期选择器组件*@paramvalue-选中的日期值*@paramdisabled-是否禁用组件*/exportinterfaceDatePickerProps{value:string;disabled?:boolean;}（二）自动化校验链接校验：使用工具（如markdown-link-check）定期检查文档中的链接有效性，避免死链。代码示例校验：通过CI/CD流程自动运行示例代码，确保代码可编译、无语法错误。规范检查：使用ESLint插件检查文档格式，确保符合团队的Markdown规范。（三）文档部署与访问静态站点生成：使用VuePress、Docusaurus等工具将Markdown文档转换为静态网站，支持搜索、导航等功能。版本化部署：为每个组件版本部署独立的文档站点，如/components/v2.3.0/date-picker。内部访问权限：根据组件的敏感程度，设置文档的访问权限，确保业务组件文档仅对内部团队开放。五、文档协作与团队规范（一）责任分工组件开发者：负责编写和维护所开发组件的文档，确保文档与代码同步更新。文档专员：协助优化文档结构、统一风格，组织文档评审与复盘。团队负责人：监督文档规范的执行，定期检查文档质量。（二）培训与共享新人培训：将文档规范纳入新人培训内容，确保新成员掌握编写要求。经验分享：定期组织文档编写经验分享会，交流最佳实践与技巧。模板共享：在团队内部共享文档模板，提高编写效率与一致性。（三）奖惩机制激励措施：对编写高质量文档的开发者进行表彰，如纳入绩效评估、颁发“最佳文档奖”。惩罚措施：对文档缺失、错误或更新不及时的情况，要求限期整改，影响项目进度的需承担相应责任。六、特殊组件文档规范（一）业务组件文档业务组件与具体业务场景强相关，需额外补充以下内容：业务背景：说明组件开发的业务需求，如“为满足电商平台订单管理需求，开发此批量操作组件”。业务规则：描述组件涉及的业务逻辑，如“仅当订单状态为‘待支付’时，显示‘取消订单’按钮”。关联系统：说明组件与其他系统的交互关系，如“调用订单服务接口获取订单列表数据”。（二）复杂组件文档对于包含多个子组件或复杂逻辑的组件（如表单、表格），需补充：组件架构图：使用Mermaid或流程图展示组件的内部结构与交互关系，例如：graphTDA[Table组件]-->B[TableHeader子组件]A-->C[TableBody子组件]C-->D[TableRow子组件]性能优化说明：介绍组件