275 lines
7.0 KiB
Markdown
275 lines
7.0 KiB
Markdown
# 字典数据联调
|
||
|
||
:::tip 说明
|
||
字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。字典项的 `value` 字段统一为字符串类型，前端使用时需要注意类型转换。
|
||
:::
|
||
|
||
## 后端字典 API
|
||
|
||
### 获取字典数据
|
||
|
||
```
|
||
GET /dict/item/getDictItemList/{code}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": [
|
||
{ "id": 1, "label": "系统", "value": "0" },
|
||
{ "id": 2, "label": "业务", "value": "1" }
|
||
],
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
### 字典数据结构
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | number | 字典项 ID |
|
||
| `label` | string | 显示文本 |
|
||
| `value` | string | 值（注意：统一为字符串） |
|
||
|
||
:::warning 值类型注意
|
||
字典项的 `value` 字段统一为字符串类型，即使存储的是数字。前端使用时需要注意类型转换。
|
||
:::
|
||
|
||
---
|
||
|
||
## 后端字典查询
|
||
|
||
在 Service 层中，可以通过字典 API 查询字典项的显示文本。通常在构建响应数据时，将枚举值转换为对应的中文描述：
|
||
|
||
```python
|
||
from application.dict_item.services import get_dict_item_label
|
||
|
||
def get_example_page(request):
|
||
# ... 分页查询逻辑 ...
|
||
|
||
records = []
|
||
for item in page_list:
|
||
record = {
|
||
'id': item.id,
|
||
'name': item.name,
|
||
'type': item.type,
|
||
# 查询字典项的显示文本
|
||
'typeText': get_dict_item_label('example_type', item.type),
|
||
'status': item.status,
|
||
'statusText': get_dict_item_label('example_status', item.status),
|
||
# ... 其他字段
|
||
}
|
||
records.append(record)
|
||
```
|
||
|
||
### 常用字典编码
|
||
|
||
| 字典编码 | 说明 | 字典项示例 |
|
||
|----------|------|-----------|
|
||
| `param_type` | 参数类型 | 0-系统, 1-业务 |
|
||
| `param_status` | 参数状态 | 1-正常, 2-禁用 |
|
||
| `operation_type` | 操作类型 | 0-其他, 1-新增, 2-修改, 3-删除 |
|
||
| `operation_source` | 操作来源 | 0-后台, 1-前台 |
|
||
| `operation_status` | 操作状态 | 0-正常, 1-异常 |
|
||
| `log_type` | 日志类型 | 1-登录, 2-退出 |
|
||
| `login_source` | 登录来源 | 0-后台, 1-前台 |
|
||
| `login_status` | 登录状态 | 0-成功, 1-失败 |
|
||
|
||
字典编码在后台「字典管理」中配置。
|
||
|
||
---
|
||
|
||
## 前端字典管理
|
||
|
||
### 搜索表单中的字典选项
|
||
|
||
搜索表单中直接硬编码选项（简单场景）或通过 API 获取（动态场景）：
|
||
|
||
**硬编码选项（简单场景）**
|
||
|
||
```typescript
|
||
// src/views/system/param/querySchemas.ts
|
||
export const schemas: FormSchema[] = [
|
||
{
|
||
field: 'type',
|
||
component: 'Select',
|
||
label: '参数类型',
|
||
componentProps: {
|
||
placeholder: '请选择参数类型',
|
||
clearable: true,
|
||
options: [
|
||
{ label: '系统', value: 0 },
|
||
{ label: '业务', value: 1 },
|
||
],
|
||
},
|
||
},
|
||
{
|
||
field: 'status',
|
||
component: 'Select',
|
||
label: '状态',
|
||
componentProps: {
|
||
placeholder: '请选择状态',
|
||
clearable: true,
|
||
options: [
|
||
{ label: '正常', value: 1 },
|
||
{ label: '禁用', value: 2 },
|
||
],
|
||
},
|
||
},
|
||
];
|
||
```
|
||
|
||
**API 获取选项（动态场景）**
|
||
|
||
```typescript
|
||
import { getDictItemByCode } from '@/api/common';
|
||
|
||
const typeOptions = ref([]);
|
||
const statusOptions = ref([]);
|
||
|
||
onMounted(async () => {
|
||
const res1 = await getDictItemByCode('param_type');
|
||
typeOptions.value = res1.data; // [{ label: '系统', value: '0' }, ...]
|
||
|
||
const res2 = await getDictItemByCode('param_status');
|
||
statusOptions.value = res2.data;
|
||
});
|
||
|
||
const schemas: FormSchema[] = [
|
||
{
|
||
field: 'type',
|
||
component: 'Select',
|
||
label: '参数类型',
|
||
componentProps: { options: typeOptions },
|
||
},
|
||
{
|
||
field: 'status',
|
||
component: 'Select',
|
||
label: '状态',
|
||
componentProps: { options: statusOptions },
|
||
},
|
||
];
|
||
```
|
||
|
||
### 前端字典 API
|
||
|
||
按字典编码获取字典项（下拉框用）位于 `src/api/common/index.ts`：
|
||
|
||
```typescript
|
||
// src/api/common/index.ts
|
||
import { http } from '@/utils/http/axios';
|
||
|
||
export function getDictItemByCode(code) {
|
||
return http.request({
|
||
url: '/dict/item/getDictItemList/' + code,
|
||
method: 'GET',
|
||
});
|
||
}
|
||
```
|
||
|
||
后端对应接口：`GET /dict/item/getDictItemList/{code}`（`application/dict_item/views.py`）。
|
||
|
||
---
|
||
|
||
## 前端表格渲染
|
||
|
||
在 `columns.ts` 中使用 `render` 函数渲染状态标签：
|
||
|
||
```typescript
|
||
// src/views/system/param/columns.ts
|
||
{
|
||
label: '参数类型',
|
||
prop: 'type',
|
||
width: 100,
|
||
render(record) {
|
||
return h(ElTag,
|
||
{ type: record.row.type == 0 ? 'primary' : 'warning' },
|
||
{ default: () => record.row.type == 0 ? '系统' : '业务' });
|
||
},
|
||
},
|
||
{
|
||
label: '状态',
|
||
prop: 'status',
|
||
width: 100,
|
||
render(record) {
|
||
return h(ElTag,
|
||
{ type: record.row.status == 1 ? 'success' : 'danger' },
|
||
{ default: () => record.row.status == 1 ? '正常' : '禁用' });
|
||
},
|
||
},
|
||
```
|
||
|
||
---
|
||
|
||
## 值类型处理
|
||
|
||
字典 value 统一为字符串，但业务字段可能为数字，需要注意转换：
|
||
|
||
```typescript
|
||
// 字典选项值为字符串
|
||
const options = [
|
||
{ label: '系统', value: '0' },
|
||
{ label: '业务', value: '1' },
|
||
];
|
||
|
||
// 业务字段为数字
|
||
formData.type = 0;
|
||
|
||
// el-option 绑定时需要转换
|
||
<el-option :value="Number(item.value)" />
|
||
```
|
||
|
||
搜索表单中的 `options` 的 `value` 为字符串 `'0'`/`'1'`，后端筛选字段期望数字。前端 API 传参时自动转换。
|
||
|
||
---
|
||
|
||
## 字典管理
|
||
|
||
### 配置字典
|
||
|
||
在后台「字典管理」中配置字典类型和字典项：
|
||
|
||
```
|
||
字典类型: param_type（参数类型）
|
||
字典项:
|
||
- label: 系统, value: 0
|
||
- label: 业务, value: 1
|
||
|
||
字典类型: param_status（参数状态）
|
||
字典项:
|
||
- label: 正常, value: 1
|
||
- label: 禁用, value: 2
|
||
```
|
||
|
||
### 字典类型命名规范
|
||
|
||
```
|
||
sys_ —— 系统类字典（sys_status, sys_gender 等）
|
||
param_ —— 参数类字典（param_type, param_status 等）
|
||
operation_ —— 操作日志类字典（operation_type, operation_status 等）
|
||
login_ —— 登录日志类字典（log_type, login_source, login_status 等）
|
||
cms_ —— 内容类字典（cms_article_status 等）
|
||
biz_ —— 业务类字典
|
||
```
|
||
|
||
---
|
||
|
||
## 联调流程
|
||
|
||
```
|
||
1. 后台「字典管理」中新增字典类型和字典项
|
||
2. 后端 service 构建响应数据时查询字典项显示文本
|
||
3. 前端 columns.ts 使用 render 函数渲染状态标签
|
||
4. 前端 querySchemas.ts 中配置搜索选项（硬编码或 API 获取）
|
||
5. 表单提交时 value 为字符串，后端存储时注意类型处理
|
||
```
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
字典数据联调通过后端字典 API + 前端 `render` 函数渲染标签实现。后端 Service 层在构建响应时查询字典项的显示文本，前端 columns.ts 使用 render 函数渲染状态标签。字典值统一为字符串，前端使用时注意类型转换。简单场景硬编码选项，动态场景通过 API 获取。
|