Formisch安装教程:React、Vue、Svelte、Angular等8大框架配置一次讲清
Formisch安装教程:React、Vue、Svelte、Angular等8大框架配置一次讲清
Formisch 是一款轻量、Schema 优先且完全类型安全的表单库,支持 React、Vue、Svelte、Solid、Angular、Preact、Qwik 和 React Native 等 8 大框架。本文带你完成 Formisch 安装:从依赖版本要求、各框架安装命令,到 useForm、createForm、injectForm 等入口 API 的差异,一篇讲清,10 分钟即可在任意主流框架项目中跑起第一个表单。
一、30 秒认识 Formisch:为什么选择它 🧩
Formisch 采用「共享内核 + 框架适配层」的架构:
- 内核层
@formisch/core负责表单状态与校验逻辑,构建时自动注入你所用框架的原生响应式代码块,因此每个框架下的性能都是原生的; - 方法层
@formisch/methods提供reset、setInput、handleSubmit等函数式 API,按需引入,包体积从 2.5 kB 起步; - 校验层 基于 Valibot 的 Schema 驱动,字段路径、数组、深层嵌套全部有 TypeScript 类型推导。
Valibot 类型推导演示:Formisch 表单校验的 Schema 类型安全示意/react-form-library-comparison/type-safe-issues.jpg)
这意味着 Formisch 安装一次、心智模型跨框架通用——写 React 和写 Svelte 的表单几乎是同一套代码思路。
二、安装前准备:两个必做检查 ✅
1. 检查 TypeScript 版本
所有框架包要求 TypeScript >=5 <8(最低 v5.0.2),建议在 tsconfig.json 中开启 strict 模式,保证类型完整推导:
{
"compilerOptions": {
"strict": true
}
}
2. 先安装 Valibot
Valibot 是 Formisch 的 peer dependency(校验引擎),必须先装:
npm install valibot # npm
pnpm add valibot # pnpm
yarn add valibot # yarn
💡 如果忘记装 Valibot,安装 @formisch 相关包时会报 peer dependency 警告,类型推导也会缺失。
三、8 大框架安装命令速查表 📦
按框架选包,一条命令完成 Formisch 安装:
| 框架 | 安装包名 | 框架版本要求 |
|---|---|---|
| React | @formisch/react |
react >=16.8 <20 |
| Vue | @formisch/vue |
vue >=3.3 <4 |
| Svelte | @formisch/svelte |
svelte >=5.29 <6 |
| Angular | @formisch/angular |
@angular/core >=19 <23 |
| Solid | @formisch/solid |
solid-js >=1.6 <2 |
| Preact | @formisch/preact |
preact >=10 <11,另需 @preact/signals |
| Qwik | @formisch/qwik |
@qwik.dev/core >=2 <3 |
| React Native | @formisch/react-native |
react >=18 <20,react-native >=0.73 <1 |
以 React 为例(其余框架把包名替换即可):
npm install @formisch/react
# 或
pnpm add @formisch/react
Preact 用户注意:还需额外安装 @preact/signals(>=2),它是响应式更新的依赖。
四、各框架上手配置:入口 API 一张表看懂 🔑
Formisch 在 8 个框架中遵循统一的三步模型:创建表单 → 包裹 Form → 连接字段,只有入口 API 的名字随框架习惯而变:
| 框架 | 创建表单 | 字段连接 | 特殊说明 |
|---|---|---|---|
| React | useForm hook |
useField hook / <Field /> |
支持 React 16.8+ Hooks |
| Vue | useForm composable |
useField / <Field /> |
模板中用 v-slot="field" |
| Svelte | createForm rune |
useField / <Field /> |
仅支持 Svelte 5 |
| Angular | injectForm 函数 |
[formischControl] 指令 |
基于 Signals,兼容 zoneless 检测 |
| Solid | createForm primitive |
useField / <Field /> |
细粒度响应,无重渲染 |
| Preact | useForm hook |
useField / <Field /> |
依赖 Preact Signals |
| Qwik | useForm$ 信号 hook |
useField / <Field /> |
全部使用 $ 后缀的信号 API |
| React Native | useForm hook |
useField / <Field /> |
没有 <Form /> 组件,用 handleSubmit 触发提交 |
React 中最短上手示例(完整代码见 frameworks/react/README.md):
import { Field, Form, useForm } from '@formisch/react';
import * as v from 'valibot';
const LoginSchema = v.object({
email: v.pipe(v.string(), v.email()),
password: v.pipe(v.string(), v.minLength(8)),
});
export default function LoginPage() {
const loginForm = useForm({ schema: LoginSchema });
// <Form of={loginForm}> 内用 <Field> 连接 input 即可
}
其他框架写法与示例:
- Vue:frameworks/vue/README.md
- Svelte:frameworks/svelte/README.md
- Angular:frameworks/angular/README.md(含与 Reactive Forms / Signal Forms 的概念对照表)
- Solid / Preact / Qwik / React Native:各目录下的 README 均有对应示例
五、安装后常见问题排查 🔍
Q1:装完导入报「找不到模块」?
确认包名带 @formisch/ 前缀,且框架主包版本满足上表 peer dependency 要求。
Q2:为什么校验不生效?
检查是否安装了 valibot(>=1.4.1 <2);它是 Formisch 的 peer dependency,不会随包自动安装。
Q3:React Native 里没有 <Form />?
这是设计如此——原生环境没有 <form> 元素和 submit 事件,改用 handleSubmit(loginForm, callback),挂在按钮 onPress 或输入框 onSubmitEditing 上触发提交。
Q4:Vue 里怎么绑定输入值?
在 <Field> 的 v-slot="field" 插槽中,输入框用 v-model="field.input" 并展开 v-bind="field.props"。
Q5:AI 辅助开发能配 Formisch 吗?
官方提供 agent skills,让 AI 掌握 Valibot 与 Formisch 的正确写法,可用 npx skills add 一条命令安装(见各框架安装文档的 “For AI Agents” 一节,如 website/src/routes/(docs)/react/guides/(get-started)/installation/index.mdx/react/guides/(get-started)/installation/index.mdx))。
六、深入阅读:源码与示例导航 🗺️
| 资料 | 路径 |
|---|---|
| 框架无关内核 | packages/core/ |
| 函数式方法(reset/submit 等) | packages/methods/ |
| React 框架包 | frameworks/react/ |
| Vue 框架包 | frameworks/vue/ |
| Svelte 框架包 | frameworks/svelte/ |
| Angular 框架包 | frameworks/angular/ |
| 完整可运行示例(Svelte 发票表单) | examples/svelte-invoice-form/ |
| 各框架 Playground | playgrounds/ |
| 官方安装文档 | website/src/routes/(docs)//) |
写在最后
Formisch 安装的核心就三句话:装 valibot → 装 @formisch/<框架> → 按框架入口 API 建表单。得益于共享内核设计,8 大框架的用法几乎一致,学会一个框架等于学会了全部。配合 2.5 kB 起步的体积和端到端类型安全,它是 2026 年构建类型安全表单的高性价比选择。祝你项目顺利 🚀

