diff --git a/docs/cn/bricks.md b/docs/cn/bricks.md index 1d10a57..99ff2a5 100644 --- a/docs/cn/bricks.md +++ b/docs/cn/bricks.md @@ -1,83 +1,31 @@ # 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-概述) -- [2. 核心对象 `bricks`](#2-核心对象-bricks) -- [3. 绑定动作（Bind Actions）](#3-绑定动作bind-actions) - - [通用属性](#通用属性) - - [各类型绑定的特定属性](#各类型绑定的特定属性) -- [4. 工具函数](#4-工具函数) - - [`uuid()`](#uuid) - - [`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) - - [主要方法](#主要方法) +bricks使用规范化的json来描述前端界面，json数据约束如下 +{ + "id" # 控件id + "widgettype" # 控件类型，请看考bricks控件清单 + "options" # 控件构造参数，支持控件类继承的参数 + "subwidgets" # 容器类控件需要，数组形式的一到多个控件json + "binds" # 事件处理数组， 参看bind数据规范 +} ---- +当widgettype值为"urlwidget“时，options必须为 +{ + "url" # 从服务器中获取控件json + “params" # 参数 + "method" # 缺省为“GET” +} +意思就是从服务器中用options中提供的数据从远程服务器中获取bricks控件源码，渲染到target定义的容器控件中，这种形式提供了bricks模块化编程能力，其他的widgettype值必须时bricks中注册过的控件名称，请参看bricks的控件清单 -## 1. 概述 - -`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` 数组定义用户交互行为，每个绑定描述符包含以下结构。 - -### 通用属性 - -所有绑定动作都具备以下字段： +### binds数据规范 +binds数组定义用户交互行为，每个绑定bind描述符包含以下结构。 | 字段名 | 类型 | 必填 | 描述 | |------------------|----------|------|------| @@ -94,7 +42,7 @@ bricks.app = null; --- -### 各类型绑定的特定属性 +各类型绑定的特定属性 #### `urlwidget` action @@ -114,8 +62,7 @@ bricks.app = null; | 属性 | 类型 | 描述 | |--------|---------|------| | `mode` | String | 同上 | -| `options.widgettype` | String | 组件类型，必须已注册 | -| `options.*` | Any | 组件初始化选项 | +| `options| 对象 | 符合控件源码要求的json数据，其属性widgettype的值必须时bricks已经注册的控件 | #### `method` action @@ -146,7 +93,7 @@ bricks.app = null; #### `event` action -派发自定义事件。 +在target控件上派发自定义事件。 | 属性 | 类型 | 描述 | |------------------|----------|------| @@ -154,345 +101,3 @@ bricks.app = null; | `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日 \ No newline at end of file