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

247 lines
6.3 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.
# 日期时间控件
## 目录
- [日期选择 (datePicker)](#日期选择-datepicker)
- [时间选择 (timePicker)](#时间选择-timepicker)
---
## 日期选择 (datePicker)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `datePicker` |
| AIBridge builder | `build_field_model(..., jnpf_key="datePicker")` |
| 源码示例 | `extend/formDemo/fieldForm1/index.vue` |
| workSystem 示例 | 几乎所有业务表单 |
### 基本规则
1. **必填配置**:
- `field_name`: 字段中文名称
- `field_vmodel`: 字段 vModel
- `jnpf_key`: `"datePicker"`
2. **特有配置**:
- `format`: 显示格式 (默认 `"yyyy-MM-dd"`)
- `valueFormat`: 值格式 (默认 `"yyyy-MM-dd"`)
### AIBridge 使用
```python
# 基础日期选择
field = build_field_model(
field_name="出生日期",
field_vmodel="f_birth_date",
jnpf_key="datePicker",
required=True
)
# 自定义格式 (如需显示年月日)
field = build_field_model(
field_name="入职日期",
field_vmodel="f_entry_date",
jnpf_key="datePicker",
format="yyyy-MM-dd",
valueFormat="yyyy-MM-dd"
)
```
### workSystem 示例
| 表单名称 | 表单ID | 用途 |
|----------|--------|------|
| 员工培训 | 624164673918337925 | 培训日期 |
| 入职申请 | 624163990351643525 | 入职日期 |
| 劳动合同续签 | 623425065425305605 | 合同日期 |
| 离职交接表 | 623417538411233285 | 离职日期 |
| 离职员工表 | 623183958128984261 | 离职日期 |
| 离职申请 | 623163301152424133 | 申请日期 |
| 列表行内编辑 | 585824111083652229 | 日期编辑 |
| 多语言采购申请 | 585448937427567365 | 采购日期 |
| 采购申请 | 585441013829468933 | 申请日期 |
| 物资申请 | 585436888639210245 | 申请日期 |
| 代码对比 | 585436444760212229 | 日期字段 |
| 付款申请 | 585398402720727621 | 付款日期 |
| 套打示例 | 585384793399624261 | 制单日期 |
| 水电费用 | 585110234985398597 | 费用日期 |
| 报价信息 | 585107422926864709 | 报价日期 |
| 个人信息 | 585101489710563653 | 生日 |
| 采购合同 | 585077579715707205 | 签订日期 |
| 订单示例 | 469133201755925637 | 订单日期 |
| 预算管理 | 469100392253286789 | 预算期间 |
| 出差管理 | 469066996185622917 | 出差日期 |
| 事件管理 | 469065268790880645 | 发生日期 |
| 设备巡检管理 | 469062048563652997 | 巡检日期 |
| 核酸检测 | 469038006062344581 | 检测日期 |
| 药房管理 | 468849844170057541 | 日期字段 |
| 报名管理外链 | 468848215723140933 | 报名日期 |
| 大客户信息 | 468842471892247429 | 签约日期 |
### 常见问题
| 问题 | 原因 | 解决 |
|------|------|------|
| 保存后显示时间戳 | valueFormat 不对 | 确认 `valueFormat: "yyyy-MM-dd"` |
| 日期显示 NaN | format 不匹配 | 确认 `format: "yyyy-MM-dd"` |
---
## 时间选择 (timePicker)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `timePicker` |
| AIBridge builder | `build_field_model(..., jnpf_key="timePicker")` |
### 基本规则
1. **特有配置**:
- `format`: 显示格式 (默认 `"HH:mm:ss"`)
- `valueFormat`: 值格式 (默认 `"HH:mm:ss"`)
### AIBridge 使用
```python
# 时间选择
field = build_field_model(
field_name="上班时间",
field_vmodel="f_work_start_time",
jnpf_key="timePicker"
)
# 范围时间 (需两个字段)
start_time = build_field_model(
field_name="开始时间",
field_vmodel="f_start_time",
jnpf_key="timePicker"
)
end_time = build_field_model(
field_name="结束时间",
field_vmodel="f_end_time",
jnpf_key="timePicker"
)
```
---
## 日期相关高级控件
### 移动端特有
| 控件 | jnpfKey | 说明 |
|------|---------|------|
| DateRange | dateRange | 日期范围选择 |
| TimeRange | timeRange | 时间范围选择 |
| NumberRange | numberRange | 数字范围 |
### 计算类
| 控件 | jnpfKey | 说明 | workSystem 示例 |
|------|---------|------|-----------------|
| DateCalculate | dateCalculate | 日期计算 | - |
| Calculate | calculate | 通用计算 | 水电费用 (#25), 采购合同 (#28) |
---
## 通用配置说明
### format 和 valueFormat
```python
# 常见格式组合
# 1. 标准日期 (最常用)
field = build_field_model(
field_name="日期",
field_vmodel="f_date",
jnpf_key="datePicker",
format="yyyy-MM-dd",
valueFormat="yyyy-MM-dd"
)
# 2. 仅时间
field = build_field_model(
field_name="时间",
field_vmodel="f_time",
jnpf_key="timePicker",
format="HH:mm:ss",
valueFormat="HH:mm:ss"
)
```
### format 格式字符串
| 格式 | 说明 | 示例 |
|------|------|------|
| yyyy | 4位年份 | 2024 |
| MM | 2位月份 | 01-12 |
| dd | 2位日期 | 01-31 |
| HH | 24小时 | 00-23 |
| mm | 分钟 | 00-59 |
| ss | 秒 | 00-59 |
### valueFormat 选项
| 值 | 说明 |
|-----|------|
| `yyyy-MM-dd` | 日期字符串 (默认) |
| `yyyy-MM-dd HH:mm:ss` | 完整时间字符串 |
| `timestamp` | 毫秒时间戳 |
---
## 数据存储规律
### 日期时间控件存储规律
| 控件 | jnpfKey | 存储类型 | 存储格式示例 | 说明 |
|------|---------|---------|------------|------|
| 日期选择 | `datePicker` | **字符串** | `"2026-04-07"` | 取决于 valueFormat 配置 |
| 时间选择 | `timePicker` | **字符串** | `"14:30:00"` | 固定字符串格式 |
### valueFormat 配置说明
| valueFormat | 存储示例 | 说明 |
|-------------|---------|------|
| `yyyy-MM-dd` | `"2026-04-07"` | 日期字符串 (默认) |
| `yyyy-MM-dd HH:mm:ss` | `"2026-04-07 14:30:00"` | 完整时间字符串 |
| `timestamp` | `1744051200000` | 毫秒时间戳(13位) |
### format vs valueFormat
- **format**: 控制前端显示格式(用户看到的)
- **valueFormat**: 控制数据存储格式(提交到数据库的)
```python
# 显示日期,存储日期字符串
field = build_field_model(
field_name="日期",
field_vmodel="f_date",
jnpf_key="datePicker",
format="yyyy-MM-dd",
valueFormat="yyyy-MM-dd"
)
```
### 数据库字段要求
| 控件 | 建议字段类型 | 说明 |
|------|------------|------|
| datePicker | `varchar(20)` | 如 "2026-04-07" |
| datePicker (时间戳) | `bigint` | 毫秒时间戳 |
| timePicker | `varchar(10)` | 如 "14:30:00" |
---
## 下一步
- [上传控件](05-upload-controls.md)
- [弹窗控件](06-popup-controls.md)
- [子表格控件](07-table-controls.md)