biugfix

2025-11-09 11:45:13 +08:00 · 2025-11-09 11:45:13 +08:00 · 40b5ae6cb2
commit 40b5ae6cb2
parent c4407bf191
1 changed files with 24 additions and 419 deletions
--- 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日