Icon 图标 | Tuff Docs

用法

类名图标

<template>
  <!-- Remix Icon -->
  <i class="i-ri-home-line" />
  <i class="i-ri-search-line" />
  <i class="i-ri-settings-3-line" />
  <!-- Carbon -->
  <i class="i-carbon-user" />
  <i class="i-carbon-folder" />

  <!-- Simple Icons (品牌) -->
  <i class="i-simple-icons-github" />
  <i class="i-simple-icons-visualstudiocode" />
</template>

TuffIcon

TuffIcon（别名 TxIcon）的 name 接受类名或内置名，icon 接受结构化来源。

<template>
  <TuffIcon name="i-ri-home-line" />
  <TuffIcon name="chevron-down" />
  <TuffIcon :icon="{ type: 'emoji', value: '🚀' }" />
  <TuffIcon :icon="{ type: 'url', value: '/app.svg', colorful: true }" />
</template>

TuffIcons 常量

@talex-touch/utils 提供预定义的图标常量。

import { TuffIcons, AppIcons } from '@talex-touch/utils'

// 通用 UI 图标
TuffIcons.Home // 'i-ri-home-line'
TuffIcons.Search // 'i-ri-search-line'
TuffIcons.Settings // 'i-ri-settings-3-line'

// 应用品牌图标
AppIcons.VSCode // 'i-simple-icons-visualstudiocode'
AppIcons.GitHub // 'i-simple-icons-github'

分类	常量	类名
导航	`TuffIcons.Home`	`i-ri-home-line`
	`TuffIcons.Back`	`i-ri-arrow-left-line`
	`TuffIcons.Forward`	`i-ri-arrow-right-line`
	`TuffIcons.Menu`	`i-ri-menu-line`
操作	`TuffIcons.Search`	`i-ri-search-line`
	`TuffIcons.Add`	`i-ri-add-line`
	`TuffIcons.Delete`	`i-ri-delete-bin-line`
	`TuffIcons.Edit`	`i-ri-edit-line`
	`TuffIcons.Copy`	`i-ri-file-copy-line`
	`TuffIcons.Save`	`i-ri-save-line`
	`TuffIcons.Download`	`i-ri-download-line`
	`TuffIcons.Upload`	`i-ri-upload-line`
	`TuffIcons.Refresh`	`i-ri-refresh-line`
状态	`TuffIcons.Check`	`i-ri-check-line`
	`TuffIcons.Close`	`i-ri-close-line`
	`TuffIcons.Warning`	`i-ri-error-warning-line`
	`TuffIcons.Info`	`i-ri-information-line`
	`TuffIcons.Error`	`i-ri-close-circle-line`
文件	`TuffIcons.File`	`i-ri-file-line`
	`TuffIcons.Folder`	`i-ri-folder-line`
	`TuffIcons.FileCode`	`i-ri-file-code-line`
	`TuffIcons.FileImage`	`i-ri-image-line`
界面元素	`TuffIcons.Settings`	`i-ri-settings-3-line`
	`TuffIcons.User`	`i-ri-user-line`
	`TuffIcons.Star`	`i-ri-star-line`
	`TuffIcons.Heart`	`i-ri-heart-line`
	`TuffIcons.Lock`	`i-ri-lock-line`
	`TuffIcons.Eye`	`i-ri-eye-line`
品牌	`AppIcons.GitHub`	`i-simple-icons-github`
	`AppIcons.VSCode`	`i-simple-icons-visualstudiocode`
	`AppIcons.Chrome`	`i-simple-icons-googlechrome`
	`AppIcons.Discord`	`i-simple-icons-discord`

自定义样式

<template>
  <!-- 尺寸 -->
  <i class="i-ri-home-line text-sm" />
  <i class="i-ri-home-line text-base" />
  <i class="i-ri-home-line text-xl" />
  <i class="i-ri-home-line text-2xl" />

  <!-- 颜色 -->
  <i class="i-ri-star-line text-yellow-500" />
  <i class="i-ri-heart-fill text-red-500" />
  <i class="i-ri-check-circle-fill text-green-500" />

  <!-- 动画 -->
  <i class="i-ri-loader-4-line animate-spin" />
