# @formsort/web-embed-api 中文文档

规范地址：https://npmcn.com/package/%40formsort/web-embed-api/

版本：2\.12\.0
npm 元数据更新时间：2026-11-10T10:42:31.528Z
中文译文更新时间：2026-11-15T09:13:50.507Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40formsort/web-embed-api
原文对照：https://npmcn.com/package/%40formsort/web-embed-api/?lang=original
项目主页：https://github.com/formsort/oss#readme
源码仓库：https://github.com/formsort/oss

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

- 包体积（解压后）：25.6 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2019-07-10T22:20:40.282Z
- 最新版本发布：2026-11-10T10:42:30.830Z
- 近 30 天下载量：63307（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 4 个）

## 中文简介

嵌入到其他网页内的格式流

## 安装

```sh
npm install @formsort/web-embed-api
```

也可以使用：`pnpm add @formsort/web-embed-api`、`yarn add @formsort/web-embed-api`、`bun add @formsort/web-embed-api`

## README

# @ formsort/web-embed- api

嵌入 [格式化](https://formsort.com/) 在其它网页内流动,在嵌入页和母页之间通信.

如果你使用反应,看 [@ formsort/ react-embed (英语)](https://npmcn.com/package/%40formsort/react-embed) 是一个方便的包装 围绕这个.

## 使用量

首先,安装

```shell
pnpm add @formsort/web-embed-api
```

```shell
npm install @formsort/web-embed-api --save
```

然后,初始化嵌入并装入一流.

## 文档

### 格式化WebEmbed( rootEl: HTML Element, 配置? : IFormsortWebEmbed Config)

初始化 : `rootEl` 提供.

```ts
const embed = FormsortWebEmbed(document.body);
```

使用 `FormsortSecureWebEmbed` 通过 POST 机构内的响应者数据而不是 (原始内容存档于2017-06-26). the URL. 通话 `loadFlow` 向 Iframe 提交 POST 导航.

```ts
import { FormsortSecureWebEmbed } from '@formsort/web-embed-api';

const embed = FormsortSecureWebEmbed(document.body);

embed.loadFlow(
  'formsort',
  'onboarding',
  'main',
  'e4923baa-dc2d-4555-813c-a166952292fa',
  { firstName: 'Olivia' },
  'staging',
  '0a3c4f52-1b8e-4d1a-9b6f-3a2e5c7d9f10'
);
```

POST数据可以包含: 平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面平面 对象。 安全嵌入的配置、方法和事件与 `FormsortWebEmbed`。 。 。 .

### `FormsortSecureWebEmbed(rootEl: HTMLElement, config?: IFormsortWebEmbedConfig)`

初始化安全格式化 iframe。 它有相同的配置,方法, 作为 `FormsortWebEmbed`。 。 。 .

内容 `loadFlow` 方法接受可选 `responderUuid`, (中文(简体) ), `initialAnswers`, (中文(简体) ), `formsortEnv`,以及 `variantRevisionUuid` 数值. `responderUuid` 财务报告和审定财务报表 `initialAnswers` 被送入POST机构. `formsortEnv` 财务报告和审定财务报表 `variantRevisionUuid` 添加到导航 URL。 它不接受 常规查询参数.

```ts
loadFlow(
  clientLabel: string,
  flowLabel: string,
  variantLabel?: string,
  responderUuid?: string,
  initialAnswers?: FormsortInitialAnswers,
  formsortEnv?: string,
  variantRevisionUuid?: string
) => void;
```

可选 `config` 对象有以下接口:

```ts
interface IFormsortWebEmbedConfig {
  useHistoryAPI?: boolean; // Default: false
  /**
   * iframe title attribute for accessibility
   */
  iframeTitle?: string;
  /**
   * iframe allow attribute for permissions
   * e.g. "camera;"
   */
  iframeAllow?: string;
  autoHeight?: boolean; // Default: false
  style?: {
    width?: CSSStyleDeclaration['width'];
    height?: CSSStyleDeclaration['height'];
  };
  authentication?: {
    idToken?: string; // ID Token for authenticated flows
  };
  origin?: string; // optional -- use if you want to load your flow in a custom damain. e.g. https://acme-flow.com
}
```

#### `config` 属性

-   `useHistoryAPI`:在重定向时,我们应该使用 HTML5 History API(即:, `window.pushState`),或者只是将 URL 全部更改?
    
    如果您拥有一页的应用程序, 并且想要在不重新装入整个页面的情况下更改容器的 URL, 将会很有帮助 。 注意你必须听 `popstate` 嵌入时的事件 `window` 以探测导航.
    
-   `autoHeight`: 嵌入是否应该 `<iframe>` 调整大小使其符合当前已装入流量的内容吗 ?
    
-   `style`: CSS 特性将应用于 Iframe 容器.
    
-   `iframeTitle`:可选字符串来设置 iframe 的标题属性,用于访问. 如果不提供,嵌入式将尝试在可获得时从流文件标题中设置标题.
    
-   `iframeAllow`: 可选字符串设置 iframe 允许权限属性(例如: `"camera;"`) (中文(简体) ).
    
-   `authentication.idToken`:当"流"需要ID符时,这个可以用来提供.
    
-   `origin`: 出现时,从自定义域中装入流出,而不是默认的窗体排序域.
    

### `loadFlow(clientLabel: string, flowLabel: string, variantLabel?: string, queryParams?: Array<[string, string]>) => void`

开始装入格式变体或流出.

请注意: `variantLabel` 是可选的。 如果不提供,则从流中选择一个变体:

-   根据重量,如果分配重量
    
-   随机,如果没有分配重量
    

### `unloadFlow() => void`

删除插入的 iFrame 及其全部事件听众 .

### `setSize(width: number, height: number) => void`

设置嵌入式的 CSS 大小 .

您也可以使用 CSS 来样式嵌入式的 Iframe - 这是 iframe 的孩子 `rootEl`,所以你会使用选择器 `#rootEl > iframe`。 。 。 .

### 活动听众

```ts
embed.addEventListener(eventName: key of IEventMap, fn: IEventMap[eventName]) => void
```

如果流被嵌入到一个白名单域中,每个事件听众都会被传递给用户的答案.

这些活动包括:

#### 流经 `(answers?: { [key: string]: any } ) => void`

设置调用函数, 当格式流完全加载时调用 .

注意这比听iframe的更准确 `load` 事件,因为它来自Formort应用程序代码,而不仅仅是当DOM被装入时.

你可以听这个来做一些事情,比如隐藏框架容器,或者显示一个装入指示器,直到所有东西都装入,以确保一个无缝的初始体验.

```ts
const embed = FormsortWebEmbed(document.body);
embed.addEventListener('FlowLoaded', () => {
  console.log('Flow has loaded!');
});
embed.loadFlow('formsort', 'onboarding', 'main');
```

#### 流量 `(answers?: { [key: string]: any }) => void`

设定回调在流量完成时被调用,这意味着用户已经完成了他们可用的所有步骤.

用于在流量完成后执行动作,例如表示祝贺或启动支付程序.

#### 流量关闭 `(answers?: { [key: string]: any }) => void`

设定回调值, 当用户在最后完成该回调时, 将会被调用 .

请注意, 只有当您的样式集定义了关闭按钮时, 才可能这样做 .

#### 已跳过 `(answers?: { [key: string]: any }) => void`

在装入新步骤时设置调用回调 .

如果用户之前没有完成流量,则在流量被加载后会发生这种情况. 随后,除最后一步的完成外,这一活动将在每一步完成后进行.

#### 步骤完成 `(answers?: { [key: string]: any }) => void`

设置一个调用, 当一个步骤完成时被调用 。 这包括在《公约》生效前完成最后一步 `"FlowFinalized"` 活动.

#### 恢复状态 `(answers?: { [key: string]: any }) => void`

设定回调,以在响应器状态更新时被调用,对应的是Formort本身保存响应器答案并将其送入集成时被调用.

默认情况下,这将大致与 `StepCompleted` 事件,因为默认行为是只在步骤之间推进时保存答案。 但是,如果你已经启用 [自动保存](https://docs.formsort.com/building-flows/variant-settings/additional-flow-settings#enable-autosave),然后,在用户输入数据后,您将收到简短的答覆.

#### 重定向 `({ url: string, answers?: { [key: string]: any } }) => ({ cancel?: boolean }) | undefined`

设置回调以自定义格式处理重定向的方式 。 要取消Formort对重定向的处理, 返回 :

```typescript
{
  cancel: true;
}
```

如果回调不返回一个值,Formort将照常处理重定向.

如果您正在将Formort嵌入一个具有自定义的 URL 路由处理的单页应用程序中,这将很有帮助.

#### 未经授权 `() => void`

为未经授权的格式化信件设定回调 .

这种回调在格式化流程被认证但ID符缺失或无效时使用.

## 发展

默认情况下,web会嵌入出品的窗体服务器. 如果您想要指向另一个流程服务器, 设置 `origin` 在配置到正确的基址时,例如:

```ts
FormsortWebEmbed(document.body, { origin: 'http://localhost:4040' });
```

## 常见问题

### @formsort/web-embed-api 是什么？

嵌入到其他网页内的格式流

### 如何安装 @formsort/web-embed-api？

在项目目录运行 npm install @formsort/web-embed-api，或使用 pnpm add / yarn add / bun add。

### @formsort/web-embed-api 支持 TypeScript 吗？

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

### @formsort/web-embed-api 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @formsort/web-embed-api 可以商用吗？

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

### @formsort/web-embed-api 的下载量有多少？

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

### @formsort/web-embed-api 还在维护吗？

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