# theme.json

HBuilder X 4.18+ 支持

iOS 13+、Android 10+ 提供了暗黑模式/深色模式，之前的模式称为light，暗黑称为dark。

当app需要暗黑主题时，开发者虽然可以自行决定自己的界面样式，但缺少合适的设置pages.json中样式的时机。

在页面的onLoad中设置当前页面的style会来不及，因为某些平台页面早于onLoad就可以创建和进行窗体转场动画，
这会造成新页面动画刚开始页面的背景色、navigationBar背景色是一个风格，而在onLoad后颜色发生变化。
也就是俗称的转场闪白或闪黑。

小程序提供了theme.json来给解决这个问题。在theme.json里配置light和dark的颜色，然后在pages.json中引用。

新页面创建时是根据pages.json的设置来初始化页面的，这样就可以在第一时间对页面样式进行适配，避免闪白闪黑。

考虑到全端兼容，uni-app x的web和app也支持theme.json设置。

但需要注意：theme.json，仅负责pages.json的页面样式、tabbar样式的控制。不负责开发者自己的页面css样式控制。

适配暗黑模式，除通过theme.json控制pages.json的样式外，还需要了解更多API：

获取OS主题：uni.getSystemInfo、uni.getDevideInfo，返回的osTheme属性
监听OS主题切换：uni.onOsThemeChange、uni.offOsThemeChange、
获取App主题：uni.getSystemInfo、uni.getAppBaseInfo，返回的appTheme属性
设置App主题：uni.setAppTheme
监听App主题切换：uni.onAppThemeChange、uni.offAppThemeChange、
manifest.json中设置App默认主题：defaultAppTheme

# theme.json使用步骤

在项目根目录下创建theme.json
在 theme.json 中定义相关变量
在 pages.json 中以@开头引用变量
可选在 manifest.json -> app 中配置主题默认值 "defaultAppTheme": "light", 支持通过主题API动态设置

# theme.json内容描述

theme.json 用于颜色主题相关的变量定义，包含以下属性：

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

示例如下：

{
	"light": {
		"navBgColor": "#f8f8f8",
		"navTxtStyle": "black"
	},
	"dark": {
		"navBgColor": "#292929",
		"navTxtStyle": "white"
	}
}

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

// 全局配置
{
  "globalStyle": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle"
  }
}
// 页面配置
{
	"path": "pages/index/index",
	"style":{
		"navigationBarBackgroundColor": "@navBgColor",
		"navigationBarTextStyle": "@navTxtStyle"
	}
}

配置完成后，调用相应 api 框架会自动所设属性，展示对应主题下的颜色。

pages.json中并非所有配置项均支持使用theme.json中的变量，支持通过变量配置的属性如下所示：

全局配置 globalStyle 与页面 style 支持：
- navigationBarBackgroundColor
- navigationBarTextStyle
- backgroundColor
- backgroundTextStyle
全局配置 tabbar 属性：
- color
- selectedColor
- backgroundColor
- borderStyle
- list
  - iconPath
  - selectedIconPath

# 配置示例

pages.json（示例省略了主题相关以外的配置项）

{
	"globalStyle": {
		"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

{
	"light": {
		"navBgColor": "#f8f8f8",
		"navTxtStyle": "black",
		"bgColor": "#ffffff",
		"bgTxtStyle": "light",
		"bgColorTop": "#eeeeee",
		"bgColorBottom": "#efefef",
		"tabFontColor": "#000000",
		"tabSelectedColor": "#3cc51f",
		"tabBgColor": "#ffffff",
		"tabBorderStyle": "black",
		"iconPath1": "/static/icon1_light.png",
		"selectedIconPath1": "/static/selected_icon1_light.png",
		"iconPath2": "/static/icon2_light.png",
		"selectedIconPath2": "/static/selected_icon2_light.png"
	},
	"dark": {
		"navBgColor": "#292929",
		"navTxtStyle": "white",
		"bgColor": "#1f1f1f",
		"bgTxtStyle": "dark",
		"bgColorTop": "#292929",
		"bgColorBottom": "#1f1f1f",
		"tabFontColor": "#ffffff",
		"tabSelectedColor": "#51a937",
		"tabBgColor": "#292929",
		"tabBorderStyle": "white",
		"iconPath1": "/static/icon1_dark.png",
		"selectedIconPath1": "/static/selected_icon1_dark.png",
		"iconPath2": "/static/icon2_dark.png",
		"selectedIconPath2": "/static/selected_icon2_dark.png"
	}
}