Files
aibridge/docs/control/02-input-controls.md
2026-05-18 09:28:15 +08:00

297 lines
7.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 输入类控件
## 目录
- [单行文本 (input)](#单行文本-input)
- [多行文本 (textarea)](#多行文本-textarea)
- [数字输入 (inputNumber)](#数字输入-inputnumber)
---
## 单行文本 (input)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `input` |
| AIBridge builder | `build_field_model(..., jnpf_key="input")` |
| 源码示例 | `extend/formDemo/fieldForm1/index.vue` |
| workSystem 示例 | 几乎所有表单 |
### 基本规则
1. **必填配置**:
- `field_name`: 字段中文名称 (显示在表单标签)
- `field_vmodel`: 字段 vModel 值 (对应数据库字段)
- `jnpf_key`: 必须为 `"input"`
2. **常用配置**:
- `required`: 是否必填 (默认 False)
- `placeholder`: 占位提示文本
- `showPassword`: 是否显示密码格式 (默认 False)
- `prefixIcon`: 输入框前缀图标
- `suffixIcon`: 输入框后缀图标
### AIBridge 使用
```python
from aibridge.builders.field_model import build_field_model
# 基础文本输入
field = build_field_model(
field_name="客户名称",
field_vmodel="f_customer_name",
jnpf_key="input",
required=True
)
# 密码输入
password_field = build_field_model(
field_name="登录密码",
field_vmodel="f_password",
jnpf_key="input",
showPassword=True
)
# 带前缀图标
field_with_icon = build_field_model(
field_name="手机号码",
field_vmodel="f_mobile",
jnpf_key="input",
prefixIcon="mobile"
)
```
### workSystem 示例
| 表单名称 | 表单ID | 用途说明 |
|----------|--------|----------|
| 信贷信息 | 797473600809468485 | 基本信息输入 |
| 员工培训 | 624164673918337925 | 多字段表单 |
| 产品管理 | 469039386000943493 | 产品名称、编码输入 |
### 常见错误
| 错误现象 | 原因 | 解决 |
|----------|------|------|
| 输入内容不保存 | vModel 与数据库字段不匹配 | 确保 `field_vmodel` 与表字段名一致 (大写 F_ 前缀) |
| 必填校验不生效 | required 未设置为 True | `build_field_model(..., required=True)` |
| placeholder 不显示 | 平台自动生成 | 如需自定义,可通过 `__config__.placeholder` 设置 |
---
## 多行文本 (textarea)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `textarea` |
| AIBridge builder | `build_field_model(..., jnpf_key="textarea")` |
| 源码示例 | `extend/formDemo/fieldForm1/index.vue` |
| workSystem 示例 | 员工培训、离职申请、采购申请 等 |
### 基本规则
1. **必填配置**:同 input
2. **特有配置**:
- `rows`: 显示行数 (默认 4)
- `maxlength`: 最大输入字符数 (默认无限制)
### AIBridge 使用
```python
# 基础多行文本
field = build_field_model(
field_name="备注说明",
field_vmodel="f_remark",
jnpf_key="textarea",
required=False
)
# 指定行数和最大长度
field = build_field_model(
field_name="详细描述",
field_vmodel="f_description",
jnpf_key="textarea",
rows=6,
maxlength=500
)
```
### workSystem 示例
| 表单名称 | 表单ID | 配置 |
|----------|--------|------|
| 员工培训 | 624164673918337925 | textarea, required |
| 离职申请 | 623163301152424133 | textarea |
| 离职交接表 | 623417538411233285 | textarea, 较长内容 |
| 产品管理 | 469039386000943493 | 产品描述 |
---
## 数字输入 (inputNumber)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `inputNumber` / `numInput` |
| AIBridge builder | `build_field_model(..., jnpf_key="inputNumber")` |
| 源码示例 | `extend/formDemo/fieldForm1/index.vue` |
| workSystem 示例 | 信贷信息、油耗计算、订单明细 等 |
### 基本规则
1. **必填配置**:同 input
2. **特有配置**:
- `step`: 步进值 (默认 1)
- `controls`: 是否显示增减按钮 (默认 True)
- `min`: 最小值 (默认无限制)
- `max`: 最大值 (默认无限制)
### AIBridge 使用
```python
# 基础数字输入
field = build_field_model(
field_name="年龄",
field_vmodel="f_age",
jnpf_key="inputNumber",
required=True
)
# 带步进和范围
field = build_field_model(
field_name="折扣比例",
field_vmodel="f_discount_rate",
jnpf_key="inputNumber",
min=0,
max=100,
step=5
)
# 不显示增减按钮
field = build_field_model(
field_name="精确数量",
field_vmodel="f_quantity",
jnpf_key="inputNumber",
controls=False
)
```
### workSystem 示例
| 表单名称 | 表单ID | 配置 |
|----------|--------|------|
| 信贷信息 | 797473600809468485 | 贷款金额 |
| 油耗计算 | 797460178185224773 | 油耗数量计算 |
| 报价信息 | 585107422926864709 | 价格输入 |
| 订单示例 | 469133201755925637 | 订单数量、单价 |
### 金额输入特殊处理
金额类字段通常需要:
1. 设置 `step=0.01` 或 `step=1`
2. 设置适当的 `min` (通常为 0)
3. 可配合 `addonAfter` 显示单位 (如 "元")
```python
# 金额输入示例 (addonAfter 需要额外配置 __config__)
field = build_field_model(
field_name="订单金额",
field_vmodel="f_order_amount",
jnpf_key="inputNumber",
min=0,
step=0.01
)
```
---
## 输入类控件通用配置
### AIBridge build_field_model 完整参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| field_name | str | 必填 | 字段中文名称 |
| field_vmodel | str | 必填 | 字段 vModel (对应数据库) |
| jnpf_key | str | "input" | 控件类型 |
| required | bool | False | 是否必填 |
| table_name | str | "base_table" | 表名 |
| render_key | int | 0 | 渲染 key |
| options | list | None | 下拉选项 (select/radio/checkbox 用) |
| dictionary_type | str | "" | 数据字典类型 |
### 输出结构
```json
{
"__config__": {
"jnpfKey": "input",
"label": "客户名称",
"showLabel": true,
"required": true,
"tableName": "ord_customer",
"renderKey": 0,
"tag": "JnpfInput",
"tagIcon": "icon-ym icon-ym-generator-input",
"layout": "colFormItem"
},
"placeholder": "请输入客户名称",
"readonly": false,
"disabled": false,
"clearable": true,
"showPassword": false,
"style": { "width": "100%" }
}
```
---
## 数据存储规律
### 输入类控件存储规律
| 控件 | jnpfKey | 存储类型 | 示例 |
|------|---------|---------|------|
| 单行文本 | `input` | **字符串** | `"测试文本ABC123"` |
| 多行文本 | `textarea` | **字符串**(含换行符) | `"第一行\n第二行\n第三行"` |
| 数字输入 | `inputNumber` | **数值或字符串**(取决于 precision 配置) | `12345.67` 或 `"12345.67"` |
### 实际测试结果
通过 AIBridge API 实际测试结果:
```python
# 单行文本
test_value = "测试文本ABC123"
stored_value = "测试文本ABC123" # str = str
# 多行文本
test_value = "第一行\n第二行\n第三行"
stored_value = "第一行\n第二行\n第三行" # str = str(含换行)
# 数字输入
test_value = 12345.67
stored_value = "12345.67" # float -> str
```
### 数据库字段要求
| 控件 | 建议字段类型 |
|------|------------|
| input | `varchar(500)` 或 `text` |
| textarea | `text` |
| inputNumber | `decimal(18,2)` 或 `varchar(50)` |
---
## 下一步
- [选择类控件](03-select-controls.md)
- [日期时间控件](04-date-controls.md)
- [上传控件](05-upload-controls.md)