Dify 工作区成员邀请弹窗从 README 到源码的收件人状态机与表单校验全解析【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify本文以 Dify 前端invite-modal模块的 README 为核心结合其真实源码与测试完整还原「工作区成员邀请」功能的状态归属设计收件人如何从一段自由文本被解析、去重、校验为结构化对象席位额度如何从服务端特性查询中推导后端错误码又如何精准落位到对应表单字段。读完后你将掌握该模块InviteForm/EmailRecipientsField/RoleSelector三组件的职责边界以及一套可复用的「草稿 已确认收件人」双状态管理模式。模块定位与职责边界模块的 READMEREADME.md开宗明义地声明了这个模块的所有权范围本模块拥有工作区成员邀请表单收件人组合、角色选择、字段与表单错误、请求状态以及邀请成功的结果。这句话把职责切成了两个清晰的阵营。React 本地状态负责「还没离开浏览器的一切」——收件人草稿、解析后的收件人列表、当前提交错误服务端数据则一律经由 TanStack Query 管理——特性查询决定席位上限、角色查询决定可分配角色、邀请变更mutation以及提交成功后的缓存失效。这种切分在 index.tsx 的顶部导入中就能得到印证import { useMutation, useQuery, useQueryClient } from tanstack/react-query import { consoleQuery } from /service/client import { commonQueryKeys } from /service/use-common import { mergeEmailRecipients } from ./email-recipients而 README 最容易被忽略、却最关键的一句是席位可用性来自consoleQuery.features.get特性模块并不在本地或 Provider 状态中镜像它。也就是说「还能再邀请几个人」这个数不存任何本地状态而是每次从 features 查询的返回值里现算。这一设计避免了「本地席位缓存与服务端漂移」的经典 Bug代价只是每次打开表单多读一次 query cache。对外契约InviteModal 的 Props 设计InviteModal对外暴露的 props 定义了整个组件的边界index.tsxtype InviteModalProps { open: boolean trigger: ReactElement isEmailSetup: boolean onOpenChange: (open: boolean) void onSend: (invitationResults: MemberInviteResponse[invitation_results]) void }两个设计要点值得注意对话框可见性由调用方拥有README 最后一句 dialog visibility remains caller-owned。open是受控属性onOpenChange是唯一的出口。测试用例routes close actions through the controlled state owner专门验证了点击关闭按钮只会回调onOpenChange(false)组件内部绝不私改可见性。isEmailSetup把邮件能力探测上移。组件只消费一个布尔值不关心它是怎么探测的。当isEmailSetup为false时表单顶部渲染一条警告横幅members.emailNotSetup提示用户当前环境未配置邮件服务——邀请邮件发不出去但表单本身不被禁用。InviteForm内部只保留三个状态对应 README 说的 email draft, parsed recipients, and current submission errorindex.tsxconst [recipients, setRecipients] useStateEmailRecipient[]([]) // 已确认的收件人 const [draft, setDraft] useState() // 输入框中的草稿 const [submissionError, setSubmissionError] useStateSubmissionError(null)错误被建模成一个可辨识联合discriminated union这是整个错误处理体系的骨架type SubmissionError | { kind: fields; errors: PartialRecordInviteFieldName, string } // 字段级错误 | { kind: form; message: string } // 整表单错误 | nullfields类错误按字段名emails或role落位交给 Base UI Form 渲染并聚焦对应控件form类错误比如网络失败则作为一条持久的rolealert提示挂在表单底部。README 中 Base UI Form owns registration, validation, external field errors, and invalid-field focus 描述的就是这套机制——字段注册、必填校验、外部错误注入、无效字段聚焦全部由langgenius/dify-ui/form承担业务代码只需把fieldErrors传进去。收件人解析分隔符、去重与浏览器原生校验收件人的核心逻辑全部沉淀在纯函数文件 email-recipients.ts没有任何 React 依赖因此单测email-recipients.spec.ts可以完全脱离渲染环境运行。分隔符采用一个宽松的正则一次覆盖逗号、分号、换行与制表符const EMAIL_DELIMITER_PATTERN /[,;\r\n\t]/这让「从 Excel 粘一列邮箱」或「从邮件头粘贴分隔名单」都能被正确拆成多个收件人。测试用例用参数化断言逐一验证了,、;、\n、\r\n、\t五种分隔符均被识别而纯空白连接的地址不会被误拆。单条地址的规范化在createEmailRecipient中完成先trim().toLowerCase()再用一个临时 DOM 输入框借道浏览器的ValidityState做格式判断function isEmailValid(value: string) { const input document.createElement(input) input.type email input.value value return input.validity.valid }这是一个有意的取舍有效性语义与用户所用浏览器保持一致而不是引入一套可能与浏览器行为漂移的自研正则。测试用例accepts an address allowed by the browser without requiring a dotted domain专门锁定这一行为——personexample这类没有点号域名的地址浏览器认为合法前端就接受最终由后端邮件服务兜底。合并与去重由mergeEmailRecipients完成它接收「已确认收件人 草稿文本」两个输入输出统一列表export function mergeEmailRecipients(recipients: EmailRecipient[], input: string) { const nextRecipients [...recipients] const existingValues new Set(recipients.map(({ value }) value)) input .split(EMAIL_DELIMITER_PATTERN) .map(createEmailRecipient) .filter(({ value }) Boolean(value)) .forEach((recipient) { const { value } recipient if (existingValues.has(value)) return // 与已有收件人去重 existingValues.add(value) nextRecipients.push(recipient) }) return nextRecipients }三个关键语义都由测试固化大小写不敏感去重FIRSTexample.com与已有的firstexample.com视为同一人无效地址不丢弃mergeEmailRecipients([], validexample.com, not-an-email)会保留not-an-emailisValid: false让用户能看见并修正而不是静默吞掉顺序保持二十人名单按粘贴顺序稳定输出。EmailRecipientsField草稿提交、粘贴拦截与键盘可达性展示层组件 email-recipients-field.tsx 承接「chip 输入框」的交互细节即 README 所说 Colocated presentation components may own their transient interaction state——draftTouched这种瞬态交互状态就留在本组件内。它的核心交互策略是「Enter 提交草稿、失焦提交草稿、直接点发送也提交草稿」三种路径最终都收敛到同一语义。commitDraft的逻辑const commitDraft () { if (!draft.trim()) return if (draftRecipients.some(({ isValid }) !isValid)) { setDraftTouched(true) // 非法草稿不生成 chip标记 touched 触发错误提示 return } updateRecipients(mergeEmailRecipients(recipients, draft)) updateDraft() setDraftTouched(false) }而表单提交时的validateRecipients会把「已确认收件人 未提交的草稿」合并后再校验这意味着用户输入完邮箱直接点发送、不按 Enter也能成功提交——测试用例submits a valid draft without requiring Enter or blur to create a chip专门验证了这一点它对应了真实的用户操作习惯很多人根本不理解「chip 化」这个中间态。几个值得学习的细节粘贴拦截onPaste只有当剪贴板内容包含分隔符时才preventDefault把整段文本插到光标位置后走mergeEmailRecipients批量生成 chip避免用户手动删逗号单条粘贴则走原生行为。中文输入法保护onKeyDown中检查event.nativeEvent.isComposing组合输入期间的 Enter 只preventDefault、不触发commitDraft避免拼音选词时误提交。RTL 方向感知isRightToLeft同时检查元素计算样式与document.documentElement.dir阿拉伯语等 RTL 界面下左右方向键的 chip 导航自动镜像。无障碍无效 chip 用aria-describedby指向屏幕阅读器专用的隐藏错误文本sr-only删除 chip 后焦点回落到相邻 chip 或输入框测试Backspace空草稿时删除最后一个收件人等路径均有覆盖。字段级错误来源有两路本地检测chip 或草稿中存在非法地址产生members.emailInvalid必填性则由Field nameemails validate{validateRecipients}交给 Base UI Form 处理空提交时显示members.emailRequired并自动聚焦输入框——这正是 README 把 invalid-field focus 划给 Base UI Form 的具体体现。RoleSelector分页角色下拉与遗留角色兼容角色选择器 role-selector.tsx 用 TanStack Query 的无限分页查询useWorkspaceRoleList({ page: 1, limit: 20, language })拉取当前租户的角色列表配合IntersectionObserver实现下拉滚动加载observer new IntersectionObserver( (entries) { if ( entries[0]!.isIntersecting !rolesLoading !isFetchingNextPage !rolesError hasMore ) fetchNextPage() }, { root: listRef.current, rootMargin: ${dynamicMargin}px, // 100~200px 的动态预加载边距 }, )rootMargin不是固定值而是Math.max(100, Math.min(listHeight * 0.2, 200))——按列表实际高度动态计算提前量保证滚到底之前下一页已经发出请求。列表尾部那个div ref{setAnchorElement} classNameh-0 /就是被观察的哨兵。另一段容易被忽视的兼容逻辑是LEGACY_ROLE_DESCRIPTION_KEY_MAPconst LEGACY_ROLE_DESCRIPTION_KEY_MAP { admin: members.adminTip, editor: members.editorTip, normal: members.normalTip, dataset_operator: members.datasetOperatorTip, } as const角色描述优先取后端的role.description当后端没给描述时组件按角色的name或id归一化为小写匹配这四个内置键回退到静态 i18n 文案再匹配不上则显示role.noDescription占位。这让新版本的自定义 RBAC 角色与早期四个硬编码角色Admin/Editor/Normal/Dataset Operator在 UI 上呈现一致。选中值统一使用role.id提交itemToStringValue{(role) role.id}测试也断言请求体中role: admin传的是 id 而非名称。席位推导纯服务端特性、零本地镜像README 那句 Seat availability comes fromconsoleQuery.features.get 在 index.tsx 中展开为一段带优先级的推导链const { data: features } useQuery(consoleQuery.features.get.queryOptions()) const memberLimit features?.workspace_members.enabled ? features.workspace_members : features?.billing.enabled features.members.limit 0 ? features.members : undefined const remainingSeats memberLimit memberLimit.limit 0 ? Math.max(memberLimit.limit - memberLimit.size, 0) : null const effectiveRecipients mergeEmailRecipients(recipients, draft) const validRecipientCount effectiveRecipients.filter(({ isValid }) isValid).length const exceedsRemainingSeats remainingSeats ! null validRecipientCount remainingSeats解读这条链限额来源优先级workspace_members特性启用时用它否则若billing启用且members.limit 0则用members两者都不满足时memberLimit为undefined意味着无上限不显示任何席位提示。remainingSeats为null与0语义不同null代表「没有席位概念」自托管未购套餐等场景0才是「真的没有剩余席位」。Math.max(..., 0)防止负数出现。超额判断只针对合法收件人validRecipientCount过滤掉isValid: false的地址避免「还没修正的坏地址」也计入席位占用。只警告、不拦截。exceedsRemainingSeats为真时渲染一条rolestatus的警告剩余 N 席 · 收件人数超出但提交按钮保持可用——测试warns but lets the backend decide whether recipients consume remaining seats明确断言了按钮 enabled 且请求照常发出。最终裁决权在服务端超限会以limit_exceeded错误码返回再由前端映射为字段错误。这是一种「前端给确定性提示、后端做权威校验」的分工。错误码落位从后端 body 到字段级 aria-invalid后端邀请接口的错误契约定义在 OpenAPI 生成的类型里dify/contracts/api/console/workspaces/types.gen的MemberInviteErrorResponse前端用一个白名单函数做防御式解析invite-error.tsconst INVITE_ERROR_CODES new SetInviteErrorCode([ invalid_param, invalid_role, limit_exceeded, ]) export function getInviteErrorCode(error: unknown): InviteErrorCode | null { const errorRecord getRecord(error) const dataRecord getRecord(errorRecord?.data) const bodyRecord getRecord(dataRecord?.body) const code bodyRecord?.code ?? errorRecord?.code return typeof code string INVITE_ERROR_CODES.has(code as InviteErrorCode) ? (code as InviteErrorCode) : null }它做了两件保守的事只认契约中列出的三个码invalid_param/invalid_role/limit_exceeded只从data.body.code或顶层code两处读取其余一律返回null走兜底。测试 invite-error.spec.ts 验证了code: BAD_REQUESTHTTP 层错误和invalid-role下划线变体非契约码都会返回null——不猜、不放大。拿到码之后handleSubmit的onError完成落位index.tsxswitch (getInviteErrorCode(error)) { case limit_exceeded: // → emails 字段邀请超出席位上限 case invalid_role: // → role 字段角色已失效或非法 default: // → 整表单members.inviteFailed 持久 alert }配套的两个状态清理规则同样有测试锚定clearEmailSubmissionError用户在邮件输入框任何变更继续输入或删除 chip时立即清除emails字段的服务端错误——「改了就别再骂我」role 的服务端错误则更黏性测试keeps a role server error visible when the user only opens the selector表明仅仅点开角色下拉不会清除invalid_role错误只有真正换一个角色才清除。这个差异是刻意的打开下拉不代表用户已经修正了选择。请求生命周期防重入、缓存失效与成功回调handleSubmit的完整流程index.tsx体现了该模块对「请求状态」的全部处理const handleSubmit ({ role }: InviteFormValues) { if (isPending) return // 1. 防重入 setRecipients(effectiveRecipients) // 2. 提交前把草稿固化成 chip setDraft() setSubmissionError(null) // 3. 清空旧错误 mutate( { body: { emails: effectiveRecipients.map(({ value }) value), role, language: locale, // 4. 邀请邮件按当前界面语言发送 }, }, { onSuccess: (response) { void queryClient.invalidateQueries({ queryKey: consoleQuery.features.get.queryKey() }) void queryClient.invalidateQueries({ queryKey: commonQueryKeys.members }) onOpenChange(false) // 5. 关弹窗 onSend(response.invitation_results) // 6. 把结果交给调用方展示 }, onError: (error) { /* 见上一节 */ }, }, ) }几个可验证的决策点防重入isPending时直接 returnmutation 挂上了context: { silent: true }请求进行中不弹全局 loading。测试freezes all editable controls while invitations are being sent断言了发送期间输入框、角色选择器、每个 chip 的删除按钮、提交按钮全部禁用/aria-disabled。缓存失效范围精准只失效features席位数变了和commonQueryKeys.members成员列表变了两个 key不做大面积invalidateAll。测试用vi.spyOn(queryClient, invalidateQueries)精确断言了失效对象。成功后的职责移交组件自己不做成功庆祝动画而是通过onSend把invitation_results抛给调用方。上层 members-page/index.tsx 拿到结果后打开同级的invited-modalinvited-modal/index.tsx来渲染发送成功的结果与邀请链接。这与 README 的 successful invitation result 属于本模块产出、但展示留在调用侧的边界一致。提交按钮文案是动态的有 N 个合法收件人时显示members.sendInviteCount含 count 插值否则显示members.sendInvite——测试counts a manually typed recipient list before it is committed甚至验证了「还没回车、邮箱还在草稿里」时按钮文案已经按 2 计数。语言字段language: locale取自useLocale()决定后端发出的邀请邮件语言测试断言其为en-US。受控关闭与表单重置README 末尾的 dialog visibility remains caller-owned 还有一个隐含推论关闭即重置。因为InviteModal是受控组件调用方把open置回false后DialogContent 卸载InviteForm连同它的三个 state 一起销毁下次打开是全新实例。测试resets the form after a controlled close覆盖了这条路径关闭后再打开之前输入的收件人 chip 不存在、角色选择器回到selectRole占位态。反过来does not render dialog content while controlled closed确认了open: false时连 dialog 节点都不渲染。这也解释了组件里没有任何「关闭时手动清状态」代码——用挂载/卸载代替手动重置是受控弹窗最省心的状态卫生方案。测试覆盖与架构自检该模块的测试规模本身就说明这套设计被当作可验证契约来维护共五个规格文件位于tests目录文件覆盖的 README 声明index.spec.tsx受控弹窗、初始聚焦、草稿直接提交、chip 固化、席位警告不拦截、错误码落位与清除、发送期冻结、关闭即重置email-recipients.spec.ts五种分隔符、规范化去重、无效地址保留、20 人批量顺序email-recipients-field.spec.tsx字段交互态草稿、chip 编辑/删除、键盘导航invite-error.spec.ts错误码白名单与防御式解析role-selector.spec.tsx角色下拉的分页加载与遗留角色描述回退值得注意的是 index.spec.tsx 里对/service/client的整体 mock测试用vi.mock把consoleQuery.features.get和workspaces.current.members.inviteEmail.post替换为可控的fetchFeatures/inviteMember函数从而在不发真实请求的前提下断言请求体形状emails数组、roleid、language与缓存失效调用——这也反向印证了 README 所说「TanStack Query owns feature and role queries, the invitation mutation, and cache invalidation」所有数据行为都收敛在这两个 query 定义上没有旁路 fetch。小结一份可迁移的前端表单架构清单把 README 的三句话翻译成工程实践可以得到这份清单状态归属三分法——瞬态交互状态draftTouched留在展示组件业务草稿recipients/draft/submissionError集中在InviteForm服务端事实features/roles只存在于 Query cache禁止本地镜像。纯函数先行——分隔符、规范化、去重抽成无 React 依赖的email-recipients.ts单测可在 Node 环境直接跑UI 组件只做编排。错误建模用可辨识联合——fields与form两类错误、配合错误码白名单保证「后端说哪错、UI 就红哪个框」且网络类故障不会被误标到具体字段。软警告 权威校验——席位超额只提示不拦截最终以服务端limit_exceeded为准前端提示永远允许与后端存在时间差而不产生死锁。受控弹窗 卸载即重置——不维护任何手动 reset 逻辑用 React 的挂载语义天然保证表单卫生。这套模式对任何「多收件人表单 远程下拉 限额控制」的管理后台场景都可直接借鉴先把 README 级别的职责声明写清楚再让测试逐条锚定声明模块边界就不会在迭代中悄悄腐化。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考