uni-app 之 设置导航

uni-app 提供了一系列 API 来动态设置页面导航栏的样式和状态，帮助开发者创建更丰富的用户界面体验。

1. uni.setNavigationBarTitle(OBJECT)

动态设置当前页面的标题

参数说明

属性	类型	必填	说明
title	string	是	页面标题
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数

示例代码

uni.setNavigationBarTitle({
  title: "新的页面标题",
});

2. uni.setNavigationBarColor(OBJECT)

设置页面导航条颜色

参数说明

属性	类型	默认值	必填	说明
frontColor	string		是	前景颜色值，包括按钮、标题、状态栏的颜色，仅支持 #ffffff 和 #000000
backgroundColor	string		是	背景颜色值，有效值为十六进制颜色
animation	object		否	动画效果
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

animation 参数说明

属性	类型	默认值	说明
duration	number	0	动画变化时间，默认为 0，单位：毫秒
timingFunc	string	'linear'	动画变化方式，支持 linear、easeIn、easeOut、easeInOut

示例代码

// 设置导航栏颜色
uni.setNavigationBarColor({
  frontColor: "#ffffff",
  backgroundColor: "#007AFF",
  animation: {
    duration: 400,
    timingFunc: "easeIn",
  },
});

3. uni.showNavigationBarLoading(OBJECT)

在当前页面显示导航条加载动画

参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数

示例代码

// 显示导航栏加载动画
uni.showNavigationBarLoading();

4. uni.hideNavigationBarLoading(OBJECT)

隐藏导航条加载动画

参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数

示例代码

// 隐藏导航栏加载动画
uni.hideNavigationBarLoading();

5. uni.hideHomeButton(OBJECT)

隐藏返回首页按钮

参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数

示例代码

// 隐藏返回首页按钮
uni.hideHomeButton();

完整示例

export default {
  data() {
    return {
      pageTitle: "商品详情",
    };
  },

  onLoad() {
    // 设置页面标题
    uni.setNavigationBarTitle({
      title: this.pageTitle,
    });

    // 设置导航栏颜色
    uni.setNavigationBarColor({
      frontColor: "#ffffff",
      backgroundColor: "#007AFF",
    });
  },

  methods: {
    // 页面数据加载
    loadData() {
      // 显示导航栏加载动画
      uni.showNavigationBarLoading();

      // 模拟异步请求
      setTimeout(() => {
        // 隐藏导航栏加载动画
        uni.hideNavigationBarLoading();

        // 更新页面标题
        uni.setNavigationBarTitle({
          title: "最新商品详情",
        });
      }, 2000);
    },

    // 改变导航栏主题
    changeTheme(theme) {
      if (theme === "light") {
        uni.setNavigationBarColor({
          frontColor: "#000000",
          backgroundColor: "#ffffff",
        });
      } else if (theme === "dark") {
        uni.setNavigationBarColor({
          frontColor: "#ffffff",
          backgroundColor: "#007AFF",
        });
      }
    },

    // 隐藏返回首页按钮
    hideHomeButton() {
      uni.hideHomeButton({
        success: () => {
          console.log("返回首页按钮已隐藏");
        },
      });
    },
  },
};

页面配置方式

除了使用 API，也可以在页面的 .vue 文件中通过配置来设置导航栏：

export default {
  style: {
    navigationBarTitleText: "页面标题",
    navigationBarBackgroundColor: "#007AFF",
    navigationBarTextStyle: "white",
    navigationStyle: "default", // 'default' 或 'custom'
  },
};

注意事项

1. frontColor 仅支持 #ffffff 和 #000000 两种颜色值
2. backgroundColor 必须是有效的十六进制颜色值
3. 在 Android 平台上，某些机型可能不支持动态修改导航栏颜色
4. hideHomeButton 仅在微信小程序等特定平台有效
5. 导航栏加载动画在不同平台的表现可能略有差异
6. 页面跳转时，导航栏设置会恢复为页面配置中的默认值
7. 使用 custom 导航栏样式时，需要自行实现导航栏布局

实际应用场景

// 商品详情页示例
export default {
  methods: {
    async loadProductDetail(productId) {
      // 显示加载状态
      uni.showNavigationBarLoading();
      uni.setNavigationBarTitle({ title: "加载中..." });

      try {
        const product = await this.fetchProduct(productId);

        // 加载完成后更新标题
        uni.setNavigationBarTitle({
          title: product.name,
        });

        // 根据商品状态改变导航栏颜色
        if (product.status === "onsale") {
          uni.setNavigationBarColor({
            frontColor: "#ffffff",
            backgroundColor: "#4CD964", // 绿色表示在售
          });
        } else {
          uni.setNavigationBarColor({
            frontColor: "#000000",
            backgroundColor: "#FF9500", // 橙色表示缺货
          });
        }
      } catch (error) {
        uni.setNavigationBarTitle({ title: "加载失败" });
        uni.showToast({ title: "获取商品信息失败", icon: "none" });
      } finally {
        uni.hideNavigationBarLoading();
      }
    },
  },
};