@wu529778790/site-navbar

v0.1.20

Published

8 days ago

A zero-dependency site top navigation web component: glass sub-site links with auto current-host highlight, responsive hamburger menu, and a runtime-loaded always-latest user avatar.

0High
0Medium
0Low

wu529778790

navbar navigation header menu avatar web-component glass top-nav 子站导航顶部导航导航栏响应式菜单

@wu529778790/site-navbar

顶部站点导航组件：内置 shenzjd.com 系列子站链接，按当前 host 自动高亮当前站；桌面端居中链接 + 右侧头像，移动端（<768px）折叠为 hamburger 下拉菜单。头像运行时动态加载 <user-avatar> Web Component（默认 unpkg @latest），user-avatar 发版后自动跟上，无需重新发布本组件。

适用于个人站群、博客、文档站等需要「统一导航 + 账号登录」的页面。

特性

🧭 内置 shenzjd.com 系列子站链接（AI情报局 / 网盘搜索 / 视频解析 / 流量卡 / Git 图床 / 导航森林 / 免费生图），可用 links 覆盖
🎯 按 location.hostname 自动高亮当前站（host 精确匹配，匹配不上则不高亮任何链接），也可用 active 强制指定；高亮样式仅为文字变色
👤 内置 user-avatar（微信登录头像）：运行时动态加载最新版 Web Component，头像组件发版即自动生效，导航栏无需跟随发版
📱 移动端（<768px）折叠为 hamburger 下拉菜单，position: fixed portal 挂载，玻璃拟态
🌗 默认深浅色自动适配（light-dark()）：宿主页面声明 color-scheme: light / dark 时跟随宿主配色，未声明时跟随系统，无需任何配置
📏 导航栏自带底部分隔线（--sn-border 控制，随深浅色切换），无需宿主额外画线
🎨 CSS 变量主题化（--sn-*），一行覆盖主色 / 强调色 / 背景 / 圆角（显式指定后固定使用，不随系统切换）
📦 NPM + CDN 双通道引入，TypeScript 类型齐全

安装

pnpm add @wu529778790/site-navbar
# 或 npm i @wu529778790/site-navbar / yarn add @wu529778790/site-navbar

快速开始（推荐 · Web Component）

方式一：CDN 一行引入（零配置，自动出现整条导航）

<!-- 只需引入本组件一条 JS：wx-auth-sdk 由组件内部自动加载并静默 init，
     无需手动引入 SDK、也无需写 WxAuth.init() -->
<script src="https://unpkg.com/@wu529778790/site-navbar@latest/dist/site-navbar.wc.js"></script>

<!-- 页面放一个标签即出现整条导航 -->
<site-navbar></site-navbar>

备选 CDN（GitHub 镜像，push 即生效）：https://cdn.jsdmirror.com/gh/wu529778790/components@main/cdn/site-navbar.wc.js

方式二：声明式属性

<site-navbar
  brand="我的导航"
  brand-icon="🧭"
  avatar="false"          <!-- 不需要头像时 -->
  theme-accent="#e04040"  <!-- 强调色 -->
  >
</site-navbar>

方式三：全局配置（复杂参数：自定义链接、主题）

<script>
  window.__SITE_NAVBAR_OPTIONS__ = {
    links: [
      { href: 'https://shenzjd.com', label: 'AI情报局', icon: '🏠' },
      { href: 'https://panhub.shenzjd.com', label: '网盘搜索', icon: '🔍' }
    ],
    brand: { text: '我的导航', icon: '🧭' },
    theme: { accent: '#1a6dff' }
  }
</script>
<script src="https://unpkg.com/@wu529778790/site-navbar@latest/dist/site-navbar.wc.js"></script>

方式四：NPM 双轨（React/Vue 项目）

import { SiteNavbar } from '@wu529778790/site-navbar'

