---
summary: "介绍如何通过 themeLocation 和 theme.json 配置小程序主题变量及深浅色模式切换。"
tags: [主题应用配置, themeLocation配置, theme.json变量定义]
questions:
  - 如何配置 themeLocation 指定 theme.json 的路径？
  - theme.json 变量配置文件的结构是什么？
  - 如何在全局配置中使用 @ 引用主题变量？
  - 路由配置中如何接入主题变量实现 tabBar 主题切换？
  - 页面配置文件中支持哪些主题变量属性？
  - 如何通过 getSystemInfo 获取当前系统主题？
  - 如何监听系统主题切换事件？
  - theme.json 中 light 和 dark 的变量定义有什么要求？
---

# 应用配置

## 一、相关配置

### 操作流程

1. 在 `src/global.config.ts` 中配置 `themeLocation`，指定变量配置文件 `theme.json` 路径，例如：在 src 目录下新增 `theme.json`，需要配置 `"themeLocation":"theme.json"`。
2. 在 `src/theme.json` 中定义相关变量。
3. 在 `src/global.config.ts` 全局配置或 `src/routes.config.ts` 路由配置或 `src/pages/${pageId}/index.config.ts` 页面配置中以 @ 开头引用变量。

支持通过变量配置的一共有以下三大类：

### 全局配置

- 全局配置文件 `src/global.config.ts` 下 `tuya.window` 对象：
  > 详见 [小程序配置-app.json 全局配置#window](/cn/miniapp/develop/miniapp/framework/app/app-json#window)
  - navigationBarBackgroundColor
  - navigationBarTextStyle
  - backgroundColor
  - backgroundTextStyle
  - backgroundColorTop
  - backgroundColorBottom

### 路由配置

- 路由配置文件 `src/routes.config.ts` 下导出的 `tabBar` 对象：
  > 详见 [小程序配置-app.json 全局配置#tabbar](/cn/miniapp/develop/miniapp/framework/app/app-json#tabbar)
  - color
  - selectedColor
  - backgroundColor
  - borderStyle
  - list
    - iconPath
    - selectedIconPath

### 页面配置

- 页面配置文件 `src/pages/${pageId}/index.config.ts` 下导出的对象：
  > 详见 [小程序页面-页面配置](/cn/miniapp/develop/miniapp/framework/page/json#配置项)
  - backgroundColor
  - backgroundTextStyle
  - navigationBarBackgroundColor
  - navigationBarTextStyle

## 二、变量配置文件

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

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

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

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

```json
{
  "light": {
    "navBgColor": "#F6F7FB",
    "navTxtStyle": "black",
    "bgColor": "rgba(0, 0, 0, 0.7)",
    "setNavBgColor": "#FFFFFF",
    "setBgColor": "#f5f5f5",
    "tabFontColor": "#000000",
    "tabSelectedColor": "#3cc51f",
    "tabBgColor": "#ffffff",
    "tabBorderStyle": "black"
  },
  "dark": {
    "navBgColor": "#F6F7FB",
    "navTxtStyle": "black",
    "bgColor": "rgba(0, 0, 0, 0.7)",
    "setNavBgColor": "#FFFFFF",
    "setBgColor": "#f5f5f5",
    "tabFontColor": "#ffffff",
    "tabSelectedColor": "#51a937",
    "tabBgColor": "#191919",
    "tabBorderStyle": "white"
  }
}
```

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

### 全局配置接入

```typescript
// src/global.config.ts
import { GlobalConfig } from '@ray-js/types';

export const tuya = {
  themeLocation: 'theme.json',
  window: {
    backgroundColor: '@bgColor',
    navigationBarTitleText: 'Title',
    navigationBarBackgroundColor: '@navBgColor',
    navigationBarTextStyle: '@navTxtStyle',
  },
};

const globalConfig: GlobalConfig = {
  basename: '',
};

export default globalConfig;
```

### 路由配置接入

```typescript
// src/routes.config.ts
import { Routes, TabBar } from '@ray-js/types';

export const routes: Routes = [
  {
    route: '/',
    path: '/pages/home/index',
    name: 'Home',
  },
  {
    route: '/history',
    path: '/pages/history/index',
    name: 'History',
  },
  {
    route: '/setting',
    path: '/pages/setting/index',
    name: 'Setting',
  },
];

export const tabBar: TabBar = {
  textColor: '@tabFontColor',
  selectedColor: '@tabSelectedColor',
  backgroundColor: '@tabBgColor',
  borderStyle: '@tabBorderStyle' as 'white' | 'black',
  list: [
    {
      text: 'Home',
      icon: '/tabBar/home.png', // 注意此处的 icon 需要在 public/tabBar/home.png 下存在
      route: '/',
      activeIcon: '/tabBar/home-active.png', // 注意此处的 icon 需要在 public/tabBar/home-active.png 下存在
      pagePath: '/pages/home/index',
    },
    {
      text: 'History',
      icon: '/tabBar/history.png',
      route: '/history',
      activeIcon: '/tabBar/history-active.png',
      pagePath: '/pages/history/index',
    },
    {
      text: 'Setting',
      icon: '/tabBar/setting.png',
      route: '/setting',
      activeIcon: '/tabBar/setting-active.png',
      pagePath: '/pages/setting/index',
    },
  ],
};
```

### 页面配置接入

```typescript
// src/pages/home/index.config.ts
export default {
  backgroundColor: '@bgColor',
  navigationBarBackgroundColor: '@navBgColor',
  navigationBarTextStyle: '@navTxtStyle',
  navigationBarTitleText: 'Home',
  disableScroll: true,
};

```

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

## 三、获取当前系统主题

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

## 四、监听主题切换事件

可通过 `useAppEvent` 监听主题切换事件，如下代码所示：

```jsx | sandbox previewTitle="监听主题切换事件"
import React from 'react';
import { Text, View, useAppEvent } from '@ray-js/ray';

export default function App() {
  useAppEvent('onThemeChange', data => {
    console.log('这个 hook 等同于 onThemeChange', data);
  });

  return (
    <View>
      <Text>切换系统主题后查看日志输出</Text>
    </View>
  );
}
```