平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Vue3中设计一套好用的Icon和IconPicker组件完整代码示例”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

目录

• 先明确目标
• 第一步：用字符串协议统一图标来源
• Icon 组件：只负责渲染，不负责选择
• 渲染 Ant Design 图标
• 渲染本地 SVG Symbol
• 渲染 Iconify 图标
• IconPicker 组件：负责选择，不负责解释渲染
• 选择器的整体结构
• 离线图标集合加载
• 本地 SVG 自动发现
• 分类、搜索与分页
• 在线搜索：防抖、缓存和取消请求
• 交互细节：选择器要像表单组件一样工作
• 兼容手动输入
• 打开时自动定位分类
• 图标来源要可视化
• 网格不要一次渲染太多
• 菜单系统里的图标解析
• 组件设计里的几个取舍
• 为什么不直接传组件？
• 为什么 Icon 和 IconPicker 要拆开？
• 为什么离线和在线都要兼容？
• 最后采用效果
• 总结

在后台管理系统里，图标是一个很容易被低估的基础能力。

最开始我们可能只是在菜单里写几个 Ant Design 图标：

<HomeOutlined />
<SettingOutlined />

从实现思路看，但随着项目复杂度上来，问题会很快出现：菜单图标来自后端设置怎么办？本地 SVG 怎么接入？Iconify 这类海量图标库怎么用？权限菜单里需一个图标选择器怎么办？离线场景和在线搜索如何兼顾？

理解这一步时，这篇文章结合一个 Vue3 + TypeScript + Ant Design Vue 管理后台项目的实现，聊聊如何设计一套工程上更可维护的 Icon 和 IconPicker 组件。

文章不会只堆代码，而是重点讲组件边界、数据协议、加载策略和交互设计。

先明确目标

一个通用图标体系至少要解决这几个问题：

1. 统一渲染入口：业务侧不关心图标来源，只传一个图标值。
2. 兼容多种来源：Ant Design 图标、本地 SVG、Iconify、本地离线图标包、在线搜索结果。
3. 兼容后端设置：菜单、权限、页面设置里图标通常是字符串，而不是 Vue 组件。
4. 按需加载：不能为了一个图标选择器，把几万枚图标全部打进首屏。
5. 选择器可用：兼容搜索、分类、分页、预览、选中态和手动输入。
6. 接口轻松稳定：业务组件最好只面对 icon: string 这一种模型。

所以核心思路是：先设计一套字符串协议，再让 Icon 和 IconPicker 围绕这套协议协作。

第一步：用字符串协议统一图标来源

图标体系的关键不是先写组件，而是先统一图标值的表达方式。

能够约定如下所示协议：

type IconValue =
  | `antdv-next:${string}`
  | `antd:${string}`
  | `svg:${string}`
  | `ri:${string}`
  | `mdi:${string}`
  | `ion:${string}`
  | string;

比如：

const icons = [
  'antdv-next:HomeOutlined',
  'svg:icon-demo-orbit',
  'ri:home-line',
  'mdi:account-circle-outline',
  'ion:planet-outline',
];

这样做有几个好处：

1. 字符串能够直接存数据库，适合菜单、权限、页面设置。
2. 前缀就是图标来源，不需额外维护复杂对象。
3. Icon 能够根据前缀自动判断渲染方式。
4. IconPicker 选出来的值能够原样交给 Icon 渲染。

也就是说，IconPicker 的产物就是 Icon 的入参，这两个组件天然闭环。

Icon 组件：只负责渲染，不负责选择

Icon 组件应该尽量小，它只解决一个问题：给我一个字符串，我把它渲染出来。

建议的 Props 设计如下所示：

interface IconProps {
  icon: string;
  kind?: 'iconify' | 'antdv-next' | 'antdvNext' | 'antd' | 'svg';
  size?: number | string;
  style?: StyleValue;
}

这里有两个设计点：

1. 默认借助 icon 前缀自动识别类型。
2. 保留 kind 作为兜底，让调用方在特殊情况下强制指定类型。

组件内部能够先做一次类型归一化：

