Back to Uni App

Set Navigation Bar Color

docs/api/set-navigation-bar-color.md

2.3.310.1 KB
Original Source
<!-- ## uni.setNavigationBarColor(options) @setnavigationbarcolor -->

::: sourceCode

uni.setNavigationBarColor(options) @setnavigationbarcolor

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-navigationBar

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-navigationBar

:::

设置导航条、状态栏颜色

setNavigationBarColor 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
4.04.414.114.615.0

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

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

参数

名称类型必填默认值兼容性描述
optionsSetNavigationBarColorOptions-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
frontColorstring-Web: 4.0; 微信小程序: 4.41; Android: √; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #000000
backgroundColorstring.ColorString-Web: 4.0; 微信小程序: 4.41; Android: √; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0背景颜色值,有效值为十六进制颜色
success(result: SetNavigationBarColorSuccess) => void-Web: 4.0; 微信小程序: 4.41; Android: √; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0接口调用成功的回调函数
fail(error: SetNavigationBarColorFail) => void-Web: 4.0; 微信小程序: 4.41; Android: √; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0接口调用失败的回调函数
complete(res: SetNavigationBarColorComplete) => void-Web: 4.0; 微信小程序: 4.41; Android: √; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0接口调用结束的回调函数(调用成功、失败都会执行)
animationSetNavigationBarColorOptionsAnimation-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -动画效果
frontColor 的属性描述
合法值兼容性描述
#ffffffWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: --
#000000Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: --
animation 的属性描述
名称类型必备默认值兼容性描述
durationnumber-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -动画变化时间,单位 ms
timingFuncstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -动画变化方式

可选值:

  • 'linear': 动画从头到尾的速度是相同的;
  • 'easeIn': 动画以低速开始;
  • 'easeOut': 动画以低速结束;
  • 'easeInOut': 动画以低速开始和结束; |
timingFunc 的属性描述
合法值兼容性描述
linearWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: --
easeInWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: --
easeOutWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: --
easeInOutWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: --

SetNavigationBarColorSuccess 的属性值 @setnavigationbarcolorsuccess-values

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

SetNavigationBarColorFail 的属性值 @setnavigationbarcolorfail-values

名称类型必备默认值兼容性描述
errCodenumber-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -设置导航栏字体颜色错误码
  • 4: 框架内部异常 | | errSubject | string | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 统一错误主题(模块)名称 | | data | any | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 错误信息中包含的数据 | | cause | Error | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 源错误信息,可以包含多个错误,详见SourceError | | errMsg | string | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | |

SetNavigationBarColorComplete 的属性值 @setnavigationbarcolorcomplete-values

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

返回值

类型必备
Promise<SetNavigationBarColorSuccess>

Promise<SetNavigationBarColorSuccess> 的属性描述

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/set-navigation-bar-color/set-navigation-bar-color

appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/set-navigation-bar-color/set-navigation-bar-color

示例

vue
<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/navbar-lite/navbar-lite'
    })
  }

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

:::

参见

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息

Bug & Tips @tips

  • app-android平台,受系统限制,通过frontColor修改状态栏前景色仅在Android6.0及以上版本生效。