前端公共组件命名规范指南

前端公共组件命名规范指南一、总则（一）目的明确。本指南旨在规范前端公共组件命名，提升代码可读性与可维护性，促进团队协作效率。（二）适用范围。本规范适用于公司所有前端项目，包括但不限于Web端、移动端及小程序开发。二、命名原则（一）统一规范。组件命名需遵循全公司统一标准，避免因个人习惯导致命名混乱。（二）语义清晰。命名应准确反映组件功能、用途或结构，便于开发者快速理解。（三）简洁易记。避免冗长命名，优先选择简短且具有描述性的词汇。（四）避免歧义。禁止使用可能产生误解或歧义的词汇，如"item"、"box"等过于通用的名称。（五）可扩展性。命名需考虑未来功能扩展，预留合理命名空间。三、命名规则（一）基础组件命名。采用"功能类型+业务领域"结构，如"btnLogin"、"inputSearch"。（二）容器组件命名。使用"容器类型+内容描述"，如"cardProfile"、"modalSettings"。（三）功能组件命名。采用"动词+名词"结构，如"filterTags"、"uploadFiles"。（四）复合组件命名。使用"主组件+子组件"结构，如"tablePagination"、"formInput"。（五）状态组件命名。采用"状态+组件类型"，如"loadingIndicator"、"errorBoundary"。（六）特殊组件命名。针对特殊用途组件，需在规范基础上增加标识，如"btnGhost"、"tabVertical"。四、命名示例（一）按钮组件。btnPrimary、btnSecondary、btnDanger、btnGhost、btnLink。（二）表单组件。formLogin、formRegister、inputText、inputNumber、selectCategory。（三）列表组件。listUsers、tableData、gridProducts、carouselImages、timelineEvents。（四）导航组件。navMain、tabDashboard、menuSettings、sidebarProfile、breadcrumbsHome。（五）反馈组件。toastSuccess、alertError、modalConfirm、progressBar、loadingSpinner。（六）布局组件。layoutFixed、layoutFluid、containerMain、headerFixed、footerSticky。五、命名禁忌（一）禁止使用中文拼音缩写，如"btn"代替"按钮"。（二）禁止使用无意义的名称，如"compA"、"widgetX"。（三）禁止使用特殊字符或数字，如"btn1"、"form_2023"。（四）禁止使用已存在的HTML元素名称，如"divContent"、"spanInput"。（五）禁止使用英文缩写（除非为通用术语），如"btnOk"代替"btnConfirm"。（六）禁止使用版本号或日期，如"btnV1"、"input2023"。六、命名转换规范（一）中文转英文。采用功能优先原则，如"搜索框"转为"searchInput"。（二）动词转名词。如"上传"转为"upload"而非"uploadAction"。（三）复数处理。使用单数形式，如"标签"转为"tag"而非"tags"。（四）中文首字母。中文词组采用首字母缩写，如"用户信息"转为"userInfo"。（五）特殊处理。如"设置"统一为"settings"而非"set"。七、命名工具与检查（一）代码检查工具。集成ESLint插件，配置组件命名规则检查。（二）Git钩子。设置pre-commit钩子，自动校验组件命名。（三）组件库管理。使用Storybook管理组件，强制执行命名规范。（四）代码评审。将组件命名检查列为代码评审必检项。（五）文档同步。命名变更需同步更新设计文档与API文档。八、实施与培训（一）培训计划。组织前端组件命名规范培训，覆盖所有开发人员。（二）文档发布。将本指南发布至公司知识库，提供查阅入口。（三）示例代码。提供标准组件命名示例代码库，供参考使用。（四）定期检查。每季度开展组件命名规范检查，对违规项进行整改。（五）奖惩机制。将命名规范执行情况纳入绩效考核，优秀案例予以表彰。九、组件分类命名细则（一）基础UI组件。btn[类型]、input[类型]、select[类型]、icon[名称]、div[用途]。（二）表单组件。form[用途]、field[字段类型]、validate[校验类型]、group[分组名称]。（三）布局组件。layout[类型]、container[尺寸]、header[样式]、footer[定位]、sidebar[方向]。（四）数据展示组件。table[数据类型]、chart[图表类型]、grid[行列结构]、list[列表类型]、tag[标签类型]。（五）交互组件。modal[用途]、dialog[功能]、toast[状态]、alert[级别]、confirm[操作]。（六）特殊组件。audio[控制]、video[播放]、canvas[绘图]、svg[图形]、draggable[拖拽]。十、命名升级机制（一）版本管理。组件命名升级需遵循版本控制原则，如btnPrimary升级为btnPrimaryV2。（二）兼容策略。命名变更需评估对现有代码的影响，提供迁移方案。（三）命名空间。复杂项目可使用命名空间前缀，如"coreBtn"、"uiInput"。（四）废弃流程。已废弃的组件命名需标记为"deprecated"，并提供替代方案。（五）评审流程。重大命名升级需经过技术委员会评审通过。十一、附则说明（一）本规范自发布之