Univer 主题系统全解析univerjs/themes 内置主题、Theme 结构与自定义指南【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univerUniver 作为一个面向 Web 与 Server 的全栈办公套件框架支持电子表格 / 文档 / 演示文稿其 UI 层采用了一套独立的主题Theme设计令牌体系。univerjs/themes是 Univer 官方提供的内置主题定义包内置默认、深蓝、绿、橙、紫、红、黄七套主题。读完本文你将掌握该包的安装与引入方式、每套主题的Theme数据结构的完整含义色阶、灰度、循环色与高亮色并能基于源码结构自定义一套属于自己的 Univer 主题。包概览univerjs/themes是一个纯 TypeScript 定义包只包含主题令牌design tokens不含 CSS、多语言资源locales与 Facade 入口。这一点在官方 README 的包概览表中写得很清楚包名UMD 全局变量CSSLocalesFacade 入口univerjs/themesUniverThemes无无无对应地从仓库的 package.json 可以看到该包的keywords为univer、theme、themes、design-system、tokens其构建产物同时提供 ESMlib/es/index.js、CJSlib/cjs/index.js与类型声明lib/types/index.d.ts三种形态源码则直接以./src/index.ts作为开发态入口。安装与 Univer 其他官方包一致使用包管理器安装即可pnpm add univerjs/themes # 或 npm install univerjs/themes官方 README 特别提醒所有univerjs/*包应保持在同一版本避免因跨版本导致的类型或运行时行为不一致。引入内置主题该包通过 packages/themes/src/index.ts 统一导出全部内置主题对象与类型import { darkBlueTheme, defaultTheme, blueTheme, greenTheme, orangeTheme, purpleTheme, redTheme, yellowTheme, } from univerjs/themes; // 同时也导出 Theme 类型供自定义主题时使用 import type { Theme } from univerjs/themes;值得注意的源码细节在 index.ts 中blueTheme与defaultTheme指向同一个导出export { default as blueTheme, default as defaultTheme } from ./default;也就是说默认主题即蓝色系主题Theme类型则来自 default.ts 的export type Theme typeof defaultTheme;即以默认主题对象的结构作为所有主题的约束模板。Theme 数据结构详解以 default.ts 为基准一套Theme对象由三大部分组成1. 十一个语义色阶scale每个语义色阶是一个从浅到深的颜色映射键名为50900部分色阶另有端点键。默认主题包含以下 scaleprimary品牌主色默认主题下为蓝色系500 为#466AF7gray中性灰阶除50900外还额外包含0#FFFFFF与1000#000000两个端点blue、red、orange、yellow、green通用功能色jiqing青色/青色系色值为#16BDCA、#0694A2等实为青蓝cyan/teal色系indigo、purple、pink辅助色以primary为例完整色阶为primary: { 50: #F3F5FF, 100: #E9EDFF, 200: #D2DAFA, 300: #BAC6F8, 400: #6280F9, 500: #466AF7, 600: #2C53F1, 700: #143EE3, 800: #083AD1, 900: #1033BF, },在 examples/src/theme-customizer/constants.ts 中COLOR_SHADE_KEYS50~900、GRAY_ENDPOINT_KEYS0、1000与COLOR_SCALE_KEYSprimary、gray、blue、red、orange、yellow、green、jiqing、indigo、purple、pink恰好一一对应上述结构说明这是 Univer 主题体系约定俗成的完整字段清单。2. 循环色loop-colorloop-color提供 12 个色板引用112用于需要循环取色的场景如多系列图表、多人协同光标、批量生成对象等每个值引用某个色阶的某个色阶点loop-color: { 1: purple.400, 2: green.500, 3: blue.500, 4: yellow.400, 5: pink.300, 6: jiqing.600, 7: orange.400, 8: gray.800, 9: indigo.500, 10: red.300, 11: green.600, 12: yellow.700, },循环色是引用式定义如purple.400而非直接写死的十六进制色值因此切换主题时循环色会自动跟随主题变化。同样theme-customizer中的LOOP_COLOR_KEYS也定义了112共 12 个键。3. 高亮背景色highlight.backgroundhighlight.background提供 16 个高亮背景定义116每个由color引用式色板与alpha透明度组成highlight: { background: { 1: { color: purple.500, alpha: 0.3 }, // ... 1~8 为 alpha 0.3 的一组 9: { color: purple.500, alpha: 0.15 }, // ... 9~16 为 alpha 0.15 的一组 }, },观察 default.ts 可以看出18 使用较高透明度0.3用于较醒目的高亮916 使用较低透明度0.15用于更柔和的高亮且两组的颜色序列一致方便按强度成对使用。这类令牌通常被用于选中态、搜索命中等场景的背景填充。各内置主题对比除默认主题外其余六套主题均为对Theme模板的完整覆写。其中 dark-blue.ts 是唯一的深色主题其余均为浅色主题。几处值得关注的差异深蓝主题的反向色阶深色主题下primary色阶从50: #1E3A8A到900: #EFF6FF即 50 最深、900 最浅与浅色主题完全相反见 dark-blue.tsgray的0变为#07111F近黑蓝1000变为#F8FAFC近白即暗色界面的中性灰整体翻转。浅色主题的主色替换例如 green.ts 将primary替换为绿色系500 为#10B981orange.ts 替换为橙色系500 为#F97316purple.ts 替换为紫色系500 为#8B5CF6red.ts 替换为红色系500 为#F43F5Eyellow.ts 替换为黄色系500 为#EAB308。循环色与高亮色跟随主色各浅色主题的loop-color与highlight都相应改用了各自的主色系组合例如橙色主题的loop-color第 1 项为primary.500、第 2 项为yellow.500见 orange.ts。中性灰的微调浅色主题的gray也会做细微调整以匹配色相例如红色主题的gray系列带有暖色倾向100: #F4EEEE紫色主题的gray系列带有紫调100: #F1F0F5。在 Univer 中使用主题方式一作为 createUniver 的 theme 参数在 Univer 的应用初始化配置中theme字段直接接受univerjs/themes导出的主题对象。仓库内置的 presets 示例如 examples/src/preset-sheets-core/main.ts、examples/src/preset-docs-core/main.ts均采用该方式import { createUniver, defaultTheme, LocaleType } from univerjs/presets; const univer createUniver({ locale: LocaleType.ZH_CN, theme: defaultTheme, // 传入内置主题或自定义主题 // ... 其他配置 });方式二通过 ThemeSwitcherService 动态注入examples/src/main.tsx 展示了另一条路径——借助ThemeSwitcherService在运行时把主题令牌注入页面headimport { defaultTheme } from univerjs/themes; import { ThemeSwitcherService } from univerjs/ui; new ThemeSwitcherService().injectThemeToHead(defaultTheme);这为运行时动态换肤如深浅色切换、品牌换色提供了接口级支持。方式三可视化定制与导出仓库在 examples/src/theme-customizer 提供了一套完整的主题定制器示例它在 constants.ts 中把defaultTheme、greenTheme、orangeTheme、redTheme、purpleTheme、yellowTheme六套主题注册为预设THEME_PRESETS并在 theme-sections.tsx 中渲染出可编辑的色板字段。参考其 types.ts 中的ThemeScaleKey、ThemeShadeKey、ThemeGrayEndpointKey、LoopColorKey、TokenDensity等类型定义可以了解定制器对主题令牌的分类方式Core Palette / Full Schema 两种密度视图。自定义一套主题基于源码结构自定义主题非常简单导入Theme类型从defaultTheme派生一份完整的覆盖对象即可。浅色主题可直接复制defaultTheme再修改primary等色阶import { defaultTheme } from univerjs/themes; import type { Theme } from univerjs/themes; const myTheme: Theme { ...defaultTheme, primary: { 50: #F0FDF4, 100: #DCFCE7, 200: #BBF7D0, 300: #86EFAC, 400: #4ADE80, 500: #22C55E, 600: #16A34A, 700: #15803D, 800: #166534, 900: #14532D, }, }; // 之后将 myTheme 传给 createUniver 的 theme 字段或 // 通过 ThemeSwitcherService().injectThemeToHead(myTheme) 注入若要做深色主题则需要像 dark-blue.ts 一样将primary、gray以及各色阶整体翻转50为最深色、900为最浅色gray的0为近黑背景色、1000为近白前景色并同步调整loop-color与highlight的引用和透明度保证明暗环境下对比度与可读性一致。小结univerjs/themes是 Univer 主题体系的核心定义包通过语义色阶 循环色引用 高亮背景三段式Theme结构让 UI 层能够以设计令牌的方式统一取色。无论是直接使用内置的七套主题还是基于Theme类型派生自定义主题亦或是借助ThemeSwitcherService做运行时换肤都可以围绕 packages/themes/src 下的源码与 examples/src/theme-customizer 示例快速落地。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考