> 做 Z-Blog 主题和插件的人，浏览器里永远开着一个 docs.zblogcn.com 的标签页。查接口列表、看模板标签、翻函数签名，一天要切过去十几次。问题来了：后台和文档两头切换，光标签页就要开一排，手一滑还容易关错。与其依赖浏览器书签，不如把文档入口直接钉进后台顶部导航——zb_DocsTopMenu 这个插件干的就是这件事，而且核心代码只有一次函数调用。

![image.png](https://developer.qcloudimg.com/http-save/yehe-12010127/207b077664130f7eec407830c2b93d0f.png)
## 一、接口在哪触发

zb_DocsTopMenu 挂的是 `Filter_Plugin_Admin_TopMenu` 接口。这个接口在后台每个页面组装顶部导航栏的时候触发，也就是说你访问后台任何一个页面，顶部菜单组装时插件回调都会被执行一次。

接口签名很简洁：`Filter_Plugin_Admin_TopMenu(arr &$topmenus)`。只有一个参数，`$topmenus` 是引用传入的数组，数组里每个元素都是一段完整的 `<li>` HTML 字符串。回调里直接往数组追加元素，追加进去的菜单项就会出现在顶栏。

关键在于：这些 `<li>` 字符串不是让你手拼的。Z-Blog 在 `c_system_admin.php` 里提供了一个官方构造函数：

```php
MakeTopMenu($requireAction, $strName, $strUrl, $strTarget, $strLiId, $strIconClass = '')
```

六个参数各自负责一件事：

| 参数 | 说明 |
|---|---|
| `$requireAction` | 权限动作，内部经 `$zbp->CheckRights()` 校验，无权限时返回空串，菜单项不显示 |
| `$strName` | 菜单显示名称 |
| `$strUrl` | 链接地址 |
| `$strTarget` | target 属性，留空 `_self` 当前窗口，`_blank` 新窗口 |
| `$strLiId` | `<li>` 元素的 id，留空自动生成 |
| `$strIconClass` | 图标类名（来自后台 `icon.css`），留空只显示文字 |

系统自己的"仪表盘""网站设置"这些顶栏菜单，全部是走这个函数构造的。插件要做的，就是在接口回调里用同样的函数构造自己的菜单项，追加到数组末尾。

接口的执行时机也有讲究：它在系统内置"仪表盘""网站设置"等菜单项之后、右侧"官方网站"等外部链接之前执行。所以插件加出来的菜单会落在顶部导航的中间区域，跟系统功能入口混在一起，位置观感是"这是后台的一部分"，而不是"这是插件硬塞进来的广告"。

## 二、插件做了什么

插件的完整实现，去掉注册和安装卸载外壳之后，就一个函数：

```php
function zb_DocsTopMenu_Add(&$topmenus)
{
    // 参数：权限动作、名称、链接、target、li 的 id、图标类名
    $topmenus[] = MakeTopMenu(
        'root',
        'Z-Blog 文档',
        'https://docs.zblogcn.com/',
        '_blank',
        'topmenu_zbdocs',
        'icon-book'
    );
}
```

六个参数逐个拆解：

**`'root'`——权限交给系统**。`MakeTopMenu` 的第一个参数是权限动作，函数内部会调用 `$zbp->CheckRights()` 校验。`'root'` 是管理员权限动作，意味着这个菜单项只有管理员登录后台时才显示。注意这一步完全没有在回调里手写权限判断——`MakeTopMenu` 把权限过滤做成了内建能力，你只管声明"这个菜单需要什么权限"，剩下的交给系统。无权限的用户访问后台时，这个函数直接返回空字符串，追加到数组里的就是个空串，渲染时什么都不输出，不需要你在回调里 if 一下再决定加不加。

**`'Z-Blog 文档'`——菜单文案**。直接写中文，后台是 UTF-8 环境，无需转码。

**`'https://docs.zblogcn.com/'`——链接**。指向 Z-Blog 官方文档站。想做企业内部文档入口的开发者，把这行换成自己的 wiki 地址即可。

**`'_blank'`——新窗口打开**。这是整个插件最贴合场景的设计决策：文档是查阅型资源，点开新窗口看完关掉，原来的后台页面状态完全不受影响。如果用当前窗口跳转，用户查完文档还得点浏览器返回键，后台页面上未保存的表单内容可能因此丢失。外链资源用 `_blank` 是后台菜单的基本礼仪。

**`'topmenu_zbdocs'`——li 的 id**。显式声明一个固定 id，方便自己写 CSS 微调样式（比如 `#topmenu_zbdocs a{color:#333}`），也方便排查菜单项是否渲染成功。留空的话系统会自动生成 id，但自动 id 不可预测，写样式定位不了。

**`'icon-book'`——图标**。来自后台自带的 `icon.css` 图标库，`icon-book` 是一本打开的书的图标，语义正好贴合"文档"。Z-Blog 后台内置了几十个常用图标，菜单项带图标后和系统"仪表盘""应用中心"等入口的视觉风格完全统一。

注册部分是标准套路：

```php
function ActivePlugin_zb_DocsTopMenu()
{
    Add_Filter_Plugin('Filter_Plugin_Admin_TopMenu', 'zb_DocsTopMenu_Add');
}
```

插件激活时把回调函数注册到 `Filter_Plugin_Admin_TopMenu` 这个钩子上，之后后台每个页面的顶栏组装都会带上这个菜单项。

## 三、实际怎么用

### 场景 1：安装即用，顶栏多一个文档图标

插件不需要任何配置，启用后后台每个页面的顶部导航会多出一项"Z-Blog 文档"，带书本图标。点击在新窗口打开官方文档站。因为权限动作是 `'root'`，只有管理员能看到，普通投稿作者的后台顶栏保持原样。

### 场景 2：改造为企业内部导航

这个插件的骨架稍加修改就能变成团队内部工具导航。比如给顶栏加内部 wiki、需求管理、运维面板三个入口：

```php
function myplugin_Add(&$topmenus)
{
    $topmenus[] = MakeTopMenu('root', '内部 Wiki', 'https://wiki.example.com/', '_blank', 'topmenu_wiki', 'icon-book');
    $topmenus[] = MakeTopMenu('root', '需求看板', 'https://board.example.com/', '_blank', 'topmenu_board', 'icon-list-ul');
    $topmenus[] = MakeTopMenu('root', '运维面板', 'https://ops.example.com/', '_blank', 'topmenu_ops', 'icon-tools');
}
```

每个入口配一个独立 id 和一个语义化图标，一次性把团队常用内部系统全钉进顶栏。权限统一用 `'root'`，也可以按需混搭：给编辑用的入口用 `'ArticleAll'`（文章管理权限），给管理员的用 `'root'`，不同角色看到的导航自然不同，而且你一行权限判断代码都不用写。

### 场景 3：加一个指向后台自身页面的快捷入口

`MakeTopMenu` 不只可以放外链，也可以放站内后台页面的深度链接。比如你经常要用"用户管理"页，但它在侧栏折叠区，找起来麻烦：

```php
$topmenus[] = MakeTopMenu(
    'MemberMng',
    '用户管理',
    $zbp->host . 'zb_system/cmd.php?act=MemberMng',
    '_self',
    'topmenu_member',
    'icon-person-lines-fill'
);
```

链接用 `$zbp->host` 拼出站内后台地址，target 用 `_self` 当前窗口跳转（站内后台页之间切换用当前窗口更顺手），权限动作直接写 `'MemberMng'`——有用户管理权限的人才看得到这个入口。这个思路可以把任何深藏在侧栏或者需要多次点击才能到达的后台功能提升为一级顶栏入口。

## 四、注意点

**1. 不要绕过 MakeTopMenu 手拼 HTML**

初学者看到 `$topmenus` 就是字符串数组，容易直接往里塞自己拼的 `<li><a href="...">xxx</a></li>`。能跑，但你会同时失去三样东西：权限过滤（`CheckRights` 逻辑在 `MakeTopMenu` 内部）、当前项高亮（系统靠 id 匹配当前页面给菜单加高亮类）、id 规范（自动生成的 id 有统一格式，主题 CSS 依赖这些格式）。手拼的 HTML 在权限过滤和高亮两方面都是裸奔的——不该看到菜单的用户看到了，点了菜单可能又因权限不足被拦截，体验稀碎。除非你对后台 HTML 结构烂熟于心，否则永远用 `MakeTopMenu`。

**2. 菜单项数量克制，外链务必新窗口**

顶栏是稀缺资源，横向空间有限，菜单项加到七八个就会在窄屏下溢出换行，破坏后台布局。实用建议：顶栏新增项控制在 3 个以内，书签类需求（比如 zb_SidebarBookmarks 那种几十条链接的场景）应该放侧栏而不是顶栏。另外外链一律 `'_blank'`，这是硬规矩：当前窗口跳外链等于把用户踢出后台，表单未保存内容可能丢失，用户回流还得靠浏览器返回键，每一环都是糟糕体验。

**3. 权限动作字符串要写系统真实存在的**

`$requireAction` 传给 `CheckRights()` 校验，这个动作名必须是系统注册过的权限动作（`'root'`、`'ArticleAll'`、`'ArticleEdt'`、`'MemberMng'`、`'CategoryMng'` 这类）。如果你随手编一个不存在的动作名，`CheckRights` 校验不通过，`MakeTopMenu` 会返回空串——菜单项静默消失，不报错不提示，排查起来非常迷惑："代码明明在跑，菜单怎么就是不出来？"遇到这种情况，第一步就是检查权限动作名拼写。想看系统有哪些权限动作，翻 `zb_system/function/c_system_event.php` 或官方文档的权限动作列表。

## 五、代码仓库

**仓库地址**：https://cnb.cool/ytecn/zblog-interfaces
**插件目录**：`zb_DocsTopMenu/`

---

「Z-Blog 接口插件集」系列第 2 个插件。

做 Z-Blog 主题和插件的人，浏览器里永远开着一个 docs.zblogcn.com 的标签页。查接口列表、看模板标签、翻函数签名，一天要切过去十几次。问题来了：后台和文档两头切换，光标签页就要开一排，手一滑还容易关错。与其依赖浏览器书签，不如把文档入口直接钉进后台顶部导航——zb_DocsTopMenu 这个插件干的就是这件事，而且核心代码只有一次函数调用。

把Z-Blog PHP官方文档钉在后台顶栏，用一行调用给 Z-Blog 顶部菜单添个常驻入口

开发工具

编程语言

将Z-Blog文档站入口直接集成到后台顶部导航，告别标签页来回切换。插件基于Filter_Plugin_Admin_TopMenu接口，通过官方MakeTopMenu函数一行代码实现，支持权限控制、图标显示与新窗口打开。管理员登录后每个后台页面均可见书本图标菜单，点击直达官方文档。源码简洁规范，适合开发者二次改造为企业内部工具导航入口。

代码解释

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

将Z-Blog文档站入口直接集成到后台顶部导航，告别标签页来回切换。插件基于Filter_Plugin_Admin_TopMenu接口，通过官方MakeTopMenu函数一行代码实现，支持权限控制、图标显示与新窗口打开。管理员登录后每个后台页面均可见书本图标菜单，点击直达官方文档。源码简洁规范，适合开发者二次改造为企业...

把Z-Blog PHP官方文档钉在后台顶栏，用一行调用给 Z-Blog 顶部菜单添个常驻入口-腾讯云开发者社区-腾讯云

把Z-Blog PHP官方文档钉在后台顶栏，用一行调用给 Z-Blog 顶部菜单添个常驻入口

把Z-Blog PHP官方文档钉在后台顶栏，用一行调用给 Z-Blog 顶部菜单添个常驻入口

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