const nav = new SiteNavbar({
  links: [
    { href: 'https://shenzjd.com', label: 'AI情报局', icon: '🏠' },
    { href: 'https://panhub.shenzjd.com', label: '网盘搜索', icon: '🔍' }
  ],
  brand: { text: '我的导航', icon: '🧭' },
  onNavigate: (link, e) => console.log('点击', link.label)
})
nav.mount(document.body)

// 卸载
nav.unmount()

Web Component 属性

<site-navbar> 全部属性均可选，不设即用默认值。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | brand | string | — | 品牌文本（显示在导航左侧） | | brand-icon | string | — | 品牌图标（emoji / SVG / 任意 HTML） | | avatar | boolean | true | 是否渲染头像（user-avatar） | | avatar-src | string | unpkg @latest | 运行时加载的 <user-avatar> 脚本地址（如指向自身 CDN） | | links | string | 内置默认 | JSON 数组字符串，如 [{"href":"...","label":"..."}] | | wx-auth-enabled | boolean | true | 是否自动加载并初始化 wx-auth-sdk（false 关闭，需自行引入 SDK 并 init） | | theme-primary | string | 随系统* | 主文字色（品牌 / hover 文字） | | theme-secondary | string | 随系统* | 次要文字色（默认链接） | | theme-accent | string | 随系统* | 强调色（当前站高亮） | | theme-hover-bg | string | 随系统* | hover 背景（现仅 hamburger 按钮使用，链接 hover 已改为纯文字变色） | | theme-bg | string | 随系统* | 保留参数（当前站高亮已改为纯文字变色，不再使用背景，暂无样式作用） | | theme-border | string | 随系统* | 边框 / 分隔线色 | | theme-radius | string | 12px | 圆角 | | theme-font-family | string | 系统字体栈 | 字体族 |

* 颜色类主题默认值自动适配深浅色：浅色 #1f2328 / #656d76 / #1a6dff / rgba(255,255,255,.55) …，深色 #e6edf3 / #8b949e / #4d9fff / rgba(28,31,36,.55) …。取色规则：宿主页面声明 color-scheme: light / dark 时跟随宿主，未声明时跟随系统。显式传入某个 theme-* 属性后该值固定使用，不再随系统切换。

样式已隔离在 shadow DOM，外部可用 --sn-* 变量覆盖（见下文「自定义主题」）。

JS API（NPM 双轨）

`new SiteNavbar(options, container?)`

所有参数均可选，不传即用默认值，new SiteNavbar() 即可。

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | links | SiteNavbarLink[] | 内置默认 | 链接列表 | | brand | SiteNavbarBrand \| null | null | 品牌区（不传不渲染，链接纯居中） | | avatar | boolean | true | 是否渲染头像 | | avatarOptions | SiteNavbarAvatarOptions | — | 透传给 user-avatar（fixed 强制为 false 以嵌入导航栏）；src 可覆盖头像脚本地址 | | theme | SiteNavbarTheme | 默认主题 | 主题（映射 --sn-* 变量） | | breakpoint | number | 768 | 移动端断点（px） | | portalEl | HTMLElement | document.body | 移动菜单 portal 挂载容器（通常无需配置） | | onNavigate | (link, event) => void | — | 点击导航链接回调 | | wxAuth | WxAuthBootstrapOptions | {} | wx-auth-sdk 自举配置（默认零配置即可用，见下文「wx-auth-sdk 自举」） |

链接 `links`

| 字段 | 类型 | 说明 | | --- | --- | --- | | href | string | 完整链接地址（必填） | | label | string | 显示文本（必填） | | icon | string | 图标（emoji / SVG / 任意 HTML），可选 | | active | boolean | 强制高亮为当前站（不传则按 location.hostname 自动匹配） |

品牌 `brand`

| 字段 | 类型 | 说明 | | --- | --- | --- | | icon | string | 品牌图标（emoji / SVG / 任意 HTML），可选 | | text | string | 品牌名称 | | href | string | 点击跳转地址（默认跳当前站首页；同站 _self 跳转，跨站自动 _blank） |

