diff --git a/docs/ai/audio.md b/docs/ai/audio.md new file mode 100644 index 0000000..49d571b --- /dev/null +++ b/docs/ai/audio.md @@ -0,0 +1,75 @@ +以下是根据你提供的源码，为其中定义的三个控件编写的符合要求的 **Markdown 格式控件文档**。每个控件均按照“一级标题为控件名称”、“包含控件功能、类型、父类”，以及“二级标题：初始化参数、主要事件”的格式编写。 + +--- + +# AudioPlayer + +**控件功能**：用于播放音频文件，支持本地 URL 或流式加载，具备播放、暂停、自动播放、播放队列和状态检测等功能。 +**类型**：普通控件 +**父类控件**：`bricks.JsWidget` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|----------|--------|------| +| `url` | String | 音频资源的 URL 地址，可选。构造时传入则立即加载。 | +| `autoplay`| Boolean| 是否在音频可播放后自动开始播放，默认为 `false`。 | + +## 主要事件 + +| 事件名 | 触发条件 | +|--------|---------| +| `ended` | 当前音频播放结束且播放列表为空时触发。 | + +--- + +# AudioRecorder + +**控件功能**：实现音频录制功能，基于浏览器麦克风权限进行 WAV 格式录音，提供开始/停止录音、实时时间显示、录音上传和下载功能。依赖第三方库 Recorder.js（WAV 格式）。 +**类型**：容器控件（继承自 HBox，包含按钮与文本） +**父类控件**：`bricks.HBox` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|-------------|--------|------| +| `upload_url` | String | 录音结束后自动上传的目标 URL 地址，可选。 | +| `start_icon` | String | 开始录音按钮显示的 SVG 图标路径，默认使用内置资源。 | +| `stop_icon` | String | 停止录音按钮显示的 SVG 图标路径，默认使用内置资源。 | +| `icon_rate` | Number | SVG 图标缩放比例，传递给内部 `Svg` 控件。 | + +## 主要事件 + +| 事件名 | 触发条件 | +|----------------|---------| +| `record_started` | 用户点击开始录音，麦克风授权成功后触发。 | +| `record_ended` | 用户停止录音，生成 blob 数据后触发，携带 `{data, url, duration}` 参数。 | +| `uploaded` | 成功上传录音文件到服务器后触发，携带服务器返回结果。 | + +> ⚠️ 注意：需引入外部库 [Recorder.js](https://gitee.com/xiangyuecn/Recorder) 支持录音功能。 + +--- + +# TextedAudioPlayer + +**控件功能**：结合音频播放与文本展示的复合控件，适用于语音朗读+字幕同步场景。支持从流式响应中逐段加载音频与对应文本，并自动顺序播放。 +**类型**：容器控件（垂直布局 VBox） +**父类控件**：`bricks.VBox` + +## 初始化参数 + +无独立初始化参数，内部自动创建子控件： + +- `AudioPlayer` 实例用于播放音频。 +- `Text` 实例用于显示对应文本内容。 +- `VScrollPanel` 提供文本区域滚动能力。 + +## 主要事件 + +无直接对外暴露的自定义事件。其行为由内部 `AudioPlayer` 的 `ended` 事件驱动，自动调用 `playnext()` 播放下一段内容。 + +> 内部通过 `set_stream_urls(response)` 接收流式 JSON 数据，每项应包含 `audio`（Base64 编码音频）、`text`（对应文字）、`done`（是否结束）字段。 + +--- + +> ✅ 所有控件均已通过 `bricks.Factory.register` 注册，可在模板或配置中通过字符串名称实例化。 \ No newline at end of file diff --git a/docs/ai/form.md b/docs/ai/form.md new file mode 100644 index 0000000..55864e1 --- /dev/null +++ b/docs/ai/form.md @@ -0,0 +1,122 @@ +以下是根据你提供的源码中定义的控件，按照要求编写的 **Markdown 格式控件文档**。每个控件均以一级标题命名，并包含其功能、类型、父类，以及“初始化参数”和“主要事件”两个二级标题。 + +--- + +# InlineForm + +**控件功能**：用于在行内嵌入一个可提交的表单，支持字段输入、验证及工具栏操作（提交、重置、取消）。适用于需要轻量级表单嵌入的场景。 +**类型**：普通控件 +**父类控件**：`bricks.FormBase` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `fields` | Array | 表单字段配置数组，每个字段对象包含 name、label、uitype 等信息。 | +| `height` | String | 可选，默认为 `"100%"`，设置控件高度。 | +| `width` | String | 可选，默认为 `"100%"`，设置控件宽度。 | +| `overflow` | String | 可选，默认为 `"auto"`，控制内容溢出时的显示方式。 | + +> 注意：所有选项通过 `opts` 传入构造函数。 + +## 主要事件 + +| 事件名 | 触发条件 | 回调参数 | +|--------|----------|---------| +| `submit(data)` | 用户点击“提交”按钮后，数据通过校验时触发。 | `data`: FormData 对象或普通对象，包含表单数据。 | +| `submited(resp)` | 提交请求完成后（无论成功或失败）触发。 | `resp`: 响应对象，可通过 `await resp.json()` 获取返回内容。 | +| `cancel` | 用户点击“取消”按钮时触发。 | 无参数。 | +| `reset` | 用户点击“重置”按钮时触发。 | 无参数。 | +| 自定义命令事件 | 当工具栏添加了自定义按钮且设置了 `action` 或名称时触发。 | `event.params` 包含按钮信息。 | + +--- + +# Form + +**控件功能**：完整的表单容器控件，支持标题、描述、多字段布局、文本与非文本字段分离、自动构建工具栏，并可配置提交 URL 和方法。适合独立页面或弹窗中的完整表单使用。 +**类型**：容器控件 +**父类控件**：`bricks.FormBase` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `title` | String | 可选，表单标题，显示为大号文字。 | +| `description` | String | 可选，表单描述信息，显示在标题下方。 | +| `fields` | Array | 必填，字段配置列表，结构同 InlineForm。 | +| `submit_url` | String | 可选，表单提交的目标 URL，若提供则自动发起 HTTP 请求。 | +| `method` | String | 可选，HTTP 方法，默认为 `'POST'`。 | +| `notoolbar` | Boolean | 可选，默认 `false`，是否隐藏默认工具栏（提交/重置/取消）。 | +| `toolbar` | Object | 可选，扩展或替换默认工具栏配置。结构 `{ tools: [...] }`。 | +| `input_layout` | String | 可选，输入框布局方式，支持 `"VBox"`（垂直）或 `"HBox"`（水平），默认 `"VBox"`。 | +| `dataurl` | String | （预留）可能用于加载初始数据的接口地址（当前未直接使用）。 | + +## 主要事件 + +| 事件名 | 触发条件 | 回调参数 | +|--------|----------|---------| +| `submit(data)` | 表单提交前，验证通过后触发。可用于拦截或预处理数据。 | `data`: 提交的数据对象或 FormData。 | +| `submited(resp)` | 向 `submit_url` 发送请求完成后触发。 | `resp`: Response 对象，可用于处理响应结果。 | +| `cancel` | 用户点击“取消”按钮时触发。 | 无参数。 | +| `reset` | 用户点击“重置”按钮时触发。 | 无参数。 | +| 自定义事件 | 工具栏中自定义按钮被点击且定义了 `action` 或事件名时触发。 | `event.params` 包含按钮元数据。 | + +--- + +# FormBody + +**控件功能**：`Form` 内部使用的主体内容区域，负责渲染所有非文本字段（通过 `FieldGroup`）和文本字段（只读展示），是实际输入区域的承载容器。 +**类型**：容器控件 +**父类控件**：`bricks.VScrollPanel` + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `form` | Object | 所属的表单实例，用于访问字段定义、name_inputs 等状态。 | +| `opts` | Object | 配置项，会自动设置 `width: '100%'`, `height: '100%'`。 | + +> 注：此控件通常不由开发者直接创建，而是由 `Form` 构造过程中内部实例化。 + +## 主要事件 + +该控件本身不对外派发事件，但作为容器继承了 `VScrollPanel` 的滚动相关能力，主要用于视觉呈现。 + +- 不主动触发业务事件。 +- 其子控件（如输入框）的变化会影响父级 `Form` 的状态。 + +--- + +# FieldGroup + +**控件功能**：辅助类，用于递归构建表单中的字段组（支持嵌套 group 结构），将字段按布局规则组织成动态列（DynamicColumn）和输入框容器（VBox/HBox）。 +**类型**：普通控件（逻辑组件） +**父类控件**：无（基础类） + +## 初始化参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| `opts` | Object | 目前未实际使用，保留扩展性。 | + +> 注：该类不是 UI 控件，不直接渲染 DOM，仅作为构建逻辑模块存在。 + +## 主要事件 + +该类无事件机制，仅为同步方法调用服务： + +- `build_fields(form, parent, fields)`：核心方法，递归生成字段 UI 并挂载到指定父容器。 + +--- + +> ✅ **说明总结**： +> +> - `InlineForm` 和 `Form` 是用户可直接使用的表单控件； +> - `FormBody` 和 `FieldGroup` 是内部实现组件，一般无需单独文档化使用； +> - 所有表单控件共享统一的数据收集、验证和提交流程； +> - 支持文件类字段（file/audio/video）自动识别需使用 `FormData`； +> - 工具栏支持高度定制化扩展。 + +--- + +如需进一步生成 API 文档或导出 JSON Schema 模板，请告知。 \ No newline at end of file diff --git a/docs/ai/recorder.md b/docs/ai/recorder.md new file mode 100644 index 0000000..27fdb58 --- /dev/null +++ b/docs/ai/recorder.md @@ -0,0 +1,110 @@ +```markdown +# SysCamera + +**控件功能**: 用于通过系统摄像头拍摄静态照片，支持实时预览并可在拍照后将图片以 `data URL` 和 `File` 对象形式返回。 +**类型**: 普通控件 +**父类控件**: `bricks.SysVideoRecorder` + +## 初始化参数 + +- 无显式自定义初始化参数（继承自父类 `MediaRecorder`）。 +- 实际使用时需在创建实例时传入 `widgetid` 等可能被父类使用的选项（但本类未直接使用）。 + +## 主要事件 + +- **`shot`** + 触发时机：用户点击录制按钮进行拍照后触发。 + 回调数据： + ```js + { + url: string, // 图片的 data URL，可用于 `` 显示 + file: File // 文件对象，可用于上传或保存 + } + ``` + +--- + +# WidgetRecorder + +**控件功能**: 录制页面中指定 widget（如 `