# menu-icon

**Repository Path**: gaojin-vip/menu-icon

## Basic Information

- **Project Name**: menu-icon
- **Description**: 一个基于 Vue 3 的菜单图标选择器组件库，支持 Ant Design 和 Element Plus 图标
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-09-28
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jin-menu-icon

一个基于 Vue 3 的菜单图标选择器组件库，支持 Ant Design 和 Element Plus 图标（仅图标，不依赖 Element Plus 组件库）。

> **🔄 最新更新**：v1.0.5 优化了图标显示效果，修复了样式冲突问题，统一了图标默认大小为 16px，提升了整体用户体验。已发布到 npm，可直接安装使用。

## ✨ 特性

- 🎨 **双图标库支持** - 同时支持 Ant Design 和 Element Plus 图标（仅图标库，不依赖组件）
- 🔍 **智能搜索** - 支持图标名称搜索，带防抖优化
- 📱 **响应式设计** - 适配各种屏幕尺寸
- 🎯 **TypeScript 支持** - 完整的类型定义
- 🚀 **按需引入** - 支持全局和按需引入
- 🌙 **暗色主题** - 自动适配系统主题
- ⚡ **性能优化** - 图标缓存、懒加载、防抖搜索
- ♿ **无障碍支持** - 完整的键盘导航和 ARIA 属性
- 🎛️ **高度可定制** - 丰富的配置选项
- 📦 **轻量级** - 仅依赖图标库，不依赖 UI 组件库

## 📦 安装

### 从 npm 安装

```bash
# 使用 npm
npm install jin-menu-icon

# 使用 yarn
yarn add jin-menu-icon

# 使用 pnpm
pnpm add jin-menu-icon
```

### 从源码安装

如果您需要最新功能或自定义修改，也可以从源码安装：

```bash
# 克隆项目
git clone https://gitee.com/gaojin-vip/menu-icon.git

# 进入项目目录
cd menu-icon

# 安装依赖
npm install

# 构建组件库
npm run build:lib
```

> **🎉 零配置安装**：所有图标库已内置，无需单独安装任何依赖！不依赖 Element Plus 组件库。

## 🚀 快速开始

### 全局引入

```typescript
import { createApp } from 'vue';
import MenuIconComponents from 'jin-menu-icon';

const app = createApp(App);

// 一键注册所有组件和依赖（样式会自动注入）
app.use(MenuIconComponents);
```

> **✨ 自动配置**：组件会自动注册所有图标，样式也会自动注入，您无需手动安装或注册任何依赖！

### 按需引入

```vue
<template>
  <div>
    <!-- 菜单图标选择器 -->
    <MenuIcon
      v-model="selectedIcon"
      placeholder="请选择图标"
      @get="handleIconSelect"
    />

    <!-- SVG 图标显示 -->
    <SvgIcon :name="selectedIcon" :size="24" color="#409EFF" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
// 组件已全局注册，无需单独引入

const selectedIcon = ref('ele-Pointer');

const handleIconSelect = (icon: string) => {
  console.log('选中的图标:', icon);
};
</script>
```

**按需引入时的依赖注册（在 main.ts 中）：**

```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import MenuIconComponents from 'jin-menu-icon';

const app = createApp(App);

// 注册菜单图标组件（自动处理所有图标和样式）
app.use(MenuIconComponents);

app.mount('#app');
```

> **💡 提示**：样式会自动注入，无需手动引入。如果需要手动控制样式，也可以从组件库中导入样式路径：
>
> ```typescript
> import { stylePath } from 'jin-menu-icon';
> // 然后动态引入样式
> ```

## 🎯 高级用法

### 自定义配置

```vue
<template>
  <MenuIcon
    v-model="selectedIcon"
    :show-search="true"
    :show-tabs="true"
    :max-height="400"
    :search-debounce="300"
    :columns="4"
    :gutter="16"
    placeholder="搜索图标..."
    @get="handleIconSelect"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
// 组件已全局注册，无需单独引入

const selectedIcon = ref('');

const handleIconSelect = (icon: string) => {
  console.log('选中的图标:', icon);
};
</script>
```

### 直接复制源码使用

如果您不想通过 npm 安装，也可以直接复制`src`目录到您的项目中：

```bash
# 复制src目录到您的项目中
cp -r node_modules/jin-menu-icon/src ./src/components/menu-icon
```

