---
title: 应用配置
summary: "介绍通过 theme.json 配置文件定义主题变量，实现小程序深浅色主题自动切换。"
questions:
  - 如何在 app.json 中配置主题变量文件的路径？
  - theme.json 文件必须包含哪些属性？
  - 如何在全局配置中引用主题变量？
  - 支持通过变量配置的 window 属性有哪些？
  - tabBar 中哪些属性支持主题变量配置？
  - 如何获取当前系统主题？
  - 监听主题切换事件有哪几种方式？
  - theme.json 中变量的定义格式是什么？
  - 页面配置中如何引用主题变量？
  - 如果未配置 themeLocation 会怎样？
---

# 应用配置

## 相关配置

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

支持通过变量配置的属性：

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

## 变量配置文件 theme.json

`theme.json` 用于颜色主题相关的变量定义，需要先在 `themeLocation` 中配置 `theme.json` 的路径，否则无法读取变量配置。

配置文件须包含以下属性：

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

light 和 dark 下均可以 `key: value` 的方式定义变量名和值，例如：

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

完成定义后，可在全局配置或页面配置的相关属性中以 `@` 开头引用，例如：

### 全局配置

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

### 页面配置

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

配置完成后，小程序框架会自动根据系统主题，为小程序展示对应主题下的颜色。

## 配置示例

### app.json

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

```json
{
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle",
    "backgroundColor": "@bgColor",
    "backgroundTextStyle": "@bgTxtStyle",
    "backgroundColorTop": "@bgColorTop",
    "backgroundColorBottom": "@bgColorBottom"
  },
  "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",
    "bgColorTop": "#eeeeee",
    "bgColorBottom": "#efefef",
    "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",
    "bgColorTop": "#191919",
    "bgColorBottom": "#1f1f1f",
    "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"
  }
}
```

## 获取当前系统主题

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

## 监听主题切换事件

支持 2 种方式：

1. 在 `App()` 中传入 `onThemeChange` 回调方法，主题切换时会触发此回调。
2. 通过 `ty.onThemeChange` 监听主题变化，`ty.offThemeChange` 取消监听。