实例方法

| 方法 | 说明 | | --- | --- | | mount(target?) | 挂载到页面（缺省挂到构造时传入的 container） | | unmount() | 卸载并销毁（解绑事件、移除 portal 菜单） | | destroy() | 同 unmount() | | static check() | 环境检查：头像 SDK 缺失时返回提示（不影响导航本体渲染） |

头像（user-avatar）：始终最新，无需联动发版

右侧头像不再打包进本组件，而是运行时动态加载 <user-avatar> Web Component（默认 https://unpkg.com/@wu529778790/user-avatar@latest/dist/user-avatar.wc.js）：

自动跟随最新版：user-avatar 每次发版（push 到 main 后 CI 自动发布 npm），所有接入站点的导航栏头像即刻用上新版，site-navbar 无需重新构建/发布；
已加载则不重复加载：页面已引入 user-avatar.wc.js 或聚合版 widgets.js 时，导航栏直接复用已注册的元素；
失败不影响导航：头像脚本加载失败（如内网无外网）只会在控制台告警并留空头像区，导航本体不受影响；
可指定脚本地址：国内直连 unpkg 慢、或希望锁定版本时，用 avatarOptions.src（JS API）或 avatar-src 属性覆盖：

<site-navbar avatar-src="https://cdn.jsdmirror.com/gh/wu529778790/components@main/cdn/user-avatar.wc.js"></site-navbar>

登录能力依赖 wx-auth-sdk，已由组件内部自动加载并静默 init（见下文「wx-auth-sdk 自举」），使用方无需任何额外处理。

wx-auth-sdk 自举（一条 JS 全搞定）

组件默认自动加载并初始化 wx-auth-sdk，使用方只需引入 site-navbar.wc.js 一条 JS，无需手动引入 SDK、也无需写 WxAuth.init()：

自动加载：若 window.WxAuth 尚不存在，组件动态注入 wx-auth.umd.js（默认 unpkg @latest）；
就绪等待：轮询等待 window.WxAuth 就绪（每 100ms，默认 10s 超时），彻底规避「SDK 用 defer 延迟加载、init 立即执行」导致的 ReferenceError 竞态；
静默校验：就绪后自动调用 WxAuth.init({ silent: true, required: false })——只静默校验登录态、绝不自动弹登录窗，弹窗可关闭；
失败降级：SDK 加载失败或超时仅 console.warn，导航栏照常渲染、绝不抛错、绝不阻塞页面；
幂等：全页共享一次加载，多实例导航栏不会重复注入脚本或重复 init；
兼容已有 init：若使用方已自行引入 SDK 并 WxAuth.init()，组件不会重复 init（SDK 文档建议只 init 一次），只确保 SDK 存在即可，绝不覆盖使用方的初始化、绝不阻塞。

可配置入口（默认零配置即可用）

<!-- 全局配置：自定义 SDK 地址 / init 参数 / 回调 -->
<script>
  window.__SITE_NAVBAR_OPTIONS__ = {
    wxAuth: {
      src: 'https://cdn.jsdmirror.com/gh/wu529778790/wx-auth-sdk@latest/dist/wx-auth.umd.js',
      initOptions: { silent: true, required: false },
      onReady: (sdk) => console.log('SDK 就绪'),
      onError: (reason) => console.warn('SDK 加载失败', reason)
    }
  }
</script>
<script src="https://unpkg.com/@wu529778790/site-navbar@latest/dist/site-navbar.wc.js"></script>

<!-- 属性：关闭自动加载（此时需自行引入 SDK 并 init） -->
<site-navbar wx-auth-enabled="false"></site-navbar>

// JS API：自定义自举行为
new SiteNavbar({
  wxAuth: { enabled: true, timeout: 15000 }
})

