梵医云开发文档

Appearance

字典数据 ​

1. 字典数据概述 ​

梵医云前端项目使用数据字典来管理系统中的枚举值、状态码等固定数据。字典数据存储在 Pinia Store 中，并通过工具函数进行访问和使用。

1.1 字典数据特点 ​

  • 集中管理：所有字典数据集中存储在 Store 中
  • 缓存机制：使用 sessionStorage 缓存字典数据，提高访问效率
  • 自动更新：字典数据支持自动刷新，过期时间为 60 秒
  • 类型安全：提供 TypeScript 类型定义，确保类型安全
  • 易于使用：提供丰富的工具函数，简化字典数据的使用

1.2 字典数据结构 ​

typescript
interface DictDataType {
  dictType: string      // 字典类型
  label: string         // 字典标签
  value: string | number | boolean  // 字典值
  colorType: ElementPlusInfoType | ''  // 颜色类型
  cssClass: string      // CSS 类名
}

2. 字典数据工具函数 ​

2.1 getDictOptions ​

获取指定字典类型的数据字典数组。

typescript
/**
 * 获取 dictType 对应的数据字典数组
 * @param dictType 数据类型
 * @returns 数据字典数组
 */
getDictOptions(dictType: string): DictDataType[]

示例：

vue
<template>
  <el-select v-model="form.status" placeholder="请选择状态">
    <el-option
      v-for="dict in getDictOptions(DICT_TYPE.COMMON_STATUS)"
      :key="dict.value"
      :label="dict.label"
      :value="dict.value"
    />
  </el-select>
</template>

