---
title: theme.json 主题配置
summary: "介绍 theme.json 主题配置文件的格式，用于声明亮色和暗色主题变量。"
questions:
  - theme.json 文件的作用是什么？
  - theme.json 的配置格式是怎样的？
  - 如何在 theme.json 中分别声明亮色和暗色主题变量？
  - 声明的主题变量如何应用到 app.json 配置中？
  - theme.json 中的变量可以用于 app.json 的哪些字段？
---

# theme.json 主题配置

`theme.json` 是主题配置描述文件，用于定义 `light`（浅色）和 `dark`（深色）主题下的变量值。配置完成后，小程序框架会根据系统主题自动切换对应的颜色方案。

## 使用步骤

1. 在 `app.json` 中配置 `themeLocation`，指定 `theme.json` 的路径。例如在根目录下新增 `theme.json`，需要配置 `"themeLocation": "theme.json"`。
2. 在 `theme.json` 中定义主题变量。
3. 在 `app.json` 中以 `@` 开头引用变量。

## 配置格式

`theme.json` 须包含以下属性：

| 属性  | 类型   | 必填 | 描述                 |
| ----- | ------ | ---- | -------------------- |
| light | object | 是   | 浅色模式下的变量定义 |
| dark  | object | 是   | 深色模式下的变量定义 |

`light` 和 `dark` 下以 `key: value` 的形式定义变量名和值：

```json
{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black",
    "bgColor": "#ffffff"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white",
    "bgColor": "#1f1f1f"
  }
}
```

## 支持主题变量的属性

声明主题变量后，可通过 `@` 符号拼接变量名应用到 `app.json` 中以下字段：

- 全局配置 `window` 属性与页面配置下的属性：
  - navigationBarBackgroundColor
  - navigationBarTextStyle
  - backgroundColor
  - backgroundTextStyle
  - backgroundColorTop
  - backgroundColorBottom
- 全局配置 `tabBar` 的属性：
  - color
  - selectedColor
  - backgroundColor
  - borderStyle
  - list
    - iconPath
    - selectedIconPath

## 配置示例

### app.json

> 示例省略了主题相关以外的配置项

```json
{
  "themeLocation": "theme.json",
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle",
    "backgroundColor": "@bgColor",
    "backgroundTextStyle": "@bgTxtStyle"
  },
  "tabBar": {
    "color": "@tabFontColor",
    "selectedColor": "@tabSelectedColor",
    "backgroundColor": "@tabBgColor",
    "borderStyle": "@tabBorderStyle",
    "list": [
      {
        "iconPath": "@iconPath1",
        "selectedIconPath": "@selectedIconPath1"
      },
      {
        "iconPath": "@iconPath2",
        "selectedIconPath": "@selectedIconPath2"
      }
    ]
  }
}
```

### theme.json

```json
{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black",
    "bgColor": "#ffffff",
    "bgTxtStyle": "light",
    "tabFontColor": "#000000",
    "tabSelectedColor": "#3cc51f",
    "tabBgColor": "#ffffff",
    "tabBorderStyle": "black",
    "iconPath1": "image/icon1_light.png",
    "selectedIconPath1": "image/selected_icon1_light.png",
    "iconPath2": "image/icon2_light.png",
    "selectedIconPath2": "image/selected_icon2_light.png"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white",
    "bgColor": "#1f1f1f",
    "bgTxtStyle": "dark",
    "tabFontColor": "#ffffff",
    "tabSelectedColor": "#51a937",
    "tabBgColor": "#191919",
    "tabBorderStyle": "white",
    "iconPath1": "image/icon1_dark.png",
    "selectedIconPath1": "image/selected_icon1_dark.png",
    "iconPath2": "image/icon2_dark.png",
    "selectedIconPath2": "image/selected_icon2_dark.png"
  }
}
```

### 页面配置

页面的 `.json` 配置文件中也可以引用主题变量：

```json
{
  "navigationBarBackgroundColor": "@navBgColor",
  "navigationBarTextStyle": "@navTxtStyle"
}
```

## 获取当前系统主题

`ty.getSystemInfo` 或 `ty.getSystemInfoSync` 的返回结果中包含 `theme` 属性，值为 `light` 或 `dark`。

## 监听主题切换事件

支持 2 种方式：

1. 在 `App()` 中传入 `onThemeChange` 回调方法：

```javascript
App({
  onThemeChange(res) {
    console.log('当前主题:', res.theme); // 'light' 或 'dark'
  }
});
```

2. 通过 `ty.onThemeChange` 监听，`ty.offThemeChange` 取消监听：

```javascript
const handler = function (res) {
  console.log('主题变化:', res.theme);
};

ty.onThemeChange(handler);

// 不再需要时取消监听
ty.offThemeChange(handler);
```