yumoqing/bricks

Fork 0

yumoqing 55908f7b8f bugfix

2025-10-05 06:39:58 +08:00

13 KiB

Raw Permalink Blame History

Bricks.js 技术文档

Bricks.js 是一个基于 JavaScript 的前端组件化框架，用于构建可扩展、模块化的 Web 应用程序。它支持动态组件加载、事件绑定、数据实时获取、弹窗管理、国际化（i18n）、媒体流控制等功能。

1. 概述
2. 核心对象 bricks
3. 绑定动作（Bind Actions）
- 通用属性
- 各类型绑定的特定属性
4. 工具函数
5. 组件构建系统
6. 事件处理器生成器
- buildEventHandler(w, desc, event)
- getRealtimeData(w, desc)
7. 各类 Handler 构造函数
8. 辅助函数
- getWidgetById(id, from_widget)
9. App 类 (bricks.App)
- 构造函数参数 opts
- 主要方法

1. 概述

bricks 是一个全局命名空间对象，封装了整个应用的核心逻辑：

var bricks = window.bricks || {};
bricks.app = null;

所有功能均挂载在 bricks 对象下，包括：

组件工厂（Factory）
弹窗管理（Popup / PopupWindow）
HTTP 请求客户端（HttpJson）
国际化支持（I18n）
设备标识与会话管理
动态组件构建与事件绑定机制

2. 核心对象 `bricks`

属性/方法	类型	描述
`app`	App 实例	当前应用主实例
`Body`	DOM 元素包装	页面 body 封装
`bug` / `debug`	Boolean	是否开启调试模式
`Factory`	Class	组件注册与创建工厂
`RF`	RegisterFunction	注册函数管理器

3. 绑定动作（Bind Actions）

通过 desc.binds 数组定义用户交互行为，每个绑定描述符包含以下结构。

通用属性

所有绑定动作都具备以下字段：

字段名	类型	必填	描述
`actiontype`	String	✅	动作类型：`bricks`, `urlwidget`, `method`, `script`, `registerfunction`, `event`, `newwindow`
`wid`	String	✅	触发事件的组件 ID
`event`	String	✅	监听的事件名称，如 `'click'`
`target`	String 或 Widget	✅	执行目标组件或特殊值（如 `'Popup'`）
`datawidget`	String	❌	获取运行时数据的源组件 ID
`datamethod`	String	❌	数据获取方法，默认 `'getValue'`
`dataparams`	Object	❌	调用 `datamethod` 的参数
`datascript`	String	❌	自定义脚本获取数据
`rtdata`	Object	❌	静态运行时数据
`conform`	Object	❌	确认对话框配置，在执行前弹出确认窗口

各类型绑定的特定属性

`urlwidget` action

从远程 URL 加载组件描述并渲染。

属性	类型	描述
`mode`	String	`'replace'`, `'insert'`, `'append'`，默认 `'replace'`
`options.method`	String	HTTP 方法，默认 `'GET'`
`options.params`	Object	请求参数
`options.url`	String	远程组件 JSON 地址

`bricks` action

本地创建 Bricks 组件。

属性	类型	描述
`mode`	String	同上
`options.widgettype`	String	组件类型，必须已注册
`options.*`	Any	组件初始化选项

`method` action

调用目标组件的方法。

属性	类型	描述
`method`	String	方法名
`params`	Object	方法参数（kwargs）

`script` action

执行内联脚本。

属性	类型	描述
`script`	String	可执行 JS 代码字符串（异步函数体）
`params`	Object	传入脚本的参数

`registerfunction` action

调用已注册的全局函数。

属性	类型	描述
`rfname`	String	注册函数名称
`params`	Object	函数参数

`event` action

派发自定义事件。

属性	类型	描述
`dispatch_event`	String	要派发的事件名
`params`	Object	携带的数据

4. 工具函数

`uuid()`

生成唯一标识符（UUID），优先使用 Web Crypto API，降级为随机字符串。

bricks.uuid(); // 返回类似 "a1b2c3d4e5f6..."

使用 crypto.randomUUID()（现代浏览器）
若不支持，则生成 30 位随机字符（来自字母数字集）

⚠️ 注意：降级版本非标准 UUID，仅作唯一性参考。

`deviceid(appname)`

为当前设备+应用组合生成持久化设备 ID，存储于 localStorage。

bricks.deviceid('myapp'); // → myappdeviceid: abcdef...

Key: ${appname}deviceid
自动生成并缓存，避免重复访问时变化

`str2data(s, d)`

模板字符串解析函数，支持变量插值和类型转换。

语法格式：

'my name is ${name}, age ${age:type}'

支持的类型：

int: 转为整数
str: 字符串（默认）
json: JSON 序列化

示例：

bricks.str2data('Hello ${user}', { user: 'Tom' }); 
// → "Hello Tom"

bricks.str2data('${data:json}', { data: { x: 1 } });
// → '{"x":1}'

返回 null 如果关键变量缺失。

`apply_data(desc, data)`

将数据填充到任意对象结构中（递归模板替换）。

const desc = { url: '/api/${id}' };
const filled = bricks.apply_data(desc, { id: 123 });
// → { url: '/api/123' }

内部使用 str2data 处理所有字符串字段。

5. 组件构建系统

`widgetBuild(desc, widget, data)`

根据组件描述符异步构建组件树。

参数：

desc: 组件描述对象（含 widgettype, options, subwidgets, binds）
widget: 父组件（上下文）
data: 初始数据，用于模板填充

流程：

若 widgettype === 'urlwidget'，先发起 HTTP 请求获取真实组件描述
应用 data 填充模板
查找组件类（通过 Factory.get(type)）
创建实例并设置 id
递归构建子组件（subwidgets）
绑定事件（binds）

