116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
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`；
|
||
> - 工具栏支持高度定制化扩展。
|
||
|