TinyVue图标使用完全指南

TinyVue 图标使用完全指南

TinyVue 作为 OpenTiny 开源项目的前端组件库，其图标系统设计得十分独特 ------ 图标不是普通组件，而是函数！ 这个设计初看可能让人困惑，但理解之后会发现它带来了极大的灵活性。本文将从核心概念出发，带你彻底掌握 TinyVue 图标的使用。

安装图标库

TinyVue 的图标独立于组件库，需要单独安装：

bash 复制代码

npm install @opentiny/vue-icon

核心概念：图标是函数

与大多数组件库（如 Element Plus、Ant Design Vue）直接提供 Vue 组件不同，TinyVue 中的每个图标都是一个工厂函数。你需要先调用这个函数，才能得到一个真正可渲染的 Vue 组件。

js 复制代码

import { IconShare } from '@opentiny/vue-icon'

// IconShare 是一个函数，执行后返回一个 Vue 组件
const IconComponent = IconShare()

这种设计的巧妙之处在于：你可以在创建图标组件时注入自定义上下文，而无需修改图标组件本身。这也是后续进阶特性（如双色、托底效果）的基础。

模板中的三种使用方式

以 Share 图标为例，在模板中有以下三种标准用法：

方式一：标签式使用（最推荐）

这是最直观也是最推荐的方式：

vue 复制代码

<template>
  <tiny-icon-share />
</template>

<script setup>
import { iconShare } from '@opentiny/vue-icon'
const TinyIconShare = iconShare()
</script>

方式二：通过 `<component>` 动态组件

当你需要动态切换图标时，这种方式非常实用：

vue 复制代码

<template>
  <component :is="currentIcon" />
</template>

<script setup>
import { iconShare, iconDel } from '@opentiny/vue-icon'
import { ref } from 'vue'

const currentIcon = ref(iconShare())

// 动态切换
function switchIcon() {
  currentIcon.value = iconDel()
}
</script>

方式三：作为属性值传入

将图标作为其他组件的属性传入，比如按钮的 icon 属性：

vue 复制代码

<template>
  <tiny-button :icon="tinyIconShare">分享</tiny-button>
</template>

调整图标大小和颜色

TinyVue 图标本质上是 SVG 元素，所有样式通过 CSS 控制：

大小：通过 font-size 控制（SVG 的 1em 映射到当前字号）
颜色：通过 fill 控制（SVG 的填充色）

vue 复制代码

<template>
  <tiny-icon-share class="icon-large" />
  <tiny-icon-del class="icon-red" />
</template>

<style scoped>
.icon-large {
  font-size: 48px;
}
.icon-red {
  fill: red;
}
</style>

Options API 用法

对于仍在使用 Options API 的项目，使用方式如下：

vue 复制代码

<template>
  <div>
    <icon-share class="icon-blue" />
    <icon-del class="icon-green" />
  </div>
</template>

<script>
import { IconShare, IconDel } from '@opentiny/vue-icon'

export default {
  components: {
    IconShare: IconShare(),
    IconDel: IconDel()
  }
}
</script>

需要注意的是，Composition API 版本导入时使用小驼峰命名（如 iconShare），而 Options API 版本使用大驼峰命名（如 IconShare），这只是命名规范的差异，实际功能完全相同。

进阶用法：高级图标特性

TinyVue 为 Saas 业务提供的高级图标支持以下特性：

shape ：'line'（线性，默认）或 'filled'（面性），用于切换图标风格
firstColor：图标的主色调
secondColor：图标的辅助色调
underlay ：托底效果配置对象，支持 background（背景色）、borderRadius（圆角）、scale（缩放比例）

vue 复制代码

<template>
  <component
    :is="iconSearch()"
    shape="filled"
    first-color="#0067D1"
    second-color="#36C18D"
    :underlay="{ background: '#eef3fe', borderRadius: '4px', scale: 0.8 }"
  />
</template>

这种高级用法允许你动态控制图标的表现形式，非常适合需要与品牌色保持一致的业务场景。

常见误区与避坑

❌ 误区：在模板中直接调用函数

vue 复制代码

<!-- 不推荐：每次组件更新都会创建新的图标实例 -->
<component :is="IconShare()" />

✅ 正确：提前执行并缓存引用

vue 复制代码

<!-- 推荐：只创建一次，后续复用 -->
<component :is="tinyIconShare" />

原因很简单：在模板中直接调用函数，Vue 每次重新渲染都会执行 IconShare()，导致不必要的性能开销和组件重建。

支持的主题变量

TinyVue 图标默认使用 CSS 变量来控制颜色，你可以通过覆盖这些变量来统一调整图标风格：

css 复制代码

.tiny-svg {
  fill: var(--tv-color-icon-control);
  color: var(--tv-color-icon-control);
}

通过修改 --tv-color-icon-control 变量，你可以一键切换所有图标的默认颜色。

总结

TinyVue 的图标系统遵循一个简单原则：图标是函数，先执行再使用。记住这一条，你就掌握了核心。其函数式设计不仅带来了性能上的优势（懒加载、按需创建），也为双色、托底等高级特性提供了实现基础。

快速上手只需三步：

从 @opentiny/vue-icon 导入图标函数
调用函数获取组件实例
在模板中像普通组件一样使用

TinyVue图标使用完全指南