uni.setAppTheme(options) @setapptheme

uni.setAppTheme(options)

setAppTheme 兼容性

参数

参见

uni.onAppThemeChange(callback)

onAppThemeChange 兼容性

参数

AppThemeChangeResult 的属性值

返回值

参见

展示全部

# 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	iOS
x	4.18	4.18

# 参数

名称

类型

必填

默认值

兼容性

描述

options

SetAppThemeOptions

是

名称

类型

必备

默认值

兼容性

描述

theme

"light" | "dark" | "auto"

是

主题

success

(result: SetAppThemeSuccessResult) => void

否

null

接口调用成功的回调函数

fail

(result: IAppThemeFail) => void

否

null

接口调用失败的回调函数

complete

(result: any) => void

否

null

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

# SetAppThemeSuccessResult 的属性值

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

# IAppThemeFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

702001 | 2002000

是

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

errSubject

string

是

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

data

any | null

否

错误信息中包含的数据

cause

Error | null

否

源错误信息，可以包含多个错误，详见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	iOS
x	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	iOS
x	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	iOS
x	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	iOS
x	4.18	4.18

# 参数

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

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

# 参见

相关 Bug

# 示例

hello uni-app x

该 API 不支持 Web，请运行 hello uni-app x 到 App 平台体验

<template>
  <view class="uni-padding-wrap">
    <view class="uni-common-mt item-box">
      <text>osTheme:</text>
      <text id="theme">{{ osTheme }}</text>
    </view>
    <view class="uni-common-mt item-box">
      <text>应用当前主题:</text>
      <text id="theme">{{ appTheme }}</text>
    </view>

    <view>
      <view class="uni-title uni-common-mt">
        <text class="uni-title-text"> 修改appTheme主题（此处仅为演示API，本应用并未完整适配暗黑模式） </text>
      </view>
    </view>
    <view class="uni-list uni-common-pl">
      <radio-group @change="radioChange" class="radio-group">
        <radio class="uni-list-cell uni-list-cell-pd radio" v-for="(item, index) in items" :key="item"
          :class="index < items.length - 1 ? 'uni-list-cell-line' : ''" :value="item"
          :checked="index === current">
          {{ item }}
        </radio>
      </radio-group>
    </view>

  </view>
</template>

<script>
  export default {
    data() {
      return {
        osThemeChangeId: 0,
        appThemeChangeId: 0,
        osTheme: "light" as string,
        appTheme: "light" as string,
        current: 0,
        items: [
          "light",
          "dark",
          "auto"
        ] as string[]
      }
    },
    methods: {
      bindOsThemeChange(): number {
        //注册osTheme变化监听
        return uni.onOsThemeChange((res: OsThemeChangeResult)=> {
          this.osTheme = res.osTheme
        })
      },
      bindAppThemeChange(): number {
        //注册appTheme变化监听
        return uni.onAppThemeChange((res: AppThemeChangeResult) => {
          this.appTheme = res.appTheme
        })
      },
      radioChange(e : UniRadioGroupChangeEvent) {
        const theme = e.detail.value
        this.setAppTheme(theme)
        uni.showToast({
          icon: 'none',
          title: '当前选中:'+theme,
        })
      },
      setAppTheme(value: string) {
        uni.setAppTheme({
          theme: value,
          success: function() {
            console.log("设置appTheme为", value, "成功")
          },
          fail: function(e: IAppThemeFail) {
            console.log("设置appTheme为", value, "失败,原因:", e.errMsg)
          }
        })
      }
    },
    onReady() {
      uni.getSystemInfo({
        success: (res:GetSystemInfoResult) => {
          this.osTheme = res.osTheme!
          this.appTheme = res.appTheme == "auto" ? res.osTheme! : res.appTheme!
          this.current = this.items.indexOf(res.appTheme!)
        }
      })
      this.osThemeChangeId = this.bindOsThemeChange()
      this.appThemeChangeId = this.bindAppThemeChange()
    },
    onUnload() {
      //注销监听
      uni.offAppThemeChange(this.appThemeChangeId)
      uni.offOsThemeChange(this.osThemeChangeId)
      uni.showToast({
        "position":"bottom",
        "title":"已停止监听主题切换"
      })
    }
  }
</script>

<style>
  .item-box {
    display: flex;
    flex-direction: row;
    justify-content: space-between;
  }
  .uni-list-cell {
    justify-content: flex-start;
  }
</style>