---
title: .theme 主题元数据
description: .theme 主题文件阅读入口，指向主题变量、色板、系列色、主题算法、占位符样式和资源引用的 DTS 说明
navTitle: .theme
---
# .theme 主题元数据

主题定义页面通用外观元素，包括基础变量、色板、边框、字体、系列色、主题算法、占位符样式和引用资源，但不直接保存某个组件的业务属性。

theme 是页面视觉风格的共享语义层。组件可以记录 `color1`、`bg1` 这类主题属性，运行时再从当前主题中解析成实际颜色、字体或图形资源；切换主题时，组件元数据通常不变，只是换用另一套主题值。

当项目、应用、门户、仪表板或报表需要统一品牌色、明暗模式、图表系列色、字体和常用视觉资源时，应优先考虑主题。如果只是调整单个组件的固定样式，应优先查看组件属性或组件风格结构。

## 主题输出样式{#style-output}

主题输出样式时，采用 CSS 变量输出在页面根 DOM 上。也可以通过 `ThemeCompiledInfo` 获取主题信息，用于 canvas 图形组件等非样式渲染的属性。

组件设置属性时可以选择主题属性，如 `color1`、`bg1`。渲染组件时，通过主题属性找到主题中定义的实际值；切换主题时，组件属性值不变，只是重新从主题中查找实际值。

## DTS 入口{#types}

- 根结构：[`types/meta/file-types/theme-json.d.ts`](../../../../../dev-types/types/meta/file-types/theme-json.d.ts)
- 通用元数据类型：[`types/common-meta-types.d.ts`](../../../../../dev-types/types/common-meta-types.d.ts)
- 组件风格：[`types/meta/visual-page/componentstyle.d.ts`](../../../../../dev-types/types/meta/visual-page/componentstyle.d.ts)