# `bricks.MiniForm` 技术文档

> **MiniForm** 是一个基于 `bricks.HBox` 的轻量级表单组件，用于动态切换和输入不同字段的数据。它支持通过下拉选择器快速切换输入项，并实时触发输入事件。

---

## 概述

`bricks.MiniForm` 类继承自 `bricks.HBox`，提供了一个紧凑的表单界面，适用于需要在多个输入字段之间快速切换的场景（如搜索框、参数配置等）。该组件包含：

- 一个下拉选择器（用于选择当前字段）
- 一个动态输入控件（根据所选字段类型自动创建）
- 支持自定义字段属性和默认值
- 可扩展的输入事件机制

---

## 继承关系

```
bricks.HBox
    └── bricks.MiniForm
```

---

## 构造函数

```js
new bricks.MiniForm(options)
```

### 参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| `options` | Object | ✅ | 配置对象，结构如下 |

#### `options` 结构

| 属性 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `defaultname` | String | ❌ | 第一个字段的 `name` | 默认激活的字段名称 |
| `label_width` | String/Number | ❌ | - | 标签列宽度（可被字段级覆盖） |
| `input_width` | String/Number | ❌ | - | 输入框宽度（可被字段级覆盖） |
| `params` | Object | ❌ | `{}` | 固定附加参数，在 `getValue()` 中返回 |
| `fields` | Array<Object> | ✅ | - | 字段定义数组，每个字段包含以下子属性 |

##### `fields[i]` 字段定义

| 属性 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `name` | String | ✅ | 字段唯一标识符（如：`"username"`） |
| `label` | String | ✅ | 显示名称（出现在下拉列表中） |
| `icon` | String | ❌ | 图标类名（可选，用于视觉增强） |
| `uitype` | String | ✅ | 控件类型（如 `"text"`, `"number"`, `"code"` 等），需与 `Input.factory` 兼容 |
| `uiparams` | Object | ❌ | 传递给具体输入控件的额外配置参数 |

---

## 示例配置

```js
var miniForm = new bricks.MiniForm({
    defaultname: 'email',
    params: { action: 'search' },
    fields: [
        {
            name: 'username',
            label: '用户名',
            uitype: 'text',
            uiparams: { placeholder: '请输入用户名' }
        },
        {
            name: 'email',
            label: '邮箱',
            uitype: 'text',
            uiparams: { type: 'email', placeholder: '请输入邮箱' }
        },
        {
            name: 'count',
            label: '数量',
            uitype: 'number',
            uiparams: { min: 1, max: 100 }
        }
    ]
});
```

---

## 方法说明

### `constructor(opts)`

初始化 MiniForm 实例并调用 `build()`。

#### 行为：
- 设置容器宽高为 `'auto'`
- 调用父类构造函数
- 执行 `build()` 构建 UI

---

### `build()`

构建整个组件的 UI，包括选项选择器和初始输入控件。

#### 步骤：
1. 确定默认字段名（优先使用 `defaultname`，否则取第一个字段）
2. 调用 `build_options()` 创建下拉选择器
3. 调用 `build_widgets(name)` 初始化对应输入控件

---

### `build_options()`

创建一个下拉选择控件（`this.choose`），允许用户切换当前编辑的字段。

#### 使用 `Input.factory` 创建的选择器配置：
```js
{
    width: "90px",
    name: "name",
    uiType: "code", // 假设为下拉或代码选择器
    valueField: 'name',   // 绑定值为字段的 name
    textField: 'label',   // 显示文本为 label
    data: this.opts.fields
}
```

> ⚠️ 注：`uiType: "code"` 可能表示一种特殊下拉控件，实际应确保其行为符合预期（例如 ComboBox 或 Select）。

绑定事件：`changed` → `change_input(e)`

---

### `build_widgets(name)`

根据指定字段名动态创建对应的输入控件。

#### 参数：
- `name`: 字段名（必须存在于 `fields` 中）

