# @formspree/ajax 中文文档

规范地址：https://npmcn.com/package/%40formspree/ajax/

版本：1\.1\.5
npm 元数据更新时间：2026-03-16T20:32:55.314Z
中文译文更新时间：2026-11-15T10:49:12.174Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：43.6 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-24T23:09:52.308Z
- 最新版本发布：2026-03-16T20:32:54.964Z
- 近 30 天下载量：2145（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

格式化 AJAX 库

## 安装

```sh
npm install @formspree/ajax
```

也可以使用：`pnpm add @formspree/ajax`、`yarn add @formspree/ajax`、`bun add @formspree/ajax`

## README

# 格式化 AJAX

用于声明格式处理的香草 JavaScript 库 [格式化](https://formspree.io/)不需要框架 – 通过数据属性或简单的JavaScript API与平面 HTML 形式合作.

## 安装

### 国家预防机制/亚兰

```sh
npm install @formspree/ajax

yarn add @formspree/ajax
```

### 脚本标记 (CDN)

没有捆绑。 关闭前添加此片段 `</body>` 标签 :

```html
<script>
  window.formspree =
    window.formspree ||
    function () {
      (formspree.q = formspree.q || []).push(arguments);
    };
  formspree('initForm', { formElement: '#my-form', formId: 'YOUR_FORM_ID' });
</script>
<script src="https://unpkg.com/@formspree/ajax@1" defer></script>
```

## 快速启动

### 无害环境管理(带捆绑机)

```js
import { initForm } from '@formspree/ajax';

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',
});
```

### HTML 语言

```html
<div data-fs-success></div>
<div data-fs-error></div>

<form id="contact-form">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" data-fs-field />
  <span data-fs-error="email"></span>

  <button type="submit" data-fs-submit-btn>Send</button>
</form>
```

就是这样。 库自动处理提交,验证错误,加载状态,以及成功消息.

## 数据属性

这些 HTML 属性允许声明形式行为而无需额外的 JavaScript :

| 属性 | 元素 | 说明 |
| --- | --- | --- |
| `data-fs-error="fieldName"` | `<span>`, (中文(简体) ), `<div>` | 显示字段级验证错误。 如果为空,则插入 API 错误消息 。 如果它有内容,则显示/隐藏为-is. |
| `data-fs-error` | `<div>` | 显示窗体级别错误(没有值)。 相同的内容策略:空元素获得服务器消息,有内容的元素显示为-is. |
| `data-fs-success` | `<div>` | 提交后显示成功消息。 空元素获得"谢谢!",带有内容的元素显示为-is. |
| `data-fs-field` | `<input>`, (中文(简体) ), `<textarea>` | 标记要接收的输入 `aria-invalid="true"` 错误。 字段名称从元素读取 `name` 属性. |
| `data-fs-submit-btn` | `<button>` | 提交期间自动停用,完成后重新启用. |

## 配置

通过配置对象到 `initForm()`数字 :

```js
import { initForm } from '@formspree/ajax';

const handle = initForm({
  // Required
  formElement: '#contact-form', // CSS selector or HTMLFormElement
  formId: 'YOUR_FORM_ID', // Your Formspree form ID

  // Optional
  origin: 'https://formspree.io', // API origin (default)
  debug: false, // Enable console logging

  // Extra data merged into every submission
  data: {
    source: 'website',
    campaign: () => getCampaign(),
    timestamp: async () => await getServerTime(),
  },

  // Lifecycle callbacks
  onInit: (context) => {},
  onSubmit: (context) => {},
  onSuccess: (context, result) => {},
  onError: (context, error) => {},
  onFailure: (context, error) => {},

  // Custom rendering (override defaults)
  enable: (context) => {},
  disable: (context) => {},
  renderFieldErrors: (context, error) => {},
  renderSuccess: (context, message) => {},
  renderFormError: (context, message) => {},
});

// Clean up when done
handle.destroy();
```

## 生命周期召回

| 回电 | 参数 | 说明 |
| --- | --- | --- |
| `onInit` | `(context)` | 表格初始化时调用 . |
| `onSubmit` | `(context)` | 在提交来文之前已打电话. |
| `onSuccess` | `(context, result)` | 请求成功提交. |
| `onError` | `(context, error)` | 从Formpree调用验证错误. |
| `onFailure` | `(context, error)` | 调用出乎意料的错误(例如网络故障). |

这个 `context` 对象包含: `form` (HTML形式), `formKey`, (中文(简体) ), `endpoint`, (中文(简体) ), `client`,以及 `config`。 。 。 .

## 默认行为

库提供了框外的合理默认:

-   **提交按钮** ——提交期间残废,竣工后再启用.
-   **字段错误** - 输入 `data-fs-error="fieldName"` 要素。 如果元素为空,则插入 API 错误消息 。 如果它有内容,则显示/隐藏为-is.
-   **外地验证** —— 说 `aria-invalid="true"` 设置在 `data-fs-field` 当其字段有错误时输入.
-   **成功的消息** - 电话 `data-fs-success` 元素显示为“谢谢!”(或保留用户内容).
-   **格式错误** - 电话 `data-fs-error` 元素(没有值)与窗体级错误消息(或保存的用户内容)一起显示.
-   **没有数据的成功 - fs - 成功** - 如果没有 `data-fs-success` 元素存在且无 `onSuccess` 提供回调,表格被替换为“谢谢!”消息.
-   **数据- fs- 成功** ——如果 `data-fs-success` 元素存在且无 `onSuccess` 提供回调,在成功后重设窗体.
-   **默认样式** ——错误消息的基本样式,无效字段,消息横幅自动被注入.

## 额外数据

使用 `data` 选项。 值可以是静态字符串,同步函数,也可以是同步函数. `undefined` 数值被跳过.

```js
initForm({
  formElement: '#my-form',
  formId: 'YOUR_FORM_ID',
  data: {
    source: 'landing-page',
    referrer: () => document.referrer || undefined,
    sessionId: async () => await fetchSessionId(),
  },
});
```

## 样式

默认样式自动被注入. 您可以使用您的 CSS 来覆盖 :

```css
/* Error message text */
[data-fs-error] {
  color: #dc3545;
  font-size: 12px;
}

/* Invalid field border */
[data-fs-field][aria-invalid='true'] {
  border-color: #dc3545;
}

/* Success message banner */
[data-fs-success][data-fs-active] {
  background: #d4edda;
  color: #155724;
}

/* Form-level error banner */
[data-fs-error=''][data-fs-active] {
  background: #f8d7da;
  color: #721c24;
}
```

## 帮助和支持

请参看 [表格文档](https://help.formspree.io/)。 。 。 .

## 常见问题

### @formspree/ajax 是什么？

格式化 AJAX 库

### 如何安装 @formspree/ajax？

在项目目录运行 npm install @formspree/ajax，或使用 pnpm add / yarn add / bun add。

### @formspree/ajax 支持 TypeScript 吗？

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

### @formspree/ajax 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @formspree/ajax 可以商用吗？

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

### @formspree/ajax 的下载量有多少？

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

### @formspree/ajax 还在维护吗？

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