Zs Admin

Appearance

自定义图标技术文档 ​

1. 自定义图标概述 ​

本项目使用 vite-plugin-svg-icons 插件来管理和加载 SVG 图标，并通过自定义组件 zs-icon 来统一使用这些图标。这种方式具有以下优势：

  • 高性能：图标按需加载，减少 HTTP 请求
  • 可定制性：支持颜色、大小等属性自定义
  • 易用性：统一的组件接口，使用方便
  • 可维护性：图标资源集中管理，便于维护

2. 图标配置 ​

2.1 Vite 插件配置 ​

项目使用 vite-plugin-svg-icons 插件来处理 SVG 图标，配置位于 config/vite.config.base.ts 文件中：

typescript
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons';

// 配置 SVG 图标插件
createSvgIconsPlugin({
  // 指定需要缓存的图标文件夹
  iconDirs: [resolve(pathSrc, 'assets/icons')],
  // 指定 symbolId 格式， dir 为图标文件夹名称， name 为图标文件名称, 例如：icon-custom-basic
  symbolId: 'icon-[dir]-[name]',
  // 指定 SVG sprite 注入到 HTML 的位置
  inject: 'body-last',
}),

配置参数说明 ​

参数类型默认值说明
iconDirsstring[]-需要缓存的图标文件夹路径数组
symbolIdstringicon-[dir]-[name]生成的 symbol 元素的 ID 格式
injectstringbody-lastSVG sprite 注入到 HTML 的位置
svgoOptionsobject{}SVGO 配置选项，用于优化 SVG 图标

2.2 图标目录结构 ​

项目中的 SVG 图标按照不同的类型和风格组织在 src/assets/icons 目录下：

src/assets/icons/
├── custom/          # 自定义图标
│   ├── basic.svg        # 基础图标
│   ├── pdf.svg          # PDF 图标
│   ├── send.svg         # 发送图标
│   ├── tenant.svg       # 租户图标
│   └── tenantPackage.svg # 租户套餐图标
├── filled/          # 填充风格图标
└── outlined/        # 轮廓风格图标

3. 图标组件实现 ​

3.1 图标组件定义 ​

项目中定义了一个统一的图标组件 zs-icon，用于使用 SVG 图标。组件位于 src/components/zs-icon/index.vue：

vue
<template>
  <svg
    :class="['svg-icon', $attrs.class]"
    :style="{ width: size + 'px', height: size + 'px' }"
    aria-hidden="true"
  >
    <use :xlink:href="`#${icon}`" :fill="color" />
  </svg>
</template>

<script lang="ts" setup>
  defineProps({
    icon: {
      type: String,
      required: true,
    },
    color: {
      type: String,
      default: 'currentColor',
    },
    size: {
      type: [String, Number],
      default: 16, // 默认大小为 16px
    },
  });
</script>

<style scoped>
  svg-icon {
    vertical-align: middle;
  }
</style>

3.2 组件属性说明 ​

属性类型默认值说明
iconstring-图标名称，对应 symbolId
colorstringcurrentColor图标颜色，支持 CSS 颜色值
size`stringnumber`16

4. 图标使用方法 ​

4.1 全局注册 ​

图标组件已在项目中全局注册，可以直接在模板中使用：

vue
<template>
  <zs-icon icon="icon-custom-basic" />
</template>

4.2 基本使用 ​

vue
<template>
  <!-- 使用默认大小和颜色的图标 -->
  <zs-icon icon="icon-custom-basic" />
  
  <!-- 指定图标的大小 -->
  <zs-icon icon="icon-custom-pdf" :size="24" />
  
  <!-- 指定图标的颜色 -->
  <zs-icon icon="icon-custom-send" color="#165DFF" />
  
  <!-- 同时指定大小和颜色 -->
  <zs-icon icon="icon-custom-tenant" :size="32" color="#722ED1" />
</template>

4.3 在组件中使用 ​

在 Vue 组件中使用图标：

vue
<template>
  <div class="tenant-card">
    <zs-icon icon="icon-custom-tenant" :size="48" color="#165DFF" />
    <h3>租户管理</h3>
    <p>管理系统中的租户信息</p>
  </div>
