图标

• 可用图标
• 安装和设置
  • 如果您的项目使用自定义配置
• 注册图标
  • 图标如何加载？
  • 将图标添加到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://...`, // 加载远程图标的URL
  iconLoader: (iconName) => {}, // 用于比iconLoaderUrl更直接的控制的函数
  ...
}).mount('#app')

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

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

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

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并返回可以加载图标的URL的函数。查看示例
• iconLoader：一个接收iconName并返回一个解析为SVG（作为字符串）或undefined的Promise的函数。当您需要比仅覆盖iconLoaderUrl更多的控制时，请使用此函数。查看示例

安装主题插件后，您的FormKit输入框将具有可用的图标属性。

注册图标

图标如何加载？

FormKit在尝试加载图标时经过4个步骤，按顺序如下：

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

因为FormKit会为图标使用CDN请求作为备选方案，所以您可以通过将支持的图标名称提供给输入框的图标属性来轻松地在新项目中开始使用 - 它们将自动加载给您 - 无需额外的设置！🪄

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

将图标添加到iconRegistry

魔术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的输入框上使用prefix-icon和suffix-icon属性，例如text、email、search、date等。这些属性也适用于select、color和range输入框。

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

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

使用自定义SVG图标

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

使用<FormKitIcon />组件

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

图标点击处理程序

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

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

使用第三方库

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

有时候，比如表单构建器或CMS，您事先不知道需要哪些图标。这就是远程加载图标的优势所在。

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

使用自定义iconLoaderUrl的FontAwesome

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

一个示例Heroicons iconLoader

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