图标

• 可用图标
• 安装和设置
  • 如果您的项目使用自定义配置
• 注册图标
  • 图标是如何加载的？
  • 将图标添加到iconRegistry
• 输出图标
  • 将图标添加到输入中
  • 使用自定义SVG图标
  • 使用<FormKitIcon />组件
• 图标点击处理器
• 使用第三方库
  • 使用自定义的iconLoaderUrl与FontAwesome一起使用
  • 一个Heroicons的iconLoader示例

FormKit自带超过130个图标！除品牌图标（如YouTube，TikTok或Visa）外，所有图标均为原创，并已获得MIT许可，可在您的项目中免费使用。您可以使用我们的图标，添加您自己的图标，或轻松地连接到第三方图标集。

在您的项目中使用图标就像将您想要的图标名称提供给输入的图标属性一样简单。

<FormKit prefix-icon="email" />
<FormKit suffix-icon="settings" />
<FormKit type="select" select-icon="caretDown" />

就这么简单！🎉

图标实际效果的快速演示

可用图标

@formkit/icons包含超过130个常见图标，使您能够轻松开始使用！使用下面的搜索来过滤可用的图标：

安装和设置

对于大多数用户来说，无需安装就可以使用图标（尽管我们建议将您的图标添加到iconRegistry以获得最佳性能）。图标支持是通过名为createThemePlugin()的FormKit第一方插件提供的。如果您正在使用FormKit的defaultConfig()，则默认启用此插件。

当使用随FormKit一起提供的defaultConfig时，您可以使用几个顶级配置选项来定制您的体验。请参阅下一节中的createThemePlugin文档，以获取每个选项的详细解释。

import { createApp } from 'vue'
import App from 'App.vue'
import { plugin, defaultConfig } from '@formkit/vue'

