@ formie/ 客户端
JavaScript和TypeScript为前作公共API和公共运行时间提供的帮助.
软件包为公共 API 路由构建 URL,干净的运行时间路由, 主机页面,并嵌入脚本。 它提交形式有效载荷,验证部分有效 将 API 错误代码映射到默认消息中 曝光每个字段多个验证问题的助手.
软件包
此寄存器包含公开的 Formerie JavaScript SDK 包 :
@formerie/client:框架中性JavaScript和TypeScript客户端.@formerie/client/element页:1<formerie-form>自定义元素,用于任何框架或平面 HTML.@formerie/react:反应钩.@formerie/vue: Vue可调和.@formerie/svelte: Svelte商店,以及@formerie/svelte/kit为 SvelteKit 组成动作.@formerie/solid:固体原始人.@formerie/angular: Angular service and sign series. (原始内容存档于2018-09-30). : Angular service and printing series.@formerie/astro: Astro 帮助 Formerie 的 Astro 属性和客户端设置.@formerie/next: Next.js 服务器动作和反应钩.@formerie/nuxt: Nuxt 服务器处理器和 Vue composables.@formerie/react-router:反应路由器路由动作和反应钩.
框架包是薄的适配器 @formerie/client。它们不重复请求路由、响应解析、验证错误处理或API安全行为.
目标对象按其标识在某形式上: { form: "fm_t77txbvg43nmar" }。要通过您的主机名发送,请添加 endpoint 选项,并保留同一ID.
框架条目点
| 项目类型 | 从浏览器提交 | 从服务器提交 |
|---|---|---|
| 普通 HTML 或浏览器 JavaScript | @formerie/client/element 或者说 @formerie/client | 直接 HTTP API或 @formerie/client |
| 反应 | @formerie/react | submitFormerieRequest 从 @formerie/client |
| 下一个.js | @formerie/next 客户端组件 | createFormerieNextAction 从 @formerie/next |
| 反应路由器 | @formerie/react-router 钩子 | createFormerieReactRouterAction 从 @formerie/react-router |
| 阴道 | @formerie/vue | submitFormerieRequest 从 @formerie/client |
| 坚果 | @formerie/nuxt 组件 | createFormerieNuxtSubmitHandler 从 @formerie/nuxt |
| 斯维尔特,斯维尔特基特 | @formerie/svelte | createFormerieAction 从 @formerie/svelte/kit |
| 固态, 固态启动 | @formerie/solid | submitFormerieFormData 从 @formerie/client |
| 角质 | @formerie/angular | submitFormerieRequest 从 @formerie/client |
| 天体 | @formerie/astro 属性, @formerie/client/element 在页面中 | submitFormerieRequest 从 @formerie/client |
| Qwik, Preact, Lit, Web 组件 | @formerie/client/element | submitFormerieFormData 从 @formerie/client |
对于没有专用适配器的框架,使用 @formerie/client
直接存在于服务器路由,动作,浏览器脚本,或自定义UI组件.
自定义元素
<formerie-form> 在任何框架或普通的HTML中,从公共计划中生成一种形式:
<script type="module">
import "@formerie/client/element";
</script>
<formerie-form form="fm_t77txbvg43nmar"></formerie-form>
表格在光线DOM中生成,所以您的网站的 CSS 样式,它的提交直接从
浏览器,所以您的站点必须是表格允许的出处 。 燃烧 formerie:success 财务报告和审定财务报表
formerie:error,答复为 detail添加 mode="iframe" 显示主机页面,
拥有自己的品牌 和步骤 不允许的起源设置.
没有捆绑,装入 dist/browser/formerie-element.js。 。 。 .
在 React TypeScript 项目中,一次声明标签:
import type { FormerieFormAttributes } from "@formerie/client/element";
declare module "react" {
namespace JSX {
interface IntrinsicElements {
"formerie-form": FormerieFormAttributes;
}
}
}
从您的服务器提交
submitFormerieRequest() 财务报告和审定财务报表 submitFormerieFormData() 发送您服务器收到的表格 。 他们动了
a 解答后转接或转接回接卡 verificationToken,并发送页面的
Origin ,因为服务器比较了符号的主机名与 Origin表格
因此,核查需要您在允许的来源。 没有标志,他们送不 Origin, (中文(简体) ),
因此不需要允许的出身.
您的服务器发送请求, 所以每位访客共享您的服务器地址 。 默认限制
每名访客每10分钟提交30份申请,然后适用于所有人。 抬起它,或者用一个
deviceToken 费率限制和通过 metadata: { deviceToken } 每个访客.
用服务器密钥通过 apiKey从您服务器上的秘密,和 visitorIp。它们只在服务器上工作:任何地方
他们扔出一页,却一无所获。 见 服务器密钥。 。 。 .
一种形式的两种语言
<FormerieForm form="fm_t77txbvg43nmar" locale="fr-CA" />
服务器选择窗体提供的最接近的语言. 变动 locale,或打电话 setLocale() 控制器,和
访客的答案留下。 在服务器上通过 locale 随你怎么说 因为服务器读不出来 <html lang>内
服务器上无任何内容的浏览器,窗体通过 <html lang>。见
两种语言的表格。 。 。 .
更改日志
见 变动情况 整个Formerie的公开发行笔记 JavaScript SDK 软件包.
安装
npm install @formerie/client
pnpm add @formerie/client
yarn add @formerie/client
bun add @formerie/client
对框架适配器使用相同的包管理命令形状 :
npm install @formerie/react
npm install @formerie/vue
npm install @formerie/svelte
npm install @formerie/astro
npm install @formerie/next
npm install @formerie/nuxt
npm install @formerie/react-router
API 使用量
import { FormerieClient } from "@formerie/client";
const forms = new FormerieClient();
const result = await forms.submit("fm_t77txbvg43nmar", {
fields: {
name: "Jane Example",
email: "[email protected]",
message: "Hello",
},
verificationToken: captchaToken,
});
FormerieClient 默认为 https://forms.formerie.com,其中表格的地址是其身份证.
运行时间使用
使用 FormerieClient 用于运行时间路径 forms.formerie.com
或经核实的客户主机名.
默认前置运行时主机 :
import { FormerieClient } from "@formerie/client";
const forms = new FormerieClient();
const hostedUrl = forms.hostedUrl("fm_t77txbvg43nmar");
const embedScriptUrl = forms.embedScriptUrl();
await forms.submit("fm_t77txbvg43nmar", {
fields: {
email: "[email protected]",
},
});
通过您自己核实的主机名发送使用相同的ID:
const forms = new FormerieClient({
endpoint: "https://forms.customer.com",
});
await forms.submit("fm_t77txbvg43nmar", {
fields: {
email: "[email protected]",
},
});
Schema 和窗体辅助工具
SDK包括用于自定义渲染器的小型运行时间助手、本地形式以及 框架整合。 这些辅助工具用于展示、有效载荷塑造和 错误演示文稿; Formerie 运行时 API 仍然具有权威性 可见度执行、验证、垃圾邮件检查、路由和交付.
使用 describeFormerieRenderModel 当您想要自建出自
在保持Formerie的公共领域元数据、能见度和
在一个位置的步组 :
import {
describeFormerieRenderModel,
FormerieClient,
} from "@formerie/client";
const forms = new FormerieClient();
const schema = await forms.schema("fm_t77txbvg43nmar");
if (schema.ok) {
const renderModel = describeFormerieRenderModel(schema, {
preferredContactMethod: "email",
});
for (const field of renderModel.fields) {
console.log(field.path, field.control, field.visibility);
}
}
模型显示 fields, (中文(简体) ), fieldsByPath公开 steps,以及
unsteppedFields。字段描述符包括安全浏览器元数据,例如
标签、描述、占位符、选项、输入类型、输入模式、,
限制、名称、当前值和能见度状态.
import {
FormerieClient,
createFormerieSubmitPayload,
evaluatePublicFieldVisibility,
listPublicSchemaFields,
validationMessagesByField,
} from "@formerie/client";
const forms = new FormerieClient();
const schema = await forms.schema("fm_t77txbvg43nmar");
if (schema.ok) {
const fields = listPublicSchemaFields(schema);
const visibility = evaluatePublicFieldVisibility(schema, {
preferredContactMethod: "email",
});
}
const formElement = document.querySelector<HTMLFormElement>("form");
if (!formElement) {
throw new Error("Form is not ready.");
}
const payload = createFormerieSubmitPayload(new FormData(formElement), {
schema: schema.ok ? schema : undefined,
verificationToken: captchaToken,
});
const result = await forms.submit("fm_t77txbvg43nmar", payload);
const messages = validationMessagesByField(result);
对于普通浏览器上载, 让 SDK 加载公共计划并提交到 运行时间客户端 :
import {
FormerieClient,
mountFormerieRuntimeForm,
} from "@formerie/client";
const forms = new FormerieClient();
await mountFormerieRuntimeForm("#contact-form", {
client: forms,
target: {
form: "fm_t77txbvg43nmar",
},
resetOnSuccess: true,
});
mountFormerieRuntimeForm 装入选定运行时间的公共计划
目标,使公共计划领域,保护公共步骤和对象群体
作为字段, 当答案改变时, 保持公共可见度规则同步, 禁用
隐蔽控制使其远离提交有效载荷,使公众能够核查
当计划需要时, 钩子会装入浏览器验证提供者
脚本,形状提交有效载荷,在请求时禁用提交按钮
中,并显示服务器验证错误。 如果你的应用程序已经有一个
计划, 使用 mountFormerieForm 直接说 如果您的页面已经生成
<form data-formerie-form> 外壳, 使用 bindFormerieForm 附加同样内容
提交、验证、状况、核查符号收藏和能见度
行为而不替换已有的 HTML .
包括公共计划 JSON 脚本在内的服务器发送页面
bindFormerieHostedForm() 作为现有 HTML 的单调版本; 它读取
<script type="application/json" data-formerie-schema> 和约束 所做出
形式。 生成主机贝壳可调用 mountFormerieForm() 同样的
公共计划加后端自有 submitUrl。这些帮助者收集
Turnstile/reCAPTCHA 浏览器安全验证属性的响应符,
提交尝试后重置部件, 可以添加保险箱 pageUrl 包含
只有当前来源和路径(从未查询参数或片段)。 他们
可通过明确的 submitUrl 或已作出的
data-formerie-submit-path 属性。 使用 syncFormerieFormVisibility 何时
围绕 Formerie 数据属性构建自定义渲染器。 使用
collectFormerieVerificationToken, (中文(简体) ),
applyFormerieVerificationError,以及 resetFormerieVerificationWidget 当 a
自定义渲染器想要直接拥有验证 UI 。 使用
renderFormerieVerificationHtml 当自定义主机页面需要浏览器安全时
转动或重回CAPTCHA部件标记 从公共计划。 生成窗体
贝壳接受用于向导输出的 public 渲染选项, CSS 类 hooks, 和 a
当您的服务器配置到检查一个时,可选的蜂蜜壶字段。 通过一个
明确 verificationToken 仅在您的自定义 UI 不曝光时提供
标准验证属性和反应字段。 公众
schema只包括浏览器安全验证数据,例如提供者和
站点密钥。 最后审定、垃圾邮件检查、核查、交付和验收
留在Forerie 运行时间 API.
CDN 使用量
软件包发布浏览器捆绑 dist/browser。浏览器片段可以
从不可改变的Formerie CDN URL或从 npm CDN 如 jsDelivr 中装入前列.
经典脚本标签 :
<script src="https://cdn.formerie.com/client/v0.1.0-alpha.15/formerie.iife.js"></script>
<script>
const forms = new Formerie.FormerieClient({
endpoint: "https://forms.customer.com",
});
forms.submit("fm_t77txbvg43nmar", {
fields: {
email: "[email protected]",
},
});
</script>
浏览器无害环境管理 :
<script type="module">
import { FormerieClient } from "https://cdn.formerie.com/client/v0.1.0-alpha.15/formerie.es.js";
const forms = new FormerieClient({
endpoint: "https://forms.customer.com",
});
</script>
自定义 Iframe 挂载 :
<script src="https://cdn.formerie.com/client/v0.1.0-alpha.15/formerie.iife.js"></script>
<div id="contact-frame"></div>
<script>
Formerie.mountFormerieEmbed({
endpoint: "https://forms.customer.com",
form: "fm_t77txbvg43nmar",
target: "#contact-frame",
});
</script>
Formerie.mountFormerieEmbed(...) 读取相同的公众 data-formerie-form, (中文(简体) ),
data-formerie-target, (中文(简体) ), data-formerie-title,以及 data-formerie-height
formerie 运行时收到脚本时嵌入脚本所使用的属性
键.
剪接片段应使用不可改变的版本路径 :
<script src="https://cdn.formerie.com/client/vX.Y.Z/formerie.iife.js"></script>
这个 /client/latest/ 化名是用于演示和手动的移动方便化名
测试。 生产页应固定一个不可改变的版本路径.
npm CDN 后退 :
<script src="https://cdn.jsdelivr.net/npm/@formerie/client/dist/browser/formerie.iife.js"></script>
国 际 人工智能技能
安装 @formerie/client 揭露 formerie 软件包管理脚本和本地二进制解析中的 CLI 命令 .
pnpm exec formerie ai detect
pnpm exec formerie ai setup
Npm 项目:
npm exec -- formerie ai setup
在不添加软件包的情况下运行安装器 :
npx --package @formerie/client formerie ai setup
CLI可以检测支持的AI工具并安装为Codex或Claude代码所捆绑的Formerie技能:
pnpm exec formerie skills install codex
pnpm exec formerie skills install codex --project
pnpm exec formerie skills install codex --path .codex/skills/formerie
pnpm exec formerie skills install claude
pnpm exec formerie skills install claude --project
安装的技巧教导AI编码代理商Formerie安全边界:公共客户端提交字段,验证符,以及仅安全元数据;接收者,提供者证书,模板,交付规则停留在服务器侧.
框架实例
import { FormerieForm } from "@formerie/react"; // Also @formerie/next and @formerie/react-router
<FormerieForm form="fm_t77txbvg43nmar" />
<script setup>
import { FormerieForm } from "@formerie/vue"; // Auto-imported with the @formerie/nuxt/module module
</script>
<template><FormerieForm form="fm_t77txbvg43nmar" /></template>
<script>
import { FormerieForm } from "@formerie/svelte";
</script>
<FormerieForm form="fm_t77txbvg43nmar" />
import { FormerieForm } from "@formerie/solid";
<FormerieForm form="fm_t77txbvg43nmar" />
import { FORMERIE_COMPONENTS } from "@formerie/angular";
@Component({ imports: [FORMERIE_COMPONENTS], template: `<formerie-form form="fm_t77txbvg43nmar" />` })
export class ContactPage {}
---
import FormerieForm from "@formerie/astro/FormerieForm.astro";
---
<FormerieForm form="fm_t77txbvg43nmar" />
每个软件包的README显示替换了窗体的一部分,并保留了自己的标记.
---
import { createFormerieFormAttributes } from "@formerie/astro";
const attrs = createFormerieFormAttributes({
form: "fm_t77txbvg43nmar",
});
---
<form {...attrs}>
<input name="email" type="email" />
</form>
许可证
麻省理工学院.