前端UI组件设计系统【免费下载链接】theme-uiBuild consistent, themeable React apps based on constraint-based design principles项目地址https://gitcode.com/gh_mirrors/th/theme-ui点击查看免费下载本文以 theme-ui 官方迁移文档MIGRATING.md为主线逐版本梳理 v0.2 至 v0.16 之间引入的破坏性变更、弃用 API 与对应迁移方案并结合当前仓库源码版本 0.17.4印证各项变化的实际实现。读完本文你将掌握如何升级到最新的 Theme UI 版本、如何正确处理ThemeProvider→ThemeUIProvider改名、MDX 改为 opt-in 后如何用useThemedStylesWithMdx重建主题样式、如何迁移Themed用法、如何在 v0.13 之后手动安装 peerDependencies、如何将主题配置项迁移到theme.config以及如何应对 v0.6 以来的 TypeScript 类型变化与颜色模式实现变化。一、v0.16TypeScript 与 React 类型要求升级v0.16 是最近一次包含破坏性变更的大版本核心变化集中在 TypeScript 与 JSX 类型系统上。TypeScript 版本下限提升Theme UI 现在要求TypeScript 版本高于 5.1.2原因是 5.1.2 之后 JSX 类型发生破坏性变更详见 issue #2430 的讨论。因此升级时需要将types/react更新到2023 年 6 月 1 日之后发布的版本强烈建议使用JSX Automatic Runtime即jsx-runtime以最大程度减少摩擦、避免出现奇怪的类型错误。这一点在当前仓库的 package.json 中得到印证theme-ui的 devDependencies 使用types/react: ^18.2.12、react: ^18.1.0peerDependencies 要求react: 18。同时仓库为 Automatic Runtime 提供了完整的产物入口packages/theme-ui/package.json 中声明了./jsx-runtime与./jsx-dev-runtime两个导出子路径对应源码见 packages/theme-ui/src/jsx-runtime.ts 与 packages/theme-ui/src/jsx-dev-runtime.ts。theme-ui/sidenav包被移除由于使用率低且types/react的破坏性变更导致维护成本上升theme-ui/sidenav包在 v0.16 中被移除。如果你还在使用它需要寻找替代方案例如自行实现侧边导航组件。ThemeProvider更名为ThemeUIProviderv0.16 将ThemeProvider改名为ThemeUIProvider目的是减少与 Emotion 的ThemeProvider混淆Emotion 11 同样导出一个名为ThemeProvider的组件。从源码看当前仓库仍然同时导出两者packages/theme-provider/src/index.tsx 中ThemeUIProvider是新实现而ThemeProvider被标记为deprecated在非生产环境下会通过React.useEffect打印警告信息/** deprecated ThemeProvider is now called ThemeUIProvider to reduce confusion with Emotion */ export const ThemeProvider: React.FCThemeProviderProps ({ theme, children }) { React.useEffect(() { if (process.env.NODE_ENV ! production) { console.warn( [theme-ui] The export ThemeProvider is deprecated and is now called ThemeUIProvider... ) } }, []) // ... }两个组件的实际渲染逻辑完全一致内部都包着CoreProvider与ColorModeProvider并在顶层 Provider 时注入RootStyles。因此迁移只需改名导入即可- import { ThemeProvider } from theme-ui import { ThemeUIProvider } from theme-ui仓库测试 packages/theme-ui/test/index.tsx 中专门验证了旧ThemeProvider会触发console.warn可作为迁移后的回归校验依据。二、v0.15MDX 改为 opt-in主题样式钩子登场v0.15 最核心的变化是MDX 支持从默认开启改为 opt-in。如果项目不使用 MDX、也不导入Themed则无需任何改动。MDXProvider不再内置改用useThemedStylesWithMdx此前 Theme UI 的ThemeProvider会隐式包含MDXProviderv0.15 起该行为被移除改为通过useThemedStylesWithMdx钩子显式接入。这样做的直接收益是让 Theme UI 可以与MDX v2协同工作。官方推荐的迁移写法是在自定义 Provider 内部组合MDXProvider、useMDXComponents与useThemedStylesWithMdximport { MDXProvider, useMDXComponents, Components as MDXComponents, MergeComponents as MergeMDXComponents, } from mdx-js/react import { useThemedStylesWithMdx } from theme-ui/mdx import { ThemeProvider, Theme } from theme-ui interface MyProviderProps { theme: Theme components?: MDXComponents | MergeMDXComponents children: React.ReactNode } function MyProvider({ theme, components, children }: MyProviderProps) { const componentsWithStyles useThemedStylesWithMdx( useMDXComponents(components) ) return ( ThemeProvider theme{theme} MDXProvider components{componentsWithStyles}{children}/MDXProvider /ThemeProvider ) }从源码看useThemedStylesWithMdx接收外层 MDX components通过wrapComponentsWithThemeStyles将defaultMdxComponents与用户 components 合并并为每个组件注入来自theme.styles的样式packages/mdx/src/useThemeStylesWithMdx.tsx用useMemo合并defaultMdxComponents与outerComponentspackages/mdx/src/wrapComponentsWithThemeStyles.tsx递归包装组件把themed(key)生成的样式作为cssprop 传入。这意味着components.p会自动获得theme.styles.p的样式以 className 形式落地与旧的隐式MDXProvider行为等价。Themed不再从theme-ui包中重新导出v0.15 起Themed组件字典以及其他theme-ui/mdx导出不再从theme-ui包重新导出。迁移改为从theme-ui/mdx导入- import { Themed } from theme-ui import { Themed } from theme-ui/mdx这一变化与当前仓库源码一致packages/theme-ui/src/index.ts 中export * from theme-ui/components等语句并不包含theme-ui/mdx的导出而 packages/mdx/src/index.tsx 明确导出Themed、defaultMdxComponents、themed与useThemedStylesWithMdx。Themed对象不再是组件Themed过去是Themed.div的别名即可以直接写Themed /。v0.15 起不再提供这种用法。迁移凡是用到Themed /的地方一律改为Themed.div /。从 packages/mdx/src/Themed.tsx 的实现可以看出Themed是一个由createThemedComponent为p、b、i、a、h1h6、img、pre、code、ol、ul、li、blockquote、hr、em、table、tr、th、td、strong、del、inlineCode、thematicBreak、div、root等标签逐一构建的组件字典其中inlineCode别名到code、thematicBreak别名到hr、root别名到div。每个组件都会用themed(key)从theme.styles中取出对应样式因此必须通过Themed.div这类具体成员来使用。三、v0.14移除emotion/styled依赖与相关 APIv0.14 的破坏性变更集中在依赖与组件 API 上theme-ui、theme-ui/components、theme-ui/mdx三个包不再依赖emotion/styled。这与当前仓库的 package.json 吻合theme-ui/components的 dependencies 中只有styled-system/*与theme-ui/*系列Emotion 相关包全部位于 peerDependencies。之前已弃用的Component.withComponentAPI 被彻底移除。theme-ui/mdx中Themed.X组件的asprop 被移除。asprop 的迁移方法所有Themed.X aselement的用法可以改为直接使用目标元素并配合sx从主题取样式// 迁移前 Themed.div ash2 / // 迁移后 h2 sx{t t.styles.div} /四、v0.13Emotion 与mdx-js/react回归 peerDependenciesv0.13 将emotion/react、emotion/styled、mdx-js/react移回peerDependencies以解决用户侧多版本 Emotion 导致的context 不匹配context mismatchbug。这是对 v0.3 一次改动的回滚目的是让这些库的实例在应用内保持唯一。现在安装theme-ui全家桶的标准命令是npm install theme-ui emotion/react emotion/styled mdx-js/react各包的具体 peer 要求来自当前仓库 packages/theme-ui/package.json、packages/mdx/package.json、packages/components/package.jsonemotion/react是绝大多数 Theme UI 库的 peerDependencytheme-ui 要求11.1.1emotion/styled是theme-ui/components、theme-ui/mdx与theme-ui的 peerDependencymdx-js/react是theme-ui/mdx与theme-ui的 peerDependency。注意如果其他库安装了冲突版本的 Emotion仍可能遇到 context 不匹配问题。theme-ui的源码中内置了防呆检查packages/core/src/index.ts 的ThemeProvider会在非生产环境比对__EMOTION_VERSION__发现多份 Emotion 时输出警告packages/theme-ui/test/index.tsx 中也有对应测试用例。若确需强制单一版本可以使用 Yarn resolutions 或 Webpack 的resolve.alias。五、v0.9放弃旧浏览器支持v0.9 起 Theme UI不再支持 IE11 等旧浏览器。收益是构建产物体积下降官方文档记载内置源码整体缩小约 34%即 9.5 kB代价是 Babel 配置不再转译旧语法。迁移要点若必须支持旧浏览器需要自行转译node_modules例如使用next-transpile-modules当前仓库的 babel.config.js 即为新的构建配置内部包gatsby-theme-code-recipes同时被移除。六、v0.8主题配置项迁移到theme.configv0.8 最重要的结构性变化是主题配置选项被移入theme.config对象。弃用的根级配置项以下原本直接写在 theme 对象根部的配置项被弃用统一收归到theme.config下旧写法已弃用新写法theme.useRootStylestheme.config.useRootStylestheme.useCustomPropertiestheme.config.useCustomPropertiestheme.useColorSchemeMediaQuerytheme.config.useColorSchemeMediaQuerytheme.useBorderBoxtheme.config.useBorderBoxtheme.useLocalStoragetheme.config.useLocalStorage⚠ 重要所有配置项应一次性全部迁移。如果 Theme UI 检测到theme.config存在就不再去 theme 根部寻找这些选项。这一点在源码中有多处印证例如 packages/color-modes/src/index.tsx 中统一使用outerTheme.config || outerTheme的取值模式const { initialColorModeName, useColorSchemeMediaQuery, useLocalStorage } outerTheme.config || outerThemev0.6 已弃用 API 的正式移除theme.useBodyStyles⟶ 替换为theme.config.useRootStylesStyled⟶ 替换为ThemeduseRootStyles默认值改为true随着useBodyStyles弃用useRootStyles现在默认开启。这意味着theme.styles.root中的样式从应用到body元素改为应用到html元素。大多数场景无需调整但部分针对 body 的样式可能需要微调。源码佐证packages/theme-provider/src/index.tsx 中RootStyles组件会读取theme.config || theme的useRootStyles当其为false或没有theme.styles.root时不注入否则会把variant: styles.root挂到html上同时给 body 设置margin: 0并默认启用border-box除非useBorderBox: false。七、v0.6Styled更名、颜色模式重构与类型变化v0.6 是一个变化密集的大版本包含新特性、破坏性变更与大量类型调整。新特性1.Styled更名为Themed为避免与emotion/styled的styled组件构造器混淆Styled组件字典更名为Themed。相关用法可参考 Themed 文档。2. 新增useRootStyles配置项默认false设为true可将styles.root应用到html而非body。当时useBodyStyles仍默认true但已计划弃用。3. 新增transitions比例尺用于支持 CSStransition属性。在 packages/css/src/index.ts 的scales映射表中可以看到transition: transitions的对应关系即sx{{ transition: themeTransition }}会从theme.transitions取值。4. 嵌套比例尺支持__default键对象形式的嵌套比例尺可以带一个__default键作为默认值。例如const theme { colors: { primary: { __default: #00f, light: #33f, } } }此时color: primary解析为color: #00fcolor: primary.light解析为#33f。源码中 packages/css/src/index.ts 定义了THEME_UI_DEFAULT_KEY __defaultget()函数在命中__default键时返回该默认值。5. 新增打印颜色模式配置通过printColorModeName在打印时使用指定颜色模式避免浪费墨水{ initialColorModeName: dark, printColorModeName: light }源码实现见 packages/color-modes/src/custom-properties.ts__createColorStyles会检测theme.config.printColorModeName若该模式存在于colors.modes中则生成media print下的颜色 CSS 变量覆盖若未找到对应模式会输出console.error提示。6. 新增Paragraph组件PR #1298现已收录在 packages/components/src/Paragraph.tsx。破坏性变更1. Emotion 11 依赖Theme UI 0.6 依赖 Emotion 11不再兼容 Emotion 10。若未单独安装 Emotion此变更对你无影响若其他依赖锁定 Emotion 10 且没有 Emotion 11 版本可通过 Yarn resolutions 或 Webpackresolve.alias强制统一版本。2. 首次渲染的颜色模式闪烁问题被消除但theme.colors不再返回原始色值为实现无闪烁渲染v0.6 恢复了对theme.rawColors的使用从useThemeUI()或sx中读取 theme 时不再能从theme.colors拿到原始色值.colors对象现在包含的是CSS 自定义属性Custom CSS Properties若需要将原始值传给不支持 CSS 变量的场景如 WebGL Canvas请使用.rawColors。迁移方式const { rawColors: colors } useThemeUI().theme源码佐证packages/color-modes/src/index.tsx 中useThemeWithAppliedColorMode在useCustomProperties ! false时会调用toCustomProperties把颜色值全部转换为var(--theme-ui-colors-*)形式写入res.colors同时保留res.rawColors。变量命名的实现见 packages/color-modes/src/custom-properties.ts。3. 默认颜色模式名变化默认颜色模式名不再是default而是undefined表示用户未设置、也未从偏好检测出颜色模式。4.useColorSchemeMediaQuery默认值改为true迁移方式如果你的主题中还没有该属性请显式添加useColorSchemeMediaQuery: false以保持旧行为。相关文档见 color modes 文档。当前实现中 packages/color-modes/src/index.tsx 会优先读取prefers-color-scheme媒体查询结果作为初始模式并将颜色模式持久化到localStorage的theme-ui-color-mode键。5. 内部 context 不再以Context命名导出如果你极不推荐使用了该内部 context可改用__ThemeUIContext见 packages/core/src/index.ts但官方建议用theme-ui/core的ThemeProvider处理局部主题覆盖。弃用项Styled将在 v0.7 移除请改用ThemeduseBodyStyles将在 v0.7 移除请改用useRootStyles。TypeScript 类型变化Theme UI 自 v0.6 起使用 TypeScript 编写发布类型与types/theme-ui不同响应式元组类型接受falsesx{{ color: isActive blue }}这类写法现在类型正确且渲染时会跳过false值packages/css/src/index.ts 的responsive函数中value false || value null直接continue。ColorMode中的已知颜色键primary、text、background、accent、secondary可以是嵌套比例尺。因此以下代码不再通过类型检查sx{{ color: theme theme.colors?.primary?.toUpperCase() }}因为colors.primary可能是对象但以下代码仍然有效sx{{ color: theme theme.colors?.primary }}若colors.primary是对象解析时使用colors.primary.__default。asprop 在Themed.X组件上正确退出类型检查TypeScript 用户请勿使用ComponentPropstypeof Themed[div]应导入ThemedComponent并使用ThemedComponentdiv。Theme UI 0.6 依赖csstypev3替代 v2。类型重命名从styled-system复制的类型被重命名或移除SxProps更名为SxPropSxStylePropThemeUIStyleObject的别名被移除请直接使用ThemeUIStyleObject。完整变更列表可参见 CHANGELOG.md。八、v0.3组件直接导入、依赖策略反转与 API 精简新特性组件现在可以直接从theme-ui包导入如import { Button } from theme-ui但要确保构建工具开启了tree-shaking内置为body添加基础样式的智能默认值简化的颜色模式 API新增theme-ui/css、theme-ui/core、theme-ui/color-modes、theme-ui/mdx子包支持更定制化的用法。破坏性变更emotion/react与mdx-js/react变成theme-ui的 dependencies不再需要单独安装若想固定版本用 Yarn resolutions。这一决定在 v0.13 又被回滚为 peerDependencies见本文第四节。Theme UI context 不再提供context.components若曾从 context 读取该对象请改用 MDX 钩子例如import { useMDXComponents } from mdx-js/react。若需从prefers-color-scheme初始化颜色模式必须显式开启useColorSchemeMediaQuery: true。ColorMode组件弃用不再需要用它为body添加颜色样式。Layout、Header、Main、Footer组件被移除请改用Box与Flex组合这些组件仍保留在 packages/components/src。initialColorMode标志失效改用initialColorModeName。ThemeProvider现在会根据theme.styles.root给body添加全局排版样式要禁用可设useBodyStyles: false。Theme context 变为无状态context.setTheme不再可用替代方案见theme-ui/editor包。ThemeStateProvider组件不再可用同样以theme-ui/editor作为替代。theme-ui/editor包 API 完全重写请参阅该包 README。九、v0.2JSX pragma 与早期包名调整v0.2 是早期迁移中值得一提的版本涉及命名与 API 的收尾工作JSX pragma如果使用了 Theme UI 自定义 JSX pragma把cssprop 改名为sx手动导入并使用的css工具函数不受影响。当前仓库中sxprop 的解析入口是 packages/core/src/parseProps.tsx它把sx与css合并后交给 Emotion。theme-ui-typography包改名改为theme-ui/typographytoStyleAPI 不再提供改用toThemeAPI用法见 Typography.js 相关文档。Box与布局组件如果使用了 Styled System 风格样式 props请替换为sxprop 或css工具函数参考 sx prop 文档。其他用ThemeProvider替换ColorModeProvider与ComponentProvideremotion/styled不再是 Theme UI 必需依赖若应用未直接使用可移除。十、升级路线图与验证清单综合以上各版本给出一个可落地的升级顺序与检查清单先读当前版本状态本仓库当前theme-ui版本为 0.17.4见 packages/theme-ui/package.json已包含 v0.16 之后的所有修复。升级基础依赖确保 TypeScript 5.1.2、types/react为 2023-06-01 之后版本、React 18安装 peerDependenciesemotion/react、emotion/styled、mdx-js/react。重命名 ProviderThemeProvider→ThemeUIProvider并留意控制台弃用警告。接入 MDX若使用 MDX v2在自定义 Provider 中组合useThemedStylesWithMdx与MDXProviderThemed一律从theme-ui/mdx导入且使用Themed.div等具体成员。迁移主题配置把useRootStyles、useCustomProperties、useColorSchemeMediaQuery、useBorderBox、useLocalStorage一次性迁入theme.config。颜色读取需要原始色值时使用theme.rawColors不要假设theme.colors返回原始值。类型适配使用ThemeUIStyleObject而非已移除的SxStyleProp使用ThemedComponentdiv而非ComponentPropstypeof Themed[div]。回归验证运行仓库测试套件如 packages/theme-ui/test/index.tsx 覆盖了 Provider 改名警告、多版本 Emotion 警告、嵌套 Provider 颜色合并等关键场景packages/mdx/test/index.tsx 验证了themed从主题提取样式的行为确认升级后无回归。按照以上路径逐项迁移即可平滑地从旧版本升级到最新的 Theme UI并规避各版本遗留的 API 陷阱。赞分享前端UI组件设计系统【免费下载链接】theme-uiBuild consistent, themeable React apps based on constraint-based design principles项目地址https://gitcode.com/gh_mirrors/th/theme-ui点击查看免费下载相关推荐Midway v3 升级 v4 完全指南Breaking Changes 对照与迁移实操Midway v3 升级 v4 完全指南Breaking Changes 对照与迁移实操 本文基于 site/docs/upgrade_v4.md https后端微服务云原生Argo CD v3.4 到 v3.5 升级指南Breaking Changes 全解析与迁移实践Argo CD v3.4 到 v3.5 升级指南Breaking Changes 全解析与迁移实践 导读 本文基于仓库中的官方升级文档 3.4 3.5.md云原生CI/CD容器编排DevOps后端Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移 导读 本文以 actix web/M后端Web框架上一篇OpenEuler社区贡献指南如何参与ubs-core开发与代码提交流程下一篇如何快速掌握openEuler热补丁制作与系统升级SysCare工具完全教程 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/13 6:30:19 · 阅读 1.2k theme-ui 迁移指南：从 v0.2 到 v0.16 的 Breaking Changes 全解析与升级实操
前端UI组件设计系统【免费下载链接】theme-uiBuild consistent, themeable React apps based on constraint-based design principles项目地址https://gitcode.com/gh_mirrors/th/theme-ui点击查看免费下载本文以 theme-ui 官方迁移文档MIGRATING.md为主线逐版本梳理 v0.2 至 v0.16 之间引入的破坏性变更、弃用 API 与对应迁移方案并结合当前仓库源码版本 0.17.4印证各项变化的实际实现。读完本文你将掌握如何升级到最新的 Theme UI 版本、如何正确处理ThemeProvider→ThemeUIProvider改名、MDX 改为 opt-in 后如何用useThemedStylesWithMdx重建主题样式、如何迁移Themed用法、如何在 v0.13 之后手动安装 peerDependencies、如何将主题配置项迁移到theme.config以及如何应对 v0.6 以来的 TypeScript 类型变化与颜色模式实现变化。一、v0.16TypeScript 与 React 类型要求升级v0.16 是最近一次包含破坏性变更的大版本核心变化集中在 TypeScript 与 JSX 类型系统上。TypeScript 版本下限提升Theme UI 现在要求TypeScript 版本高于 5.1.2原因是 5.1.2 之后 JSX 类型发生破坏性变更详见 issue #2430 的讨论。因此升级时需要将types/react更新到2023 年 6 月 1 日之后发布的版本强烈建议使用JSX Automatic Runtime即jsx-runtime以最大程度减少摩擦、避免出现奇怪的类型错误。这一点在当前仓库的 package.json 中得到印证theme-ui的 devDependencies 使用types/react: ^18.2.12、react: ^18.1.0peerDependencies 要求react: 18。同时仓库为 Automatic Runtime 提供了完整的产物入口packages/theme-ui/package.json 中声明了./jsx-runtime与./jsx-dev-runtime两个导出子路径对应源码见 packages/theme-ui/src/jsx-runtime.ts 与 packages/theme-ui/src/jsx-dev-runtime.ts。theme-ui/sidenav包被移除由于使用率低且types/react的破坏性变更导致维护成本上升theme-ui/sidenav包在 v0.16 中被移除。如果你还在使用它需要寻找替代方案例如自行实现侧边导航组件。ThemeProvider更名为ThemeUIProviderv0.16 将ThemeProvider改名为ThemeUIProvider目的是减少与 Emotion 的ThemeProvider混淆Emotion 11 同样导出一个名为ThemeProvider的组件。从源码看当前仓库仍然同时导出两者packages/theme-provider/src/index.tsx 中ThemeUIProvider是新实现而ThemeProvider被标记为deprecated在非生产环境下会通过React.useEffect打印警告信息/** deprecated ThemeProvider is now called ThemeUIProvider to reduce confusion with Emotion */ export const ThemeProvider: React.FCThemeProviderProps ({ theme, children }) { React.useEffect(() { if (process.env.NODE_ENV ! production) { console.warn( [theme-ui] The export ThemeProvider is deprecated and is now called ThemeUIProvider... ) } }, []) // ... }两个组件的实际渲染逻辑完全一致内部都包着CoreProvider与ColorModeProvider并在顶层 Provider 时注入RootStyles。因此迁移只需改名导入即可- import { ThemeProvider } from theme-ui import { ThemeUIProvider } from theme-ui仓库测试 packages/theme-ui/test/index.tsx 中专门验证了旧ThemeProvider会触发console.warn可作为迁移后的回归校验依据。二、v0.15MDX 改为 opt-in主题样式钩子登场v0.15 最核心的变化是MDX 支持从默认开启改为 opt-in。如果项目不使用 MDX、也不导入Themed则无需任何改动。MDXProvider不再内置改用useThemedStylesWithMdx此前 Theme UI 的ThemeProvider会隐式包含MDXProviderv0.15 起该行为被移除改为通过useThemedStylesWithMdx钩子显式接入。这样做的直接收益是让 Theme UI 可以与MDX v2协同工作。官方推荐的迁移写法是在自定义 Provider 内部组合MDXProvider、useMDXComponents与useThemedStylesWithMdximport { MDXProvider, useMDXComponents, Components as MDXComponents, MergeComponents as MergeMDXComponents, } from mdx-js/react import { useThemedStylesWithMdx } from theme-ui/mdx import { ThemeProvider, Theme } from theme-ui interface MyProviderProps { theme: Theme components?: MDXComponents | MergeMDXComponents children: React.ReactNode } function MyProvider({ theme, components, children }: MyProviderProps) { const componentsWithStyles useThemedStylesWithMdx( useMDXComponents(components) ) return ( ThemeProvider theme{theme} MDXProvider components{componentsWithStyles}{children}/MDXProvider /ThemeProvider ) }从源码看useThemedStylesWithMdx接收外层 MDX components通过wrapComponentsWithThemeStyles将defaultMdxComponents与用户 components 合并并为每个组件注入来自theme.styles的样式packages/mdx/src/useThemeStylesWithMdx.tsx用useMemo合并defaultMdxComponents与outerComponentspackages/mdx/src/wrapComponentsWithThemeStyles.tsx递归包装组件把themed(key)生成的样式作为cssprop 传入。这意味着components.p会自动获得theme.styles.p的样式以 className 形式落地与旧的隐式MDXProvider行为等价。Themed不再从theme-ui包中重新导出v0.15 起Themed组件字典以及其他theme-ui/mdx导出不再从theme-ui包重新导出。迁移改为从theme-ui/mdx导入- import { Themed } from theme-ui import { Themed } from theme-ui/mdx这一变化与当前仓库源码一致packages/theme-ui/src/index.ts 中export * from theme-ui/components等语句并不包含theme-ui/mdx的导出而 packages/mdx/src/index.tsx 明确导出Themed、defaultMdxComponents、themed与useThemedStylesWithMdx。Themed对象不再是组件Themed过去是Themed.div的别名即可以直接写Themed /。v0.15 起不再提供这种用法。迁移凡是用到Themed /的地方一律改为Themed.div /。从 packages/mdx/src/Themed.tsx 的实现可以看出Themed是一个由createThemedComponent为p、b、i、a、h1h6、img、pre、code、ol、ul、li、blockquote、hr、em、table、tr、th、td、strong、del、inlineCode、thematicBreak、div、root等标签逐一构建的组件字典其中inlineCode别名到code、thematicBreak别名到hr、root别名到div。每个组件都会用themed(key)从theme.styles中取出对应样式因此必须通过Themed.div这类具体成员来使用。三、v0.14移除emotion/styled依赖与相关 APIv0.14 的破坏性变更集中在依赖与组件 API 上theme-ui、theme-ui/components、theme-ui/mdx三个包不再依赖emotion/styled。这与当前仓库的 package.json 吻合theme-ui/components的 dependencies 中只有styled-system/*与theme-ui/*系列Emotion 相关包全部位于 peerDependencies。之前已弃用的Component.withComponentAPI 被彻底移除。theme-ui/mdx中Themed.X组件的asprop 被移除。asprop 的迁移方法所有Themed.X aselement的用法可以改为直接使用目标元素并配合sx从主题取样式// 迁移前 Themed.div ash2 / // 迁移后 h2 sx{t t.styles.div} /四、v0.13Emotion 与mdx-js/react回归 peerDependenciesv0.13 将emotion/react、emotion/styled、mdx-js/react移回peerDependencies以解决用户侧多版本 Emotion 导致的context 不匹配context mismatchbug。这是对 v0.3 一次改动的回滚目的是让这些库的实例在应用内保持唯一。现在安装theme-ui全家桶的标准命令是npm install theme-ui emotion/react emotion/styled mdx-js/react各包的具体 peer 要求来自当前仓库 packages/theme-ui/package.json、packages/mdx/package.json、packages/components/package.jsonemotion/react是绝大多数 Theme UI 库的 peerDependencytheme-ui 要求11.1.1emotion/styled是theme-ui/components、theme-ui/mdx与theme-ui的 peerDependencymdx-js/react是theme-ui/mdx与theme-ui的 peerDependency。注意如果其他库安装了冲突版本的 Emotion仍可能遇到 context 不匹配问题。theme-ui的源码中内置了防呆检查packages/core/src/index.ts 的ThemeProvider会在非生产环境比对__EMOTION_VERSION__发现多份 Emotion 时输出警告packages/theme-ui/test/index.tsx 中也有对应测试用例。若确需强制单一版本可以使用 Yarn resolutions 或 Webpack 的resolve.alias。五、v0.9放弃旧浏览器支持v0.9 起 Theme UI不再支持 IE11 等旧浏览器。收益是构建产物体积下降官方文档记载内置源码整体缩小约 34%即 9.5 kB代价是 Babel 配置不再转译旧语法。迁移要点若必须支持旧浏览器需要自行转译node_modules例如使用next-transpile-modules当前仓库的 babel.config.js 即为新的构建配置内部包gatsby-theme-code-recipes同时被移除。六、v0.8主题配置项迁移到theme.configv0.8 最重要的结构性变化是主题配置选项被移入theme.config对象。弃用的根级配置项以下原本直接写在 theme 对象根部的配置项被弃用统一收归到theme.config下旧写法已弃用新写法theme.useRootStylestheme.config.useRootStylestheme.useCustomPropertiestheme.config.useCustomPropertiestheme.useColorSchemeMediaQuerytheme.config.useColorSchemeMediaQuerytheme.useBorderBoxtheme.config.useBorderBoxtheme.useLocalStoragetheme.config.useLocalStorage⚠ 重要所有配置项应一次性全部迁移。如果 Theme UI 检测到theme.config存在就不再去 theme 根部寻找这些选项。这一点在源码中有多处印证例如 packages/color-modes/src/index.tsx 中统一使用outerTheme.config || outerTheme的取值模式const { initialColorModeName, useColorSchemeMediaQuery, useLocalStorage } outerTheme.config || outerThemev0.6 已弃用 API 的正式移除theme.useBodyStyles⟶ 替换为theme.config.useRootStylesStyled⟶ 替换为ThemeduseRootStyles默认值改为true随着useBodyStyles弃用useRootStyles现在默认开启。这意味着theme.styles.root中的样式从应用到body元素改为应用到html元素。大多数场景无需调整但部分针对 body 的样式可能需要微调。源码佐证packages/theme-provider/src/index.tsx 中RootStyles组件会读取theme.config || theme的useRootStyles当其为false或没有theme.styles.root时不注入否则会把variant: styles.root挂到html上同时给 body 设置margin: 0并默认启用border-box除非useBorderBox: false。七、v0.6Styled更名、颜色模式重构与类型变化v0.6 是一个变化密集的大版本包含新特性、破坏性变更与大量类型调整。新特性1.Styled更名为Themed为避免与emotion/styled的styled组件构造器混淆Styled组件字典更名为Themed。相关用法可参考 Themed 文档。2. 新增useRootStyles配置项默认false设为true可将styles.root应用到html而非body。当时useBodyStyles仍默认true但已计划弃用。3. 新增transitions比例尺用于支持 CSStransition属性。在 packages/css/src/index.ts 的scales映射表中可以看到transition: transitions的对应关系即sx{{ transition: themeTransition }}会从theme.transitions取值。4. 嵌套比例尺支持__default键对象形式的嵌套比例尺可以带一个__default键作为默认值。例如const theme { colors: { primary: { __default: #00f, light: #33f, } } }此时color: primary解析为color: #00fcolor: primary.light解析为#33f。源码中 packages/css/src/index.ts 定义了THEME_UI_DEFAULT_KEY __defaultget()函数在命中__default键时返回该默认值。5. 新增打印颜色模式配置通过printColorModeName在打印时使用指定颜色模式避免浪费墨水{ initialColorModeName: dark, printColorModeName: light }源码实现见 packages/color-modes/src/custom-properties.ts__createColorStyles会检测theme.config.printColorModeName若该模式存在于colors.modes中则生成media print下的颜色 CSS 变量覆盖若未找到对应模式会输出console.error提示。6. 新增Paragraph组件PR #1298现已收录在 packages/components/src/Paragraph.tsx。破坏性变更1. Emotion 11 依赖Theme UI 0.6 依赖 Emotion 11不再兼容 Emotion 10。若未单独安装 Emotion此变更对你无影响若其他依赖锁定 Emotion 10 且没有 Emotion 11 版本可通过 Yarn resolutions 或 Webpackresolve.alias强制统一版本。2. 首次渲染的颜色模式闪烁问题被消除但theme.colors不再返回原始色值为实现无闪烁渲染v0.6 恢复了对theme.rawColors的使用从useThemeUI()或sx中读取 theme 时不再能从theme.colors拿到原始色值.colors对象现在包含的是CSS 自定义属性Custom CSS Properties若需要将原始值传给不支持 CSS 变量的场景如 WebGL Canvas请使用.rawColors。迁移方式const { rawColors: colors } useThemeUI().theme源码佐证packages/color-modes/src/index.tsx 中useThemeWithAppliedColorMode在useCustomProperties ! false时会调用toCustomProperties把颜色值全部转换为var(--theme-ui-colors-*)形式写入res.colors同时保留res.rawColors。变量命名的实现见 packages/color-modes/src/custom-properties.ts。3. 默认颜色模式名变化默认颜色模式名不再是default而是undefined表示用户未设置、也未从偏好检测出颜色模式。4.useColorSchemeMediaQuery默认值改为true迁移方式如果你的主题中还没有该属性请显式添加useColorSchemeMediaQuery: false以保持旧行为。相关文档见 color modes 文档。当前实现中 packages/color-modes/src/index.tsx 会优先读取prefers-color-scheme媒体查询结果作为初始模式并将颜色模式持久化到localStorage的theme-ui-color-mode键。5. 内部 context 不再以Context命名导出如果你极不推荐使用了该内部 context可改用__ThemeUIContext见 packages/core/src/index.ts但官方建议用theme-ui/core的ThemeProvider处理局部主题覆盖。弃用项Styled将在 v0.7 移除请改用ThemeduseBodyStyles将在 v0.7 移除请改用useRootStyles。TypeScript 类型变化Theme UI 自 v0.6 起使用 TypeScript 编写发布类型与types/theme-ui不同响应式元组类型接受falsesx{{ color: isActive blue }}这类写法现在类型正确且渲染时会跳过false值packages/css/src/index.ts 的responsive函数中value false || value null直接continue。ColorMode中的已知颜色键primary、text、background、accent、secondary可以是嵌套比例尺。因此以下代码不再通过类型检查sx{{ color: theme theme.colors?.primary?.toUpperCase() }}因为colors.primary可能是对象但以下代码仍然有效sx{{ color: theme theme.colors?.primary }}若colors.primary是对象解析时使用colors.primary.__default。asprop 在Themed.X组件上正确退出类型检查TypeScript 用户请勿使用ComponentPropstypeof Themed[div]应导入ThemedComponent并使用ThemedComponentdiv。Theme UI 0.6 依赖csstypev3替代 v2。类型重命名从styled-system复制的类型被重命名或移除SxProps更名为SxPropSxStylePropThemeUIStyleObject的别名被移除请直接使用ThemeUIStyleObject。完整变更列表可参见 CHANGELOG.md。八、v0.3组件直接导入、依赖策略反转与 API 精简新特性组件现在可以直接从theme-ui包导入如import { Button } from theme-ui但要确保构建工具开启了tree-shaking内置为body添加基础样式的智能默认值简化的颜色模式 API新增theme-ui/css、theme-ui/core、theme-ui/color-modes、theme-ui/mdx子包支持更定制化的用法。破坏性变更emotion/react与mdx-js/react变成theme-ui的 dependencies不再需要单独安装若想固定版本用 Yarn resolutions。这一决定在 v0.13 又被回滚为 peerDependencies见本文第四节。Theme UI context 不再提供context.components若曾从 context 读取该对象请改用 MDX 钩子例如import { useMDXComponents } from mdx-js/react。若需从prefers-color-scheme初始化颜色模式必须显式开启useColorSchemeMediaQuery: true。ColorMode组件弃用不再需要用它为body添加颜色样式。Layout、Header、Main、Footer组件被移除请改用Box与Flex组合这些组件仍保留在 packages/components/src。initialColorMode标志失效改用initialColorModeName。ThemeProvider现在会根据theme.styles.root给body添加全局排版样式要禁用可设useBodyStyles: false。Theme context 变为无状态context.setTheme不再可用替代方案见theme-ui/editor包。ThemeStateProvider组件不再可用同样以theme-ui/editor作为替代。theme-ui/editor包 API 完全重写请参阅该包 README。九、v0.2JSX pragma 与早期包名调整v0.2 是早期迁移中值得一提的版本涉及命名与 API 的收尾工作JSX pragma如果使用了 Theme UI 自定义 JSX pragma把cssprop 改名为sx手动导入并使用的css工具函数不受影响。当前仓库中sxprop 的解析入口是 packages/core/src/parseProps.tsx它把sx与css合并后交给 Emotion。theme-ui-typography包改名改为theme-ui/typographytoStyleAPI 不再提供改用toThemeAPI用法见 Typography.js 相关文档。Box与布局组件如果使用了 Styled System 风格样式 props请替换为sxprop 或css工具函数参考 sx prop 文档。其他用ThemeProvider替换ColorModeProvider与ComponentProvideremotion/styled不再是 Theme UI 必需依赖若应用未直接使用可移除。十、升级路线图与验证清单综合以上各版本给出一个可落地的升级顺序与检查清单先读当前版本状态本仓库当前theme-ui版本为 0.17.4见 packages/theme-ui/package.json已包含 v0.16 之后的所有修复。升级基础依赖确保 TypeScript 5.1.2、types/react为 2023-06-01 之后版本、React 18安装 peerDependenciesemotion/react、emotion/styled、mdx-js/react。重命名 ProviderThemeProvider→ThemeUIProvider并留意控制台弃用警告。接入 MDX若使用 MDX v2在自定义 Provider 中组合useThemedStylesWithMdx与MDXProviderThemed一律从theme-ui/mdx导入且使用Themed.div等具体成员。迁移主题配置把useRootStyles、useCustomProperties、useColorSchemeMediaQuery、useBorderBox、useLocalStorage一次性迁入theme.config。颜色读取需要原始色值时使用theme.rawColors不要假设theme.colors返回原始值。类型适配使用ThemeUIStyleObject而非已移除的SxStyleProp使用ThemedComponentdiv而非ComponentPropstypeof Themed[div]。回归验证运行仓库测试套件如 packages/theme-ui/test/index.tsx 覆盖了 Provider 改名警告、多版本 Emotion 警告、嵌套 Provider 颜色合并等关键场景packages/mdx/test/index.tsx 验证了themed从主题提取样式的行为确认升级后无回归。按照以上路径逐项迁移即可平滑地从旧版本升级到最新的 Theme UI并规避各版本遗留的 API 陷阱。赞分享前端UI组件设计系统【免费下载链接】theme-uiBuild consistent, themeable React apps based on constraint-based design principles项目地址https://gitcode.com/gh_mirrors/th/theme-ui点击查看免费下载相关推荐Midway v3 升级 v4 完全指南Breaking Changes 对照与迁移实操Midway v3 升级 v4 完全指南Breaking Changes 对照与迁移实操 本文基于 site/docs/upgrade_v4.md https后端微服务云原生Argo CD v3.4 到 v3.5 升级指南Breaking Changes 全解析与迁移实践Argo CD v3.4 到 v3.5 升级指南Breaking Changes 全解析与迁移实践 导读 本文基于仓库中的官方升级文档 3.4 3.5.md云原生CI/CD容器编排DevOps后端Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移 导读 本文以 actix web/M后端Web框架上一篇OpenEuler社区贡献指南如何参与ubs-core开发与代码提交流程下一篇如何快速掌握openEuler热补丁制作与系统升级SysCare工具完全教程 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考