若依框架
前端手册

使用字典功能

# 使用字典功能的详细总结

在若依框架中，“字典”模块主要用于管理系统中的数据字典。数据字典是指一组具有特定分类和编码的键值对集合，通常用于在系统中表示一些常用的、可枚举的值。比如性别、状态、分类等信息。字典表为这些信息提供了一个统一的管理和维护的地方，可以方便地进行数据的修改和扩展。

字典模块的作用

统一管理常用数据：字典模块将系统中常用的枚举数据集中管理，使得这些数据的维护变得更加简单和直观。比如，在多个地方使用到的性别、状态等数据，可以通过字典表统一管理，避免了重复定义和数据不一致的问题。
方便维护和扩展：当需要增加或修改系统中某些常用数据（如新增一个状态或修改一个分类名称）时，只需要在字典表中进行修改即可，前端或后端无需更改代码，提升了系统的灵活性和可维护性。
简化前端展示：前端可以通过字典编码直接获取字典项并显示，无需在代码中硬编码这些值，减少了前端代码的复杂性。
支持动态加载：字典数据可以在系统运行时动态加载，前端请求时可以实时获取最新的字典项数据，适应业务的变化。

字典模块的主要功能

字典类型管理：用于管理不同的字典分类。例如，性别字典、状态字典、分类字典等。这些分类通常在数据库中以字典类型（dict_type）存储。
字典数据管理：每个字典类型下可以包含多个字典数据项，每个数据项都有唯一的字典编码（dict_code）、显示的字典标签（dict_label）以及字典值（dict_value）。
字典数据的增删改查：字典模块提供了对字典数据的增删改查操作接口。管理员可以通过后台管理界面方便地管理字典数据。
字典数据的缓存和加载：字典数据通常会被缓存到系统中以提高访问效率，并在系统启动时或字典数据变更时重新加载。

相关数据库表结构

在若依框架中，字典模块主要涉及以下几个数据库表：

sys_dict_type（字典类型表）：
- dict_id：字典类型的唯一标识。
- dict_name：字典类型的名称，例如“性别”。
- dict_type：字典类型的编码，通常用于前端请求时的识别和获取对应的字典数据。
- status：字典类型的状态，0表示正常，1表示停用。
- remark：字典类型的备注信息。
sys_dict_data（字典数据表）：
- dict_code：字典数据项的唯一标识。
- dict_sort：字典数据项的显示顺序。
- dict_label：字典数据项的显示标签，例如“男”、“女”。
- dict_value：字典数据项的值，例如“1”、“2”。
- dict_type：字典类型编码，与字典类型表中的dict_type关联。
- css_class：字典数据项的样式类（用于前端展示）。
- list_class：字典数据项的表格显示样式（用于前端表格展示）。
- is_default：是否为默认选项（0是，1否）。
- status：字典数据项的状态，0表示正常，1表示停用。
- remark：字典数据项的备注信息。

实现逻辑

字典类型和字典数据的关系：
- 每个字典类型可以对应多个字典数据项。例如，字典类型“性别”下可能有“男”和“女”两个字典数据项。
前端获取字典数据：
- 前端通过调用 /system/dict/data/type/{dictType} 接口，根据字典类型编码获取对应的字典数据列表。这些数据通常用于表单下拉框、状态标签等场景。
缓存机制：
- 字典数据在系统中通常会进行缓存，避免频繁的数据库查询，提高性能。缓存的字典数据在修改后会同步更新，确保前端展示的数据是最新的。

使用示例

性别选择：在用户注册或编辑表单中，性别选择框可以通过调用字典数据接口获取“性别”字典类型下的所有选项（如“男”、“女”），用户选择后，系统会存储对应的字典值（如“1”、“2”）。
状态显示：在数据列表中展示用户状态时，可以通过字典数据接口获取状态字典（如“正常”、“禁用”），并在表格中动态展示。

# 一、字典功能的引入和初始化

在若依系统中，可以通过简单的配置和方法调用来加载和使用字典数据。

# 1. 在 `main.js` 中引入全局字典变量和方法

若依系统的字典功能已经封装好了，我们可以直接在 main.js 中引入字典的全局变量和方法。

import DictData from '@/components/DictData';
DictData.install();

1
2

以上代码会将字典相关的方法注册到 Vue 实例上，方便在项目中的任何地方使用字典功能。

# 2. 加载数据字典

