--- title: ".bar 格式规范：v0 看板标准 · Metrix.Bar" description: "Metrix.Bar .bar v0 格式完整参考：根标签、网络权限、配置项、常驻 JavaScript Worker、生命周期钩子、宿主 API 与原生 UI 树。" canonical: "https://metrix.bar/zh/docs/bar-format" language: "zh-CN" --- # .bar 格式规范 > Metrix.Bar 单文件 .bar v0 看板规格说明。 ## 概述 `.bar` 文件是用于定义单个完整看板的声明式规范。单个文件整合了网络权限声明、用户配置项定义以及一个常驻的 JavaScript Worker，由 Worker 负责数据抓取、状态维护与原生托盘及面板界面的渲染。 - **单文件定义**：无需分离的布局文件或样式配置，一个文件即为一个独立看板。 - **常驻 Worker**：基于 ES Module 标准常驻后台运行，支持定时调度、本地持久化与异步取数。 - **原生 UI 树**：Worker 直接返回结构轻量的 JSON 树（`{type, props, children}`），直接映射为桌面原生组件。 - **ESM 库引入**：支持从白名单内的 CDN 动态导入 JavaScript 模块（如 `htm`）。 ## 文件结构 `.bar` 文档以根标签 `` 开头，包含声明权限、输入项、配置说明与脚本 Worker 的子块： ```bar ``` | 元素 | 是否必填 | 格式 | 用途 | | --------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------- | | `` | 是 | 属性声明 | 根定义：`protocol-version`、`id`、可选元数据以及刷新间隔 `refresh` | | `` | 否 | XML 标签 | 声明网络权限（`fetch`、动态 `import`）与本地文件读取权限（`$metrix.readFile`） | | `` | 否 | XML `` 标签 | 声明看板供用户配置的参数与安全密钥 | | `` | 否 | 纯文本 / CDATA | 供用户查看的纯文本配置与使用说明，展示在目录、应用界面与 API 中 | | ` ``` 再次调用 `open('archive')` 即可使用另一个独立数据库。每个看板最多 8 个持久命名库，每 Worker 最多 8 个连接、4 个待完成操作。每次操作最多 10 秒，且受所属 hook 的取消约束；每次执行或整个 batch 的 SQL 与参数合计最多 1 MiB，batch 最多 100 条语句；每次执行或整个 batch 合计最多 10,000 行及 8 MiB 结果（含结构开销），每个主库与内存临时库分别最多 32 MiB 数据页。所有看板共享 128 MiB SQLite 堆内存预算；这不是应用总内存上限，其他看板的查询可能占用这一共同预算。这里提供 D1 的常用 prepared statement 与 batch 接口，不包含 exec、dump、session、交互式事务或流式查询。预先打包的 `kysely@0.27.6` + `kysely-d1@0.4.0` 已通过真实 Worker 的建表和基础增删改查（含 RETURNING）验证。`kysely@0.28.18` 与 `0.29.7` 初始化会写入 `Symbol.asyncDispose`，当前 Worker 不支持；`kysely-d1` 自身也不支持交互式事务或流式查询。支持表、索引、JOIN 和聚合等 SQL 能力；用户 PRAGMA、ATTACH/DETACH、VACUUM、扩展加载、虚拟表及直接事务控制不可用。宿主在 Worker 关闭时释放连接。原生开发检查使用独立临时数据库并在结束后删除；浏览器 Playground / WASM Sandbox 不提供 SQLite。 ## ` ``` 有关主流 UI 构树库（如 Preact、Vue、React、Snabbdom 等）与状态管理库的搭配指南，请参考 [技术选型与推荐技术栈](/zh/docs/tech-stack.md)。 --- ## UI 树模型 `render(env)` 钩子返回的对象结构如下： - `tray`：菜单栏 / 系统托盘展示项： - `title`：直接显示在托盘上的简短文本。 - `icon`：系统图标名称或网络图标地址。 - `iconTemplate`：可选布尔值。设为 `true` 时在 macOS 强制启用系统 Template 模式（深色模式或高亮时自动反色）。 - `tooltip`：鼠标悬浮托盘图标时的提示文本。 - `menu`：托盘右键上下文菜单项数组。菜单项支持： - `label`：菜单项文本。 - `onClick`：点击触发的处理函数。 - `disabled`：布尔值，是否禁用。 - `separator`：布尔值，是否为分割线。 - `checked`：布尔值，显示勾选状态。 - `radio`：布尔值，单选标记（逻辑由脚本维护）。 - `shortcut`：快捷键提示（如 `"Cmd+Shift+P"`）。 - `tooltip`：浮动提示文本。 - `items`：递归嵌套的子菜单项数组。 - `panel`：点击托盘后弹出的面板内容树： - `type`：原生组件名称（见 [组件参考](/docs/components)）。 - `props`：组件属性与事件回调（如 `onClick`、`onChange`、`onSubmit`）。 - `key`：可选的稳定节点标识，在同级节点中必须唯一。作为 `activeDescendant` 或 `scrollWith` 目标的节点，其 key 还必须在面板内唯一。 - `children`：子节点数组。同一次 UI 构建收集的原生输入回调按顺序派发，批次开始执行后不会在回调之间插入渲染。每批最多 32 个回调；若执行前视图已被替换，旧回调仍可能过期。文本输入观察事件与节点引用详见[组件参考](/zh/docs/components)。 ## 桌面系统命令 `$metrix.system(command,args?)` 返回 Promise。在 `