公司有三个后台项目,做的时候都是赶工期,日期选择器从第一个项目复制到第二个,再复制到第三个。某天客服反馈:用户选 11 月 6 日,保存后列表里显示 11 月 5 日。排查发现是日期转字符串时走了 UTC,东八区的零点退到了前一天。修的时候更麻烦:三份代码逻辑相似但已经各自改过,第一份加了「不可选未来日期」,第二份加了「快捷选项」,第三份把样式调成了另一种圆角。三处都要改,改完还要分别回归,最后行为仍然不完全一致。

团队决定把日期选择器收成公共组件。真正开始做才发现,难点不在日历怎么画,而在几个之前没想过的问题:外部要不要能控制选中的值?键盘能不能操作?弹层打开后焦点放哪?其他项目想改按钮颜色怎么办?改完 API 怎么发版,才不会让已经接入的项目半夜构建失败?

这篇讲组件库和可复用组件的设计。重点不是推荐某个库,而是把「什么时候该用现成的、API 怎么定、无障碍怎么做、样式怎么留口子、版本怎么发」这几件事按项目顺序讲清楚。组件化不是把代码抽到一个文件夹,而是把一份需要长期维护的契约抽出来。

先用现成的还是自己写:先算维护账

遇到重复组件,第一反应常常是「抽个公共库」。但在抽之前,先算一笔账:这个组件未来要维护多久、有多少项目依赖、团队里谁负责接 issue。写一个日期选择器可能只要三天,维护它三年需要处理浏览器差异、无障碍反馈、设计改版、依赖升级、下游项目的定制需求,这些都不在最初的三天里。

现成库的优势是这些账已经有人替你付过。Ant Design 面向企业后台,组件全、表单和表格能力强,适合业务密集、界面风格统一的管理系统;Element Plus 是 Vue 生态里类似定位的选择,和 Vue 的写法结合紧密;Radix 走的是无样式原语路线,只提供行为和可访问性,视觉完全交给使用方,适合有自己设计系统的团队。这三者不是谁更好的关系,是三种不同的分工方式。

用现成的

省掉基础行为和边界处理,文档、社区、无障碍通常更成熟。代价是视觉和交互要跟着它的规范走,深度定制会变成和内部结构对抗,包体积和升级节奏也不完全由你控制。

自己写

API、样式、发布节奏都自己说了算,能贴合业务。代价是行为细节、键盘操作、焦点管理、浏览器兼容都要自己兜,长期维护需要明确的人。

判断维度可以按顺序问四个问题。第一,这个组件是不是业务核心?日期选择器、按钮、输入框这类通用件,现成库大概率比自己写靠谱;业务特有的审批流、订单卡片,才值得自己封装。第二,设计是否需要高度定制?如果设计系统和主流库差异很大,用无样式原语加自己的样式,比深度覆盖现成库更省事。第三,团队有没有长期维护的人?没有负责人就不要自建,否则半年后它就是新的技术债。第四,下游有多少项目?三个以上、且需求开始分叉,才值得抽出独立包;只有两个项目、需求一致,共享一个目录就够。

「自己写」不等于从零写。可以用无样式库处理弹层定位、焦点陷阱、键盘导航这些最容易出错的部分,自己只写视觉和业务 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 或插槽允许替换内部结构。三层从轻到重,使用方能按需要选择。

主题层: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;下游只用一个组件却被迫全量引入,是最常见的抱怨。

一句话的判断:组件库解决的是「多项目、长期、需要一致行为」的问题。如果只是「这个页面想复用一段结构」,抽成组件就够了,不必上升成库。

今天就能验证的练习,和小结

  1. 写一个受控输入框,父级故意不在 onChange 里更新 value,确认输入没有反应;再把更新补上,理解「受控」的责任在哪一方。
  2. 在东八区用 new Date(2026, 10, 6).toISOString().slice(0, 10) 打印一次,确认输出 2026-11-05;再改用本地字段拼接,确认输出 2026-11-06。
  3. 做一个只有两个页签的 Tabs,拔掉鼠标,只用 Tab 和方向键操作,记录焦点在哪、aria-selected 有没有跟着变。
  4. 给一个按钮组件加 CSS 变量主题,只改 --btn-accent 就换颜色;再尝试用 className 改外边距,确认不需要动组件内部样式。
  5. 找一个项目里的公共组件,检查它的 props 命名是否和表单组件一致;把不一致的一处列出来,评估改动会影响多少调用点。
先算维护账:通用件优先用现成库或无样式原语,业务核心件才自己封装,且要有负责人。
API 先定状态归属:受控与非受控都支持,defaultValue 只管初始值,回调签名全库统一。
无障碍是组件行为的一部分:键盘、焦点、aria 一开始就做,否则会被复制到所有页面。
样式留三层口子:CSS 变量、className、headless;不要让使用方用深层选择器拆内部结构。
文档和版本是产品的一部分:示例可运行,breaking change 走 major,给迁移路径和包体积预算。

组件化把重复的交互沉淀成资产:一个日期选择器不再有三份实现,一套交互和可访问性规则不再每个页面重写。真正交付的不是代码,是一份能被多个项目依赖、还能持续升级的契约。

但组件库解决的是「长什么样、怎么交互」,页面里还有一类东西比它更容易失控:数据。列表页要 loading、要错误提示、要缓存、要在返回时恢复状态,这些如果每个组件各写一遍,组件库再整齐也救不回来。下一篇把数据请求单独拎出来讲。

再往后,资产要被构建、检查、发布,问题就从「怎么写」变成了「怎么保证每次发布都一致」。工程化那一组会接着讲这些资产怎么打包、怎么做静态检查、怎么跑测试和发布流水线。这篇里提到的按需加载、tree-shaking、版本发布、依赖范围,都会落到具体工具和流程上;现在先把组件的边界和契约定清楚,后面的构建配置才有意义。