企业实践与时区国际化

• 各库的定位与体积
• Intl.DateTimeFormat 的原生能力
• 时区、格式化、不可变性

原生 Intl.DateTimeFormat 提供浏览器内置的本地化格式化（语言、时区、数字），无需依赖、体积为零，但 API 较低层、不支持解析、链式操作与复杂的日期运算。Moment 功能全但体积大且已进入维护模式；Day.js 轻量（2KB）兼容 Moment API；date-fns 函数式、tree-shakable；Luxon 不可变、IANA 时区强。取舍：简单格式化用 Intl；需要解析/运算/链式按需选库。现代趋势是减少依赖、优先 Intl。

Intl 满足基础格式化，库满足复杂运算与时区，按需选择避免过度依赖。

• PlainDate 表示无时区日期
• ZonedDateTime 表示带时区时间点
• 多时区日历

Temporal API 提供类型化日期时间类型：PlainDate 表示日历日期（无时间、无时区），ZonedDateTime 表示带 IANA 时区的精确时间点，Temporal.Instant 表示绝对时间点。工程化应用：日历展示用 PlainDate（纯日期），跨时区调度用 ZonedDateTime/Instant，分离"日历日期"与"时间点"避免时区混淆。Temporal 不可变、支持 DST 与日历系统，是处理多时区的高级方案。

PlainDate 与 ZonedDateTime 分离"无时区日期"与"带时区时间点"，是 Temporal 处理多时区正确的关键。

• 体积小
• 插件化按需加载
• Moment 兼容 API

dayjs 仅约 2KB，体积小，核心 API 兼容 Moment（parse、format、diff、add 等），通过插件按需扩展（utc、timezone、customParseFormat、relativeTime 等）。轻量场景：不需要完整 Moment 功能、对 bundle 体积敏感的中小项目，只需基础格式化与运算。用插件按需加载避免全量引入。

dayjs 以"小体积 + Moment 兼容 + 插件化"著称，适合轻量、体积敏感的项目。

• 函数式 API
• Tree-shakable
• 不可变

date-fns 提供大量纯函数工具（format、addDays、isAfter 等），每个函数独立模块，天然 tree-shakable，只打包用到的函数。支持 FP 风格（fp 子模块，curried、数据最后参数）与 immutable 设计。现代应用：体积可控、类型友好、无原型污染，适合现代构建与 tree-shaking 友好的工程。

date-fns 的核心是"纯函数 + 模块化 + tree-shakable"，是现代工程的首选之一。

• 维护模式的原因
• 体积与不可变性
• 迁移建议

Moment.js 官方已宣布进入维护模式（不再新增功能，仅修 bug），原因是其体积大、API 可变性问题、不可 tree-shake、且原生 Intl 与现代库已覆盖其功能。维护模式意味着不推荐新项目使用。迁移建议：现代项目用 Day.js（兼容 API 平滑迁移）、date-fns（函数式）或 Luxon（不可变、时区强）。遗留项目需评估迁移成本。

Moment 因体积与设计问题进入维护模式，官方建议新项目用现代替代库。

• 插件按需加载
• utc/timezone 时区
• customParseFormat 解析

dayjs 通过插件扩展功能，用 dayjs.extend(plugin) 按需加载。utc 插件提供 UTC 模式，timezone 插件提供 IANA 时区转换（.tz()），customParseFormat 允许自定义解析格式（dayjs(str, format)）。工程价值：按需引入避免体积膨胀，核心保持轻量，需要时再扩展时区与自定义解析。

plugin 机制让 dayjs 核心轻量、能力按需扩展，是控制体积与功能平衡的关键。

• FP 纯函数与 currying
• OO 方法链
• 选型

date-fns 用纯函数（format(date, 'yyyy')，数据在参数），FP 子模块支持 currying 与数据最后参数，便于组合。dayjs/luxon 用 OO 方法链（dayjs().add(1,'d').format()），状态封装在对象中。差异：FP 无状态、可组合、易测试；OO 链式直观、读起来像自然语言。选型看团队偏好：FP 适合函数式风格与组合，OO 适合直观链式。

FP（纯函数、可组合）与 OO（状态封装、链式）是两种编程范式在日期库的体现。

• 不可变设计
• IANA 时区支持
• 现代 API

Luxon 用不可变对象（DateTime），所有操作返回新对象，避免副作用；原生支持 IANA 时区（setZone('Asia/Shanghai')）、DST 与 Intl 集成。企业应用价值：不可变性减少共享状态 bug，时区处理准确（跨时区调度、国际业务），API 现代化（ISO 解析、Duration）。适合对时区敏感的企业级应用。

Luxon 的不可变 + IANA 时区强支持，是企业级时区与国际化场景的优质选择。

• IANA 时区命名
• DST 规则
• 时区转换

IANA 时区数据库（如 America/New_York、Asia/Shanghai）以地区命名时区，包含历史与 DST 规则。DST 处理的关键是：特定时区特定日期有 gap（时钟前跳）与 overlap（时钟回拨），转换需基于 IANA 规则而非固定偏移。Luxon/Temporal 等库用 IANA 规则正确处理 DST。工程价值：国际业务用 IANA 时区而非固定 offset，避免 DST 错误。

DST 的 gap/overlap 需 IANA 规则处理，固定偏移会出错，现代库保证正确转换。

