# @cimom/vben-core-icons

该包提供了 Vue Vben Admin 项目的核心图标系统，集成了 Iconify 和 Lucide 图标库，并提供了便捷的图标创建和使用工具。它是整个项目图标系统的基础，确保了图标使用的一致性和可扩展性。

## 安装

```bash
pnpm add @cimom/vben-core-icons
```

## 基本使用

### 使用 Iconify 图标

```vue
<template>
  <div>
    <!-- 直接使用 IconifyIcon 组件 -->
    <IconifyIcon icon="mdi:home" />

    <!-- 带样式的图标 -->
    <IconifyIcon
      icon="mdi:account"
      :style="{ color: 'blue', fontSize: '24px' }"
    />
  </div>
</template>

<script setup lang="ts">
import { IconifyIcon } from '@cimom/vben-core-icons';
</script>
```

### 使用 Lucide 图标

```vue
<template>
  <div>
    <!-- 使用 Lucide 图标 -->
    <Menu />
    <Bell />
    <CircleAlert />

    <!-- 带属性的 Lucide 图标 -->
    <Info size="24" color="blue" />
  </div>
</template>

<script setup lang="ts">
import { Menu, Bell, CircleAlert, Info } from '@cimom/vben-core-icons';
</script>
```

### 创建自定义图标组件

```vue
<template>
  <div>
    <HomeIcon />
    <SettingsIcon />
  </div>
</template>

<script setup lang="ts">
import { createIconifyIcon } from '@cimom/vben-core-icons';

// 创建自定义图标组件
const HomeIcon = createIconifyIcon('mdi:home');
const SettingsIcon = createIconifyIcon('mdi:cog');
</script>
```

## API 参考

### IconifyIcon 组件

基于 `@iconify/vue` 的 `Icon` 组件，用于显示 Iconify 图标。

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `icon` | `string \| IconifyIconStructure` | - | 图标名称或图标数据对象 |
| `width` | `string \| number` | `1em` | 图标宽度 |
| `height` | `string \| number` | `1em` | 图标高度 |
| `color` | `string` | - | 图标颜色 |
| `flip` | `'horizontal' \| 'vertical' \| 'horizontal,vertical'` | - | 图标翻转方向 |
| `rotate` | `number \| string` | - | 图标旋转角度 |
| `inline` | `boolean` | `false` | 是否为内联图标 |

### Lucide 图标组件

从 `lucide-vue-next` 导出的图标组件，可以直接使用。

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `size` | `string \| number` | `24` | 图标大小 |
| `color` | `string` | `currentColor` | 图标颜色 |
| `strokeWidth` | `string \| number` | `2` | 线条宽度 |
| `absoluteStrokeWidth` | `boolean` | `false` | 是否使用绝对线条宽度 |

### 工具函数

#### createIconifyIcon

创建基于 Iconify 的图标组件。

```ts
function createIconifyIcon(icon: string): Component;
```

#### addIcon

添加自定义图标到 Iconify 库。

```ts
function addIcon(name: string, data: IconifyIconStructure): boolean;
```

#### addCollection

添加图标集合到 Iconify 库。

```ts
function addCollection(data: IconifyJSON, prefix?: string): boolean;
```

#### listIcons

列出已加载的图标。

```ts
function listIcons(provider?: string, prefix?: string): string[];
```

## 可用的 Lucide 图标

该包导出了以下 Lucide 图标组件：

- `ArrowDown` - 向下箭头
- `ArrowLeft` - 向左箭头
- `ArrowLeftToLine` - 向左到线箭头
- `ArrowRightLeft` - 左右箭头
- `ArrowRightToLine` - 向右到线箭头
- `ArrowUp` - 向上箭头
- `ArrowUpToLine` - 向上到线箭头
- `Bell` - 铃铛
- `BookOpenText` - 打开的书
- `Check` - 勾选
- `ChevronDown` - 向下箭头（细）
- `ChevronLeft` - 向左箭头（细）
- `ChevronRight` - 向右箭头（细）
- `ChevronsLeft` - 双向左箭头
- `ChevronsRight` - 双向右箭头
- `Circle` - 圆形
- `CircleAlert` - 警告圆形
- `CircleCheckBig` - 大勾选圆形
- `CircleHelp` - 帮助圆形
- `CircleX` - 关闭圆形
- `Copy` - 复制
- `CornerDownLeft` - 左下角
- `Ellipsis` - 省略号
- `Expand` - 展开
- `ExternalLink` - 外部链接
- `Eye` - 眼睛（显示）
- `EyeOff` - 闭眼（隐藏）
- `FoldHorizontal` - 水平折叠
- `Fullscreen` - 全屏
- `Github` - GitHub 图标
- `Grip` - 抓取
- `GripVertical` - 垂直抓取
- `IconDefault` - 默认图标
- `Info` - 信息
- `InspectionPanel` - 检查面板
- `Languages` - 语言
- `LoaderCircle` - 加载圆圈
- `LockKeyhole` - 锁
- `LogOut` - 登出
- `MailCheck` - 邮件检查
- `Maximize` - 最大化
- `MdiMenuClose` - 菜单关闭
- `MdiMenuOpen` - 菜单打开
- `Menu` - 菜单
- `Minimize` - 最小化
- `Minimize2` - 最小化（另一种）
- `MoonStar` - 月亮星星（暗色模式）
- `Palette` - 调色板
- `PanelLeft` - 左侧面板
- `PanelRight` - 右侧面板
- `Pencil` - 铅笔（编辑）
- `Plus` - 加号
- `RefreshCcw` - 刷新
- `Save` - 保存
- `Search` - 搜索
- `Settings` - 设置
- `Slash` - 斜杠
- `SlidersHorizontal` - 水平滑块
- `Sun` - 太阳（亮色模式）
- `Trash` - 垃圾桶（删除）
- `User` - 用户
- `X` - 关闭

