跳转至

主题应用

{
  "scope": "global",
  "triggers": {
    "theming": ["INV1", "INV2", "INV3", "INV7", "INV8", "INV9", "INV11"]
  }
}

本记录定义了编译后的主题如何对 React 树和浏览器文档生效。

目的

用户应该在普通内容、嵌套主题区域、Portal 和非 CSS 消费者中看到相同的主题。挂载多个提供者不得创建重复样式,也不得让一个提供者移除另一个提供者仍在使用的样式。

系统模型

Theme 接收一个 DefinedTheme、一个颜色模式和子组件。包含函数图标条目或插槽函数的主题由客户端代码传递给 Theme。服务器代码可以使用此类主题解析图标;将其作为 prop 从服务器组件传递给客户端组件是不受支持的。

  • 它按名称注册主题。
  • 对于未预先构建的主题,它向 Web 编译器请求 CSS,并将该 CSS 挂载到文档中。
  • 对于已构建的主题,它假定消费者已加载样式表,并且不会再次编译或注入。
  • 它使用主题名称和颜色模式包装子组件。
  • 根提供者还会将活动主题名称和显式的浅色/深色模式写入 <html>。嵌套提供者不会更改 <html>。

useTheme 通常通过 React 上下文读取最近的提供者。

当没有提供者上下文时——例如渲染到独立的 React root 或回退视口中的内容——它只能通过一条共享的回退路径跟随根主题:

  1. 根 Theme 将其主题名称和显式的浅色/深色模式写入 <html>。
  2. useTheme 读取这些属性,并为每个文档共享一个观察者。
  3. 它在共享注册表中按名称查找主题对象。
  4. 每个无提供者的消费者复用该路径,而不是创建自己的观察者。

普通的 React Portal 保留提供者上下文,不需要此回退。回退机制无法为独立的 React root 恢复嵌套提供者。需要嵌套主题的内容必须将提供者上下文保留在同一个 React 树中。

MediaTheme 将局部表面标记为深色、浅色、自动检测或关闭。编译后的主题 CSS 使用该标记切换表面令牌,同时保留父主题的组件规则。

AppShell 使用相同的提供者/根回退身份路径来解析命名的移动导航宽度断点。最近的 Theme 优先;没有提供者上下文时,它跟随已注册的根主题;没有活动主题时,它使用标准宽度映射。

边界与不变量

  • INV1 — 最近的提供者获胜。 子组件读取最近的 Theme 上下文和 CSS 作用域。一个例外:主题的 reducedMotion: 'always' 也会影响每个嵌套提供者(spec:AST-108 FR6)。
  • INV2 — 只有根提供者更改 <html>。 嵌套提供者保持局部作用,不能更改浏览器界面或 Portal 范围的主题身份。
  • INV3 — 分离的消费者共享一个根主题存储。 独立的 React root 或回退视口通过一个内部存储(每个文档一个观察者)读取根属性和主题注册表。普通的 React Portal 保留提供者上下文。回退机制无法恢复嵌套提供者。
  • INV4 — 已构建的主题不会再次编译。 标记为已构建的主题使用其已加载的样式表,并跳过运行时样式生成和注入。
  • INV5 — 运行时样式安全共享。 多个使用同一未构建主题的提供者共享一套文档级样式。只有当没有已挂载的提供者仍然需要它们时,样式才会被移除。
  • INV6 — 提供者消费者避免文档观察。 提供者下的 useTheme 直接读取上下文。共享的文档观察者仅存在于无提供者消费者,并在未使用时断开连接。
  • INV7 — 系统跟随平台,任何未知模式也是如此。 Theme 的模式值和默认值归 component:Theme 所有。system 解析为当前的浅色/深色偏好,而不会向 <html> 写入强制模式。任何其他运行时值(例如过时的存储偏好或无类型调用者的字符串)都被视为 system:根提供者不向 <html> 写入强制模式,消费者通过平台偏好解析它。useTheme().mode 始终是解析后的 'light' 或 'dark',绝不会是 system,也绝不会是原始值。
  • INV8 — 媒体表面不会替换主题。 MediaTheme 更改局部表面令牌和可选的表面特定组件规则。它保持活动主题不变,并且关闭时不会重新挂载子组件。
  • INV9 — 应用过程不会更改已编译的规则。 提供者可以挂载、共享和移除编译器输出。它不得创建与构建路径不同的主题到 CSS 行为。
  • INV10 — 命名的响应式消费者共享 Theme 元数据。 AppShell 通过与其他无提供者消费者相同的根回退,从最近的活动主题解析 sm/md/lg/xl/2xl。其移动端严格低于该断点;相等属于更宽的布局。
  • INV11 — 图标解析在服务器和客户端之间保持一致。 服务器渲染和水合为活动主题将每个图标和插槽请求解析到同一节点。