• 后端统一 UTC 存储
• ISO 8601 传输
• 客户端本地化与时区列表

最佳实践：后端统一以 UTC 存储时间，用 ISO 8601 字符串传输（含时区偏移），客户端用 Intl.DateTimeFormat 按用户本地时区格式化展示。Intl.supportedValuesOf('timeZone') 可获取运行时支持的时区列表，用于用户时区选择。这样保证存储、传输、展示三层纪律清晰：存储 UTC、传输 ISO、展示本地化。

"存储 UTC、传输 ISO、展示本地化"是跨时区系统的黄金规则，配合 Intl 本地化。

• 私有 npm registry
• 设计令牌分发
• 版本管理

内部组件库用私有 npm registry（Verdaccio/Nexus 或平台私有包）发布组件包，设计令牌作为独立包或依赖分发，供各项目引用。工程价值：组件与令牌统一源头、版本管理、跨项目复用；令牌包与主题解耦，支持多品牌。需管理发布流程、权限、变更记录与版本语义。

私有 registry（npm 包）承载组件与令牌，实现跨项目统一与版本治理。

• 相对时间格式化
• 多语言
• 无依赖

Intl.RelativeTimeFormat 用原生 API 格式化相对时间（"3 分钟前"、"2 小时后"），支持多语言（zh、en 等）与数字精度。工程价值：无需日期库即可实现"时间相隔"显示，语言本地化由浏览器处理，零依赖、体积小。适合时间线、消息、日志等场景。

Intl.RelativeTimeFormat 提供本地化的相对时间，替代手写"x 分钟前"逻辑。

• 日期/数字本地化
• 多语言
• 零依赖

Intl.DateTimeFormat 格式化日期时间（按语言、时区、年/月/日组合），Intl.NumberFormat 格式化数字（货币、百分比、小数位、千分位）。二者按 locale 自动本地化，工程价值：无需 i18n 库或手写格式，实现多语言、货币、日期统一，体积零依赖。是国际化格式的标准基础。

Intl 提供原生本地化日期与数字，覆盖大部分国际化格式需求。

• Date 的缺陷
• Temporal 的类型化
• 不可变与准确性

Date 存在解析不一、可变、月份 0 索引、时区混乱等缺陷。Temporal 以类型化（PlainDate/PlainDateTime/ZonedDateTime/Instant）、不可变、显式时区、正确的 DST 处理替代 Date，消除时区与偏移 bug。大型项目价值：时间类型清晰、不可变减少共享状态问题、跨时区准确，提升时间处理的健壮性与可维护性。Temporal 已纳入 ES2026（Stage 4），可用 polyfill。

Temporal 用类型化 + 不可变 + 显式时区解决 Date 的缺陷，是大型项目时间处理的升级。

• 时长格式化
• 相对时间格式化
• 多语言

Intl.DurationFormat 格式化时长（如"1 小时 30 分"），Intl.RelativeTimeFormat 格式化相对时间（"3 分钟前"）。二者按 locale 本地化、零依赖。工程价值：视频时长、订单时长、倒计时等展示多语言统一，无需手写或依赖库。配合使用覆盖"时长展示"与"相对时间"两类常见格式化。

DurationFormat 与 RelativeTimeFormat 分别管时长与相对时间，Intl 原生本地化。

• 获取用户时区
• 精确到地区
• 无需 DST 计算

Intl.DateTimeFormat().resolvedOptions().timeZone 返回用户设备时区（IANA 名，如 Asia/Shanghai），是获取客户端时区的标准方式。工程边界：它返回时区标识而非固定偏移，DST 由浏览器按规则处理；无法区分同 IANA 时区内的细分（如中国无夏令时但某些地区有）。用于记录用户时区时需要传递该值，而不是依赖设备本地设置。

该方法给出 IANA 时区标识，适合存储与换算，但需注意其语义与边界。

• 类型化类型
• 不可变
• 显式时区

Temporal 提供 PlainDate/PlainDateTime/PlainTime/ZonedDateTime/Instant/Duration 等类型化类型，均不可变，操作返回新对象。相比 Date：Date 解析可变、时区隐式、月份 0 索引；Temporal 解析可靠、时区显式、字段自然。Temporal 显式区分"日历日期"与"时间点"，正确处理 DST。已纳入 ES2026，可用 @js-temporal/polyfill 在旧环境使用。

Temporal 以类型化、不可变、显式时区解决 Date 的固有缺陷，是时间 API 的现代替代。

• 标准阶段与兼容性
• polyfill 依赖
• 生态迁移

Temporal 虽已纳入 ES2026（Stage 4），但运行时原生支持尚不普及，需 polyfill（@js-temporal/polyfill）替代，且大型项目全面迁移需改造大量代码。因此不能宣称"已稳定替代 Date"：它仍处于落地早期，需依赖 polyfill 与兼容处理，生态工具（日期库、框架）集成也待完善。应标注为"标准已定、原生支持逐步推出"，按需评估迁移。

标准虽定，但原生支持与生态迁移未完成，需如实标注其落地状态，避免夸大。

• 私有 registry 部署
• 版本语义化
• 发布与消费

