企业官网建设流程全解析

在 Storybook Addon 中通过 styled 模板字符串接入全局主题变量（theming 实战指南）

Storybook 官方以storybook/theming暴露了一套轻量主题 API，允许开发者（尤其是 addon 作者）直接复用 Storybook 内置的浅色 / 深色主题变量，让自定义面板、工具条与官方 UI 保持视觉一致。本文以 docs/_snippets/component-styled-variables-template-literals.md 这个核心示例为主线，讲解如何在样式组件中通过styled的模板字符串语法读取theme对象（如theme.background.app），并顺带对比对象写法、梳理主题变量结构与仓库内的真实落地用法，读完后你能在自有组件中正确、稳定地消费 Storybook 主题。

1. 片段出处：Addon 作者的主题接入小节

这段模板字符串写法不是孤立存在的，它隶属于 Storybook 文档中 Theming 章节 的“Using the theme for addon authors”小节。该小节专门面向“想要复用官方主题、获得原生 Storybook 开发体验”的扩展作者，明确指出：

Reuse the theme variables above for a native Storybook developer experience. The theming engine relies on emotion, a CSS-in-JS library.

也就是说，主题引擎基于 emotion 实现，而storybook/theming为其封装了开箱即用的styled。文档在给出模板字符串示例前，先配套了一个导入片段：

import { styled } from 'storybook/theming';

对应文件为 docs/_snippets/storybook-theming-styled-import.md。它与本节讨论的模板字符串示例共同构成一套完整的“import + 使用”流程。

2. 核心示例：模板字符串读取主题变量

关联文档给出的完整示例（面向 React，文件类型标注为MyComponent.js|jsx）如下：

const Component = styled.div` background: `${props => props.theme.background.app}` width: 0; `;

2.1 逐行拆解

• styled.div：由storybook/theming导出的、基于 emotion 的样式工厂方法。此处以 HTML 的div为宿主标签构造一个带样式的组件；
• 反引号模板字符串中内嵌${props => props.theme.background.app}：props由 emotion/styled 自动注入，它是包裹在当前组件上下文中的主题对象。props.theme指向通过ThemeProvider注入的 Storybook 主题；
• theme.background.app：逐级取到主题对象background分组下的app键，它代表整个应用/Manager UI 的主背景色；
• width: 0;：同属该样式块的普通 CSS 声明，说明主题变量完全可以与静态 CSS 声明混写在同一段模板字符串中。

2.2 值得注意的转义细节

在原文档示例中，模板字符串内部再次使用了反引号包裹表达式${...}（即${…}的嵌套写法）。在实际写作 JSX/JS 源码时，若整段外层已是反引号，内层通常可以去掉或按需保留成内嵌函数调用，文档这样书写的目的是直观展示“在模板字符串的表达式槽位里调用props”，这一模式与 emotion 官方推荐的模板字面量用法一致。

3. 与对象写法（object notation）的对照

同一小节中，component-styled-variables-object-notation.md 给出了完全等价的对象写法：

const Component = styled.div(({ theme }) => ({ background: theme.background.app, width: 0, }));

两种写法对比：

两者最终都由 emotion 编译为同样的样式结果，选型更多是代码风格与团队习惯问题。文档将两者并列展示，也正是为了让读者在 addon 代码库里自由选择。

4. 主题变量从哪来：theme对象的结构

要让props.theme.background.app有值，必须理解theme对象的来源。在 Theming 文档 中可以看到：

• Storybook 内置 light、dark 以及跟随系统偏好的 “normal” 三套主题，未指定时默认 normal；
• 主题是一个完整替换而非合并的对象，设置时须提供完整对象；
• 顶层存在base（必填，不可省略）、颜色相关的app/color分组、字体相关的font/text分组等。因此示例中的theme.background.app便是background分组（归属于app视觉体系）中的一个颜色键；
• 在.storybook/manager.js中通过主题对象控制 Manager UI，而 Docs 页面使用同一套主题系统但独立主题化，默认恒为 light。

注意：如果你在写 addon，不要对具体的颜色键名做“硬编码假设”之外的自定义，官方推荐直接消费上述分组的语义化变量（如app、background、color、font、text），这样当用户切换到 light/dark 或自定义主题时，你的面板会自动跟随，无需额外适配。

5. 仓库内真实用法：官方组件就是这么写样式的

仓库的 UI 代码中大量采用“styled+props => props.theme”模式，可作为模板字符串/对象写法的真实参照。例如：

• code/core/src/actions/components/ActionLogger/style.tsx 为 Actions 面板定义样式；
• code/core/src/component-testing/components/InteractionsPanel.tsx 等组件也通过 styled 消费主题；
• a11y 等 addons 目录 下的面板组件在*.stories.tsx中同样体现了以官方主题为前提的展示方式。

这些实现说明一个事实：官方与知名 addon 都基于同一套storybook/theming语义变量，而 addon 作者只需import { styled } from 'storybook/theming'，即可获得与原生组件一致的样式体验与自动主题切换能力。

6. 让 addon 组件感知主题：别忘了 Provider

styled表达式中的props.theme依赖上层的ThemeProvider。在 Storybook 运行时（Manager/UI 侧），主题已由 Storybook 内部统一注入，因此在 addon 的 Manager 面板中直接书写上述 styled 组件即可正确取到当前用户主题。

若你的 addon 需要在独立环境 / 测试用例中渲染这些组件，则应自行包裹 Provider，确保props.theme非空。可以结合 docs/configure/user-interface/theming.mdx 中create()快速生成主题的方式构造测试主题对象（base必填，常用简写覆盖brandImage、brandTitle、brandUrl、target等字段）。

7. 小结与建议

• 模板字符串与对象写法是从storybook/theming中取主题变量的两种等价姿势，本片段是其中的模板字符串范式；
• 主题变量应优先取语义化分组键（background.app、color、font、text等），不要硬编码色值，否则在 light/dark/自定义主题下会视觉失真；
• 官方主题引擎基于 emotion，styled自storybook/theming导出，与组件库生态（styled-components / emotion 用户）心智模型一致；
• 编写 addon 时，可参照 theming.mdx 的 addon authors 小节 与 code/core 内官方组件的样式实现，保持扩展与官方 UI 的观感统一。

实践建议：在 addon 仓库中把import { styled } from 'storybook/theming'作为唯一样式入口，统一用本文的模板字符串（或对象写法）读取theme，即可用最小成本获得 Storybook 级的设计一致性。