formkit-core-skilld

@formkit/core 2.1.2

FormKit 的框架无关核心。每个输入、组、列表和表单都是树中的一个 FormKitNode。Vue 和 React 适配器（@formkit/vue、 @formkit/react）负责渲染这些节点；输入类型、验证和 i18n 位于同级软件包中，不在此处。请将此 Skill 的范围限定为仅使用 @formkit/core 导入。

• 软件包：@formkit/[email protected]，采用 ESM（"type": "module"），并提供 CJS 回退， 以及 development 条件构建（package.json:8-21）。
• 唯一依赖项：@formkit/utils@^2.1.2（package.json:38-40）。
• 文档：https://formkit.com/essentials/architecture
• API 参考：https://formkit.com/api-reference/core

何时使用其他软件包

需求	软件包
<FormKit> 组件、defaultConfig、createInput	@formkit/vue / @formkit/react
输入类型定义（text、select…）	@formkit/inputs
验证规则	@formkit/validation
区域设置消息	@formkit/i18n
Schema 渲染	@formkit/vue（类型和编译器位于此处）

公共 API

运行时导出（dist/index.mjs:1919）：bfs、clearErrors、compile、 createClasses、createConfig、createMessage、createNode、 createPlaceholder、createValue、deregister、error、errorHandler、 generateClassList、getNode、isComponent、isConditional、isDOM、 isList、isNode、isPlaceholder、isSugar、names、register、reset、 resetCount、resetRegistry、setErrors、stopWatch、submitForm、 sugar、use、useIndex、valueInserted、valueMoved、valueRemoved、 warn、warningHandler、watchRegistry、FORMKIT_VERSION，以及约 70 个公共 类型（dist/index.d.mts:2329）。

常见任务

创建节点树

import { createNode } from '@formkit/core'

const email = createNode({ name: 'email' })
const form = createNode({
  type: 'group',            // 'input' (default) | 'group' | 'list'
  children: [email, createNode({ name: 'password' })],
})
form.at('email')            // → the email node

组的值是以子节点 name 为键的对象；列表的值是以子节点索引为键的数组（dist/index.mjs:714-723）。完整选项表： 节点 API。

设置值并等待完成

await email.input('[email protected]')  // debounced, async commit
email.value                            // committed value

切勿直接赋值 node.value = x。input() 会进行防抖（输入节点默认 20 ms，dist/index.mjs:1255-1267），然后通过 commit 钩子提交（dist/index.mjs:759-765）。当整个子树完成提交后，await node.settled 会解析（dist/index.d.mts:1856-1860）。

监听事件（并清理）

const receipt = form.on('commit.deep', ({ payload }) => { ... })
// later:
form.off(receipt)

.deep 会捕获从后代节点冒泡的事件（dist/index.mjs:47-53）。 on() 会返回一个凭据；务必将其传递给 off()。核心事件表： 事件和钩子。

注册钩子中间件

node.hook.commit((value, next) => next(transform(value)))

中间件签名为 (payload, next) => next(payload)；钩子包括： classes、commit、error、setErrors、init、input、message、 prop、text、schema（dist/index.d.mts:579-600）。在插件中注册以便复用。

编写插件

import { createNode } from '@formkit/core'
import type { FormKitPlugin } from '@formkit/core'

const colorize: FormKitPlugin = (node) => {
  node.props.color = node.type === 'group' ? 'yellow' : 'teal'
  // return false to stop inheritance by children
}
createNode({ type: 'group', plugins: [colorize], children: [createNode()] })

插件会被后代节点继承，并在每个节点上运行一次。附加 plugin.library，通过 node.define() 定义自定义输入类型。

存储消息；使用 ledger 计数

import { createMessage, createNode } from '@formkit/core'

const node = createNode()
node.store.set(createMessage({ key: 'limit', value: 'Too many!' }))
node.store.limit.value                       // 'Too many!'
node.ledger.count('visible', (m) => m.visible)
node.on('count:visible', ({ payload }) => console.log(payload))

详情：存储和 ledger。

通过 id 查找节点

import { createNode, getNode, watchRegistry, stopWatch } from '@formkit/core'

const node = createNode({ props: { id: 'manufacturer' } }) // root nodes register
getNode('manufacturer')                    // FormKitNode | undefined
const receipt = watchRegistry('manufacturer', (e) => { ... })
stopWatch(receipt)

根节点（或带有 props.alias 的节点）会自动注册（dist/index.d.mts:2220-2228）。详情： 注册表和辅助函数。

设置错误、重置、提交

import { setErrors, clearErrors, reset, submitForm } from '@formkit/core'

setErrors('myForm', 'Server rejected', { email: ['Already taken'] })
reset('myForm', { email: '' })   // resetTo becomes the new initial value
clearErrors('myForm', true)      // true clears children too
submitForm('myForm')             // dispatches a submit DOM event

编译 schema 表达式

import { compile } from '@formkit/core'

const condition = compile("$name == 'bob'").provide((tokens) => {
  return { name: () => nameRef.value }   // each token must return a function
})
condition()  // false

运算符：&& || == != === !== > < >= <= + - * / %（dist/index.mjs:1574-1598）。 Schema 节点类型和守卫：schema 和编译器。

防止错误的行为规则

• 通过 node.props（而非 node.config）读取配置；显式 props 和父级配置会合并到 props 中（dist/index.d.mts:729-792）。
• 设置根配置属性时，源节点会触发 config:{prop}，每个未覆盖该属性的继承节点都会触发 prop / prop:{prop}（dist/index.mjs:1283-1289）。
• group 节点要求值为对象，list 节点要求值为数组；违反要求会抛出错误 107 / 108（dist/index.mjs:745-757）。
• 消息是不可变的（Readonly<FormKitMessageProps>，dist/index.d.mts:70-75）；请通过 store.set() 替换，切勿直接修改。
• node.walk() 会遍历子树（不包括节点自身），且开销较大；仅在少数生命周期时刻使用（dist/index.d.mts:1885-1890）。
• 避免在同一父节点下出现两个同名（name）同级节点；若无法避免，请使用 config.mergeStrategy = { fieldName: 'synced' } 同步它们（dist/index.d.mts:721-725）。
• 每次读取 node.root 都会执行遍历；请勿在热路径中调用（dist/index.d.mts:1840-1843）。
• 如需替换核心错误处理，请在导出的 errorHandler / warningHandler 分发器上注册中间件（dist/index.d.mts:2151-2157）。

版本限制

• 本文档基于 @formkit/[email protected] 编写（发布于 2026-07-24）。
• 自 2.0.0 起，2.x 的变更均为针对重置、注册表清理和编译器的错误修复；核心 API 没有破坏性变更。请参阅 API 变更。
• 在准备好的源码中，FORMKIT_VERSION 是构建时占位符（"__FKV__"）；请勿根据它进行分支判断（dist/index.d.mts:2321-2327）。

参考资料

• 节点 API — 创建、类型、陷阱、值流、结算、遍历
• 事件和钩子 — 事件发射器、回执、.deep、事件表、钩子中间件
• 存储和账本 — 消息、createMessage、计数器
• 配置、props 和插件 — 继承、createConfig、mergeStrategy、库
• Schema 和编译器 — Schema 节点类型、守卫、sugar()、compile()
• 注册表和辅助工具 — getNode、setErrors、reset、submitForm、错误代码
• API 变更 — 2.0.0 → 2.1.2