Carbon Design System v12 迁移指南四大包破坏性变更详解与源码级实现解析【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文基于 Carbon Design SystemIBM 开源设计系统官方的 v12 迁移文档系统梳理从 v11 升级到 v12 时carbon/utilities、carbon/react、carbon/styles和carbon/web-components四个包的消费者影响Temporal polyfill 的自动注入机制、Popover/Tooltip 圆角化与 caret 废弃、Tile 与 RadioTile 图标体系变化、OverflowMenu 组合模型重构、StructuredList 选区指示器迁移、浮动样式动态化以及 Pagination 预览 API 的移除。读完后你可以按包逐一对照自己的应用代码、测试与自定义样式完成迁移审查并通过官方 codemod 自动化大部分 React 侧改造。前置条件Feature Flag 机制与先开启、后迁移策略官方迁移文档 docs/migration/v12.md 的适用前提非常明确它假设 v12 的发布行为已在你的项目中被启用。Carbon 的迁移策略不是大版本发布日一次性破坏而是把所有 v12 破坏性变更封装为enable-v12-*前缀的 feature flag在 v11 期间供消费者提前渐进式开启。因此阅读本文档前需要先理解 flag 体系权威来源为 docs/feature-flags.md以enable-v12-*开头的 flag 表示该特性已承诺进入 v12API 冻结不再变更并将在 v12 中默认开启以enable-v12-release为入口的元 flag 可一次性启用全部enable-v12-*flags从源码结构看所有 flag 在 feature-flags.yml 中均声明为enabled: false即在 v11 发行包中默认关闭行为向后兼容。与 v12 迁移直接相关的 flag 清单如下摘自 docs/feature-flags.md 的 flag 表Flag说明可用包配套 Codemodenable-v12-release启用全部 v12 flagReact、Sass、Web Components—enable-v12-dynamic-floating-styles为 Popover、Tooltip 等组件启用动态浮动样式React、Web Components—enable-v12-overflowmenu启用基于 Menu 子组件的 v12 OverflowMenuReact、Web Components有enable-v12-tile-default-icons为 Tile 组件启用默认图标React、Web Components有enable-v12-tile-radio-icons启用 Tile 组件的新版 radio 图标React、Sass、Web Components有enable-v12-structured-list-visible-iconsStructuredList 中图标组件常显Sass有enable-v12-toggle-reduced-label-spacing缩减 Toggle 控件与标签间距Sass、Web Components—对于有 codemod 的 flag可在项目根目录用carbon/upgrade自动改写代码# 在干净的工作区中运行 npx carbon/upgrade migrate enable-v12-overflowmenu --write变更可通过 git 查看本地未暂存的改动来审查。需要注意v12 的 codemod 默认只覆盖 React 源码Web Components 与 Sass 的迁移目前是手工的详见 carbon/upgrade 文档。理论上如果你在 v12 发布前已在项目中开启全部enable-v12-*flags升级到 v12 时受影响组件将无需再做任何改动——这正是本文后续各节的组织逻辑逐包列出现有 v12 行为及其消费者影响而非实现历史。carbon/utilitiesdate-picker 的 Temporal polyfill 自动注入问题背景carbon/utilities/date-picker中的日期选择器原语构建于 Temporal API 之上而 Temporal 尚未在所有浏览器中普及没有任何版本的 Safari 实现它Chrome 和 Edge 也要到 144 版本才支持。由于该模块树内所有Temporal.*引用都是裸全局引用在不支持 Temporal 的引擎上第一次访问Temporal.Now.plainDateISO()日历打开转换时触发会抛出ReferenceError日历永远无法打开。注入机制导入carbon/utilities/date-picker现在会在globalThis上安装temporal-polyfill约 20 kB gzip且仅当引擎本身未提供Temporal时才生效——原生实现永远优先。应用代码无需做任何事。源码层面的实现就是入口文件里的一行副作用导入位于任何原语模块之前// packages/utilities/src/date-picker/index.ts节选 /** * temporal-polyfill/global installs globalThis.Temporal only when the engine * does not already provide it, so a native implementation always wins. It is * imported first so the global exists before any primitive can reach for it. */ import temporal-polyfill/global; export * from ./primitives/index.js;见 date-picker 入口。消费者注意事项不要叠加第二个 Temporal polyfill两个实现争夺同一个全局变量是难以诊断的错误来源。如果你的应用已经自己安装了 Temporal polyfill它现在变成冗余依赖可以移除审查打包体积预算polyfill 带来的约 20 kB gzip 增量会经由carbon/react与carbon/web-components的 preview v12 日期选择器传导给下游消费者必须通过carbon/utilities/date-picker入口导入原语直接导入某个原语模块如carbon/utilities/src/date-picker/primitives/...会跳过 polyfill 安装该入口模块头部注释已将其标注为内部使用见 入口注释 与 primitives 文档。仓库中有一个专门的回归测试 temporal-polyfill-test.js它刻意不导入测试用的temporal-mock.js而是全程走date-picker入口验证无原生 Temporal 环境下polyfill 安装成功isTemporalAvailable()为true、从IDLE状态点击日历图标能正常打开日历、月份导航不抛错。这为入口必须先行安装全局这一约定提供了可验证的行为基线。carbon/react组件行为变更Popovercaret属性废弃配合 Popover / Toggletip / Tooltip 的新版 v12 样式见下文 Sass 部分这三个组件的箭头caret被移除因此 React 的caretprop 已废弃在 v12 中caret被强制为false。源码中保留了弃用提示见 Popover 组件Thecaretprop has been deprecated and will be removed in the next major release of Carbon.迁移动作从调用点删除caret属性更新视觉快照。Tile 默认图标ClickableTile在未提供renderIcon时现在默认渲染ArrowRight图标禁用的可点击 tile 则强制使用Error图标覆盖任何消费者自定义图标。组件 API 与交互模型不做其他改变。该行为由enable-v12-tile-default-iconsflag 控制源码实现位于 Tile.tsxconst v12DefaultIcons useFeatureFlag(enable-v12-tile-default-icons); if (v12DefaultIcons) { if (!Icon) { Icon ArrowRight; } if (disabled) { Icon Error; } }注意iconClasses中${prefix}--tile--disabled-icon分支禁用状态不仅换图标还切换了图标类名。相关演示可参考 Tile.featureflag.stories.js。审查重点假定可点击 tile 无尾部图标的布局、快照与测试以及假定禁用 tile 保留自定义图标的用例。AI Label 与装饰器decorator位置调整交互式装饰器包括AILabel现在渲染在原生label和legend元素之外也在可排序表头按钮之外带元素装饰器的ClickableTile会用一个外层包装包裹链接与装饰器确保装饰器不落在链接内部。由此产生一条硬性约束labelText、titleText、legendText、label等标签类属性不得包含交互式内容。帮助触发器、toggletip 和其他交互控件应移到兄弟元素或移入组件的decoratorprop若可用。审查 DOM 选择器、快照与假设装饰器嵌套在 label/legend/表头按钮/可点击 tile 链接内部的测试。RadioTile 图标体系RadioTile改用RadioButton与RadioButtonChecked图标替代CheckmarkFilled。选区指示器在选中与未选中两种状态下均存在其布局由下文 Sass 侧的 tile radio icon 变更控制。React 组件 API 不变。审查自定义图标假定、视觉快照以及此前只在选中态预期有指示器的布局。OverflowMenu 组合模型重构OverflowMenu现在采用基于Menu的实现子项组合从OverflowMenuItem变为MenuItem与MenuItemDivider- OverflowMenu aria-labelActions - OverflowMenuItem itemTextEdit / - OverflowMenuItem hasDivider isDelete itemTextDelete / OverflowMenu labelActions MenuItem labelEdit / MenuItemDivider / MenuItem kinddanger labelDelete / /OverflowMenu属性映射关系项文本itemText→label删除项isDelete→kinddanger分割线hasDivider→ 独立的MenuItemDivider /组件href、disabled、className、onClick等项属性继续可用wrapperClassName被并入className。新版实现位于 OverflowMenu/next 入口从源码可见其直接复用Menu组件并以 Floating UIuseFloating、flip、autoUpdate驱动定位label既用作触发器 tooltip 也用作菜单的可访问标签。enable-v12-overflowmenu是四个拥有 codemod 的 v12 flag 之一建议优先跑 codemod 再人工核对npx carbon/upgrade migrate enable-v12-overflowmenu --write审查重点父级 label、项自定义、wrapper 类名以及依赖旧子项结构的测试与选择器。StructuredList 选区指示器可选中的StructuredListRow现在使用selectionprop并自动在首列渲染 radio 指示器。消费者此前手工添加的CheckmarkFilled单元格不再属于选区模式的一部分。指示器的视觉表现由下文 Sass 侧变更控制。审查可选中行、自定义选区单元格、单元格位置假定与视觉快照。动态浮动样式Floating UI fixed 定位浮动面即使在autoAlign为false时也会使用 Floating UI 的 fixed-position 样式。注意这不等于加入碰撞检测autoAlign仍然同时提供动态定位与碰撞检测。影响范围包括ComboBox、Dropdown、MultiSelect、MenuButton、ComboButton、OverflowMenu以及基于 Popover 的Tooltip与Toggletip面。审查滚动容器、transform 容器与裁剪容器内的浮层以及依赖旧定位上下文的代码。Toggle 标签间距与 Tag 圆角无 API 变更ToggleReact 无组件 API 变更标签文本与控件之间缩减后的间距经由carbon/styles的再导出传入审查依赖旧间距的视觉快照与应用侧覆盖Tag同样无 API 变更。Tag含 dismissible、selectable、operational、skeleton 变体经由carbon/styles再导出获得按尺寸区分的圆角审查依赖旧药丸形状的快照与覆盖。两者对应的 Sass 变更见下文。Pagination 预览 API 移除unstable_Pagination/preview_Pagination与unstable_PageSelector/preview_PageSelector被移除统一使用稳定的Pagination组件。默认页码选择控件已内置省略pageSizes即隐藏每页条数选择器需要自定义页码选择控件时用renderPageSelect替代此前的PageSelector子组件。官方给出的迁移前后对照- import { - unstable_Pagination as Pagination, - unstable_PageSelector as PageSelector, - } from carbon/react; - - Pagination pageSizes{[10, 20, 30]} totalItems{100} - {({ currentPage, onSetPage, totalPages }) ( - PageSelector - currentPage{currentPage} - onChange{(event) onSetPage(event.target.value)} - totalPages{totalPages} - / - )} - /Pagination import { Pagination } from carbon/react; Pagination pageSizes{[10, 20, 30]} totalItems{100} /审查重点import、render-prop 子用法以及针对.cds--unstable-pagination的测试与选择器。carbon/stylesSass 侧视觉变更Popover / Toggletip / Tooltip 圆角Popover 与 Toggletip/Tooltip 的角通过 border-radius token 圆角化Popover 用$border-radius-08Toggletip/Tooltip 用$border-radius-04。每个组件在触发按钮与内容之间新增了 4px 间距caret 被移除。Menu 圆角菜单与菜单项分别通过$border-radius-08与$border-radius-04圆角化菜单内四周有$spacing-02的内边距子菜单位置与危险菜单项的焦点态做了适配性微调。Tile radio 图标radio tile 的选区图标从仅选中态可见变为始终可见布局同时为图标以及 AI 标签/装饰器在 inline-end 方向预留了额外空间。该样式变更同时支撑 React tile 行为 与 Web Components tile 行为。审查两个包中的自定义 tile 内边距、图标可见性覆盖与快照。StructuredList 选区图标选区图标不再在未选中时以透明填充勾选态图标使用 primary 图标色旧版针对末列的宽度与内边距覆盖不再应用。审查自定义末列尺寸、选区图标颜色以及假定指示器占据末列的样式。Toggle 标签间距Toggle 标签文本与控件之间的 block-end 边距从$spacing-05变为$spacing-03同时支撑 React 与 Web Components 两侧。审查两个包中的视觉快照与自定义间距覆盖。Tag 圆角Tag 不再是药丸形小号 tag 用$border-radius-02中号与大号 tag 用$border-radius-04可关闭按钮及其焦点指示器与父 tag 使用相同圆角skeleton tag 遵循同样的按尺寸圆角。审查自定义圆角覆盖与视觉快照。carbon/web-components变更Popovercaret属性废弃与 React 侧一致配合新版 v12 样式caret 被移除caret属性已废弃v12 中强制为false。Tile 默认图标cds-clickable-tile在没有自定义图标时渲染ArrowRighttile 处于禁用态时改渲染Error。交互模型不变。审查假定无尾部图标的布局与视觉测试以及假定禁用 tile 保留自定义图标的用例。Tile radio 图标cds-radio-tile使用空心/勾选 radio 图标替代CheckmarkFilled图标在两种状态下均可见并通过上文 Sass 侧变更为其预留空间。审查自定义图标假定、tile 内边距与期待仅选中态有指示器的视觉快照。OverflowMenu 组合模型重构cds-overflow-menu现在期望一个直接的cds-menu子元素与 menu button / combo button 采用同一组合模型。已废弃的cds-overflow-menu-body与 overflow-menu-item 组合被菜单项与分割线取代cds-overflow-menu labelActions cds-menu cds-menu-item labelEdit/cds-menu-item cds-menu-item-divider/cds-menu-item-divider cds-menu-item kinddanger labelDelete/cds-menu-item /cds-menu /cds-overflow-menu审查子元素组合、菜单 label、项自定义以及依赖已废弃元素的测试与选择器。动态浮动样式Web Components 中该定位变更作用于cds-overflow-menuautoalign为false时Floating UI 应用动态 fixed-position 样式但不含碰撞检测autoalign为true时包含碰撞检测。审查滚动、transform、裁剪容器内的菜单以及依赖旧定位上下文的代码。Toggle 标签间距与 Tag 圆角cds-toggle缩减标签文本与控件间的 block-end 间距与 Sass 变更对齐审查视觉快照与自定义间距覆盖cds-tag、cds-dismissible-tag、cds-selectable-tag、cds-operational-tag、cds-tag-skeleton无 API 变更通过 Sass 侧变更获得按尺寸区分的圆角审查视觉快照与自定义圆角覆盖。迁移执行检查清单综合各节的 Review 提示按包整理出可执行的迁移审查清单依赖与构建层carbon/utilities确认没有自行引入第二个 Temporal polyfill核对打包体积预算中约 20 kB 的 polyfill 增量确认日期选择器相关代码全部经由carbon/utilities/date-picker入口导入。React API 层删除caretprop移除unstable_Pagination/preview_Pagination/PageSelector引用改用稳定PaginationpageSizes/renderPageSelect将OverflowMenuItem组合替换为MenuItem/MenuItemDivider建议运行npx carbon/upgrade migrate enable-v12-overflowmenu --write把 label 类属性中的交互控件移到兄弟元素或decoratorprop。Sass 覆盖层检查针对 tag 药丸形状、toggle 标签间距、menu 内边距/末列尺寸、tile 内边距与 radio 图标可见性的自定义覆盖是否仍然成立。测试与选择器层更新假设 caret 存在、tile 无尾部图标、禁用 tile 保留自定义图标、装饰器嵌套于 label/legend 内、radio 指示器仅选中态可见、.cds--unstable-pagination类名、旧 OverflowMenu 子结构的快照与 DOM 选择器Web Components 侧同步更新对cds-overflow-menu-body等废弃元素的引用。浮层定位层在滚动、transform、裁剪容器内逐一回归ComboBox、Dropdown、MultiSelect、MenuButton、ComboButton、OverflowMenu、Tooltip、Toggletip以及 WC 侧cds-overflow-menu的定位表现。参考文件迁移总览本文主体来源docs/migration/v12.mdFeature flag 权威清单与 codemod 用法docs/feature-flags.md、feature-flags.ymlTemporal polyfill 注入与回归测试date-picker 入口、temporal-polyfill-test.js、primitives 文档Tile 默认图标实现Tile.tsx新版 OverflowMenuMenu 组合 Floating UInext 入口Popovercaret弃用提示Popover 组件Codemod 工具与文档packages/upgrade/README.md【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考