【免费下载链接】pierrepierre’s open source code项目地址https://gitcode.com/gh_mirrors/pi/pierre点击查看免费下载导读pierre/theming是 pierre 开源仓库中的框架无关主题管理包而createThemeController及其配套类型ThemeController、ThemeControllerOptions、ThemeControllerState等构成了该包最核心的状态层它负责维护当前颜色模式light / dark / system、亮色与暗色主题的选择以及激活主题的异步解析与缓存。读完本文你将掌握 Controller API 的完整导出面、每个配置项与状态字段的精确语义理解其「SSR 安全」设计与「先解析成功再发布状态」的错误处理策略并能通过单控制器、多控制器、React 与原生 JavaScript 四种配方把主题切换能力直接落地到自己的应用中。一、Controller 在整个 theming 架构中的位置在pierre/theming的设计中主题管理被拆成四个关注点对应 skills/theming/SKILL.md元数据层createThemeCollection/createThemeCatalog描述主题集合名称、加载器、明暗标签解析层createThemeResolver负责注册加载器、异步加载与缓存已解析的主题对象状态层createThemeController把「用户当前选了什么」沉淀为可订阅、可持久化的状态映射层normalizeThemeColors等工具把解析后的主题对象转换成可直接用于 UI 的颜色值。Controller 是连接前三者的枢纽它接收一个 catalog或 resolver内部完成加载器注册、初始状态构建、持久化读取、prefers-color-scheme监听并在每次选择变更时驱动解析器重新加载激活主题。核心实现位于 packages/theming/src/modules/createThemeController.ts所有导出统一从 packages/theming/src/index.ts 对外发布。二、导出总览Controller API 的完整导出面原文档以一张表完整列出pierre/theming主入口.子路径中与控制器相关的全部导出这里完整继承并补充每个类型的源码位置ExportKindPurpose源码位置createThemeControllerFunctionCreates state for a color mode and selected light and dark themes.createThemeController.tsThemeControllerTypeDefines controller state, mutations, subscription, and cleanup.createThemeController.tsThemeControllerOptionsTypeSelects a catalog or resolver and configures initial state.createThemeController.tsThemeControllerStateTypeDescribes the current selection and resolved theme.createThemeController.tsPendingThemeResolutionTypeIdentifies the active theme load.createThemeController.tsThemeResolutionErrorTypeDescribes a failed active theme load.createThemeController.tsThemeResolutionErrorContextTypeIdentifies the name and scheme for a failed load callback.createThemeController.tsThemePersistenceTypeDefines customloadandsavemethods.createThemeController.tsThemeSelectionTypeDescribes the persisted mode and theme names.createThemeController.tsColorModeTypeAcceptslight,dark, orsystem.types.tsColorSchemeTypeAccepts concretelightordark.types.tsThemeLikeTypeDefines the shared resolved-theme shape.types.ts2.1 基础类型先看ColorMode、ColorScheme与ThemeLike// packages/theming/src/modules/types.ts export interface ThemeLike { bg?: string; colors?: Recordstring, string; fg?: string; name?: string; type?: dark | light; } export type ColorScheme dark | light; export type ColorMode ColorScheme | system;ColorMode是用户可见的选择允许light、dark或跟随操作系统的systemColorScheme是具体生效的明暗方案永远只有light或dark二值ThemeLike是控制器与解析器共同约定的最小主题对象形状只有bg/fg/colors/name/type五个可选字段——解析器不依赖具体主题引擎Shiki、VS Code 等的完整结构任何满足该形状的对象都可以参与解析。三、ThemeControllerOptions初始化配置的完整字段原文档给出字段总表下面是完整继承并逐一结合源码展开。FieldPurposecatalogSupplies descriptors and catalog default names.resolverSupplies an existing resolver or shares one with other controllers.defaultLightThemeNameOverrides the initial light theme name.defaultDarkThemeNameOverrides the initial dark theme name.defaultModeSets the initial color mode.storageKeyStores the selection in browser local storage.persistenceSupplies custom selection storage.preloadInactiveResolves the inactive color-scheme theme too.onResolutionErrorReceives an active theme load error.核心约束创建控制器时必须传catalog、resolver或「catalog 共享 resolver」中的任意一种组合。源码中的校验逻辑createThemeController.ts明确抛错const selectedResolver options.resolver ?? (catalog ! null ? createThemeResolver() : undefined); if (selectedResolver null) { throw new Error(createThemeController requires a catalog or resolver); }三种合法组合的具体行为只传catalog控制器内部调用createThemeResolver()创建独立隔离的 resolver并把 catalog 中的全部加载器通过registerInto注册进去见 createThemeCollection.ts 的registerInto内部使用registerThemeIfAbsent避免重复注册冲突。测试 controller.test.ts 验证了这种隔离性控制器解析器里注册的主题不会泄漏到外部新建的无关 resolver。只传resolver这是「遗留路径」源码注释称为 Legacy path适用于调用方已经自行维护 resolver 注册的场景此时 catalog 默认名回退到内置常量FALLBACK_LIGHT_THEME pierre-light与FALLBACK_DARK_THEME pierre-darkcreateThemeController.ts。同时传catalog与resolvercatalog 的加载器会注册进外部传入的 resolver从而允许多个控制器共享同一个加载器注册表和解析缓存这正是多控制器配方的基石。3.1 各字段的默认值链与源码语义从 createThemeController.ts 可以梳理出精确的默认值解析顺序字段默认值解析顺序defaultDarkThemeNameoptions.defaultDarkThemeName→catalog?.defaultDarkThemeName→pierre-darkdefaultLightThemeNameoptions.defaultLightThemeName→catalog?.defaultLightThemeName→pierre-lightdefaultModeoptions.defaultMode→systempreloadInactiveoptions.preloadInactive→false仅解析激活主题storageKey省略则禁用内置持久化preloadInactive的作用默认false时控制器只解析当前激活配色方案对应的那个主题设为true后会在激活主题解析完成后顺带解析另一个配色方案的主题preloadInactiveForcreateThemeController.ts这样用户从暗色切到亮色时主题对象已在缓存中模式切换是瞬时的无需再等一次网络/模块加载。代价是初始多加载一个主题对象。storageKey与persistence的优先级两者同时出现时persistence自定义适配器优先只给storageKey时使用内置的「单 JSON 键」localStorage 适配器createLocalStorageAdaptercreateThemeController.ts它把整个ThemeSelection序列化为一个 JSON 条目存储两者都不给时持久化被禁用。源码注释特别提醒如果宿主应用需要把 mode 和两个主题名分别存到已有的独立 key下例如与旧的引导脚本兼容就必须传入自定义persistence。onResolutionError接收激活主题加载失败的回调签名是(error: unknown, context: ThemeResolutionErrorContext) void不传时默认落到console.error错误信息形如[theming] Failed to resolve theme xxx for dark color schemecreateThemeController.ts。四、ThemeController成员状态、变更、订阅与清理原文档方法表完整继承如下MemberPurposeresolverExposes the controllers resolver.getState()Returns the current immutable state object.setColorMode(mode)Selects light, dark, or system mode.setThemeNameForScheme(scheme, name)Selects the theme for one color scheme.subscribe(listener)Subscribes to state changes and returns an unsubscribe function.destroy()Removes the system color-scheme listener.4.1resolver成员控制器把内部或外部传入的 resolver 直接暴露出来调用方可以读取hasRegisteredTheme(name)/hasResolvedTheme(name)做同步判断主动resolveTheme预热主题在需要显式 resolver 的消费场景中复用同一个缓存实例。docs 应用正是这样做的themeController.resolver被导出为docsThemeResolver别名供仍需显式 resolver 的消费方使用避免创建第二套缓存apps/docs/components/themeController.ts。4.2setColorMode(mode)与setThemeNameForScheme(scheme, name)setColorMode切换light/dark/system三态。内部先调用resolveColorScheme把 mode 折叠成具体的明暗方案system时查询matchMedia((prefers-color-scheme: dark))见 createThemeController.ts再走setActiveSelection触发解析。若新 mode 与当前相同则直接返回幂等。setThemeNameForScheme只更新某个配色方案槽位的主题名不会切换模式源码注释明确说明切换模式由setColorMode负责。关键在于它自动判断目标槽位当前是否激活激活槽位 → 走setActiveSelection需要重新解析主题非激活槽位 → 走updateInactiveThemeName只更新名字并立即持久化、通知不触发解析createThemeController.ts。测试 controller.test.ts 验证了激活槽位换主题会重新解析setThemeNameForScheme(dark, test-dark-2)后resolvedTheme.name同步变为test-dark-2。4.3subscribe与destroy的生命周期subscribe(listener)把监听器加入内部Set返回一个unsubscribe函数用于从集合中移除该监听器createThemeController.ts。destroy()是浏览器的清理入口移除prefers-color-scheme的change事件监听并清空全部监听器createThemeController.ts。源码注释特别标注它「在服务端或重复调用都是安全的」。测试 controller.test.ts 验证了订阅语义subscribe后激活主题解析完成会触发通知调用返回的unsubscribe后再setColorMode(dark)通知计数不再增长。五、ThemeControllerState状态对象的全部字段原文档字段表完整继承如下FieldPurposelightThemeNameStores the selected light theme name.darkThemeNameStores the selected dark theme name.modeStores the selected color mode.resolvedColorSchemeProvides the active concrete light or dark scheme.resolvedThemeProvides the active resolved theme object.pendingThemeResolutionIdentifies an active theme load.resolutionErrorDescribes the latest active load failure.补充三个关键语义源码注释 createThemeController.tsresolvedColorScheme永远是light或dark绝不可能是system。它是把mode与操作系统偏好折叠后的具体结果。源码注释强烈建议用它驱动 DOM 的明暗应用例如data-theme/data-color-scheme属性而不要再自行推导一次。pendingThemeResolution与resolutionError是互斥的瞬态字段前者在激活主题/mode 变更等待主题对象加载期间被设置携带{ colorScheme, name }后者在加载失败时被填充携带{ colorScheme, error, name }。状态对象是新引用语义每次变更都会产出新的 state 对象这保证了订阅端尤其是 React 的useSyncExternalStore可以依据引用相等性判断是否真的发生了变化避免多余渲染。5.1 错误处理的关键保证绝不发布半成品状态这是 Controller 最值得注意的设计源码注释 createThemeController.ts激活主题解析失败时控制器保留最后一次成功解析的选择与 resolvedTheme而不是发布一个只有新名字、没有对应主题对象的半成品状态。实现上resolveActive会先检查缓存resolver.getResolvedTheme(name)缓存命中则同步提交否则进入异步解析把pendingSelectionPatch暂存起来只有 Promiseresolve且解析 ID 仍为最新resolutionId activeResolutionId时才真正提交补丁并notify()reject时则清空补丁、填充resolutionError、调用onResolutionError但不改变已生效的mode/ 主题名 /resolvedThemecreateThemeController.ts。测试 controller.test.ts 完整验证了这一行为把激活槽位换成加载失败的broken-dark后darkThemeName仍停留在test-dark、resolvedTheme不变、savedSelections为空失败不持久化、resolutionError精确记录了{ colorScheme: dark, error, name: broken-dark }且onResolutionError收到了包含上下文的回调。另一条测试 controller.test.ts 验证了setColorMode遇到失败主题时 mode 保持原值。5.2system模式的实时跟随控制器在创建时通过attachMediaListener挂上matchMedia((prefers-color-scheme: dark))的change监听createThemeController.ts。当操作系统切换明暗偏好、且当前 mode 为system时maybeUpdateSystemColorScheme会重新解析 concrete scheme 并触发激活主题切换让 UI 实时跟随 OScreateThemeController.ts。destroy()移除的正是这个监听器。六、持久化ThemeSelection与ThemePersistenceThemeSelectioncreateThemeController.ts是持久化存储的最小形状只含三件事——这正是「用户的已选内容」export interface ThemeSelection { darkThemeName: string; lightThemeName: string; mode: ColorMode; }源码注释强调了一个重要原则只持久化选择绝不持久化已解析的主题对象。解析后的主题在每次加载时由 resolver 重新派生避免把大对象写进 localStorage、也避免版本演进后旧数据失效。ThemePersistencecreateThemeController.ts是自定义适配器的接口export interface ThemePersistence { load(): ThemeSelection | null; save(selection: ThemeSelection): void; }load返回存储的选择缺失或不可读时返回nullsave写入选择。源码注释特别要求实现方必须自行守护浏览器访问localStorage 等以保证控制器整体 SSR 安全——服务端环境下load/save只是 no-op。6.1 默认 localStorage 适配器与防御性读取内置适配器createLocalStorageAdaptercreateThemeController.ts的关键细节load读出 JSON 后校验parsed.mode是否存在缺失视为损坏数据返回null单个字段缺失时回退到默认主题名JSON 解析异常损坏值返回null。save整个ThemeSelection序列化成一个 JSON 条目写入storageKey写入抛错配额/访问受限被吞掉因为「存储失败对主题功能是非致命的」。底层getStorage()createThemeController.ts在服务端或 localStorage 访问抛异常如沙箱 iframe、禁用 cookie 的隐私模式时返回undefined从而让整个持久化链路静默降级。七、实战配方四种落地方式下面的配方来自 skills 文档体系controller.md、recipe-one-controller.md、recipe-multiple-controllers.md、recipe-react.md、recipe-vanilla.md并补充了源码依据。7.1 配方一单控制器默认推荐当应用全局共享一个颜色模式和一套明暗主题选择时只用一个控制器。把 catalog 与 controller 放进同一个模块import { createThemeCatalog, createThemeController } from pierre/theming; import { themes } from pierre/theming/themes; export const themeCatalog createThemeCatalog({ themes, defaultLightThemeName: pierre-light, defaultDarkThemeName: pierre-dark, }); export const themeController createThemeController({ catalog: themeCatalog, defaultMode: system, storageKey: app-theme, });themes来自pierre/theming/themes子路径是 Pierre 与 Shiki 两个集合的稳定合并见 collections.md在应用需要读取或变更主题状态的任何地方 import同一个controller 实例应用拆除该模块时调用destroy()。createThemeCatalog会对默认名做校验默认亮/暗主题名必须存在于集合中否则构造时直接抛错createThemeCatalog.ts。7.2 配方二多控制器隔离区域当应用存在相互独立的区域不同模式、不同选择、不同存储 key 或不同生命周期时使用多个控制器若这些区域共享同一套加载器与缓存就传入同一个 resolverimport { createThemeCatalog, createThemeController, createThemeResolver, } from pierre/theming; import { themes } from pierre/theming/themes; const catalog createThemeCatalog({ themes, defaultLightThemeName: pierre-light, defaultDarkThemeName: pierre-dark, }); const resolver createThemeResolver(); export const workspaceTheme createThemeController({ catalog, resolver, storageKey: workspace-theme, }); export const previewTheme createThemeController({ catalog, resolver, defaultMode: light, storageKey: preview-theme, });要点每个区域订阅自己的controller区域移除时对每个controller 调用destroy()选择需要相互独立时使用不同的 storageKey。共享 resolver 的意义在于两个控制器注册的是同一套加载器、共享同一份解析缓存主题对象只加载一次。7.3 配方三React 集成控制器创建在组件外部的模块中组件内用useThemeController读取状态react.tsimport { useEffect } from react; import { useThemeController } from pierre/theming/react; import { themeController } from ./theme-controller; export function ThemeControls() { const state useThemeController(themeController); useEffect(() { document.documentElement.dataset.colorScheme state.resolvedColorScheme; }, [state.resolvedColorScheme]); return ( button typebutton onClick{() themeController.setColorMode( state.resolvedColorScheme dark ? light : dark ) } Use {state.resolvedColorScheme dark ? light : dark} mode /button ); }useThemeController是useSyncExternalStore的薄封装react.ts本身不含任何业务逻辑订阅用controller.subscribe客户端快照与服务端快照都用controller.getState——服务端拿到初始选择客户端水合后自动更新。由于控制器只在真正变化时发布新的state 对象快照引用在渲染之间稳定不会产生撕裂tearing或渲染循环。需要把state.resolvedTheme传给代码/文件树等 UI 表面需要 workbench 级 UI 颜色时再用normalizeThemeColors。7.4 配方四原生 JavaScript / 其他框架用「单控制器或双控制器」配方建好 controller 后把每次状态变化应用到 documentimport { normalizeThemeColors } from pierre/theming/color; import { themeController } from ./theme-controller; function applyTheme() { const state themeController.getState(); document.documentElement.dataset.colorScheme state.resolvedColorScheme; if (state.resolvedTheme null) return; const { colors } normalizeThemeColors(state.resolvedTheme); document.documentElement.style.setProperty( --app-background, colors?.[editor.background] ?? state.resolvedTheme.bg ?? ); document.documentElement.style.setProperty( --app-foreground, colors?.[editor.foreground] ?? state.resolvedTheme.fg ?? ); } applyTheme(); const unsubscribe themeController.subscribe(applyTheme);首次applyTheme()立即应用当前状态themeController.setColorMode(mode)交给模式切换控件setThemeNameForScheme(scheme, name)交给主题选择器宿主不再需要更新时调用unsubscribe()。八、SSR 安全控制器在服务端的行为源码顶部注释createThemeController.ts明确声明了 SSR 安全设计每一次浏览器访问localStorage、matchMedia都被守卫因此控制器可以在服务端正常构造和运行持久化与prefers-color-scheme监听在服务端只是 no-op客户端再水合。三条守卫路径分别是getStorage()服务端或访问抛异常时返回undefined持久化链路整体降级systemPrefersDark()服务端或matchMedia不可用时返回falsesystem模式先落到亮色等客户端上报真实偏好attachMediaListener()matchMedia不可用时静默跳过监听挂载。docs 应用正是利用这一点把 controller 做成模块单例服务端每进程创建一次浏览器守卫使其成为常量客户端每次页面加载创建一次并跨客户端导航存活apps/docs/components/themeController.ts。九、真实应用docs 应用的自定义持久化apps/docs/components/themeController.ts 是 Controller API 在仓库内的真实落地样本其中docsPersistence展示了「内置storageKey不满足需求时如何写自定义适配器」const MODE_KEY theme; const LIGHT_THEME_KEY diffshub-light-theme; const DARK_THEME_KEY diffshub-dark-theme; const docsPersistence: ThemePersistence { load() { const mode readKey(MODE_KEY); const light readKey(LIGHT_THEME_KEY); const dark readKey(DARK_THEME_KEY); if (mode null light null dark null) return null; const validMode mode light || mode dark || mode system ? mode : system; return { mode: validMode, lightThemeName: light ?? docsThemeCatalog.defaultLightThemeName, darkThemeName: dark ?? docsThemeCatalog.defaultDarkThemeName, }; }, save(selection) { writeKey(MODE_KEY, selection.mode); writeKey(LIGHT_THEME_KEY, selection.lightThemeName); writeKey(DARK_THEME_KEY, selection.darkThemeName); }, }; export const themeController createThemeController({ catalog: docsThemeCatalog, persistence: docsPersistence, defaultMode: system, });关键点docs 应用需要把选择映射到三个既有的历史 key上theme是防闪烁引导脚本读取的 key另两个是 diffshub 的主题 key以兼容旧版已保存的用户选择因此不能用内置的单 JSON 存储而是通过persistence自定义布局load中把不合法 mode 归一到system、缺失主题名回退到 catalog 默认名。createThemeController的选项设计persistence优先于storageKey正是为这类场景准备的。十、测试验证一览pierre/theming的控制器行为有完整的测试覆盖位于 packages/theming/test/controller.test.ts核心用例包括测试用例验证点registers catalog loaders without an external resolver仅传 catalog 时自动注册全部加载器并解析激活主题uses an isolated resolver for catalog-only controllers独立 resolver 的隔离性registers catalog loaders into a supplied resolver before initial resolutioncatalog resolver 组合的注册时机先于初始解析exposes initial selection and resolves the active theme初始状态与激活主题解析notifies subscribers when the active theme resolves订阅与退订语义setColorMode switches the active theme模式切换驱动主题切换setThemeNameForScheme on the active slot re-resolves激活槽位换主题重新解析setThemeNameForScheme keeps the active selection when resolution fails失败不发布半成品、不持久化、上报错误上下文setColorMode keeps the active mode when the next theme fails模式切换遇失败保持原 mode结语createThemeController把「明暗模式选择、双槽位主题名、激活主题解析、持久化、OS 偏好跟随」五件事收敛到一个框架无关、SSR 安全、且对外暴露完整 TypeScript 类型的单一实例中。理解其resolvedColorScheme与resolvedTheme的分工、失败回退语义、以及catalog/resolver/persistence三条配置线的优先级就能在任意宿主React、原生 JS 或其他框架中以最小成本获得一致的、可持久化的主题切换体验。更多配套能力可继续查阅同目录下的 resolver.md加载与缓存、collections.md集合与 catalog以及 react.mdReact 绑定。赞分享【免费下载链接】pierrepierre’s open source code项目地址https://gitcode.com/gh_mirrors/pi/pierre点击查看免费下载相关推荐OpenProject 移动应用平板分屏导航指南如何在 iPad 和 Android 平板上高效审阅工作包OpenProject 移动应用平板分屏导航指南如何在 iPad 和 Android 平板上高效审阅工作包 OpenProject 移动应用Beta是开源Garden Skills 设计方向顾问不知道要什么风格时如何挑对设计方向Garden Skills 设计方向顾问不知道要什么风格时如何挑对设计方向 garden skills 里 web design engineer 技能的 设Pierre Theming 主题工具包完全指南从 Shiki 主题到应用 UI 色的统一解析管线Pierre Theming 主题工具包完全指南从 Shiki 主题到应用 UI 色的统一解析管线 本指南围绕 Pierre 开源 UI 体系的主题基础包 上一篇NextTrace代码覆盖率分析确保核心功能的测试完整性下一篇FlexiViT架构深度解析理解flexivit_large.300ep_in1k的多patch尺寸设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
【免费下载链接】pierrepierre’s open source code项目地址https://gitcode.com/gh_mirrors/pi/pierre点击查看免费下载导读pierre/theming是 pierre 开源仓库中的框架无关主题管理包而createThemeController及其配套类型ThemeController、ThemeControllerOptions、ThemeControllerState等构成了该包最核心的状态层它负责维护当前颜色模式light / dark / system、亮色与暗色主题的选择以及激活主题的异步解析与缓存。读完本文你将掌握 Controller API 的完整导出面、每个配置项与状态字段的精确语义理解其「SSR 安全」设计与「先解析成功再发布状态」的错误处理策略并能通过单控制器、多控制器、React 与原生 JavaScript 四种配方把主题切换能力直接落地到自己的应用中。一、Controller 在整个 theming 架构中的位置在pierre/theming的设计中主题管理被拆成四个关注点对应 skills/theming/SKILL.md元数据层createThemeCollection/createThemeCatalog描述主题集合名称、加载器、明暗标签解析层createThemeResolver负责注册加载器、异步加载与缓存已解析的主题对象状态层createThemeController把「用户当前选了什么」沉淀为可订阅、可持久化的状态映射层normalizeThemeColors等工具把解析后的主题对象转换成可直接用于 UI 的颜色值。Controller 是连接前三者的枢纽它接收一个 catalog或 resolver内部完成加载器注册、初始状态构建、持久化读取、prefers-color-scheme监听并在每次选择变更时驱动解析器重新加载激活主题。核心实现位于 packages/theming/src/modules/createThemeController.ts所有导出统一从 packages/theming/src/index.ts 对外发布。二、导出总览Controller API 的完整导出面原文档以一张表完整列出pierre/theming主入口.子路径中与控制器相关的全部导出这里完整继承并补充每个类型的源码位置ExportKindPurpose源码位置createThemeControllerFunctionCreates state for a color mode and selected light and dark themes.createThemeController.tsThemeControllerTypeDefines controller state, mutations, subscription, and cleanup.createThemeController.tsThemeControllerOptionsTypeSelects a catalog or resolver and configures initial state.createThemeController.tsThemeControllerStateTypeDescribes the current selection and resolved theme.createThemeController.tsPendingThemeResolutionTypeIdentifies the active theme load.createThemeController.tsThemeResolutionErrorTypeDescribes a failed active theme load.createThemeController.tsThemeResolutionErrorContextTypeIdentifies the name and scheme for a failed load callback.createThemeController.tsThemePersistenceTypeDefines customloadandsavemethods.createThemeController.tsThemeSelectionTypeDescribes the persisted mode and theme names.createThemeController.tsColorModeTypeAcceptslight,dark, orsystem.types.tsColorSchemeTypeAccepts concretelightordark.types.tsThemeLikeTypeDefines the shared resolved-theme shape.types.ts2.1 基础类型先看ColorMode、ColorScheme与ThemeLike// packages/theming/src/modules/types.ts export interface ThemeLike { bg?: string; colors?: Recordstring, string; fg?: string; name?: string; type?: dark | light; } export type ColorScheme dark | light; export type ColorMode ColorScheme | system;ColorMode是用户可见的选择允许light、dark或跟随操作系统的systemColorScheme是具体生效的明暗方案永远只有light或dark二值ThemeLike是控制器与解析器共同约定的最小主题对象形状只有bg/fg/colors/name/type五个可选字段——解析器不依赖具体主题引擎Shiki、VS Code 等的完整结构任何满足该形状的对象都可以参与解析。三、ThemeControllerOptions初始化配置的完整字段原文档给出字段总表下面是完整继承并逐一结合源码展开。FieldPurposecatalogSupplies descriptors and catalog default names.resolverSupplies an existing resolver or shares one with other controllers.defaultLightThemeNameOverrides the initial light theme name.defaultDarkThemeNameOverrides the initial dark theme name.defaultModeSets the initial color mode.storageKeyStores the selection in browser local storage.persistenceSupplies custom selection storage.preloadInactiveResolves the inactive color-scheme theme too.onResolutionErrorReceives an active theme load error.核心约束创建控制器时必须传catalog、resolver或「catalog 共享 resolver」中的任意一种组合。源码中的校验逻辑createThemeController.ts明确抛错const selectedResolver options.resolver ?? (catalog ! null ? createThemeResolver() : undefined); if (selectedResolver null) { throw new Error(createThemeController requires a catalog or resolver); }三种合法组合的具体行为只传catalog控制器内部调用createThemeResolver()创建独立隔离的 resolver并把 catalog 中的全部加载器通过registerInto注册进去见 createThemeCollection.ts 的registerInto内部使用registerThemeIfAbsent避免重复注册冲突。测试 controller.test.ts 验证了这种隔离性控制器解析器里注册的主题不会泄漏到外部新建的无关 resolver。只传resolver这是「遗留路径」源码注释称为 Legacy path适用于调用方已经自行维护 resolver 注册的场景此时 catalog 默认名回退到内置常量FALLBACK_LIGHT_THEME pierre-light与FALLBACK_DARK_THEME pierre-darkcreateThemeController.ts。同时传catalog与resolvercatalog 的加载器会注册进外部传入的 resolver从而允许多个控制器共享同一个加载器注册表和解析缓存这正是多控制器配方的基石。3.1 各字段的默认值链与源码语义从 createThemeController.ts 可以梳理出精确的默认值解析顺序字段默认值解析顺序defaultDarkThemeNameoptions.defaultDarkThemeName→catalog?.defaultDarkThemeName→pierre-darkdefaultLightThemeNameoptions.defaultLightThemeName→catalog?.defaultLightThemeName→pierre-lightdefaultModeoptions.defaultMode→systempreloadInactiveoptions.preloadInactive→false仅解析激活主题storageKey省略则禁用内置持久化preloadInactive的作用默认false时控制器只解析当前激活配色方案对应的那个主题设为true后会在激活主题解析完成后顺带解析另一个配色方案的主题preloadInactiveForcreateThemeController.ts这样用户从暗色切到亮色时主题对象已在缓存中模式切换是瞬时的无需再等一次网络/模块加载。代价是初始多加载一个主题对象。storageKey与persistence的优先级两者同时出现时persistence自定义适配器优先只给storageKey时使用内置的「单 JSON 键」localStorage 适配器createLocalStorageAdaptercreateThemeController.ts它把整个ThemeSelection序列化为一个 JSON 条目存储两者都不给时持久化被禁用。源码注释特别提醒如果宿主应用需要把 mode 和两个主题名分别存到已有的独立 key下例如与旧的引导脚本兼容就必须传入自定义persistence。onResolutionError接收激活主题加载失败的回调签名是(error: unknown, context: ThemeResolutionErrorContext) void不传时默认落到console.error错误信息形如[theming] Failed to resolve theme xxx for dark color schemecreateThemeController.ts。四、ThemeController成员状态、变更、订阅与清理原文档方法表完整继承如下MemberPurposeresolverExposes the controllers resolver.getState()Returns the current immutable state object.setColorMode(mode)Selects light, dark, or system mode.setThemeNameForScheme(scheme, name)Selects the theme for one color scheme.subscribe(listener)Subscribes to state changes and returns an unsubscribe function.destroy()Removes the system color-scheme listener.4.1resolver成员控制器把内部或外部传入的 resolver 直接暴露出来调用方可以读取hasRegisteredTheme(name)/hasResolvedTheme(name)做同步判断主动resolveTheme预热主题在需要显式 resolver 的消费场景中复用同一个缓存实例。docs 应用正是这样做的themeController.resolver被导出为docsThemeResolver别名供仍需显式 resolver 的消费方使用避免创建第二套缓存apps/docs/components/themeController.ts。4.2setColorMode(mode)与setThemeNameForScheme(scheme, name)setColorMode切换light/dark/system三态。内部先调用resolveColorScheme把 mode 折叠成具体的明暗方案system时查询matchMedia((prefers-color-scheme: dark))见 createThemeController.ts再走setActiveSelection触发解析。若新 mode 与当前相同则直接返回幂等。setThemeNameForScheme只更新某个配色方案槽位的主题名不会切换模式源码注释明确说明切换模式由setColorMode负责。关键在于它自动判断目标槽位当前是否激活激活槽位 → 走setActiveSelection需要重新解析主题非激活槽位 → 走updateInactiveThemeName只更新名字并立即持久化、通知不触发解析createThemeController.ts。测试 controller.test.ts 验证了激活槽位换主题会重新解析setThemeNameForScheme(dark, test-dark-2)后resolvedTheme.name同步变为test-dark-2。4.3subscribe与destroy的生命周期subscribe(listener)把监听器加入内部Set返回一个unsubscribe函数用于从集合中移除该监听器createThemeController.ts。destroy()是浏览器的清理入口移除prefers-color-scheme的change事件监听并清空全部监听器createThemeController.ts。源码注释特别标注它「在服务端或重复调用都是安全的」。测试 controller.test.ts 验证了订阅语义subscribe后激活主题解析完成会触发通知调用返回的unsubscribe后再setColorMode(dark)通知计数不再增长。五、ThemeControllerState状态对象的全部字段原文档字段表完整继承如下FieldPurposelightThemeNameStores the selected light theme name.darkThemeNameStores the selected dark theme name.modeStores the selected color mode.resolvedColorSchemeProvides the active concrete light or dark scheme.resolvedThemeProvides the active resolved theme object.pendingThemeResolutionIdentifies an active theme load.resolutionErrorDescribes the latest active load failure.补充三个关键语义源码注释 createThemeController.tsresolvedColorScheme永远是light或dark绝不可能是system。它是把mode与操作系统偏好折叠后的具体结果。源码注释强烈建议用它驱动 DOM 的明暗应用例如data-theme/data-color-scheme属性而不要再自行推导一次。pendingThemeResolution与resolutionError是互斥的瞬态字段前者在激活主题/mode 变更等待主题对象加载期间被设置携带{ colorScheme, name }后者在加载失败时被填充携带{ colorScheme, error, name }。状态对象是新引用语义每次变更都会产出新的 state 对象这保证了订阅端尤其是 React 的useSyncExternalStore可以依据引用相等性判断是否真的发生了变化避免多余渲染。5.1 错误处理的关键保证绝不发布半成品状态这是 Controller 最值得注意的设计源码注释 createThemeController.ts激活主题解析失败时控制器保留最后一次成功解析的选择与 resolvedTheme而不是发布一个只有新名字、没有对应主题对象的半成品状态。实现上resolveActive会先检查缓存resolver.getResolvedTheme(name)缓存命中则同步提交否则进入异步解析把pendingSelectionPatch暂存起来只有 Promiseresolve且解析 ID 仍为最新resolutionId activeResolutionId时才真正提交补丁并notify()reject时则清空补丁、填充resolutionError、调用onResolutionError但不改变已生效的mode/ 主题名 /resolvedThemecreateThemeController.ts。测试 controller.test.ts 完整验证了这一行为把激活槽位换成加载失败的broken-dark后darkThemeName仍停留在test-dark、resolvedTheme不变、savedSelections为空失败不持久化、resolutionError精确记录了{ colorScheme: dark, error, name: broken-dark }且onResolutionError收到了包含上下文的回调。另一条测试 controller.test.ts 验证了setColorMode遇到失败主题时 mode 保持原值。5.2system模式的实时跟随控制器在创建时通过attachMediaListener挂上matchMedia((prefers-color-scheme: dark))的change监听createThemeController.ts。当操作系统切换明暗偏好、且当前 mode 为system时maybeUpdateSystemColorScheme会重新解析 concrete scheme 并触发激活主题切换让 UI 实时跟随 OScreateThemeController.ts。destroy()移除的正是这个监听器。六、持久化ThemeSelection与ThemePersistenceThemeSelectioncreateThemeController.ts是持久化存储的最小形状只含三件事——这正是「用户的已选内容」export interface ThemeSelection { darkThemeName: string; lightThemeName: string; mode: ColorMode; }源码注释强调了一个重要原则只持久化选择绝不持久化已解析的主题对象。解析后的主题在每次加载时由 resolver 重新派生避免把大对象写进 localStorage、也避免版本演进后旧数据失效。ThemePersistencecreateThemeController.ts是自定义适配器的接口export interface ThemePersistence { load(): ThemeSelection | null; save(selection: ThemeSelection): void; }load返回存储的选择缺失或不可读时返回nullsave写入选择。源码注释特别要求实现方必须自行守护浏览器访问localStorage 等以保证控制器整体 SSR 安全——服务端环境下load/save只是 no-op。6.1 默认 localStorage 适配器与防御性读取内置适配器createLocalStorageAdaptercreateThemeController.ts的关键细节load读出 JSON 后校验parsed.mode是否存在缺失视为损坏数据返回null单个字段缺失时回退到默认主题名JSON 解析异常损坏值返回null。save整个ThemeSelection序列化成一个 JSON 条目写入storageKey写入抛错配额/访问受限被吞掉因为「存储失败对主题功能是非致命的」。底层getStorage()createThemeController.ts在服务端或 localStorage 访问抛异常如沙箱 iframe、禁用 cookie 的隐私模式时返回undefined从而让整个持久化链路静默降级。七、实战配方四种落地方式下面的配方来自 skills 文档体系controller.md、recipe-one-controller.md、recipe-multiple-controllers.md、recipe-react.md、recipe-vanilla.md并补充了源码依据。7.1 配方一单控制器默认推荐当应用全局共享一个颜色模式和一套明暗主题选择时只用一个控制器。把 catalog 与 controller 放进同一个模块import { createThemeCatalog, createThemeController } from pierre/theming; import { themes } from pierre/theming/themes; export const themeCatalog createThemeCatalog({ themes, defaultLightThemeName: pierre-light, defaultDarkThemeName: pierre-dark, }); export const themeController createThemeController({ catalog: themeCatalog, defaultMode: system, storageKey: app-theme, });themes来自pierre/theming/themes子路径是 Pierre 与 Shiki 两个集合的稳定合并见 collections.md在应用需要读取或变更主题状态的任何地方 import同一个controller 实例应用拆除该模块时调用destroy()。createThemeCatalog会对默认名做校验默认亮/暗主题名必须存在于集合中否则构造时直接抛错createThemeCatalog.ts。7.2 配方二多控制器隔离区域当应用存在相互独立的区域不同模式、不同选择、不同存储 key 或不同生命周期时使用多个控制器若这些区域共享同一套加载器与缓存就传入同一个 resolverimport { createThemeCatalog, createThemeController, createThemeResolver, } from pierre/theming; import { themes } from pierre/theming/themes; const catalog createThemeCatalog({ themes, defaultLightThemeName: pierre-light, defaultDarkThemeName: pierre-dark, }); const resolver createThemeResolver(); export const workspaceTheme createThemeController({ catalog, resolver, storageKey: workspace-theme, }); export const previewTheme createThemeController({ catalog, resolver, defaultMode: light, storageKey: preview-theme, });要点每个区域订阅自己的controller区域移除时对每个controller 调用destroy()选择需要相互独立时使用不同的 storageKey。共享 resolver 的意义在于两个控制器注册的是同一套加载器、共享同一份解析缓存主题对象只加载一次。7.3 配方三React 集成控制器创建在组件外部的模块中组件内用useThemeController读取状态react.tsimport { useEffect } from react; import { useThemeController } from pierre/theming/react; import { themeController } from ./theme-controller; export function ThemeControls() { const state useThemeController(themeController); useEffect(() { document.documentElement.dataset.colorScheme state.resolvedColorScheme; }, [state.resolvedColorScheme]); return ( button typebutton onClick{() themeController.setColorMode( state.resolvedColorScheme dark ? light : dark ) } Use {state.resolvedColorScheme dark ? light : dark} mode /button ); }useThemeController是useSyncExternalStore的薄封装react.ts本身不含任何业务逻辑订阅用controller.subscribe客户端快照与服务端快照都用controller.getState——服务端拿到初始选择客户端水合后自动更新。由于控制器只在真正变化时发布新的state 对象快照引用在渲染之间稳定不会产生撕裂tearing或渲染循环。需要把state.resolvedTheme传给代码/文件树等 UI 表面需要 workbench 级 UI 颜色时再用normalizeThemeColors。7.4 配方四原生 JavaScript / 其他框架用「单控制器或双控制器」配方建好 controller 后把每次状态变化应用到 documentimport { normalizeThemeColors } from pierre/theming/color; import { themeController } from ./theme-controller; function applyTheme() { const state themeController.getState(); document.documentElement.dataset.colorScheme state.resolvedColorScheme; if (state.resolvedTheme null) return; const { colors } normalizeThemeColors(state.resolvedTheme); document.documentElement.style.setProperty( --app-background, colors?.[editor.background] ?? state.resolvedTheme.bg ?? ); document.documentElement.style.setProperty( --app-foreground, colors?.[editor.foreground] ?? state.resolvedTheme.fg ?? ); } applyTheme(); const unsubscribe themeController.subscribe(applyTheme);首次applyTheme()立即应用当前状态themeController.setColorMode(mode)交给模式切换控件setThemeNameForScheme(scheme, name)交给主题选择器宿主不再需要更新时调用unsubscribe()。八、SSR 安全控制器在服务端的行为源码顶部注释createThemeController.ts明确声明了 SSR 安全设计每一次浏览器访问localStorage、matchMedia都被守卫因此控制器可以在服务端正常构造和运行持久化与prefers-color-scheme监听在服务端只是 no-op客户端再水合。三条守卫路径分别是getStorage()服务端或访问抛异常时返回undefined持久化链路整体降级systemPrefersDark()服务端或matchMedia不可用时返回falsesystem模式先落到亮色等客户端上报真实偏好attachMediaListener()matchMedia不可用时静默跳过监听挂载。docs 应用正是利用这一点把 controller 做成模块单例服务端每进程创建一次浏览器守卫使其成为常量客户端每次页面加载创建一次并跨客户端导航存活apps/docs/components/themeController.ts。九、真实应用docs 应用的自定义持久化apps/docs/components/themeController.ts 是 Controller API 在仓库内的真实落地样本其中docsPersistence展示了「内置storageKey不满足需求时如何写自定义适配器」const MODE_KEY theme; const LIGHT_THEME_KEY diffshub-light-theme; const DARK_THEME_KEY diffshub-dark-theme; const docsPersistence: ThemePersistence { load() { const mode readKey(MODE_KEY); const light readKey(LIGHT_THEME_KEY); const dark readKey(DARK_THEME_KEY); if (mode null light null dark null) return null; const validMode mode light || mode dark || mode system ? mode : system; return { mode: validMode, lightThemeName: light ?? docsThemeCatalog.defaultLightThemeName, darkThemeName: dark ?? docsThemeCatalog.defaultDarkThemeName, }; }, save(selection) { writeKey(MODE_KEY, selection.mode); writeKey(LIGHT_THEME_KEY, selection.lightThemeName); writeKey(DARK_THEME_KEY, selection.darkThemeName); }, }; export const themeController createThemeController({ catalog: docsThemeCatalog, persistence: docsPersistence, defaultMode: system, });关键点docs 应用需要把选择映射到三个既有的历史 key上theme是防闪烁引导脚本读取的 key另两个是 diffshub 的主题 key以兼容旧版已保存的用户选择因此不能用内置的单 JSON 存储而是通过persistence自定义布局load中把不合法 mode 归一到system、缺失主题名回退到 catalog 默认名。createThemeController的选项设计persistence优先于storageKey正是为这类场景准备的。十、测试验证一览pierre/theming的控制器行为有完整的测试覆盖位于 packages/theming/test/controller.test.ts核心用例包括测试用例验证点registers catalog loaders without an external resolver仅传 catalog 时自动注册全部加载器并解析激活主题uses an isolated resolver for catalog-only controllers独立 resolver 的隔离性registers catalog loaders into a supplied resolver before initial resolutioncatalog resolver 组合的注册时机先于初始解析exposes initial selection and resolves the active theme初始状态与激活主题解析notifies subscribers when the active theme resolves订阅与退订语义setColorMode switches the active theme模式切换驱动主题切换setThemeNameForScheme on the active slot re-resolves激活槽位换主题重新解析setThemeNameForScheme keeps the active selection when resolution fails失败不发布半成品、不持久化、上报错误上下文setColorMode keeps the active mode when the next theme fails模式切换遇失败保持原 mode结语createThemeController把「明暗模式选择、双槽位主题名、激活主题解析、持久化、OS 偏好跟随」五件事收敛到一个框架无关、SSR 安全、且对外暴露完整 TypeScript 类型的单一实例中。理解其resolvedColorScheme与resolvedTheme的分工、失败回退语义、以及catalog/resolver/persistence三条配置线的优先级就能在任意宿主React、原生 JS 或其他框架中以最小成本获得一致的、可持久化的主题切换体验。更多配套能力可继续查阅同目录下的 resolver.md加载与缓存、collections.md集合与 catalog以及 react.mdReact 绑定。赞分享【免费下载链接】pierrepierre’s open source code项目地址https://gitcode.com/gh_mirrors/pi/pierre点击查看免费下载相关推荐OpenProject 移动应用平板分屏导航指南如何在 iPad 和 Android 平板上高效审阅工作包OpenProject 移动应用平板分屏导航指南如何在 iPad 和 Android 平板上高效审阅工作包 OpenProject 移动应用Beta是开源Garden Skills 设计方向顾问不知道要什么风格时如何挑对设计方向Garden Skills 设计方向顾问不知道要什么风格时如何挑对设计方向 garden skills 里 web design engineer 技能的 设Pierre Theming 主题工具包完全指南从 Shiki 主题到应用 UI 色的统一解析管线Pierre Theming 主题工具包完全指南从 Shiki 主题到应用 UI 色的统一解析管线 本指南围绕 Pierre 开源 UI 体系的主题基础包 上一篇NextTrace代码覆盖率分析确保核心功能的测试完整性下一篇FlexiViT架构深度解析理解flexivit_large.300ep_in1k的多patch尺寸设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
