Carbon 设计系统 Feature Flags 完整指南v11 到 v12 渐进式迁移的官方机制【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbonFeature Flags特性开关是 Carbon 设计系统在保持向后兼容的前提下让消费项目以白名单方式逐项体验新行为与新样式、并最终平滑过渡到 v12 的核心机制。本文以仓库权威文档 docs/feature-flags.md 为主体结合carbon/feature-flags包的源码、React/Web Components/Sass 三端接入实现与carbon/upgrade的 codemod 工具链完整覆盖当前全部 flag 清单、命名约定、三端启用方式、底层判定原理与一键迁移实操帮助你理解并规划 Carbon v11 → v12 的升级路径。Feature Flags 是什么Carbon 的各包carbon/react、carbon/web-components、carbon/styles等随版本发布携带一组 feature flags用于开启新行为和新样式。它们的定位是让消费方在当前大版本内按自己的节奏增量接入预览preview变更预览代码的总体策略见 docs/preview-code.md而无需等待下个大版本一次性接收全部破坏性变更。几个关键事实新 flag 引入时默认置为false关闭确保既有用户不受影响、保持向后兼容一个 flag 可以同时存在于 React、Web Components、Sass 中的任意组合部分 flag 配有对应的 codemod自动化代码改写脚本用于加速迁移该文档是flag 名称、包可用性、关联 codemod 的权威来源source of truthcodemod 的详细用法与已知限制见carbon/upgradeREADME。当前全部 Feature Flags 清单除非特别说明下列所有 flag 默认均为false。这是当前仓库中权威的 flag 总表Flag描述可用包Codemodenable-dialog-element启用组件使用原生 dialog 元素React, Sassenable-enhanced-file-uploader启用增强版 FileUploader 回调更丰富的数据与更多触发时机Reactenable-focus-wrap-without-sentinels启用不使用哨兵sentinel节点的新焦点循环行为Reactenable-presence启用组件关闭态保持卸载、打开态才挂载React, Sassenable-tile-contrast启用对比度更佳的 Tile 改进样式Sassenable-treeview-controllable启用新的 TreeView 可控 APIReactenable-v12-dynamic-floating-styles为 Popover、Tooltip 等组件启用浮层样式的动态设置React, Web Componentsenable-v12-overflowmenu启用基于 Menu 子组件的新版 v12 OverflowMenuReact, Web Componentsenable-v12-overflowmenuenable-v12-release一次性启用全部 v12 feature flagsReact, Sass, Web Componentsenable-v12-structured-list-visible-icons让 StructuredList 内的图标组件始终可见Sassenable-v12-structured-list-visible-iconsenable-v12-tile-default-icons为 Tile 组件启用默认图标React, Web Componentsenable-v12-tile-default-iconsenable-v12-tile-radio-icons在 Tile 组件中渲染更新后的单选图标React, Sass, Web Componentsenable-v12-tile-radio-iconsenable-v12-toggle-reduced-label-spacing减小 Toggle 控件与其标签之间的间距Sass, Web Components已废弃 flagenable-experimental-tile-contrast已废弃改用enable-tile-contrastSassenable-experimental-focus-wrap-without-sentinels已废弃改用enable-focus-wrap-without-sentinelsReact清单中的数据与 packages/feature-flags/feature-flags.yml 中定义的 17 个 flag含enable-css-custom-properties、enable-css-grid、enable-v11-release等历史项保持一致其中enable-v12-release在配置文件中默认关闭其余 v12 相关 flag 全部默认关闭。启用 v12 之后看什么启用enable-v12-release后建议通读 docs/migration/v12.md它按包carbon/utilities、carbon/react、carbon/styles、carbon/web-components列出了迁移到 v12 时各包的变更点、跨包关联关系与需要审查的代码区域例如 Popover/Toggletip/Tooltip 的 caret 移除、ClickableTile默认渲染ArrowRight图标等行为差异。Feature Flag 命名约定所有 flag 遵循带状态语义的前缀命名约定这是判断一个 flag 稳定性的第一依据。enable-*前缀待测试的新特性包含希望消费项目试用并提供反馈的新特性一般稳定、不太可能变化但可能根据反馈调整可能需要项目内手动迁移或代码调整记录在 Storybook 中可能未记录在 carbondesignsystem.com 官网上需要用户反馈来确认功能是否满足全部关切。使用这类 flag 时请关注 Carbon 定期 minor 版本发布的 release notes其中会列出相关变更。enable-v#-*前缀已承诺到未来大版本的特性随着某个 flag 使用率上升或判定为高重要性Carbon 会将其承诺进未来的 major 版本并重命名为enable-v#-*前缀例如enable-v12-some-feature。此时该 flag 背后的 API 或功能已固定、不再变化并计划在名称所指的大版本中默认开启。关键设计是所有破坏性变更都会以enable-v12-*flag 的形式在当前 major 版本v11内发布。这使项目可以更早、按自己的节奏选择接入破坏性变更避免升级到下个大版本时一次性承受巨大变更集。理论上如果项目在 v12 发布前启用了全部enable-v12-*flag升级到 v12 时受影响组件就无需再改动。一个 flag 要承诺进大版本并被重命名为enable-v#-*必须满足经过早期采用者测试测试覆盖完整Unit、AVT、VRT在 Storybook 中记录在案在 carbondesignsystem.com 上有文档尽可能提供自动化迁移脚本codemod。底层实现carbon/feature-flags包所有端React/Web Components/Sass的 flag 判定最终都汇聚到独立的carbon/feature-flags包。它的构建脚本 tasks/build.mjs 读取feature-flags.yml作为唯一数据源将其编译生成src/generated/feature-flags.js供 JS 使用的featureFlagInfo数组与基于process.env.CARBON_FLAG_NAME如CARBON_ENABLE_V12_RELEASE环境变量的覆盖逻辑scss/generated/feature-flags.scss供 Sass 使用的$generated-feature-flagsmap。也就是说新增或修改 flag 只需编辑一份 YAMLJS 与 Sass 两端自动同步生成。JS 侧 API入口 src/index.ts 暴露了createScope(flags?)创建独立的作用域实例全局单例FeatureFlags及其绑定方法add、enable、disable、enabled、mergenotifyAvailableFlag用于框架包在无需作用域时也能完成 flag 查找与提示。核心判定逻辑在 src/FeatureFlagScope.ts 的FeatureFlagScope类中add重复添加会抛错enable/disable/enabled对不存在的 flag 会抛错enabled(name)在返回结果前会先判断isV12Flag(name)——若 flag 是 v12 类且enable-v12-release为true则直接返回true。enable-v12-release的总开关机制isV12Flag的实现FeatureFlagScope.ts值得单独说明export const v12ReleaseFlag enable-v12-release; const v12FlagPrefix enable-v12-; // 携带 v12 行为但不带 enable-v12- 前缀的历史 flag const unprefixedV12Flags new Set([enable-focus-wrap-without-sentinels]); export const isV12Flag (name: string) name ! v12ReleaseFlag (name.startsWith(v12FlagPrefix) || unprefixedV12Flags.has(name));即所有enable-v12-*前缀的 flag外加特殊登记的无前缀 flagenable-focus-wrap-without-sentinels都会在enable-v12-release开启时被一并点亮而enable-*普通 flag 与enable-experimental-*废弃 flag 不受总开关影响。这一点在测试 feature-flags-test.js 中有直接验证v12 flag 被总开关点亮、无前缀 v12 flag 被点亮、废弃 experimental flag 不被点亮、v12 flag 也可独立于总开关单独开启。Sass 侧 index.scss 提供了与之必须保持同步的平行实现is-v12-flag()与enabled-by-v12-release()采用同样的前缀规则且同样登记了$unprefixed-v12-flags: enable-focus-wrap-without-sentinels。源码注释明确提醒这两个实现是同一规则的两份代码若不同步会出现JavaScript 有 v12 行为而 Sass 没有或相反的偏差。开发期的 v12 flag 提示src/notify.ts 中的notifyAvailableFlag会在开发环境process.env.NODE_ENV ! production下对已存在但未启用的 v12 flag打印一次console.info提示内容包括 flag 描述并引导开启enable-v12-release一次性点亮所有 v12 flag。它对每个 flag 每个会话只提示一次且对已启用的 flag、非 v12 flag、enable-v12-release自身均保持沉默。框架层如 React 的useFeatureFlag负责在调用点做NODE_ENV守卫因为该包发布时NODE_ENV已被内联。相关行为在 notify 测试用例中均有覆盖。在各框架中启用 Feature FlagsReactFeatureFlags组件与 Hookscarbon/react提供FeatureFlags组件与useFeatureFlag/useFeatureFlagshooks实现在 packages/react/src/components/FeatureFlags/index.tsx。import { FeatureFlags } from carbon/react; FeatureFlags enableV12Release enableDialogElement App / /FeatureFlags组件通过PROP_TO_FLAG映射把 camelCase prop 转换为 kebab-case flag 名enableV12Release→enable-v12-release等。要点只把显式传入非undefined的 prop 写入作用域未指定的 prop 不会遮蔽父级FeatureFlags作用域中的设置这是嵌套作用域的正确行为作用域通过createScope(explicitFlags)创建再以mergeWithScope(parentScope)继承父级值flags对象形式的 prop 已被标记为deprecated官方建议运行featureflag-deprecate-flags-propcodemod 迁移到独立布尔 propuseFeatureFlag(flag)读取当前 context 下的判定结果useFeatureFlags()返回整个作用域对象。Web Componentsfeature-flags自定义元素Web Components 侧通过feature-flags元素以 attribute 形式声明 flag实现在 packages/web-components/src/components/feature-flags/index.ts。feature-flags enable-v12-release enable-v12-dynamic-floating-stylestrue cds-overflow-menu.../cds-overflow-menu /feature-flags元素内部维护flagComponentMap把每个 flag attribute 关联到受影响的组件标签名如enable-v12-overflowmenu→CDS-OVERFLOW-MENU、enable-v12-dynamic-floating-styles→CDS-FLOATING、enable-dialog-element→CDS-MODALattribute 变化时同步更新对应组件顶层的 flag 状态。当前 Web Components 支持的 attribute 包括enable-v12-release、enable-v12-tile-default-icons、enable-v12-tile-radio-icons、enable-v12-overflowmenu、enable-treeview-controllable、enable-focus-wrap-without-sentinels、enable-dialog-element、enable-v12-dynamic-floating-styles、enable-v12-toggle-reduced-label-spacing等。Sass$feature-flagsmap 与 mixin/functionSass 消费者通过 index.scss 暴露的 API 控制样式分支use carbon/feature-flags as featureFlags; // 在加载 Carbon 样式之前合并覆盖 $feature-flags: ( enable-tile-contrast: true, );可用的函数与 mixinfeatureFlags.enabled($name)查询某 flag 是否开启会先计算enable-v12-release总开关featureFlags.add($name, $enabled)/enable($name)/disable($name)动态新增或切换 flag重复新增、查询不存在的 flag 会errorfeatureFlags.enabled($name) { ... }mixin 形式flag 开启时输出其中的样式内容$feature-flags: map.merge(feature-flags.$generated-feature-flags, $feature-flags)默认值 map可在!default声明后覆盖。由于 Sass 与 JS 是两套独立实现文档表格中标注 Sass 的 flag如enable-tile-contrast、enable-v12-structured-list-visible-icons需要在.scss中配置而 React/Web Components 的 flag 则在组件层配置。使用 Codemod 迁移Codemod 是自动化代码改写脚本用于在迁移到新组件/新 API 时减少手工劳动。Carbon 提供的 codemod 面向 v12 相关 flag上表所列 v12 codemod默认针对 React 源码除非另有说明Web Components 与 Sass 的迁移目前仍需手动完成。一个 flag 可能没有 codemod原因包括尚未编写 codemod该 flag 仅用于.scss文件当前不为 Sass 提供 codemod该 flag 保护的是无需重构代码的新行为。运行 Codemod在项目目录工作区干净中执行npx carbon/upgrade migrate codemod-name --write例如启用 v12 OverflowMenunpx carbon/upgrade migrate enable-v12-overflowmenu --write改动完成后通过 git 查看本地未暂存unstaged的 diff 来审查变更。更多可用 codemod 见 packages/upgrade/README.md。主要 v12 codemod 一览enable-v12-release将 React 根节点包上FeatureFlags enableV12Release并补充必要 import同时兼容createRoot/hydrateRoot与现代ReactDOM.render入口详见 packages/upgrade/README.md// Before import { createRoot } from react-dom/client; import App from ./App; const root createRoot(document.getElementById(root)); root.render(App /); // After import { createRoot } from react-dom/client; import { FeatureFlags } from carbon/react; import App from ./App; const root createRoot(document.getElementById(root)); root.render( FeatureFlags enableV12Release App / /FeatureFlags );enable-v12-overflowmenu将OverflowMenuItem转为MenuItem映射itemText→label、isDelete→kinddanger为hasDivider项添加MenuItemDivider。支持两种模式默认带FeatureFlags enableV12Overflowmenu包裹或通过--wrapWithFeatureFlagfalse仅做 API 迁移用法示例npx carbon/upgrade migrate enable-v12-overflowmenu --write npx carbon/upgrade migrate enable-v12-overflowmenu --wrapWithFeatureFlagfalse --write// Before OverflowMenu OverflowMenuItem itemTextOption 1 / OverflowMenuItem itemTextDelete isDelete / /OverflowMenu // AfterAPI-only 模式 OverflowMenu MenuItem labelOption 1 / MenuItem labelDelete kinddanger / /OverflowMenuenable-v12-tile-default-icons/enable-v12-tile-radio-icons分别为 Tile 与 RadioTile 组件包裹FeatureFlags enableV12TileDefaultIcons/FeatureFlags enableV12TileRadioIcons后者同时处理TileGroup内的 RadioTile。enable-v12-structured-list-visible-icons为StructuredListRow添加selection属性并移除单元格中自定义的CheckmarkFilled图标示例见 packages/upgrade/README.md。已知限制使用前务必阅读tile default icons、tile radio icons、OverflowMenu 三个 codemod 生成的是carbon/feature-flags的 import但 JSX 组件由carbon/react导出使用前需修正生成的 importtile default icons codemod 目标是Tile而 v12 默认图标行为实际影响ClickableTile需审查其覆盖范围OverflowMenu codemod 只更新子项与子项 props不会把父组件aria-label更新为label需逐项对照 v12 API 复核structured list codemod 只改 React 标记不更新应用的 Sass feature flag 配置。组件级文档与 Storybook除本文档外部分组件在 Storybook 中设有Feature flags文件夹其中文档页覆盖该包专属的配置与用法stories 则直观演示开启 flag 前后的效果。当前 React 侧已有多个组件提供此类示例例如 Modal、ComposedModal 的 presence 相关 stories以及 Web Components 侧的 overflow-menu.feature-flag.mdx演示enable-v12-dynamic-floating-styles如何让浮层样式随目标组件动态变化。flag 的清单、可用性与 codemod 关联仍以上文总表为准Storybook 页面仅作补充说明。IBM Products 组件迁移作为 v12 的一部分carbon-for-ibm-products中一批被广泛使用的组件正在整合进carbon/react目标是让所有 Carbon 使用者无需额外依赖独立包即可使用这些组件。需要注意在 v12 Storybook 侧边栏中这些组件带有Migrated徽标以便识别它们不包含在已发布的 v11 包中开启enable-v12-release也不会暴露它们——这些组件将随 v12 正式发布成为carbon/react公共 API 的一部分。实践建议与升级路径总结综合本文档、源码与 codemod 工具链推荐的渐进式迁移路径是盘点现状对照总表确认项目用到的组件涉及的 flagReact/Sass/Web Components 分别核对逐项试点对enable-*普通 flag先在 Storybook 对应 stories 中观察效果再在项目内按组件启用并收集反馈分步接入 v12用enable-v12-overflowmenu、enable-v12-tile-radio-icons等 codemod 逐项迁移审查 git diffSass 类 flag 手动更新$feature-flags最终统一全部迁移完成后以enable-v12-release总开关点亮所有 v12 flag对照 docs/migration/v12.md 的包级变更清单做最终审查实现升级到 v12 时受影响组件零改动的目标利用开发期提示留意开发环境控制台中notifyAvailableFlag输出的 v12 flag 可用提示按需提前启用。这套默认关闭 前缀分级 总开关 codemod的机制让大规模设计系统可以在一个 major 版本周期内平稳交付破坏性变更是消费方规划升级节奏时最应优先掌握的官方工具。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考