# @inploi/forms 中文文档

规范地址：https://npmcn.com/package/%40inploi/forms/

版本：1\.7\.9
npm 元数据更新时间：2026-11-01T09:28:59.159Z
中文译文更新时间：2026-11-01T11:29:28.348Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40inploi/forms
原文对照：https://npmcn.com/package/%40inploi/forms/?lang=original

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

- 包体积（解压后）：418 kB，57 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：@inploi/sdk \>=2\.1\.5
- 首次发布：2026-05-18T13:25:37.989Z
- 最新版本发布：2026-11-01T09:28:58.995Z
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

用于inploi应用程序流的可视化表单渲染器。

## 安装

```sh
npm install @inploi/forms
```

也可以使用：`pnpm add @inploi/forms`、`yarn add @inploi/forms`、`bun add @inploi/forms`

## README

# @inploi /形式

用于inploi应用程序流的可视化表单渲染器。它采用与前面相同的流JSON [`@inploi/plugin-chatbot`](https://npmcn.com/package/%40inploi/plugin-chatbot/) 按顺序呈现，并将其呈现为经典的可滚动表单。表单可以与页面内嵌呈现，也可以在抽屉中打开，并通过标准进行主题化 `appearance` 选项。

> **已弃用（2026年10月）：使用Candidate小部件的表单模式。** `@inploi/forms` 已被取代，并且不会获得任何新功能。表单样式的应用程序现在通过统一的候选小部件(`@inploi/plugin-candidate`、应用布局 `form`)，其中会话保持默认值。对于新的集成，使用它。
> 
> 这个包作为设计参考保存在这个存储库和npm上，它的CDN文件也保存下来。它仍然是连接到工作室的 **SDK形式** 块和 **形式** 按钮操作，一些演示页面使用它，所以删除它还不安全。它从未被出售过，并且在截至2026年10月28日的一周内，没有看到任何客户域在Worker日志中加载它（日志只追溯到大约7天）。
> 
> 这里最近的更改（PROD-7504中的原始错误复制，以及PROD-7448中的共享引擎对齐）伴随着共享流引擎和小部件的工作而来。它们不是客户影响的证据。这里没有其他固定的地方：改进了小部件的表单模式。它的框架运行的风险 `sdk.inploi.com` ，如果非内部租户开始通过它提交，则重新访问（PROD-7342 ADR，“form decision”）。

## 体系结构

-   **主机插件** （`forms.ts`)创建和监督iframe，管理抽屉打开/关闭，滚动锁，主题传播，提交运输和人才银行副本支票。它遵循与。相同的iframe脚手架模式 [`@inploi/plugin-kin`](https://npmcn.com/package/%40inploi/plugin-kin/).
-   **框架运行时** （`forms.runtime.tsx`)是一个在iframe内渲染的Preact应用程序。它拥有表单状态、验证、草稿持久性、用户交互和主机RPC（提交、重复检查和地址查找） `requestId` 相关性，内联-没有单独的桥接模块)。
-   **流投影** （`form.projector.ts`)遍历原始流图并生成可渲染项和终端状态。它评估 `if-block`之前, `jump`,应用 `add-submission`，收集提交链，暴露准备 `check-duplicate` 候选人，并收集提交后的文本/图像/链接内容。
-   **共享的逻辑** 消耗自 [`@inploi/flows`](https://npmcn.com/package/%40inploi/flows/) 对于验证邻近流助手、条件、插值、提交响应形状、会话键和重复检查请求构建。

Forms是一个带有小型表单执行器的投影优先呈现器，而不是聊天机器人服务解释器的副本。

-   **组件库** （`src/library.ts`)：统一候选小部件的表单模式（PROD-7448）重用Forms `Calendar`， `Combobox` 以及浮动原语。它从源代码捆绑它们，因此它们共享它的Preact和样式 他们通过他们的标记(角色、状态、 `data-active`）. 候选小部件从 对话的引擎(`@inploi/flows/form`)，而不是from `form.projector.ts`. `library.ts` 工作空间是内部的吗 不是已发布的导出。Forms还通过仅用于工作区的源别名从Candidate的独立工具包中捆绑相同的图标。

## 公共API

```ts
import { formsPlugin } from '@inploi/forms';

const forms = formsPlugin({ appearance: { placement: 'drawer' } });
await forms.open({ flow, title: 'Apply now', context: { jobId: '...' } });
```

### 放置

```ts
formsPlugin({
    appearance: { placement: 'embedded' },
    container: '#application-form',
});
```

`drawer` 是默认位置。 `embedded` 将iframe挂载到提供的容器中，并调整其大小以适合表单内容。

### 提交

默认情况下，主机插件提交给 `/flow/submit` 使用SDK `apiClient`． 消费者可以使用 `onSubmit`：

```ts
const forms = formsPlugin({
    onSubmit: async payload => {
        await submitApplication(payload);
        return { success: true };
    },
});
```

`FormsSubmitPayload` 仅包含公共提交数据： `integrationId`、可选 `job`，并过滤 `submissions`.

看到 `forms.protocol.ts` 如需查询全套类型(`OpenFormsParams`， `FormsAppearance`， `FormsSubmitPayload`,……)。

## 运行时行为

-   草稿通过流身份、流键和上下文哈希进行持久化。关闭，最小化，失败提交和成功提交保存草稿。标头重置动作是重新开始的显式方式。
-   求职者打开带有已保存的草稿的表单，其中包含答案，但从未提交过（这是加载框架后第一次打开该表单），他会看到表单上方的横幅：“您有一份未完成的此职位申请。继续你停下来的地方吗 **继续** （保留答案）和 **重新开始** （清除草稿，就像头部重置一样）。它位于始终在页面上的活动区域，因此它的到来是宣布的。抽屉将焦点移至继续；嵌入式表单永远不会从宿主页面转移焦点。回答问题同时也否定了问题。成功的提交将写入A `submitted:<state key>` 标记到同一存储，并且标头重置或再次开始删除它，因此提交的应用程序永远不会提供恢复（PROD-7338）。草稿只存在于浏览器的IndexedDB中：其他设备或浏览器、私人窗口、已清除的站点数据或Safari的7天存储到期重新开始。
-   当必需字段缺失、值无效、重复检查挂起、提交已经在进行中或正在运行提交冷却时间时，将禁用提交。
-   顺序 `integration-application-submit` 节点作为一个链来执行 `FormApp` `await`S按顺序执行每一步，并在第一次失败或重定向时短路。重定向响应显示提供者消息，并将页脚提交按钮替换为重定向CTA，该CTA将在新选项卡中打开ATS。没有持久的提交光标：在成功提交之前，任何字段编辑都会重置提交状态，下一次单击会从步骤0重新运行整个链（依赖于积分幂等）。
-   提交的API将作为一个重复的应用程序、一个封闭的角色或一个未知的裁决(结构化的 `error.data` 从 `/flow/submit`)显示我们自己的信息消息，而不是提供者的文本和错误提示音。提交停留在这些之后可用；只有成功才能消除它。在同一应用程序上，这个候选人自己失败的尝试在一个小时内的重复很可能是尝试着陆，如它所示 `submission_duplicate_earlier_attempt` 和FLOW\_SUBMIT记录 `outcome: 'duplicate_after_own_attempt'`． 主机在页面的整个生命周期中保留该尝试历史记录，而不是在重新加载期间。
-   其他故障后的恢复遵循API `error.data` （PROD-6846），通过聊天机器人的共享助手从 `@inploi/flows/utils`． 在API标记的提供者提交步骤之前的失败 `retryable` 与判决 `not_submitted` 显示 `submission_retryable`． 一个失败的标志 `retryable: false` 保留API的消息并保持提交，直到候选人更改答案。无法阅读的文件(`code: 'unreadable_document'` 与一个 `field`)清除该文件答案，放入 `submission_unreadable_document` 对文件的输入和启动没有等待。没有结果可读的抛出提交（连接丢失、网关超时、不可读的主体、没有集成响应的5xx）是一个未确认的接收和显示 `submission_unknown`.
-   一个失败的API标签 `reason: provider_maintenance` （供应商的定期维护窗口，api#1713, PROD-7336）显示 `submission_provider_maintenance` 窗户的尽头(`maintenance_until`)，或 `submission_provider_maintenance_later` 当没有可用的结局。Submit将等待到该结束（最多6小时），显示为“Submit将在{time}再次可用”。窗口内的未知判决可能已经到达提供者，因此它保持不变 `submission_unknown`，但它仍在等待窗口结束。
-   每一次失败的提交都会启动一个倒计时的冷却时间：连续的节流和临时中断等待20秒，40秒，然后60秒（或提供商的更长的Retry-After，上限为120秒）；其他的要等30分钟。应答更改和报头重置后，冷却时间仍然存在，当打开另一个流或作业时，冷却时间将被清除。
-   这些字段是可选的 `forms:submit-result`因此，旧主机后面的CDN帧的行为与以前一样，而旧帧忽略它们。
-   API接受以后交付的提交（HTTP 202） `integration_response.data.outcome: 'pending'`)是成功的：它显示了API的 `data.message`，或者 `submission_pending` 如果没有，则替换流的成功消息和FLOW\_SUBMIT记录 `outcome: 'pending'`． 在提交链中，它像任何成功一样继续进行下一步，并且当后面的步骤明显成功时，保留最新的挂起消息。
-   Post-submit `text`， `image` 和 `link` 节点在最终提交成功后呈现。
-   一个成功的最终提交锁定了输入：它们被封装在一个禁用的 `<fieldset>`，因此每个控件都变成不可编辑和可见静音，而标签，描述，信息节点和链接保持完全清晰和可点击。页脚CTA和提交后内容保持互动性；报头reset清除锁（和草稿）。
-   `end-flow` Before submit被视为终端死角，并隐藏提交按钮。
-   `check-duplicate` 运行主机端的人才银行客户端，并将结果作为下游条件的集成提交写回来。
-   `question-address` 支持手动输入和主机端Mapbox建议。常规地址字段保持可见；选择一个建议填充它们，用户仍然可以手动编辑。当需要这个问题时，除了第2行以外的每个映射部分都是必需的，因为只有当节点携带时才需要第2行 `line2Required: true` （api为拒绝空行2的ats设置它）；只包含空格的必需部件被视为缺失。
-   `integration-workflow-get` 期望在运行前由后端实现；如果它到达表单，则表单关闭失败，而不是跳过特定于集成的字段。

## 常见问题

### @inploi/forms 是什么？

用于inploi应用程序流的可视化表单渲染器。

### 如何安装 @inploi/forms？

在项目目录运行 npm install @inploi/forms，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@inploi/sdk（\>=2\.1\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @inploi/forms 支持 TypeScript 吗？

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

### @inploi/forms 支持 ESM 还是 CommonJS？

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

### @inploi/forms 可以商用吗？

@inploi/forms 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @inploi/forms 还在维护吗？

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