企业私有 registry 用 Verdaccio/Nexus 或云厂商私有包部署，发布内部 npm 包，配 .npmrc 指向私有源。版本管理遵循语义化版本（SemVer），不兼容变更升 major，涉及多包用 workspace 或 changesets 管理版本与 changelog。工程价值：内部包统一管理、权限控制、发布自动化，避免依赖公共源。

私有 registry = 私有源 + SemVer + 发布流程，实现内部包可控分发。

• 定制边界
• 主题覆盖
• 维护成本

使用第三方组件库需界定边界：优先用库提供的主题/令牌机制定制，避免直接改源码（升级会丢失）；用 CSS 变量覆盖主题，用 wrapper 封装扩展而非 fork。平衡：过度定制增加维护成本（升级冲突），应把"通用能力"交给库、"业务扩展"封装在 wrapper。维护成本上，尽量跟随库版本，减少本地 fork，可通过锁版本与升级测试管理。

边界原则是"用库的扩展点，不碰库源码"，把定制收敛到 wrapper 与主题变量，平衡定制与升级。

• 源码所有权
• 维护成本
• 团队能力要求

shadcn/ui 把组件源码复制进项目，可维护性取决于团队：优点是源码可控、可定制、无依赖锁定；缺点是需自行维护升级（重新 add 拉新版）、保证一致性、处理多项目同步。评估团队能力：需具备 Tailwind/CSS 变量/组件工程能力，能处理升级 diff 与 fork 维护。适合有维护能力的团队，否则升级与一致性会成为负担。

shadcn 的可维护性是把双刃剑：所有权高但维护责任转移给团队，需评估团队能力。

• CN Registry 社区分发
• 私有 fork 团队定制
• 多团队协作

CN Registry（shadcn 社区 registry）提供丰富的第三方组件，可 npx shadcn add 按需引入。私有 fork 是团队自建 registry/组件库，承载内部定制组件与设计令牌。多团队工程价值：CN Registry 补充通用组件，私有 fork 保证品牌与规范统一、组件可跨团队复用；通过 registry 元数据分发，团队按需安装、可定制源码。

CN 社区源补通用能力，私有 fork 管内部规范化，二者结合支撑多团队组件工程。

• 组件中心化
• 独立版本与依赖
• 跨项目复用

Bit.dev 提供组件中心（component hub），组件可独立版本化、独立依赖、跨项目复用，支持从源码直接发布组件并跟踪依赖图。大型团队价值：组件级协作（而非应用级）、独立版本治理、跨项目共享统一组件，配合 Scope 与版本管理实现组件化开发。它比 monorepo 更细粒度。

Bit 把组件作为一等公民独立版本与分发，适合组件驱动的大型团队。

• 源码所有权
• 无版本锁定
• 自定义

"分发但属于你"指 shadcn 把组件源码分发给你，但源码一旦复制进项目即归项目所有，不绑定 shadcn 版本，可任意修改。它不同于 npm 依赖（有版本锁定与升级语义），shadcn 没有"版本"概念，升级靠重新 add 拉新拷贝。工程价值：完全所有权、自由定制、无依赖包袱；代价是需自行维护升级与一致性。

copy-paste 模式让组件"属于你"，无版本锁定，换取所有权与定制，转移维护责任。

• 私有 registry 分发
• 组件与主题打包
• 多团队协作

shadcn registry 协议让团队自建私有注册表，把组件、设计令牌、主题、依赖以元数据形式分发，多团队通过 npx shadcn add 从私有源安装。现代价值：组件与主题按需源码分发、可定制、与设计系统统一；多团队共享组件库与令牌，避免重复实现；元数据驱动、可版本化、CI 友好。支撑企业级组件治理。

私有 registry 协议把"组件 + 主题 + 依赖"元数据化分发，是多团队组件治理的现代方案。

• 替换 Date 的收益
• 原生支持与 polyfill
• 迁移成本

Temporal 以类型化、不可变、显式时区解决 Date 缺陷，收益是时间处理更准确健壮。但现代取舍：原生运行时支持未普及，需 polyfill（@js-temporal/polyfill）增加体积；完全替换需改造现有代码与依赖（日期库、组件）。工程上建议在新代码或新项目采用 Temporal，遗留代码渐进迁移，评估 polyfill 体积与运维成本。

替换是"收益 vs 兼容/迁移成本"的权衡，宜渐进采用而非一刀切。

• 私有 registry 配置
• monorepo 多包安装
• 安装位置与样式

npx shadcn add 支持 --registry 指向私有源，从私有 registry 拉取组件。monorepo 协作边界：组件通常安装到 packages/ui，需通过 components.json 指定路径与别名；多个应用共享时，安装到 ui 包再由各应用消费。边界是 CLI 只负责拷贝源码与配置，样式扫描、依赖共享、构建集成需工程自行处理（如 Tailwind @source 扫描 ui 包）。

shadcn add 管"拷贝到指定位置"，monorepo 的共享与样式集成需工程配置配合。

• CVA 变体管理
• tailwind-merge 冲突
• 品牌令牌

企业定制用 CVA（Class Variance Authority）管理组件变体（size、variant），用 tailwind-merge 合并冲突类，配合 CSS 变量承载品牌令牌。做法：在 shadcn 模板基础上，用 CVA 定义品牌变体，tailwind-merge 保证覆盖正确，品牌色/圆角用 CSS 变量切换。工程价值：组件变体灵活、定制可控、品牌主题统一。