然后在您的项目中引入：

```typescript
// main.ts
import { createApp } from 'vue';
import MenuIconComponents from './src/components/menu-icon/main';

const app = createApp(App);
app.use(MenuIconComponents);
```

## 📚 API 文档

### MenuIcon Props

| 参数             | 说明                 | 类型                            | 默认值                           |
| ---------------- | -------------------- | ------------------------------- | -------------------------------- |
| modelValue       | 双向绑定值           | string                          | -                                |
| prepend          | 输入框前置内容       | string                          | 'ele-Pointer'                    |
| placeholder      | 输入框占位文本       | string                          | '请输入内容搜索图标或者选择图标' |
| size             | 输入框大小           | 'small' \| 'default' \| 'large' | 'default'                        |
| disabled         | 是否禁用             | boolean                         | false                            |
| clearable        | 是否可清空           | boolean                         | true                             |
| emptyDescription | 自定义空状态描述文字 | string                          | '无相关图标'                     |
| showSearch       | 是否显示搜索框       | boolean                         | true                             |
| showTabs         | 是否显示标签页       | boolean                         | true                             |
| maxHeight        | 弹窗最大高度         | number                          | 230                              |
| searchDebounce   | 搜索防抖延迟(ms)     | number                          | 300                              |

### MenuIcon Events

| 事件名            | 说明            | 参数            |
| ----------------- | --------------- | --------------- |
| update:modelValue | 更新 modelValue | (value: string) |
| get               | 获取图标        | (value: string) |
| clear             | 清空图标        | (value: string) |

### SvgIcon Props

| 参数        | 说明         | 类型    | 默认值 |
| ----------- | ------------ | ------- | ------ |
| name        | 图标名称     | string  | ''     |
| size        | 图标大小     | number  | 16     |
| color       | 图标颜色     | string  | ''     |
| disabled    | 是否禁用     | boolean | false  |
| customClass | 自定义类名   | string  | ''     |
| loading     | 是否显示加载 | boolean | false  |

## 🏷️ 图标命名规则

- **Element Plus 图标**：`ele-{图标名}`，如 `ele-Pointer`、`ele-Edit`（仅图标，不依赖 Element Plus 组件库）
- **Ant Design 图标**：`ali-{图标名}`，如 `ali-User`、`ali-Setting`

## 🛠️ 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建组件库
npm run build:lib

# 类型检查
npm run type-check

# 预览构建结果
npm run preview

# 发布到 npm
npm publish
```

## 📊 包信息

- **版本**: 1.0.5
- **包大小**: 约 2.0 MB（完全自包含）
- **外部依赖**: 仅需 Vue 3.3.0+
- **内部依赖**: 仅图标库已打包，不依赖 UI 组件库
- **兼容性**: 支持现代浏览器和 Node.js 16+
- **TypeScript**: 完整类型支持
- **代码质量**: 已通过 TypeScript 检查
- **NPM 地址**: https://www.npmjs.com/package/jin-menu-icon

## 📝 更新日志

### v1.0.5 (2024-12-19)

#### ✨ 新特性

- 统一图标默认大小为 16px，提供更一致的用户体验
- 优化了图标选择器中的图标显示效果

#### 🐛 修复

- 修复了 Element Plus 图标不显示的问题（通过区分 Element Plus 和 Ant Design 图标的样式处理）
- 修复了样式冲突问题（将 `el-icon` 类名改为 `menu-icon-svg`，避免与 Element Plus 内置样式冲突）
- 修复了 Ant Design 图标在修复 Element Plus 图标后变大的问题

#### 🔧 改进

- 改进了图标样式处理逻辑，Element Plus 图标使用 `width/height`，Ant Design 图标使用 `font-size`
- 优化了 SCSS 样式，确保图标在不同模式下都能正确显示
- 增强了错误处理机制，添加了图片加载失败的处理

#### 📦 技术改进

- 更新了组件类名，避免与外部库的样式冲突
- 优化了样式计算逻辑，提升渲染性能
- 改进了移动端响应式设计

## 📁 项目结构

```
src/
├── components/                         # 组件文件
│   ├── icon.vue                       # 主图标选择器组件
│   ├── list.vue                       # 图标列表组件
│   └── svgIcon.vue                    # SVG图标显示组件
├── types/                             # TypeScript类型定义
│   └── index.ts                       # 类型定义文件
├── utils/                             # 工具函数
│   └── init.ts                        # 图标初始化和注册
├── theme/                             # 样式文件
│   └── iconSelector.scss              # 组件样式
├── main.ts                            # 主入口文件
└── vue-shim.d.ts                      # Vue类型声明

