跳到主要内容

数据字典配置

概述​

数据字典是报表系统中的核心功能之一，用于将数据库或 API 的原始字段值转换为用户友好的可读文本。

应用场景​

  • 枚举值转换：将性别字段 1、2 转换为"男"、"女"
  • 状态码转换：将订单状态 0、1、2 转换为"待支付"、"已支付"、"已发货"
  • 类型映射：将用户类型 admin、user、guest 转换为"管理员"、"普通用户"、"访客"
  • 多值翻译：支持一个字段包含多个值的分隔符转换

核心优势​

✅ 简化维护：集中管理字典数据，避免硬编码
✅ 提升可读性：让报表数据更直观易懂
✅ 支持集成：可与 JeecgBoot 系统字典无缝对接
✅ 灵活配置：支持系统字典、API 字典、SQL 字典等多种方式

一、报表字典配置​

系统字典是最常用的配置方式，通过可视化界面管理字典数据，无需编码即可完成配置。

1. 进入数据字典管理​

在报表设计页面，点击顶部工具栏的「添加数据字典」按钮，进入数据字典管理界面。

数据字典入口

图11.11 数据字典入口

数据字典管理页面

图11.12 数据字典管理页面

2. 新建字典​

点击「添加」按钮，填写字典基本信息：

字段说明示例
字典名称字典的显示名称，支持中英文、数字性别字典、订单状态
字典编码字典的唯一标识，建议使用英文或拼音sex、order_status
描述字典的用途说明（可选）用于性别字段的数据转换
命名建议
  • 字典编码建议使用小写英文或下划线命名，如：user_type、gender
  • 名称应简洁明了，便于后期维护和团队协作
添加字典基本信息

图11.21 添加字典基本信息

3. 配置字典项​

选中已创建的字典，点击「添加」按钮，配置具体的字典项数据：

字段说明示例
名称前端显示的文本男、女
数据值数据库或 API 中的实际值1、2
描述字典项说明（可选）男性
是否启用控制该字典项是否生效✅ 启用
配置示例

场景：数据库中性别字段存储值为 1、2，需要在前端显示为"男"、"女"

配置方法：

  • 字典项 1：名称=男，数据值=1
  • 字典项 2：名称=女，数据值=2

完成后效果：报表中值为 1 的数据会自动显示为"男"，值为 2 显示为"女"

字典项配置完成

4. 在报表中使用字典​

配置完成后，在报表设计页面使用字典非常简单：

  1. 选中需要应用字典的单元格
  2. 在字段属性找到「字典 code」配置项
  3. 填写对应的字典编码即可（如：sex）

使用字典

图11.51 在报表中使用字典

使用说明
  • 字典应用后，单元格中的原始值会自动转换为字典配置的显示文本
  • 支持数据集字段和参数字段使用字典
  • 如果找不到对应的字典项，会显示原始值

二、API 字典​

API 字典允许通过接口动态获取字典数据，适用于字典数据频繁变更或需要从外部系统获取的场景。

详见：API 字典专题文档

适用场景：

  • 字典数据量大，需要动态加载
  • 字典数据来自第三方系统
  • 字典数据需要实时更新

三、SQL 表字典​

最简用法：直接使用一条 SQL 作为字典数据源，返回两列固定别名：

  • value：数据值
  • text：显示文本

使用步骤：

  1. 在字段属性的「字典 code」中直接填写 SQL；
  2. 确保查询结果列名（或别名）为 value、text。

示例：

SELECT item_value AS value, item_text AS text FROM sys_dict_item

效果：单元格会按 value -> text 自动映射显示。

报表设计界面配置示例

报表预览效果示例

四、数据库多值分隔符配置​

版本要求

1.5.1（2022.07.05）及以上版本支持

功能说明​

当数据库字段存储多个值（如：1,2,3），并且需要将这些值全部转换为对应的字典文本时（如：男,女,未知），可以使用多值分隔符配置。

效果展示​

配置前后对比：

配置前配置后
1,2,3男,女,未知

多值分隔效果

图11.61 多值分隔符转换效果

配置步骤​

版本差异

1.9.6+ 版本：参数配置已改为可视化界面，详情请参考 可视化参数配置

步骤 1：在参数配置中添加 dictSplit 属性

填写属性名称 dictSplit，值为数据库中使用的分隔符，例如：

{
  "dictSplit": ","
}

参数配置

图11.62 参数配置示例

分隔符说明
  • 参数中的 , 代表数据库存放的数据分隔符
  • 根据实际情况，可以配置为其他分隔符，如 ;、|、- 等
  • 分隔符必须与数据库中存储的分隔符完全一致

步骤 2：数据库数据示例

假设数据库中存储的数据如下：

数据库数据

图11.63 数据库数据示例

步骤 3：应用字典

在报表单元格中配置对应的字典 code，系统会自动按分隔符将多个值逐一转换。

五、JeecgBoot 系统字典对接​

v2.3.1+ 支持此功能。

  • 可直接使用 JeecgBoot 系统字典，避免重复维护；
  • 在字段属性的「字典 code」中填写 JeecgBoot 字典编码即可使用；
  • 如果积木报表中维护的字典code 与 JeecgBoot 系统字典code不一致，则以积木报表中维护的字典code 优先级更高。

具体实现代码示例：

  • 实现JmReportTokenServiceI接口中的getDictItems方法
@Slf4j
@Component
public class JimuReportTokenService implements JmReportTokenServiceI {
    
    @Override
    public List<JmDictModel> getDictItems(String dictCode) {
        List<JmDictModel> dictItems  = new ArrayList<>();
        if(oConvertUtils.isNotEmpty(dictCode)){
            List<DictModel> dictItemsList = sysBaseApi.getDictItems(dictCode);
            dictItemsList.forEach(dictItem->{
                JmDictModel dictModel = new JmDictModel();
                dictModel.setText(dictItem.getText());
                dictModel.setValue(dictItem.getValue());
                dictModel.setDictCode(dictCode);
                dictItems.add(dictModel);
            });
        }
        return dictItems;
    }
}