CVA 管变体、tailwind-merge 管冲突、CSS 变量管品牌，构成企业定制的基础。

• CSS 变量主题
• 多品牌切换
• 暗黑模式

shadcn 模板的 globals.css 集中定义 CSS 变量主题（语义色、圆角），通过作用域覆盖实现多品牌与暗黑：:root 默认、.dark 暗黑、:root[data-theme='brand'] 品牌。价值：主题单点定义、多品牌/多主题通过变量切换、组件类名不变，与 Tailwind 工具类无缝集成。是现代主题系统的简洁实现。

globals.css 的 CSS 变量 + 作用域覆盖，支撑多品牌与暗黑模式，主题与组件解耦。

• @theme 映射令牌
• CSS 变量切换
• 企业多主题

Tailwind v4 下 shadcn 用 @theme inline 把 CSS 变量映射为工具类，企业主题切换通过在不同作用域覆盖 CSS 变量实现，工具类不变。价值：令牌定义在 CSS 层、可运行时切换、多主题/暗黑支持，工具类与令牌解耦，切换只改变量、性能好。适合企业级多品牌与主题切换。

@theme 映射 + CSS 变量覆盖实现企业级主题切换，令牌与类解耦、切换高效。

• pnpm workspaces 管理包
• Turborepo 任务编排
• 组件共享

在 pnpm workspaces 的 monorepo 中，shadcn 组件放 packages/ui，通过 pnpm link 被应用消费；Turborepo 管理构建、Lint、测试任务的流水线与缓存。工程价值：组件单一来源、依赖高效安装（pnpm 硬链接）、任务并行与缓存（Turborepo）加速 CI。需处理 Tailwind 样式扫描与 ui 包的构建。

pnpm workspaces 管包、Turborepo 管任务，shadcn 组件作为 workspace 包共享。

• Lucide 图标集
• 自定义 SVG
• 取舍

shadcn 默认用 Lucide（lucide-react）图标，风格统一、按需引入（tree-shakable）、MIT 许可。取舍：用 Lucide 快、一致、体积可控；自定义 SVG 体系更适合品牌专属图标、需要设计团队维护、可完全控制。工程上基础沿用 Lucide，品牌图标用自定义 SVG 覆盖，或按需求构建图标库。

Lucide 省事一致，自定义 SVG 品牌可控，按品牌需求与团队资源取舍。

• registry.json 定义组件元数据
• 与 OpenAPI 的差异
• 组件分发

registry.json 的 schema 描述组件（名称、文件、依赖、样式、registry 源），是组件分发协议；OpenAPI 描述 HTTP API。差异：registry.json 面向"组件源码安装"，OpenAPI 面向"接口契约"。但 registry.json 的 schema 化与 OpenAPI 类似，让组件元数据可被工具（CLI）机器读取、校验、版本化，是组件分发自动化的基础。

registry.json 用 schema 描述组件元数据，其"机器可读"理念与 OpenAPI 一致，但对象不同。

• Storybook 展示组件
• Histoire 的 Vue 替代
• 文档与测试

shadcn/ui 的组件是源码，可直接在 Storybook（React）中编写 stories 展示，Storybook 8/9 支持 args、controls、play 测试、a11y。Vue 场景用 Histoire（Vue 的 Storybook 替代）展示 shadcn-vue 组件。工程价值：组件文档化、交互演示、回归测试，与源码组件无缝集成，是 shadcn 组件库文档化的常见方式。

源码组件可直接接入 Storybook/Histoire 做文档与测试，无特殊集成障碍。

• RHF 与 Zod 集成
• 封装组件
• 边界

shadcn 的 Form 封装 RHF + zod，提供 FormField/FormItem 等，处理受控、校验、错误展示。边界：它封装了"表单逻辑 + UI 样式"，但复杂业务（多步、动态字段、跨字段校验）仍由 RHF API 与 zod schema 承担，shadcn 主要负责 UI 与基础绑定。适合大部分 CRUD 表单，复杂场景需结合 RHF 高级能力。

shadcn Form 封装基础绑定与 UI，复杂校验逻辑仍由 RHF + zod 处理。

• TanStack Table 逻辑
• 分页/排序/筛选
• 边界

shadcn Data Table 用 TanStack Table 管理排序、筛选、分页、列状态，shadcn 组件渲染。边界：shadcn 提供基础 Table 样式与 hooks 集成模板，但服务端分页、虚拟化、复杂列交互、性能优化需工程用 TanStack Table 能力实现。适合大型 CRUD，但需自行处理服务端数据与表现层优化。

shadcn 提供表格 UI 与集成模板，数据逻辑与性能优化落在 TanStack Table 与工程。

• RSC 的服务端/客户端分配
• shadcn 组件需要客户端交互
• 边界

shadcn 组件大多含交互（表单、弹窗、onClick），需标记为客户端组件（'use client'），不能作为 Server Component 直接使用。RSC 模式下边界：共享 UI 结构可用 RSC，交互组件用 client 组件；shadcn 组件在 RSC 中需通过 client 包装或使用 headless 分离。数据获取在服务端，交互在客户端。

RSC 模式下，shadcn 交互组件须为 client 组件，服务端负责渲染与数据，边界清晰。