createApp(App).use(plugin, defaultConfig({
  ...
  icons: { heart: '<svg...' }, // 允许定义图标以便在不进行远程获取的情况下使用
  iconLoaderUrl: (iconName) => `https://...`, // 加载远程图标的位置
  iconLoader: (iconName) => {}, // 比iconLoaderUrl替换提供更直接控制的函数
  ...
}).mount('#app')

如果您的项目使用自定义配置

如果您的项目没有使用 FormKit 提供的 defaultConfig，那么您需要在您的 FormKit 项目的配置中安装 createThemePlugin()：

• 从 @formkit/themes 包中导入 createThemePlugin()。
• 在您的 FormKit 配置的插件数组中添加 createThemePlugin()。

import { createApp } from 'vue'
import App from 'App.vue'
import { createThemePlugin } from '@formkit/themes'
import { plugin } from '@formkit/vue'

// 重要：这只对不使用 defaultConfig() 的应用程序必需
createApp(App).use(plugin, {
  ...
  plugins: [
    createThemePlugin()
  ]
  ...
}.mount('#app')

createThemePlugin 接受 4 个可选参数：

• theme：FormKit 主题名称的字符串表示，例如 'genesis'。当提供时，如果找到匹配的 FormKit 主题，它将自动通过 CDN 加载。
• icons：要添加到内部 iconRegistry 的 SVG 图标的对象。键是图标名称，值是 SVG，例如 { heart: '<svg ...' }
• iconLoaderUrl：接收 iconName 并返回可以加载未在 iconRegistry 中找到的图标的 URL 的函数。参见示例
• iconLoader：接收 iconName 并返回解析为 SVG（作为字符串）或 undefined 的 Promise 的函数。当您需要比仅覆盖 iconLoaderUrl 更多的控制时，使用此功能。参见示例

一旦主题插件在您的项目中安装，您的 FormKit 输入将有图标属性可供使用。

注册图标

图标是如何加载的？

FormKit 在尝试加载图标时会经历 4 个步骤。它们按顺序是：

1. SVG 属性值 - 如果属性值是 SVG（例如 prefix-icon="<svg ..."），那么将使用提供的 SVG。
2. iconRegistry - 如果属性值是字符串且不是 SVG，那么 FormKit 将在其内部 iconRegistry 中查找匹配的键。
3. 您的项目的 CSS 变量 - 如果有一个与 --fk-icon-${yourIconName} 匹配的 CSS 变量在您的 CSS 中定义，它将被加载到 iconRegistry 中。CSS 变量的值应该是 base64 编码的 SVG - 它不应该被包裹在引号中。这就是 FormKit 为其第一方主题的输入提供默认图标的方式。
4. 通过 CDN - 如果在您的代码库中找不到匹配的图标，那么将通过 CDN 向 @formkit/icons 包发出请求。如果找到匹配的图标名称，它将被使用。如果您想使用第三方图标库作为备选，您可以覆盖远程图标的加载位置。

因为 FormKit 会回退到 CDN 请求图标，所以您可以在新项目中轻松开始，只需向您的输入的图标属性提供支持的图标名称，它们将自动为您加载 - 无需额外设置！🪄

远程加载的 SVG 在第一次获取图标时被添加到内部的 iconRegistry 中。对同一图标的额外请求将被缓存，直到用户重新加载您的应用程序。

将图标添加到iconRegistry

Magic CDN非常棒 - 但为了获得最佳的性能，你应该在你的项目中本地注册你知道你会使用的图标。 你可以通过将图标添加到你的根FormKit配置中来做到这一点。FormKit的第一方图标可以从@formkit/icons包中导入。

yarn add @formkit/icons

import { createApp } from 'vue'
import App from 'App.vue'
import { applicationIcons, ethereum } from '@formkit/icons'
import { thirdPartyIcon } from '@some-other-icon-package'
import { plugin, defaultConfig } from '@formkit/vue'

createApp(App).use(plugin, defaultConfig({
  ...
  icons: {
    ...applicationIcons, // 整组图标的扩展
    ethereum, // 或添加单个图标
    thirdPartyIcon, // 你可以导入任何SVG图标
    formkit: `<svg ...` // 或定义你自己的
  }
  ...
}).mount('#app')

输出图标

将图标添加到输入中

许多FormKit输入支持suffix和prefix图标。你可以在任何text类型的输入，如text，email，search，date等上使用prefix-icon和suffix-icon属性。这些属性也可以在select，color和range输入上使用。

select输入有一个select-icon属性，允许你更改用于选择输入的控制的图标。

file输入有file-remove-icon和file-item-icon属性：

使用自定义SVG图标

有时你需要在你的项目中渲染一个一次性的图标。你可以直接向图标属性提供一个SVG定义，SVG将为你渲染：

使用<FormKitIcon />组件

FormKit附带了一个名为<FormKitIcon />的组件，允许你在项目的任何地方输出iconRegistry中的任何图标。需要在FormKit的其他部分使用你正在使用的图标？没问题：

图标点击处理器

每个图标属性都注册了一个点击处理器属性。例如，prefix-icon属性将有一个对应的@prefix-icon-click属性。

每个点击处理器属性都接收输入的核心node和点击event作为参数。

使用第三方库

如果你想在你的FormKit项目中使用第三方图标集，你可以提供一个自定义的iconLoaderUrl或完整的iconLoader （全局，节点配置级别，或作为组件属性），它负责检索在iconRegistry中不存在的图标。

有时候 —— 在像表单构建器或CMS这样的情况下 —— 你无法预先知道你需要哪些图标。这就是远程加载图标的闪光点。

• iconLoaderUrl和iconLoader函数都会接收当前的iconName作为参数
• iconLoaderUrl的返回值应该是一个URL，指向一个可以找到图标SVG的远程CDN。这是改变备用加载行为的最简单的方式。
• 如果你需要更多的控制，使用iconLoader，它允许替换所有的远程图标获取逻辑。这个函数应该返回一个Promise，解析为string（SVG）或undefined。
• 你只需要使用iconLoaderUrl或iconLoader —— 如果你提供了两者，那么iconLoader优先。

使用自定义的iconLoaderUrl与FontAwesome一起使用

下面是一个FormKit从FontAwesome加载图标的实现，通过替换iconLoaderUrl为一个不同的CDN路径。

一个Heroicons的iconLoader示例

下面是一个FormKit的实现，它有一个完全自定义的iconLoader，它从Heroicons获取缺失的图标，而不是从FormKit图标集获取。