dist/                                  # 构建输出目录
├── index.mjs                          # 主入口文件
├── assets/                            # 静态资源
│   └── css/                           # 样式文件
│       └── index.[hash].css          # 组件样式
├── components/                        # 组件文件
│   ├── index.[hash].mjs              # 主组件
│   ├── list.[hash].mjs               # 列表组件
│   └── svgIcon.[hash].mjs            # SVG图标组件
└── types/                             # TypeScript类型定义
    └── main.d.ts                      # 主入口类型
```

## 🔧 技术特性

- **构建工具**: Vite 6.0.0
- **模块格式**: ES Module
- **外部依赖**: 仅 Vue 3.3.0+
- **代码分割**: 按组件分离
- **类型支持**: 完整 TypeScript 定义
- **性能优化**: Tree Shaking + 按需加载
- **样式处理**: SCSS + 自动注入
- **图标库**: @element-plus/icons-vue + @ant-design/icons-vue

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接

- [Vue 3](https://vuejs.org/)
- [Element Plus Icons](https://element-plus.org/zh-CN/component/icon.html)
- [Ant Design Vue](https://antdv.com/)
- [TypeScript](https://www.typescriptlang.org/)
- [Vite](https://vitejs.dev/)

## 🚨 故障排除

### Element Plus 图标不显示问题

如果您遇到 Element Plus 图标区域显示空白占位符的问题，请按以下步骤排查：

#### 1. 检查组件注册

确保在 `main.ts` 中正确注册了组件：

```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import MenuIconComponents from 'jin-menu-icon';

const app = createApp(App);

// 确保在创建应用后立即注册
app.use(MenuIconComponents);

app.mount('#app');
```

#### 2. 手动注册图标（如果自动注册失败）

```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import MenuIconComponents, { elSvg, alSvg } from 'jin-menu-icon';

const app = createApp(App);

// 手动注册图标
elSvg(app);
alSvg(app);

// 注册组件
app.use(MenuIconComponents);

app.mount('#app');
```

#### 3. 调试图标注册状态

在组件中添加调试代码：

```vue
<template>
  <MenuIcon v-model="selectedIcon" />
</template>

<script setup>
import { onMounted } from 'vue';
import { getCurrentInstance } from 'vue';