本记录不涵盖主题创作、令牌定义、编译器输出,也不界定哪些组件部分是公开的主题目标。

变更耦合

  • 提供者嵌套的变更会测试根、嵌套、Portal 和清理行为。
  • 样式生命周期的变更会测试两个使用同一主题的提供者,并确认卸载其中一个不会破坏另一个。
  • 根属性的变更会同时测试浏览器模式、Portal 覆盖范围和无提供者钩子。
  • useTheme 回退的变更会测试提供者和无提供者路径,并确认提供者消费者不会创建文档观察者。
  • MediaTheme 的变更会测试深色、浅色、自动、关闭、回退以及不变的子组件身份。
  • 运行时编译的变更首先属于共享编译器,并与静态构建路径进行对照检查。

代码所有权

  • Theme.tsx 拥有 provider 作用域、运行时样式生命周期和根文档同步。
  • themeRegistry.ts 负责按主题名称进行服务端安全查找。
  • useTheme.ts 拥有 provider 访问和供分离消费者使用的共享根回退。其观察和订阅逻辑保持单一归属;提取另一模块不在此契约范围内。
  • MediaTheme.tsx 拥有本地亮色/暗色表面上下文。
  • AppShell.tsx 消费最近的有效宽度映射以进行移动端导航。
  • architecture:theme-compilation 拥有 Theme 挂载的 CSS。

规格决策

  • spec:AST-012/DEC-1 负责 AppShell 消费的固定宽度点词汇表。
  • spec:AST-087/DEC-2 使主题图标条目成为函数,这样持有这些条目的主题可以从客户端代码访问 Theme。
  • spec:AST-108/DEC-1 允许主题的 reducedMotion: 'always' 到达嵌套的 provider(INV1)。

验证

不变量 证据 失败信号
INV1, INV2, INV3 Theme.test.tsx 和 portal/root 测试固件 嵌套 provider 更改 <html>,或 portal 内容找不到根主题
INV4, INV5 运行时注入和清理测试 构建的主题注入 CSS,重复的 provider 重复注入 CSS,或一次卸载移除共享样式
INV6 useTheme.test.tsx Provider 消费者观察 DOM,或回退观察者泄漏
INV7 useTheme.test.tsx "light|dark|system 之外的模式":在亮色和暗色平台偏好下测试 "banana",仅在亮色偏好下测试 "DARK" 和 "";Theme.test.tsx "系统模式下为根 provider 从 <html> 移除 data-theme"。证据缺口:没有测试覆盖通过 useTheme 使用 system 模式的 provider,或未知值会对 <html> 产生什么影响(需从源码阅读)。 系统模式解析不正确,useTheme().mode 返回除 'light' 或 'dark' 之外的任何值(例如原始未知值),或根 provider 在 system 或未知模式下向 <html> 写入强制模式
INV8 MediaTheme.dom.test.tsx 表面模式替换主题、丢失父组件规则,或重新挂载子组件
INV9 运行时/构建编译器比较 同一主题下 provider 挂载的 CSS 与构建出的 CSS 不同
INV10 AppShell.test.tsx 命名点忽略最近的主题或将相等视为移动端
INV11 SSR 和水合图标测试夹具 同一主题下,服务端渲染的图标与水合后的图标不同

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx