@fish-render/icons/README.md

Fish Render icon library for Vue 3

# @fish-render/icons

一个现代化的 Vue 3 图标库，提供内置图标组件和动态 SVG 加载功能。

## ✨ 特性

- 🎯 **零配置**：内置图标组件，无需任何配置即可使用
- 🚀 **高性能**：SVG 图标直接内联，无额外网络请求
- 🎨 **CSS 控制**：通过 `font-size` 控制图标大小，通过 `color` 控制颜色
- 📦 **动态加载**：支持从静态文件和 assets 目录动态加载 SVG
- 🔧 **TypeScript**：完整的 TypeScript 支持
- 📱 **响应式**：支持各种尺寸和颜色配置
- 🛠️ **插件支持**：SvgIcon 组件支持 vite-plugin-svg-icons

## 📦 安装

```bash
npm install @fish-render/icons
# 或
yarn add @fish-render/icons
# 或
pnpm add @fish-render/icons
```

## 🚀 快速开始

### 内置图标组件

```vue
<template>
  <div>
    <!-- 直接使用内置图标组件 -->
    <Add />
    <Search />
    <Refresh />
    <Trash />
    <More />
  </div>
</template>

<script setup>
import { Add, Search, Refresh, Trash, More } from '@fish-render/icons'
</script>

<style>
/* 通过 CSS 控制图标大小和颜色 */
.icon-large {
  font-size: 32px;
}
.icon-small {
  font-size: 16px;
}
.icon-white {
  color: white;
}
.icon-red {
  color: #f44336;
}
</style>
```

### PathIcon 组件 - 动态加载静态资源

用于从静态目录动态加载 SVG 文件的组件。

```vue
<template>
  <div>
    <!-- 从静态文件加载 -->
    <PathIcon name="external" />

    <!-- 从 assets 目录加载 -->
    <PathIcon name="user" />
  </div>
</template>

<script setup>
import { PathIcon, setIconConfig } from '@fish-render/icons'

// 配置默认路径
setIconConfig({
  path: '/icons/',
  prefix: '',
})
</script>
```

### SvgIcon 组件 - 配合 vite-plugin-svg-icons

**注意：SvgIcon 组件需要配合 `vite-plugin-svg-icons` 和 `virtual:svg-icons-register` 使用。**

#### 1. 安装依赖

```bash
npm install vite-plugin-svg-icons -D
# 或
yarn add vite-plugin-svg-icons -D
# 或
pnpm add vite-plugin-svg-icons -D
```

#### 2. 配置 Vite

```typescript
// vite.config.ts
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'

export default defineConfig({
  plugins: [
    createSvgIconsPlugin({
      iconDirs: [path.resolve(process.cwd(), 'src/icons')],
      symbolId: 'icon-[dir]-[name]',
    }),
  ],
})
```

#### 3. 在 main.ts 中注册

```typescript
// main.ts
import 'virtual:svg-icons-register'
```

#### 4. 使用 SvgIcon 组件

```vue
<template>
  <div>
    <!-- 使用 SvgIcon 组件 -->
    <SvgIcon name="user" />
    <SvgIcon name="settings" color="#1890ff" />
    <SvgIcon name="heart" prefix="custom" />
  </div>
</template>

<script setup>
import { SvgIcon } from '@fish-render/icons'
</script>

<style>
/* 通过 CSS 控制图标大小 */
.svg-icon {
  font-size: 24px;
}
</style>
```

## 📚 API 文档

### 内置图标组件

所有内置图标组件都支持以下特性：

- **无 props**：无需传递任何属性
- **CSS 控制**：通过 `font-size` 控制大小，通过 `color` 控制颜色
- **响应式**：支持各种尺寸和颜色配置

#### 可用图标

```javascript
import {
  Add,
  Search,
  Refresh,
  Trash,
  More,
  Left,
  Right,
  Up,
  Under,
  Selected,
  DeleteIcon,
  Fillin,
  InformationAdd,
  More1,
} from '@fish-render/icons'
```

#### 使用示例

```vue
<template>
  <!-- 基本使用 -->
  <Add />

  <!-- 通过 CSS 类控制大小和颜色 -->
  <Add class="icon-large icon-red" />

  <!-- 通过内联样式控制 -->
  <Add style="font-size: 24px; color: blue;" />
</template>

<script setup>
import { Add } from '@fish-render/icons'
</script>

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

### PathIcon 组件

用于动态加载外部 SVG 文件的组件。

#### Props

| 属性   | 类型     | 默认值 | 说明                     |
| ------ | -------- | ------ | ------------------------ |
| `name` | `string` | -      | SVG 文件名（不含扩展名） |

#### 使用示例

```vue
<template>
  <!-- 使用配置的默认路径 -->
  <PathIcon name="user" />

  <!-- 从 assets 目录加载 -->
  <PathIcon name="settings" />
</template>

<script setup>
import { PathIcon, setIconConfig } from '@fish-render/icons'

// 设置默认配置
setIconConfig({
  path: '/icons/',
  prefix: '',
})
</script>
```

### SvgIcon 组件

**需要配合 vite-plugin-svg-icons 使用**

#### Props

| 属性     | 类型     | 默认值   | 说明                           |
| -------- | -------- | -------- | ------------------------------ |
| `name`   | `string` | -        | 图标名称（对应 SVG 文件名）    |
| `color`  | `string` | -        | 图标颜色                       |
| `prefix` | `string` | `'icon'` | 图标前缀（对应 symbolId 前缀） |

#### 使用示例

```vue
<template>
  <!-- 基本使用 -->
  <SvgIcon name="user" />

  <!-- 自定义颜色 -->
  <SvgIcon name="heart" color="#ff4d4f" />

  <!-- 自定义前缀 -->
  <SvgIcon name="logo" prefix="custom" />

  <!-- 通过 CSS 控制大小 -->
  <SvgIcon name="settings" class="icon-large" />
</template>

<script setup>
import { SvgIcon } from '@fish-render/icons'
</script>

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

### 配置函数

#### setIconConfig(config)

设置全局图标配置（仅对 PathIcon 有效）。

```javascript
import { setIconConfig } from '@fish-render/icons'

setIconConfig({
  path: '/public/icons/', // 静态文件路径
  prefix: 'icon-', // 文件名前缀
})
```

#### getIconConfig()

获取当前图标配置。

```javascript
import { getIconConfig } from '@fish-render/icons'

const config = getIconConfig()
console.log(config)
// { path: '/public/icons/', prefix: '' }
```

## 🎨 样式指南

### 图标大小控制

```css
/* 通过 font-size 控制图标大小 */
.icon-16 {
  font-size: 16px;
}
.icon-24 {
  font-size: 24px;
}
.icon-32 {
  font-size: 32px;
}
.icon-48 {
  font-size: 48px;
}
.icon-64 {
  font-size: 64px;
}
```

### 图标颜色控制

```css
/* 通过 color 控制图标颜色 */
.icon-white {
  color: white;
}
.icon-black {
  color: black;
}
.icon-red {
  color: #f44336;
}
.icon-blue {
  color: #2196f3;
}
.icon-green {
  color: #4caf50;
}
```

### 图标对齐

```css
/* 图标垂直对齐 */
.icon-component {
  vertical-align: middle;
}
```

## 📁 目录结构

### PathIcon 使用时的目录结构

```
your-project/
├── public/
│   └── icons/              # 静态 SVG 图标
│       ├── user.svg
│       ├── logo.svg
│       └── settings.svg
└── src/
    └── components/
        └── MyComponent.vue
```

### SvgIcon 使用时的目录结构

```
your-project/
├── src/
│   ├── icons/              # SVG 图标目录（由 vite-plugin-svg-icons 处理）
│   │   ├── user.svg
│   │   ├── settings.svg
│   │   └── heart.svg
│   ├── main.ts             # 需要导入 'virtual:svg-icons-register'
│   └── components/
│       └── MyComponent.vue
└── vite.config.ts          # 需要配置 vite-plugin-svg-icons
```

## 🔧 开发指南

### 添加新图标

1. 将 SVG 文件放入 `packages/icons/src/icons/` 目录
2. 运行生成命令：

```bash
pnpm generate
```

3. 重新构建包：

```bash
pnpm build:icons
```

### 自定义构建

```bash
# 生成图标组件
pnpm generate

# 构建图标包
pnpm build:icons

# 发布图标包
pnpm publish:icons
```

## 🚨 注意事项

1. **SVG 格式**：确保 SVG 文件格式正确，包含 `viewBox` 属性
2. **文件命名**：使用 kebab-case 命名 SVG 文件
3. **路径配置**：确保图标路径正确配置
4. **错误处理**：为缺失的图标提供备用方案
5. **SvgIcon 依赖**：SvgIcon 组件必须配合 `vite-plugin-svg-icons` 使用
6. **插件注册**：使用 SvgIcon 时必须在 main.ts 中导入 `'virtual:svg-icons-register'`

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## �� 许可证

MIT License