前端React组件库命名约定指南

前端React组件库命名约定指南一、总则（一）目的明确。为规范前端React组件库命名，提升代码可读性与维护性，本指南旨在统一命名标准，促进团队协作，特制定本约定。1.命名原则1.1.一致性原则。组件命名应遵循统一风格，避免因个人习惯导致命名混乱。1.2.描述性原则。命名需清晰反映组件功能、类型或用途，避免使用模糊或歧义的词汇。1.3.简洁性原则。在满足描述性的前提下，尽量使用简短直观的命名，避免冗长。1.4.可扩展性原则。命名应预留扩展空间，便于后续功能迭代或组件复用。1.5.规范性原则。严格遵循本指南及前端开发通用命名规范。2.适用范围2.1.本指南适用于所有前端React组件库的命名工作，包括但不限于基础组件、业务组件及工具组件。2.2.各开发团队需将本指南纳入团队规范，确保所有成员严格遵守。2.3.新增组件必须遵循本指南进行命名，已有组件逐步按本指南进行标准化改造。二、基础组件命名规则（一）通用组件规范。基础组件命名需体现其通用性，避免与业务场景强关联。1.容器类组件1.1.页面容器：`PageContainer`、`LayoutWrapper`1.2.通用容器：`Container`、`Box`1.3.布局组件：`GridSystem`、`FlexContainer`2.表单类组件2.1.输入组件：`InputField`、`InputText`2.2.选择组件：`SelectBox`、`DropdownMenu`2.3.表单项：`FormItem`、`FieldSet`3.交互类组件3.1.按钮组件：`ButtonPrimary`、`ButtonSecondary`3.2.提示组件：`ToastMessage`、`Notification`3.3.动画组件：`AnimationTransition`、`LoadingIndicator`4.数据展示类组件4.1.列表组件：`ListGrid`、`ListView`4.2.卡片组件：`CardComponent`、`TileView`4.3.图表组件：`ChartBase`、`DataVisualization`三、业务组件命名规则（一）场景化组件规范。业务组件命名需体现其特定业务场景，增强可识别性。1.数据录入组件1.1.表单生成器：`FormBuilder`、`DynamicForm`1.2.数据校验：`ValidatorField`、`InputRule`1.3.编辑器组件：`RichTextEditor`、`CodeMirrorWrapper`2.数据展示组件2.1.数据表格：`DataTable`、`DataGrid`2.2.甘特图：`GanttChart`、`TimelineView`2.3.仪表盘：`DashboardPanel`、`MetricCard`3.交互组件3.1.下拉选择：`Select2`、`MultiSelect`3.2.树形控件：`TreeView`、`HierarchicalList`3.3.栅格布局：`GridPanel`、`LayoutGrid`4.特殊场景组件4.1.移动端适配：`MobileAdaptive`、`ResponsivePanel`4.2.国际化组件：`LocaleComponent`、`TranslationField`4.3.可访问性组件：`AccessibilityWrapper`、`ScreenReaderText`四、工具组件命名规则（一）辅助性组件规范。工具组件命名需体现其辅助功能，保持简洁明了。1.布局辅助1.1.占位符：`SkeletonLoader`、`Placeholder`1.2.分隔线：`DividerLine`、`Separator`1.3.间距管理：`SpacingUnit`、`MarginControl`2.数据处理2.1.数据转换：`DataTransformer`、`FormatUtility`2.2.状态管理：`StateHandler`、`ContextWrapper`2.3.请求封装：`ApiRequester`、`FetchUtility`3.交互增强3.1.拖拽功能：`DraggableElement`、`DropZone`3.2.确认弹窗：`ConfirmDialog`、`PromptWindow`3.3.水印功能：`WatermarkGenerator`、`StampUtility`4.其他工具4.1.类型定义：`TypeHelper`、`InterfaceBuilder`4.2.测试辅助：`TestWrapper`、`MockProvider`4.3.性能监控：`PerformanceLogger`、`BundleAnalyzer`五、命名规范细则（一）命名语法规范。组件命名需遵循统一的语法结构，增强可读性。1.命名结构1.1.基础结构：`组件类型`+`功能描述`+`场景标识`1.2.示例：`ButtonPrimaryConfirm`（按钮类型、主要按钮、确认功能）1.3.禁止使用：避免使用连字符、下划线或驼峰式命名，统一使用小写字母加中划线。2.关键词规范2.1.必须使用：`Component`、`Base`、`Wrapper`、`Utility`等关键词明确组件性质。2.2.避免使用：`Module`、`System`、`Framework`等过于宽泛的词汇。2.3.优先使用：`Primary`、`Secondary`、`Light`、`Dark`等描述性词汇。3.规则限制3.1.长度限制：组件命名总长度不得超过30个字符。3.2.大小写：所有命名必须使用小写字母，重要单词间用中划线分隔。3.3.重复避免：相同类型的组件需使用不同后缀区分，如`ButtonPrimary`、`ButtonSecondary`。六、命名示例与对照（一）典型命名对照。通过具体示例展示规范命名与不规范命名的差异。1.表单组件示例1.1.规范命名：`InputTextEmail`、`SelectBoxAddress`1.2.不规范命名：`email_input`、`address_select_box`1.3.不规范原因：缺乏类型标识、使用连字符而非中划线、过长。2.交互组件示例2.1.规范命名：`ButtonConfirmDelete`、`ModalConfirm`2.2.不规范命名：`delete_confirm_button`、`confirm_modal`2.3.不规范原因：动词优先、缺乏功能描述、大小写错误。3.工具组件示例3.1.规范命名：`SpacingMedium`、`DataFormatCurrency`3.2.不规范命名：`medium_spacing`、`currency_data_format`3.3.不规范原因：缩写使用不当、缺乏关键词、大小写错误。七、实施与维护（一）执行保障机制。为确保命名规范有效落地，需建立配套的实施与维护机制。1.实施流程1.1.新组件开发：必须使用本指南进行命名，代码提交前需通过命名规范检查。1.2.代码审查：审查员需重点检查组件命名是否符合本指南要求。1.3.自动化工具：开发环境需集成命名规范检查工具，如ESLint插件。2.维护机制2.1.定期审计：每季度对组件库进行命名规范审计，识别并整改不符合规范的命名。2.2.版本控制：组件命名变更需在版本控制系统中清晰记录，便于追溯。2.3.更新机制：本指南需根据项目发展定期更新，确保持续适用。3.培训与支持3.1.新人培训：所有新加入团队的开发人员必须接受命名规范培训。3.2.在线文档：提供在线命名规范查询工具，方便开发人员随时查阅。3.3.咨询渠道：设立命名规范咨询渠道，解答开发人员命名疑问。八、附则（一）补充说明与免责。本指南为前端React组件库命名提供指导性规范，特殊情况需经技术负责人审批。1.特殊情况处理1.1.保留原名：已有组件如符合项目历史命名习惯且不影响维护，经审批可保留原名。1.2.逐步迁移：对于大量不符合规范的组件，制定逐步迁移计划，分阶段完成标准化改造。1.3.复用组件：如组件被多个业务线复用，命名需体现其通用性，避免业务线强关联。2.责任划分2.1.开发团队：负责本团队组件库的命名规范执行与维护。2.2.技术负责人：负责命名规范的最终审批与解释。2.3.代码审查：审查员需对命名规范执行