type NormalizedIconKind = 'iconify' | 'antdv-next' | 'svg';
type IconKind = NormalizedIconKind | 'antdvNext' | 'antd';

function normalizeKind(kind?: IconKind): NormalizedIconKind | undefined {
  if (!kind) return undefined;
  if (kind === 'antdvNext' || kind === 'antd') return 'antdv-next';
  return kind;
}

随后根据 icon 计算最后类型：

const iconText = computed(() => props.icon.trim());

const resolvedKind = computed<NormalizedIconKind>(() => {
  const forcedKind = normalizeKind(props.kind);
  if (forcedKind) return forcedKind;

  if (iconText.value.startsWith('antdv-next:') || iconText.value.startsWith('antd:')) {
    return 'antdv-next';
  }

  if (iconText.value.startsWith('svg:')) {
    return 'svg';
  }

  return 'iconify';
});

这个设计让调用方能够很轻量：

<IconView icon="antdv-next:HomeOutlined" :size="18" />
<IconView icon="svg:icon-demo-orbit" :size="18" />
<IconView icon="ri:home-line" :size="18" />

渲染 Ant Design 图标

落到代码里，Ant Design 图标本质上是 Vue 组件，能够借助动态导入拿到：

const antdvKey = computed(() => {
  return iconText.value
    .replace(/^antdv-next:/, '')
    .replace(/^antd:/, '');
});

const antdvComp = shallowRef<Component>();

watch([resolvedKind, antdvKey], async ([kind, key]) => {
  if (kind !== 'antdv-next') {
    antdvComp.value = undefined;
    return;
  }

  const icons = await import('@antdv-next/icons');
  antdvComp.value = icons[key] || icons.QuestionOutlined;
}, { immediate: true });

模板中直接采用动态组件：

<component
  :is="antdvComp"
  v-if="resolvedKind === 'antdv-next'"
  class="app-icon"
  :
/>

这里采用 shallowRef 是合理的，因为图标组件本身不需深层响应式代理。

渲染本地 SVG Symbol

本地 SVG 建议走 symbol 模式：

<svg
  v-else-if="resolvedKind === 'svg'"
  class="app-icon app-icon-svg"
  :
  aria-hidden="true"
>
  <use :href="`#${svgId}`" rel="external nofollow"  />
</svg>

对应的图标值是：

svg:icon-demo-orbit

组件内部只需去掉 svg: 前缀：

const svgId = computed(() => iconText.value.replace(/^svg:/, ''));

这种方式的优点是：

1. SVG 能够跟随 currentColor，自然继承文字颜色。
2. 渲染成本低。
3. 与设计系统里的自定义图标兼容性好。

渲染 Iconify 图标

落到代码里，Iconify 的优势是图标库巨大，同时且天然兼容 prefix:name 格式，比如：

ri:home-line
mdi:account-circle-outline
ion:planet-outline

Icon 组件中能够直接采用 @iconify/vue：

<IconifyIcon
  v-else-if="canRenderIconify"
  class="app-icon"
  :icon="iconifyIcon"
  :
/>

若项目希望兼容离线图标包，能够把常用集合单独安装下来，比如：

import { addCollection } from '@iconify/vue';

export type LocalIconifyPrefix = 'ri' | 'mdi' | 'ion';

const localPrefixes = new Set<string>(['ri', 'mdi', 'ion']);
const localIconifyLoadPromises = new Map<LocalIconifyPrefix, Promise<IconsJson>>();

export function isLocalIconifyPrefix(prefix: string): prefix is LocalIconifyPrefix {
  return localPrefixes.has(prefix);
}

export function loadLocalIconifySet(prefix: LocalIconifyPrefix) {
  const cached = localIconifyLoadPromises.get(prefix);
  if (cached) return cached;

  const promise = (async () => {
    let module: unknown;

    if (prefix === 'ri') {
      module = await import('@iconify-json/ri/icons.json');
    } else if (prefix === 'mdi') {
      module = await import('@iconify-json/mdi/icons.json');
    } else {
      module = await import('@iconify-json/ion/icons.json');
    }

    const iconsJson = resolveIconsJson(module);
    addCollection(iconsJson as Parameters<typeof addCollection>[0]);
    return iconsJson;
  })();

  localIconifyLoadPromises.set(prefix, promise);
  return promise;
}

