vue-mini-navbar

vue-mini-navbar

兼容 Vue2 / Vue3 / uni-app / 微信小程序原生 的小程序顶部距离信息插件，服务于「自定义顶部导航栏」布局场景。同步返回状态栏高度、胶囊按钮位置、导航栏高度、安全区等信息，结果自动本地缓存（二次调用零开销），TypeScript 编写。

自定义导航栏示例（uni-app）

真机效果（iPhone：状态栏 47px，底部安全区 34px，左侧返回胶囊与右上角胶囊同高对称）：

安装

npm install vue-mini-navbar

快速开始

Vue3（含 uni-app Vue3 项目）

// main.js
import { createApp } from 'vue'
import VueMiniNavbar from 'vue-mini-navbar'
import App from './App.vue'

createApp(App).use(VueMiniNavbar).mount('#app')

<script setup>
// 组合式 API
import { useTopBarInfo } from 'vue-mini-navbar'
const topBarInfo = useTopBarInfo()
const info = topBarInfo()
// 或选项式：this.$topBarInfo()
</script>

Vue2（含 uni-app Vue2 项目）

// main.js
import Vue from 'vue'
import VueMiniNavbar from 'vue-mini-navbar'

Vue.use(VueMiniNavbar)

// 任意组件中
// this.$topBarInfo()

微信小程序原生

// 无需 install，直接引入函数
import { getTopBarInfo } from 'vue-mini-navbar'

Page({
  data: { navBarHeight: 0, statusBarHeight: 0 },
  onLoad() {
    const info = getTopBarInfo()
    this.setData({
      statusBarHeight: info.statusBarHeight,
      navBarHeight: info.navBarHeight
    })
  }
})

API

getTopBarInfo(options?: { refresh?: boolean }): TopBarInfo

默认先读本地缓存（uni / wx storage），命中且校验通过直接返回；未命中则重新计算并写回本地。

• refresh: true：跳过缓存强制重算并覆盖本地，用于横竖屏切换、onResize 后

useTopBarInfo(): (options?) => TopBarInfo

组合式 API，行为与 getTopBarInfo 一致。

clearTopBarInfoCache(): void

清除本地缓存条目（调试用）。

computeTopBarInfo(): TopBarInfo

底层纯函数，跳过缓存直接计算（一般不直接使用）。

返回对象（TopBarInfo）

所有距离单位均为 px：

平台与缓存说明

• 环境探测优先级（与兄弟插件 vue-local-cache 一致）：窗口信息 uni.getWindowInfo() → uni.getSystemInfoSync() → wx.getWindowInfo() → wx.getSystemInfoSync() → H5 window 兜底；胶囊 uni.getMenuButtonBoundingClientRect() → wx.getMenuButtonBoundingClientRect()
• 本地缓存：key 为 vue-mini-navbar:topbar-info，结构带版本号 { v, data }，版本不匹配或数据损坏自动重新计算
• 容错风格：所有平台 API 调用 try/catch 静默兜底，任何字段取不到时给默认值，不抛错

License

MIT