uni.setNavigationBarColor(options)

设置导航条、状态栏颜色

setNavigationBarColor 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	√	4.11	4.61

注意当pages.json中设置导航栏为custom时：

1. 状态栏的背景色将恒为透明。此时无法通过本API设置状态栏背景色。开发者可自行在状态栏区域放置view，设置背景色。
2. 本API设置前景色frontColor时，会修改状态栏的前景色。

参数

名称	类型	必填	默认值	兼容性	描述
options	SetNavigationBarColorOptions	是
名称 类型 必备 默认值 兼容性 描述 frontColor string 是 前景颜色值，包括按钮、标题、状态栏的颜色，仅支持 #ffffff 和 #000000 合法值 描述 #ffffff #000000 backgroundColor string.ColorString 是 背景颜色值，有效值为十六进制颜色 success (result: SetNavigationBarColorSuccess) => void 否 接口调用成功的回调函数 fail (error: SetNavigationBarColorFail) => void 否 接口调用失败的回调函数 complete (res: SetNavigationBarColorComplete) => void 否 接口调用结束的回调函数（调用成功、失败都会执行） animation SetNavigationBarColorOptionsAnimation 否 动画效果 名称 类型 必备 默认值 兼容性 描述 duration number 否 动画变化时间，单位 ms timingFunc string 否 动画变化方式 可选值： - 'linear': 动画从头到尾的速度是相同的; - 'easeIn': 动画以低速开始; - 'easeOut': 动画以低速结束; - 'easeInOut': 动画以低速开始和结束; 合法值 描述 linear easeIn easeOut easeInOut

SetNavigationBarColorSuccess 的属性值

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

SetNavigationBarColorFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是			设置导航栏字体颜色错误码 - 4: 框架内部异常
errSubject	string	是			统一错误主题（模块）名称
data	any	否			错误信息中包含的数据
cause	Error	否			源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

SetNavigationBarColorComplete 的属性值

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

返回值

类型	必备
Promise<SetNavigationBarColorSuccess>	否
名称 类型 必备 默认值 兼容性 描述 errMsg string 是

示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

扫码体验

示例

<template>
  <page-head title="setNavigationBarColor"></page-head>
  <view class="uni-padding-wrap uni-common-mt">
    <button @tap="setNavigationBarColor1" class="uni-btn">
      设置导航条背景绿色，标题白色
    </button>
    <button @tap="setNavigationBarColor2" class="uni-btn">
      设置导航条背景红色，标题黑色
    </button>
    <button @tap="goNavbarLite" class="uni-btn">
      跳转自定义导航栏页面
    </button>
  </view>
</template>

<script setup lang="uts">
  import { state, setLifeCycleNum } from '@/store/index.uts'

  // 自动化测试
  const getLifeCycleNum = () : number => {
    return state.lifeCycleNum
  }

  // 自动化测试
  const setLifeCycleNumFunc = (num : number) => {
    setLifeCycleNum(num)
  }

  const setNavigationBarColor1 = () => {
    uni.setNavigationBarColor({
      frontColor: '#ffffff',
      backgroundColor: '#00ff00',
      success: () => {
        console.log('setNavigationBarColor success')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      },
      fail: () => {
        console.log('setNavigationBarColor fail')
        setLifeCycleNumFunc(state.lifeCycleNum - 1)
      },
      complete: () => {
        console.log('setNavigationBarColor complete')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      }
    })
  }

  const setNavigationBarColor2 = () => {
    uni.setNavigationBarColor({
      frontColor: '#000000',
      backgroundColor: '#ff0000',
      success: () => {
        console.log('setNavigationBarColor success')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      },
      fail: () => {
        console.log('setNavigationBarColor fail')
        setLifeCycleNumFunc(state.lifeCycleNum - 1)
      },
      complete: () => {
        console.log('setNavigationBarColor complete')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      }
    })
  }

  const goNavbarLite = () => {
    uni.navigateTo({
      url: '/pages/template/custom-navbar-search/custom-navbar-search'
    })
  }

  defineExpose({
    getLifeCycleNum,
    setLifeCycleNum: setLifeCycleNumFunc,
    setNavigationBarColor1,
    setNavigationBarColor2
  })
</script>

示例源码如下，请查看 pre > code 标签中的内容

<template>
  <page-head title="setNavigationBarColor"></page-head>
  <view class="uni-padding-wrap uni-common-mt">
    <button @tap="setNavigationBarColor1" class="uni-btn">
      设置导航条背景绿色，标题白色
    </button>
    <button @tap="setNavigationBarColor2" class="uni-btn">
      设置导航条背景红色，标题黑色
    </button>
    <button @tap="goNavbarLite" class="uni-btn">
      跳转自定义导航栏页面
    </button>
  </view>
</template>

<script setup lang="uts">
  import { state, setLifeCycleNum } from '@/store/index.uts'

  // 自动化测试
  const getLifeCycleNum = () : number => {
    return state.lifeCycleNum
  }

  // 自动化测试
  const setLifeCycleNumFunc = (num : number) => {
    setLifeCycleNum(num)
  }

  const setNavigationBarColor1 = () => {
    uni.setNavigationBarColor({
      frontColor: '#ffffff',
      backgroundColor: '#00ff00',
      success: () => {
        console.log('setNavigationBarColor success')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      },
      fail: () => {
        console.log('setNavigationBarColor fail')
        setLifeCycleNumFunc(state.lifeCycleNum - 1)
      },
      complete: () => {
        console.log('setNavigationBarColor complete')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      }
    })
  }

  const setNavigationBarColor2 = () => {
    uni.setNavigationBarColor({
      frontColor: '#000000',
      backgroundColor: '#ff0000',
      success: () => {
        console.log('setNavigationBarColor success')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      },
      fail: () => {
        console.log('setNavigationBarColor fail')
        setLifeCycleNumFunc(state.lifeCycleNum - 1)
      },
      complete: () => {
        console.log('setNavigationBarColor complete')
        setLifeCycleNumFunc(state.lifeCycleNum + 1)
      }
    })
  }

  const goNavbarLite = () => {
    uni.navigateTo({
      url: '/pages/template/custom-navbar-search/custom-navbar-search'
    })
  }

  defineExpose({
    getLifeCycleNum,
    setLifeCycleNum: setLifeCycleNumFunc,
    setNavigationBarColor1,
    setNavigationBarColor2
  })
</script>

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

通用类型

GeneralCallbackResult

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是			错误信息

Bug & Tips

• app-android平台，受系统限制，通过frontColor修改状态栏前景色仅在Android6.0及以上版本生效。
• 本API默认处理栈顶页面，而不是代码所在页面。详见