</template>

状态角标

TxStatusIcon 的 tone 在图标右下角叠加状态点。

示例加载中...

操作系统图标

TxOsIcon 根据 platform 与 os 识别平台。

示例加载中...

图标来源

`type`	用途
`class`	图标类名（推荐）。
`emoji`	轻量强调。
`file` / `url`	本地或远程图标。
`builtin`	内置图标：`check`、`chevron-down`、`close`、`search`、`user`、`star`、`star-half`、`info`、`check-circle`、`x-circle`、`alert-triangle`。

colorful 可写在组件属性上，也可写在 icon.colorful 中。

最佳实践

产品 UI 优先用 UnoCSS 类名（i-*），它继承 currentColor；需要状态、URL / file 解析或保留原色时再用 TxIconSource。
只有图标本身承载语义时才设置 alt；装饰性图标的语义交给周围文本。
单色 SVG 保持 colorful=false 以跟随主题色；品牌标识与多色图设置 colorful=true。
在应用外壳注入一次 TX_ICON_CONFIG_KEY，不要逐个图标传 resolver。
TxOsIcon 搭配可见的平台文本，用 CSS 字号调整大小；回退图标只是视觉默认值，不是校验结果。

API 参考

TxIcon

属性

属性名	默认值	说明
icon	-	结构化图标来源（type / value），与 name 二选一。
name	-	类名或内置图标名。
size	-	尺寸（px）；省略时继承父级字号。
colorful		保留 SVG 原色。
alt		可访问名称，写入 title；也用作兜底图片的 alt。
empty		未解析出图标时显示的兜底图片 URL。
urlResolver	-	覆盖 URL / file 路径解析。
svgFetcher	-	覆盖 SVG 内容获取。

插槽

名称	参数	说明
`empty`	-	替换未解析出图标时的兜底内容。

TxStatusIcon

属性

属性名	类型	默认值	说明
colorful			保留 SVG 原色；默认 true，与 TxIcon 相反。
size			尺寸（px）；默认 18，TxIcon 则继承父级字号。
tone			右下角的状态点；none 时不显示。
indicatorSize			状态点尺寸（px）。
indicatorOffset			状态点偏移（px）。

icon、name、alt、empty 与 TxIcon 相同。

TxOsIcon

属性

属性名	类型	默认值	说明
platform			平台标识，如 darwin、win32、linux。
os			可读的系统名称，同样参与识别。

classIcon / getIcon

import { classIcon, getIcon } from '@talex-touch/utils'

const icon = classIcon('i-ri-star-line')
// { type: 'class', value: 'i-ri-star-line' }

const searchIcon = getIcon('Search')
// { type: 'class', value: 'i-ri-search-line' }

图标集

图标集	前缀	描述
Remix Icon	`i-ri-`	通用 UI 图标，线条 / 填充风格
Carbon	`i-carbon-`	IBM 设计系统图标
Simple Icons	`i-simple-icons-`	品牌 / Logo 图标

图标搜索

在 Icônes 浏览和搜索全部图标。

概述

name 以 i- 开头时按类名渲染，命中内置名时渲染内置 SVG，其余按类名渲染；类不存在时不显示任何内容。
file 与本地绝对 url 经注入的 fileProtocol 或 urlResolver 转换。
colorful=false 时，能读到内容（data URL 或 svgFetcher）的单色 SVG 以 currentColor 遮罩渲染；多色或读不到内容的 SVG 渲染原图。
icon.status 为 loading 或 error 时优先显示对应状态。
设置 alt 时根节点为 role="img" 并带 title；未设置时为 aria-hidden="true"。
TxOsIcon 将 platform 与 os 合并转小写，识别 macOS / Windows / Linux，未识别时显示 macOS；SVG 为 aria-hidden。

技术实现

shouldRenderSvgAsMask 检查 SVG 的绘制颜色是否都是中性色或 currentColor，以决定是否走遮罩。
TX_ICON_CONFIG_KEY 注入 urlResolver、svgFetcher 与 fileProtocol。
源码：packages/tuffex/packages/components/src/icon/。

查看源码

packages/tuffex/packages/components/src/icon/index.ts