这段代码里有一个很重要的点：用 Map 缓存加载 Promise，而不是缓存结果。

这样即使多个图标同时触发同一个图标包加载，也只会发起一次动态导入。

Icon 中再根据前缀决定是否加载本地集合：

const iconifyPrefix = computed(() => {
  const [prefix] = iconifyIcon.value.split(':');
  return prefix || '';
});

const localIconifyReady = ref(true);

watch([resolvedKind, iconifyPrefix], async ([kind, prefix]) => {
  if (kind !== 'iconify' || !isLocalIconifyPrefix(prefix)) {
    localIconifyReady.value = true;
    return;
  }

  localIconifyReady.value = false;
  await loadLocalIconifySet(prefix);

  if (resolvedKind.value === 'iconify' && iconifyPrefix.value === prefix) {
    localIconifyReady.value = true;
  }
}, { immediate: true });

这能够避免图标包尚未注册时就立刻渲染，减少闪烁和失败状态。

IconPicker 组件：负责选择，不负责解释渲染

如果说 Icon 是渲染层，那么 IconPicker 就是数据选择层。

它的输出仍然应该是字符串：

<IconPicker v-model="iconValue" />
<IconView :icon="iconValue" />

建议的 Props 设计如下所示：

interface IconPickerProps {
  modelValue?: string;
  value?: string;
  placeholder?: string;
  pageSize?: number;
  svgIcons?: string[];
  svgPrefix?: string;
  onlineLimit?: number;
}

这里同时兼容 modelValue 和 value，能够兼容不同表单体系。

事件则保持轻松：

const emit = defineEmits<{
  (e: 'update:modelValue', v: string): void;
  (e: 'update:value', v: string): void;
  (e: 'change', v: string): void;
}>();

选中图标时统一派发：

function emitUpdate(value: string) {
  emit('update:value', value);
  emit('update:modelValue', value);
  emit('change', value);
}

选择器的整体结构

一个好用的 IconPicker 通常包含这些区域：

1. 输入框触发器：展示当前图标值，兼容手动输入。
2. 搜索框：筛选当前分类图标，也能够触发在线搜索。
3. 分类栏：All、RI、MDI、ION、Ant Design、本地 SVG。
4. 图标网格：展示图标预览，兼容 tooltip 和选中态。
5. 分页栏：避免一次渲染过多图标。

组件结构能够类似这样：

<a-popover v-model:open="open" trigger="click" placement="bottomLeft">
  <template #default>
    <a-input v-model:value="inputValue" allow-clear>
      <template #suffix>
        <button type="button" @mousedown.prevent.stop="togglePopover">
          <IconView :icon="inputValue || 'ion:apps-outline'" :size="18" />
        </button>
      </template>
    </a-input>
  </template>

  <template #content>
    <a-input v-model:value="keyword" />
    <a-segmented v-model:value="category" :options="categoryOptions" />
    <p class="icon-grid">
      <button v-for="name in pageItems" :key="name" @click="apply(name)">
        <IconView :icon="name" :size="20" />
      </button>
    </p>
    <a-pagination v-model:current="page" :page-size="pageSize" :total="filteredTotal" />
  </template>
</a-popover>

这里有一个细节：触发按钮采用 @mousedown.prevent.stop，能够避免点击后输入框 blur 或 Popover 状态抖动。

离线图标集合加载

理解这一步时，IconPicker 不是一打开页面就加载所有图标，而是在打开弹层时再加载：

function loadOfflineIconSets() {
  void loadIconifySet('ri');
  void loadIconifySet('mdi');
  void loadIconifySet('ion');
  void loadAntdvIcons();
}

function onOpenChange(next: boolean) {
  if (next) {
    category.value = detectCategoryByIcon(boundValue.value.trim());
    page.value = 1;
    loadOfflineIconSets();
    focusSearch();
  }

  open.value = next;
}

这样首屏不会因为选择器而膨胀。用户真正打开选择器时，再异步加载候选项。

分类列表能够分开维护：