返回： 构建完成的组件实例（Promise）

`buildBind(w, desc)`

为指定组件建立事件绑定。

步骤：

解析 wid 得到触发源组件
调用 buildEventBind(...) 添加监听器

`buildEventBind(from_widget, widget, event, desc)`

实际绑定事件处理器。

widget.bind(event, handler);

处理器为 bricks.universal_handler(from_widget, widget, desc) 的柯里化函数。

`universal_handler(from_widget, widget, desc, event)`

统一事件处理入口，支持前置确认（conform）。

逻辑：

若有 conform 配置，创建 Conform 弹窗，确认后再执行后续操作
否则直接调用 buildEventHandler(...)

若失败，输出调试信息。

6. 事件处理器生成器

`buildEventHandler(w, desc, event)`

根据 actiontype 分发不同类型的处理器。

actiontype	返回处理器函数
`newwindow`	新窗口打开链接
`urlwidget`	加载远程组件
`bricks`	创建本地组件
`registerfunction`	调用注册函数
`method`	调用组件方法
`script`	执行脚本
`event`	派发事件

同时处理：

实时数据提取（rtdata 来源：datawidget, datamethod, datascript）
参数映射（params_mapping）
事件参数合并

`getRealtimeData(w, desc)`

从指定组件获取实时数据。

方式：

desc.method: 调用组件方法
desc.script: 执行脚本获取结果

返回： Promise 包裹的结果数据

7. 各类 Handler 构造函数

这些函数返回一个“延迟执行”的函数（通常用 .bind() 封装），供事件触发时调用。

`buildNewWindowHandler`

打开新浏览器窗口。

支持参数拼接（URL 查询参数）
使用 _buildWidget 渲染 NewWindow 组件

`buildUrlwidgetHandler`

加载远程组件并在目标位置展示。

支持 FormData 特殊处理（POST 提交）
参数自动注入 URL 或请求体

`buildBricksHandler`

在目标容器中渲染本地 Bricks 组件。

支持 mode: replace, insert, append
自动处理弹窗打开（Popup/PopupWindow）

`buildRegisterFunctionHandler`

调用通过 bricks.RF.register(name, func) 注册的函数。

参数合并策略：desc.params + rtdata + event_params
支持模板填充

`buildMethodHandler`

调用目标组件上的某个方法。

target[desc.method].bind(target, params)

适用于 setValue, show, hide 等组件 API。

`buildScriptHandler`

动态创建异步函数并绑定执行环境。

const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
new AsyncFunction('params', 'event', scriptBody);

可用于复杂逻辑脚本注入。

`buildDispatchEventHandler`

向目标组件派发自定义事件。

target.dispatch(desc.dispatch_event, mergedParams);

常用于跨组件通信。

8. 辅助函数

`getWidgetById(id, from_widget)`

根据 ID 查找组件实例，支持路径表达式。

ID 支持语法：

'self': 当前组件
'root': 根组件
'app' / 'body': 应用主体
'window': 浏览器窗口根元素
'#id': DOM ID 选择器
'-id': 使用 closest() 向上查找

示例：

bricks.getWidgetById('loginForm.usernameInput');

返回匹配的 bricks_widget 实例或原生 DOM。

9. App 类 (`bricks.App`)

继承自 bricks.Layout，是整个应用的根容器。

构造函数参数 `opts`

参数	类型	描述
`appname`	String	应用名，用于设备 ID 存储
`debug`	Boolean/String	是否启用调试日志
`login_url`	String	登录页地址，默认 `/rbac/userpassword_login.ui`
`charsize`	Number	字体基础大小
`language`	String	初始语言（如 `'zh-CN'`）
`i18n.url`	String	国际化资源接口
`i18n.default_lang`	String	默认语言
`widget`	Object	根组件描述

主要方法

方法	描述
`run()`	启动应用：初始化语言、构建根组件、添加至 DOM
`build()`	构建根组件树
`change_language(lang)`	切换语言并通知 i18n 系统
`key_down_action(event)`	全局键盘事件捕获
`new_zindex()`	获取新的 z-index 层级
`screenWidth()` / `screenHeight()`	获取视口尺寸
`save_session(session)` / `get_session()`	会话管理
`start_camera(vpos)`	打开指定摄像头
`start_mic()`	打开麦克风
`getCameras()`	获取可用视频输入设备列表
`textsize_bigger()` / `textsize_smaller()`	调整字体大小
`show_windows_panel()`	显示多窗口面板（实验性）

附录 A：内置组件类型（常见 `widgettype`）

类型	说明
`Text`	文本显示
`Button`	按钮
`Input`	输入框
`Layout`	布局容器
`Popup`	模态弹窗
`PopupWindow`	独立窗口弹窗
`Conform`	确认对话框
`NewWindow`	新浏览器窗口包装器
`WindowsPanel`	窗口管理面板

附录 B：调试技巧

启用调试：

bricks.bug = true;

查看日志：

console.log(...args); // 内部使用 debug 输出

推荐配合 Chrome DevTools 使用。

许可证

MIT License（假设项目允许）

📝 文档版本：v1.0
✍️ 最后更新：2025年4月5日

13 KiB Raw Permalink Blame History Unescape Escape

Bricks.js 技术文档

目录

1. 概述

2. 核心对象 bricks

3. 绑定动作（Bind Actions）

通用属性

各类型绑定的特定属性

urlwidget action

bricks action

method action

script action

registerfunction action

event action

4. 工具函数

uuid()

deviceid(appname)

str2data(s, d)

apply_data(desc, data)

5. 组件构建系统

widgetBuild(desc, widget, data)

buildBind(w, desc)

buildEventBind(from_widget, widget, event, desc)

universal_handler(from_widget, widget, desc, event)