Carbon React Feature Flags 全面指南从FeatureFlags.js到 v12 渐进式升级【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本指南以 packages/react/src/internal/README.md 中关于编译期特性开关Feature Flags的说明为核心骨架结合carbon/react与carbon/feature-flags的源码实现系统讲解 Carbon 特性开关的默认值定义、组件内条件渲染用法、运行时开关组件以及贯穿 React / Sass / Web Components 三端的 v12 渐进式升级路径。读完本文你将掌握如何基于useFeatureFlag与FeatureFlags组件在项目中有序地开启 v12 新行为并在升级前利用 Codemod 自动化迁移。一、Feature Flags 是什么CarbonIBM 开源设计系统在carbon/react中内置了一套Feature Flags特性开关机制。它的作用是让使用方在仍然停留在当前主版本的前提下逐步、按需地启用新的组件行为与样式而不是一次性承受整个大版本升级带来的破坏性变更。在 React 包的内部目录下FeatureFlags.js维护着全部编译期特性开关的默认值清单组件源码在编译/渲染时读取这些开关决定走旧路径还是新路径。当某个新特性开关被引入时默认一律为false关闭从而保证向后兼容——这一点从源码与配置中可以明确印证packages/feature-flags/feature-flags.yml中除enable-v11-release外其余开关如enable-v12-release、enable-dialog-element、enable-presence等默认值均为false汇总各端开关清单的权威文档位于 docs/feature-flags.md其中明确说明除非特别指定所有开关默认关闭。从底层实现看开关的运行时载体是carbon/feature-flags包packages/feature-flags它在启动时从./generated/feature-flags读取由feature-flags.yml生成的全部开关信息并构建一个默认作用域见 packages/feature-flags/src/index.ts// packages/feature-flags/src/index.ts节选 const createDefaultScope () { const scope createScope(); for (const featureFlag of featureFlagInfo) { scope.add(featureFlag.name, featureFlag.enabled); } return scope; }; export const FeatureFlags createDefaultScope();二、最简用法根据开关渲染不同内容关联文档给出的核心示例演示了如何在 React 组件中读取某个开关并做条件渲染——这是carbon/react特性开关最直接的使用形态import { aFeatureFlag } from /path/to/FeatureFlags; // ... const MyComponent (props) ( div {...props}{aFeatureFlag ? foo : bar}/div );在这个示例中aFeatureFlag即代表 packages/react/src/internal/FeatureFlags.js 中定义的某个编译期开关常量当它为true时渲染foo否则渲染bar。需要指出的是这是文档展示的最原始形态直接导入默认值常量。在当前的carbon/react架构中更推荐、也更普遍的做法是通过useFeatureFlag(flagName)Hook 在运行时读取开关例如 packages/react/src/components/ComboBox/ComboBox.tsx 中的实际调用// packages/react/src/components/ComboBox/ComboBox.tsx节选 useFeatureFlag(enable-v12-dynamic-floating-styles) || autoAlign;useFeatureFlag由 packages/react/src/components/FeatureFlags/index.tsx 导出它从FeatureFlagContext中取出当前作用域并查询开关状态同时会在非生产环境下调用notifyAvailableFlag给出开发提示export const useFeatureFlag (flag: string) { const scope useContext(FeatureFlagContext); const enabled scope.enabled(flag); if (process.env.NODE_ENV ! production) { notifyAvailableFlag(flag, enabled); } return enabled; };三、运行时开关组件FeatureFlags与作用域合并仅靠编译期默认值开关的粒度只能停留在全包级。为了让不同子树使用不同的开关组合carbon/react提供了FeatureFlags组件定义于 packages/react/src/components/FeatureFlags/index.tsx它可以包裹一段 React 子树通过 Context 为其提供独立的开关作用域。其使用方式如下import { FeatureFlags } from carbon/react; FeatureFlags enablePresence enableV12Overflowmenu {/* 该子树内 enable-presence 与 enable-v12-overflowmenu 被打开 */} MyApp / /FeatureFlags从源码结构可以梳理出以下几点关键机制Prop 到开关名的映射PROP_TO_FLAG常量把驼峰命名的 Prop如enableV12Release映射为 kebab-case 的开关名如enable-v12-release。只合并显式传入的开关组件通过useMemo遍历映射表仅把值为undefined之外的 Prop 写入新作用域避免未指定的 Prop 覆盖父级作用域的设置——这是嵌套FeatureFlags作用域能正确生效的前提。作用域合并新建作用域后调用scope.mergeWithScope(parentScope)保证子作用域继承父级已有的开关值子级显式指定的开关优先见 packages/feature-flags/src/FeatureFlagScope.ts 中mergeWithScope的实现子作用域已有的 key 不会被父级覆盖。flagsProp 已废弃早期版本通过flags{{ enable-presence: true }}传入对象现在该 Prop 已被标记为废弃propTypes 中通过deprecate包装并提示运行 Codemod应改用上述独立布尔 Prop。配套的 Hook 有两个useFeatureFlag(flag)读取单个开关是否启用useFeatureFlags()直接获取当前FeatureFlagContext的整个作用域对象便于批量查询。四、作用域底层FeatureFlagScope的实现无论是编译期默认作用域还是FeatureFlags组件创建的运行时作用域最终都落到 packages/feature-flags/src/FeatureFlagScope.ts 的FeatureFlagScope类上。该类以Mapstring, boolean存储开关状态并暴露以下核心方法方法作用关键行为add(name, enabled)注册一个新开关同名重复注册会抛出异常enable(name)/disable(name)打开 / 关闭指定开关开关不存在时抛出异常checkForFlagenabled(name)查询开关是否启用见下方 v12 特殊逻辑merge(flags)合并一组开关同名 key 以传入值为准mergeWithScope(scope)合并另一个作用域子作用域已有 key 优先父级不覆盖值得注意的细节是enabled()中针对 v12 的特殊逻辑enabled(name: string) { this.checkForFlag(name); if (isV12Flag(name) this.flags.get(v12ReleaseFlag) true) { return true; } return this.flags.get(name) ?? false; }即当enable-v12-release被打开时所有enable-v12-*前缀的开关以及enable-focus-wrap-without-sentinels这一特例都会被自动视为开启无需逐个设置。isV12Flag的判定规则也定义在同一文件开关名以enable-v12-开头或命中unprefixedV12Flags集合。五、开关命名规范enable-*与enable-v#-*根据 docs/feature-flags.md 中Feature flag naming convention一节的说明Carbon 的开关命名遵循严格的前缀约定前缀本身即表明该开关所处的生命周期阶段enable-*试验性开关包含希望消费方测试并反馈的新特性总体稳定、不太可能变动但可能根据反馈调整可能需要使用方做少量手动迁移或代码改动已收录进 Storybook 文档需要用户反馈以确保特性覆盖所有关切点。enable-v#-*已承诺给未来主版本的开关当某个开关被广泛采用、或该特性被判定为高优先级时Carbon 会将其承诺给某个未来主版本并重命名为enable-v#-*例如enable-v12-some-feature此时该开关背后的 API 或功能已冻结、不再变动计划在名称所指示的主版本中默认开启所有破坏性变更都会以enable-v12-*开关形式在当前主版本v11中提供让项目可以提前、按自己的节奏启用破坏性变更避免升级到 v12 时一次性面对巨大变更集——理论上如果项目在 v12 发布前已开启全部enable-v12-*开关升级到 v12 时受影响组件无需再做任何改动。一个开关要被承诺并重命名为enable-v#-*必须满足经过早期采用者测试、单元/AVT/VRT 测试全覆盖、Storybook 与官网文档齐备并尽可能提供自动化迁移脚本Codemod。六、v12 开关全景与逐项说明下表汇总当前仓库中与 v12 相关的开关数据来自 packages/feature-flags/feature-flags.yml可用性与 Codemod 信息来自 docs/feature-flags.md开关说明可用端enable-v12-release一键开启全部 v12 特性开关并隐含开启enable-focus-wrap-without-sentinelsReact、Sass、Web Componentsenable-v12-tile-default-iconsTile 组件渲染默认图标React、Web Componentsenable-v12-tile-radio-iconsRadioTile组件渲染新的单选图标React、Sass、Web Componentsenable-v12-overflowmenu使用基于Menu子组件的 v12OverflowMenuReact、Web Componentsenable-v12-dynamic-floating-styles为Popover、Tooltip等组件动态设置浮动样式React、Web Componentsenable-v12-structured-list-visible-iconsStructuredList中的图标组件始终可见Sassenable-v12-toggle-reduced-label-spacing缩减 Toggle 控件与标签之间的间距Sass、Web Componentsenable-dialog-element组件使用原生dialog元素React、Sassenable-enhanced-file-uploaderFileUploader提供更丰富的回调数据与更广的触发事件Reactenable-focus-wrap-without-sentinels不依赖哨兵节点的新焦点循环行为Reactenable-presence组件在关闭状态下保持卸载、打开时才挂载Presence 机制React、Sassenable-treeview-controllable新的TreeView可控 APIReactenable-tile-contrast改进的 Tile 对比度样式Sass两个已废弃开关需注意enable-experimental-tile-contrast改用enable-tile-contrast与enable-experimental-focus-wrap-without-sentinels改用enable-focus-wrap-without-sentinels。在carbon/react中这些开关在 packages/react/src/components/FeatureFlags/index.tsx 的FeatureFlagsProps中均有对应的独立布尔 Prop如enableV12TileDefaultIcons、enablePresence、enableEnhancedFileUploader等可逐项开启。真实组件代码中随处可见此类消费例如 packages/react/src/components/ComposedModal/ComposedModal.tsx 同时查询enable-presence、enable-dialog-element与焦点循环相关开关来决定自身的渲染与行为。七、开启 v12 后的迁移Codemod 与注意事项使用 Codemod 自动化迁移Codemod 是carbon/upgrade提供的代码自动改写脚本可以显著降低启用新特性时的迁移成本。在干净的工作目录下进入你的项目目录执行npx carbon/upgrade migrate codemod-name --write例如为OverflowMenu启用 v12 行为npx carbon/upgrade migrate enable-v12-overflowmenu --write执行后可通过git中的未暂存文件变更来审阅改动。v12 相关的 Codemod 默认针对React 源码Web Components 与 Sass 的迁移目前需要手动完成。并非所有开关都配有 Codemod常见原因包括尚未编写、开关仅作用于.scss文件目前不提供此类 Codemod、或开关保护的新行为本就不需要重构代码。迁移评估与文档指引开启enable-v12-release后建议结合 docs/migration/v12.md 检查各包的变更范围、跨包关系以及从 v11 迁移应用时需要重点审视的区域。此外部分组件在 Storybook 中设有独立的Feature flags文件夹如 FileUploader.featureflag.mdx、ComposedModal.featureflag.mdx、Toggletip.featureflag.stories.js 等这些页面演示了开关开启前后的行为差异可作为直观参考但开关的清单、可用端与 Codemod 关联仍以 docs/feature-flags.md 为权威来源。另需注意一批源自carbon-for-ibm-products的常用组件正在并入carbon/reactv12 计划的一部分它们不会在发布的 v11 包中提供开启enable-v12-release也不会提前暴露它们——这些组件将在 v12 发布时成为carbon/react公共 API 的一部分。八、写在最后Carbon 的 Feature Flags 机制是一条设计精良的渐进式升级通道从 packages/react/src/internal/README.md 中按开关条件渲染的最小用法出发向上是useFeatureFlag/FeatureFlags组件构成的运行时作用域体系packages/react/src/components/FeatureFlags/index.tsx向下是carbon/feature-flags中以Map为核心的FeatureFlagScopepackages/feature-flags/src/FeatureFlagScope.ts最终由feature-flags.yml统一登记并生成默认值packages/feature-flags/feature-flags.yml。对实际项目而言推荐的接入路径是先在 Storybook 对应组件的 Feature flags 页面观察开关效果再通过FeatureFlags组件或独立 Prop 在局部开启验证确认无回归后用 Codemod 完成代码迁移最后借助enable-v12-release做一次全量开关验证平滑过渡到 v12。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考