Novu React Inbox 深度实战指南从基础集成到全量自定义渲染【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu导读本文围绕 Novu 开源仓库中novu/react包的 Inbox应用内通知中心组件系统讲解如何在 React 应用中完成从「开箱即用的通知中心」到「完全自定义的通知 UI」的完整落地。你将掌握 Inbox 的基础挂载方式、铃铛Bell与通知条目的自定义渲染、粒度化渲染插槽、事件回调、主题变量定制以及组合式组件布局并理解这些 API 背后在仓库源码中的真实实现。本文主体依据 react-inbox-examples.md 展开并佐以 packages/react 下的组件源码与 packages/js 的主题默认值配置。一、前置条件需要准备的三个核心标识在使用novu/react的Inbox组件前你需要从 Novu 后台Dashboard获取三个关键信息参数说明applicationIdentifier应用的公开标识Public Key可从 Novu Dashboard 的 API Keys 页面获取它不是 Secret Key可以安全地暴露在前端subscriberId当前登录用户的唯一标识用于定位该用户的通知数据例如用户数据库中的 IDsubscriberHash可选的 HMAC 签名由服务端使用环境 Secret Key 对subscriberId计算生成用于防止他人伪造用户身份启用订阅者身份验证后必须提供在 Create React App 项目中通常通过环境变量REACT_APP_NOVU_APP_ID注入应用标识其他构建工具可替换为对应的VITE_等前缀。二、基础集成一分钟挂载一个可用通知中心最基础的用法是直接渲染Inbox组件它会自动完成 SDK 初始化、订阅者认证、WebSocket 实时连接并渲染出完整的通知中心 UI铃铛 通知弹层import { Inbox } from novu/react; function App() { return ( Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 subscriberHashhmac-hash-from-server / ); }从源码看这个看似简单的挂载背后发生了完整的初始化流程Inbox组件在 Inbox.tsx 中通过buildSubscriber构造订阅者对象并借助InternalNovuProvider创建Novu客户端实例随后在InboxChild中由NovuUI组件实例化底层 UI 引擎见 NovuUI.tsx最终通过Mounter将组件挂载到真实 DOM 中。因此单组件即可获得完整的连接、订阅与渲染能力。兼容性提示源码类型定义types.ts中subscriberId被标记为deprecated推荐改用subscriber属性可传对象或字符串同时支持 Keyless 模式——不传applicationIdentifier、subscriberId时SDK 会以空字符串初始化并让 API 侧自动生成标识见 Inbox.tsx 注释。三、自定义铃铛图标renderBell默认铃铛无法满足品牌化需求时可通过renderBell渲染函数接管铃铛的整个外观。该函数接收实时未读数unreadCount返回任意 React 节点import { Inbox } from novu/react; function App() { return ( Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 renderBell{(unreadCount) ( button classNamebell-button BellIcon / {unreadCount 0 ( span classNamebadge{unreadCount}/span )} /button )} / ); }源码层面renderBell的类型为BellRenderer (unreadCount: UnreadCount) React.ReactNode见 types.ts。在 Inbox.tsx 中它会被包装成(el, unreadCount) mountElement(el, renderBell(unreadCount))的形式通过mountElement把 React 渲染结果桥接到底层 UI 的 DOM 容器中——这解释了为什么回调返回的是 React 节点而非字符串。Bell子组件同样支持renderBell见 Bell.tsx说明该自定义能力在「整体 Inbox」与「组合式布局」两条路径上是一致的。四、整体自定义通知渲染renderNotification如果对单条通知的呈现有整体性的设计要求可以使用renderNotification一次性接管整条通知的渲染。回调接收完整的notification对象内含avatar、subject、body、createdAt等字段import { Inbox } from novu/react; function App() { return ( Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 renderNotification{(notification) ( div classNamenotification-item {notification.avatar ( img src{notification.avatar} alt classNameavatar / )} div classNamecontent {notification.subject h4{notification.subject}/h4} p{notification.body}/p time{new Date(notification.createdAt).toLocaleString()}/time /div /div )} / ); }需要特别留意的是 API 的互斥约束当使用renderNotification时renderAvatar、renderSubject、renderBody、renderDefaultActions、renderCustomActions均不可同时传入。这一约束在类型层面被强制实现——NotificationRendererProps与SubjectBodyRendererProps构成互斥联合见 types.ts在 Inbox.tsx 的挂载逻辑中也据此分叉到两条不同的mountComponent分支。五、粒度渲染定制只改想改的部分当只想调整通知的局部样式如头像、标题、正文、默认操作按钮而非重写整条通知时使用粒度化渲染插槽。这组 API 不会与其他布局冲突适合在保留 Novu 默认布局的前提下做局部视觉定制Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 renderAvatar{(notification) ( img src{notification.avatar || /default-avatar.png} classNameavatar / )} renderSubject{(notification) ( strong classNamecustom-subject{notification.subject}/strong )} renderBody{(notification) ( p classNamecustom-body{notification.body}/p )} renderDefaultActions{(notification) ( div classNameactions {notification.primaryAction ( button onClick{() notification.primaryAction?.redirect?.url} {notification.primaryAction.label} /button )} /div )} /对应源码中的渲染器类型types.ts渲染插槽类型签名职责renderAvatar(notification) ReactNode通知头像renderSubject(notification) ReactNode通知标题renderBody(notification) ReactNode通知正文renderDefaultActions(notification) ReactNode默认操作区primary/secondary action 按钮renderCustomActions(notification) ReactNode自定义操作区插槽其中renderCustomActions在示例中虽未演示但同样被 Inbox.tsx 与 Notifications.tsx 支持可用于在默认操作按钮之外追加自定义按钮区域。六、事件处理通知点击与操作回调Inbox 提供三个核心事件回调用于响应通知本身及操作按钮的交互Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 onNotificationClick{(notification) { console.log(Clicked:, notification.id); if (notification.redirect?.url) { window.location.href notification.redirect.url; } }} onPrimaryActionClick{(notification) { console.log(Primary action:, notification.primaryAction?.label); }} onSecondaryActionClick{(notification) { console.log(Secondary action:, notification.secondaryAction?.label); }} /onNotificationClick点击通知条目时触发常用于实现跳转逻辑。示例演示了读取notification.redirect.url进行页面跳转更推荐的做法是将routerPush传给 Inbox见下文组合组件由框架路由接管跳转。onPrimaryActionClick/onSecondaryActionClick点击通知上的主/次操作按钮时触发可通过notification.primaryAction、notification.secondaryAction读取按钮配置。事件处理器同样被透传至底层 UI在 Inbox.tsx 中它们作为mountComponent的 props 传入并在两个渲染分支中保持一致。七、主题定制用 appearance 变量快速换肤通过appearance.variables可以一键定义通知中心的品牌色、背景、前景色、字号与圆角无需触碰 CSS 文件Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 appearance{{ variables: { colorPrimary: #6366F1, colorBackground: #1E1B4B, colorForeground: #E0E7FF, fontSize: 14px, borderRadius: 12px, }, }} /上述variables并非凭空设计——它们与底层主题系统一一对应。仓库中的默认主题变量定义在 defaultVariables.ts变量默认值作用colorPrimary#7D52F4品牌主色colorPrimaryForegroundwhite主色上的前景文字色colorBackground#FCFCFC组件背景色colorForeground#1A1523前景文字色borderRadius0.375rem圆角基准此外novu/js/ui/themes还内置了完整的深色主题dark.ts见 dark.ts可通过baseTheme叠加组合。底层会把variables展开为 CSS 自定义属性如--nv-color-primary、--nv-radius-lg再生成对应的 alpha 阴影色阶与圆角规则见 helpers/utils.ts这也是为什么只需少量变量即可驱动整个组件库的配色。React 侧的appearance类型支持baseTheme且允许以数组传入多套主题见 types.ts并按版本适配后透传给底层 UI见 NovuUI.tsx。八、组合式组件自由编排布局默认的Inbox是一体化方案当需要完全掌控布局例如铃铛放在导航栏、通知面板放在页面侧边栏时可以使用组合式子组件。Inbox包裹子组件后仅承担 Provider 与配置传递职责布局由子组件决定import { Inbox, Bell, Notifications, Preferences } from novu/react; function NotificationCenter() { return ( Inbox applicationIdentifier{process.env.REACT_APP_NOVU_APP_ID!} subscriberIdsubscriber-123 Bell / Notifications / Preferences / /Inbox ); }Bell未读铃铛。可通过自身renderBell定制Bell.tsx。Notifications通知列表。支持与整体 Inbox 相同的全部渲染插槽与事件回调renderNotification、renderAvatar、renderSubject、renderBody、renderDefaultActions、renderCustomActions、三个事件处理器见 Notifications.tsx。Preferences订阅偏好设置面板让用户管理各工作流/渠道的通知开关Preferences.tsx。在源码中Inbox通过isWithChildrenProps判断是否传入 children从而在「渲染默认布局」与「仅提供 NovuUI 上下文」两种模式间切换见 Inbox.tsx。组合模式下NovuUI会实例化底层 UI 引擎并将实例通过 Context 暴露给各子组件见 NovuUI.tsx子组件再各自调用novuUI.mountComponent完成挂载。九、源码视角的进阶能力速览除文档示例外结合仓库源码可以确认以下进阶能力Keyless 模式applicationIdentifier可为空字符串由 API 侧自动生成标识适合本地开发或无应用标识的快速体验Inbox.tsx。subscriber新 API替代已废弃的subscriberId支持传Subscriber对象或字符串types.ts。弹层定位placement与placementOffset可控制通知弹层的方位与偏移types.ts。实时性控制NovuProviderhooks 版本支持realtime属性关闭后 WebSocket 自动注入新通知的行为由你自行接管配合novu.on(notifications.notification_received, ...)与refetch()手动刷新NovuProvider.tsx。更多高级参数tabs多标签页、localization本地化文案、preferencesFilter/preferenceGroups/preferencesSort偏好面板过滤与排序、routerPush路由跳转接管、backendUrl/socketUrl/socketOptions自定义后端与 Socket 地址等均可通过 props 传入types.ts。十、进一步探索完整组件导出清单见 packages/react/src/components/index.ts包含ConnectChat、SlackConnectButton、Subscription、TelegramConnectButton等更多组件。主题系统与暗色模式可继续阅读 packages/js/src/ui/themes/dark.ts 与 defaultVariables.ts。同系列参考文档品牌化与样式branding-and-styling.md、无头模式headless-inbox-examples.md、多租户multi-tenancy.md、Next.js 集成nextjs-inbox-examples.md、个性化personalization.md与安全security.md。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考