API 字典配置

概述

API 字典是一种通过 API 接口动态获取字典数据的配置方式，相比系统字典配置，具有更强的灵活性和实时性。

适用场景

• 📊 数据量大：字典数据超过 100 项，需要分页加载
• 🔄 实时更新：字典数据频繁变更，需要实时获取最新数据
• 🔗 外部集成：字典数据来自第三方系统或其他服务
• 🔍 支持搜索：需要提供搜索功能快速定位字典项
• 🔍 参数传递：支持系统变量和自定义参数

---

一、接口API 开发

1. 数据格式要求

接口返回 JSON 数组，每个字典项包含 text（显示文本）和 value（数据值）：

[
  { "text": "男", "value": "1" },
  { "text": "女", "value": "2" }
]

字段	类型	必填	说明
text	String	✅	前端显示文本
value	String	✅	数据库实际值

---

2. 新版接口（推荐1.7.9+）

版本说明

1.9.2+ 新增 initValue 参数用于初始化默认值对应项的查询。

参数说明

参数名	类型	必填	说明
dictCode	String	✅	字典编码（报表字段名）
pageNo	Integer	❌	当前页码，默认 1
pageSize	Integer	❌	每页条数，默认 10
searchText	String	❌	搜索关键字
queryAll	Boolean	❌	是否查询全部，为 true 时需返回所有数据
initValue	String	❌	初始化默认值（多个用逗号分隔）

重要提示

当 queryAll=true 时，必须返回所有字典数据，否则会影响列表中字典值的翻译显示。

代码示例

/**
 * 返回数据字典
 *
 * @param dictCode   字典值code（是报表动态报表配置明细的字段名称）
 * @param pageNo     当前页数
 * @param pageSize   每页显示条数
 * @param searchText 搜索文本
 * @param queryAll   查询全部，当queryAll为true的时候需要将所有字典值返回，否则会影响列表字典的翻译
 * @param initValue  字典初始化的时候查询的默认值（在报表设计中设置了默认值时才会传递）
 */
@GetMapping("/getDictSex")
public List<Object> getDictSex(@RequestParam(name="dictCode") String dictCode,
                               @RequestParam(name = "pageNo",defaultValue = "1",required = false) Integer pageNo,
                               @RequestParam(name = "pageSize",defaultValue = "10",required = false) Integer pageSize,
                               @RequestParam(name="searchText",required = false) String searchText,
                               @RequestParam(name="queryAll",required = false) Boolean queryAll,
                               @RequestParam(name = "initValue", required = false) String initValue){
        List<Object> list = new ArrayList<>();
        if("sex".equals(dictCode)){
        for (int i = 0; i < 12; i++) {
            Map<String,String> map  = new HashMap<>(5);
            map.put("text","男"+i);
            map.put("value","1"+i);
            list.add(map);
        }
    }
    if("男".equals(searchText)){
        List<Object> list1 = new ArrayList<>();
        Map<String,String> map  = new HashMap<>(5);
        map.put("text","男");
        map.put("value","1");
        list1.add(map);
        return list1;
    }
    if(pageNo >=2){
        return new ArrayList<>();
    }
    return list;
}

---

3. 老版本接口（1.7.8及以下）

版本限制

该版本不支持分页和搜索，建议升级至 1.7.9+。

/**
 * 返回数据字典
 * @param dictCode 字典值code（是报表动态报表配置明细的字段名称）
 */
@GetMapping("/getDictSex")
public List<Map<String, String>> getDictSex(@RequestParam(name = "dictCode") String dictCode) {
    List<Map<String, String>> list = new ArrayList<>();
    if (dictCode.equals("sex")) {
        Map<String, String> map = new HashMap<>();
        map.put("text", "男");
        map.put("value", "1");
        list.add(map);

        Map<String, String> map1 = new HashMap<>();
        map1.put("text", "女");
        map1.put("value", "2");
        list.add(map1);
    }
    return list;
}

---

4. 动态参数传递

支持通过 #{} 语法传递系统变量。

• 语法：?参数名=#{系统变量名}
• 示例：/jmreport/test/getDictSex?createBy=#{sysUserCode}&orgCode=#{sysOrgCode}

常用系统变量详见：系统变量编写规则

---

二、前台使用配置

在 api 数据集或 sql 数据集中：

1. 打开“报表字段明细”或“报表参数”
2. 在“字典 code”中填入 API 地址（支持相对/绝对路径）
3. 勾选“查询”，选择“多选查询”或“单选查询”

注意：

• 外部路径需写 http/https 全路径；不写则按相对路径，系统自动补全 IP 与项目名

示例：

• 相对路径：/jmreport/test/getDictSex?createBy=#{sysUserCode}
• 全路径：http://127.0.0.1:8080/jeecg-boot/jmreport/test/getDictSex?createBy=#{sysUserCode}