## 高级用法

### 动态加载图标

```ts
import { addIcon, IconifyIcon } from '@cimom/vben-core-icons';
import { ref } from 'vue';

// 动态加载图标
const iconName = 'custom:my-icon';
const iconLoaded = ref(false);

// 添加自定义图标
addIcon(iconName, {
  body: '<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8zm-1-13h2v6h-2zm0 8h2v2h-2z"/>',
  width: 24,
  height: 24,
});

iconLoaded.value = true;
```

### 创建图标选择器组件

```vue
<template>
  <div class="icon-selector">
    <div class="icon-selector__search">
      <input v-model="searchText" placeholder="搜索图标..." />
    </div>
    <div class="icon-selector__list">
      <div
        v-for="icon in filteredIcons"
        :key="icon"
        class="icon-selector__item"
        @click="selectIcon(icon)"
      >
        <IconifyIcon :icon="icon" />
        <span>{{ icon }}</span>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue';
import { IconifyIcon, listIcons } from '@cimom/vben-core-icons';

const props = defineProps({
  value: {
    type: String,
    default: '',
  },
});

const emit = defineEmits(['update:value', 'select']);

const searchText = ref('');

// 获取所有可用图标
const allIcons = listIcons();

// 过滤图标
const filteredIcons = computed(() => {
  if (!searchText.value) {
    return allIcons;
  }
  return allIcons.filter((icon) =>
    icon.toLowerCase().includes(searchText.value.toLowerCase()),
  );
});

// 选择图标
function selectIcon(icon: string) {
  emit('update:value', icon);
  emit('select', icon);
}
</script>

<style scoped>
.icon-selector {
  width: 100%;
  border: 1px solid #e8e8e8;
  border-radius: 4px;
}

.icon-selector__search {
  padding: 8px;
  border-bottom: 1px solid #e8e8e8;
}

.icon-selector__search input {
  width: 100%;
  padding: 8px;
  border: 1px solid #d9d9d9;
  border-radius: 4px;
}

.icon-selector__list {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(80px, 1fr));
  gap: 8px;
  padding: 8px;
  max-height: 300px;
  overflow-y: auto;
}

.icon-selector__item {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 8px;
  border: 1px solid #e8e8e8;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s;
}

.icon-selector__item:hover {
  border-color: #1890ff;
  color: #1890ff;
}

.icon-selector__item span {
  margin-top: 4px;
  font-size: 12px;
  text-overflow: ellipsis;
  overflow: hidden;
  white-space: nowrap;
  width: 100%;
  text-align: center;
}
</style>
```

### 图标与主题集成

```vue
<template>
  <div>
    <ThemeIcon />
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { Sun, MoonStar } from '@cimom/vben-core-icons';
import { usePreferences } from '@cimom/vben-preferences';

const { preferences, updatePreferences } = usePreferences();

// 根据当前主题动态显示图标
const ThemeIcon = computed(() => {
  return preferences.theme === 'dark' ? Sun : MoonStar;
});

// 切换主题
function toggleTheme() {
  updatePreferences({
    theme: preferences.theme === 'dark' ? 'light' : 'dark',
  });
}
</script>
```

## 与其他包的关系

- **@cimom/vben-icons**: 基于此包构建，提供了更高级别的图标封装和组织。
- **@cimom/vben-core-ui-kit**: 使用此包的图标系统构建 UI 组件。
- **@cimom/vben-preferences**: 可以通过偏好设置来动态切换图标主题。

## 注意事项

1. 该包主要提供图标系统的基础，不包含具体的图标组织和分类。
2. 使用 Iconify 图标时，需要确保图标名称正确，否则将无法显示。
3. 为了优化性能，建议只导入需要使用的 Lucide 图标，而不是全部导入。

## 常见问题

### 图标不显示

确保图标名称正确，并且已经正确安装和导入了相关依赖：

```ts
// 检查图标是否存在
import { listIcons } from '@cimom/vben-core-icons';

const allIcons = listIcons();
console.log('可用图标:', allIcons);
```

### 自定义图标

如果需要使用自定义 SVG 图标，可以通过 `addIcon` 函数添加：

```ts
import { addIcon, IconifyIcon } from '@cimom/vben-core-icons';

// 添加自定义图标
addIcon('custom:logo', {
  body: '<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>',
  width: 24,
  height: 24
});

// 使用自定义图标
<IconifyIcon icon="custom:logo" />
```

### 图标大小和颜色

Iconify 和 Lucide 图标的大小和颜色可以通过属性或 CSS 设置：

```vue
<template>
  <!-- 通过属性设置 -->
  <IconifyIcon icon="mdi:home" width="32" height="32" color="red" />

  <!-- 通过 CSS 设置 -->
  <IconifyIcon icon="mdi:home" class="custom-icon" />

  <!-- Lucide 图标 -->
  <Menu size="32" color="blue" stroke-width="1.5" />
</template>

<style>
.custom-icon {
  font-size: 32px;
  color: red;
}
</style>
```