# ldesign-dict

**Repository Path**: ldesign-v1/ldesign-dict

## Basic Information

- **Project Name**: ldesign-dict
- **Description**: LDesign ?????? - Data dictionary management
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/dict

数据字典管理库，支持静态注册、远程加载、TTL 缓存、并发去重和响应式 Vue 3 集成。

## 功能特性

- **统一字典管理** — 通过字典编码（code）统一管理各类数据字典
- **多数据源** — 支持静态配置和远程加载两种数据源
- **TTL 缓存** — 可配置缓存过期时间，默认 5 分钟
- **并发去重** — 同一编码的并发请求自动合并
- **UI 组件** — 提供下拉选择框、单选框、复选框组件
- **Vue 3 集成** — useDict、useDictLabel 响应式 composable
- **事件系统** — 监听注册、加载、缓存过期等事件

## 安装

```bash
npm install @ldesign/dict
```

## 快速开始

### 核心库使用

```typescript
import { DictManager, DictSelect, DictRadio, DictCheckbox } from '@ldesign/dict-core'

// 创建字典管理器
const manager = new DictManager({
  fetcher: async (code) => {
    const res = await fetch(`/api/dict/${code}`)
    return res.json()
  },
  cacheTTL: 10 * 60 * 1000, // 10 分钟
  dicts: [
    {
      code: 'gender',
      items: [
        { value: 1, label: '男' },
        { value: 2, label: '女' },
      ],
    },
    {
      code: 'status',
      items: [
        { value: 'active', label: '启用' },
        { value: 'inactive', label: '禁用' },
      ],
      cacheTTL: 60000, // 单独配置 1 分钟
    },
  ],
})

// 获取字典（优先缓存，否则远程加载）
const genderItems = await manager.get('gender')
// [{ value: 1, label: '男' }, { value: 2, label: '女' }]

// 同步获取（仅缓存命中时返回）
const cached = manager.getSync('gender') // readonly

// 根据 value 查找 label
manager.getLabel('gender', 1) // '男'

// 根据 value 获取完整字典项
manager.getItem('gender', 1) // { value: 1, label: '男' }

// 检查字典是否存在
manager.has('gender') // true

// 获取所有字典编码
manager.getCodes() // ['gender', 'status']

// 强制刷新（清除缓存并重新加载）
const fresh = await manager.refresh('gender')

// 清除缓存
manager.clearCache('gender') // 清除单个
manager.clearCache()          // 清除全部

// 设置远程获取函数
manager.setFetcher(async (code) => {
  const res = await fetch(`/api/v2/dict/${code}`)
  return res.json()
})

// 事件监听
manager.on('register', (config) => console.log('注册:', config.code))
manager.on('loaded', (code, items) => console.log('加载:', code, items.length))
manager.on('cacheExpire', (code) => console.log('过期:', code))
manager.on('error', (err) => console.error('错误:', err))
```

### UI 组件

```typescript
import { DictSelect, DictRadio, DictCheckbox } from '@ldesign/dict-core'

// 下拉选择框
const select = new DictSelect({
  container: '#select-container',
  code: 'gender',
  placeholder: '请选择性别',
  clearable: true,
  onChange: (value, item) => {
    console.log('选择:', value, item?.label)
  },
})
select.setItems(await manager.get('gender'))
select.setValue(1)
select.getValue() // 1
select.destroy()

// 单选框
const radio = new DictRadio({
  container: '#radio-container',
  code: 'status',
  value: 'active',
  onChange: (value, item) => console.log(value, item),
})
radio.setItems(statusItems)

// 复选框
const checkbox = new DictCheckbox({
  container: '#checkbox-container',
  code: 'permissions',
  value: ['read', 'write'],
  onChange: (values, items) => console.log(values, items),
})
checkbox.setItems(permissionsItems)
checkbox.getValue() // ['read', 'write']
```

### Vue 3 使用

```vue
<script setup>
import { useDict, useDictLabel } from '@ldesign/dict-vue'
import { ref } from 'vue'

// 获取字典列表
const { items, loading, error, refresh } = useDict('gender')

// 响应式字典编码
const dictCode = ref('gender')
const { items: dynamicItems } = useDict(dictCode)
// dictCode 变化时自动重新加载

// 根据 value 获取 label
const selectedValue = ref(1)
const label = useDictLabel('gender', selectedValue)
// label 自动更新为 '男' 或 '女'
</script>

<template>
  <div>
    <div v-if="loading">加载中...</div>
    <div v-else-if="error">错误: {{ error.message }}</div>
    <select v-else v-model="selectedValue">
      <option v-for="item in items" :key="item.value" :value="item.value">
        {{ item.label }}
      </option>
    </select>
    <p>当前选择: {{ label }}</p>
    <button @click="refresh">刷新</button>
  </div>
</template>
```

### Vue 插件

```typescript
import { createDictPlugin } from '@ldesign/dict-vue'

app.use(createDictPlugin({
  fetcher: async (code) => {
    const res = await fetch(`/api/dict/${code}`)
    return res.json()
  },
  cacheTTL: 10 * 60 * 1000,
  dicts: [
    {
      code: 'gender',
      items: [
        { value: 1, label: '男' },
        { value: 2, label: '女' },
      ],
    },
  ],
}))
```

## API 文档

### DictManager

| 方法 | 说明 |
|------|------|
| `register(config)` | 注册静态字典 |
| `get(code)` | 获取字典项（异步，优先缓存否则远程加载） |
| `getSync(code)` | 同步获取（仅缓存命中时返回，冻结副本） |
| `getLabel(code, value)` | 根据 value 查找 label |
| `getItem(code, value)` | 根据 value 获取完整字典项 |
| `has(code)` | 检查字典是否存在 |
| `getCodes()` | 获取所有已注册的字典编码 |
| `refresh(code)` | 强制刷新（清除缓存并重新加载） |
| `clearCache(code?)` | 清除缓存 |
| `setFetcher(fetcher)` | 设置远程获取函数 |
| `on(event, listener)` | 添加事件监听器 |
| `off(event, listener)` | 移除事件监听器 |

### DictItem

```typescript
interface DictItem<V = string | number> {
  value: V               // 字典值
  label: string          // 显示标签
  disabled?: boolean     // 是否禁用
  sort?: number          // 排序权重
  extra?: Record<string, unknown> // 附加数据
  children?: DictItem<V>[] // 子级（树形字典）
}
```

## License

MIT