FormKit 提供了健壮且可访问的标记 —— 但不假设您
期望的样式。有一个 可选的 基础主题(如在这些文档中所见)
称为 Genesis
,您可以在您的项目中使用。
要通过 CDN 加载 genesis
,请将其提供给您的 defaultConfig
的 theme
属性。
...
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
— 输入类型,text
、select
、checkbox
等。data-multiple
— 对于接受 multiple
属性的输入,当输入具有多个属性时(如 select
输入),这将被追加。data-disabled
— 当输入被禁用时出现。data-complete
— 当输入是 "complete" 时出现。旨在用于在用户完成填写输入时为输入提供样式(如绿色对号)。阅读关于 context.state.complete
以获取什么条件会使这个为 true
的信息。data-invalid
— 当输入有失败的验证规则和对失败规则的消息可见时出现。data-errors
— 当输入有明确设置的错误时出现。您可以使用上述属性轻松为填写您的表单的用户提供实时视觉反馈:
大多数用户会希望将他们自己的样式和类应用到 FormKit 提供的标记。 FormKit 提供了许多方法来为您的项目应用类。
可以使用以下任何方法(从最高到最低特异性)修改所有 部分 的类:
{section-key}-class
属性。 (最具体)classes
属性。classes
配置选项。rootClasses
配置函数。 (最不具体)类遵循严格的层次结构。最初,类由 rootClasses
函数生成。然后可以由 classes
配置选项修改,然后由 classes
属性修改,最后由 {section-key}-class
属性修改。在这些阶段中,类可以被 追加,重置,或 选择性修改。
要添加一个类,只需返回你想要添加的字符串,或者提供一个带有布尔值的类对象 — true
属性将被添加:
通过提供一个特殊的(不渲染的)类 $reset
,可以完全删除所有早期层次步骤产生的类,无论是字符串格式还是对象格式:
可以通过提供一个对象,其值为 false
的类,你想要移除,或者通过提供一个以 $remove:
开头并与类列表中的现有类匹配的 {section-key}-class
属性的类名,来选择性地移除类层次中早期步骤产生的类。这包括移除 formkit 默认的 formkit-
前缀类:
除了上面列出的四种方法,还有更通用的覆盖方法,如覆盖输入的模式,使用 classes
节点钩子,或利用插槽:
修改 FormKit 输入中元素的类的最简单方法是通过 {section-key}-class
属性。要向特定部分元素添加类,如 label
,只需添加 label-class
属性:
Classes 属性与 section-key 类属性类似,只是它允许同时设置所有部分的类:
Classes 配置选项与 classes 属性类似,只是它适用于所有应用配置的输入。FormKit 的独特配置系统允许你在项目中全局应用类,或者只在某个组或表单中的输入上应用类:
FormKit 附带了一个名为 generateClasses
的辅助函数,包含在 @formkit/themes
中。
generateClasses
函数接受一个由输入类型键入的 javascript 对象,其值为由 ${sectionKey}
键入的子对象,其值为字符串。使用此函数,您可以根据给定输入的类型快速将类列表应用到输入内的各个部分。
rootClasses
是一个配置函数,负责生成每个元素的默认类。此函数已经有一个默认值,它生成所有默认类(如 formkit-outer
和 formkit-label
)随 FormKit 一起提供 - 因此替换这个单一函数可以让你轻松替换所有初始类。这使它成为使用像 Tailwind 这样的实用框架编写自定义主题的理想选择。
rootClasses
函数传递了2个参数(分别是):
该函数将为每个部分调用一次,它 必须 返回带有布尔值的类的对象。
虽然 rootClasses
的典型用法是在全局配置级别应用类到你的整个项目 - 你也可以使用 config
属性来覆盖你的项目中的特定表单或输入,使用从你提供的函数中的逻辑计算出的类列表:
因为 rootClasses
是一个配置选项,你可以按输入、按组或全局应用它。
除了通过配置或属性 在 <FormKit>
组件上 修改类,你还可以在 schema 中使用相同的技术:
在 schema 中,你还可以通过 {section-key}Class
属性修改输入内元素的类。例如,要向标签部分添加一个类,你可以添加 labelClass
属性:
{
$formkit: 'text',
name: 'email',
// 将 'appended-class' 添加到 "label" 部分
labelClass: 'appended-class'
},
就像<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
}
},
},
由于config会传递给后代输入,所以你可以通过父级(如form
、list
或group
)上的config修改类,这将影响到任何深度的所有后代:
如果你还没有添加 Tailwind CSS 到你的项目中,请按照他们的安装说明进行操作。
FormKit 提供了一个 Genesis 主题的 Tailwind 版本,你可以在你自己的项目中作为起点使用。要使用这个预制的 Tailwind 主题,将以下主题复制到你的项目中的一个文件(比如 tailwind-theme.js
)。
现在,将你的 Tailwind 主题导入到你的 formkit.config
文件中,并将其添加到你的项目配置中。
你需要从 @formkit/themes
包中导入 generateClasses
辅助函数,以及从 @formkit/icons
包中导入支持的图标。
npm install @formkit/themes @formkit/icons
// formkit.config.js
import { generateClasses } from '@formkit/themes'
import { genesisIcons } from '@formkit/icons'
import myTailwindTheme from './tailwind-theme.js' // 更改为你的主题路径
export default {
icons: {
...genesisIcons,
},
config: {
classes: generateClasses(myTailwindTheme),
},
}
接下来,将你的主题路径添加到你的 tailwind.config
文件的内容数组中 —— 这是必需的,以便 Tailwind 知道你在项目中使用了哪些类。
此外,你应该将 FormKitVariants
插件添加到你的 tailwind.config.js
文件中,从 @formkit/themes
包中,以便在你的项目中使用 FormKit 提供的变体,如 formkit-invalid:
。
// tailwind.config.js
const FormKitVariants = require('@formkit/themes/tailwindcss')
module.exports = {
content: [
...
'./tailwind-theme.js',
],
plugins: [FormKitVariants],
}
想要创建你自己的Tailwind主题吗?我们编写了一份指南,通过使用内联类props以及使用FormKitVariants
插件和@formkit/themes
中的generateClasses
辅助函数,引导你完成整个过程,以创建全局Tailwind主题。
该指南以完全用Tailwind编写的FormKit Genesis CSS主题作为结尾。