文档 / API 参考

API 参考

brk 的全部能力都集中在 brk 命名空间下, 一共 10 项:2 个组件、2 个导航方法、1 个加载方法、3 个网络方法、2 个缓存容器。 这一页是总览,每项都会拆成单独的详细页。

// brk 命名空间 card icon opens _open _load _json _post _edit v weak
01 —

组件

// 内置的两个 FunctionComponent
brk.card 组件
FunctionComponent<{ cls?: string; css?: string; clk?: Function }>

全局统一的卡片组件。一个带边框、内边距、圆角的容器,用于承载内容块。 之所以内置,是因为它在页面里出现的频率极高——几乎每个独立内容单元都会被包一层。

用法和原生元素一致:<brk.card>...</brk.card>,返回 HTMLElement。

brk.icon 组件
FunctionComponent<{ d: string; c?: string; styles?: object }>

渲染一个 SVG 图标。底层使用 document.createElementNS 创建 SVG 命名空间下的节点, 因此属性处理方式与普通元素不同——尺寸、颜色等通过 styles 对象传入,而非 css 字符串。

d 是 SVG 路径数据;c 是颜色简写。

02 —

导航

// 打开页面 / 打开链接
brk.opens 导航
(meta: any) => any

打开一个任意目标——页面、应用或文档。默认是一个空函数, 不会报错也不会做任何事。它的语义由你在应用层定义。

这是 brk 里最常被覆盖的 API。多页应用、微前端外壳、路由跳转——都在这里实现。 详细做法见 指南 · 多页容器。

brk._open 导航
(key: string, target?: string) => any

打开一个网络链接。默认行为等同于在新标签页打开, 即 window.open(key, target ?? '_blank')。

与 opens 的分工:opens 面向应用内部(页面、模块), _open 面向外部(URL)。

03 —

加载

// 动态引入模块
brk._load 加载
(src: string) => Promise<any>

加载一个异步模块,本质是浏览器的动态 import()。 加载完成后返回模块对象,通常包含 page.vino。

页面之间互相加载、外壳挂载子页面、扩展能力挂到 brk 上——都走这里。

04 —

网络

// 三个最小 HTTP 封装
brk._json 网络
(path: string) => Promise<object>

发起 GET 请求,返回解析后的 JSON。用于拉取数据。

brk._post 网络
(path: string, body: object) => Promise<object>

发起 POST 请求,提交 JSON body,返回解析后的 JSON。用于创建资源。

brk._edit 网络
(path: string, body: object) => Promise<object>

发起 PATCH 请求,提交 JSON body,返回解析后的 JSON。用于局部更新资源。

只提供 GET / POST / PATCH 三种最常用的语义。DELETE、PUT 等其余方法需要自行调用 fetch——这是"骨架"定位的一部分。

05 —

缓存

// 两个不同生命周期的存储
brk.v 缓存
any

全局共享缓存,初始值为 {}。用于跨页面存放数据—— 即使页面卸载,这里的数据依然保留。

典型用法:存登录态、主题偏好、用户信息、跨页面的业务数据。

brk.weak 缓存
WeakMap<HTMLElement, any>

一个以 DOM 为 key 的弱引用存储。把一个 DOM 元素作为 key, 就能挂上任意关联数据;当这个 DOM 被移除并被垃圾回收后,关联数据自动消失。

典型用法:把 { state, handlers } 挂到行 DOM 上, 父组件通过事件冒泡的 currentTarget 反查到对应的数据。

// 命名约定

三个符号的语义

无前缀
面向应用的能力。 card、icon、opens、v、weak 直接以名字挂在 brk 上。它们要么是组件,要么是应用层高频使用的语义。
_ 前缀
面向基础设施的能力。 _load、_open、_json、_post、_edit 带下划线。它们是对浏览器原生能力的薄封装,属于"底层工具", 不常直接出现在业务代码里,也不鼓励被应用层覆盖。
单字母
高频、短、有意义。 v 是 value / vault 的缩写, 代表全局值容器;weak 直接取自 WeakMap。 这类名字只在 brk 命名空间下使用,不会污染全局。
!

这一页是总览。 每一项都会拆成单独的详细页,包含参数说明、返回值、示例、源码位置与注意事项。目前所有条目都已列出,但详细页尚未完成。