• Instant 表示绝对时间点
• 与 Date.now 对比
• 精度

Temporal.Instant 表示绝对时间点（UTC，纳秒精度），与 Date.now 的毫秒相比精度更高、语义更明确。工程价值：Instant 用于记录时间戳、排序、跨时区比较，语义清晰（无时区混淆）；Date.now 返回毫秒自 epoch。高精度场景（日志、性能、金融）用 Instant，普通场景 Date.now 也够。

Instant 提供更高精度与明确语义，Date.now 简单，按精度需求选择。

• 国际化日期类型
• 日历系统
• React Aria 集成

@internationalized/date 提供国际化日期类型（CalendarDate、ZonedDateTime、CalendarDateTime），支持不同日历系统（Gregorian、Islamic 等）与时区，是 React Aria 的日期基础设施。工程价值：日历组件（date picker）的类型与计算国际化正确、支持多日历、时区处理一致，配合 React Aria 构建可访问的日期选择器。

@internationalized/date 提供跨日历、跨时区的日期类型，是国际化日期组件的基础。

• 日期选择器库
• 可访问性
• 国际化

react-day-picker 提供轻量日期选择器，支持范围、多选、禁用日期；react-aria-components 的 DatePicker 提供可访问、可定制的日期选择器，与 @internationalized/date 集成。工程应用：按需选择——react-day-picker 简单、react-aria 可访问性强、定制深。价值：无需自建日期选择器，涵盖范围选择、国际化、键盘导航。

成熟日期选择器库（react-day-picker / react-aria）提供可访问、国际化的日期选择，避免自建。

• Duration 类型
• Humanize 时长
• 国际化

Luxon 的 Duration 表示时间跨度（如 2 小时 30 分），可进行算术、格式化；配合 Intl 或 Luxon 的 toHuman 可按语言展示（"2 小时 30 分"）。工程价值：时差、时长、倒计时展示统一，支持多语言与不可变运算，适合国际业务的时间差展示。

Duration 承载时长，toHuman/humanize 本地化展示，是时差展示的工程基础。

• RFC 5545 RRULE
• 重复事件计算
• 日历集成

rrule.js 实现 RFC 5545 的 RRULE 重复规则（如 FREQ=WEEKLY、BYDAY=MON），生成重复事件的具体日期序列。工程应用：日历、提醒、日程系统的重复事件展开，配合 Temporal/Luxon 计算发生时间。它把复杂的重复规则解析与展开标准化，是日历类应用的基础。

rrule.js 处理 RFC 5545 重复规则，是日历重复事件的标准实现。

• polyfill 提供
• 兼容性
• 体积与性能

@js-temporal/polyfill 在原生不支持 Temporal 的环境提供实现，兼容标准 API。工程价值：可在当前浏览器/Node 使用 Temporal，标准稳定后移除 polyfill。代价：增加 bundle 体积、性能略低于原生。需评估体积与性能，渐进采用，或按环境条件加载。

polyfill 桥接标准与运行时，但引入体积与性能成本，需按需权衡。

• 轻量体积
• Moment 兼容 API
• 迁移平滑

Day.js 1.x 约 2KB，核心 API 兼容 Moment（parse/format/diff/add），使从 Moment 迁移平滑。工程价值：遗留项目从 Moment 迁移成本低（API 相似），同时体积大幅减小、tree-shakable；插件化扩展能力。适合需要 Moment 兼容但轻量的迁移场景。

Day.js 以"Moment 兼容 + 轻量"提供平滑迁移路径，是替换 Moment 的首选。

• IANA 时区
• 不可变 API
• 时区转换

Luxon 的 DateTime 不可变，setZone 等操作返回新对象；原生支持 IANA 时区与 DST。工程应用：跨时区调度（fromISO 后 setZone）、国际业务时间、不可变避免共享状态 bug。适合对时区准确性与不可变性要求高的应用。

Luxon 的不可变 + IANA 时区强支持，是时区敏感应用的工程基础。

• 迁移路径
• API 兼容
• 风险

Moment 弃用后迁移路径：Day.js API 高度兼容 Moment，迁移成本最低（改 import 与少量 API）；date-fns 函数式但 API 不同，迁移需重写调用；Luxon 不可变、API 不同。实践：先评估 API 使用面，Day.js 适合快速迁移，date-fns/Luxon 适合顺带重构。注意时区、解析、格式化差异，用测试覆盖。

迁移按 API 兼容度选：Day.js 平滑、date-fns/Luxon 需重构，注意差异与测试。

• 时区工具
• zonedTimeToUtc/utcToZonedTime
• 跨时区

date-fns-tz 为 date-fns 提供时区支持，核心有 zonedTimeToUtc（把某时区时间转 UTC）、utcToZonedTime（UTC 转某时区）、formatInTimeZone 等。实践：跨时区计算用 zonedTimeToUtc 统一转 UTC 再运算，展示用 utcToZonedTime/formatInTimeZone 按用户时区。它让 date-fns 生态具备正确时区处理。

date-fns-tz 补充 date-fns 的时区能力，核心是 UTC 与本地时区双向转换。

• 复数规则
• 多语言
• i18n 协作