在组件中，可以通过 dicts 属性来声明需要加载的字典类型。可以加载多个字典类型。

export default {
  dicts: ['gender', 'status'], // 示例加载两个字典类型：gender 和 status
  ...
};

1
2
3
4

# 二、字典数据的读取和显示

字典数据可以通过内置的 dict.type 对象进行访问和使用。

# 1. 显示字典数据

以 el-select 组件为例，可以通过 v-for 指令循环渲染字典数据。

<el-select v-model="selectedValue" placeholder="请选择">
  <el-option
    v-for="dict in dict.type.gender"
    :key="dict.value"
    :label="dict.label"
    :value="dict.value"
  />
</el-select>

1
2
3
4
5
6
7
8

在上述示例中，dict.type.gender 是加载的字典数据源，label 和 value 分别表示字典的显示文本和实际值。

# 2. 翻译字典数据

字典数据翻译指的是将字典值转换为字典对应的标签。在表格中，通常使用 dict-tag 组件进行字典数据的翻译和展示。

<el-table-column label="性别" align="center" prop="gender">
  <template slot-scope="scope">
    <dict-tag :options="dict.type.gender" :value="scope.row.gender"/>
  </template>
</el-table-column>

1
2
3
4
5

对于自定义翻译方法，可以通过 selectDictLabel 函数来实现。

methods: {
  genderFormat(row) {
    return this.selectDictLabel(this.dict.type.gender, row.gender);
  },
},

1
2
3
4
5

# 三、不同版本的字典使用方法

# 1. 大于 3.7.0 版本

直接在 dicts 中声明需要的字典类型。
通过 dict.type 对象读取和翻译字典数据。

# 2. 小于 3.7.0 版本

在早期版本中，需要手动通过 API 加载字典数据，然后在组件的 data 或 created 钩子中使用这些数据。

import { getDicts } from "@/api/system/dict/data";

