DocuSeal React 嵌入签署表单：DocusealForm 组件全参数与集成指南

DocuSeal React 嵌入签署表单DocusealForm 组件全参数与集成指南【免费下载链接】docusealOpen source DocuSign alternative. Create, fill, and sign digital documents ✍️项目地址: https://gitcode.com/GitHub_Trending/do/docuseal本文基于 DocuSeal 官方文档 docs/embedding/signing-form-react.md 整理并深入扩写以 React 组件DocusealForm为主体覆盖其完整属性Attributes、回调Callback与 JWT 鉴权机制并结合当前开源仓库的路由定义、控制器与配置加载源码解释src的/d/{slug}与/s/{slug}两类 URL 在服务器端的实际处理链路帮助你在自有 React 应用中完成嵌入式电子签署流程的落地。工作原理两类签署 URL 与后端路由DocusealForm通过src属性指向 DocuSeal 服务端的表单页面。文档中明确了两类 URL/d/{slug}—— 模板级签署表单 URLtemplate form signing URL。可在管理后台的模板页面直接复制模板的slug字段也可以从/templatesAPI 获取。/s/{slug}—— 单个签署人 URLindividual signer URL。签署人的slug字段可以从/submissionsAPI 获取适用于通过 API 为带多收件人的模板发起签署请求的场景。这两类路径与仓库路由定义一一对应见 config/routes.rbresources :start_form, only: %i[show update], path: d, param: slug do get :completed end # ... resources :submit_form, only: %i[show update], path: s, param: slug do resources :values, only: %i[index], controller: submit_form_values # ... end即/d/...由 StartFormController 处理模板入口先收集签署人邮箱等信息/s/...由 SubmitFormController 处理直接进入具体签署人的签署表单页。从 StartFormController#show 的源码结构看/d/{slug}页面有一个关键前提模板必须开启了共享链接template.shared_link?否则未登录用户访问会抛出 404已登录且有权的用户则渲染私有视图。这解释了为什么通过 API 或后台创建模板后若未配置 sharing嵌入表单会打不开。快速开始最小可运行示例文档给出的完整示例如下来自 docs/embedding/signing-form-react.mdimport React from react import { DocusealForm } from docuseal/react export function App() { return ( div classNameapp DocusealForm srchttps://docuseal.com/d/{{template_slug}} email{{signer_email}} onComplete{(data) console.log(data)} / /div ); }其中docuseal/react是 DocuSeal 提供的 React 封装包README 中列出的嵌入方案之一同系列还有 Vue 版 与 Angular 版。一个需要在开源仓库语境下说明的重要限制嵌入式表单组件本身属于 DocuSeal 的付费Pro功能。从 EmbedScriptsController 的源码结构看开源版本在/js/:filename脚本端点对应 config/routes.rb 中的get /js/:filename, to: embed_scripts#show, as: :embed_script返回的是一段占位脚本它会把自定义元素docuseal-form与docuseal-builder注册为渲染Upgrade to Pro升级提示页的占位组件const DummyForm class extends DummyBuilder {}; if (!window.customElements.get(docuseal-form)) { window.customElements.define(docuseal-form, DummyForm); }因此DocusealForm的完整交互能力字段渲染、签名画布、完成卡片等依赖你部署的实例开启了相应许可本文的参数与回调说明对任何版本的服务端行为仍然成立可作为集成契约参考。属性Attributes完整参考以下表格完整继承文档中 JSON 形式的属性定义并标注了类型、默认值与说明。除src外其余属性均为可选。身份与鉴权类属性类型必填说明srcstring是签署表单的公开 URL。/d/{slug}为模板表单 URL可在后台模板页复制或经/templatesAPI 获取slug/s/{slug}为单个签署人 URL经/submissionsAPI 获取emailstring否签署人邮箱。若不提供表单会额外显示一个填写邮箱的步骤namestring否签署人姓名rolestring否签署人角色或头衔例如First Partytokenstring否用 API key 签名JWT HS256的 JSON Web Token。JWT 只能在后端生成payload 字段见下文externalIdstring否你的应用中用于唯一标识该签署人的字符串键metadataobject否附加签署人信息的元数据对象示例{ customData: custom value }token的 payload 结构仅可在后端生成字段类型必填说明slugstring是模板或签署人Submitter的 slug。使用 Submitter slug 时无需再传email参数emailstring否签署人邮箱。配合 Template slug 使用时若未指定则会出现邮箱填写步骤external_idstring否应用内唯一标识签署人的字符串键previewboolean否默认false以预览模式展示表单不可提交关于 JWT 在仓库内的实现开源仓库中提供了通用的 JWT 编解码工具 lib/json_web_token.rb使用Rails.application.secret_key_base对 payload 进行JWT.encode/JWT.decode。从源码结构看官方云服务的 token 校验对应API key 签名的约定自托管集成时应以你部署实例实际的校验实现为准并始终在后端完成 token 生成前端只负责把结果传给DocusealForm。展示与交互类属性类型默认值说明expandbooleantrue表单打开时是否展开minimizebooleanfalse设为true时始终最小化表单字段点击字段才展开orderAsOnPagebooleanfalse按字段在页面上的位置排序表单字段withTitlebooleantrue设为false移除表单中的文档标题withFieldNamesbooleantrue设为false隐藏字段名当字段名不是人类可读格式时有用withFieldPlaceholderbooleanfalse设为true用字段名占位符替代字段类型图标skipFieldsbooleanfalse允许跳过表单字段autoscrollFieldsbooleantrue设为false禁用自动滚动到下一个文档字段goToLastbooleantrue自动定位到最后一个未完成的步骤onlyRequiredFieldsbooleanfalse设为true时分步表单只显示必填字段隐藏所有可选字段languagestring浏览器语言UI 语言可用en, es, it, de, fr, nl, pl, uk, cs, pt, he, ar, kr, ja默认自动跟随浏览器语言i18nobject{}用于把默认 UI 文案替换为自定义值的键值对象可用键见 app/javascript/submission_form/i18n.jslogostring无在签署表单中使用的公开 Logo 图片 URLbackgroundColorstring无表单背景色仅支持 HEX 颜色码示例#d9d9d9customCssstring无应用于表单的自定义 CSS示例#submit_form_button { background-color: #d9d9d9; }关于i18n仓库中的文案键集中在 app/javascript/submission_form/i18n.js约 1600 余行、14 种语言键名如complete: Complete、sign_and_complete: Sign and Complete、by_clicking_you_agree_to_the: By clicking {button}, you agree to the支持{placeholder}插值、digitally_signed_by: Digitally signed by等。你的i18n对象只需以这些键覆盖对应文案即可。完成、拒绝与邮件类属性类型默认值说明previewbooleanfalse预览模式不可提交。注意预览模式嵌入已完成文档时要求token鉴权completedRedirectUrlstring无提交完成后跳转的 URL示例https://docuseal.com/successcompletedMessageobject无完成后的提示消息含title如 Documents have been signed!与body如 If you have any questions, please contact us.completedButtonobject无完成后卡片上的自定义按钮title按钮文字如 Go Back与url仅支持绝对 URL如 https://example.com均为必填withDownloadButtonbooleantrue设为false从完成卡片移除已签署文档下载按钮withSendCopyButtonbooleantrue设为false从完成卡片移除发送邮件按钮withCompleteButtonbooleanfalse设为true在表单头部显示完成按钮allowToResubmitbooleantrue设为false禁止用户重新提交表单withDeclinebooleanfalse设为true在表单中显示拒绝按钮sendCopyEmailboolean默认发送设为false关闭向签署人自动发送已签署文档的邮件默认会发送这些完成态配置在服务端并非硬编码而是由账户级配置合并而来。从 lib/submitters/form_configs.rb 可以看到SubmitFormController渲染表单时会调用Submitters::FormConfigs.call从account_configs表读取completed_button、completed_message、allow_to_decline、reuse_signature、allow_typed_signature等键值DEFAULT_KEYS常量并与前端传入属性共同构成最终表单配置——这解释了为什么completedButton/completedMessage既可以在嵌入属性里覆盖也可以在后台账户设置中统一配置。签名与数据预填类属性类型默认值说明allowTypedSignaturebooleantrue设为false禁止用户输入打字签名signaturestring无预填签名值可以是 base64 的data:image/字符串、图片的公开 URL或按标准字体渲染为手写体签名的纯文本rememberSignatureboolean无是否记住签名供以后使用为true时签名存储在签署人浏览器 localStorage 中之后该签署人的新表单可自动预填reuseSignaturebooleantrue设为false时不在第二个签名框复用签名而是重新采集valuesobject无表单字段的预赋值示例{ First Name: Jon, Last Name: Doe }readonlyFieldsarray无只读字段列表示例[First Name,Last Name]签名预填的服务端对应逻辑在 SubmitFormController#show当配置允许预填签名form_configs[:prefill_signature]时会优先读取当前用户的已存签名UserConfigs.load_signature否则调用Submitters::MaybeAssignDefaultBrowserSignature从浏览器/cookies 中恢复记住的签名并挂到signature_attachment——这正是rememberSignature/signature属性在表单页生效的机制。回调Callback参考组件提供四个回调属性均非必填完整继承文档定义回调类型触发时机示例onInitfunction表单组件初始化时() { console.log(Loaded) }onLoadfunction表单数据加载完成时接收 data(data) { console.log(data) }onCompletefunction表单完成提交后接收 data(data) { console.log(data) }onDeclinefunction表单被拒绝后接收 data配合withDecline(data) { console.log(data) }一个贴近实际业务的组合示例在文档最小示例基础上扩展常用属性DocusealForm src{https://your-docuseal-instance.com/d/${templateSlug}} email{signerEmail} name{signerName} roleFirst Party token{jwtFromBackend} // 后端生成的 JWT logohttps://your-cdn.com/logo.png languageen completedRedirectUrlhttps://example.com/success completedButton{{ title: Go Back, url: https://example.com }} withDecline onComplete{(data) trackEvent(form_completed, data)} onDecline{(data) trackEvent(form_declined, data)} /源码级流程解析一次嵌入签署如何走完后端结合仓库源码可以把嵌入表单的完整链路拆成三段便于排查集成问题1. 入口页/d/{slug}StartFormController 是/d路由的处理器show动作校验模板为共享链接shared_link?并处理require_phone_2fa/require_email_2fa等偏好——开启手机/邮箱两步验证的模板会直接对匿名嵌入访问抛出 404见 app/controllers/start_form_controller.rb。update动作执行find_or_initialize_submitter按link_form_fields默认[email]在模板的非过期、未拒绝 Submission 中find_or_initialize_by现有签署人找不到则创建新 Submissionsource: :link与 Submitter随后redirect_to submit_form_path(submitter.slug)跳转到/s/{submitter_slug}。若模板定义了多个未指定收件人且传入的是新记录会渲染multiple_submitters_error_message错误——这是多签署人模板使用共享链接时的典型报错场景。2. 签署页/s/{slug}SubmitFormController 负责字段填写与提交show在渲染前经过maybe_render_locked_page模板/Submission 已归档、已过期或已拒绝时渲染对应锁定页、maybe_require_link_2fa共享链接两步验证未通过则重定向回/d入口等前置动作。update先调用Submitters::AuthorizedForForm.call做鉴权其实现见 lib/submitters/authorized_for_form.rb分别校验pass_email_2fa?与pass_link_2fa?支持加密 cookieemail_2fa_slug或two_factor_token参数/请求头随后调用Submitters::SubmitValues.call保存字段值必填字段缺失时返回422 { field_uuid }验证失败返回422 { error }。3. 完成与事件完成卡片的行为下载按钮、发送邮件按钮、完成按钮文案由前文所述的FormConfigs决定preview属性对应的是/e/{slug}预览路由config/routes.rb 中的submissions_preview文档特别指出预览模式嵌入已完成文档需要token鉴权。集成注意事项与边界条件email与token的关系不传email且 token payload 中也没有email且用的是 Template slug时表单会多出邮箱填写步骤用 Submitter slug 时则无需再传 email。多签署人模板/d/{slug}共享链接方式要求模板中的签署人可被唯一确定filter_undefined_submitters相关逻辑多人签署建议走/s/{submitter_slug}或 JWT Submitter slug。重提交allowToResubmit从 StartFormController#can_resubmit? 看重提交还受服务端约束原签署需已完成、完成时间在 14 天内、来源非api/embed/mcp且账户配置允许——即前端传allowToResubmit{false}是只能更严服务端规则是最终边界。语言列表文档列出的 14 种语言en, es, it, de, fr, nl, pl, uk, cs, pt, he, ar, kr, ja与 app/javascript/submission_form/i18n.js 中维护的语言文案一致kr为文档原样写法。预览模式preview只读展示若要在预览中查看已完成的文档必须提供token。completedButton.url仅接受绝对 URLbackgroundColor仅接受 HEX 色值customCss用于细粒度覆盖如按钮颜色。延伸阅读其他框架的嵌入文档JavaScript 版、Vue 版、Angular 版、表单构建器 React 版API 文档docs/api/ruby.md含/templates、/submissions端点说明用于获取 slugWebhook 事件参考docs/webhooks/submission-webhook.md服务端关键实现StartFormController、SubmitFormController、FormConfigs、AuthorizedForForm、JsonWebToken【免费下载链接】docusealOpen source DocuSign alternative. Create, fill, and sign digital documents ✍️项目地址: https://gitcode.com/GitHub_Trending/do/docuseal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考