Intl.PluralRules 按语言返回复数字类（one/other/few/many 等），用于选择复数形式。i18n 框架（ICU 消息）用它做复数选择（如 "1 item" vs "3 items"）。工程价值：多语言复数正确、零依赖、与 i18n 库协作，是国际化复数的标准基础。

Intl.PluralRules 提供语言复数规则，配合 i18n 框架实现正确复数形式。

• 多日历系统
• 日期类型
• 国际化

@internationalized/date 支持多种日历系统（Gregorian、Islamic、Hebrew、Japanese 等），提供 CalendarDate 等类型，可在不同日历间转换与计算。工程价值：跨日历系统（如穆斯林、希伯来日历）的日期组件正确，国际化日期处理统一，配合 React Aria 构建可访问日历组件。

@internationalized/date 以类型化日期支持多日历，是跨日历国际化组件的基础。

• ICU 消息格式
• React-Intl 集成
• 取舍

FormatJS 是 i18n 库，React-Intl 是其 React 封装，用 ICU MessageFormat 定义消息（含复数、选择、插值）。工程价值：多语言消息结构化、复数/选择/日期本地化、React 组件集成。取舍：ICU 消息功能强但格式较复杂、需工具链；轻量场景可用简单 key-value 或 Intl。适合需要复数/性别/嵌套的中大型国际化。

ICU 消息格式强但复杂，按国际化复杂度选择 FormatJS 或轻量方案。

• IANA 时区命名
• Temporal/Luxon 集成
• DST 处理

IANA 时区数据库（America/New_York、Asia/Shanghai）以地区命名，含 DST 规则。Temporal 与 Luxon 原生支持 IANA 时区，setZone/withTimeZone 按 IANA 规则转换，正确处理 DST。现代工程价值：跨时区业务用 IANA 时区而非固定偏移，Temporal/Luxon 保证 DST 正确，是新代码的标准做法。

IANA 时区 + Temporal/Luxon 集成，保证跨时区转换与 DST 正确。

• Instant 绝对时间点
• ZonedDateTime 带时区
• 取舍

Temporal.Instant 表示绝对时间点（UTC），与用户时区无关；ZonedDateTime 表示某时区带日历的本地时间。取舍：存储/传输用 Instant（无歧义），面向用户展示/计算用 ZonedDateTime（按用户时区）。跨时区协作：后端存 Instant，前端按用户时区转 ZonedDateTime 展示，二者可互转。分离"绝对时间"与"本地表示"。

Instant 管绝对时间、ZonedDateTime 管本地表示，协作时清晰分离，避免时区混淆。

• Intl 本地化
• 库的功能
• 边界

Intl.DateTimeFormat 原生按 locale（'en-US'/'zh-CN'）格式化日期时间，多语言、零依赖，适合展示格式化。date-fns/Luxon 提供解析、运算、不可变、链式等 Intl 没有的能力。边界：纯展示用 Intl；需要解析/运算/时区转换/自定义格式用库。现代库底层也常用 Intl 做本地化，二者互补。

Intl 管本地化展示，库管解析运算，边界清晰、互补。

• fromISO 解析
• setZone 时区转换
• 跨时区调度

DateTime.fromISO 解析 ISO 字符串，setZone 转换到指定 IANA 时区，正确处理 DST。跨时区调度价值：把存储的 UTC 时间转成用户时区，或把用户输入转成 UTC 存储，进行时区换算与调度。配合 DST 正确处理，适合会议调度、国际业务等。

fromISO + setZone 提供可靠的时区转换，是跨时区调度的核心操作。

• 时区转换
• 与 date-fns 配合
• 边界

date-fns-tz 为 date-fns 补时区能力：zonedTimeToUtc 把某时区时间转 UTC，utcToZonedTime 把 UTC 转某时区，formatInTimeZone 按时区格式化。边界：date-fns 本身无时区，date-fns-tz 挂接时区转换，运算仍用 date-fns 纯函数。它让 date-fns 生态能处理跨时区，但需正确理解转换方向。

date-fns-tz 补时区转换，date-fns 管运算，二者配合实现跨时区处理。

• Intl 日历支持
• @internationalized/date
• 转换

Intl.DateTimeFormat 支持 calendar 选项（gregory、islamic、hebrew、japanese），按日历显示日期。@internationalized/date 提供多日历类型与转换。工程价值：面向特定文化（穆斯林、希伯来、日本）的应用用对应日历显示，日期的内部存储仍用公历，展示时转换。满足跨文化日历需求。

不同日历通过 Intl 或库在展示层转换，内部存储统一公历，是国际化日历的原则。

• DST gap/overlap
• 前端转换
• 边界

DST 转换产生 gap（时钟前跳，某时间段不存在）与 overlap（时钟回拨，某时间段重复）。前端处理边界：正确转换需基于 IANA 规则（Temporal/Luxon 处理），不能手写固定偏移；gap/overlap 时如何选择（如 overlap 取第一次或第二次）需明确。前端应依赖库的 DST 处理，避免自行实现，并注意边界时间的展示。

DST 的 gap/overlap 需 IANA 规则库处理，前端勿手写偏移，明确 overlap 选择策略。

• Day.js 插件式
• Luxon 内置
• 简洁度