onMounted(() => {
  const instance = getCurrentInstance();
  const app = instance?.appContext?.app;

  if (app) {
    const components = app._context?.components || {};
    const elementIcons = Object.keys(components).filter((key) =>
      key.startsWith('ele-')
    );
    const antIcons = Object.keys(components).filter((key) =>
      key.startsWith('ali-')
    );

    console.log('已注册的 Element Plus 图标:', elementIcons.length);
    console.log('已注册的 Ant Design 图标:', antIcons.length);

    if (elementIcons.length === 0) {
      console.warn('Element Plus 图标未注册！');
    }
    if (antIcons.length === 0) {
      console.warn('Ant Design 图标未注册！');
    }
  }
});
</script>
```

#### 4. 常见错误和解决方案

| 错误信息                                   | 原因                        | 解决方案                                 |
| ------------------------------------------ | --------------------------- | ---------------------------------------- |
| `Unknown custom element: <ele-Setting>`    | Element Plus 图标组件未注册 | 确保调用了 `app.use(MenuIconComponents)` |
| `Cannot read property 'name' of undefined` | 图标库导入失败              | 检查依赖安装，重新安装组件库             |
| 图标显示为空白                             | 组件注册时机不对            | 确保在 Vue 应用创建后立即注册            |

#### 5. 自动修复机制

从 v1.0.4 开始，组件库已内置自动修复机制：

- 组件会在检测到图标未注册时自动重新注册
- 控制台会显示警告信息：`[MenuIcon] 图标未正确注册，正在尝试重新注册...`
- 无需手动干预，组件会自动尝试修复

#### 6. v1.0.5 样式修复

v1.0.5 版本已修复以下问题：

- **Element Plus 图标不显示**：通过区分 Element Plus 和 Ant Design 图标的样式处理方式
- **样式冲突**：将 `el-icon` 类名改为 `menu-icon-svg`，避免与 Element Plus 内置样式冲突
- **图标大小不一致**：统一默认图标大小为 16px

#### 7. 获取帮助

如果问题仍然存在，请：

1. 检查浏览器控制台错误信息
2. 确认 Vue 版本 >= 3.3.0
3. 验证组件注册顺序
4. 提供完整的错误日志

---

## ❓ 常见问题

### Q: 安装时出现依赖冲突怎么办？

A: 使用 `--legacy-peer-deps` 参数：

```bash
npm install jin-menu-icon@1.0.5 --legacy-peer-deps
```

### Q: 组件库包含哪些依赖？

A: 组件库已内置所有图标库，包括：

- @element-plus/icons-vue 2.3.1（仅图标库）
- @ant-design/icons-vue 7.0.1

### Q: 支持哪些图标库？

A: 支持 Element Plus 和 Ant Design 两套图标库，总计 1000+ 图标（仅图标库，不依赖 UI 组件库）。

### Q: TypeScript 类型错误怎么办？

A: 确保项目使用 Vue 3.3.0+ 版本，并正确配置 TypeScript。如果仍有问题，请检查 `tsconfig.json` 配置。

### Q: 图标不显示怎么办？

A: 确保已正确安装并注册了组件库。所有图标库已内置，无需额外安装。

### Q: 样式不生效？

A: 样式会自动注入，无需手动引入。如果样式仍然不生效，请检查：

1. 确保使用的是最新版本
2. 确保组件已正确注册
3. 检查浏览器控制台是否有错误

### Q: 如何自定义样式？

A: 可以通过 CSS 变量或覆盖组件样式来自定义外观。具体请参考样式文件 `iconSelector.scss`。

### Q: 如何获取所有可用图标列表？

A: 可以通过以下方式获取：

```typescript
import { getElementPlusIconfont, getAlicdnIconfont } from 'jin-menu-icon';

// 获取 Element Plus 图标
const eleIcons = await getElementPlusIconfont();

// 获取 Ant Design 图标
const aliIcons = await getAlicdnIconfont();
```

### Q: 如何检查组件库是否正确安装？

A: 可以通过以下方式检查：

```bash
# 检查包是否安装成功
npm list jin-menu-icon

# 检查包信息
npm view jin-menu-icon

# 在代码中测试导入
import MenuIconComponents from 'jin-menu-icon';
console.log('组件库安装成功！');
```

### Q: 支持哪些 Vue 版本？

A: 组件库支持 Vue 3.3.0 及以上版本，推荐使用最新稳定版。

### Q: 如何自定义图标样式？

A: 可以通过 CSS 变量或覆盖组件样式：

```css
/* 自定义主题色 */
.icon-selector {
  --primary-color: #your-color;
}

/* 自定义图标大小 */
.icon-selector .icon-item i {
  font-size: 24px;
}
```

## 🚀 快速体验

想要快速体验组件库？复制以下代码到您的 Vue 项目中：

```vue
<template>
  <div class="demo">
    <h3>图标选择器演示</h3>

    <!-- 基础使用 -->
    <MenuIcon
      v-model="selectedIcon"
      placeholder="请选择图标"
      @get="handleIconSelect"
    />

    <!-- 显示选中的图标 -->
    <div v-if="selectedIcon" class="selected-icon">
      <p>选中的图标：</p>
      <SvgIcon :name="selectedIcon" :size="32" color="#409EFF" />
      <code>{{ selectedIcon }}</code>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import MenuIconComponents from 'jin-menu-icon';

// 注册组件（如果使用全局注册可省略）
const { MenuIcon, SvgIcon } = MenuIconComponents;

const selectedIcon = ref('ele-Pointer');

const handleIconSelect = (icon) => {
  console.log('选中图标:', icon);
};
</script>

<style scoped>
.demo {
  padding: 20px;
  max-width: 600px;
  margin: 0 auto;
}

.selected-icon {
  margin-top: 20px;
  padding: 15px;
  border: 1px solid #e4e7ed;
  border-radius: 6px;
  background: #f5f7fa;
}

.selected-icon code {
  display: block;
  margin-top: 10px;
  padding: 5px 10px;
  background: #fff;
  border-radius: 4px;
  font-family: monospace;
}
</style>
```

---

**🎉 现在就开始使用 MenuIcon 组件库，享受零配置的图标选择体验！**