---
title: 图标体系
description: TxIcon 的图标解析顺序与加载配置
category: Foundations
status: beta
since: 0.4.0
tags: [icon, svg, resolver, iconify]
syncStatus: reviewed
verified: false
---

## 五种来源

`name` 只解析为 `class` 或 `builtin`，按表中顺序先命中先生效；`emoji`、`url`、`file` 只能经 `icon` 显式传入，`icon` 优先于 `name`。

| 写法 | 类型 | 渲染 |
|------|------|------|
| `name="i-carbon-search"` | `class` | 带该 class 的 `<i>`：Iconify / UnoCSS 预设图标 |
| `name="chevron-down"` | `builtin` | 内置表里的内联 `<svg>` |
| `name` 为其他字符串 | `class` | 同第一行，字符串直接作 class 名 |
| `:icon="{ type: 'emoji', value }"` | `emoji` | 按文本输出 |
| `:icon="{ type: 'url', value }"` | `url` | 拉取后绘制 |
| `:icon="{ type: 'file', value }"` | `file` | 先套本地文件协议，再拉取绘制 |

:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <!-- class：构建里带的任意 Iconify 图标集 -->
    <TxIcon name="i-carbon-search" />

    <!-- builtin：不需要图标集 -->
    <TxIcon name="chevron-down" />

    <!-- 显式来源 -->
    <TxIcon :icon="{ type: 'emoji', value: '🚀' }" />
    <TxIcon :icon="{ type: 'url', value: '/icons/plugin.svg' }" />
    <TxIcon :icon="{ type: 'file', value: '/Users/me/icon.png', colorful: true }" />
  </template>
---
:::

## 内置图标表

`check`、`chevron-down`、`chevron-right`、`chevron-left`、`arrow-left`、`arrow-up`、`arrow-down`、`plus`、`close`、`search`、`user`、`star`、`star-half`、`info`、`check-circle`、`x-circle`、`alert-triangle` 内置在组件中，未配置任何图标集时核心交互也能渲染。

- 内置表不是通用图标库；其他图标用 Iconify class 或显式来源。
- 条目画成实心剪影或开放描边。`chevron-down` 用描边：它在 12–14px 下作展开指示，实心楔形会在标签旁糊成一团。其余方向与 `plus` 用同一描边。

## 颜色、蒙版与 `colorful`

适用于 `url` / `file` 来源。

| 模式 | 渲染 | 用于 |
|------|------|------|
| 单色（默认） | 单色 SVG 以 CSS mask 绘制，取 `currentColor`，随主题变色 | 界面图标 |
| `colorful: true` | `<img>`，保留原色 | Logo、应用图标 |

来源上的 `color` 覆盖单色墨色。

## 加载应用图标

图标在自定义协议、鉴权接口或传输层后面时，provide 一次配置，其下所有 `TxIcon` 生效：

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { TX_ICON_CONFIG_KEY } from '@talex-touch/tuffex/icon'

  app.provide(TX_ICON_CONFIG_KEY, {
    // 把原始值改写成浏览器能取到的地址
    urlResolver: (url, type) => (type === 'file' ? `tfile://${url}` : url),
    // 自己接管抓取：重试、鉴权头、IPC 传输……
    svgFetcher: async url => (await fetch(url)).text(),
    // 没有 resolver 时，给 `file` 来源加的协议前缀
    fileProtocol: 'tfile://',
  })
---
:::

单个 `TxIcon` 可用自己的 `urlResolver` / `svgFetcher` prop 覆盖注入的配置。

## 动效图标

需要会动的图标时，可参考 [AnimateIcons](https://animateicons.in/)：542 个基于 Lucide 几何的 MIT 动效图标。

- 以 React 组件（`motion/react`）分发，不能直接作为 Tuffex 或 Vue 依赖；可移植的是 SVG 路径与逐路径动画时序。
- 不是 Iconify 图标集：没有 `i-animateicons-*` class，移植结果是组件，不走 `name` 解析。
- 图标不需要动时，优先用构建已带的图标集（`carbon`、`ri`、`simple-icons`……）。
- 复制几何路径时一并保留署名与 MIT 声明。

## 技术实现

- 解析与渲染：`packages/tuffex/packages/components/src/icon/src/TxIcon.vue`。
- 配置契约：`packages/tuffex/packages/components/src/icon/src/types.ts`（`TxIconSource`、`TxIconConfig`、`TX_ICON_CONFIG_KEY`）。

## 相关组件

| 组件 | 用途 |
|------|------|
| 《[Icon 图标](./icon.zh.mdc)》 | 通用场景与完整属性 |
| 《[IconChip 图标徽标](./icon-chip.zh.mdc)》 | 承载字形或短标签的色块 |
| Status icon | 状态语义色字形 |
