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
— 当输入“完成”时出现。旨在用于在用户完成填写输入时为输入提供样式(如绿色复选标记)。阅读关于 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-
前缀类:
除了上面列出的四种方法外,还有更通用的覆盖方法,如覆盖输入的模式、使用 classes
节点钩子或使用插槽:
修改 FormKit 输入中元素的类的最简单方法是通过 {section-key}-class
属性。要将类添加到特定的部分元素,如 label
,只需添加 label-class
属性:
类属性类似于 section-key 类属性,只是它允许同时设置所有部分的类:
类配置选项类似于类属性,只是它适用于应用配置的所有输入。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
}
},
},
由于配置会传递给后代输入,您可以在父级(如 form
、list
或 group
)上通过配置更改类,这将影响任何深度的所有后代:
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 主题吗?我们编写了一篇指南,介绍了使用内联类 props 以及使用 FormKitVariants
插件和 @formkit/themes
中的 generateClasses
辅助函数创建全局 Tailwind 主题的过程。
该指南以完整再现用 Tailwind 编写的 FormKit Genesis CSS 主题结束。