const riNames = ref<string[]>([]);
const mdiNames = ref<string[]>([]);
const ionNames = ref<string[]>([]);
const antdvIconNames = ref<string[]>([]);

function iconifyNames(prefix: string, json: IconsJson) {
  const names = [
    ...Object.keys(json.icons || {}),
    ...Object.keys(json.aliases || {}),
  ];
  return names.map((name) => `${prefix}:${name}`);
}

Ant Design 图标也能够动态导入，随后过滤出真正的图标组件：

async function loadAntdvIcons() {
  const icons = await import('@antdv-next/icons');

  antdvIconNames.value = Object.keys(icons)
    .filter((name) => /(Outlined|Filled|TwoTone)$/.test(name))
    .map((name) => `antdv-next:${name}`);
}

本地 SVG 自动发现

结合项目来看，除了借助 Props 传入本地 SVG，也能够采用 Vite 的 import.meta.glob 自动发现：

const localSvgModules = import.meta.glob('../../assets/icons/**/*.svg');

function extractSvgSymbolName(path: string) {
  const matched = path.match(//icons/(.*).svg$/);
  if (!matched || !matched[1]) return '';

  const normalized = matched[1].replace(///g, '-');
  const prefix = props.svgPrefix || '';
  return normalized.startsWith(prefix) ? normalized : `${prefix}${normalized}`;
}

const svgAll = computed(() => {
  const fromLocal = Object.keys(localSvgModules)
    .map(extractSvgSymbolName)
    .filter(Boolean)
    .map(normalizeSvgName);

  const fromProps = (props.svgIcons || [])
    .map(normalizeSvgName)
    .filter(Boolean);

  return dedupe([...fromProps, ...fromLocal]);
});

这让业务侧有两种接入方式：

1. 把 SVG 文件放进约定目录，由选择器自动识别。
2. 借助 svgIcons 显式传入当前页面临时定义的 symbol。

示例：

<IconPicker
  v-model="pickedIcon"
  :svg-icons="['icon-demo-orbit', 'icon-demo-pulse']"
/>

分类、搜索与分页

IconPicker 的数据流能够拆成三步：

1. listByCategory：先根据分类拿到候选集合。
2. filtered：再根据关键词过滤。
3. pageItems：最后根据分页截取当前页。

const listByCategory = computed<string[]>(() => {
  switch (category.value) {
    case 'ri':
      return riAll.value;
    case 'mdi':
      return mdiAll.value;
    case 'ion':
      return ionAll.value;
    case 'antdv-next':
      return antdvAll.value;
    case 'svg':
      return svgAll.value;
    default:
      return allOfflineIcons.value;
  }
});

const filtered = computed(() => {
  const query = keyword.value.trim().toLowerCase();
  if (!query) return listByCategory.value;

  return listByCategory.value.filter((item) =>
    item.toLowerCase().includes(query),
  );
});

const pageItems = computed(() => {
  const start = (page.value - 1) * props.pageSize;
  return filtered.value.slice(start, start + props.pageSize);
});

分类或关键词变化时，分页要回到第一页：

watch([category, keyword], () => {
  page.value = 1;
});

理解这一步时，这个逻辑虽然轻松，但很关键。否则用户在第 10 页搜索一个关键词，很容易看到空列表，以为没有结果。

在线搜索：防抖、缓存和取消请求

离线图标适合常用集合，但 Iconify 的价值在于海量在线搜索。

在线搜索建议只在满足条件时触发，比如：

1. 当前分类是 all。
2. 关键词长度至少 2 个字符。
3. 输入停止 300ms 后再请求。

const shouldSearchOnline = computed(() => {
  const query = keyword.value.trim();
  return query.length >= 2 && category.value === 'all';
});

请求层面建议同时处理三件事：

1. 用 setTimeout 做防抖。
2. 用 Map 缓存相同关键词结果。
3. 用 AbortController 取消上一次未完成请求。

const onlineIcons = ref<string[]>([]);
const onlineCache = new Map<string, string[]>();
const onlineAbortController = ref<AbortController | null>(null);
let onlineTimer: ReturnType<typeof setTimeout> | null = null;

function scheduleOnlineSearch() {
  if (onlineTimer) {
    clearTimeout(onlineTimer);
    onlineTimer = null;
  }

  if (!shouldSearchOnline.value) {
    resetOnlineState();
    return;
  }

  const query = keyword.value.trim();
  onlineTimer = setTimeout(() => {
    fetchOnlineIcons(query);
  }, 300);
}

真正请求时：

async function fetchOnlineIcons(query: string) {
  const normalized = query.trim().toLowerCase();
  if (!normalized) return;

  if (onlineCache.has(normalized)) {
    onlineIcons.value = onlineCache.get(normalized) || [];
    return;
  }

  onlineAbortController.value?.abort();

  const controller = new AbortController();
  onlineAbortController.value = controller;

  try {
    const url = `https://api.iconify.design/search?query=${encodeURIComponent(normalized)}&limit=${props.onlineLimit}`;
    const response = await fetch(url, { signal: controller.signal });
    const data = await response.json() as { icons?: string[] };

    const icons = Array.isArray(data.icons)
      ? data.icons.filter((item): item is string => typeof item === 'string' && Boolean(item))
      : [];

    onlineCache.set(normalized, icons);

    if (!controller.signal.aborted) {
      onlineIcons.value = icons;
    }
  } finally {
    if (onlineAbortController.value === controller) {
      onlineAbortController.value = null;
    }
  }
}

组件卸载时也要清理定时器和请求：

onBeforeUnmount(() => {
  if (onlineTimer) clearTimeout(onlineTimer);
  onlineAbortController.value?.abort();
});

实际处理时，这个细节决定了 IconPicker 在复杂页面里的稳定性。否则用户更快输入、切换页面或关闭弹层时，很容易出现过期请求覆盖新结果的问题。

交互细节：选择器要像表单组件一样工作

落到代码里，IconPicker 本质上是一个表单控件，所以它要尊重表单控件的采用习惯。

兼容手动输入

理解这一步时，不要把 IconPicker 做成只能点选。实际业务中，开发者可能已经知道图标名，直接粘贴会更快：

function onInputChange() {
  emitUpdate(editableValue.value);
}

这样能够兼容：

ri:home-line
mdi:account-circle-outline
custom-prefix:custom-icon

打开时自动定位分类

若当前值是 mdi:account，打开选择器时默认切到 MDI 分类会更自然：

function detectCategoryByIcon(iconName: string): Category {
  if (iconName.startsWith('ri:')) return 'ri';
  if (iconName.startsWith('mdi:')) return 'mdi';
  if (iconName.startsWith('ion:')) return 'ion';
  if (iconName.startsWith('svg:')) return 'svg';
  if (iconName.startsWith('antdv-next:') || iconName.startsWith('antd:')) {
    return 'antdv-next';
  }
  return 'all';
}

图标来源要可视化

图标多了以后，只看名字不够。能够给不同来源设置不同颜色和标签：

const iconMetaConfig = {
  ri: { label: 'Remix', color: '#3b82f6' },
  mdi: { label: 'MDI', color: '#10b981' },
  ion: { label: 'Ion', color: '#8b5cf6' },
  'antdv-next': { label: 'Antdv', color: '#ef4444' },
  svg: { label: 'SVG', color: '#f59e0b' },
  online: { label: 'Online', color: '#64748b' },
};

从实现思路看，在 tooltip、hover 色条、分类标签里复用这套元信息，用户就能更快判断图标来源。

网格不要一次渲染太多

图标选择器很容易一次渲染几千个按钮。如果没有虚拟滚动，至少要分页：

const pageItems = computed(() => {
  const start = (page.value - 1) * props.pageSize;
  return filtered.value.slice(start, start + props.pageSize);
});

默认 pageSize 能够设成 36。比如 6 列网格，每页 6 行，视觉上比较稳定。

菜单系统里的图标解析

在这个场景下，在菜单、标签页、全局搜索这些地方，图标通常来自路由 meta 或后端权限设置。

从实现思路看，若只用少量 Ant Design 图标，能够额外维护一个轻量 resolveIcon：

const iconMap: Record<string, Component> = {
  HomeOutlined,
  SettingOutlined,
  UserOutlined,
};

function normalizeIconName(name: string): string {
  const trimmed = name.trim();
  if (trimmed.startsWith('antdv-next:')) return trimmed.slice('antdv-next:'.length);
  if (trimmed.startsWith('antd:')) return trimmed.slice('antd:'.length);
  return trimmed;
}

export function resolveIcon(name?: string): Component | undefined {
  if (!name) return undefined;
  return iconMap[normalizeIconName(name)];
}

这种方式适合菜单树：只注册菜单常用图标，避免布局组件引入过多内容。

落到代码里，若想要菜单也兼容 Iconify 和 SVG，则能够直接在菜单项里采用统一的 Icon 组件，而不是 resolveIcon。

组件设计里的几个取舍

为什么不直接传组件？

落到代码里，因为后台系统里的图标经常来自后端。后端不可能传 Vue 组件，只能传字符串。

字符串协议天然适合：

1. 后端存储。
2. 权限设置。
3. 表单编辑。
4. 复制粘贴。
5. 国际化和多端复用。

为什么 Icon 和 IconPicker 要拆开？

因为它们职责完全不同。

Icon 是渲染组件，要足够轻，采用频率很高。

IconPicker 是选择组件，会涉及大量数据、搜索、分页、网络请求，不能污染 Icon 的复杂度。

拆开以后，业务里能够自由组合：

<IconPicker v-model="form.icon" />
<IconView :icon="form.icon" />

为什么离线和在线都要兼容？

只兼容在线搜索，内网环境或弱网环境会很难用。

只兼容离线图标包，图标覆盖面又不够。

比较稳妥的方案是：

1. 常用集合离线化，比如 ri、mdi、ion。
2. 关键词搜索时补充在线结果。
3. 在线搜索结果也仍然得到 Iconify 标准字符串。

这样既保证基础可用，又保留扩展空间。

最后采用效果

业务页面能够这样写：

<script setup lang="ts">
import { ref } from 'vue';
import IconView from '@/components/Icon/index.vue';
import IconPicker from '@/components/IconPicker/index.vue';
const iconValue = ref('ri:map-pin-time-line');
</script>
<template>
  <IconPicker v-model="iconValue" />
  <IconView :icon="iconValue" :size="32" />
</template>

如果需本地 SVG：

<svg aria-hidden="true" >
  <symbol id="icon-demo-orbit" viewBox="0 0 1024 1024">
    <!-- svg paths -->
  </symbol>
</svg>

<IconView icon="svg:icon-demo-orbit" :size="20" />

如果需让 IconPicker 识别页面内临时 symbol：

<IconPicker
  v-model="iconValue"
  :svg-icons="['icon-demo-orbit', 'icon-demo-pulse']"
/>

总结

结合项目来看，设计一套 Vue3 图标组件，重点不是“能不能显示图标”，而是能不能在真实业务里长期维护。

我认为比较稳的方案是：

1. 用字符串协议统一所有图标来源。
2. Icon 只负责按协议渲染。
3. IconPicker 只负责选择同时输出协议字符串。
4. 常用 Iconify 集合做离线动态加载。
5. 搜索结果用分页控制渲染规模。
6. 在线搜索加防抖、缓存和请求取消。
7. 本地 SVG 用 svg: 协议接入，保持和其他来源一致。

当 IconPicker 选出的值能够直接交给 Icon 渲染时，这套体系就已经形成闭环。后续无论是菜单设置、权限管理、表单设计器，还是低代码页面设置，都能够围绕同一个 icon: string 模型扩展。

从实现思路看，这就是基础组件真正有价值的地方：不是把某个 UI 做出来，而是把复杂度收敛到一个稳定、可复用、可演进的工程模型里。

到此这篇关于Vue3中设计一套好用的Icon和IconPicker组件示例的文章就介绍到这了,更多相关Vue3中Icon和IconPicker组件内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多兼容脚本之家！

您可能感兴趣的文章:

• Vue3采用icon的两种方式实例
• 在vue3中采用icon图标的三种方案
• vue3自动导入icon图标具体实现方法