@zhaogyna/react

React 适配包，重导出 @zhaogyna/browser 全部 API + React 专有组件。

安装

npm install @zhaogyna/react

peerDependencies: react >= 16.8.0，react-router-dom >= 6.0.0（可选）

本包已内含 @zhaogyna/browser，无需重复安装。

快速开始

import { init, MonitorErrorBoundary } from '@zhaogyna/react'

init({
  dsn: 'https://monitor.example.com/api/envelope',
  release: '1.0.0',
  environment: 'production',
})

function App() {
  return (
    <MonitorErrorBoundary fallback={<h1>Something went wrong</h1>}>
      <MyApp />
    </MonitorErrorBoundary>
  )
}

完整配置项

与 @zhaogyna/browser 完全一致，参见 @zhaogyna/browser 配置项。

React 专有 API

MonitorErrorBoundary

错误边界组件，捕获子组件树中的渲染异常。

import { MonitorErrorBoundary } from '@zhaogyna/react'

function App() {
  return (
    <MonitorErrorBoundary
      // Fallback UI — 支持静态节点或 render prop
      fallback={<h1>Something went wrong</h1>}
      // fallback={({ error, resetError }) => (
      //   <div>
      //     <p>{error.message}</p>
      //     <button onClick={resetError}>Retry</button>
      //   </div>
      // )}

      // 错误捕获回调
      onError={(error, componentStack) => {
        console.error('Caught:', error, componentStack)
      }}

      // 捕获前修改 Scope（一次性，不污染全局）
      beforeCapture={(scope, error, componentStack) => {
        scope.setTag('section', 'checkout')
        scope.setExtra('componentStack', componentStack)
      }}

      // 重置回调
      onReset={() => {
        console.log('Error boundary reset')
      }}
    >
      <ChildComponents />
    </MonitorErrorBoundary>
  )
}

| Prop | 类型 | 说明 | |------|------|------| | children | ReactNode | 子组件 | | fallback | ReactNode \| (({ error, resetError }) => ReactNode) | Fallback UI | | onError | (error: Error, componentStack: string) => void | 错误捕获回调 | | beforeCapture | (scope, error: Error, componentStack: string) => void | 捕获前修改 Scope | | onReset | () => void | 重置回调 |

内部行为：

• 标记 mechanism = { type: 'react_error_boundary', handled: true }，与 globalErrorHandler 配合避免重复上报
• 附加 componentStack 到 extra

MonitorProfiler

渲染性能采集组件，包裹 React.Profiler。

import { MonitorProfiler } from '@zhaogyna/react'

function App() {
  return (
    <MonitorProfiler id="Dashboard" threshold={50}>
      <Dashboard />
    </MonitorProfiler>
  )
}

| Prop | 类型 | 说明 | |------|------|------| | id | string | 组件标识（必填） | | threshold | number | 慢渲染阈值 ms（默认 50） | | children | ReactNode | 子组件 |

超过阈值的渲染自动添加面包屑（category: react.profiler.{id}），数据包含 component、phase（mount/update）、actualDuration、baseDuration。

注意：React Profiler 回调仅在开发模式或 profiler 生产构建中生效。

useMonitorRouter

配合 React Router v6 自动添加导航面包屑。

import { useMonitorRouter } from '@zhaogyna/react'
import { useLocation } from 'react-router-dom'

function Layout() {
  useMonitorRouter(useLocation())
  return <Outlet />
}

| 参数 | 类型 | 说明 | |------|------|------| | location | { pathname, search, hash, key? } | React Router v6 的 location 对象 |

检测 location 变化自动添加 type: 'navigation' 面包屑，包含 from / to 数据。

重导出的 Browser API

以下 API 从 @zhaogyna/browser 完整重导出，可直接从 @zhaogyna/react 引入：

| API | 说明 | |-----|------| | init | 初始化 SDK | | captureException | 捕获异常 | | captureMessage | 捕获消息 | | track | 自定义埋点 | | setUser | 设置用户信息 | | setTag / setTags | 设置标签 | | setExtra / setExtras | 设置附加数据 | | setLevel | 设置级别 | | setTransaction | 设置事务名 | | setFingerprint | 设置指纹 | | addBreadcrumb / clearBreadcrumbs | 面包屑管理 | | startSpan | 开始追踪 Span | | startFunnel / trackFunnelStep / endFunnel | 漏斗分析 | | addIntegration / lazyLoadIntegration | 集成管理 | | flush / close | 刷新/关闭 SDK | | on | 生命周期监听 | | withScope / getClient | 作用域/客户端 | | createClient / getActiveClients / findClientForUrl | 多实例 | | 所有集成工厂函数 | globalErrorHandler、tryCatchWrapper、breadcrumbCollector、httpInterceptor、dedupe、trackDedupe、httpContext、inboundFilter、functionToString、browserSessionIntegration、performanceVitals、longTaskObserver、resourceObserver、pageViewTracker、clickTracker、exposureTracker、stayTracker、sessionReplay |

License

MIT