结论先行：自建组件库不是把现成组件搬进设计器，而是把组件改造成「可被非开发者配置」的物料。完整流程只有五步：契约定义、物料封装、属性面板、校验与默认值、版本与灰度。单个组件的投入通常在 2~4 人日，其中一半时间花在属性面板和默认值上，而不是写组件本身。先想清楚哪些组件必须自建、哪些直接用第三方，能省掉大量无效工作。

一、先判断：什么组件值得自建

不是所有组件都值得自建。判断标准有三条：

• 业务上高频出现，且第三方组件无法通过属性配置覆盖；
• 交互规则与产品强绑定，比如带审批状态的卡片、带库存校验的选择器；
• 需要统一品牌视觉，第三方组件的样式改造成本高于重写。

反过来，纯展示类、纯布局类组件优先用第三方，把自建预算留给业务组件。

二、第一步：契约定义

契约（Contract）指组件对外承诺的输入输出边界，至少要写清四件事：

1. 数据结构：接收什么字段、字段类型、是否必填；
2. 事件：会向外抛出哪些事件，触发时机是什么；
3. 样式变量：哪些颜色、间距、圆角允许被设计器修改；
4. 渲染边界：在哪些端可用，小程序端有哪些限制。

契约没定清，后面属性面板会反复改，返工成本远高于前期多花半天。

三、第二步：物料封装

封装是把普通组件变成设计器可识别的物料，关键动作：

• 声明物料元信息：名称、图标、分类、搜索关键词；
• 声明拖入画布时的默认尺寸与默认属性；
• 把内部状态与外部数据源解耦，避免组件直接请求接口；
• 对外只暴露契约内的属性，内部实现细节不进入配置面板。

四、第三步：属性面板

属性面板（Property Panel）是使用者与组件之间唯一的操作界面，设计原则是「少而分组」：

• 按「内容、样式、交互、数据」四组折叠，每组不超过 6 个可见项；
• 高频属性放前面，低频属性收进「更多设置」；
• 复杂属性用选择器或开关，不要让使用者手填 JSON 字符串；
• 每个属性都要有中文标签与一句说明，避免只写英文字段名。

五、第四步：校验与默认值

这一步决定组件在真实项目里好不好用。

• 默认值要能直接跑起来：拖进画布就能看到内容，而不是空白占位；
• 属性变更要即时校验：数值越界、必填为空、枚举值不合法时在面板上提示，而不是等预览才报错；
• 边界情况要有兜底：数据为空、字段缺失、接口超时，组件都应显示占位状态而不是崩溃；
• 默认值同时是文档：多数使用者不会读文档，会直接看拖进来的样子。

六、第五步：版本与灰度

组件一旦被多个页面引用，升级就变成风险动作。需要做到：

• 语义化版本：破坏性变更升主版本，新增属性升次版本，修复升补丁版本；
• 页面锁定版本：页面记录所用组件版本，不随组件库升级而自动变化；
• 灰度发布：先放开给 1~2 个试点页面，观察一周再全量；
• 保留回滚：组件保留上一主版本至少 3 个月，避免旧页面无法渲染。

七、自有组件与第三方组件的取舍

八、建库的三条经验

1. 从 10 个组件起步：先覆盖最高频的业务场景，不要一开始就按 UI 框架全量复制。
2. 每个组件配一个示例页面：示例页面既是验收标准，也是使用者的上手材料。
3. 建库前先定命名规范：组件名、属性名、事件名统一前缀，后期检索和迁移成本会低一个量级。

组件层面的验收标准怎么落成清单，见拖拽生成的页面质量怎么验收。

FAQs

Q1：自建组件库需要前端开发能力吗？

A：需要。物料封装、契约定义、属性面板映射都涉及代码，通常由 1~2 名熟悉框架的前端开发者负责，业务人员只能参与属性命名与默认值确认。

Q2：一个组件从设计到上线要多久？

A：多数情况 24 人日，简单展示组件约 2 人日，带数据交互和复杂校验的业务组件约 4 人日；若需要多端适配，再增加 12 人日。

Q3：组件升级会不会影响已经上线的页面？

A：会，如果页面没有锁定版本。做法是页面记录组件版本号，升级走灰度，并保留上一主版本至少 3 个月，确保旧页面随时可回滚。

延伸阅读

• 物料体系设计：组件库如何服务低代码平台
• 组件化开发有什么好处？5大优势一次讲清
• 设计系统是什么？怎么从零搭建一套设计系统
• 低代码 DSL 怎么设计？从 JSON Schema 到页面渲染