#### 流程：
1. 若已有输入控件，则解绑 `input` 事件
2. 清空当前所有控件
3. 添加选择器控件 `this.choose`
4. 查找匹配字段定义 `f`
5. 复制字段描述并设置 `width: 'auto'`
6. 使用 `Input.factory(desc)` 创建输入控件 `i`
7. 绑定 `input` 事件到 `input_handle`
8. 将新控件加入布局
9. 保存引用至 `this.input`

---

### `change_input(e)`

当下拉选择器值改变时触发，重新构建输入控件。

#### 行为：
- 获取当前选择的字段名 `this.choose.value`
- 调用 `build_widgets(name)` 切换输入控件

---

### `input_handle(e)`

当输入内容发生变化时触发，用于广播事件。

#### 行为：
1. 调用 `getValue()` 获取完整数据
2. 输出调试信息（通过 `bricks.debug`）
3. 触发 `input` 事件，携带数据 `d`

```js
this.dispatch('input', d);
```

> 可通过 `.bind('input', handler)` 监听此事件

---

### `getValue() → Object`

获取当前表单的合并值。

#### 返回值结构：
```js
{
    // 来自 this.opts.params 的固定参数
    action: 'search',
    // 来自当前输入控件的动态值
    username: 'john_doe'
}
```

#### 逻辑：
- 初始化为 `params` 对象（若未设置则为空 `{}`）
- 合并当前输入控件的值（`this.input.getValue()`）
- 使用 `bricks.extend(d, v)` 进行浅合并

---

### `show_options(e)`

显示下拉选择器（调试用途或外部调用）。

#### 行为：
- 输出调试日志
- 调用 `this.choose.show()` 显示选择器

> 主要用于开发调试或定制交互逻辑

---

### `clear_widgets()`

> 📌 注意：此方法未在代码中定义，但被调用。

假设其来自父类 `HBox`，功能为清空所有子控件。

---

## 事件系统

### 支持监听的事件

| 事件名 | 触发时机 | 携带数据 |
|--------|----------|---------|
| `input` | 输入值变化时 | 合并后的表单数据对象 |

#### 示例监听：

```js
miniForm.bind('input', function(data) {
    console.log('Current form data:', data);
    // { action: 'search', username: 'testuser' }
});
```

---

## 工厂注册

```js
bricks.Factory.register('MiniForm', bricks.MiniForm);
```

允许通过工厂模式创建实例：

```js
var form = bricks.Factory.create('MiniForm', options);
```

---

## 设计特点

| 特性 | 说明 |
|------|------|
| ✅ 动态输入切换 | 支持运行时更换输入控件类型 |
| ✅ 模块化结构 | 基于 `Input.factory` 实现控件解耦 |
| ✅ 可扩展性 | 支持任意 `uitype` 和 `uiparams` |
| ✅ 事件驱动 | 提供标准 `input` 事件接口 |
| ⚠️ 宽度控制有限 | 当前 `label_width` / `input_width` 未完全实现（可能依赖样式或其他机制） |

---

## 注意事项

1. **`Input.factory` 依赖**  
   必须确保 `Input.factory` 支持所有声明的 `uitype` 类型。

2. **`objcopy()` 函数**  
   代码中使用了 `objcopy(f)`，应确保全局存在此工具函数（通常为对象深拷贝或浅拷贝）。

3. **`bricks.extend`**  
   用于合并对象，类似 jQuery 的 `$.extend` 或 Lodash 的 `_.assign`。

4. **UI 渲染顺序**  
   每次切换字段都会重建输入控件，适合字段较少的场景；高频切换可能影响性能。

5. **样式兼容性**  
   推荐配合 CSS 设置 `.bricks-miniform` 或相关类以优化布局。

---

## 调试支持

启用调试模式后，会输出以下信息：

- `show_options()` 调用记录
- `input_handle()` 中的实时数据

可通过 `bricks.debug = console.log` 启用。

---

## 总结

`bricks.MiniForm` 是一个简洁高效的动态表单组件，特别适用于：

- 多条件搜索栏
- 快捷参数输入
- 动态配置面板

结合 `bricks` 框架的输入控件体系，能够快速搭建灵活的用户界面。

--- 

✅ **推荐使用场景**：工具条、查询过滤器、快捷操作面板  
🔧 **可优化方向**：缓存输入控件实例、支持更多布局配置、增加验证机制