<script setup lang="ts">
import { getDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'
</script>

2.2 getIntDictOptions ​

获取整数类型的字典选项数组。

typescript
/**
 * 获取整数类型的字典选项数组
 * @param dictType 数据类型
 * @returns 整数类型字典选项数组
 */
getIntDictOptions(dictType: string): NumberDictDataType[]

示例：

vue
<template>
  <el-select v-model="form.status" placeholder="请选择状态">
    <el-option
      v-for="dict in getIntDictOptions(DICT_TYPE.COMMON_STATUS)"
      :key="dict.value"
      :label="dict.label"
      :value="dict.value"
    />
  </el-select>
</template>

<script setup lang="ts">
import { getIntDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'
</script>

2.3 getStrDictOptions ​

获取字符串类型的字典选项数组。

typescript
/**
 * 获取字符串类型的字典选项数组
 * @param dictType 数据类型
 * @returns 字符串类型字典选项数组
 */
getStrDictOptions(dictType: string): StringDictDataType[]

示例：

vue
<template>
  <el-select v-model="form.type" placeholder="请选择类型">
    <el-option
      v-for="dict in getStrDictOptions(DICT_TYPE.SYSTEM_USER_SEX)"
      :key="dict.value"
      :label="dict.label"
      :value="dict.value"
    />
  </el-select>
</template>

<script setup lang="ts">
import { getStrDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'
</script>

2.4 getBoolDictOptions ​

获取布尔类型的字典选项数组。

typescript
/**
 * 获取布尔类型的字典选项数组
 * @param dictType 数据类型
 * @returns 布尔类型字典选项数组
 */
getBoolDictOptions(dictType: string): DictDataType[]

示例：

vue
<template>
  <el-select v-model="form.enabled" placeholder="请选择是否启用">
    <el-option
      v-for="dict in getBoolDictOptions(DICT_TYPE.INFRA_BOOLEAN_STRING)"
      :key="dict.value"
      :label="dict.label"
      :value="dict.value"
    />
  </el-select>
</template>

<script setup lang="ts">
import { getBoolDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'
</script>

2.5 getDictObj ​

获取指定字典类型的指定值对应的字典对象。

typescript
/**
 * 获取指定字典类型的指定值对应的字典对象
 * @param dictType 字典类型
 * @param value 字典值
 * @return 字典对象
 */
getDictObj(dictType: string, value: any): DictDataType | undefined

示例：

vue
<script setup lang="ts">
import { getDictObj } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const statusObj = getDictObj(DICT_TYPE.COMMON_STATUS, 0)
console.log(statusObj?.label) // 输出：启用
console.log(statusObj?.colorType) // 输出：success
</script>

2.6 getDictLabel ​

获得字典数据的文本展示。

typescript
/**
 * 获得字典数据的文本展示
 * @param dictType 字典类型
 * @param value 字典数据的值
 * @return 字典名称
 */
getDictLabel(dictType: string, value: any): string

示例：

vue
<template>
  <el-table :data="tableData">
    <el-table-column label="状态">
      <template #default="{ row }">
        {{ getDictLabel(DICT_TYPE.COMMON_STATUS, row.status) }}
      </template>
    </el-table-column>
  </el-table>
</template>

<script setup lang="ts">
import { getDictLabel } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'
</script>

3. 字典数据类型枚举 ​

3.1 通用类型 ​

typescript
enum DICT_TYPE {
  USER_TYPE = 'user_type',                    // 用户类型
  COMMON_STATUS = 'common_status',             // 通用状态
  COMMON_ACTIVE_STATUS = 'common_active_status', // 活动状态
  TERMINAL = 'terminal',                       // 终端
  DATE_INTERVAL = 'date_interval',             // 数据间隔
}

3.2 系统模块 (SYSTEM) ​

typescript
enum DICT_TYPE {
  SYSTEM_USER_SEX = 'system_user_sex',         // 用户性别
  SYSTEM_MENU_TYPE = 'system_menu_type',       // 菜单类型
  SYSTEM_ROLE_TYPE = 'system_role_type',       // 角色类型
  SYSTEM_DATA_SCOPE = 'system_data_scope',     // 数据范围
  SYSTEM_NOTICE_TYPE = 'system_notice_type',   // 通知类型
  SYSTEM_LOGIN_TYPE = 'system_login_type',     // 登录类型
  SYSTEM_LOGIN_RESULT = 'system_login_result', // 登录结果
  SYSTEM_SMS_CHANNEL_CODE = 'system_sms_channel_code', // 短信渠道编码
  SYSTEM_SMS_TEMPLATE_TYPE = 'system_sms_template_type', // 短信模板类型
  SYSTEM_SMS_SEND_STATUS = 'system_sms_send_status', // 短信发送状态
  SYSTEM_SMS_RECEIVE_STATUS = 'system_sms_receive_status', // 短信接收状态
  SYSTEM_OAUTH2_GRANT_TYPE = 'system_oauth2_grant_type', // OAuth2 授权类型
  SYSTEM_MAIL_SEND_STATUS = 'system_mail_send_status', // 邮件发送状态
  SYSTEM_NOTIFY_TEMPLATE_TYPE = 'system_notify_template_type', // 通知模板类型
  SYSTEM_SOCIAL_TYPE = 'system_social_type',   // 社交登录类型
}

3.3 基础设施模块 (INFRA) ​

typescript
enum DICT_TYPE {
  INFRA_BOOLEAN_STRING = 'infra_boolean_string', // 布尔字符串
  INFRA_JOB_STATUS = 'infra_job_status',       // 定时任务状态
  INFRA_JOB_LOG_STATUS = 'infra_job_log_status', // 定时任务日志状态
  INFRA_API_ERROR_LOG_PROCESS_STATUS = 'infra_api_error_log_process_status', // API 错误日志处理状态
  INFRA_CONFIG_TYPE = 'infra_config_type',     // 配置类型
  INFRA_CODEGEN_TEMPLATE_TYPE = 'infra_codegen_template_type', // 代码生成模板类型
  INFRA_CODEGEN_FRONT_TYPE = 'infra_codegen_front_type', // 代码生成前端类型
  INFRA_CODEGEN_SCENE = 'infra_codegen_scene', // 代码生成场景
  INFRA_FILE_STORAGE = 'infra_file_storage',   // 文件存储
  INFRA_OPERATE_TYPE = 'infra_operate_type',   // 操作类型
}

3.4 工作流模块 (BPM) ​

typescript
enum DICT_TYPE {
  BPM_MODEL_FORM_TYPE = 'bpm_model_form_type', // 流程表单类型
  BPM_TASK_CANDIDATE_STRATEGY = 'bpm_task_candidate_strategy', // 任务候选人策略
  BPM_PROCESS_INSTANCE_STATUS = 'bpm_process_instance_status', // 流程实例状态
  BPM_TASK_STATUS = 'bpm_task_status',         // 任务状态
  BPM_OA_LEAVE_TYPE = 'bpm_oa_leave_type',     // OA 请假类型
  BPM_PROCESS_LISTENER_TYPE = 'bpm_process_listener_type', // 流程监听器类型
  BPM_PROCESS_LISTENER_VALUE_TYPE = 'bpm_process_listener_value_type', // 流程监听器值类型
}

3.5 支付模块 (PAY) ​

typescript
enum DICT_TYPE {
  PAY_CHANNEL_CODE = 'pay_channel_code',      // 支付渠道编码类型
  PAY_ORDER_STATUS = 'pay_order_status',      // 商户支付订单状态
  PAY_REFUND_STATUS = 'pay_refund_status',     // 退款订单状态
  PAY_NOTIFY_STATUS = 'pay_notify_status',     // 商户支付回调状态
  PAY_NOTIFY_TYPE = 'pay_notify_type',         // 商户支付回调类型
  PAY_TRANSFER_STATUS = 'pay_transfer_status',  // 转账订单状态
  PAY_TRANSFER_TYPE = 'pay_transfer_type',     // 转账订单类型
  PAY_TRANSFER_AUDIT = 'pay_transfer_audit',   // 转账审核状态
  WITHDRAW_STATUS = 'withdraw_status',        // 提现状态
}

3.6 公众号模块 (MP) ​

typescript
enum DICT_TYPE {
  MP_AUTO_REPLY_REQUEST_MATCH = 'mp_auto_reply_request_match', // 自动回复请求匹配类型
  MP_MESSAGE_TYPE = 'mp_message_type',     // 消息类型
}

3.7 会员模块 (MEMBER) ​

typescript
enum DICT_TYPE {
  MEMBER_POINT_BIZ_TYPE = 'member_point_biz_type', // 积分的业务类型
  MEMBER_EXPERIENCE_BIZ_TYPE = 'member_experience_biz_type', // 会员经验业务类型
  NUMBER_ALLOCATION_TYPE = 'number_allocation_type', // 编码分配类别
  DISTINGGUISH_TYPE = 'distinguish',         // 编码类型
  POST_MANAGEMENT = 'post_management',       // 岗位管理
  CODE_BIND_ROLES = 'code_bind_roles',       // 职位
}

3.8 商品模块 (MALL - PRODUCT) ​

typescript
enum DICT_TYPE {
  PRODUCT_SPU_STATUS = 'product_spu_status', // 商品状态
  PRODUCT_AUDIT_STATUS = 'product_audit_status', // 商品审核状态
  PRODUCT_AUDIT_TYPE = 'product_audit_type', // 商品审核类型
  ENTERPRISE_CLASS_STATUS = 'enterprise_class_status', // 企业类别状态
  ENTERPRISE_TYPE = 'enterprise_type',       // 企业类别
  GOODS_BRAND_LABEL = 'goods_brand_label',   // 商品活动分类
  DETERMINE_CATEGORY_TYPE = 'determine_category_type', // 确定分类类型
}

3.9 交易模块 (MALL - TRADE) ​

typescript
enum DICT_TYPE {
  EXPRESS_CHARGE_MODE = 'trade_delivery_express_charge_mode', // 快递的计费方式
  TRADE_AFTER_SALE_STATUS = 'trade_after_sale_status', // 售后状态
  TRADE_AFTER_SALE_WAY = 'trade_after_sale_way', // 售后方式
  TRADE_AFTER_SALE_TYPE = 'trade_after_sale_type', // 售后类型
  TRADE_ORDER_TYPE = 'trade_order_type',   // 订单类型
  TRADE_ORDER_STATUS = 'trade_order_status', // 订单状态
  TRADE_ORDER_ITEM_AFTER_SALE_STATUS = 'trade_order_item_after_sale_status', // 订单项售后状态
  TRADE_DELIVERY_TYPE = 'trade_delivery_type', // 配送方式
  TRADE_DELIVERY_SUB_TYPE = 'delivery_sub_type', // 配送方式2
  TRADE_DELIVERY_STATE = 'trade_delivery_state', // 发货状态
  TRADE_DELIVERY_BATCH_STATUS = 'trade_delivery_batch_status', // 批量发货状态
  BROKERAGE_ENABLED_CONDITION = 'brokerage_enabled_condition', // 分佣模式
  BROKERAGE_BIND_MODE = 'brokerage_bind_mode', // 分销关系绑定模式
  BROKERAGE_BANK_NAME = 'brokerage_bank_name', // 佣金提现银行
  BROKERAGE_WITHDRAW_TYPE = 'brokerage_withdraw_type', // 佣金提现类型
  BROKERAGE_RECORD_BIZ_TYPE = 'brokerage_record_biz_type', // 佣金业务类型
  BROKERAGE_RECORD_STATUS = 'brokerage_record_status', // 佣金状态
  BROKERAGE_WITHDRAW_STATUS = 'brokerage_withdraw_status', // 佣金提现状态
}

3.10 营销模块 (MALL - PROMOTION) ​

typescript
enum DICT_TYPE {
  PROMOTION_DISCOUNT_TYPE = 'promotion_discount_type', // 优惠类型
  PROMOTION_PRODUCT_SCOPE = 'promotion_product_scope', // 营销的商品范围
  PROMOTION_COUPON_TEMPLATE_VALIDITY_TYPE = 'promotion_coupon_template_validity_type', // 优惠劵模板的有限期类型
  PROMOTION_COUPON_STATUS = 'promotion_coupon_status', // 优惠劵的状态
  PROMOTION_COUPON_TAKE_TYPE = 'promotion_coupon_take_type', // 优惠劵的领取方式
  PROMOTION_ACTIVITY_STATUS = 'promotion_activity_status', // 优惠活动的状态
  PROMOTION_CONDITION_TYPE = 'promotion_condition_type', // 营销的条件类型
  PROMOTION_BARGAIN_RECORD_STATUS = 'promotion_bargain_record_status', // 砍价记录的状态
  PROMOTION_COMBINATION_RECORD_STATUS = 'promotion_combination_record_status', // 拼团记录的状态
  PROMOTION_BANNER_POSITION = 'promotion_banner_position', // banner 定位
  DISTRIBUTION_ESCALATION_RULE = 'distribution_escalation_rule', // 分销升级条件
  DISTRIBUTION_GRADE = 'distribution_grade', // 分销等级
  DISTRIBUTION_ARRIVAL_TERMS = 'distribution_arrival_terms', // 分销佣金到帐条件
  RAWARD_STATUS = 'raward_status',           // 分红计划执行状态
  REWARD_AT = 'raward_at',                   // 分红时间节点
  DIVIDEND_RECORD_STATUS = 'dividend_record_status', // 分红记录状态
  DIVIDEND_RECORD_READ = 'dividend_record_read', // 分红记录读状态
}

3.11 客户管理模块 (CRM) ​

typescript
enum DICT_TYPE {
  CRM_AUDIT_STATUS = 'crm_audit_status',     // CRM 审批状态
  CRM_BIZ_TYPE = 'crm_biz_type',             // CRM 业务类型
  CRM_BUSINESS_END_STATUS_TYPE = 'crm_business_end_status_type', // CRM 商机结束状态类型
  CRM_RECEIVABLE_RETURN_TYPE = 'crm_receivable_return_type', // CRM 回款的还款方式
  CRM_CUSTOMER_INDUSTRY = 'crm_customer_industry', // CRM 客户所属行业
  CRM_CUSTOMER_LEVEL = 'crm_customer_level', // CRM 客户级别
  CRM_CUSTOMER_SOURCE = 'crm_customer_source', // CRM 客户来源
  CRM_PRODUCT_STATUS = 'crm_product_status', // CRM 商品状态
  CRM_PERMISSION_LEVEL = 'crm_permission_level', // CRM 数据权限的级别
  CRM_PRODUCT_UNIT = 'crm_product_unit',     // CRM 产品单位
  CRM_FOLLOW_UP_TYPE = 'crm_follow_up_type', // CRM 跟进方式
}

3.12 企业资源计划模块 (ERP) ​

typescript
enum DICT_TYPE {
  ERP_AUDIT_STATUS = 'erp_audit_status',     // ERP 审批状态
  ERP_STOCK_RECORD_BIZ_TYPE = 'erp_stock_record_biz_type', // 库存明细的业务类型
  ERP_PRODUCT_AUDIT = 'erp_product_audit',   // 商品审核状态
  ERP_PRODUCT_STATUS = 'erp_product_state',  // 商品状态
  ERP_PAY_METHOD = 'pay_method',             // 支付方式
  ERP_COMPANY_PURCHASE_STATUS = 'erp_company_purchase_status', // 采购状态
  ERP_PAYMENT_METHOD = 'payment_method',     // 结算方式
  ERP_RETURN_METHOD = 'return_method',       // 退货方式
  ERP_REOLENISH_STATUS = 'reolenish_status', // 补货状态
  ERP_REPLENISH_TYPE = 'replenish_type',     // 补货类型
  ERP_INQUIRE_PRICE = 'inquire_price',       // 是否询价
  ERP_PURCHASING_PLAN_TYPE = 'purchasing_plan_type', // 采购计划类型
  ERP_CONTRACT_TYPE = 'contract_type',       // 合同类型
  ERP_TRAMSPORTATION_METHOD = 'transportation_method', // 承运方式
  ERP_TRAMSPORT_METHOD = 'transport_method', // 运输方式
  ERP_IS_DIRECT_ADJUST = 'is_direct_adjust', // 是否直调
  ERP_TEMPERATURE_CONTRO_CONDITION = 'temperature_contro_condition', // 温控状况
  ERP_TEMPERATURE_CONTRO_METHOD = 'temperature_control_method', // 温控方式
  ERP_METHOD_NOTE = 'payment_method_note',   // 付款方式
  ERP_ENTERPRISE_PROPERTY = 'erp_enterprise_property', // 企业类型
  ERP_IS_HAVE_TICKET = 'is_have_ticket',     // 是否带票
  ERP_SUSPICIOUS_LOCK = 'suspicious_lock',   // 可疑锁定
  ERP_ACCEPTANC = 'acceptance_status',       // 验收情况
  ERP_INVENTORY_TYPE = 'inventory_type',     // 验收情况
  ERP_RETAIL_ORDER_STATUS = 'retail_order_status', // 零售订支付状态
  ERP_PRODUCT_SHELF_STATUS = 'erp_product_shelf_status', // ERP 是否上下架
  ERP_IS_PRESCRIPTION = 'is_prescription',   // 是否是处方药
  ERP_IS_EPHEDRINE = 'is_ephedrine',        // 是否是黄麻碱
  ERP_GROUP_TYPE = 'group_type',             // 汇总方式
  ERP_DOCUMENT_TYPE = 'document_type',       // 单据类型
  ERP_INVENTORY_STATUS = 'Inventory_status', // 单据状态
  ERP_LEVEL = 'level',                       // 货位类别
  ERP_ATTRIBUT = 'attribute',                // 零售货位属性
  ERP_DISTRIBUTION_DOC_TYPE = 'erp_distribution_doc_type', // ERP 配送单据类型
  ERP_MAINTENANCE_TYPE = 'maintenance_type', // 养护类型
  ERP_GENERATING_CYCLE = 'generating_cycle', // 生成周期
  ERP_SORT_CRITERIA = 'sort_criteria',      // 养护排序条件
  ERP_MAINTENANCE_CONTENT = 'maintenance_content', // 养护内容
  ERP_MAINTENANCE_METHOD = 'maintenance_method', // 养护方法
  ERP_QUALITY_CONDITION = 'quality_condition', // 养护管理-质量状况
  ERP_CHECK_CONCLUSION = 'check_conclusion', // 养护管理-验收结论
  ERP_REVIEW_STATUS = 'review_status',      // 养护管理-单据状态
  ERP_IS_SUBMIT = 'is_submit',              // 复核单状态
  ERP_EXPIRY_DATE = 'expiry_date',          // 过期日期
  ERP_DEVICE_TYPE = 'device_type',           // 设备类型
  ERP_DEVICE_STATUS = 'device_status',      // 设备状态
  ERP_DEVICE_FIX_STATUS = 'device_fix_status', // 维修状态
  ERP_DEVICE_FAULT_STATUS = 'device_fault_status', // 故障状态
}

3.13 人工智能模块 (AI) ​

typescript
enum DICT_TYPE {
  AI_PLATFORM = 'ai_platform',               // AI 平台
  AI_IMAGE_STATUS = 'ai_image_status',      // AI 图片状态
  AI_MUSIC_STATUS = 'ai_music_status',       // AI 音乐状态
  AI_GENERATE_MODE = 'ai_generate_mode',     // AI 生成模式
  AI_WRITE_TYPE = 'ai_write_type',           // AI 写作类型
  AI_WRITE_LENGTH = 'ai_write_length',       // AI 写作长度
  AI_WRITE_FORMAT = 'ai_write_format',       // AI 写作格式
  AI_WRITE_TONE = 'ai_write_tone',           // AI 写作语气
  AI_WRITE_LANGUAGE = 'ai_write_language',   // AI 写作语言
}

3.14 门店管理模块 (STORE) ​

typescript
enum DICT_TYPE {
  STORE_STATE = 'store_state',               // 门店状态
  IS_ONLINE = 'is_online',                   // 是否上线
  IS_DIRECT_SALES = 'is_direct_sales',       // 是否直营
  SAME_CITY_LOGISTICS = 'same_city_logistics', // 同城物流
  ACCOUNT_SPLITTING_SUPPORT = 'account_splitting_support', // 分账支持
  SERVICE_ENABLE = 'service_enable',         // 是否启用
  STORE_TYPE = 'store_type',                 // 门店类型
}

3.15 医院管理模块 (HOSPITAL) ​

typescript
enum DICT_TYPE {
  HOSPITAL_TYPE = 'hospital_type',           // 医院类型
  HOSPITAL_APPOINTMENT_ORDER_STATUS = 'appointment_order_status' // 预约订单状态
}

4. 字典数据在组件中的使用 ​

4.1 在表单中使用字典 ​

vue
<template>
  <el-form :model="form" label-width="120px">
    <el-form-item label="用户状态">
      <el-select v-model="form.status" placeholder="请选择用户状态">
        <el-option
          v-for="dict in getIntDictOptions(DICT_TYPE.COMMON_STATUS)"
          :key="dict.value"
          :label="dict.label"
          :value="dict.value"
        />
      </el-select>
    </el-form-item>

    <el-form-item label="用户性别">
      <el-select v-model="form.sex" placeholder="请选择用户性别">
        <el-option
          v-for="dict in getStrDictOptions(DICT_TYPE.SYSTEM_USER_SEX)"
          :key="dict.value"
          :label="dict.label"
          :value="dict.value"
        />
      </el-select>
    </el-form-item>

    <el-form-item label="是否启用">
      <el-select v-model="form.enabled" placeholder="请选择是否启用">
        <el-option
          v-for="dict in getBoolDictOptions(DICT_TYPE.INFRA_BOOLEAN_STRING)"
          :key="dict.value"
          :label="dict.label"
          :value="dict.value"
        />
      </el-select>
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import { reactive } from 'vue'
import { getIntDictOptions, getStrDictOptions, getBoolDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const form = reactive({
  status: 0,
  sex: '1',
  enabled: true
})
</script>

4.2 在表格中使用字典 ​

vue
<template>
  <el-table :data="tableData">
    <el-table-column label="用户编号" prop="id" />
    <el-table-column label="用户名称" prop="username" />
    <el-table-column label="用户性别">
      <template #default="{ row }">
        {{ getDictLabel(DICT_TYPE.SYSTEM_USER_SEX, row.sex) }}
      </template>
    </el-table-column>
    <el-table-column label="用户状态">
      <template #default="{ row }">
        <el-tag :type="getDictObj(DICT_TYPE.COMMON_STATUS, row.status)?.colorType">
          {{ getDictLabel(DICT_TYPE.COMMON_STATUS, row.status) }}
        </el-tag>
      </template>
    </el-table-column>
    <el-table-column label="创建时间" prop="createTime" />
  </el-table>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { getDictLabel, getDictObj } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const tableData = ref([
  {
    id: 1,
    username: 'admin',
    sex: '1',
    status: 0,
    createTime: '2024-01-01 00:00:00'
  }
])
</script>

4.3 在搜索表单中使用字典 ​

vue
<template>
  <el-form :model="queryParams" :inline="true">
    <el-form-item label="用户状态">
      <el-select v-model="queryParams.status" placeholder="请选择用户状态" clearable>
        <el-option
          v-for="dict in getIntDictOptions(DICT_TYPE.COMMON_STATUS)"
          :key="dict.value"
          :label="dict.label"
          :value="dict.value"
        />
      </el-select>
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="handleQuery">搜索</el-button>
      <el-button @click="resetQuery">重置</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import { reactive } from 'vue'
import { getIntDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const queryParams = reactive({
  status: undefined
})

const handleQuery = () => {
  console.log('搜索', queryParams)
}

const resetQuery = () => {
  queryParams.status = undefined
}
</script>

4.4 在弹窗中使用字典 ​

vue
<template>
  <el-dialog v-model="dialogVisible" title="新增用户">
    <el-form :model="form" label-width="120px">
      <el-form-item label="用户名称">
        <el-input v-model="form.username" />
      </el-form-item>
      <el-form-item label="用户状态">
        <el-select v-model="form.status" placeholder="请选择用户状态">
          <el-option
            v-for="dict in getIntDictOptions(DICT_TYPE.COMMON_STATUS)"
            :key="dict.value"
            :label="dict.label"
            :value="dict.value"
          />
        </el-select>
      </el-form-item>
    </el-form>
    <template #footer>
      <el-button @click="dialogVisible = false">取消</el-button>
      <el-button type="primary" @click="handleConfirm">确定</el-button>
    </template>
  </el-dialog>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue'
import { getIntDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const dialogVisible = ref(false)
const form = reactive({
  username: '',
  status: 0
})

const handleConfirm = () => {
  console.log('提交', form)
  dialogVisible.value = false
}
</script>

5. 字典数据 Store ​

5.1 Store 结构 ​

typescript
interface DictState {
  dictMap: Map<string, any>    // 字典数据映射
  isSetDict: boolean            // 是否已设置字典
}

5.2 Store 方法 ​

setDictMap ​

设置字典数据映射。

typescript
async setDictMap(): Promise<void>

getDictByType ​

根据类型获取字典数据。

typescript
getDictByType(type: string): DictDataType[]

resetDict ​

重置字典数据。

typescript
async resetDict(): Promise<void>

5.3 使用 Store ​

vue
<script setup lang="ts">
import { useDictStoreWithOut } from '@/store/modules/dict'

const dictStore = useDictStoreWithOut()

// 设置字典数据
await dictStore.setDictMap()

// 获取字典数据
const dictData = dictStore.getDictByType('common_status')

// 重置字典数据
await dictStore.resetDict()
</script>

6. 字典数据最佳实践 ​

6.1 命名规范 ​

  • 使用大写字母和下划线命名字典类型
  • 字典类型应该具有描述性
  • 使用模块前缀区分不同模块的字典
typescript
// ✅ 好的命名
enum DICT_TYPE {
  COMMON_STATUS = 'common_status',
  SYSTEM_USER_SEX = 'system_user_sex',
  PRODUCT_SPU_STATUS = 'product_spu_status',
}

// ❌ 不好的命名
enum DICT_TYPE {
  status = 'status',
  userSex = 'user_sex',
  productStatus = 'product_status',
}

6.2 工具函数选择 ​

根据字典值的类型选择合适的工具函数：

vue
<script setup lang="ts">
// ✅ 正确选择工具函数
import { getIntDictOptions, getStrDictOptions, getBoolDictOptions } from '@/utils/dict'

// 整数类型字典
const statusOptions = getIntDictOptions(DICT_TYPE.COMMON_STATUS)

// 字符串类型字典
const sexOptions = getStrDictOptions(DICT_TYPE.SYSTEM_USER_SEX)

// 布尔类型字典
const enabledOptions = getBoolDictOptions(DICT_TYPE.INFRA_BOOLEAN_STRING)

// ❌ 不正确选择工具函数
const statusOptions = getStrDictOptions(DICT_TYPE.COMMON_STATUS) // 应该使用 getIntDictOptions
</script>

6.3 性能优化 ​

  • 避免在循环中重复调用字典函数
  • 使用计算属性缓存字典数据
  • 合理使用字典缓存
vue
<script setup lang="ts">
import { computed } from 'vue'
import { getIntDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

// ✅ 好的做法：使用计算属性
const statusOptions = computed(() => getIntDictOptions(DICT_TYPE.COMMON_STATUS))

// ❌ 不好的做法：在循环中重复调用
const getStatusLabel = (value: number) => {
  const options = getIntDictOptions(DICT_TYPE.COMMON_STATUS)
  return options.find(item => item.value === value)?.label
}
</script>

6.4 类型安全 ​

使用 TypeScript 类型定义确保类型安全：

vue
<script setup lang="ts">
import { ref } from 'vue'
import { getIntDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

// ✅ 好的做法：明确指定类型
const status = ref<number>(0)
const statusOptions = getIntDictOptions(DICT_TYPE.COMMON_STATUS)

// ❌ 不好的做法：不指定类型
const status = ref(0)
</script>

6.5 错误处理 ​

处理字典数据不存在的情况：

vue
<script setup lang="ts">
import { getDictLabel } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const getStatusLabel = (value: number) => {
  const label = getDictLabel(DICT_TYPE.COMMON_STATUS, value)
  return label || '未知状态'
}
</script>

7. 字典数据常见问题 ​

7.1 字典数据不显示 ​

问题原因：

  • 字典类型名称错误
  • 字典数据未加载
  • 字典缓存过期

解决方案：

vue
<script setup lang="ts">
import { onMounted } from 'vue'
import { useDictStoreWithOut } from '@/store/modules/dict'
import { getIntDictOptions } from '@/utils/dict'
import { DICT_TYPE } from '@/utils/dict'

const dictStore = useDictStoreWithOut()

onMounted(async () => {
  // 确保字典数据已加载
  await dictStore.setDictMap()
})

// ✅ 正确的字典类型
const statusOptions = getIntDictOptions(DICT_TYPE.COMMON_STATUS)

// ❌ 错误的字典类型
const statusOptions = getIntDictOptions('common_status')
</script>

7.2 字典标签不显示 ​

问题原因：

  • 字典值类型不匹配
  • 字典数据不存在

解决方案：

vue
<template>
  <el-table :data="tableData">
    <el-table-column label="状态">
      <template #default="{ row }">
        <!-- ✅ 正确：使用 getDictLabel -->
        {{ getDictLabel(DICT_TYPE.COMMON_STATUS, row.status) }}

        <!-- ❌ 错误：直接显示值 -->
        {{ row.status }}
      </template>
    </el-table-column>
  </el-table>
</template>

7.3 字典颜色不显示 ​

问题原因：

  • colorType 未正确设置
  • el-tag 的 type 属性未绑定

解决方案：

vue
<template>
  <el-table :data="tableData">
    <el-table-column label="状态">
      <template #default="{ row }">
        <!-- ✅ 正确：使用 colorType -->
        <el-tag :type="getDictObj(DICT_TYPE.COMMON_STATUS, row.status)?.colorType">
          {{ getDictLabel(DICT_TYPE.COMMON_STATUS, row.status) }}
        </el-tag>

        <!-- ❌ 错误：不使用 colorType -->
        <el-tag>
          {{ getDictLabel(DICT_TYPE.COMMON_STATUS, row.status) }}
        </el-tag>
      </template>
    </el-table-column>
  </el-table>
</template>

7.4 字典缓存问题 ​

问题原因：

  • 字典缓存过期
  • 字典数据未更新

解决方案：

vue
<script setup lang="ts">
import { useDictStoreWithOut } from '@/store/modules/dict'

const dictStore = useDictStoreWithOut()

// 重置字典数据
const resetDict = async () => {
  await dictStore.resetDict()
}
</script>

8. 字典数据管理 ​

8.1 字典数据添加 ​

在后台管理系统中添加字典数据：

  1. 进入系统管理 -> 字典管理
  2. 点击新增字典类型
  3. 填写字典类型、字典名称等信息
  4. 添加字典数据

8.2 字典数据修改 ​

在后台管理系统中修改字典数据：

  1. 进入系统管理 -> 字典管理
  2. 选择要修改的字典类型
  3. 修改字典数据

8.3 字典数据删除 ​

在后台管理系统中删除字典数据：

  1. 进入系统管理 -> 字典管理
  2. 选择要删除的字典类型
  3. 删除字典数据

8.4 字典数据刷新 ​

在前端代码中刷新字典数据：

vue
<script setup lang="ts">
import { useDictStoreWithOut } from '@/store/modules/dict'

const dictStore = useDictStoreWithOut()

// 刷新字典数据
const refreshDict = async () => {
  await dictStore.resetDict()
}
</script>

9. 字典数据扩展 ​

9.1 添加新的字典类型 ​

在 @/utils/dict.ts 中添加新的字典类型：

typescript
export enum DICT_TYPE {
  // 现有字典类型
  COMMON_STATUS = 'common_status',

  // 新增字典类型
  CUSTOM_TYPE = 'custom_type',
}

9.2 添加新的字典工具函数 ​

在 @/utils/dict.ts 中添加新的字典工具函数：

typescript
/**
 * 获取自定义类型的字典选项数组
 * @param dictType 数据类型
 * @returns 自定义类型字典选项数组
 */
export const getCustomDictOptions = (dictType: string) => {
  const dictOptions: DictDataType[] = getDictOptions(dictType)
  const dictOption: CustomDictDataType[] = []
  dictOptions.forEach((dict: DictDataType) => {
    dictOption.push({
      ...dict,
      // 自定义处理逻辑
      customField: dict.value + '_custom'
    })
  })
  return dictOption
}

注意：本文档持续更新中，如有问题请及时反馈。