【JEECG Boot】 《JEECG Boot 数据字典使用教程》（完整版）

文章目录

• [JEECG Boot 数据字典使用步骤（完整版）](#JEECG Boot 数据字典使用步骤（完整版）)
• • 一、第一步：后台创建字典（可视化配置）
  • • [1. 进入字典管理](#1. 进入字典管理)
    • [2. 新增字典（主数据）](#2. 新增字典（主数据）)
    • [3. 新增字典项（明细数据）](#3. 新增字典项（明细数据）)
  • [二、第二步：后端实体使用 @Dict 自动翻译](#二、第二步：后端实体使用 @Dict 自动翻译)
  • • [1. 在实体类字段上加注解](#1. 在实体类字段上加注解)
    • [2. 效果](#2. 效果)
  • [三、第三步：前端表单使用 JDictSelectTag 组件](#三、第三步：前端表单使用 JDictSelectTag 组件)
  • • [1. 基础用法（下拉框）](#1. 基础用法（下拉框）)
    • [2. 单选按钮](#2. 单选按钮)
    • [3. 按钮风格单选](#3. 按钮风格单选)
    • [4. 数值类型回显异常加：stringToNumber](#4. 数值类型回显异常加：stringToNumber)
  • 四、第四步：表格列显示字典文本（不用翻译接口）
  • • [方法 1：后端自动翻译（最简单）](#方法 1：后端自动翻译（最简单）)
    • [方法 2：前端手动翻译（灵活）](#方法 2：前端手动翻译（灵活）)
  • 五、第五步：使用表字典（动态从业务表取数据）
  • • 后端
    • 前端
    • 带过滤条件
  • 六、第六步：字典修改后刷新缓存
  • 七、第七步：表单提交校验（防止非法值）
• [最常用的 4 种场景速查（直接复制）](#最常用的 4 种场景速查（直接复制）)
• • [1. 普通字典（最常用）](#1. 普通字典（最常用）)
  • [2. 表字典（用户/部门/分类）](#2. 表字典（用户/部门/分类）)
  • [3. 表格翻译](#3. 表格翻译)
  • [4. 数值回显失败修复](#4. 数值回显失败修复)
• [常见问题 1 分钟解决](#常见问题 1 分钟解决)
• • • [1. @Dict 翻译不生效？](#1. @Dict 翻译不生效？)
    • [2. JDictSelectTag 下拉不显示数据？](#2. JDictSelectTag 下拉不显示数据？)
    • [3. 编辑页面回显不生效？](#3. 编辑页面回显不生效？)
    • [4. 表字典报SQL注入错误？](#4. 表字典报SQL注入错误？)
  • 总结（最核心的3句话）

---

JEECG Boot 数据字典使用步骤（完整版）

本文是最实用、一步一操作、直接照着就能用的 《JEECG Boot 数据字典使用教程》，从后台配置 → 后端翻译 → 前端渲染 → 常见问题，一篇全部讲清楚。

---

一、第一步：后台创建字典（可视化配置）

1. 进入字典管理

系统管理 → 字典管理

2. 新增字典（主数据）

点击【新增】，填写：

• 字典名称：性别
• 字典编码：sex（必须唯一，代码里会用）
• 描述：用户性别

3. 新增字典项（明细数据）

点击字典右侧【字典配置】，添加选项：

• 文本：男，值：1
• 文本：女，值：2
• 文本：未知，值：0

保存后，字典就创建完成了。

---

二、第二步：后端实体使用 @Dict 自动翻译

1. 在实体类字段上加注解

/**
 * 性别
 */
@Dict(dicCode = "sex")
private Integer sex;

2. 效果

接口返回数据时，自动生成 sex_dictText 字段

例如：

• sex = 1 → sex_dictText = "男"
• sex = 2 → sex_dictText = "女"

不需要写任何翻译逻辑！

---

三、第三步：前端表单使用 JDictSelectTag 组件

这是 JEECG 最常用、最标准的字典下拉组件。

1. 基础用法（下拉框）

<JDictSelectTag
  v-model:value="form.sex"
  dictCode="sex"
  placeholder="请选择性别"
/>

2. 单选按钮

<JDictSelectTag
  v-model:value="form.sex"
  dictCode="sex"
  type="radio"
/>

3. 按钮风格单选

<JDictSelectTag
  v-model:value="form.sex"
  dictCode="sex"
  type="radioButton"
/>

4. 数值类型回显异常加：stringToNumber

<JDictSelectTag
  v-model:value="form.sex"
  dictCode="sex"
  :stringToNumber="true"
/>

---

四、第四步：表格列显示字典文本（不用翻译接口）

方法 1：后端自动翻译（最简单）

接口返回自带 sex_dictText，表格直接绑定：

{
  title: "性别",
  dataIndex: "sex_dictText",
  key: "sex_dictText"
}

方法 2：前端手动翻译（灵活）

<template>
  <a-table :columns="columns" :data-source="tableList" />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { initDictOptions, filterDictText } from '@/components/dict/JDictSelectUtil';

const sexOptions = ref([]);

// 加载字典
onMounted(async () => {
  let res = await initDictOptions('sex');
  sexOptions.value = res.result || [];
});

const columns = [
  {
    title: '性别',
    dataIndex: 'sex',
    customRender: ({ text }) => filterDictText(sexOptions.value, text)
  }
];
</script>

---

五、第五步：使用表字典（动态从业务表取数据）

不需要在字典管理配置，直接关联表：

后端

@Dict(dictTable = "sys_user", dicText = "realname", dicCode = "id")
private String userId;

前端

<JDictSelectTag
  v-model:value="form.userId"
  dictCode="sys_user,realname,id"
/>

带过滤条件

<JDictSelectTag
  v-model:value="form.userId"
  dictCode="sys_user,realname,id,sex=1"
/>

---

六、第六步：字典修改后刷新缓存

字典修改后必须刷新缓存才会生效：

1. 字典管理页面 → 右上角【刷新缓存】
2. 或前端页面按 Ctrl + Shift + 刷新缓存
3. 后端会自动清空 Redis 缓存

---

七、第七步：表单提交校验（防止非法值）

@DictVerify(dictCode = "sex", message = "性别格式不正确")
private Integer sex;

---

最常用的 4 种场景速查（直接复制）

1. 普通字典（最常用）

@Dict(dicCode="sex")
private Integer sex;

<JDictSelectTag v-model:value="form.sex" dictCode="sex" />

2. 表字典（用户/部门/分类）

dictCode="sys_user,realname,id"

3. 表格翻译

customRender: ({ text }) => filterDictText(sexOptions.value, text)

4. 数值回显失败修复

:stringToNumber="true"

---

常见问题 1 分钟解决

1. @Dict 翻译不生效？

• 实体必须加 getter/setter（或 @Data）
• 返回类型必须是 Result<?>、List、IPage
• 字典编码写错
• 没刷新缓存

2. JDictSelectTag 下拉不显示数据？

• dictCode 错误
• 字典项被禁用
• 网络请求404（没登录/权限不足）

3. 编辑页面回显不生效？

加 :stringToNumber="true"

4. 表字典报SQL注入错误？

• 只允许简单条件：sex=1
• 不能写复杂SQL
• 表名必须在白名单

---

总结（最核心的3句话）

1. 后台配置字典 → 得到字典编码
2. 实体加 @Dict → 接口自动翻译出 xxx_dictText
3. 前端用 JDictSelectTag → 一行代码渲染下拉/单选