{T}

IconPicker 封装与动态加载优化

概述

图标体系从"能展示"走向"能选择"，关键一步是把 IconList 升级为 IconPicker——一个具备清晰输入输出边界的交互型组件。本文讲它的双向绑定设计、图标动态加载优化、组件目录重组，以及两个高频踩坑（Grid 最后一行不满、组件名与页面名冲突）。

学习目标

  • 理解从展示型组件（IconList）到交互型组件（IconPicker）的职责分层
  • 掌握 v-model 双向绑定，以及 Vue 3.3 defineModel 的简化写法
  • 能用动态 import() 按图标集加载，降低首屏体积
  • 知道组件承担强交互后如何做目录重组与类型提取
  • 解决图标网格的 Grid 自适应与组件命名冲突问题

一、从 IconList 到 IconPicker：展示型到交互型

IconList 只负责把图标铺出来，IconPicker 则把"选择 → 回传"流程抽象成可复用组件：输入是当前值与图标集，输出是选中的图标名。核心纪律是输入输出边界清晰——图标展示与图标选择职责分层，展示组件可被选择器复用，选择器只对外暴露 v-model 与少量配置。命名和目录也要围绕复用性组织，而不是散落在页面里。

二、v-model：表单型组件最自然的接入

图标选择器本质是表单型组件，v-model 是最符合 Vue 习惯的接入方式。标准实现是 modelValue + update:modelValue：

ts
const props = defineProps<{ modelValue: string }>()
const emit = defineEmits<{ 'update:modelValue': [value: string] }>()
const selectIcon = (value: string) => emit('update:modelValue', value)

Vue 3.3 起可用 defineModel 把上述三行压缩成一行，并天然支持默认值：

ts
const selectedIcon = defineModel<string>({ default: '' })
// 直接读写 selectedIcon.value 即自动触发 update:modelValue

事件类型建议用数组语法提取到独立的 types 文件，避免散落在组件内：

ts
const emit = defineEmits<{ submit: [data: IconPickerSubmitData]; cancel: [] }>()

一旦接好 v-model，接入任意表单场景都只需 <IconPicker v-model="icon" />，无须额外胶水代码。

三、动态加载图标：降低初始成本

图标量一旦变多，全量静态导入会明显拖累体积与首屏。动态加载的目标是降低初始成本，而非炫技——它适合"量大且并非首屏必需"的资源：

ts
const loadCollection = async (name: string) => {
  return await import(`./collections/${name}.ts`)
}

实践中要注意三点：动态加载需同步考虑加载状态与空状态；图标网格数据可以配合 loadIcons 批量预加载；一切性能优化应建立在真实数据规模上，不要为少量图标引入复杂度。

四、组件目录重组与类型提取

当组件开始承担更强交互（弹窗、预览、提交），往往触发目录重组。典型演进是：把示例代码从 App.vue 移到 pages/ 作为 demo 页，组件本身归到 components/，相关类型抽到 src/types/icon.ts，组合逻辑（如复制）抽成 composables/useIconCopy.ts。

自动导入方面，unplugin-vue-components 的 directoryAsNamespace 控制注册名：开启后 icon/EPIconList.vue 注册为 IconEPIconList，关闭则为 EPIconList（更简洁，推荐）。组件重命名、新增目录或类型异常后，需重启 dev server 或清 node_modules/.vite 缓存让自动导入重新扫描。

五、Grid 自适应布局与命名冲突

图标网格最宜用 Grid 而非 Flex。Flex 换行时最后一行元素无法自动占满剩余空间，而 Grid 的 auto-fill + minmax 能自适应列数：

css
.icon-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
  gap: 8px;
}

minmax 的最小值应不小于图标字号（如 text-3xl ≈ 1.875rem），否则图标会被截断。另一个高频坑是组件名与页面名冲突导致无限递归渲染——当 pages/IconList.vue 内部又调用 <IconList /> 时，会指向自身。解法是用带前缀的组件名（如 EPIconList），或把页面改名为 IconListDemo.vue，或用完整路径显式导入。

六、图标集数据与构建收尾

选择器与展示组件就绪后，还要把图标数据本身工程化。典型做法是把图标集固化为数据文件，作为列表组件的数据源：

json
{ "collection": "ep", "icons": ["edit", "delete", "search", "setting", "user", "star"] }

若直接用 import epData from '@/components/icons/ep.json'，需在 env.d.ts 声明 declare module '*.json'（或更精确的图标数据类型），否则 TS 会报找不到模块。构建层面要注意：自定义 SVG 依赖 virtual:svg-icons-register 注入 Sprite，打包后不能漏掉该虚拟模块；IconFont 则需把字体文件随产物发布，并留意字体 URL 的相对路径。此外，图标选择器最终应落到文档站，提供搜索、分类筛选与"最近使用"记录，让组件能力与使用者入口闭环；对图标的可访问性（如 aria-hidden、键盘可达的选中态）也应一并考虑，而非只追求视觉呈现。

七、选择器交互：搜索、分类与最近使用

图标数量上来后，"能选"还不够，还要"选得快"。图标选择器至少要补三层交互：

  • 搜索：按图标名模糊匹配，输入即过滤，避免滚动翻找。
  • 分类 / 图标集筛选：按 collection（如 ep、mdi）切换数据集，降低单次渲染量。
  • 最近使用：把近期选中项存进 useStorage，下次置顶，高频图标一步到位。

这三层都依赖 六 里固化的 ep.json 数据源——数据是骨架，交互是血肉。搜索与分类筛选应尽量在前端做轻量过滤，不要每次请求远程；"最近使用"则用 useStorage 持久化到本地，刷新后仍在。

交互细节还有两点提醒：搜索输入应做轻量防抖，避免每次按键都重算大列表；筛选结果为空时要给出明确的空状态文案，而不是一片空白让用户怀疑是否加载失败。另外，弹窗形式的选择器要处理好关闭后的焦点回归，保证键盘用户不会"选中后找不到光标在哪"。

当图标集膨胀到上千个时，一次性渲染会拖垮列表。可引入分页或虚拟滚动，只渲染视口内的图标——数据层依旧读 ep.json，只是渲染窗口随滚动移动。这样选择器在万级图标下也能保持流畅，而搜索与分类筛选又进一步缩小了需要渲染的集合规模。

实践中还有一个易忽略的点：搜索关键词应只匹配图标名而非整个 collection:name。否则用户输入 edit 时，匹配逻辑若作用于全称，反而可能漏掉 ep:edit 或带出一堆无关结果。匹配范围和展示名保持一致，体验才符合直觉。

常见问题

问题原因解决方案
展示与选择职责混在一起未区分展示/交互组件先拆展示组件，再封装选择器
父组件接入不顺手未遵循 v-model 约定用 defineModel 或 modelValue 双向绑定
图标太多首屏变慢一次性全量导入动态 import() 或按图标集加载
图标网格最后一行不满用了 Flex 换行改用 Grid auto-fill + minmax
页面无限递归渲染组件名与页面名相同组件加前缀或页面改名
自动导入失效缓存未刷新重启 dev 或清 .vite 缓存

延伸阅读