diff --git a/bricks/progressbar.js b/bricks/progressbar.js index 0f3dbb8..824c13f 100644 --- a/bricks/progressbar.js +++ b/bricks/progressbar.js @@ -15,8 +15,8 @@ bricks.ProgressBar = class extends bricks.HBox { this.add_widget(this.text_w); } set_value(v){ - var pzt = (current / total) * 100; - pzt = Math.max(0, Math.min(100, percentage)); + var pzt = this.total_value ? (v / this.total_value) * 100 : 0; + pzt = Math.max(0, Math.min(100, pzt)); this.text_w.set_style('width', pzt + '%') } } diff --git a/docs/ai/.progressbar.md.swp b/docs/ai/.progressbar.md.swp new file mode 100644 index 0000000..fc2f8ef Binary files /dev/null and b/docs/ai/.progressbar.md.swp differ diff --git a/docs/ai/accordion.md b/docs/ai/accordion.md new file mode 100644 index 0000000..4a5225d --- /dev/null +++ b/docs/ai/accordion.md @@ -0,0 +1,44 @@ +# Accordion + +**控件功能**：Accordion 是一个可折叠的面板控件，允许用户通过点击标题按钮切换显示不同内容区域。常用于组织多个内容块，节省界面空间。 + +**类型**：容器控件 +**父类控件**：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `item_size` | String (可选) | 每个折叠项标题的高度，默认为 `'25px'`。 | +| `items` | Array\ | 折叠项列表，每个对象包含以下属性：
- `name`: 该项唯一标识符
- `icon`: 显示在按钮前的图标（可选）
- `label`: 按钮上显示的文字
- `content`: 子控件配置对象（widgettype 等），用于动态构建内容
- `refresh` (Boolean, 可选): 是否每次点击都重新加载内容 | +| `item_css` | String (可选) | 标题按钮的 CSS 类名，默认为 `'accordion-button'`。 | +| `content_css` | String (可选) | 内容区域的 CSS 类名，默认为 `'accordion-content'`。 | + +示例： +```js +{ + item_size: '30px', + items: [ + { + name: 'panel1', + label: '基本信息', + icon: 'info', + content: { widgettype: 'Label', text: '这里是基本信息' } + }, + { + name: 'panel2', + label: '设置', + refresh: true, + content: { widgettype: 'Form', fields: [...] } + } + ] +} +``` + +## 主要事件 + +| 事件名 | 触发时机 | 回调参数 | 说明 | +|--------|---------|----------|------| +| `click` (内部绑定) | 用户点击某个折叠项标题按钮时触发 | `event.target.bricks_widget` 指向被点击的 `Button` 实例 | 控制内容切换的核心事件，由内部自动绑定并处理内容加载与展示 | + +> 注意：该控件自身不对外暴露自定义事件 API，但其行为依赖于 `Button` 的 `click` 事件来驱动内容切换逻辑。开发者可通过监听子控件事件实现扩展功能。 \ No newline at end of file diff --git a/docs/ai/asr.md b/docs/ai/asr.md new file mode 100644 index 0000000..f0d76f8 --- /dev/null +++ b/docs/ai/asr.md @@ -0,0 +1,46 @@ +# ASRClient + +控件功能：实现语音识别客户端功能，通过 WebSocket 与服务器通信，实时发送音频数据并接收识别结果。提供开始/停止录音的交互按钮，并触发相应的事件。 + +类型：普通控件 +父类控件：`bricks.VBox` + +## 初始化参数 + +- `start_icon` (String, 可选) + 开始录音状态下的图标路径，默认为 `imgs/start_recording.svg`。 + +- `stop_icon` (String, 可选) + 停止录音状态下的图标路径，默认为 `imgs/stop_recording.svg`。 + +- `ws_url` (String, 必填) + WebSocket 服务地址，用于建立与语音识别后端的连接。 + +- `icon_options` (Object, 可选) + 图标控件的配置选项，将传递给 `bricks.Svg` 实例，可自定义图标显示样式。 + +- `ws_params` (Object, 可选) + 发送至 WebSocket 服务器的额外参数，在发送音频数据时合并使用。 + +## 主要事件 + +- `start` + 触发时机：用户点击图标开始录音时。 + 参数：无 + +- `stop` + 触发时机：用户点击图标停止录音时。 + 参数：无 + +- `transtext` + 触发时机：从服务器接收到语音识别结果时。 + 参数： + ```json + { + "content": "识别出的文本内容", + "speaker": "说话人标识（如支持）", + "start": "该段语音起始时间戳", + "end": "该段语音结束时间戳" + } + ``` + 说明：此事件由 `response_data` 方法解析服务器消息后派发，供上层组件处理识别结果。 diff --git a/docs/ai/bar.md b/docs/ai/bar.md new file mode 100644 index 0000000..598ce00 --- /dev/null +++ b/docs/ai/bar.md @@ -0,0 +1,34 @@ +# ChartBar + +**控件功能**：用于展示柱状图（Bar Chart），基于 ECharts 扩展实现，支持从指定数据源获取数据并动态渲染多系列柱状图。 +**类型**：普通控件 +**父类控件**：`bricks.EchartsExt` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|------------|--------|----| +| `data_url` | string | 可选，数据请求的 URL 地址，用于异步加载图表数据。 | +| `data_params`| object | 请求数据时携带的额外参数，配合 `data_url` 使用。 | +| `method` | string | 数据请求方式，如 `'GET'` 或 `'POST'`，默认为 `'GET'`。 | +| `data` | array | 可选，直接传入本地数据数组，格式为对象数组，每个对象表示一条记录。 | +| `nameField` | string | 指定哪一字段作为 X 轴分类名称（如类别、时间等）。 | +| `valueFields`| array | 字符串数组，指定一个或多个字段作为 Y 轴数值，用于生成多个数据系列（series）。 | + +> 示例数据结构： +> ```json +> [ +> { "category": "A", "value1": 10, "value2": 20 }, +> { "category": "B", "value1": 15, "value2": 25 } +> ] +> ``` +> 若 `nameField = "category"`，`valueFields = ["value1", "value2"]`，则会生成两个柱状系列。 + +## 主要事件 + +| 事件名 | 触发时机 | 回调参数说明 | +|------------|--------|------------| +| `chart:loaded` | 图表数据加载完成并成功渲染后触发 | `event.detail` 包含原始数据和最终生成的 ECharts 配置项（options） | +| `chart:error` | 数据加载失败或解析异常时触发 | `event.detail` 包含错误信息，如 `message`, `url`, `status` 等 | + +> 注：事件通过自定义事件机制派发，可通过 `addEventListener('chart:loaded', handler)` 监听。 \ No newline at end of file diff --git a/docs/ai/brief.md b/docs/ai/brief.md new file mode 100644 index 0000000..0faa7ae --- /dev/null +++ b/docs/ai/brief.md @@ -0,0 +1,109 @@ +# bricks框架简介 +## 目录 +* bricks目标 +* bricks概念 +* bricks开发方法 +* bricks运行 + +## bricks目标 +* 无前端代码或极少代码 +* 降低前端开发技术难度 +* 数据驱动 +* 常用控件包装 +* 纯json开发 + +## bricks概念 +* 控件与控件继承 +* 事件以及事件处理 +* 控件嵌套和页面组装 + +### 控件与控件继承 +bricks采用控件这一概念来描述web GUI的显示部件，每个控件均映射到一个html +的标签类型的一个javascript类。每个控件均可以实例化，并可在页面显示。 +控件分为：基本控件，容器控件。控件有内置方法，也能触发事件。 + +* 基本控件 + +基本控件是一个原子控件，不能有子控件。 + +* 容器控件 + +容器控件可以有子控件，bricks通过在容器控件添加子控件，以及在子容器控件中 +在添加子子控件的方式来构造复杂的web页面。 + +bricks已实现的控件请参看[控件清单](widgets.md) + +### 控件扩展 +如果现有的控件没法满足系统要求，bricks支持控件扩展，控件扩展需遵守： +* 控件class继承自某一个控件的class + +* 按照需求实现控件逻辑 + +* 在需要的地方用this.dispatch触发此控件的事件 + +假设需要扩展一个名字叫ExtContainer的控件 +``` +bricks.ExtContainer = class extends bricks.VBox { + constructor(opts){ + super(opts); + /* 新控件的创建代码 */ + } + ...... + /* 对象的其他方法，在需要的时候，在某个方法中，使用this.dispatch('new_event', data)方法引发事件 */ +} +bricks.register('ExtContainer', bricks.ExtContainer); /* 注册新控件 */ +``` +新控件的使用，example.ui +``` +{ + "widgettype":"ExtContainer", + "options":{ + .... + }, + "subwidgets":[ + ... + ], + "binds":[ + { + "wid":"self", + "event":"new_event", + "actiontype":"urlwidget", + "target":"some_container", + "options":{ + "url":"{{entire_url('./some_ui.ui')}}" + } + } + ] +} +``` + +### 事件以及事件处理 +每个控件都能触发所映射dom元素的事件，以及控件js类的成员函数以及祖先类的 +成员函数中dispatch出的事件 + +所以bricks控件的事件来源于两类，dom元素原生事件以及控件类中自定义的事件。 +两类事件处理方式相同。 + +### 控件表达形式 +在服务器的后台，以json文件的形式表达控件，每个ui文件定义一个控件， +对于容器控件，可以在ui文件中的subwidgets子属性中为此控件添加子控件 + +#### id属性 +字符串属性，定义控件的id，让控件可以用getWidgetById找到，如果不给定，系统会自动生成一个id +#### options属性 +字典属性，创建控件时的选项，每个控件可接受的选项请参看控件选项说明 +#### binds属性 +数组属性，定义零到多个事件响应，每个bind字典需要遵守[事件](event.md)要求 +#### 容器控件特有属性 +##### subwidgets +数组属性，定义容器控件的子控件，每个元素定义一个子控件，子控件遵守控件的数据要素要求 + +## 应用开发开发 +使用存放在服务器后台的.ui后缀的json格式文件来开发，每个.ui文件定义一个控件， 支持基本控件和容器空间。 + +关于如何书写ui文件请参考[UI文件格式](descjson.md) + +## 调试 +ui文件可以直接调试，如在服务器根目录下的test目录下有一个hello.ui文件， +就可以在浏览器中用url：https://sername/test/hello.ui调试 + diff --git a/docs/ai/button.md b/docs/ai/button.md new file mode 100644 index 0000000..b94e725 --- /dev/null +++ b/docs/ai/button.md @@ -0,0 +1,35 @@ +# Button + +控件功能：一个可点击的按钮控件，支持图标、文本标签和自定义动作响应，常用于触发事件或执行操作。 +类型：普通控件 +父类控件：`bricks.Layout` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `orientation` | string | 布局方向，可选值为 `'horizontal'` 或垂直（默认为垂直），影响内部元素排列方式。 | +| `height` | string | 控件高度，默认为 `100%`。 | +| `width` | string | 控件宽度，默认为 `100%`。 | +| `item_rate` | number | 图标和文本的尺寸缩放比例，默认为 `1`。 | +| `tooltip` | string | 鼠标悬停时显示的提示文字。 | +| `color` | string | 文本颜色，CSS 颜色值。 | +| `bgcolor` | string | 背景颜色，CSS 颜色值。 | +| `nonepack` | boolean | 是否去除内边距和边框，若为 `true` 则设置 `padding: 0` 和 `border: 0`。 | +| `name` | string | 控件唯一标识名称，用于设置 DOM 元素 ID。 | +| `icon` | string | 图标资源 URL，如果指定，则在按钮中创建并显示一个 `Icon` 控件。 | +| `label` | string | 按钮上显示的文本标签内容。 | +| `css` | object | 自定义 CSS 样式对象，将被合并到按钮样式中。 | +| `action` | object | 点击按钮时触发的动作配置，包含以下子属性：
- `target`: 目标组件/路径
- `datawidget`: 数据源控件
- `datamethod`: 获取数据的方法名
- `datascript`: 自定义脚本逻辑
- `dataparams`: 传递给动作的参数
- `rtdata`: 是否实时获取数据
- `actiontype`: 动作类型（如跳转、提交等） | + +## 主要事件 + +- **`click`** + 当按钮被点击时触发。事件回调会接收到 `opts` 配置对象作为参数。 + 触发时机：用户点击按钮（包括图标或文本部分）后，调用 `target_clicked` 方法时派发。 + 示例监听： + ```js + button.bind('click', function(opts) { + console.log('Button clicked with options:', opts); + }); + ``` diff --git a/docs/ai/camera.md b/docs/ai/camera.md new file mode 100644 index 0000000..f3eb7d9 --- /dev/null +++ b/docs/ai/camera.md @@ -0,0 +1,26 @@ +# Camera + +控件功能：用于调用设备摄像头进行拍照或视频录制，支持切换摄像头、开始/停止录制、拍摄照片等功能。 +类型：普通控件（基于 `Popup` 的扩展） +父类控件：`bricks.Popup` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `fps` | Number | 视频采集帧率，默认为 60 FPS | +| `type` | String | 控件模式，可选值为 `'picture'`（拍照模式）或 `'recorder'`（录像模式） | +| `auto_dismiss` | Boolean | 是否自动关闭弹窗，默认为 `false`（由代码中显式设置） | + +> 注意：`opts.auto_dismiss = false;` 在构造函数中被强制设置。 + +## 主要事件 + +| 事件名 | 触发条件 | 携带数据 | +|--------|--------|--------| +| `shot` | 用户点击拍照按钮时触发 | 拍摄得到的图片数据 URL（base64 格式的 JPEG 图像） | +| `recorded` | 视频录制结束后触发 | 录制完成的视频文件对象（`File` 类型，格式为 WebM） | + +> 说明： +> - 当 `type='picture'` 时，点击拍摄按钮会触发 `shot` 事件并传出图像数据。 +> - 当 `type='recorder'` 时，点击录制按钮开始/停止录制，停止后触发 `recorded` 事件并传出视频文件。 diff --git a/docs/ai/cols.md b/docs/ai/cols.md new file mode 100644 index 0000000..ad71839 --- /dev/null +++ b/docs/ai/cols.md @@ -0,0 +1,32 @@ +# Cols + +控件功能：用于展示分页的、可滚动的多列数据列表，支持动态加载前后页数据，常用于内容墙、卡片式布局等场景。 +类型：容器控件 +父类控件：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `data_url` | String | 数据请求的 URL 地址，用于异步加载数据。 | +| `data_params` | Object | 请求数据时携带的初始参数对象。 | +| `data_method` | String | 请求方法（如 GET、POST），默认为 GET。 | +| `page_rows` | Number | 每页请求的数据行数。 | +| `cache_limit` | Number | 缓存的页数上限，用于控制内存中保留的历史数据页数量。 | +| `col_cwidth` | Number | 每一列的固定宽度（单位像素），用于动态列布局计算。 | +| `mobile_cols` | Number | 在移动端显示的列数，默认为 2。 | +| `title` | String | 可选标题文本，若存在则显示标题组件。 | +| `description` | String | 可选描述文本（支持 Markdown 格式），会渲染为说明内容。 | +| `toolbar` | Object | 工具栏配置对象，用于定义顶部操作按钮。 | +| `record_view` | Object | 单条记录的视图模板定义，描述如何渲染每一条数据项。 | + +> 注：`record_view` 是一个控件配置对象，会被 `bricks.widgetBuild` 用来生成每个数据项的子控件。 + +## 主要事件 + +| 事件名 | 触发条件 | 携带数据 | +|--------|----------|---------| +| `record_click` | 用户点击某一条记录时触发 | 点击记录对应的数据对象（`user_data`） | +| `command` | 当工具栏按钮被点击时，通过 `toolbar_w` 传递上来的命令事件，由 `command_handle` 转发为 `dispatch(name)` | 命令名称（来自 toolbar 的 `params.name`） | + +> 说明：`dispatch('record_click', data)` 会向外广播该事件，供外部监听处理。 diff --git a/docs/ai/conform.md b/docs/ai/conform.md new file mode 100644 index 0000000..277ce0c --- /dev/null +++ b/docs/ai/conform.md @@ -0,0 +1,26 @@ +# Conform + +控件功能：用于显示一个确认对话框，包含消息内容和“确认”与“取消”操作按钮，常用于用户操作前的二次确认。 +类型：容器控件 +父类控件：`bricks.PopupWindow` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `message` | String | 要显示的消息文本内容，支持多语言（i18n）和自动换行。 | +| `conform` | Object | 可选，用于自定义“确认”按钮的配置，如事件处理扩展、图标、标签等，会合并到默认配置中。 | +| `discard` | Object | 可选，用于自定义“取消”按钮的配置，行为同 `conform`。 | +| `timeout` | Number | 继承自父类，此处被强制设为 0，表示不启用自动关闭。 | +| `auto_open` | Boolean | 继承自父类，设为 true，表示构造后自动弹出显示。 | + +> 注：`opts` 中其他继承自 `PopupWindow` 的参数也适用，但本控件内部重写了 `timeout` 和 `auto_open`。 + +## 主要事件 + +| 事件名 | 触发时机 | 携带数据 | +|--------|----------|--------| +| `conformed` | 用户点击“确认”按钮时触发 | 无特定数据，仅事件通知 | +| `cancelled` | 用户点击“取消”按钮时触发 | 无特定数据，仅事件通知 | + +> 事件通过 `this.dispatch()` 派发，可通过实例绑定监听。 diff --git a/docs/ai/continueaudio.md b/docs/ai/continueaudio.md new file mode 100644 index 0000000..29e4532 --- /dev/null +++ b/docs/ai/continueaudio.md @@ -0,0 +1,40 @@ +# ContinueAudioPlayer + +**控件功能**： +`ContinueAudioPlayer` 是一个用于连续播放音频的 Web Audio API 控件，支持通过 WebSocket 接收音频数据（如 Base64 编码的音频片段），并实现无缝续播。具备播放、暂停、恢复、重启、音量调节和静音切换等功能。 + +**类型**：普通控件 +**父类控件**：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|------------|--------|----| +| `ws_url` | string | （可选）WebSocket 服务地址，用于接收音频流数据（当前控件未直接实现 WebSocket 连接逻辑，需外部使用）。 | +| `onStart` | function | 音频开始播放时触发的回调函数。 | +| `onEnd` | function | 当前音频轨道播放结束时触发的回调函数。 | +| `onPause` | function | 暂停播放时触发的回调函数。 | +| `onResume` | function | 恢复播放时触发的回调函数。 | +| `onVolumeChange` | function | 音量变化或静音状态改变时触发，参数为当前输出音量值（0 或实际音量）。 | + +> 示例： +> ```js +> new bricks.ContinueAudioPlayer({ +> ws_url: 'wss://example.com/audio-stream', +> onStart: () => console.log('Audio started'), +> onEnd: () => console.log('Audio ended'), +> onPause: () => console.log('Paused'), +> onResume: () => console.log('Resumed'), +> onVolumeChange: (vol) => console.log('Volume:', vol) +> }); +> ``` + +## 主要事件 + +| 事件名 | 触发条件 | +|------------------|--------| +| `onStart` | 调用 `handleAudioTrack` 成功解码并开始播放音频时触发。 | +| `onEnd` | 当前音频源播放完毕（`source.onended`）时触发。 | +| `onPause` | 调用 `pauseAudio` 并成功暂停音频上下文后触发。 | +| `onResume` | 调用 `resumeAudio` 并成功恢复音频上下文后触发。 | +| `onVolumeChange` | 调用 `setVolume` 或 `toggleMute` 导致输出音量变化时触发，传递当前有效音量值（静音时为 0）。 | \ No newline at end of file diff --git a/docs/ai/countdown.md b/docs/ai/countdown.md new file mode 100644 index 0000000..8035c25 --- /dev/null +++ b/docs/ai/countdown.md @@ -0,0 +1,36 @@ +# TimePassed + +控件功能：显示自计时开始以来经过的时间（以时:分:秒格式展示），每秒自动更新一次。 +类型：普通控件 +父类控件：bricks.VBox + +## 初始化参数 + +- `opts`：继承自 VBox 的选项对象，无特殊参数。 + - 控件内部初始化时从零秒开始计时，并通过 `bricks.formatTime` 格式化时间显示。 + +## 主要事件 + +- 无自定义事件触发。 +- 内部使用 `schedule_once` 实现周期性更新，但不对外派发事件。 + +--- + +# Countdown + +控件功能：实现一个倒计时控件，支持设定初始时间（如 "01:00:00"），启动后每秒递减并更新显示，倒计时结束时触发 `timeout` 事件。 +类型：普通控件 +父类控件：bricks.VBox + +## 初始化参数 + +- `opts.limit_time`：字符串类型，表示倒计时的总时间，格式为 `"HH:MM:SS"` 或 `"MM:SS"` 或 `"SS"`。 + - 示例： + - `"30"` → 30 秒 + - `"01:30"` → 1 分 30 秒 + - `"01:00:00"` → 1 小时 +- `opts.text_rate`：可选参数，用于设置文本显示刷新率（若底层 Text 控件支持）。 + +## 主要事件 + +- `timeout`：当倒计时归零时，控件会调用 `this.dispatch('timeout')` 派发该事件，可用于通知外部逻辑执行后续操作。 diff --git a/docs/ai/datarow.md b/docs/ai/datarow.md new file mode 100644 index 0000000..3418da7 --- /dev/null +++ b/docs/ai/datarow.md @@ -0,0 +1,29 @@ +# DataRow + +**控件功能**：用于在表格或列表中展示一行数据，支持表头和数据行的渲染，可包含字段显示、复选框选择以及工具栏操作。常用于数据浏览界面中的行级交互。 + +**类型**：容器控件 +**父类控件**：`bricks.HBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `opts.toolbar` | Array | 工具栏配置数组，定义该行上可显示的操作图标按钮（仅非表头行生效）。每个工具项将触发对应事件。 | +| `opts.fields` | Array | 字段定义数组，每个元素描述一个显示字段，包括 `name`、`label`、`uitype`、`cwidth` 等属性。 | +| `opts.css` | String/Object | 自定义样式类名或 CSS 属性对象，应用于该控件根元素。 | +| `opts.browserfields` | Object | 浏览模式下的字段控制选项：
- `exclouded`: 排除显示的字段名数组；
- `cwidth`: 指定各字段的列宽（以字符单位计）。 | +| `opts.editexclouded` | Array | 编辑模式下排除的字段列表（当前未使用）。 | +| `opts.header_css` | String/Object | 表头行专用的自定义样式。 | +| `opts.checkField` | String | 若设置，则在行首添加复选框控件，绑定到指定字段名，用于选择/反选记录。 | + +> 注：`DataRow` 继承自 `HBox`，因此也支持其布局相关参数如 `height: 'auto'`。 + +## 主要事件 + +| 事件名 | 触发时机 | 传递参数 | +|--------|----------|---------| +| `check_changed` | 当行内复选框状态改变时触发 | 触发该事件的 `DataRow` 实例本身 | +| `[tool.name]`（动态） | 点击工具栏中某个非空白图标按钮时触发，事件名为按钮的 `name` | 由 `IconBar` 触发，携带点击信息，通过 `my_dispatch` 转发至外部监听器 | + +> 示例：若 `toolbar.tools` 中有 `{ name: 'delete' }`，则点击该图标会触发名为 `delete` 的事件。 diff --git a/docs/ai/dataviewer.md b/docs/ai/dataviewer.md new file mode 100644 index 0000000..0cabb8e --- /dev/null +++ b/docs/ai/dataviewer.md @@ -0,0 +1,46 @@ +# DataViewer + +**控件功能**：用于展示分页数据的容器控件，支持滚动加载前后页、行记录操作（增删改查）、工具栏命令响应，并可动态渲染数据行。常用于数据列表或表格类场景。 + +**类型**：容器控件 +**父类控件**：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `data_url` | String | 数据加载的接口 URL，供 `PageDataLoader` 使用 | +| `data_params` | Object | 请求数据时附加的参数，在每次请求中发送 | +| `page_rows` | Number | 每页请求的数据条数 | +| `data_method` | String | 请求方法（如 'GET' 或 'POST'），默认为 'GET' | +| `cache_limit` | Number | 缓存页数限制，控制内存中保留的历史页面数量 | +| `editable` | Object | 可选配置，定义新增、更新、克隆、删除等操作的图标和 URL | +|   `.add_icon` | String | 新增按钮图标路径 | +|   `.update_icon` | String | 更新按钮图标路径 | +|   `.clone_icon` | String | 克隆按钮图标路径 | +|   `.delete_icon` | String | 删除按钮图标路径 | +|   `.new_data_url` | String | 新增记录提交的目标 URL | +|   `.update_data_url` | String | 更新记录提交的目标 URL | +|   `.delete_data_url` | String | 删除记录提交的目标 URL | +| `toolbar` | Object | 自定义工具栏描述对象，包含额外命令按钮 | +| `row_options` | Object | 行渲染相关选项 | +|   `.fields` | Array | 字段定义数组，每个字段包含 name, uitype 等信息 | +|   `.editexclouded` | Array | 在编辑/克隆时不显示的字段名列表 | + +> ⚠️ 所有初始化参数通过 `opts` 传入，构造函数会自动设置宽度为 `'100%'`、高度为 `'100%'`、溢出隐藏。 + +## 主要事件 + +| 事件名称 | 触发条件 | 传递数据（event.params）说明 | +|--------|--------|-----------------------------| +| `row_check_changed` | 当某一行的选择状态发生变化时触发（由子类或内部机制调用） | 包含该行用户数据的对象（`user_data`） | +| `` | 工具栏中非内置按钮被点击时，以按钮 `name` 分发自定义事件 | 若当前有选中行，则携带该行的 `user_data`；否则为 null | +| `command` | 内部使用，来自 `IconTextBar` 的原始命令事件 | 原始工具项描述 `{ name, selected_row }` | + +> 💡 特殊命令处理： +> - `add`: 弹出新增表单窗口 +> - `update`: 弹出修改当前选中行的表单 +> - `clone`: 弹出基于当前行复制的新建表单 +> - `delete`: 弹出确认框并执行删除动作 + +--- \ No newline at end of file diff --git a/docs/ai/descjson.md b/docs/ai/descjson.md new file mode 100644 index 0000000..bb1cf6c --- /dev/null +++ b/docs/ai/descjson.md @@ -0,0 +1,40 @@ +# 应用开发源码.ui后缀文件规格说明 +Bricks在服务器端使用Json文件格式的.ui后缀文件存储控件描述文件，前端获得.ui文件的json后转化为json对象，并用此json对象调用widgetBuild函数创建Bricks控件。 + +.ui文件支持jinja2模版，所以可以动态生成前端控件属性和数据 + +控件描述数据规格要求 +``` +{ + "id" # 可选，缺少动态生成一个uuid类型的id + "widgettype" # widgettype是一个字符串属性。其值为Bricks中的注册的控件名称或"urlwidget" "options" # 对象类型，给定控件实例化的初始化参数，参看每个控件的说明 + "subwidgets" # 数组类型，只有容器控件需要，数组中的每个元素为子控件的控件描述数据 + "binds" # 定义事件处理，参看后面的事件处理说明 +} +``` +控件描述json文件必须含有“widgettype” 和”options“两个属性。“subwidgets”属性用来定义此控件包含的子控件。“binds”用于定义此控件或其子控件的事件处理 + +## widgettype说明 +其值为Bricks中的注册的控件名称或"urlwidget", widgettype定义此控件是bricks的哪个控件，值为“urlwidget”时，控件数据从服务器中获取，其options有特殊约定 + +## options +控件初始化参数，可以是控件本身定义初始化参数，也可以是祖先类的初始化参数，当widgettype等于urlwidget时，options要符合下列规格 +{ + "url" # 获得控件数据的url + "method" # http方法（如“GET”，“POST” 。。。） + "params" # 字典数据，http请求所带的参数 +} + +## binds +列表属性，定义控件的事件处理，在列表中的每一项，定义一个事件处理， Bricks支持5种事件处理方法， +分别是urlwidget, method, script, registedfunction和event + +在binds中这五种事件处理方法都可以定义，在同一个控件中可以灵活的使用不同事件处理方法来响应不同控件的不同事件， +支持： +* 可定义bings所在控件的事件处理 +* 可定义binds所在控件的子（孙）控件的事件处理 +* 可定义应用控件树上任何‘wid’对应的控件的事件处理 +* 同一个控件的同一个事件，使用多个处理方法按定义顺序依次处理 + +详细事件处理请参看[bricks的事件处理](event.md) + diff --git a/docs/ai/docxviewer.md b/docs/ai/docxviewer.md new file mode 100644 index 0000000..0ec1a6f --- /dev/null +++ b/docs/ai/docxviewer.md @@ -0,0 +1,77 @@ +# DOCXviewer + +**控件功能**：用于在网页中嵌入并显示 `.docx` 文档内容，通过 Mammoth.js 将 Word 文档转换为 HTML 并渲染。 +**类型**：普通控件（继承自容器控件 VBox） +**父类控件**：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `url` | String | 指向 .docx 文件的 URL 地址，将在 `on_parent` 事件触发时加载 | + +> ⚠️ 注意：需提前引入 Mammoth.js 库（如 CDN 资源）才能正常工作。 + +## 主要事件 + +| 事件名 | 触发时机 | 回调参数 | 说明 | +|--------|----------|---------|------| +| `on_parent` | 控件被添加到父容器后触发 | - | 自动调用 `set_url(this.url)` 开始加载并渲染文档 | + +--- + +# EXCELviewer + +**控件功能**：用于查看 Excel 文件（`.xlsx` 或 `.xls`），支持多工作表切换展示表格数据。 +**类型**：容器控件 +**父类控件**：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `url` | String | 指向 Excel 文件的 URL 地址，在 `on_parent` 时加载 | +| `height` | String | 默认设置为 `"100%"`，确保高度占满父容器 | + +## 主要事件 + +| 事件名 | 触发时机 | 回调参数 | 说明 | +|--------|----------|---------|------| +| `on_parent` | 控件挂载到父节点后 | - | 触发 `set_url(url)` 加载 Excel 数据 | +| `click`（子 Text 控件） | 点击某个 sheet 标签时 | sheetname, widget | 切换并显示对应的工作表内容 | + +> ✅ 支持特性： +> - 动态生成工作表标签栏（HBox + Text） +> - 可滚动区域展示表格 HTML 内容（VScrollPanel） +> - 当前选中标签高亮（CSS 类 `selected`） + +--- + +# PDFviewer + +**控件功能**：用于在页面中内嵌显示 PDF 文件，逐页渲染为 Canvas 图像。 +**类型**：容器控件 +**父类控件**：`bricks.VBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `url` | String | PDF 文件的 URL 地址，由 `set_url` 使用 | +| `width` | String | 强制设为 `'100%'`，以适配父容器宽度 | + +## 主要事件 + +| 事件名 | 触发时机 | 回调参数 | 说明 | +|--------|----------|---------|------| +| `on_parent` | 控件挂载完成后 | - | 调用 `set_url()` 启动 PDF 加载与渲染 | +| （内部 Promise） | PDF 成功加载后 | pdf 对象 | 遍历所有页调用 `add_page_content(page)` | +| （错误处理） | 加载失败时 | error | 输出 `'error'` 到控制台 | + +> ✅ 渲染细节： +> - 使用 `pdfjsLib`（Mozilla PDF.js）解析和绘制 PDF +> - 每页使用 `` 渲染，缩放比例固定为 `1.5` +> - 页面之间插入 `Splitter` 分隔条（视觉或布局用途） + +> ⚠️ 注意：需确保全局已定义 `pdfjsLib` 并正确配置。 + diff --git a/docs/ai/dynamicaccordion.md b/docs/ai/dynamicaccordion.md new file mode 100644 index 0000000..f8668d4 --- /dev/null +++ b/docs/ai/dynamicaccordion.md @@ -0,0 +1,46 @@ +# DynamicAccordion + +**控件功能**: 动态可折叠列表控件，支持分页加载、远程数据获取、内容懒加载、增删改查操作及工具栏自定义。适用于展示大量可折叠结构化数据。 +**类型**: 容器控件 +**父类控件**: bricks.VScrollPanel + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `data_url` | String | 数据请求地址，用于加载列表数据 | +| `data_method` | String | 请求方法（GET/POST等），默认为 GET | +| `cache_limit` | Number | 缓存页数限制，控制内存中保留的数据页数量 | +| `page_rows` | Number | 每页请求的数据行数 | +| `row_cheight` | Number | 每行高度系数，默认为 `1.5` | +| `record_view` | Object/String | 每条记录在标题区的渲染模板（widget 描述或名称） | +| `content_rely_on` | String | 内容是否展开依赖的字段名 | +| `content_rely_value` | Any | 当 `content_rely_on` 字段等于该值时才加载内容 | +| `editable` | Object | 编辑配置对象，包含新增、修改、删除相关设置 | +|   `.add_icon` | String | 新增按钮图标路径 | +|   `.update_icon` | String | 更新按钮图标路径 | +|   `.delete_icon` | String | 删除按钮图标路径 | +|   `.form_cheight` | Number | 表单高度系数 | +|   `.new_data_url` | String | 添加新记录提交地址 | +|   `.update_data_url` | String | 更新记录提交地址 | +|   `.delete_data_url` | String | 删除记录提交地址 | +| `fields` | Array | 字段定义数组，用于表单和数据显示 | +| `record_toolbar` | Object | 每行右侧工具栏配置（图标按钮组） | +| `record_toolbar_collapsable` | Boolean | 工具栏是否可折叠（暂未实现细节） | +| `header` | Object | 表头配置（预留） | +| `content_view` | Object/String | 展开后内容区域的渲染模板 | +| `title` | String | 控件顶部标题文本（可选） | +| `description` | String | 控件描述文本（可选） | +| `toolbar` | Object | 顶部工具栏配置（传给 `IconTextBar`） | + +## 主要事件 + +| 事件名 | 触发条件 | 参数 | +|--------|----------|------| +| `row_selected` | 用户点击某一行时触发 | `info`: 被点击的 `AccordionInfo` 实例 | +| 自定义事件（通过 `record_toolbar.tools[i].name` 定义） | 点击行内自定义工具按钮时触发 | `record`: 当前行数据对象 | +| `conformed`（内部使用） | 删除确认弹窗用户确认后触发 | 传递至 `delete_record_act` 方法处理 | +| `submited`（嵌套表单） | 新增/编辑表单提交成功后触发 | 响应数据 `event.params` | +| `cancel`（嵌套表单） | 表单取消操作时触发 | 关闭当前编辑区域 | + +> 注：部分事件为子组件触发并由 `DynamicAccordion` 监听处理，例如 `submited`, `cancel`, `click` 等。 diff --git a/docs/ai/dynamiccolumn.md b/docs/ai/dynamiccolumn.md new file mode 100644 index 0000000..9b7f2db --- /dev/null +++ b/docs/ai/dynamiccolumn.md @@ -0,0 +1,27 @@ +# DynamicColumn + +控件功能：动态列布局容器，根据屏幕尺寸和配置自动调整网格列数与列宽，适用于响应式布局场景。 +类型：容器控件 +父类控件：Layout + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------------|--------|------| +| `col_cwidth` | Number | （可选）每列的字符宽度单位（基于 `charsize`），用于计算列宽。若未设置且无 `col_width`，默认为 20。 | +| `col_width` | Number | （可选）每列的固定像素宽度。优先级低于 `col_cwidth`。 | +| `col_cgap` | Number | （可选）列之间的间隙大小（以 `charsize` 为单位），默认值为 `0.5`。 | +| `mobile_cols`| Number | （可选）在移动端竖屏模式下强制使用的列数，默认值为 `1`。 | + +> 注意：如果 `col_cwidth` 和 `col_width` 都未提供，则 `col_cwidth` 默认设为 20。 + +## 主要事件 + +- **`on_parent`** + 当控件被添加到父容器时触发，用于初始化或重新计算列宽。 + +- **`resize`** + 浏览器窗口尺寸变化时触发，动态调整 `gridTemplateColumns` 和 `gap` 以适应新尺寸。 + +- **`charsize`**（来自 `bricks.app`） + 字符尺寸发生变化时触发（通常因字体或缩放改变），用于重新计算基于字符单位的列宽和间隙。 diff --git a/docs/ai/event.md b/docs/ai/event.md new file mode 100644 index 0000000..03527a0 --- /dev/null +++ b/docs/ai/event.md @@ -0,0 +1,512 @@ +# bricks控件的事件处理 +bricks控件的事件处理是在控件描述数据的binds属性中添加事件处理数据来实现的 +## bricks支持的事件处理类型 +* urlwidget +* method +* script +* registerfunction +* event + +例外还支持一种混合型 + +* actions + +在事件处理定义中使用"actiontype"属性来定义事件处理类型 + +## 事件处理定义数据要素 + +所有事件处理类型都有的数据要素有 +### wid +事件发起控件id，“self"表示是binds属性所在的控件，id支持“a.b.c“格式，说明从当前位置先找到id为a的控件，再从a位置找到控件id为b的控件，再从b位置找到id为c的控件 + +#### 特殊约定的控件id +* self -- binds所在的控件 +* root -- 下的第一个控件 +* body/app -- bricks.app +* -x -- 从当前位置向上找祖先类控件id为x的控件 + +### event +支持控件的html原生事件以及控件类中定义的事件，或者是event事件处理类型中dispatch_event属性中定义的事件 + +### actiontype +指定事件处理类型，支持“urlwidget", "method", "script", "registerfunction", "event"， 或者“actions”混合型 + +### conform +对象类型，确认控件的options，如存在，则此绑定需要用户确认后再执行 + +### datawidget +给事件添加动态参数时定义获取动态参数的控件的id，关于datawidget规则请查看[控件id](widgetid.md) + +如果不需要使用动态参数，那么datawidget, datamethod, datascript, dataparams这几个属性可以不设置。 + +### datamethod +获取动态参数的方法 +### datascript +获取动态参数的脚本 +### dataparams +获取动态参数时需给定的参数, 可选，对象类型，k,v形式给定参数 + +### popup_options +当target为“Popup“或“PopupWindow”时，定义Popup或PopupWindow的参数 + +#### dismiss_events +字符串数组，每个字符串定义一个Popup, PopupWindow的子控件的事件，这些事件发生时将导致Popup, PopupWindow关闭 + +#### eventpos +Popup, PopupWindow窗体移动到鼠标位置 + +### 获取动态参数说明 +绑定任务获取实时数据作为参数，需要给定以下属性： +* datawidget：字符串或控件类型，获取实时数据的控件 +* datamethod：字符串类型，控件的方法，使用params作为参数调用， +获取实时数据的方法 +* datascript：字符串类型， js脚本，使用return返回数据 +* dataparams：参数 +datamethod 优先datascript，从datawidget控件中通过datamethod + +### target +事件处理的目标控件， 支持下面形式的target定义： +* 目标控件实例对象 +* 字符串，且等于“Popup“ +* 字符串，且等于”PopupWindow“ +* 其他字符串（控件对象的id） +当actiontype为"urlwidget"时，target应该是一个容器控件，所生成的控件将插入或替代到“target”所代表的对象中，如果actiontype是其他类型,则在此对象中执行方法，脚本，定义函数，或定义事件 + +### conform +如果一个事件处理需要用户确认，可以在事件处理中指定一个conform属性来引发，当此事件发生时，会弹出一个确认窗口，用户确认后才会处理此事件，否则不处理 + +不同的事件处理方法也有部分不同的事件处理属性，一下分别说明： + +### urlwidget方法 +urlwidget事件处理方法是从后台获取一个控件描述文件，动态生成bricks控件，并将控件添加（添加，添加或替换）到事件target指定的控件中。 + +urlwidget绑定需要一个options属性和一个mode属性，在此属性中需要 +* url：字符串类型， 获取desc数据的url +* mehtod：字符串类型，url调用的方法，缺省”GET“ +* params：对象类型，调用的参数, 从datawidget获取的数据影响此属性 +绑定创建的控件添加到target控件中 + +例子 +``` +{ + "widgettype":"VBox", + "options":{ + "width":"100%", + "height":"100%" + }, + "subwidgets":[ + { + "widgettype":"HBox", + "options":{ + "height":"40px" + }, + "subwidgets":[ + { + "id":"replace", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"replace mode" + } + }, + { + "id":"insert", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"insert mode" + } + }, + { + "id":"append", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"append mode" + } + } + ] + }, + { + "id":"main", + "widgettype":"Filler" + } + ], + "binds":[ + { + "wid":"replace", + "event":"click", + "actiontype":"urlwidget", + "target":"main", + "options":{ + "url":"{{entire_url('replace_text.ui')}}", + "params":{ + "text":"Insert before" + } + } + }, + { + "wid":"insert", + "event":"click", + "actiontype":"urlwidget", + "target":"main", + "options":{ + "url":"{{entire_url('insert_text.ui')}}", + "params":{ + "text":"Insert before" + } + }, + "mode":"insert" + }, + { + "wid":"append", + "event":"click", + "actiontype":"urlwidget", + "target":"main", + "options":{ + "url":"{{entire_url('subtext.ui')}}", + "params":{ + "text":"Append After" + } + }, + "mode":"append" + } + ] +} +``` +在上述例子中，我们使用了一个竖向排列的容器（VBox），并在此容器中添加了两个字控件，分别是一个横向排列的容器HBox，和一个填充器（Filler） +并在横向排列的子控件中添加了3个按钮控件, 每个Button定义了id， 分别是replace，insert，和append，在主控件（VBox）的binds中分别定义了三个事件处理，分别对应于3个Button的click事件，演示了三种子控件在target控件中插入的模式（替换所有子控件，插入在已有子控件之前，添加到已有子控件之后） + +### method方法 +需要指定target参数和method参数， +* target：类型为字符串或控件类型， +如果是字符串，使用“getWidgetById”函数获取控件实例。 +* method：字符串，target实例的方法， +* params：传递给方法的参数 +method绑定方法，将事件绑定到target控件的一个方法，并用params传递参数 + +例子 +``` +{ + "widgettype":"VBox", + "options":{ + "width":"100%", + "height":"100%" + }, + "subwidgets":[ + { + "widgettype":"HBox", + "options":{ + "height":"40px" + }, + "subwidgets":[ + { + "id":"changetext", + "widgettype":"Button", + "options":{ + "dynsize":false, + "width":"80px", + "i18n":true, + "label":"Change text" + } + }, + { + "id":"smaller", + "widgettype":"Button", + "options":{ + "dynsize":false, + "width":"80px", + "i18n":true, + "label":"Small size" + } + }, + { + "id":"larger", + "widgettype":"Button", + "options":{ + "dynsize":false, + "width":"80px", + "i18n":true, + "label":"larger size" + } + } + ] + }, + { + "widgettype":"Filler", + "options":{}, + "subwidgets":[ + { + "id":"text_1", + "widgettype":"Text", + "options":{ + "dynsize":true, + "text":"original text" + } + } + ] + } + ], + "binds":[ + { + "wid":"changetext", + "event":"click", + "actiontype":"method", + "target":"text_1", + "params":"new text", + "method":"set_text" + }, + { + "wid":"smaller", + "event":"click", + "actiontype":"method", + "target":"app", + "method":"textsize_smaller" + }, + { + "wid":"larger", + "event":"click", + "actiontype":"method", + "target":"app", + "method":"textsize_bigger" + } + ] +} +``` +上述例子中，三个Button分别驱动app中textsize_smaller()，textsize_bigger()来改变bricks字符大小，从而影响到text_1控件的显示大小 + +### script方法 +绑定脚本，此方法将事件绑定到一个脚本，支持以下属性 +* script：字符串，脚本正文 +* params：对象类型，脚本可以访问params变量来获取参数。 +脚本中可以使用以下变量： +* this 事件处理中target对应的控件实例 +* params：参数对象，datawidget获得的数据会添加到params中 + +例子 +``` +{ + "id":"insert", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"click me" + }, + "binds":[ + { + "wid":"self", + "event":"click", + "actiontype":"script", + "target":"self", + "script":"console.log(this, params, event);" + } + ] +} +``` +在上述例子中定义了使用“script”事件处理方法来处理Button的“click事件”， 在click后在控制台上把事件传过来的参数显示出来 + +### registerfunction方法 +事件绑定一个注册函数， 参看[RegisterFunction](registerfunction.md) +支持以下属性： +* rfname：字符串，已注册的函数名称 +* params：对象类型，调用注册函数时作为参数传递给注册函数。 + +``` + + + + + + + + + + + + + + + +``` +在上述例子中，使用bricks.RF注册了一个setText函数， 并在主控件的binds区域定义了当changetext按钮点击后调用注册函数“setText”来处理 + +### event方法 +绑定事件，需指定target，触发target对象的一个事件 +支持以下属性 +dispatch_event：需触发的事件名 +params：传递给事件的参数，处理函数可以使用evemt.params获得此参数 + +``` +{ + "widgettype":"VBox", + "options":{}, + "subwidgets":[ + { + "id":"btn1", + "widgettype":"Button", + "options":{ + "label":"press me" + } + }, + { + "id":"txt1", + "widgettype":"Text", + "options":{ + "otext":"I will dispatch a event when btn1 pressed", + "i18n":true + } + } + ], + "binds":[ + { + "wid":"btn1", + "event":"click", + "actiontype":"event", + "target":"txt1", + "dispatch_event":"gpc" + }, + { + "wid":"txt1", + "event":"gpc", + "actiontype":"script", + "target":"self", + "script":"alert('yield');" + } + ] +} +``` +上述例子中，在主控件的binds区域定义了btn1的按钮点击后使用event处理类型来处理btn1的click事件，即转而触发“txt1”正文控件的“gpc”事件，并定义了当”txt1“正文控件在gpc事件发生后使用script事件处理方法alert一个消息 + +## 定义需要确认的事件处理 +有时候我们需要客户确认后在处理事件，如果用户不确认，则放弃处理事件，比如在删除数据时我们通常需要用户确认一下 +例子 +``` +{ + "id":"insert", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"click me" + }, + "binds":[ + { + "wid":"self", + "event":"click", + "actiontype":"script", + "conform":{ + "title":"conformtest", + "message":"测试事件处理前的用户确认功能，确认码？" + }, + "target":"self", + "script":"alert('确认过眼神!')" + } + ] +} +``` +上述例子中定义了Button的click事件使用script事件处理方式来处理，但是在处理前需要显示信息，让用户确认是否继续，如果用户放弃则不处理事件，确认后正常的处理事件。 + diff --git a/docs/ai/factory.md b/docs/ai/factory.md new file mode 100644 index 0000000..d9204d2 --- /dev/null +++ b/docs/ai/factory.md @@ -0,0 +1,22 @@ +# Factory_ + +## 控件功能 +`Factory_` 是一个用于注册和获取控件（或组件）的工厂类，提供全局唯一的控件注册与管理机制。通过该类可以动态地注册自定义控件，并在需要时根据名称获取对应的控件构造函数或类。 + +- **类型**：普通控件（工具类/管理器） +- **父类控件**：无（原生 JavaScript 类） + +## 初始化参数 +- 无显式外部传参的构造函数。 +- 内部初始化时创建一个 `widgets_kv` 对象，用于存储注册的控件映射表： + - 初始化包含一个保留键 `_t_`，值为 `1`，可能用于版本标识或存在性检测。 + +## 主要事件 +- 本控件不触发任何 UI 事件。 +- 提供以下方法作为核心行为接口： + - `register(name: string, widget: function/class)` + 将指定名称 `name` 与控件类/函数 `widget` 进行绑定注册。 + - `get(name: string): function/class | null` + 根据名称查询已注册的控件，若不存在则返回 `null`。 + +> 注：此控件通常作为底层基础设施使用，被 `bricks` 框架用来统一管理所有可视化控件或业务组件的生命周期与访问入口。 \ No newline at end of file diff --git a/docs/ai/floaticonbar.md b/docs/ai/floaticonbar.md new file mode 100644 index 0000000..2ad7581 --- /dev/null +++ b/docs/ai/floaticonbar.md @@ -0,0 +1,117 @@ +# IconBar + +控件功能：创建一个图标工具栏，包含多个可点击的SVG图标按钮，支持选中状态和事件分发。 +类型：容器控件 +父类控件：`bricks.HBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `opts.cheight` | Number | 子控件高度（字符单位），默认值为 `2` | +| `opts.rate` | Number | 缩放比例，影响图标大小，默认值为 `1` | +| `opts.margin` | String | 图标之间的左右边距，CSS格式（如 `'10px'`） | +| `opts.tools` | Array | 工具项数组，每个工具项是一个对象，包含以下字段：
- `name`: 工具名称（用于标识和事件）
- `icon`: SVG图标的URL
- `rate`: 当前图标的缩放比例（可选）
- `dynsize`: 是否动态调整尺寸（布尔值）
- `tip`: 提示文本（可选） | + +> 如果未提供 `cheight` 或 `rate`，会自动设置默认值。 + +## 主要事件 + +| 事件名 | 触发条件 | 携带数据 | +|--------|---------|--------| +| `desc.name`（即 `tools[i].name`） | 点击某个图标时触发，事件名为该图标的 `name` 字段 | 传递对应图标的 `desc` 对象 | +| `command` | 所有图标点击都会触发此统一事件 | 传递当前图标的 `desc` 对象 | + +> 事件通过 `dispatch` 分发，可用于外部监听具体命令或通用操作。 + +--- + +# IconTextBar + +控件功能：扩展自 `IconBar`，每个工具项显示为“图标 + 文本”组合形式，适用于需要标签说明的工具栏。 +类型：容器控件 +父类控件：`bricks.IconBar` + +## 初始化参数 + +继承 `IconBar` 的所有参数，并增强 `tools` 数组中每一项的支持： + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `opts.tools[i].label` | String | 显示在图标旁边的文本标签 | +| `opts.tools[i].tip` | String | 鼠标悬停提示文本，会应用到整个图标+文本容器上 | +| 其他参数同 `IconBar` | —— | 支持 `name`, `icon`, `rate`, `dynsize` 等 | + +> 每个工具项会被构造成一个水平布局（`HBox`），内部依次添加 `Svg` 和 `Text` 控件。 + +## 主要事件 + +与 `IconBar` 完全一致： + +| 事件名 | 触发条件 | 携带数据 | +|--------|---------|--------| +| `desc.name` | 点击某一项时触发，事件名为其 `name` | 对应的 `desc` 对象 | +| `command` | 所有点击均触发此事件 | 当前项的 `desc` 对象 | + +> 事件绑定在整体 `HBox` 上，点击任意部分（图标或文字）都会触发。 + +--- + +# FloatIconBar + +控件功能：浮动式图标工具栏，初始只显示一个“外挂图标”，鼠标移入时展开完整的 `IconBar`。常用于侧边悬浮工具栏。 +类型：容器控件 +父类控件：`bricks.HBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `opts` | Object | 传递给内部 `IconBar` 的配置对象，结构同 `IconBar` 的 `opts.tools` 等 | +| 内部使用 `bricks_resource('imgs/float-out.png')` | —— | 固定的浮出按钮图标 | + +> 实际工具项由传入的 `opts` 构建内部 `IconBar` 使用。 + +## 主要事件 + +与内部 `IconBar` 保持一致： + +| 事件名 | 触发条件 | 携带数据 | +|--------|---------|--------| +| `desc.name` | 用户点击展开后的某个图标时触发 | 对应图标的 `desc` 对象 | +| `command` | 所有图标点击都会触发 | 当前图标的 `desc` 对象 | + +> 事件来自内嵌的 `IconBar` 实例，自动透传。 + +此外还具备行为事件： +- `mousemove` 在浮出图标上触发展开菜单 +- 页面任意位置 `click` 触发收起菜单（通过监听 `bricks.Body`） + +--- + +# FloatIconTextBar + +控件功能：浮动式“图标+文本”工具栏，是 `FloatIconBar` 的扩展版本，展开后显示带文字标签的工具项。 +类型：容器控件 +父类控件：`bricks.FloatIconBar` + +## 初始化参数 + +与 `FloatIconBar` 相同： + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `opts` | Object | 包含 `tools` 数组及其他配置，在内部构建 `IconTextBar` 时使用 | + +> 内部调用 `build_bar(opts)` 创建的是 `IconTextBar` 实例，因此支持 `label`、`tip` 等文本相关属性。 + +## 主要事件 + +与 `IconTextBar` 一致： + +| 事件名 | 触发条件 | 携带数据 | +|--------|---------|--------| +| `desc.name` | 点击展开后的某一项时触发 | 该项的 `desc` 对象 | +| `command` | 所有点击都触发 | 当前项的 `desc` 对象 | + +> 所有事件均由内部 `IconTextBar` 实例发出，自动向上冒泡。 \ No newline at end of file diff --git a/docs/ai/gobang.md b/docs/ai/gobang.md new file mode 100644 index 0000000..97b2f5a --- /dev/null +++ b/docs/ai/gobang.md @@ -0,0 +1,58 @@ +# GobangPoint + +控件功能：表示五子棋棋盘中的一个棋位点，根据状态显示为空、黑子或白子，并支持鼠标悬停效果。 +类型：普通控件 +父类控件：`bricks.Image` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `p_status` | Number | 棋位状态：0 表示空，1 表示黑子，2 表示白子 | +| `p_x` | Number | 水平位置，取值范围为 1 到 15 | +| `p_y` | Number | 垂直位置，取值范围为 1 到 15 | +| `tip` | String (可选) | 鼠标提示文本 | + +> 注：构造函数会自动调用 `calc_url()` 根据位置和状态生成对应的图片路径，并通过 `set_url()` 设置图像源。 + +## 主要事件 + +- **`mouseover`** + 当鼠标进入控件区域时触发，调用 `set_current_position(true)`，设置当前坐标高亮样式（添加 `curpos` CSS 类）。 + +- **`mouseout`** + 当鼠标离开控件区域时触发，调用 `set_current_position(false)`，移除高亮样式。 + +--- + +# Gobang + +控件功能：实现一个 15×15 的五子棋游戏界面容器，负责渲染棋盘、管理棋位状态、响应玩家回合逻辑。 +类型：容器控件 +父类控件：`bricks.VBox` + +## 初始化参数 + +无显式外部传参，内部初始化如下： + +- 自动创建一个 `Filler` 占位控件用于自适应布局 +- 创建并渲染一个 15×15 的棋盘点阵（使用 `GobangPoint`） +- 绑定窗口尺寸变化响应，动态调整每个棋格大小以保持正方形且填满可用空间 + +## 主要事件 + +- **`element_resize`（绑定在 `filler` 上）** + 当 `filler` 的 DOM 元素尺寸发生变化时触发，调用 `resize_area()` 方法重新计算每个棋格的宽高，确保棋盘等比缩放适配容器。 + +### 自定义方法说明 + +- `render_empty_area()` + 初始化并渲染空白棋盘，创建嵌套的 `VBox` 和 `HBox` 结构来排列 15×15 的 `GobangPoint` 实例，并存储于 `this.area[i][j]` 中供后续操作。 + +- `resize_area()` + 根据 `filler` 的实际尺寸动态计算每个棋格的大小（取最小边长除以 15），并对所有 `GobangPoint` 设置统一的宽高样式。 + +- `inform_go(party)` + （当前为空实现）用于通知指定方（如 `'black'` 或 `'white'`）进行下一步操作，可用于集成 AI 或网络对战逻辑。 + +> 注：该控件通过 `bricks.Factory.register('Gobang', bricks.Gobang);` 注册，可在模板中以 `` 形式使用。 \ No newline at end of file diff --git a/docs/ai/html.md b/docs/ai/html.md new file mode 100644 index 0000000..60a79af --- /dev/null +++ b/docs/ai/html.md @@ -0,0 +1,21 @@ +# Html + +控件功能：用于在页面中插入自定义的 HTML 内容。 +类型：普通控件 +父类控件：`bricks.JsWidget` + +## 初始化参数 + +- `html` (String) + 要插入到控件中的 HTML 字符串内容。该内容将被设置为控件 DOM 元素的 `innerHTML`。 + +示例： +```js +new bricks.Html({ + html: '
这是一个红色的文本
' +}); +``` + +## 主要事件 + +无主要事件（继承自父类的通用事件，如 `init`, `render` 等，但本控件未定义特定事件）。 \ No newline at end of file diff --git a/docs/ai/iconbarpage.md b/docs/ai/iconbarpage.md new file mode 100644 index 0000000..39d5785 --- /dev/null +++ b/docs/ai/iconbarpage.md @@ -0,0 +1,34 @@ +# IconbarPage + +控件功能：一个带有图标工具栏的页面容器，支持在顶部或底部放置图标工具栏（IconTextBar），点击工具项可动态加载并显示对应的内容组件。 +类型：容器控件 +父类控件：bricks.VBox + +## 初始化参数 + +- `opts`：配置对象，包含以下属性： + - `bar_opts` *(Object)*：图标工具栏的配置选项，传递给 `bricks.IconTextBar`。 + - `margin` *(String | Number)*：工具栏的外边距。 + - `rate` *(Number)*：布局中所占比例。 + - `tools` *(Array)*：工具项数组，每个工具项为一个对象，结构如下： + - `name` *(String)*：工具的名称，用于标识。 + - `icon` *(String)*：图标的类名或路径。 + - `label` *(String, 可选)*：工具的文本标签。 + - `tip` *(String)*：鼠标悬停时的提示信息。 + - `dynsize` *(Boolean)*：是否动态调整大小。 + - `rate` *(Number)*：该工具在布局中的占比。 + - `content` *(Object | String)*：描述要加载的子控件的配置或类型名，用于动态构建内容。 + - `bar_at` *(String)*：指定工具栏位置，可选值为 `'top'` 或 `'bottom'`，默认为 `'top'`。 + +> 注意：构造函数会自动设置 `height: '100%'`。 + +## 主要事件 + +- `command` 事件： + - 来源：内部 `IconTextBar` 实例触发。 + - 回调参数：`event.params` 包含被点击的 `tool` 对象。 + - 行为：当用户点击某个工具图标时，`command_handle` 方法会被调用，并根据 `tool.content` 动态创建内容组件，替换当前显示区域的内容。 + +```javascript +bar.bind('command', this.command_handle.bind(this)) +``` diff --git a/docs/ai/iframe.md b/docs/ai/iframe.md new file mode 100644 index 0000000..52ff535 --- /dev/null +++ b/docs/ai/iframe.md @@ -0,0 +1,33 @@ +# NewWindow + +## 控件功能，类型（普通控件或容器控件），父类控件 +- **控件功能**：打开一个新浏览器窗口，加载指定 URL。 +- **控件类型**：普通控件 +- **父类控件**：`bricks.JsWidget` + +## 初始化参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|--------|------|------| +| `url` | string | 是 | 要在新窗口中打开的页面 URL。 | +| `name` | string | 否 | 新窗口的名称（即 `window.open` 的第二个参数），默认为 `'_blank'`，表示新建标签页。 | + +## 主要事件 +无主要事件。该控件在初始化时立即执行 `window.open()`，不提供可监听的事件。 + +--- + +# Iframe + +## 控件功能，类型（普通控件或容器控件），父类控件 +- **控件功能**：创建一个内嵌的 iframe 框架，用于在当前页面中嵌入另一个网页，支持设置高度并自动加载指定 URL。 +- **控件类型**：普通控件 +- **父类控件**：`bricks.Layout` + +## 初始化参数 +| 参数名 | 类型 | 必填 | 说明 | +|----------|--------|------|------| +| `url` | string | 是 | 要嵌入的 iframe 页面地址。 | +| `height` | string 或 number | 否 | iframe 的高度，默认值为 `'100%'`。 | + +## 主要事件 +无主要事件。该控件在构造函数中直接设置 `src` 属性，加载页面，未定义自定义事件。 \ No newline at end of file diff --git a/docs/ai/image.md b/docs/ai/image.md new file mode 100644 index 0000000..3ef600f --- /dev/null +++ b/docs/ai/image.md @@ -0,0 +1,109 @@ +# Image + +## 控件功能，类型（普通控件或容器控件），父类控件 +用于显示图片的控件。支持设置图片 URL、默认错误备用图，以及将当前图像内容导出为 Base64 字符串。 +**类型：** 普通控件 +**父类控件：** `bricks.JsWidget` + +### 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------|------|------| +| `url` | String | 图片的 URL 地址，构造时会自动设置到 `` 元素的 `src` 属性 | +| `default_url` | String | 当图片加载失败时，自动切换为此 URL 显示备用图 | +| `height` | Number (可选) | 设置图片高度（可由 CSS 或 DOM 自动处理） | +| `width` | Number (可选) | 设置图片宽度（可由 CSS 或 DOM 自动处理） | + +> 注：所有参数通过 `opts` 对象传入构造函数。 + +### 主要事件 + +无显式定义事件，但内部使用了原生 `` 的 `onerror` 事件来处理加载失败情况： + +- **`onerror` → 触发 `set_default_url()`** + 当图片加载失败时，自动替换为 `default_url` 指定的备用图片，并清除错误监听以防止循环触发。 + +--- + +# Icon + +## 控件功能，类型（普通控件或容器控件），父类控件 +基于 `Image` 扩展的图标控件，支持字符单位尺寸缩放（`charsize` 基础）、动态大小调整和布局适配。常用于界面中与文字对齐的小图标。 +**类型：** 普通控件 +**父类控件：** `bricks.Image` + +### 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `url` | String | 图标图片地址，继承自 `Image` | +| `rate` | Number | 缩放倍率，默认为 `1`，实际大小 = `charsize * rate` | +| `cwidth` | Number | 占据的字符宽度，默认为 `1` | +| `cheight` | Number | 占据的字符高度，默认为 `1` | +| `dynsize` | Boolean | 是否启用动态尺寸调整，默认为 `true`，根据 `charsize_sizing()` 调整尺寸 | + +> 注：`charsize` 来源于 `bricks.app.charsize`，是应用级字体基准单位。 + +### 主要事件 + +无独立事件定义，行为主要在初始化和属性变更后通过 `options_parse()` 触发重绘。 + +- **`options_parse()`** + 在控件初始化时调用，用于解析并应用尺寸相关选项，包括设置 URL 和调整大小。 + +--- + +# StatedIcon + +## 控件功能，类型（普通控件或容器控件），父类控件 +状态图标控件，可依据不同状态切换对应图标图像。适用于如开关状态、多态指示器等场景。 +**类型：** 普通控件 +**父类控件：** `bricks.Icon` （间接继承 `Image`） + +### 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `states` | Array<{state: String, url: String}> | 状态数组，每个对象包含一个状态名和对应的图片 URL | +| `state` | String | 初始状态名称；若未指定，则默认使用 `states[0].state` | +| `rate`, `cwidth`, `cheight`, `dynsize` | 同上 | 继承自 `Icon` 的布局与样式参数 | + +> 示例： +> ```js +> { +> states: [ +> { state: 'normal', url: 'icon-normal.png' }, +> { state: 'active', url: 'icon-active.png' } +> ], +> state: 'normal' +> } +> ``` + +### 主要事件 + +- **`set_state(state)`** + 方法：手动设置当前状态，控件会查找匹配的状态项并更新图片 URL，重新解析选项并渲染。 + - 参数：`state` —— 要切换到的状态字符串 + - 行为：遍历 `this.states`，找到对应项后调用 `super.options_parse()` 更新视图 + +--- + +# BlankIcon + +## 控件功能，类型（普通控件或容器控件），父类控件 +空白占位图标控件，不显示任何图像，仅作为具有固定字符尺寸的透明占位符，用于布局对齐或动态替换前的预留空间。 +**类型：** 普通控件 +**父类控件：** `bricks.JsWidget` + +### 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `rate` | Number | 尺寸缩放比率，默认为 `1`，影响基于 `charsize` 的计算 | +| `cwidth` | Number | 占据的字符宽度，默认为 `1` | +| `cheight` | Number | 占据的字符高度，默认为 `1` | +| `dynsize` | Boolean | 是否启用动态尺寸调整，默认为 `true`，控制是否响应 `charsize_sizing()` | + +### 主要事件 + +无公开事件或回调。其核心作用是在 UI 布局中保持与其他图标一致的尺寸行为，而不加载任何图像资源。 \ No newline at end of file diff --git a/docs/ai/input.md b/docs/ai/input.md new file mode 100644 index 0000000..55a6a72 --- /dev/null +++ b/docs/ai/input.md @@ -0,0 +1,372 @@ +# UiType + +**控件功能**：所有输入控件的基础类，提供通用的值获取、设置、重置、禁用等方法。 +**类型**：普通控件 +**父类控件**：`bricks.Layout` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `name` | string | 控件名称（必填） | +| `value` / `defaultvalue` | any | 默认值 | +| `required` | boolean | 是否为必填项，默认 `false` | + +## 主要事件 + +- `changed`：当控件值发生变化时触发，携带当前控件的键值对数据。 +- `blur`：失去焦点时可能被派发（由子类实现）。 + +--- + +# UiHide + +**控件功能**：隐藏字段控件，用于存储不显示的数据，DOM 显示为 `display: none`。 +**类型**：普通控件 +**父类控件**：`UiType` + +## 初始化参数 + +继承自 `UiType`，无额外参数。 + +## 主要事件 + +- `changed`：值变化时触发。 + +--- + +# UiStr + +**控件功能**：单行文本输入框，支持对齐、长度限制、占位符等功能。 +**类型**：普通控件 +**父类控件**：`UiType` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `align` | string | 文本对齐方式：`left`, `center`, `right` | +| `length` | number | 最大字符数（maxlength） | +| `minlength` | number | 最小字符数（minlength） | +| `tip` | string | 提示信息（暂未使用） | +| `width` | string | 输入框宽度（如 `'200px'`） | +| `readonly` | string/boolean | 是否只读 | +| `required` | boolean | 是否必填 | +| `placeholder` | string | 占位符文本（支持国际化） | +| `css` | string | 自定义 CSS 类名 | +| `dynsize` | boolean | 是否动态调整字体大小，默认 `true` | +| `cfontsize` | number | 字体缩放比例 | + +## 主要事件 + +- `focus`：获得焦点时触发。 +- `blur`：失去焦点时触发。 +- `changed`：输入内容改变且通过正则校验后触发。 +- `keydown`：按下 Enter 键时会触发 blur 事件。 + +--- + +# UiPassword + +**控件功能**：密码输入框，继承 `UiStr`，输入内容掩码显示。 +**类型**：普通控件 +**父类控件**：`UiStr` + +## 初始化参数 + +同 `UiStr`。 + +## 主要事件 + +同 `UiStr`。 + +--- + +# UiInt + +**控件功能**：整数输入框，自动限制只能输入数字，右对齐显示。 +**类型**：普通控件 +**父类控件**：`UiStr` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `length` | number | 输入最大位数（可选） | + +## 主要事件 + +- `changed`：输入合法整数时触发。 +- 值始终以整数形式返回（调用 `parseInt`）。 + +--- + +# UiFloat + +**控件功能**：浮点数输入框，支持小数位控制和步长设置。 +**类型**：普通控件 +**父类控件**：`UiInt` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `dec_len` | number | 小数点后保留位数，默认为 2 | + +## 主要事件 + +- `changed`：输入合法浮点数时触发。 +- 返回值为 `parseFloat(this.value)`。 + +--- + +# UiTel + +**控件功能**：电话号码输入框，使用 ``，支持自定义 pattern。 +**类型**：普通控件 +**父类控件**：`UiStr` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `pattern` | string | 正则表达式字符串，用于验证输入格式 | + +## 主要事件 + +- `changed`：输入符合 pattern 时触发。 + +--- + +# UiEmail + +**控件功能**：邮箱输入框，使用 ``，可附加自定义 pattern。 +**类型**：普通控件 +**父类控件**：`UiStr` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `pattern` | string | 可选的自定义正则验证规则 | + +## 主要事件 + +- `changed`：输入合法邮箱格式时触发。 + +--- + +# UiFile + +**控件功能**：文件上传控件，支持拖拽上传、点击选择文件，可限定文件类型和多选。 +**类型**：容器控件 +**父类控件**：`VBox` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `accept` | string | 接受的 MIME 类型前缀，如 `'image/'`, `'audio/'` | +| `multiple` | boolean | 是否允许多文件上传 | +| `width` | string | 容器宽度，默认 `'100%'` | + +## 主要事件 + +- `dragenter` / `dragover` / `dragleave` / `drop`：拖拽相关事件处理高亮与文件接收。 +- `changed`：选择或拖入文件后触发，传递文件对象或数组。 +- `input`：原生 input change 事件监听。 + +--- + +# UiImage + +**控件功能**：图像上传控件，支持拖拽、点击上传及拍照按钮，上传后预览图片。 +**类型**：容器控件 +**父类控件**：`UiFile` + +## 初始化参数 + +同 `UiFile`，默认 `accept='image/'`。 + +## 主要事件 + +- `changed`：文件选择或拍照完成后触发，附带 File 对象。 +- `shot`：拍照完成事件由 `SysCamera` 派发并被捕获。 + +--- + +# UiAudio + +**控件功能**：音频上传控件，支持录音功能（麦克风），上传后可播放预览。 +**类型**：容器控件 +**父类控件**：`UiFile` + +## 初始化参数 + +同 `UiFile`，默认 `accept='audio/'`。 + +## 主要事件 + +- `changed`：文件选择或录音完成后触发。 +- `record_end`：录音结束事件由 `SysAudioRecorder` 派发。 + +--- + +# UiVideo + +**控件功能**：视频上传控件，支持录制视频功能（摄像头），上传后可播放预览。 +**类型**：容器控件 +**父类控件**：`UiFile` + +## 初始化参数 + +同 `UiFile`，默认 `accept='video/'`。 + +## 主要事件 + +- `changed`：文件选择或录制完成后触发。 +- `record_end`：录像结束事件由 `SysVideoRecorder` 派发。 + +--- + +# UiCheck + +**控件功能**：复选框控件（视觉上是图标切换），表示布尔状态（true/false）。 +**类型**：普通控件 +**父类控件**：`UiType` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `value` | boolean | 初始是否选中 | + +## 主要事件 + +- `changed`：状态切换时触发，携带 `{name: true/false}` 数据。 +- `state_changed`：图标状态变更事件（来自 `MultipleStateIcon`）。 + +--- + +# UiCheckBox + +**控件功能**：多选/单选组控件，基于数据生成多个 `UiCheck` + 文本标签。支持静态数据或远程加载。 +**类型**：容器控件 +**父类控件**：`UiType` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `label` | string | 分组标题 | +| `data` | array | 静态选项列表 `[ {text:'', value:''} ]` | +| `dataurl` | string | 远程数据 URL | +| `method` | string | 请求方式，默认 GET | +| `params` | object | 请求参数 | +| `textField` | string | 显示字段名，默认 `'text'` | +| `valueField` | string | 值字段名，默认 `'value'` | +| `value` / `defaultValue` | string/array | 默认选中值（单选为字符串，多选为数组） | + +> 注：若 `multicheck` 属性存在且为真，则为多选模式。 + +## 主要事件 + +- `changed`：任一选项状态变化时触发，携带 `{name: selectedValue(s)}`。 +- 内部绑定 `UiCheck` 的 `changed` 事件进行值更新。 + +--- + +# UiDate + +**控件功能**：日期选择器，使用原生 ``，支持最小/最大日期限制。 +**类型**：普通控件 +**父类控件**：`UiStr` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `max_date` | string | 最大允许日期（格式 YYYY-MM-DD） | +| `min_date` | string | 最小允许日期（格式 YYYY-MM-DD） | + +## 主要事件 + +- `changed`：日期更改时触发。 +- `blur` / `focus`：焦点事件由父类支持。 + +--- + +# UiText + +**控件功能**：多行文本域（textarea），支持 Tab 缩进、回车换行、动态字体适配。 +**类型**：普通控件 +**父类控件**：`UiType` + +## 初始化参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `rows` | number | 行数，默认 5 | +| `cols` | number | 列数，默认 40 | +| `readonly` | boolean | 是否只读 | +| `required` | boolean | 是否必填 | +| `value` / `defaultvalue` | string | 默认文本内容 | + +## 主要事件 + +- `input`：内容变化时更新内部值。 +- `keydown`：拦截 Tab 和 Enter 键实现智能缩进与换行。 +- `changed`：内容变化时手动派发。 + +--- + +# UiCode + +**控件功能**：下拉选择框（`