用途 该技能说明如何为 Novu 新增一个聊天渠道的连接按钮,使订阅者能够连接或断开某个渠道。按钮参照现有的 Slack、MsTeams、Telegram 实现,放在 @novu/js(SolidJS 核心)与 @novu/react(React 封装)中。
架构 采用三层结构:packages/js 提供 SolidJS 核心组件,其中使用数据 Hook 并调用 novu.channel* SDK,需在 Renderer.tsx 中注册;packages/react 提供公开封装,以 Default<Channel>ConnectButton 通过 mountComponent 挂载核心组件,再由 <Channel>ConnectButton 经 memo、NovuUI、withRenderer 组合。React 组件按名称挂载 SolidJS 组件,该名称必须注册在 Renderer.tsx 的 novuComponents 中并列入 CHANNEL_COMPONENTS,否则会走错渲染路径。
连接模型选择 先确定模型:
- 基于连接(connection-based),如 Slack、MS Teams:提供商在工作区或租户级通过 OAuth 授权;使用 novu.channelConnections;调用 generateConnectOAuthUrl() 生成 OAuth 弹窗 URL;用 get(connectionIdentifier) 检测;复用 useChannelConnection;需 connectionIdentifier、context、scope、connectionMode、autoLinkUser 等额外 props;标识符由 components/constants.ts 的 buildDefaultConnectionIdentifier(...) 生成。
- 基于端点(endpoint-based),如 Telegram:订阅者通过打开深链接关联,无工作区授权;使用 novu.channelEndpoints;调用 link({ integrationIdentifier }) 得到深链接 URL;用 list({ providerId, integrationIdentifier, limit: 1 }) 检测;需新建 use<Channel>Connection(照 useTelegramConnection);除基础 props 外无额外 props。 不确定时:OAuth 或应用安装型提供商选连接模型,机器人深链接或令牌型提供商选端点模型。
文件清单 核心(packages/js):新建品牌图标 src/ui/icons/<Channel>Colored.tsx(照 TelegramColored.tsx);新建 src/ui/components/<channel>-connect-button/<Channel>ConnectButton.tsx;仅端点模型需新建 src/ui/api/hooks/use<Channel>Connection.ts;编辑 Renderer.tsx 导入组件、加入 novuComponents、把名称字符串加入 CHANNEL_COMPONENTS;编辑 components/index.ts 导出组件;编辑 index.ts 在类型块重新导出 <Channel>ConnectButtonProps。 React(packages/react):新建 Default<Channel>ConnectButton.tsx 与 <Channel>ConnectButton.tsx;编辑 components/index.ts 与 src/index.ts,分别在值导出块加入组件、类型块加入 <Channel>ConnectButtonProps。 通常不需要新增 SDK 方法,除非提供商需要全新服务端调用(罕见);不要编辑自动生成的 libs/internal-sdk。
按钮行为 统一状态机:初始加载用 <Show when={!loading()} fallback={<Loader/>}>,从 Hook 的连接或端点派生 isConnected(),isLoading() = loading() || actionLoading()。已连接时点击调用 disconnect(identifier),触发 onDisconnectSuccess 或 onDisconnectError(err)。未连接时点击先 setActionLoading(true),取 URL 后 window.open(url, '_blank', 'noopener,noreferrer'),再开始轮询;轮询用固定间隔(2500ms,超时 120000ms)或退避(参见 MS Teams),用一次性 committed 标志或 ref 确保只有首次成功或超时触发副作用,并在 onCleanup 清除定时器;成功则 mutate(found) 并调用 onConnectSuccess(identifier),超时则 onConnectError(new Error(...))。外观复用共享键 channelConnectButtonContainer、Button、Inner、Icon、Label(均传入 { connected } 上下文),图标经 IconRendererWrapper(键 channelConnect / channelConnected),回退到 <Channel>Colored 或 CheckCircleFill,不要新增外观键。基础 props:integrationIdentifier(必填)、subscriberId、onConnectSuccess、onConnectError、onDisconnectSuccess、onDisconnectError、connectLabel、connectedLabel。
约定与注意事项 核心是 SolidJS 而非 React:用信号代替 Hook,用 <Show> 代替三元表达式,惰性读取 props(() => props.x),通过 onCleanup 清理。mountComponent 的名称必须与 novuComponents 键一致且在 CHANNEL_COMPONENTS 中列出。<Channel>ConnectButtonProps 在核心中定义,React 从 @novu/js/ui 导入,不要重复定义。遵循 Novu 约定:目录小写加连字符、具名导出、每个 return 前空一行、不使用嵌套三元表达式。这些包已发布,新导出属于次要版本升级,prop 变更需保持向后兼容。
构建与验证 修改 packages/ 后必须执行 pnpm build;对改动文件做类型检查与 lint;手动测试:在 playground/nextjs 中添加页面或标签(可复制 src/components/telegram-end-user-connect.tsx),把 <Channel>ConnectButton 包在 <NovuProvider> 中,再针对真实集成连接与断开验证。