Day.js 的 timezone 需引入插件（dayjs.extend(timezone)），其 API 用 .tz() 转换，简洁但依赖插件与 IANA 数据。Luxon 内置时区（setZone），无需插件，API 更统一、不可变。取舍：Day.js 轻量但时区插件需加载、API 相对简单；Luxon 时区内置、完整但体积更大。按轻量/时区强度与 API 偏好选择。

Day.js 插件化轻量、Luxon 内置统一，时区场景 Luxon 更完整。

• 两种格式
• 传输
• 边界

ISO 8601 是日期时间标准格式，RFC 3339 是 ISO 8601 的受限子集（面向 Internet 应用，如 '2024-01-01T12:00:00Z'）。API 通信边界：统一用 ISO 8601/RFC 3339 字符串传输时间，带时区偏移（Z 或 +08:00），后端存 UTC，避免歧义。前端用 Date.parse 或库解析。边界的核心是"存储 UTC、传输带偏移的 ISO、展示本地化"。

传输用 ISO/RFC 3339 带偏移，避免时间歧义，是 API 时间通信的纪律。

• 交易日历
• 业务日计算
• 边界

Temporal 提供日期运算（add、until），可计算自然日天数。但金融交易日历（排除节假日、特定市场休市）需业务规则，Temporal 不内置交易日历，需结合节假日数据（如金融日历库）计算。边界：Temporal 管日期运算与日历，业务日/交易日需业务配置与数据。工程上可用 Temporal 的日差 + 节假日表实现。

Temporal 提供日期运算基础，交易日/业务日需工程叠加节假日规则。

• 数字本地化
• 金融精度
• 边界

Intl.NumberFormat 按 locale 格式化数字（货币、千分位、小数位），用于展示。金融数据边界：格式化用 Intl，但计算精度需用定点/十进制（如 BigInt/库），避免浮点误差；Intl 只负责展示不负责计算。实践：存储/计算用高精度类型，展示用 Intl.NumberFormat 按 locale 格式化，二者分离。

Intl 管展示本地化，金融计算需高精度类型，避免浮点误差，职责分离。

• 动态字段数组
• 增删改
• 性能

useFieldArray 管理动态字段数组（增删改、重排），提供 append/remove/insert 等，字段名以 index 生成，与 RHF 状态集成。性能上按字段注册、避免整表重渲染。工程价值：订单/发票等动态行表单高效，字段操作与校验、错误管理统一，配合 Controller 处理受控组件。

useFieldArray 让动态字段数组的增删改与校验统一，是动态表单的核心。

• RHF 非受控
• TanStack Form 受控
• 取舍

RHF 默认非受控（用 ref 注册输入，减少重渲染），性能好；TanStack Form 默认受控（用 Store 订阅字段），类型安全强、状态可预测。取舍：RHF 非受控性能优、生态成熟、与 zod 集成好；TanStack Form 受控类型安全、字段级订阅、现代 API。按性能敏感度与类型安全偏好选择。

RHF 非受控重性能，TanStack Form 受控重类型与可预测，按需求取舍。

• 字段数组
• 动态字段
• 大型表单

TanStack Form 支持字段数组（form.useFieldArray 或 field 的数组），动态增删字段，且类型安全（字段值类型推导）。大型表单应用：字段级订阅避免整表重渲染、类型安全减少错误、与 zod 校验集成。配合 Form 的 store 机制，动态字段与复杂表单状态管理高效。

TanStack Form 的字段数组 + 类型安全 + 细粒度订阅，适合大型动态表单。

• 受控模式
• 性能
• 现状

Formik 早期主流，采用受控模式（值存 state），API 直观但每字段变化触发整表重渲染，性能与大型表单有短板。现代取舍：RHF（非受控）与 TanStack Form（受控优化）在性能与类型上更优，Formik 生态增量少。新项目倾向 RHF/TanStack Form，遗留项目可继续，但增长有限。取舍关注性能与类型安全。

Formik 受控直观但性能受限，现代库在性能与类型上更优，属维护方向。

• locale 参数
• 多语言
• 日历

date-fns 通过 locale 参数支持多语言，如 format(date, 'PPPP', { locale: zhCN }) 输出中文格式。工程实践：多语言日历按当前语言选择 locale，格式化月份、星期、日期显示。它让日期格式本地化，无需手写映射。配合 Intl 或 i18n 框架统一语言。

date-fns 的 locale 参数让格式化本地化，是多语言日历的基础。

• ISO 解析
• 时区
• 应用

DateTime.fromISO 解析 ISO 8601 字符串，保真时区信息（含偏移），可后续 setZone 转换。现代应用：解析 API 返回的 ISO 时间，按用户时区展示，或转换存储。它提供可靠解析、正确处理偏移与 DST，是跨时区应用解析的标准入口。

fromISO 可靠解析 ISO 并保留时区，配合 setZone 实现跨时区应用。

• Duration 类型
• 时长运算
• 展示

Luxon 的 Duration 表示时长（小时、分钟、秒），可运算（add/mapUnits）、转换（toFormat/toHuman）。工程应用：视频时长、订单处理时长、倒计时的计算与展示，toHuman 按语言展示。它提供不可变、精确的时长运算，避免手写毫秒换算。

Duration 封装时长单位与运算，统一视频/订单等时长的计算与展示。

• 范围判断
• 插件
• 应用

