React-tracking 完全指南：10分钟掌握React声明式追踪

【免费下载链接】react-tracking 🎯 Declarative tracking for React apps. 项目地址: https://gitcode.com/gh_mirrors/re/react-tracking

React-tracking 是一个专为 React 应用设计的声明式追踪库，它提供了高阶组件和 React Hook 两种使用方式，能帮助开发者将追踪逻辑与组件代码解耦，实现更清晰、更可维护的事件追踪方案。无论是用户交互事件还是页面访问数据，React-tracking 都能以优雅的方式进行处理，且不依赖于特定的分析平台。

快速入门：安装与基础配置

一键安装步骤

使用 npm 即可快速安装 React-tracking：

npm install --save react-tracking

安装完成后，你可以通过两种主要方式在项目中使用：作为高阶组件（装饰器形式或直接使用）或通过 React Hook。

核心模块导入

基础使用只需导入 track 装饰器和 useTracking Hook：

import track, { useTracking } from 'react-tracking';

两种使用模式：Hook 与装饰器

React Hook 最快配置方法 ⚡

useTracking Hook 是 React 函数组件的理想选择，它返回 trackEvent 方法和 <Track> 组件，前者用于手动触发追踪事件，后者用于传递上下文追踪数据给子组件。

基础示例：

import { useTracking } from 'react-tracking';

const FooPage = () => {
  const { Track, trackEvent } = useTracking({ page: 'FooPage' });

  return (
    <Track>
      <button onClick={() => trackEvent({ action: 'buttonClick' })}>
        点击触发追踪
      </button>
    </Track>
  );
};

当按钮被点击时，会自动发送如下追踪数据：

{ page: 'FooPage', action: 'buttonClick' }

类组件装饰器使用指南

对于类组件，可以使用 @track 装饰器语法，这需要配置 Babel 装饰器插件。装饰器可用于类本身或类方法，实现组件挂载时自动追踪或方法调用时触发追踪。

类装饰器示例：

import track from 'react-tracking';

@track({ page: 'HomePage' }, { dispatchOnMount: true })
class HomePage extends React.Component {
  // 组件挂载时自动发送 { page: 'HomePage' }
}

方法装饰器示例：

@track({ page: 'HomePage' })
class HomePage extends React.Component {
  @track({ action: 'loginClick' })
  handleLogin = () => {
    // 点击时自动发送 { page: 'HomePage', action: 'loginClick' }
  };
}

高级功能：自定义与上下文传递

自定义数据发送目标

React-tracking 默认将数据发送到 window.dataLayer（适用于 Google Tag Manager），但你可以通过 dispatch 选项自定义发送逻辑。在顶层组件配置一次即可全局生效：

// 顶层 App 组件
const { Track } = useTracking(
  {},
  { dispatch: data => window.myCustomDataLayer.push(data) }
);

核心实现逻辑位于 src/dispatchTrackingEvent.js，默认代码如下：

export default function dispatchTrackingEvent(data) {
  if (typeof window !== 'undefined' && Object.keys(data).length > 0) {
    (window.dataLayer = window.dataLayer || []).push(data);
  }
}

组件间上下文追踪数据传递

通过 <Track> 组件或装饰器，追踪数据会自动沿着组件树向下合并。子组件无需重复定义父组件已提供的基础数据：

// 父组件提供 page 数据
const Parent = () => {
  const { Track } = useTracking({ page: 'ProductList' });
  return <Track><Child /></Track>;
};

// 子组件自动继承 page 数据
const Child = () => {
  const { trackEvent } = useTracking({ component: 'AddToCartButton' });
  return (
    <button onClick={() => trackEvent({ action: 'click' })}>
      加入购物车
    </button>
  );
};

点击按钮时发送的数据：

{ page: 'ProductList', component: 'AddToCartButton', action: 'click' }

实用场景：从页面访问到用户交互

页面加载自动追踪

通过 dispatchOnMount 选项，可在组件挂载时自动发送追踪数据，适合页面访问统计：

// 函数组件
useTracking({ page: 'AboutUs' }, { dispatchOnMount: true });

// 类组件
@track({ page: 'AboutUs' }, { dispatchOnMount: true })
class AboutUs extends React.Component {}

异步操作追踪

对于返回 Promise 的异步方法，React-tracking 会自动在 Promise 决议后发送追踪数据：

class DataLoader extends React.Component {
  @track({ action: 'dataLoaded' })
  async fetchData() {
    const result = await api.getData();
    return result; // 追踪数据会在请求完成后发送
  }
}

动态追踪数据生成

追踪数据支持函数形式，可根据 props、state 或方法参数动态生成：

@track((props, state, [event]) => ({
  action: 'click',
  label: event.target.textContent,
  userId: props.currentUser.id
}))
handleButtonClick = (event) => {
  // 点击事件会发送动态生成的追踪数据
};

类型支持与工具集成

TypeScript 类型定义

安装 @types/react-tracking 即可获得完整类型支持，确保代码类型安全：

import { useTracking } from 'react-tracking';

interface TrackingData {
  page: string;
  action?: string;
}

const { trackEvent } = useTracking<TrackingData>({ page: 'Dashboard' });

PropType 验证

如需验证 tracking 属性，可导入 TrackingPropType：

import { TrackingPropType } from 'react-tracking';

MyComponent.propTypes = {
  tracking: TrackingPropType
};

总结：为什么选择 React-tracking？

React-tracking 以声明式方式解决了 React 应用中的事件追踪问题，其核心优势包括：

• 关注点分离：追踪逻辑与业务逻辑解耦，组件更专注于 UI 渲染
• 上下文传递：自动合并组件树中的追踪数据，避免重复定义
• 灵活 API：同时支持 Hook 和装饰器，适配不同组件风格
• 平台无关：可对接任何分析平台，通过自定义 dispatch 实现数据转发

通过本文介绍的方法，你可以在 10 分钟内掌握 React-tracking 的核心用法，并在实际项目中快速实现专业的事件追踪系统。无论是小型应用还是大型项目，React-tracking 都能帮助你更优雅地处理数据收集需求。

要开始使用，只需执行：

git clone https://gitcode.com/gh_mirrors/re/react-tracking

探索示例代码并将其集成到你的项目中。

【免费下载链接】react-tracking 🎯 Declarative tracking for React apps. 项目地址: https://gitcode.com/gh_mirrors/re/react-tracking