样式

FormKit 提供了健壮且易于访问的标记 —— 但不对您所需的样式做任何假设。有一个_可选_的基本主题(如本文档所示) 名为 Genesis,您可以在项目中使用。

安装 Genesis 主题

CDN 使用

要通过 CDN 加载 genesis,请将其提供给 defaultConfigtheme 属性。

...
defaultConfig({
  theme: 'genesis' // 将从 CDN 加载并注入到文档头部
})
...

直接导入

要安装 Genesis,请先安装 @formkit/themes 包。

npm install @formkit/themes

然后在您的 main.js(您启动 Vue 的地方)中包含 Genesis 的 theme.css(这假设您正在使用像 Vite、Webpack、Snowpack 或 Nuxt 这样的构建工具):

import '@formkit/themes/genesis'

外部属性

为了便于样式化,某些属性会自动添加到所有 FormKit 输入的 outer 部分并从中删除:

  • data-type — 输入类型,textselectcheckbox 等。
  • data-multiple — 对于接受 multiple 属性的输入,当输入具有多个属性时(如 select 输入),将附加此属性。
  • data-disabled — 当输入被禁用时出现。
  • data-complete — 当输入“完成”时出现。旨在用于在用户完成填写输入时为输入提供样式(如绿色复选标记)。阅读关于 context.state.complete 了解什么条件会导致这是 true
  • data-invalid — 当输入具有失败的验证规则且失败规则的消息可见时出现。
  • data-errors — 当输入具有显式设置的错误时出现。

您可以使用上述属性为填写表单的用户提供实时视觉反馈:

加载实时示例

自定义类

大多数用户将希望将自己的样式和类应用于 FormKit 提供的标记。 FormKit 提供了许多方法来应用您项目的类。

可以使用以下任何方法(从最高到最低特异性)修改所有部分的类:

类遵循严格的层次结构。最初,类由 rootClasses 函数生成。然后可以通过 classes 配置选项进行修改,然后通过 classes 属性,最后通过 {section-key}-class 属性。在这些阶段中,类可以附加重置有选择地修改

添加类

要添加一个类,只需返回要添加的字符串,或提供一个带有布尔值的类对象 — true 属性将被添加:

加载实时示例

重置类

通过在字符串格式或对象格式中提供一个特殊的(不渲染的)类 $reset,可以完全删除由所有早期层次结构步骤生成的类:

加载实时示例

移除类

通过为要移除的类提供值为 false 的对象,或者为以 $remove: 开头并与类列表中现有类匹配的 {section-key}-class 属性提供类名,可以有选择地移除由类层次结构的早期步骤生成的类。这包括移除 formkit 默认的 formkit- 前缀类:

加载实时示例
tip

除了上面列出的四种方法外,还有更通用的覆盖方法,如覆盖输入的模式、使用 classes 节点钩子或使用插槽:

Section-key 类属性

修改 FormKit 输入中元素的类的最简单方法是通过 {section-key}-class 属性。要将类添加到特定的部分元素,如 label,只需添加 label-class 属性:

加载实时示例

类属性

类属性类似于 section-key 类属性,只是它允许同时设置所有部分的类:

加载实时示例

类配置

类配置选项类似于类属性,只是它适用于应用配置的所有输入。FormKit 的独特配置系统允许您在项目中全局应用类或仅在某个组或表单中的输入:

全局类配置

加载实时示例

组、列表或表单上的类配置

加载实时示例

使用来自 @formkit/themes 的 generateClasses

FormKit 附带了一个名为 generateClasses 的辅助函数,包含在 @formkit/themes 中。

generateClasses 函数接受一个由输入类型键入的 javascript 对象,值为一个由 ${sectionKey} 键入的子对象,值为字符串。通过这个函数,您可以根据给定输入类型快速将类列表应用到输入内的部分。

加载实时示例

rootClasses 函数

rootClasses 是一个配置函数,负责生成每个元素的默认类。此函数已经有一个默认值,它生成所有默认类(如 formkit-outerformkit-label),这些类随 FormKit 一起提供 - 因此替换此单个函数可以轻松替换所有初始类。这使得它成为使用 Tailwind 等实用程序框架编写自定义主题的理想选择。

rootClasses 函数传递了 2 个参数(分别是):

该函数将为每个部分调用一次,它 必须 返回具有布尔值的类对象。

虽然 rootClasses 的典型用法是在全局配置级别应用类到整个项目 - 但您还可以使用 config 属性来覆盖项目中特定表单或输入的类列表,从您提供的函数中的逻辑计算:

加载实时示例
tip

因为 rootClasses 是一个配置选项,您可以在每个输入、每个组或全局应用它。

在 schema 中修改类

除了通过配置或属性 <FormKit> 组件上 修改类之外,您还可以在 schema 中使用相同的技术:

schema 中的部分键类属性

在 schema 中,您还可以通过 {section-key}Class 属性修改输入内元素的类。例如,要将类添加到标签部分,可以添加 labelClass 属性:

{
  $formkit: 'text',
  name: 'email',
  // 将 'appended-class' 添加到 "label" 部分
  labelClass: 'appended-class'
},

在 schema 中的 Classes prop

就像 <FormKit> 组件上的 classes prop 一样,您可以通过 schema 节点上的 classes 属性修改任何 section 的输入类列表:

{
  $formkit: 'text',
  name: 'email',
  // 修改此输入的 "outer" 和 "inner" 部分上的类
  classes: {
    outer: 'new-outer-class',
    inner: {
      $reset: true, // 重置 "inner" 部分上的类
      'new-inner-class': true
    }
  },
},

在 schema 中的 Config

由于配置会传递给后代输入,您可以在父级(如 formlistgroup)上通过配置更改类,这将影响任何深度的所有后代:

加载实时示例

Tailwind CSS

使用提供的 Genesis 主题

FormKit 附带了一个可选的默认 Tailwind 主题,名为 Genesis。要在您的项目中使用这个预制的 Tailwind 主题,请从 @formkit/themes/tailwindcss/genesis 导入它,并将其添加到您的 formkit.config.js。您还需要从 @formkit/icons 中包含必要的 genesisIcons 导入。

// formkit.config.js
import { generateClasses } from '@formkit/themes'
import { genesisIcons } from '@formkit/icons'
import genesis from '@formkit/themes/dist/tailwindcss/genesis'

export default {
  icons: {
    ...genesisIcons,
  },
  config: {
    classes: generateClasses(genesis),
  },
}

genesis 主题导入对于简洁性很好,但 Tailwind 解析器需要提供指向 node_modules 中完整主题文件的路径,以便知道正在使用哪些类。此外,您应该将 FormKitVariants 插件添加到 tailwind.config.js,以便在项目中使用诸如 formkit-invalid: 之类的有用 FormKit 变体。

// tailwind.config.js
const FormKitVariants = require('@formkit/themes/tailwindcss')

module.exports = {
  content: [
    './src/**/*.{html,js,vue}',
    './node_modules/@formkit/themes/dist/tailwindcss/genesis/index.cjs',
  ],
  plugins: [FormKitVariants],
}

创建您自己的 Tailwind CSS 主题

想要创建自己的 Tailwind 主题吗?我们编写了一篇指南,介绍了使用内联类 props 以及使用 FormKitVariants 插件和 @formkit/themes 中的 generateClasses 辅助函数创建全局 Tailwind 主题的过程。

该指南以完整再现用 Tailwind 编写的 FormKit Genesis CSS 主题结束。

指南:创建一个 Tailwind CSS 主题立即阅读