</template>

<style scoped>
.tenant-card {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 20px;
  border-radius: 8px;
  background-color: #f5f5f5;
}

h3 {
  margin: 16px 0 8px;
  font-size: 18px;
  font-weight: 600;
}

p {
  margin: 0;
  font-size: 14px;
  color: #666;
}
</style>

4.4 在菜单中使用 ​

在系统菜单中使用图标：

vue
<template>
  <a-menu :selected-keys="selectedKeys" mode="inline">
    <a-menu-item key="tenant">
      <template #icon>
        <zs-icon icon="icon-custom-tenant" />
      </template>
      租户管理
    </a-menu-item>
    <a-menu-item key="tenantPackage">
      <template #icon>
        <zs-icon icon="icon-custom-tenantPackage" />
      </template>
      租户套餐
    </a-menu-item>
  </a-menu>
</template>

5. 图标添加与管理 ​

5.1 添加新图标 ​

要添加新的自定义图标，只需按照以下步骤操作：

  1. 准备 SVG 图标文件：确保 SVG 文件符合以下要求

    • 移除不必要的属性和样式
    • 确保图标路径正确
    • 建议使用 24x24 或 48x48 的尺寸

  2. 将 SVG 文件放入指定目录：将准备好的 SVG 文件放入 src/assets/icons/custom/ 目录下

  3. 使用新图标：在组件中使用新图标，图标名称格式为 icon-custom-<文件名>

5.2 图标命名规范 ​

为了便于管理和使用，建议遵循以下命名规范：

  • 使用小写字母
  • 单词之间使用连字符 (-) 分隔
  • 文件名应能清晰反映图标的用途
  • 避免使用过于复杂的名称

5.3 图标优化 ​

为了提高性能，建议对 SVG 图标进行优化：

  • 移除不必要的属性（如 width、height、fill 等）
  • 移除不必要的嵌套元素
  • 合并路径
  • 简化路径

可以使用工具如 SVGO 来自动化优化 SVG 图标。

6. 图标组件原理 ​

6.1 SVG Sprite 技术 ​

项目使用 SVG Sprite 技术来管理和加载图标。SVG Sprite 是一种将多个 SVG 图标合并为一个文件的技术，通过 <symbol> 元素定义每个图标，然后通过 <use> 元素引用。

6.2 工作流程 ​

  1. 构建阶段：vite-plugin-svg-icons 插件扫描指定目录下的 SVG 图标文件
  2. 生成 Sprite：将所有 SVG 图标转换为 <symbol> 元素，合并为一个 SVG Sprite 文件
  3. 注入 HTML：将生成的 SVG Sprite 注入到 HTML 文件的末尾
  4. 使用图标：通过 <use xlink:href="#icon-name" /> 引用需要的图标

6.3 优势 ​

  • 减少 HTTP 请求：所有图标只需要一个 HTTP 请求
  • 按需加载：图标按需渲染，提高性能
  • 可定制性：支持颜色、大小等属性自定义
  • 兼容性好：支持现代浏览器

7. 最佳实践 ​

7.1 图标使用建议 ​

  • 统一图标风格：在同一页面或组件中，使用相同风格的图标
  • 合理设置大小：根据上下文合理设置图标大小，保持视觉一致性
  • 注意颜色搭配：确保图标颜色与背景颜色对比度足够，保证可读性
  • 避免过度使用：不要在页面中过度使用图标，保持界面简洁

7.2 性能优化 ​

  • 只引入必要的图标：避免引入不必要的图标资源
  • 优化 SVG 文件：对 SVG 图标进行优化，减少文件大小
  • 按需加载：对于大型应用，可以考虑按需加载图标

7.3 可访问性 ​

  • 添加适当的 alt 文本：对于重要的图标，添加适当的 alt 文本
  • 使用 aria-hidden：对于装饰性图标，添加 aria-hidden="true" 属性
  • 确保颜色对比度：确保图标颜色与背景颜色对比度符合 WCAG 标准