Day.js 的 isSameOrAfter、isSameOrBefore、isBetween 插件提供日期比较与范围判断。工程应用：判断日期是否在范围内、是否过期、日历/筛选的边界判断。它们以插件提供，简洁直观。适合日期范围校验、日程筛选等场景。

isSameOrAfter/isBetween 等插件简化日期范围判断，是日历/筛选的基础。

• 周末配置
• 地区差异
• 应用

Luxon 的 Info.weekendDays 返回指定地区（locale）的周末星期（如某些地区周末是周五六）。工程价值：不同地区周末不同，用 Info.weekendDays 按 locale 判断周末，正确处理业务（如营业日、排班）。避免硬编码周末为周六日。

Info.weekendDays 按 locale 提供周末配置，是地区差异的正确处理。

• Duration 时长
• 算术
• 边界

Temporal.Duration 表示时长，支持 add/subtract/round 等算术，可存储日期与时间部分。现代边界：Duration 算术精确处理日历日（天）与时间（小时）混合，round 处理舍入与 DST 相关。但业务时长（如工作日）需结合业务规则。Temporal.Duration 提供不可变、精确的时长运算基础。

Duration 提供精确时长算术，业务语义（工作日等）需工程叠加。

• parseISO 解析 ISO
• parse 自定义格式
• 取舍

date-fns 的 parseISO 解析 ISO 8601 字符串（'2024-01-01'），parse 按自定义格式解析（parse(str, 'dd/MM/yyyy', ref)）。取舍：parseISO 简单、适合 ISO 标准输入；parse 灵活、适合非标准格式但需指定格式与参考日期。工程上优先 ISO + parseISO，非标准输入用 parse 并明确格式。

parseISO 管标准 ISO，parse 管自定义格式，按输入格式选择。

• locale 加载
• 中文格式
• 应用

Day.js 通过 locale('zh-cn') 加载中文语言包，格式化中文日期（如星期、月份中文）。工程应用：中文应用按语言加载 locale，格式化日期显示本地化。配合插件（相对时间、日历）输出中文。它让中文日期展示统一、无需手写映射。

locale 加载让 Day.js 输出中文日期，是中文日期本地化的基础。

• immutable
• tree-shake
• 对比 Moment

date-fns v4+ 采用不可变设计（函数不修改参数）、纯函数模块化、天然 tree-shake（只打包用到的函数）。对比 Moment：Moment 可变、不可 tree-shake、体积大。现代取舍：date-fns 体积可控、可组合、类型友好，适合现代构建；Moment 已维护模式。新项目偏好 date-fns 等现代库。

date-fns 的 immutable + tree-shake 优势明显，是其替代 Moment 的现代价值。

• 渐进增强
• Remix 集成
• 边界

Conform 是 Remix 的表单库，采用渐进增强：无 JS 时表单通过原生 POST 提交，有 JS 时增强为客户端校验与交互。边界：Conform 依赖 Remix 的 action/loader 与原生表单语义，适合 Remix 全栈；传统 SPA 用 RHF 等客户端库。渐进增强模式在无 JS 环境仍可用，但复杂度高，适合 Remix 项目。

Conform 的渐进增强依赖 Remix 原生表单，SPA 用客户端表单库，边界按框架。

• Formik 受控性能
• RHF 非受控
• Angular Signals

Formik 2 受控模式每字段变化触发整表重渲染，性能差；RHF v8+ 非受控 + 字段订阅，性能优。Angular Forms 传统适用，Angular Signals Forms 用 signal 响应式、更高效。工程取舍：React 生态 RHF 性能与类型优；Angular 用 Signals Forms 现代高效。按框架与性能敏感度选型。

RHF 非受控性能优，Angular Signals Forms 现代高效，均优于早期受控方式。

• 受控性能
• 大型表单
• 替代

Formik 受控模式在大型表单中每字段变化整表重渲染，性能瓶颈；且类型安全较弱、生态增量少。RHF 非受控 + 字段订阅 + 类型强，逐渐替代。取舍：遗留 Formik 可继续，新项目与大型表单用 RHF/TanStack Form。除非有强历史依赖，否则迁移到现代库。

Formik 受控性能与类型短板使其在大型表单被 RHF 取代，属维护方向。

• 表单 Action
• useActionState
• 服务端集成

React 19 引入表单 Action（

表单 Action + useActionState 让提交状态与处理原生化，简化表单与并发。

• 类型安全
• 现代 API
• 字段级订阅

TanStack Form 表单状态强类型，字段值、校验器类型推导，配合 zod 单一来源。现代 API：useForm + useStore 字段级订阅、validators 按需时机、框架无关。工程价值：类型安全减少错误、细粒度订阅提升性能、现代声明式 API。适合类型安全优先的现代表单。

TanStack Form 以类型安全 + 字段级订阅 + 现代 API 见长，是现代表单库。

• 暴露命令式 API
• 焦点管理
• 可访问性

useImperativeHandle 配合 forwardRef 暴露组件的命令式方法（如 focus、scroll）。国际化/可访问性价值：暴露 focus 方法用于错误焦点管理、表单验证后聚焦错误字段、组合组件（如日期选择器）暴露内部输入焦点。配合 aria-invalid/aria-describedby 提升可访问性。

useImperativeHandle 暴露命令式焦点/操作，辅助可访问性与表单交互。