--- title: "使用看板：参数配置、实时预览与菜单栏常驻 · Metrix.Bar" description: "了解如何在 Metrix.Bar 中使用看板：配置 API 参数与密钥、预览面板效果、常驻至菜单栏或托盘，以及导入导出 .bar 文件。" canonical: "https://metrix.bar/zh/docs/dashboards" language: "zh-CN" --- # 使用看板 > 官方看板使用指南、参数配置、外观预览、菜单栏常驻与 .bar 文件导入导出。 ## 概述 在 Metrix.Bar 中，所有监控与指标均以看板（Dashboard）为单位进行组织。一个看板封装了数据查询、业务逻辑、菜单栏指标与弹出面板。无需手动拼装界面画布，开箱即用。 ## 挑选看板 打开 Metrix.Bar，应用展示当前已添加的看板以及官方看板源目录（按分类分组）。App 仅内置 GitHub 仓库看板，其余 13 个官方看板按需从[官方看板源](/zh/docs/registries)安装。 - **AI**：Claude Code 用量、Codex 用量。 - **统计与图表**：Umami、Plausible、PostHog、Rybbit、Dub 短链分析、Sink。 - **开发**：GitHub 仓库指标。 - **天气**：天气。 - **金融**：加密货币行情、加密钱包、股指。 完整索引发布在 [metrix.bar/dashboards/index.json](/dashboards/index.json)，也可在[看板库](/zh/gallery)中浏览。你也可以导入由同事分享或 AI Agent 编写的任何 `.bar` 格式看板文件。 ## 配置输入项 每个看板都会声明运行所需的配置项。当打开需要初始配置的看板时，应用会自动生成参数表单： | 输入类型 | 说明 | 存储与保护方式 | | -------------------- | -------------------------------------------- | --------------------------------------------------------- | | `string` | 单行文本（如仓库全名 `owner/name`、站点 ID） | 保存在本地应用配置中 | | `integer` / `number` | 数值（如阈值、端口） | 保存在本地应用配置中 | | `bool` | 开关复选框 | 保存在本地应用配置中 | | `select` | 预设选项下拉框 | 保存在本地应用配置中 | | `secret` | API 密钥、密码、私密 Token | 保存在系统安全凭据库中；看板可读取以完成服务认证 | | `file` | 本地凭证文件路径（如 `~/.codex/auth.json`） | 仅在权限声明（``）允许的路径范围内读取 | 如果存在未填写的必填项（`required`），看板会处于**等待配置**状态，不会发起无效的网络请求。 GitHub 仓库看板直接读取 GitHub REST API。公开仓库无需 Token，使用每小时 60 次的匿名额度，足够每 10 分钟刷新一个仓库；配置 Token 后额度更高，并可读取私有仓库。刷新失败时保留最近成功的数据并提供 Retry。 Umami 看板需填写 API 地址，以及 API 密钥或自托管 Umami 2 的用户名和密码。API 密钥优先；Umami Cloud 必须使用 API 密钥。 Rybbit 填写 `https://app.rybbit.io` 或自托管域名，以及具有 `analytics:read` 权限的个人 API key，即可自动加载各组织中有权访问的站点，并从列表切换查看站点详情。 Umami 和 Rybbit 可在当前显示网站的实时访客总数超过阈值时发送系统通知。在 Settings → Notifications 中开启通知，输入非负整数（默认 100），按 Enter 或点击 Save 生效。通知默认关闭；完整的新采样超过阈值后，持续超限只通知一次，完整采样的合计人数回落到阈值或以下后，再次超限可重新通知。无效或失败的实时人数不会触发通知或恢复通知资格。即使面板关闭，实时人数仍每分钟刷新。重新启动看板会重置通知去重状态。 ### 凭据安全管理 在 `secret` 字段输入密钥时： - 密钥将以该看板专属 ID 为标识写入系统安全凭据库中。 - 应用配置文件与导出的 `.bar` 单文件中绝不记录任何密钥明文。 - 你可以随时在参数设置页面更新或清除已保存的密钥。 ## 预览看板 选择看板入口前，可先预览： - **实时数据**：Metrix.Bar 自动运行看板 Worker，并将界面渲染为原生组件。 - **错误诊断**：若某个接口请求失败或数据异常，错误状态直接呈现在面板中，不会影响其他看板的运行。 ## 看板入口与打开方式 在看板设置中，可独立配置视觉入口、键盘快捷键与打开方式： - **五种来源独立开关与打开方式**：菜单栏（Menu Bar）、左侧 Sidebar（Left Sidebar）、右侧 Sidebar（Right Sidebar）、底部 Sidebar（Bottom Sidebar）与键盘快捷键（Keyboard Shortcut）五个触发来源均有独立的启用开关与打开方式选择（Flyout 或 Dialog）。同一个看板可设置菜单栏以 Flyout 打开，而快捷键与右侧 Sidebar 以 Dialog 打开。关闭某个视觉入口或禁用快捷键会保留其已配置的打开方式。 - **快捷键独立开关与录制**：在看板设置中，Keyboard Shortcut 行提供独立的启用开关与打开方式选择；其下方的独立 Shortcut 行承载按键绑定与录制（Record）/ 取消流程。即使菜单栏与三侧 Sidebar 全部关闭，快捷键仍可独立唤出面板，且在错误态下仍可编辑。 屏幕 Sidebar 独立于主窗口的导航侧栏： - **单次只展开触发方向**：触发左、右或底部外缘热区时，任意时刻最多在当前屏幕展开对应的那一侧 rail（最多一个屏幕、一个方向 rail），不同时展开多侧；指针切换到另一侧时先移除旧栏再创建目标栏。 - **贴边触发与驻留保持**：屏幕 Sidebar 为贴屏边的深色胶囊（固定深色背景，不随系统浅色模式改变）。平时完全隐藏；贴死右侧或底侧边缘即可触发（左右触发区位于高度 25%～75% 的区域，底部触发区位于底边宽度 25%～75% 的区域，厚度均为 2 DIP），指针停留约 100 ms 展开，多屏相接的内缝不会触发。展开时从屏幕边缘滑入，收起时滑出；在系统 Reduce Motion（减少动态效果）偏好下无动画，即时显隐。指针在当前侧有效触发热区内驻留时持续保持展开，即使落在短 rail 外侧也不会闪烁或收起；离开有效保持区（当前侧有效热区、rail、tooltip、面板、连接通道与菜单）300 ms 后收起。App 处于非前台状态时，Sidebar 贴边展开与图标悬停同样可以正常响应。 - **外观与排布**：Sidebar 只显示图标。底栏横向排列图标，溢出时横向滚动，tooltip 显示在图标上方。悬停提示只显示单行核心数值，优先显示托盘标题（`tray.title`），缺省时依次使用托盘提示（`tray.tooltip`）、看板名称，不显示标题行；图标依次使用托盘图标、看板图标、通用看板 glyph。指标数值由看板格式化。Sidebar 窗口请求显示在系统栏上方，底栏可能与 Dock 或任务栏位于同一区域。 - **图标拖动排序与菜单栏联动**：在屏幕 Sidebar 内按住平台主修饰键（macOS Cmd，Windows/Linux Ctrl）拖动图标可直接重排顺序，并写入全局看板顺序，首页、其他 Sidebar 和主窗口左栏各分组内同步跟随；拖动仅调整当前栏可见看板之间的相对位置，松手前先松开修饰键或拖回原位即可取消。在 macOS 上按住 Cmd 拖动菜单栏中的 Metrix.Bar 图标后，看板顺序会在下次展开 Sidebar 或刷新主窗口时单向跟随（Windows 与 Linux 托盘顺序由系统决定，不同步）。 Dialog 与 Flyout 呈现： - **Flyout**：从所点入口向屏幕内侧展开，底栏 Flyout 向上展开。点击 Sidebar 图标打开 Flyout 时，macOS 使用系统 Popover，箭头指向被点击图标（左栏向右、右栏向左、底栏向上），Flyout 打开期间侧栏保持展开；Windows 与 Linux 使用无箭头的 Flyout。 - **高透明遮罩与居中呈现**：Dialog 在当前显示器完整 Bounds 上展示遮罩并居中展示看板内容，不进入系统全屏 Space。遮罩采用约 12% 黑色的高透明遮罩（系统高对比度模式下为约 40% 黑色）；内容卡片带圆角与阴影。 - **无关闭按钮与四侧 10% 间隙**：界面无“X”关闭按钮。内容请求尺寸由看板决定，默认 320×480 DIP。左右边距各至少为屏幕宽度的 10%，上下边距各至少为屏幕高度的 10%，内容区域宽高最多为屏幕宽高的 80%，超大内容内部滚动；内容尺寸动态变化不会缩小遮罩外壳。 - **交互与关闭**：点击内容外或按 Esc 可关闭，内容内点击不关闭；有内部浮层时 Esc 优先关闭该浮层。Dialog 打开时 Sidebar 收起，关闭后需先离开边缘触发区再进入，才能重新唤出 Sidebar。 多个入口共享同一份数据与面板状态。已配置且可用的 Sidebar 即使收起仍保持刷新；没有可用入口、预览或打开的面板时，看板闲置，直到再次需要。你仍可通过主窗口或快捷键打开看板。右键入口可执行刷新、打开设置等操作；移除菜单栏入口不会关闭已启用的 Sidebar 入口。 ### 平台可用性 Linux 支持目标为 X11 及具备可用 gtk-layer-shell 库和协议的 Wayland。GNOME 原生 Wayland，或因缺库、缺协议而无法原生定位屏幕的会话，会禁用 Sidebar 并说明原因。Dialog 同样需要原生屏幕定位能力，不可用时明确提示，不以普通浮窗替代。注意：Windows 与 Linux 桌面 GUI 实机验收仍待完成。 ## 本地 API 自动化 Metrix.Bar 在 6387 端口提供本地回环 HTTP API，供命令行与 AI 代理自动化调用： - **立即刷新**：`POST /v0/dashboards/:id/refresh` 触发数据刷新。 - **发送事件**：`POST /v0/dashboards/:id/events/:name` 向看板 Worker 发送自定义事件。 - **读取快照**：`GET /v0/dashboards/:id` 获取看板当前状态与 UI 视图树。 ## 导入与导出 `.bar` 文件 所有看板均基于 `.bar` 单文件格式进行分发： - **导入**：将 `.bar` 文件置入 Dashboards 目录，或通过本地 HTTP API 直接创建。 - **导出**：导出的文件完整包含所有权限声明（网络源与本地文件路径）、输入参数定义与 Worker 脚本，但不包含任何敏感密钥，确保分享安全。