export default {
  data() {
    return {
      genderOptions: [],
    };
  },
  created() {
    this.getDicts("gender").then(response => {
      this.genderOptions = response.data;
    });
  },
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14

然后通过以下方式读取和翻译字典数据：

<el-option
  v-for="dict in genderOptions"
  :key="dict.dictValue"
  :label="dict.dictLabel"
  :value="dict.dictValue"
/>

<el-table-column label="性别" align="center" prop="gender">
  <template slot-scope="scope">
    <dict-tag :options="genderOptions" :value="scope.row.gender"/>
  </template>
</el-table-column>

1
2
3
4
5
6
7
8
9
10
11
12

# 四、字典组件的使用示例

字典组件 dict-tag 提供了丰富的选项和自定义功能：

单个值显示：

<dict-tag :options="sys_user_sex" value="1"></dict-tag>

多个值显示：

<dict-tag :options="sys_user_sex" value="1,2"></dict-tag>

自定义分隔符：

<dict-tag :options="sys_user_sex" value="0;1" separator=";"></dict-tag>

显示数组值：

<dict-tag :options="sys_user_sex" :value="[1,2]"></dict-tag>

当未找到匹配的数据时，显示原值：

<dict-tag :options="sys_user_sex" :value="[1,2,3,4,5]" :show-value="false"></dict-tag>

# 五、字典的使用场

# 1. 表单中的选择项

场景说明：在管理系统的表单中，通常需要用户选择一些固定的选项，例如性别、状态、分类等。这些选项的数据通常存储在字典中，并通过字典数据接口动态加载到前端进行展示。通过这种方式，可以确保系统中这些常用选项的一致性和可维护性。

字典的使用：在表单中，性别选择框通常通过调用字典数据接口获取“性别”字典类型下的所有选项（如“男”、“女”）。这些选项的实际值（如“1”、“2”）保存在字典数据表中。用户在表单中选择性别后，系统会将对应的字典值（如“1”代表“男”）存储在后端的数据库中。

实现方式：前端在加载表单时，通过调用getDicts('sys_user_sex')接口来获取字典数据。这些数据会被存储在前端变量中，然后渲染为选择框中的选项。

示例代码：

<el-select v-model="formData.gender" placeholder="请选择性别">
  <el-option
    v-for="item in genderOptions"
    :key="item.dictValue"
    :label="item.dictLabel"
    :value="item.dictValue">
  </el-option>
</el-select>

1
2
3
4
5
6
7
8

// 获取性别字典数据
getDicts('sys_user_sex').then(response => {
  this.genderOptions = response.data; // 将获取到的性别选项存储在genderOptions中，用于表单选择
});

1
2
3
4

解释：

用户在性别选择框中选择某个选项（如“男”），formData.gender会存储对应的字典值（如“1”）。
在表单提交时，formData.gender中的值会被发送到后端，并存储在数据库中，以表示用户的性别。

# 2. 数据列表中的状态显示

场景说明：在管理页面中，如用户列表、订单列表等，状态信息通常需要展示为人类可读的格式（如“启用”、“停用”），而这些状态的实际值（如“0”、“1”）存储在数据库中。通过数据字典，可以动态获取这些状态的标签和样式，在前端进行展示。

字典的使用：通过字典接口getDicts('sys_common_status')获取状态字典数据。这个字典数据包括状态的标签（如“启用”）和对应的值（如“0”）。在页面展示时，根据数据库中的状态值动态显示相应的标签和样式。

实现方式：前端在渲染表格时，通过字典值找到对应的标签和样式，并在表格中显示状态。

示例代码：

<el-table-column label="状态" prop="status">
  <template slot-scope="scope">
    <el-tag :type="getStatusType(scope.row.status)">
      {{ getStatusLabel(scope.row.status) }}
    </el-tag>
  </template>
</el-table-column>

1
2
3
4
5
6
7

// 获取状态字典数据
getDicts('sys_common_status').then(response => {
  this.statusOptions = response.data; // 将状态选项存储在statusOptions中，用于状态显示
});

// 根据字典值获取标签
getStatusLabel(value) {
  const item = this.statusOptions.find(option => option.dictValue === value);
  return item ? item.dictLabel : ''; // 返回对应的标签，如"启用"、"停用"
}

// 根据字典值获取标签样式
getStatusType(value) {
  const item = this.statusOptions.find(option => option.dictValue === value);
  return item ? item.cssClass : 'default'; // 返回对应的样式，如"success"、"warning"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

解释：

列表中每一行的状态字段会根据scope.row.status中的值，通过getStatusLabel函数获取对应的标签。
标签样式通过getStatusType函数动态设置，以便状态在界面上有直观的显示效果（如不同颜色的标签）。

# 3. 后台管理系统的配置项

场景说明：在系统设置中，管理员通常需要配置一些系统级别的选项，如通知方式、权限等级等。这些配置项的数据可以通过字典进行管理，方便管理员在后台进行修改和扩展。

字典的使用：通过调用字典接口getDicts('sys_notify_method')，系统管理员可以获取通知方式的字典项（如“短信通知”、“邮件通知”）。这些字典项会作为选项显示在配置页面的下拉框中，管理员选择后，系统将保存对应的字典值。

实现方式：前端在配置页面加载时，通过调用字典接口获取字典数据，并将这些数据作为选项渲染在配置表单中。

示例：

<el-select v-model="configData.notifyMethod" placeholder="请选择通知方式">
  <el-option
    v-for="item in notifyMethodOptions"
    :key="item.dictValue"
    :label="item.dictLabel"
    :value="item.dictValue">
  </el-option>
</el-select>

1
2
3
4
5
6
7
8

// 获取通知方式字典数据
getDicts('sys_notify_method').then(response => {
  this.notifyMethodOptions = response.data; // 将通知方式选项存储在notifyMethodOptions中
});

1
2
3
4

解释：

用户在通知方式的选择框中选择一种方式（如“短信通知”），对应的字典值（如“1”）会存储在configData.notifyMethod中。
在配置保存时，选择的字典值会提交到后台，并保存为系统的配置项。

# 4. 系统日志记录

场景说明：在系统中记录用户操作日志时，操作类型（如“登录”、“修改资料”、“删除记录”）通常需要以人类可读的形式存储和展示。通过字典模块，操作类型可以统一管理，方便日志的记录和查询。

字典的使用：在记录操作日志时，通过字典获取操作类型的标签（如“登录”），然后将这些标签存储在日志记录中。当管理员查看日志时，系统会根据字典值显示对应的标签。

实现方式：在日志展示页面中，通过字典接口获取操作类型数据，并在表格中根据日志记录的类型值显示对应的标签。

示例：

<el-table-column label="操作类型" prop="operationType">
  <template slot-scope="scope">
    {{ getOperationTypeLabel(scope.row.operationType) }}
  </template>
</el-table-column>

1
2
3
4
5

// 获取操作类型字典数据
getDicts('sys_operation_type').then(response => {
  this.operationTypeOptions = response.data; // 将操作类型选项存储在operationTypeOptions中
});

// 根据字典值获取操作类型标签
getOperationTypeLabel(value) {
  const item = this.operationTypeOptions.find(option => option.dictValue === value);
  return item ? item.dictLabel : ''; // 返回操作类型的标签，如"登录"、"修改"、"删除"
}

1
2
3
4
5
6
7
8
9
10

解释：

每条日志记录的操作类型字段会通过scope.row.operationType中的值，使用getOperationTypeLabel函数找到对应的标签进行展示。
日志表格会以直观的方式展示用户的操作类型，使得管理员可以轻松了解每一条记录的操作内容。

# 5. 前后端交互中的枚举值传递

场景说明：在前后端数据交互过程中，常常需要传递一些固定的枚举值，例如状态、类型等。为了确保前后端的一致性，这些枚举值通常通过字典进行管理和使用。

字典的使用：前端通过字典接口获取枚举类型的字典值，并在请求时将这些值作为参数传递给后端。这样可以确保前后端在处理这些数据时使用相同的值，避免硬编码带来的错误。

实现方式：在前端发起请求时，使用字典项中的值作为参数传递给后端，后端根据这些值进行相应的处理。

示例：

// 前端发起查询请求，传递状态参数
this.$http.get('/api/users', {
  params: {
    status: this.selectedStatus // selectedStatus 是从字典表中选择的状态值
  }
});

1
2
3
4
5
6

解释：

用户在前端选择了某个状态（如“启用”），对应的字典值（如“0”）会存储在selectedStatus中。
当发起查询请求时，这个字典值会作为参数传递给后端，用于

查询符合条件的数据。

# 6. 国际化支持

场景说明：在多语言支持的系统中，字典表可以为不同语言的字典项进行定义，这样在用户选择不同语言时，系统能够自动显示对应的字典标签，支持多语言界面。

字典的使用：通过字典表管理不同语言的字典标签，当用户切换语言时，系统根据当前语言设置动态加载对应的字典标签，实现界面内容的国际化支持。

实现方式：在前端切换语言时，通过字典接口获取对应语言的字典数据，并在界面上展示。

示例：

<el-select v-model="selectedLanguage" placeholder="选择语言">
  <el-option
    v-for="item in languageOptions"
    :key="item.dictValue"
    :label="item.dictLabel"
    :value="item.dictValue">
  </el-option>
</el-select>

1
2
3
4
5
6
7
8

// 获取语言字典数据
getDicts('sys_language').then(response => {
  this.languageOptions = response.data; // 将语言选项存储在languageOptions中
});

// 动态设置字典标签的语言版本
setLanguage(dictType, language) {
  this.getDicts(dictType).then(response => {
    response.data.forEach(item => {
      item.dictLabel = item[`dictLabel_${language}`]; // 根据语言设置动态修改字典标签
    });
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13

解释：

当用户选择了一种语言（如“英语”），setLanguage函数会根据选择的语言动态加载对应的字典标签。
在页面展示时，字典标签会根据当前语言显示相应的内容，确保系统的多语言支持。

总结

通过字典管理功能，可以极大地提高数据类型的管理效率和代码的可维护性。无论是在表单中选择数据，还是在表格中展示数据，字典功能都能提供一致、简洁的解决方案。根据项目的版本和需求，可以选择合适的字典使用方式，确保项目的稳定性和易维护性。

编辑此页

上次更新: 2024/12/28, 18:32:08

← 使用 Svg Icon 图标动态系统参数→

使用字典功能

# 使用字典功能的详细总结

# 一、字典功能的引入和初始化

# 1. 在 main.js 中引入全局字典变量和方法

# 2. 加载数据字典

# 二、字典数据的读取和显示

# 1. 显示字典数据

# 2. 翻译字典数据

# 三、不同版本的字典使用方法

# 1. 大于 3.7.0 版本

# 2. 小于 3.7.0 版本

# 四、字典组件的使用示例

# 五、字典的使用场

# 1. 表单中的选择项

# 2. 数据列表中的状态显示

# 3. 后台管理系统的配置项

# 4. 系统日志记录

# 5. 前后端交互中的枚举值传递

# 6. 国际化支持

# 1. 在 `main.js` 中引入全局字典变量和方法