公司有三个后台项目,做的时候都是赶工期,日期选择器从第一个项目复制到第二个,再复制到第三个。某天客服反馈:用户选 11 月 6 日,保存后列表里显示 11 月 5 日。排查发现是日期转字符串时走了 UTC,东八区的零点退到了前一天。修的时候更麻烦:三份代码逻辑相似但已经各自改过,第一份加了「不可选未来日期」,第二份加了「快捷选项」,第三份把样式调成了另一种圆角。三处都要改,改完还要分别回归,最后行为仍然不完全一致。
团队决定把日期选择器收成公共组件。真正开始做才发现,难点不在日历怎么画,而在几个之前没想过的问题:外部要不要能控制选中的值?键盘能不能操作?弹层打开后焦点放哪?其他项目想改按钮颜色怎么办?改完 API 怎么发版,才不会让已经接入的项目半夜构建失败?
这篇讲组件库和可复用组件的设计。重点不是推荐某个库,而是把「什么时候该用现成的、API 怎么定、无障碍怎么做、样式怎么留口子、版本怎么发」这几件事按项目顺序讲清楚。组件化不是把代码抽到一个文件夹,而是把一份需要长期维护的契约抽出来。
先用现成的还是自己写:先算维护账
遇到重复组件,第一反应常常是「抽个公共库」。但在抽之前,先算一笔账:这个组件未来要维护多久、有多少项目依赖、团队里谁负责接 issue。写一个日期选择器可能只要三天,维护它三年需要处理浏览器差异、无障碍反馈、设计改版、依赖升级、下游项目的定制需求,这些都不在最初的三天里。
现成库的优势是这些账已经有人替你付过。Ant Design 面向企业后台,组件全、表单和表格能力强,适合业务密集、界面风格统一的管理系统;Element Plus 是 Vue 生态里类似定位的选择,和 Vue 的写法结合紧密;Radix 走的是无样式原语路线,只提供行为和可访问性,视觉完全交给使用方,适合有自己设计系统的团队。这三者不是谁更好的关系,是三种不同的分工方式。
用现成的
省掉基础行为和边界处理,文档、社区、无障碍通常更成熟。代价是视觉和交互要跟着它的规范走,深度定制会变成和内部结构对抗,包体积和升级节奏也不完全由你控制。
自己写
API、样式、发布节奏都自己说了算,能贴合业务。代价是行为细节、键盘操作、焦点管理、浏览器兼容都要自己兜,长期维护需要明确的人。
判断维度可以按顺序问四个问题。第一,这个组件是不是业务核心?日期选择器、按钮、输入框这类通用件,现成库大概率比自己写靠谱;业务特有的审批流、订单卡片,才值得自己封装。第二,设计是否需要高度定制?如果设计系统和主流库差异很大,用无样式原语加自己的样式,比深度覆盖现成库更省事。第三,团队有没有长期维护的人?没有负责人就不要自建,否则半年后它就是新的技术债。第四,下游有多少项目?三个以上、且需求开始分叉,才值得抽出独立包;只有两个项目、需求一致,共享一个目录就够。
API 设计:先定清楚谁持有状态
可复用组件最先要定的是状态归属。以日期选择器为例,选中的日期到底由组件自己记,还是由使用方记?这两种模式分别叫非受控和受控,它们决定了组件能不能被外部联动、能不能被表单统一管理。
非受控模式最省事:使用方给一个初始值 defaultValue,之后组件自己维护状态,只在变化时通过 onChange 通知。受控模式则要求使用方传 value,组件不保存状态,每次变化都请求使用方更新,更新后再传回来。两种都要支持,但必须把规则写清楚。
// React 环境:同时支持受控与非受控
function DatePicker({ value, defaultValue = "", onChange, label }) {
const isControlled = value !== undefined;
const [inner, setInner] = useState(defaultValue);
const current = isControlled ? value : inner;
function select(next) {
if (!isControlled) setInner(next);
onChange?.(next);
}
return (
<label>
{label}
<input
type="date"
value={current}
onChange={(event) => select(event.target.value)}
/>
</label>
);
}
这段代码用原生日期输入,任何支持 input type="date" 的浏览器都能跑。value 不传就是非受控,组件用内部状态;传了就是受控,内部状态不再生效。要注意一个坑:不要在运行中从非受控切到受控,React 会对这种切换发出警告,行为也容易混乱。要么一开始就传 value,要么一直不传。
defaultValue 只表示初始值,后续使用方再改它,组件不应该跟着变。很多 bug 来自「以为改了 defaultValue 就能重置组件」,实际不会。需要重置时,受控模式由外部改 value;非受控模式要给一个明确的 reset 方法或换一个 key。
children 与复合组件:把结构交给使用方
有些组件的结构比行为更值得暴露。比如标签页,使用方需要决定有几个页签、每个页签写什么,组件只负责切换逻辑和键盘行为。写成一个大 props 配置,使用方会被迫把内容塞进数组,读起来很别扭;写成复合组件,结构就回到模板里。
// React 环境:用 context 串起 Tabs 和 Tab,完整可运行的最小版
import { createContext, useContext, useState } from "react";
const TabContext = createContext(null);
function Tabs({ defaultValue, children }) {
const [active, setActive] = useState(defaultValue);
return (
<TabContext.Provider value={{ active, setActive }}>
<div>{children}</div>
</TabContext.Provider>
);
}
function Tab({ value, children }) {
const { active, setActive } = useContext(TabContext);
return (
<button
type="button"
role="tab"
aria-selected={active === value}
onClick={() => setActive(value)}
>
{children}
</button>
);
}
使用方这样写:<Tabs defaultValue="all"><Tab value="all">全部</Tab><Tab value="open">待处理</Tab></Tabs>。结构清晰,新增页签不用改组件。复合组件的代价是约定变多:哪些子组件能放、顺序有没有要求、父子怎么通信,都要在文档里写明。子组件脱离父组件单独使用会报错,这是可以接受的,但错误信息要能看懂。
不要为了「灵活」把所有东西都做成 children。按钮的内容适合 children,布局和关键行为不适合。使用方如果能把组件拆散到无法正常工作,那不叫灵活,叫没设计。
props 命名:一致比聪明重要
组件库的 API 会被几十个页面调用,命名不一致的代价会被放大。最基础的三条:值用 value,变化用 onChange,初始值用 defaultValue。不要这个组件叫 onSelect,那个叫 onValueChange,第三个叫 onUpdate。每个名字单看都合理,放在一起就要查文档。
布尔属性用肯定语义,避免 noBorder、disablePadding 这种双重否定。要表达「不加边框」,用 bordered={false} 比 noBorder 更容易读。布尔属性的默认值也要统一:如果大多数场景需要边框,默认就是有边框,让少数场景显式关掉。
尺寸、变体这类枚举,用一组固定的字符串,不要同时支持 size="small" 和 size={12}。固定枚举方便统一改样式,也方便在文档里列全。需要透传原生属性时,把剩下的 props 展开到根元素上,但要有选择地透传,别把内部使用的属性也漏到 DOM 上,控制台会报一堆未知属性警告。
事件回调的签名也要稳定。是只传新值,还是传新值和旧值,还是传事件对象,要在所有组件里统一。下游项目会基于这个签名写逻辑,改签名就是 breaking change,代价比想象中大。
无障碍不是收尾工作,是组件行为的一部分
可复用组件的无障碍问题会被复制到所有使用它的页面。一个弹窗没有焦点陷阱,意味着所有接入这个弹窗的页面都有同样的问题;一个自定义下拉不能用键盘选择,所有表单都受影响。这种事后再补,成本比一开始就做高得多,因为焦点顺序和键盘行为会牵扯到组件结构。
最低限度要满足几件事。所有可点击元素用 button 或带正确 role 的元素,不要用 div 加点击事件;图标按钮要有 aria-label;弹层打开时把焦点移进去,关闭时还给触发元素;弹层内按 Tab 不能跑到背后的页面;Escape 能关闭;下拉和标签页支持方向键切换。
// 键盘处理的基本骨架,放在弹层或列表容器上
function handleKeyDown(event) {
if (event.key === "Escape") {
closeLayer();
}
if (event.key === "ArrowRight") {
focusNextItem();
}
if (event.key === "ArrowLeft") {
focusPreviousItem();
}
}
焦点管理有几个容易漏的细节。打开弹层前记下当前焦点,关闭后还回去,否则用户不知道自己在哪;弹层里有多个可聚焦元素时,初始焦点放在第一个有意义的位置,不要放在关闭按钮上;禁用状态要用 disabled 或 aria-disabled,不要只把颜色调浅,键盘仍然能触发。
测试方法很朴素:拔掉鼠标只用键盘走一遍,能不能打开、选择、关闭,关闭后焦点在哪;再开屏幕阅读器听标签和状态有没有念出来。规则见HTML 无障碍,组件库要把它们固化成默认行为。
样式覆盖:留三个口子,别让使用方拆墙
组件库不可能满足所有视觉需求,一定要留覆盖入口。比较健康的方式是三层:第一层,CSS 变量控制颜色、圆角、间距这类主题值;第二层,className 允许使用方在外层加类,做局部布局调整;第三层,headless 或插槽允许替换内部结构。三层从轻到重,使用方能按需要选择。
最不健康的方式是让使用方写深层选择器。比如 .ant-select .ant-select-selector .ant-select-selection-item 一路点下去改高度。这种写法依赖内部结构,组件库一升级,类名或层级一变就失效;而且它从业务样式里穿透到组件内部,出了问题很难判断是谁的责任。
如果非要用选择器覆盖,把范围收在组件根节点的自定义类下面,并且只覆盖一两个属性。不要复制整段组件样式再改,那等于把内部实现抄进了业务代码。升级时要重点检查这些覆盖点,最好在文档里列出来。
业务页面别直接改组件内部字号,组件也别假设自己处在某个页面布局里;两边通过变量和 className 交流,升级和改版才不会互相牵连。
文档、示例和版本纪律:让下游敢升级
组件库真正的产品是文档。使用方不读源码,只看文档里的示例和 props 表。每个组件至少要有:一段最小可用示例、受控和非受控怎么写、常见组合、props 说明、无障碍说明、已知限制。示例要能直接复制运行,不要只放截图。
Storybook 这类工具的价值是把示例变成可浏览、可交互的页面,顺便能跑视觉检查。是否使用具体工具不重要,重要的是每个组件都有一个稳定的展示入口,设计、测试、开发能对着同一个页面讨论。示例最好覆盖边界状态:空数据、加载中、禁用、超长文本、错误状态。
版本纪律比文档更影响下游。语义化版本的基本约定是:修 bug 发 patch,加可选能力发 minor,改 API 或行为发 major。真正难的是判断什么算 breaking change。删 props、改回调签名、改默认行为、改 DOM 结构导致外部样式失效,这些都算。很多团队只把「删 API」当 breaking,结果下游在小版本升级后样式或交互变了。
发布 breaking change 时,要给迁移路径:废弃警告至少保留一个 minor 周期,文档写清旧写法和新写法,能提供 codemod 就提供。changelog 要写「对使用方有什么影响」,不要只列提交记录。peerDependencies 的范围要明确,避免下游装了不兼容的框架版本。
按需加载和包体积要从第一天考虑。每个组件独立入口、打包时能 tree-shake、避免入口文件副作用导入全部组件。下游只用一个按钮,不该把整个库和图标全下载。入口怎么写、用默认导出还是具名导出,和ES 模块的规则直接相关;发布前用包分析看一眼。
完整场景:日期选择器从三份复制到一个包
需求:三个后台项目都要日期选择器,支持受控和非受控,能禁用未来日期,键盘可操作,样式跟随各项目的主题色,发布成独立包,下游按需引入。最初的实现是复制来的,日期格式化这样写:
// 错误示范:在东八区,本地零点会被转成前一天
function formatBad(date) {
return date.toISOString().slice(0, 10);
}
console.log(formatBad(new Date(2026, 10, 6))); // 2026-11-05
这就是开头那个「选 6 号显示 5 号」的根因。new Date(2026, 10, 6) 表示本地时间 11 月 6 日零点,转成 UTC 是 11 月 5 日 16 点,再截前十个字符就成了 5 号。只要用户在东八区、日期又在本地零点附近,就会差一天。修复方式是按本地字段拼接,不要让日期经过 UTC:
function formatLocal(date) {
const year = date.getFullYear();
const month = String(date.getMonth() + 1).padStart(2, "0");
const day = String(date.getDate()).padStart(2, "0");
return year + "-" + month + "-" + day;
}
console.log(formatLocal(new Date(2026, 10, 6))); // 2026-11-06
更彻底的做法是把「日期」当成纯字符串处理,组件对外只认 YYYY-MM-DD,内部要做日历计算时再解析,并且明确用本地时间。这样跨时区传输、存数据库、回显都不会因为时区偏移一天。不要把 Date 对象直接当业务值传来传去,它带时区语义,很容易在某一层被意外转换。
第二版把复制代码收进公共包,同时补上受控、非受控、禁用日期、键盘操作和主题变量。API 定成 value、defaultValue、onChange、min、max、disabled,和其他表单组件保持同一套命名。样式只暴露 CSS 变量,不暴露内部类名。发布前写清三条升级说明:日期值统一为字符串、受控模式必须回传 value、禁用日期从布尔开关改成范围。
上线后仍然会遇到下面这些故障。它们大多不是日历画得对不对,而是契约没定清楚或版本没管好。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 选 6 号,保存后显示 5 号 | 日期经过 UTC 转换,东八区本地零点退到前一天 | 看格式化有没有用 toISOString,打印转换前后的值 |
| 父组件传入 value 后,选择没有反应 | 受控模式下父级没有在 onChange 里更新 state | 看 onChange 有没有真正写回 value |
| 升级组件库后,按钮高度和圆角全变了 | 业务侧用深层选择器覆盖了内部结构,结构一变就失效 | 搜业务 CSS 里对组件库内部类名的引用 |
| 弹窗打开后,Tab 键跑到背后的页面 | 没有焦点陷阱,初始焦点也没移进弹层 | 打开时打印 document.activeElement,再连按 Tab 观察 |
| 小的版本升级后构建失败 | 依赖范围过宽,或 breaking change 没有按 major 发布 | 看 changelog、peerDependencies 和实际安装版本 |
| 首屏体积多了两百 KB | 全量引入组件库,入口文件有副作用,tree-shaking 失效 | 看包分析里组件库占比和入口的导入方式 |
表格里第二条最容易被误判成组件 bug。受控组件的契约是「值由你管,组件只通知」,父级不回传,组件就只能一直显示旧值。文档里要把这一点写成显式示例,不要只写一句「支持受控」。
边界与代价:什么规模适合做组件库
组件库是长期资产,也是长期负债。下面这些边界决定它值不值得做、做到什么程度。
- 只有两个页面用、且需求不会分叉的组件,不要抽成包。抽出去之后,每次改都要发版、升级、回归,成本高于复制一份。
- 三个以上项目依赖、且有明确负责人时才适合独立包。issue 要有模板、分级和固定处理节奏;没有负责人的库,问题会堆着,最后大家绕开它自己写。
- 不要为了统一命名去包装现成库。把
onChange包成onValueChange,把size包成scale,只是多一层翻译,使用方还要学两套 API。包装应该增加能力,不是改名字。 - 无障碍和键盘行为是持续成本。每加一个交互组件,都要重新验证焦点、键盘、屏幕阅读器;把它当成一次性工作,迟早会还债。
- 样式覆盖口子开得越多,内部实现越难改。变量、className、headless 三层要明确边界,不要每个使用方都提一个插槽需求。
- 版本纪律破一次,下游就会锁版本、复制代码、绕开升级;breaking change 的发布流程要比新增功能更严格。
- 包体积要设预算。每加一个依赖、一个图标集、一个日期库,都要看它进了多少 bundle;下游只用一个组件却被迫全量引入,是最常见的抱怨。
一句话的判断:组件库解决的是「多项目、长期、需要一致行为」的问题。如果只是「这个页面想复用一段结构」,抽成组件就够了,不必上升成库。
今天就能验证的练习,和小结
- 写一个受控输入框,父级故意不在
onChange里更新 value,确认输入没有反应;再把更新补上,理解「受控」的责任在哪一方。 - 在东八区用
new Date(2026, 10, 6).toISOString().slice(0, 10)打印一次,确认输出 2026-11-05;再改用本地字段拼接,确认输出 2026-11-06。 - 做一个只有两个页签的 Tabs,拔掉鼠标,只用 Tab 和方向键操作,记录焦点在哪、
aria-selected有没有跟着变。 - 给一个按钮组件加 CSS 变量主题,只改
--btn-accent就换颜色;再尝试用 className 改外边距,确认不需要动组件内部样式。 - 找一个项目里的公共组件,检查它的 props 命名是否和表单组件一致;把不一致的一处列出来,评估改动会影响多少调用点。
组件化把重复的交互沉淀成资产:一个日期选择器不再有三份实现,一套交互和可访问性规则不再每个页面重写。真正交付的不是代码,是一份能被多个项目依赖、还能持续升级的契约。
但组件库解决的是「长什么样、怎么交互」,页面里还有一类东西比它更容易失控:数据。列表页要 loading、要错误提示、要缓存、要在返回时恢复状态,这些如果每个组件各写一遍,组件库再整齐也救不回来。下一篇把数据请求单独拎出来讲。
再往后,资产要被构建、检查、发布,问题就从「怎么写」变成了「怎么保证每次发布都一致」。工程化那一组会接着讲这些资产怎么打包、怎么做静态检查、怎么跑测试和发布流水线。这篇里提到的按需加载、tree-shaking、版本发布、依赖范围,都会落到具体工具和流程上;现在先把组件的边界和契约定清楚,后面的构建配置才有意义。