biugfix
This commit is contained in:
yumoqing
parent
c4407bf191
commit
40b5ae6cb2
@ -1,83 +1,31 @@
|
|||||||
# Bricks.js 技术文档
|
# Bricks.js 技术文档
|
||||||
|
|
||||||
> **Bricks.js** 是一个基于 JavaScript 的前端组件化框架，用于构建可扩展、模块化的 Web 应用程序。它支持动态组件加载、事件绑定、数据实时获取、弹窗管理、国际化（i18n）、媒体流控制等功能。
|
> **Bricks.js** 是一个基于 JavaScript 的开发的前端组件化框架，用于构建可扩展、模块化的 Web 应用程序。bricks提供开发者使用json数据开发前端界面的能力，它支持动态组件加载、事件绑定、数据实时获取、弹窗管理、国际化（i18n）、媒体流控制等功能。
|
||||||
|
|
||||||
---
|
bricks以控件为单位构建界面，所有控件都从一个JsWidget继承而来，bricks的控件分为普通控件和容器控件，容器控件可以有子控件，而普通控件没有子控件，在bricks的源码文件中，用”subwidgets“数组描述子控件
|
||||||
|
|
||||||
## 目录
|
## bricks开发逻辑
|
||||||
|
使用json格式的原文件（以".ui“结尾）来开发前端界面，每个ui文件
|
||||||
|
|
||||||
- [1. 概述](#1-概述)
|
bricks使用规范化的json来描述前端界面，json数据约束如下
|
||||||
- [2. 核心对象 `bricks`](#2-核心对象-bricks)
|
{
|
||||||
- [3. 绑定动作（Bind Actions）](#3-绑定动作bind-actions)
|
"id" # 控件id
|
||||||
- [通用属性](#通用属性)
|
"widgettype" # 控件类型，请看考bricks控件清单
|
||||||
- [各类型绑定的特定属性](#各类型绑定的特定属性)
|
"options" # 控件构造参数，支持控件类继承的参数
|
||||||
- [4. 工具函数](#4-工具函数)
|
"subwidgets" # 容器类控件需要，数组形式的一到多个控件json
|
||||||
- [`uuid()`](#uuid)
|
"binds" # 事件处理数组， 参看bind数据规范
|
||||||
- [`deviceid(appname)`](#deviceidappname)
|
}
|
||||||
- [`str2data(s, d)`](#str2datas-d)
|
|
||||||
- [`apply_data(desc, data)`](#apply_datadesc-data)
|
|
||||||
- [5. 组件构建系统](#5-组件构建系统)
|
|
||||||
- [`widgetBuild(desc, widget, data)`](#widgetbuilddesc-widget-data)
|
|
||||||
- [`buildBind(w, desc)`](#buildbindw-desc)
|
|
||||||
- [`buildEventBind(from_widget, widget, event, desc)`](#buildeventbindfrom_widget-widget-event-desc)
|
|
||||||
- [`universal_handler(from_widget, widget, desc, event)`](#universal_handlerfrom_widget-widget-desc-event)
|
|
||||||
- [6. 事件处理器生成器](#6-事件处理器生成器)
|
|
||||||
- [`buildEventHandler(w, desc, event)`](#buildeventhandlerw-desc-event)
|
|
||||||
- [`getRealtimeData(w, desc)`](#getrealtimedataw-desc)
|
|
||||||
- [7. 各类 Handler 构造函数](#7-各类-handler-构造函数)
|
|
||||||
- [`buildNewWindowHandler`](#buildnewwindowhandler)
|
|
||||||
- [`buildUrlwidgetHandler`](#buildurlwidgethandler)
|
|
||||||
- [`buildBricksHandler`](#buildbrickshandler)
|
|
||||||
- [`buildRegisterFunctionHandler`](#buildregisterfunctionhandler)
|
|
||||||
- [`buildMethodHandler`](#buildmethodhandler)
|
|
||||||
- [`buildScriptHandler`](#buildscripthandler)
|
|
||||||
- [`buildDispatchEventHandler`](#builddispatcheventhandler)
|
|
||||||
- [8. 辅助函数](#8-辅助函数)
|
|
||||||
- [`getWidgetById(id, from_widget)`](#getwidgetbyidid-from_widget)
|
|
||||||
- [9. App 类 (`bricks.App`)](#9-app-类-bricksapp)
|
|
||||||
- [构造函数参数 `opts`](#构造函数参数-opts)
|
|
||||||
- [主要方法](#主要方法)
|
|
||||||
|
|
||||||
---
|
当widgettype值为"urlwidget“时，options必须为
|
||||||
|
{
|
||||||
|
"url" # 从服务器中获取控件json
|
||||||
|
“params" # 参数
|
||||||
|
"method" # 缺省为“GET”
|
||||||
|
}
|
||||||
|
意思就是从服务器中用options中提供的数据从远程服务器中获取bricks控件源码，渲染到target定义的容器控件中，这种形式提供了bricks模块化编程能力，其他的widgettype值必须时bricks中注册过的控件名称，请参看bricks的控件清单
|
||||||
|
|
||||||
## 1. 概述
|
### binds数据规范
|
||||||
|
binds数组定义用户交互行为，每个绑定bind描述符包含以下结构。
|
||||||
`bricks` 是一个全局命名空间对象，封装了整个应用的核心逻辑：
|
|
||||||
|
|
||||||
```js
|
|
||||||
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` 数组定义用户交互行为，每个绑定描述符包含以下结构。
|
|
||||||
|
|
||||||
### 通用属性
|
|
||||||
|
|
||||||
所有绑定动作都具备以下字段：
|
|
||||||
|
|
||||||
| 字段名 | 类型 | 必填 | 描述 |
|
| 字段名 | 类型 | 必填 | 描述 |
|
||||||
|------------------|----------|------|------|
|
|------------------|----------|------|------|
|
||||||
@ -94,7 +42,7 @@ bricks.app = null;
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 各类型绑定的特定属性
|
各类型绑定的特定属性
|
||||||
|
|
||||||
#### `urlwidget` action
|
#### `urlwidget` action
|
||||||
|
|
||||||
@ -114,8 +62,7 @@ bricks.app = null;
|
|||||||
| 属性 | 类型 | 描述 |
|
| 属性 | 类型 | 描述 |
|
||||||
|--------|---------|------|
|
|--------|---------|------|
|
||||||
| `mode` | String | 同上 |
|
| `mode` | String | 同上 |
|
||||||
| `options.widgettype` | String | 组件类型，必须已注册 |
|
| `options| 对象 | 符合控件源码要求的json数据，其属性widgettype的值必须时bricks已经注册的控件 |
|
||||||
| `options.*` | Any | 组件初始化选项 |
|
|
||||||
|
|
||||||
#### `method` action
|
#### `method` action
|
||||||
|
|
||||||
@ -146,7 +93,7 @@ bricks.app = null;
|
|||||||
|
|
||||||
#### `event` action
|
#### `event` action
|
||||||
|
|
||||||
派发自定义事件。
|
在target控件上派发自定义事件。
|
||||||
|
|
||||||
| 属性 | 类型 | 描述 |
|
| 属性 | 类型 | 描述 |
|
||||||
|------------------|----------|------|
|
|------------------|----------|------|
|
||||||
@ -154,345 +101,3 @@ bricks.app = null;
|
|||||||
| `params` | Object | 携带的数据 |
|
| `params` | Object | 携带的数据 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. 工具函数
|
|
||||||
|
|
||||||
### `uuid()`
|
|
||||||
|
|
||||||
生成唯一标识符（UUID），优先使用 Web Crypto API，降级为随机字符串。
|
|
||||||
|
|
||||||
```js
|
|
||||||
bricks.uuid(); // 返回类似 "a1b2c3d4e5f6..."
|
|
||||||
```
|
|
||||||
|
|
||||||
- 使用 `crypto.randomUUID()`（现代浏览器）
|
|
||||||
- 若不支持，则生成 30 位随机字符（来自字母数字集）
|
|
||||||
|
|
||||||
> ⚠️ 注意：降级版本非标准 UUID，仅作唯一性参考。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `deviceid(appname)`
|
|
||||||
|
|
||||||
为当前设备+应用组合生成持久化设备 ID，存储于 `localStorage`。
|
|
||||||
|
|
||||||
```js
|
|
||||||
bricks.deviceid('myapp'); // → myappdeviceid: abcdef...
|
|
||||||
```
|
|
||||||
|
|
||||||
- Key: `${appname}deviceid`
|
|
||||||
- 自动生成并缓存，避免重复访问时变化
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `str2data(s, d)`
|
|
||||||
|
|
||||||
模板字符串解析函数，支持变量插值和类型转换。
|
|
||||||
|
|
||||||
**语法格式：**
|
|
||||||
|
|
||||||
```
|
|
||||||
'my name is ${name}, age ${age:type}'
|
|
||||||
```
|
|
||||||
|
|
||||||
支持的类型：
|
|
||||||
- `int`: 转为整数
|
|
||||||
- `str`: 字符串（默认）
|
|
||||||
- `json`: JSON 序列化
|
|
||||||
|
|
||||||
**示例：**
|
|
||||||
|
|
||||||
```js
|
|
||||||
bricks.str2data('Hello ${user}', { user: 'Tom' });
|
|
||||||
// → "Hello Tom"
|
|
||||||
|
|
||||||
bricks.str2data('${data:json}', { data: { x: 1 } });
|
|
||||||
// → '{"x":1}'
|
|
||||||
```
|
|
||||||
|
|
||||||
返回 `null` 如果关键变量缺失。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `apply_data(desc, data)`
|
|
||||||
|
|
||||||
将数据填充到任意对象结构中（递归模板替换）。
|
|
||||||
|
|
||||||
```js
|
|
||||||
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`: 初始数据，用于模板填充
|
|
||||||
|
|
||||||
**流程：**
|
|
||||||
1. 若 `widgettype === 'urlwidget'`，先发起 HTTP 请求获取真实组件描述
|
|
||||||
2. 应用 `data` 填充模板
|
|
||||||
3. 查找组件类（通过 `Factory.get(type)`）
|
|
||||||
4. 创建实例并设置 `id`
|
|
||||||
5. 递归构建子组件（`subwidgets`）
|
|
||||||
6. 绑定事件（`binds`）
|
|
||||||
|
|
||||||
**返回：** 构建完成的组件实例（Promise）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `buildBind(w, desc)`
|
|
||||||
|
|
||||||
为指定组件建立事件绑定。
|
|
||||||
|
|
||||||
**步骤：**
|
|
||||||
1. 解析 `wid` 得到触发源组件
|
|
||||||
2. 调用 `buildEventBind(...)` 添加监听器
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `buildEventBind(from_widget, widget, event, desc)`
|
|
||||||
|
|
||||||
实际绑定事件处理器。
|
|
||||||
|
|
||||||
```js
|
|
||||||
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`
|
|
||||||
|
|
||||||
调用目标组件上的某个方法。
|
|
||||||
|
|
||||||
```js
|
|
||||||
target[desc.method].bind(target, params)
|
|
||||||
```
|
|
||||||
|
|
||||||
适用于 `setValue`, `show`, `hide` 等组件 API。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `buildScriptHandler`
|
|
||||||
|
|
||||||
动态创建异步函数并绑定执行环境。
|
|
||||||
|
|
||||||
```js
|
|
||||||
const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
|
|
||||||
new AsyncFunction('params', 'event', scriptBody);
|
|
||||||
```
|
|
||||||
|
|
||||||
可用于复杂逻辑脚本注入。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `buildDispatchEventHandler`
|
|
||||||
|
|
||||||
向目标组件派发自定义事件。
|
|
||||||
|
|
||||||
```js
|
|
||||||
target.dispatch(desc.dispatch_event, mergedParams);
|
|
||||||
```
|
|
||||||
|
|
||||||
常用于跨组件通信。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 辅助函数
|
|
||||||
|
|
||||||
### `getWidgetById(id, from_widget)`
|
|
||||||
|
|
||||||
根据 ID 查找组件实例，支持路径表达式。
|
|
||||||
|
|
||||||
**ID 支持语法：**
|
|
||||||
- `'self'`: 当前组件
|
|
||||||
- `'root'`: 根组件
|
|
||||||
- `'app'` / `'body'`: 应用主体
|
|
||||||
- `'window'`: 浏览器窗口根元素
|
|
||||||
- `'#id'`: DOM ID 选择器
|
|
||||||
- `'-id'`: 使用 `closest()` 向上查找
|
|
||||||
|
|
||||||
**示例：**
|
|
||||||
```js
|
|
||||||
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：调试技巧
|
|
||||||
|
|
||||||
启用调试：
|
|
||||||
```js
|
|
||||||
bricks.bug = true;
|
|
||||||
```
|
|
||||||
|
|
||||||
查看日志：
|
|
||||||
```js
|
|
||||||
console.log(...args); // 内部使用 debug 输出
|
|
||||||
```
|
|
||||||
|
|
||||||
推荐配合 Chrome DevTools 使用。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 许可证
|
|
||||||
|
|
||||||
MIT License（假设项目允许）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
> 📝 文档版本：v1.0
|
|
||||||
> ✍️ 最后更新：2025年4月5日
|
|
||||||
Loading…
x
Reference in New Issue
Block a user