让开源，少一点语言距离。
npm包中文文档

@inploi/forms

中文文档
1.7.9发布于 2026/11/01TypeScriptESM + CJS

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

中文使用文档
中文原文
文档目录5 节
  1. 体系结构
  2. 公共API
  3. 放置
  4. 提交
  5. 运行时行为

@inploi /形式

用于inploi应用程序流的可视化表单渲染器。它采用与前面相同的流JSON @inploi/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.
  • 框架运行时 （forms.runtime.tsx)是一个在iframe内渲染的Preact应用程序。它拥有表单状态、验证、草稿持久性、用户交互和主机RPC（提交、重复检查和地址查找） requestId 相关性，内联-没有单独的桥接模块)。
  • 流投影 （form.projector.ts)遍历原始流图并生成可渲染项和终端状态。它评估 if-block之前, jump,应用 add-submission，收集提交链，暴露准备 check-duplicate 候选人，并收集提交后的文本/图像/链接内容。
  • 共享的逻辑 消耗自 @inploi/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

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

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

放置

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

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

提交

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

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 awaitS按顺序执行每一步，并在第一次失败或重定向时短路。重定向响应显示提供者消息，并将页脚提交按钮替换为重定向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 共发布 33 个版本，首次发布于 2026/05/18；过去 12 个月发布了 33 个版本。

版本发布日期距今
1.7.9latest2026/11/012 天前
1.7.82026/10/313 天前
1.7.72026/10/295 天前
1.7.62026/10/286 天前
1.7.52026/10/267 天前
1.7.42026/10/2113 天前

关于 @inploi/forms 的常见问题

@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 和提交记录判断。