uni.setAppTheme(options) @setapptheme

展示全部

# uni.setAppTheme(options)

设置应用主题

uni.setAppTheme，并不会帮助开发者自动实现整个应用的亮/暗主题切换，它的作用是：

根据theme.json，设置pages.json的亮/暗主题
触发uni.onAppThemeChange，开发者和组件作者均可监听这个事件，自行响应将页面设置为对应的亮/暗风格。

当然组件作者也可以不监听onAppThemeChange，而是暴露主题切换API给开发者，由开发者监听主题切换，再调用组件的主题切换API。

目前uni-app x的内置组件和UI相关的API（比如showModal），并不会响应setAppTheme。组件是暴露了样式属性供开发者自行设置，Modal相关API目前没有样式设置，后续会升级支持。

# setAppTheme 兼容性

Web	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件
x	4.18	4.18	4.18	4.18

# 参数

名称

类型

必填

默认值

兼容性

描述

options

SetAppThemeOptions

是

名称

类型

必备

默认值

兼容性

描述

theme

string

是

主题

合法值	兼容性	描述
light	-	-
dark	-	-
auto	-	-

success

(result: SetAppThemeSuccessResult) => void

否

null

接口调用成功的回调函数

fail

(result: IAppThemeFail) => void

否

null

接口调用失败的回调函数

complete

(result: any) => void

否

null

接口调用结束的回调函数（调用成功、失败都会执行）

# SetAppThemeSuccessResult 的属性值

名称	类型	必备	默认值	兼容性	描述
theme	string	是	-	-	-

# IAppThemeFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码
- 702001 参数错误
- 2002000 未知错误

合法值	兼容性	描述
702001	-	-
2002000	-	-

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

uni.setAppTheme({
  theme: "auto",
  success: function() {
    console.log("设置appTheme为 auto 成功")
  },
  fail: function(e: IAppThemeFail) {
    console.log("设置appTheme为 auto 失败,原因:", e.errMsg)
  }
})

# 参见

相关 Bug

# uni.onAppThemeChange(callback)

开启监听应用主题变化

版本历史调整

HBuilderX 4.18版本的逻辑是：uni.setAppTheme 设置的 theme 值变化时触发本监听回调，回调参数中的 appTheme 值可能是"light" | "dark" | "auto"。在 app 平台设置应用的 theme 值为 auto 后，需再次查询osTheme来判断当前的真实主题。如果应用主题是auto，那么需要同时监听osTheme的变化。
HBuilderX 4.19版本调整为：应用的light/dark主题真正发生变化时触发监听回调。无论是手动设置setAppTheme还是跟随osTheme变化，只要真正变化了就会触发本监听。回调参数中的 appTheme 值只能是"light" | "dark"。

# onAppThemeChange 兼容性

Web	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件
x	4.18	4.18	4.18	4.18

# 参数

名称	类型	必填	默认值	兼容性	描述
callback	(res: AppThemeChangeResult) => void	是	-	-	-

# AppThemeChangeResult 的属性值

名称

类型

必备

默认值

兼容性

描述

appTheme

string

是

应用主题

# 返回值

类型
number

//callbackId 用于注销监听
val callbackId = uni.onAppThemeChange((res: AppThemeChangeResult) => {
  console.log("onAppThemeChange", res.appTheme)
})

# 参见

相关 Bug

# uni.offAppThemeChange(id)

取消监听应用主题变化

# offAppThemeChange 兼容性

Web	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件
x	4.18	4.18	4.18	4.18

# 参数

名称	类型	必填	默认值	兼容性	描述
id	number	是	-	-	-

val callbackId = uni.onAppThemeChange((res: AppThemeChangeResult) => {
  console.log("onAppThemeChange", res.appTheme)
})
//...
//...
//注销监听
uni.offAppThemeChange(this.appThemeChangeId)

# 参见

相关 Bug

# uni.onOsThemeChange(callback)

开启监听系统主题变化

# onOsThemeChange 兼容性

Web	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件
x	4.18	4.18	4.18	4.18

# 参数

名称	类型	必填	默认值	兼容性	描述
callback	(res: OsThemeChangeResult) => void	是	-	-	-

# OsThemeChangeResult 的属性值

名称

类型

必备

默认值

兼容性

描述

osTheme

string

是

系统主题

# 返回值

类型
number

//callbackId 用于注销监听
val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
    console.log("onOsThemeChange---", res.osTheme)
})

# 参见

相关 Bug

注意：

android 10、iOS 13 才开始支持深色模式主题 dark，更低版本无法获取、监听OS的主题。

# uni.offOsThemeChange(id)

取消监听系统主题变化

# offOsThemeChange 兼容性

Web	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件
x	4.18	4.18	4.18	4.18

# 参数

名称	类型	必填	默认值	兼容性	描述
id	number	是	-	-	-

val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
    console.log("onOsThemeChange---", res.osTheme)
})
...
...
//注销监听
uni.offOsThemeChange(callbackId)