#字典数据
XinAdmin 提供了完整的字典数据管理功能，支持在前端组件中根据字典编码动态渲染标签、徽章或文本。
#数据结构
#字典类型（sys_dict）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int | 字典ID |
| name | string | 字典名称 |
| code | string | 字典编码（唯一） |
| describe | string | 字典描述 |
| status | int | 状态：0-正常，1-禁用 |
| sort | int | 排序 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
#字典项（sys_dict_item）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int | 字典项ID |
| dict_id | int | 所属字典ID |
| label | string | 字典项标签 |
| value | string | 字典项值 |
| color | string | 颜色值（用于标签显示） |
| status | int | 状态：0-正常，1-禁用 |
| sort | int | 排序 |
#DictTag 组件
DictTag 组件用于根据字典编码和值渲染对应的标签、徽章或文本。
#安装位置
source_code/web/components/DictTag/index.tsx#使用方法
import DictTag from '@/components/DictTag';
// 渲染为 Tag 标签（默认）
<DictTag code="user_status" value={1} />
// 渲染为文本
<DictTag code="user_status" value={1} renderType="text" />
// 渲染为 Badge 徽章
<DictTag code="user_status" value={1} renderType="badge" />
// 自定义默认值
<DictTag code="user_status" value={99} defaultText="未知" defaultColor="gray" />#Props 说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| code | string | 必填 | 字典编码 |
| value | string | number | 必填 | 字典值 |
| renderType | 'text' | 'tag' | 'badge' | 'text' | 渲染样式 |
| defaultText | string | '-' | 当字典值不存在时显示的文本 |
| defaultColor | string | 'default' | 当字典值不存在时显示的颜色 |
#字典状态管理
XinAdmin 使用 Zustand 管理字典数据，提供以下功能：
#初始化字典
import useDictStore from '@/stores/dict';
const { initDict } = useDictStore();
// 在应用启动时调用
await initDict();#获取字典项
import useDictStore from '@/stores/dict';
const getDictItem = useDictStore((state) => state.getDictItem);
// 获取单个字典项
const item = getDictItem('user_status', 1);
// 返回: { label: '正常', value: '1', color: 'green' }#获取选项列表
import useDictStore from '@/stores/dict';
const getOptions = useDictStore((state) => state.getOptions);
// 获取下拉选项
const options = getOptions('user_status');
// 返回: [{ label: '正常', value: '1' }, { label: '禁用', value: '0' }]#API 接口
#获取所有字典
请求
GET /api/admin/system/dict/list/all响应
{
"success": true,
"data": [
{
"id": 1,
"name": "用户状态",
"code": "user_status",
"describe": "用户状态字典",
"status": 0,
"sort": 1,
"dict_items": [
{
"id": 1,
"label": "正常",
"value": "1",
"color": "green",
"sort": 1
},
{
"id": 2,
"label": "禁用",
"value": "0",
"color": "red",
"sort": 2
}
]
}
]
}#字典管理接口
使用 CRUD 注解自动生成以下接口：
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 列表 | GET | /api/admin/system/dict/list | 获取字典列表 |
| 详情 | GET | /api/admin/system/dict/list/{id} | 获取字典详情 |
| 创建 | POST | /api/admin/system/dict/list | 创建字典 |
| 更新 | PUT | /api/admin/system/dict/list/{id} | 更新字典 |
| 删除 | DELETE | /api/admin/system/dict/list/{id} | 删除字典 |
#字典项管理接口
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 列表 | GET | /api/admin/system/dict/item | 获取字典项列表 |
| 详情 | GET | /api/admin/system/dict/item/{id} | 获取字典项详情 |
| 创建 | POST | /api/admin/system/dict/item | 创建字典项 |
| 更新 | PUT | /api/admin/system/dict/item/{id} | 更新字典项 |
| 删除 | DELETE | /api/admin/system/dict/item/{id} | 删除字典项 |
#使用示例
#在表格中使用
import { Table } from 'antd';
import DictTag from '@/components/DictTag';
const columns = [
{
title: '状态',
dataIndex: 'status',
render: (value) => <DictTag code="user_status" value={value} renderType="tag" />
}
];#在下拉框中使用
import { Select } from 'antd';
import useDictStore from '@/stores/dict';
const options = useDictStore((state) => state.getOptions)('user_status');
<Select options={options} />#完整示例
import React from 'react';
import { Card, Table, Tag } from 'antd';
import DictTag from '@/components/DictTag';
import useDictStore from '@/stores/dict';
const UserList: React.FC = () => {
const getOptions = useDictStore((state) => state.getOptions);
const columns = [
{
title: '用户名',
dataIndex: 'username',
},
{
title: '状态',
dataIndex: 'status',
render: (value: number) => (
<DictTag
code="user_status"
value={value}
renderType="tag"
/>
)
},
{
title: '角色',
dataIndex: 'role',
render: (_, record) => (
<>
{record.roles.map((role) => (
<Tag key={role.id}>{role.name}</Tag>
))}
</>
)
}
];
return (
<Card>
<Table columns={columns} dataSource={data} />
</Card>
);
};