# @formerie/client 中文文档

规范地址：https://npmcn.com/package/%40formerie/client/

版本：0\.1\.0-alpha\.15
npm 元数据更新时间：2026-11-03T04:19:33.774Z
中文译文更新时间：2026-11-15T08:40:27.562Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40formerie/client
原文对照：https://npmcn.com/package/%40formerie/client/?lang=original
项目主页：https://formerie.com/
源码仓库：https://github.com/Formerie/formerie-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.3 MB，191 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-26T03:20:20.052Z
- 最新版本发布：2026-11-03T04:19:33.598Z
- 近 30 天下载量：2808（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

JavaScript和TypeScript客户端的帮助器,用于Formerie公共API和运行时间.

## 安装

```sh
npm install @formerie/client
```

也可以使用：`pnpm add @formerie/client`、`yarn add @formerie/client`、`bun add @formerie/client`

## README

# @ 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中,从公共计划中生成一种形式:

```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 项目中,一次声明标签:

```ts
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`。它们只在服务器上工作:任何地方 他们扔出一页,却一无所获。 见 [服务器密钥](https://formerie.com/docs/server-keys)。 。 。 .

## 一种形式的两种语言

```tsx
<FormerieForm form="fm_t77txbvg43nmar" locale="fr-CA" />
```

服务器选择窗体提供的最接近的语言. 变动 `locale`,或打电话 `setLocale()` 控制器,和 访客的答案留下。 在服务器上通过 `locale` 随你怎么说 因为服务器读不出来 `<html lang>`内 服务器上无任何内容的浏览器,窗体通过 `<html lang>`。见 [两种语言的表格](https://formerie.com/docs/multi-language-forms)。 。 。 .

## 更改日志

见 [变动情况](https://npmcn.com/package/%40formerie/client/CHANGELOG.md) 整个Formerie的公开发行笔记 JavaScript SDK 软件包.

## 安装

```bash
npm install @formerie/client
```

```bash
pnpm add @formerie/client
```

```bash
yarn add @formerie/client
```

```bash
bun add @formerie/client
```

对框架适配器使用相同的包管理命令形状 :

```bash
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 使用量

```ts
import { FormerieClient } from "@formerie/client";

const forms = new FormerieClient();

const result = await forms.submit("fm_t77txbvg43nmar", {
  fields: {
    name: "Jane Example",
    email: "jane@example.com",
    message: "Hello",
  },
  verificationToken: captchaToken,
});
```

`FormerieClient` 默认为 `https://forms.formerie.com`,其中表格的地址是其身份证.

## 运行时间使用

使用 `FormerieClient` 用于运行时间路径 `forms.formerie.com` 或经核实的客户主机名.

默认前置运行时主机 :

```ts
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: "jane@example.com",
  },
});
```

通过您自己核实的主机名发送使用相同的ID:

```ts
const forms = new FormerieClient({
  endpoint: "https://forms.customer.com",
});

await forms.submit("fm_t77txbvg43nmar", {
  fields: {
    email: "jane@example.com",
  },
});
```

## Schema 和窗体辅助工具

SDK包括用于自定义渲染器的小型运行时间助手、本地形式以及 框架整合。 这些辅助工具用于展示、有效载荷塑造和 错误演示文稿; Formerie 运行时 API 仍然具有权威性 可见度执行、验证、垃圾邮件检查、路由和交付.

使用 `describeFormerieRenderModel` 当您想要自建出自 在保持Formerie的公共领域元数据、能见度和 在一个位置的步组 :

```ts
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`。字段描述符包括安全浏览器元数据,例如 标签、描述、占位符、选项、输入类型、输入模式、, 限制、名称、当前值和能见度状态.

```ts
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 加载公共计划并提交到 运行时间客户端 :

```ts
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 中装入前列.

经典脚本标签 :

```html
<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: "jane@example.com",
    },
  });
</script>
```

浏览器无害环境管理 :

```html
<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 挂载 :

```html
<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 运行时收到脚本时嵌入脚本所使用的属性 键.

剪接片段应使用不可改变的版本路径 :

```html
<script src="https://cdn.formerie.com/client/vX.Y.Z/formerie.iife.js"></script>
```

这个 `/client/latest/` 化名是用于演示和手动的移动方便化名 测试。 生产页应固定一个不可改变的版本路径.

npm CDN 后退 :

```html
<script src="https://cdn.jsdelivr.net/npm/@formerie/client/dist/browser/formerie.iife.js"></script>
```

## 国 际 人工智能技能

安装 `@formerie/client` 揭露 `formerie` 软件包管理脚本和本地二进制解析中的 CLI 命令 .

```bash
pnpm exec formerie ai detect
pnpm exec formerie ai setup
```

Npm 项目:

```bash
npm exec -- formerie ai setup
```

在不添加软件包的情况下运行安装器 :

```bash
npx --package @formerie/client formerie ai setup
```

CLI可以检测支持的AI工具并安装为Codex或Claude代码所捆绑的Formerie技能:

```bash
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安全边界:公共客户端提交字段,验证符,以及仅安全元数据;接收者,提供者证书,模板,交付规则停留在服务器侧.

## 框架实例

```tsx
import { FormerieForm } from "@formerie/react"; // Also @formerie/next and @formerie/react-router

<FormerieForm form="fm_t77txbvg43nmar" />
```

```vue
<script setup>
import { FormerieForm } from "@formerie/vue"; // Auto-imported with the @formerie/nuxt/module module
</script>

<template><FormerieForm form="fm_t77txbvg43nmar" /></template>
```

```svelte
<script>
  import { FormerieForm } from "@formerie/svelte";
</script>

<FormerieForm form="fm_t77txbvg43nmar" />
```

```tsx
import { FormerieForm } from "@formerie/solid";

<FormerieForm form="fm_t77txbvg43nmar" />
```

```ts
import { FORMERIE_COMPONENTS } from "@formerie/angular";

@Component({ imports: [FORMERIE_COMPONENTS], template: `<formerie-form form="fm_t77txbvg43nmar" />` })
export class ContactPage {}
```

```astro
---
import FormerieForm from "@formerie/astro/FormerieForm.astro";
---

<FormerieForm form="fm_t77txbvg43nmar" />
```

每个软件包的README显示替换了窗体的一部分,并保留了自己的标记.

```astro
---
import { createFormerieFormAttributes } from "@formerie/astro";

const attrs = createFormerieFormAttributes({
  form: "fm_t77txbvg43nmar",
});
---

<form {...attrs}>
  <input name="email" type="email" />
</form>
```

## 许可证

麻省理工学院.

## 常见问题

### @formerie/client 是什么？

JavaScript和TypeScript客户端的帮助器,用于Formerie公共API和运行时间\.

### 如何安装 @formerie/client？

在项目目录运行 npm install @formerie/client，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 formerie，可以用 npx formerie 直接运行。

### @formerie/client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @formerie/client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @formerie/client 可以商用吗？

@formerie/client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @formerie/client 的下载量有多少？

根据 npm 官方下载统计，@formerie/client 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,808 次，日均约 94 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @formerie/client 还在维护吗？

最新版本 0\.1\.0-alpha\.15 发布于 2026/11/03（12 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/06/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。