WxAuthBootstrapOptions 字段：

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | src | string | unpkg @latest | SDK 脚本地址 | | enabled | boolean | true | 是否自动加载并初始化 SDK | | initOptions | object | { silent: true, required: false } | 传给 WxAuth.init 的参数 | | pollInterval | number | 100 | 轮询间隔（ms） | | timeout | number | 10000 | 就绪等待超时（ms） | | onReady | (sdk) => void | — | SDK 就绪并 init 完成后的回调 | | onError | (reason) => void | — | 加载失败 / 超时后的回调 |

自定义主题

组件通过 CSS 变量暴露主题，直接在宿主页面覆盖即可（默认值随系统深浅色自适应，覆盖后固定使用你的颜色）：

site-navbar {
  --sn-primary: #1f2328;        /* 主文字色 */
  --sn-secondary: #656d76;      /* 次要文字色 */
  --sn-accent: #1a6dff;         /* 强调色（当前站高亮） */
  --sn-hover-bg: rgba(31,35,40,.06); /* hover 背景（现仅 hamburger 按钮使用） */
  --sn-bg: rgba(255,255,255,.55);    /* 保留变量（当前无样式作用） */
  --sn-border: rgba(27,31,36,.08);  /* 边框 / 底部分隔线 */
  --sn-radius: 12px;            /* 圆角 */
  --sn-font-family: -apple-system, ...; /* 字体族 */
}

防闪烁（FOUC）与布局稳定

组件默认已处理：

Web Component 未定义时的占位：<site-navbar> 是未知元素时高度为 0，等 JS 加载、组件注册、渲染后才撑出高度，页面内容会被突然往下推（"闪一下"）。组件在注册时自动注入一条全局样式：
```
site-navbar:not(:defined) { display: block; height: var(--sn-navbar-height, 44px); }
```
从页面首帧起 <site-navbar> 就占位 44px（与导航栏实际渲染高度 43.7px 对齐，加载后不会回跳），组件升级后由自身接管渲染，占位自动失效。
移动端菜单不占布局：菜单以 position: fixed 挂到 body，任何时刻都脱离文档流（无论开/关），不会在页面底部撑出空白。

接入方可选（彻底消除 JS 下载期间的闪烁）：

如果希望 JS 下载期间页面也纹丝不动，可在 <head> 里直接写一条 CSS（不依赖 JS 加载）：

<style>
  site-navbar:not(:defined) { display: block; height: 44px; }
</style>

导航栏实际高度默认 44px；若你自定义了导航栏高度（如增大内边距），请同步调整该值，或用变量 --sn-navbar-height 覆盖。

在线演示

https://blog.shenzjd.com/components/packages/site-navbar/demo/

本地演示

pnpm build            # 仓库根目录执行，产出 dist/
pnpm preview          # 启动静态服务器 http://localhost:8317

浏览器打开 http://localhost:8317/packages/site-navbar/demo/index.html，顶部即导航组件实时样式；把窗口缩到 768px 以下看移动端菜单。

浏览器兼容

现代浏览器（Chrome / Firefox / Safari / Edge），无 IE 支持计划。

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@wu529778790/site-navbar

特性

安装

快速开始（推荐 · Web Component）

方式一：CDN 一行引入（零配置，自动出现整条导航）

方式二：声明式属性

方式三：全局配置（复杂参数：自定义链接、主题）

方式四：NPM 双轨（React/Vue 项目）

Web Component 属性

JS API（NPM 双轨）

new SiteNavbar(options, container?)

链接 links

品牌 brand

实例方法

头像（user-avatar）：始终最新，无需联动发版

wx-auth-sdk 自举（一条 JS 全搞定）

可配置入口（默认零配置即可用）

自定义主题

防闪烁（FOUC）与布局稳定

在线演示

本地演示

浏览器兼容

License

`new SiteNavbar(options, container?)`

链接 `links`

品牌 `brand`