@miot-rn/common-component 1.0.2 → 1.0.4

package/dist/service/track/TrackService.js

@@ -0,0 +1,104 @@
+import { Service } from 'miot';
+import { Platform } from 'react-native';
+let _config = null;
+let _currentRef = '';
+let _currentSubRef = '';
+const _debugLog = [];
+
+/** 初始化，插件入口调用一次 */
+export function initTrackService(config) {
+  _config = config;
+}
+
+/**
+ * 读取已注册的埋点公参。
+ *
+ * 给自带上报通道的第三方组件用（如 miot/ui/smartScene 的 trackParams）：那些组件不经过本文件的
+ * reportTrack，公参必须由调用方拼进它们的载荷，从这里取可保证与 reportTrack 同一来源、不会漂移。
+ * 未 init 时返回空对象，调用方无需判空。
+ */
+export function getCommonParams() {
+  return _config ? _config.getCommonParams() : {};
+}
+
+/**
+ * 设置当前页面 ref（同步到 Native），并驱动 Android 的页面 view。
+ *
+ * 双端差异（与已上线的 stdcamera / 门铃 / miot.plugin.spec 完全一致）：
+ *   - Android：页面 view 由 Native「内部 view 机制」自主产出、SDK 计算 duration，只依赖插件
+ *     通过 updatePluginPageRef 设置的 ref/subRef，且**必须携带插件公参**
+ *     (package_name/package_id/plugin_id/plugin_version/did/device_model...)，否则 Native
+ *     不知道当前是哪个插件页、无法产出该页 view。只要每次进入/切换页面都用带公参的
+ *     updatePluginPageRef 设置新 ref，Native 就会在下一次 ref 变化（或插件退出）时结算并上报
+ *     上一页的 view（含 from_ref 来源链）。
+ *   - iOS：不依赖公参，view 由 reportTrack 显式经 reportEventRefChannel('view') 上报。
+ *
+ * 同值去重：Native 端每次调用都会把 old current_ref 当作下一条事件的 from_ref，同 (ref,subRef)
+ * 重复调用会让 from_ref 串档为自己。这里在 JS 侧短路。
+ */
+export function setPageRef(ref, subRef) {
+  const sub = subRef || ref;
+  if (ref === _currentRef && sub === _currentSubRef) {
+    return;
+  }
+  _currentRef = ref;
+  _currentSubRef = sub;
+  // Native updatePluginPageRef 的 JSDoc 要求 key 为 ref / subRef(驼峰)；同时带 sub_ref(下划线)
+  // 兼容事件 schema。
+  // Android 的页面 view 由 Native 依据这里的 refParams 自主产出（见下文平台差异说明），
+  // 必须把 item_type 一并塞进来，否则 Native 生成的 view 事件缺 item_type（MIIO-130722）。
+  const refParams = {
+    ref,
+    subRef: sub,
+    sub_ref: sub,
+    item_type: 'ref'
+  };
+  // Android 的 view 机制强依赖此处携带的插件公参（见上方说明）；iOS 无需。
+  if (Platform.OS === 'android' && _config) {
+    Object.assign(refParams, _config.getCommonParams());
+  }
+  Service.smarthome.updatePluginPageRef?.(refParams);
+}
+
+/**
+ * 核心上报方法
+ * 底层 SDK reportEventRefChannel 接受单个事件类型，
+ * 遍历 eventTypes 逐个上报，确保每条事件独立发送。
+ */
+export function reportTrack(eventTypes, params = {}) {
+  if (!_config) return;
+  const finalParams = {
+    ref: _currentRef,
+    sub_ref: _currentSubRef,
+    ..._config.getCommonParams(),
+    ...params
+  };
+  for (const eventType of eventTypes) {
+    if (_config.debug) {
+      // eslint-disable-next-line no-console
+      console.log('[Track]', eventType, finalParams);
+      _debugLog.push({
+        time: Date.now(),
+        event: eventType,
+        params: {
+          ...finalParams
+        }
+      });
+      if (_debugLog.length > 200) _debugLog.shift();
+    }
+    // 页面 view 的双端差异（与 stdcamera / 门铃 / miot.plugin.spec 一致）：
+    //   - Android：view 由 Native 内部机制依据 updatePluginPageRef(带公参) 自主产出、SDK 计算
+    //     duration，**不能**经 reportEventRefChannel(平台侧不消费、且会与内部机制冲突)。此处跳过——
+    //     Android view 已由 setPageRef 在每次页面切换时驱动。
+    //   - iOS：view 必须显式经 reportEventRefChannel('view') 上报，SDK 使用 JS 计算的 duration。
+    if (eventType === 'view' && Platform.OS === 'android') {
+      continue;
+    }
+    Service.smarthome.reportEventRefChannel?.(eventType, finalParams);
+  }
+}
+
+/** 调试用：获取最近上报记录 */
+export function getTrackLog() {
+  return _debugLog;
+}

package/dist/service/track/index.d.ts

@@ -0,0 +1,12 @@
+export { initTrackService, setPageRef, reportTrack, getTrackLog, getCommonParams } from './TrackService';
+export { usePageTrack } from './usePageTrack';
+export { useCardTrack } from './useCardTrack';
+export { useTrack } from './useTrack';
+export { useExposeOnVisible } from './useExposeOnVisible';
+export { TrackScrollView } from './TrackScrollView';
+export { TrackFlatList } from './TrackFlatList';
+export { useTrackScrollProvider } from './useTrackScrollProvider';
+export { TrackScrollContext } from './TrackScrollContext';
+export type { TrackScrollContextValue, ScrollListener, MeasurableNode } from './TrackScrollContext';
+export type { TrackEventType, TrackItemType, TrackParams, TrackServiceConfig } from './types';
+export type { Frame } from './intersect';

package/dist/service/track/index.js

@@ -0,0 +1,9 @@
+export { initTrackService, setPageRef, reportTrack, getTrackLog, getCommonParams } from "./TrackService";
+export { usePageTrack } from "./usePageTrack";
+export { useCardTrack } from "./useCardTrack";
+export { useTrack } from "./useTrack";
+export { useExposeOnVisible } from "./useExposeOnVisible";
+export { TrackScrollView } from "./TrackScrollView";
+export { TrackFlatList } from "./TrackFlatList";
+export { useTrackScrollProvider } from "./useTrackScrollProvider";
+export { TrackScrollContext } from "./TrackScrollContext";

package/dist/service/track/intersect.d.ts

@@ -0,0 +1,8 @@
+export interface Frame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function visibleRatio(item: Frame, viewport: Frame): number;
+export declare function isVisible(item: Frame, viewport: Frame, threshold: number): boolean;

package/dist/service/track/intersect.js

@@ -0,0 +1,15 @@
+/**
+ * 矩形相交可见比例（item 在 viewport 内的高度 / item 自身高度）。
+ * 横向不相交直接返回 0，避免 carousel 里横向滚出视口的 item 被误判为可见。
+ */
+export function visibleRatio(item, viewport) {
+  if (item.height <= 0 || item.width <= 0) return 0;
+  const vOverlap = Math.max(0, Math.min(item.y + item.height, viewport.y + viewport.height) - Math.max(item.y, viewport.y));
+  const hOverlap = Math.max(0, Math.min(item.x + item.width, viewport.x + viewport.width) - Math.max(item.x, viewport.x));
+  if (hOverlap <= 0) return 0;
+  return vOverlap / item.height;
+}
+export function isVisible(item, viewport, threshold) {
+  if (threshold <= 0) return visibleRatio(item, viewport) > 0;
+  return visibleRatio(item, viewport) >= threshold;
+}

package/dist/service/track/intersect.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/service/track/intersect.test.js

@@ -0,0 +1,189 @@
+/// <reference types="jest" />
+
+/**
+ * 视口相交判定的纯几何用例。
+ *
+ * 这套判定算错了不会抛错：曝光要么静默丢失、要么重复上报，日志和肉眼都发现不了。
+ * 埋点基础层其余部分已在 oversea 线上验证过，只有这个纯函数值得单独钉住边界。
+ *
+ * 需要长期钉住的两条非直觉行为（改动时若断言变红，说明语义被换掉了，不是测试过时）：
+ * 1. 比例只按**纵向**算，横向只是「有没有相交」的开关 —— 横向露一半、纵向全露，比例仍是 1。
+ * 2. item 比视口高时比例永远 < 1，threshold=1 会导致该 item 永不曝光。
+ */
+
+import { visibleRatio, isVisible } from "./intersect";
+
+/** 典型竖屏滚动容器视口：纵向占据 y=100~700 */
+const viewport = {
+  x: 0,
+  y: 100,
+  width: 390,
+  height: 600
+};
+const item = o => ({
+  x: 0,
+  y: 100,
+  width: 390,
+  height: 100,
+  ...o
+});
+describe('visibleRatio', () => {
+  it('完全落在视口内 → 1', () => {
+    expect(visibleRatio(item({
+      y: 300
+    }), viewport)).toBe(1);
+  });
+  it('完全在视口下方 → 0', () => {
+    expect(visibleRatio(item({
+      y: 800
+    }), viewport)).toBe(0);
+  });
+  it('完全在视口上方 → 0', () => {
+    expect(visibleRatio(item({
+      y: -200
+    }), viewport)).toBe(0);
+  });
+  it('上边缘与视口顶部相切（贴着但没进来）→ 0', () => {
+    expect(visibleRatio(item({
+      y: 0,
+      height: 100
+    }), viewport)).toBe(0);
+  });
+  it('下边缘与视口底部相切 → 0', () => {
+    expect(visibleRatio(item({
+      y: 700
+    }), viewport)).toBe(0);
+  });
+  it('从底部露出一半 → 0.5', () => {
+    expect(visibleRatio(item({
+      y: 650,
+      height: 100
+    }), viewport)).toBe(0.5);
+  });
+  it('从顶部滚出一半 → 0.5', () => {
+    expect(visibleRatio(item({
+      y: 50,
+      height: 100
+    }), viewport)).toBe(0.5);
+  });
+  it('item 比视口高 → 比例按视口高度截断，永远拿不到 1', () => {
+    // 1200 高的长卡片纵向铺满视口，可见比例只有 600/1200
+    expect(visibleRatio(item({
+      y: 0,
+      height: 1200
+    }), viewport)).toBe(0.5);
+  });
+  it('横向完全滚出视口（carousel 场景）→ 0，即使纵向完全相交', () => {
+    expect(visibleRatio(item({
+      x: 400,
+      width: 100,
+      y: 300
+    }), viewport)).toBe(0);
+  });
+  it('横向相切 → 0', () => {
+    expect(visibleRatio(item({
+      x: 390,
+      width: 100,
+      y: 300
+    }), viewport)).toBe(0);
+  });
+  it('横向只露一部分、纵向全露 → 1（比例只按纵向算）', () => {
+    expect(visibleRatio(item({
+      x: 195,
+      width: 390,
+      y: 300
+    }), viewport)).toBe(1);
+  });
+  it('零高度 → 0，不产出 NaN', () => {
+    const r = visibleRatio(item({
+      height: 0,
+      y: 300
+    }), viewport);
+    expect(r).toBe(0);
+    expect(Number.isNaN(r)).toBe(false);
+  });
+  it('零宽度 → 0', () => {
+    expect(visibleRatio(item({
+      width: 0,
+      y: 300
+    }), viewport)).toBe(0);
+  });
+  it('负尺寸（measureInWindow 异常值）→ 0，不产出负比例', () => {
+    expect(visibleRatio(item({
+      height: -100,
+      y: 300
+    }), viewport)).toBe(0);
+    expect(visibleRatio(item({
+      width: -390,
+      y: 300
+    }), viewport)).toBe(0);
+  });
+});
+describe('isVisible', () => {
+  it('threshold=0 → 相交一个像素即可见', () => {
+    expect(isVisible(item({
+      y: 699,
+      height: 100
+    }), viewport, 0)).toBe(true);
+  });
+  it('threshold=0 → 相切不算可见', () => {
+    expect(isVisible(item({
+      y: 700
+    }), viewport, 0)).toBe(false);
+  });
+  it('threshold=0 → 横向滚出不算可见', () => {
+    expect(isVisible(item({
+      x: 400,
+      width: 100,
+      y: 300
+    }), viewport, 0)).toBe(false);
+  });
+  it('比例恰好等于 threshold → 可见（取 >=，边界不丢曝光）', () => {
+    expect(visibleRatio(item({
+      y: 650,
+      height: 100
+    }), viewport)).toBe(0.5);
+    expect(isVisible(item({
+      y: 650,
+      height: 100
+    }), viewport, 0.5)).toBe(true);
+  });
+  it('比例差一个像素低于 threshold → 不可见', () => {
+    expect(visibleRatio(item({
+      y: 651,
+      height: 100
+    }), viewport)).toBeCloseTo(0.49, 5);
+    expect(isVisible(item({
+      y: 651,
+      height: 100
+    }), viewport, 0.5)).toBe(false);
+  });
+  it('threshold=1 → 只有完整落入视口才算可见', () => {
+    expect(isVisible(item({
+      y: 300
+    }), viewport, 1)).toBe(true);
+    expect(isVisible(item({
+      y: 650,
+      height: 100
+    }), viewport, 1)).toBe(false);
+  });
+  it('threshold=1 且 item 比视口高 → 永不可见（调用方不能对长卡片用 threshold=1）', () => {
+    expect(isVisible(item({
+      y: 0,
+      height: 1200
+    }), viewport, 1)).toBe(false);
+    expect(isVisible(item({
+      y: 100,
+      height: 1200
+    }), viewport, 1)).toBe(false);
+  });
+  it('负 threshold 按 0 处理', () => {
+    expect(isVisible(item({
+      y: 699,
+      height: 100
+    }), viewport, -1)).toBe(true);
+    expect(isVisible(item({
+      y: 700
+    }), viewport, -1)).toBe(false);
+  });
+});

package/dist/service/track/types.d.ts

@@ -0,0 +1,16 @@
+export type TrackEventType = 'click' | 'expose' | 'view' | 'control' | 'scroll' | 'drag' | 'play';
+export type TrackItemType = 'ref' | 'card' | 'button' | 'item' | 'dialog' | 'area';
+export interface TrackParams {
+    ref?: string;
+    sub_ref?: string;
+    item_type?: TrackItemType;
+    item_name?: string;
+    item_content?: string;
+    card_name?: string;
+    duration?: number;
+    [key: string]: unknown;
+}
+export interface TrackServiceConfig {
+    getCommonParams: () => Record<string, unknown>;
+    debug?: boolean;
+}

package/dist/service/track/types.js

@@ -0,0 +1 @@
+export {};

package/dist/service/track/useCardTrack.d.ts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+import { MeasurableNode } from './TrackScrollContext';
+import type { TrackEventType, TrackParams } from './types';
+interface UseCardTrackOptions {
+    cardName: string;
+    viewRef?: RefObject<MeasurableNode | null>;
+    threshold?: number;
+}
+export declare function useCardTrack({ cardName, viewRef, threshold }: UseCardTrackOptions): {
+    trackEvent: (eventTypes: TrackEventType[], params?: TrackParams) => void;
+    trackExpose: (itemName: string, extra?: TrackParams) => void;
+    trackClick: (itemName: string, extra?: TrackParams) => void;
+};
+export {};

package/dist/service/track/useCardTrack.js

@@ -0,0 +1,61 @@
+import { useCallback, useRef } from 'react';
+import { reportTrack } from "./TrackService";
+import { useExposeOnVisible } from "./useExposeOnVisible";
+export function useCardTrack({
+  cardName,
+  viewRef,
+  threshold = 0
+}) {
+  const fallbackRef = useRef(null);
+  const effectiveRef = viewRef ?? fallbackRef;
+  const hasExplicitRef = !!viewRef;
+  useExposeOnVisible({
+    viewRef: effectiveRef,
+    threshold,
+    enabled: !!cardName,
+    forceMountFallback: !hasExplicitRef,
+    onExpose: () => {
+      reportTrack(['expose'], {
+        item_type: 'card',
+        card_name: cardName
+      });
+    }
+  });
+
+  /** 通用事件上报（自动带 card_name） */
+  const trackEvent = useCallback((eventTypes, params = {}) => {
+    reportTrack(eventTypes, {
+      card_name: cardName,
+      ...params
+    });
+  }, [cardName]);
+
+  /** 元素曝光 */
+  const trackExpose = useCallback((itemName, extra) => {
+    reportTrack(['expose'], {
+      card_name: cardName,
+      item_type: 'button',
+      item_name: itemName,
+      ...extra
+    });
+  }, [cardName]);
+
+  /** 元素点击（自动附带卡片级 click） */
+  const trackClick = useCallback((itemName, extra) => {
+    reportTrack(['click'], {
+      item_type: 'card',
+      card_name: cardName
+    });
+    reportTrack(['click'], {
+      card_name: cardName,
+      item_type: 'button',
+      item_name: itemName,
+      ...extra
+    });
+  }, [cardName]);
+  return {
+    trackEvent,
+    trackExpose,
+    trackClick
+  };
+}

package/dist/service/track/useExposeOnVisible.d.ts

@@ -0,0 +1,11 @@
+import { RefObject } from 'react';
+import { MeasurableNode } from './TrackScrollContext';
+interface UseExposeOnVisibleOptions {
+    viewRef: RefObject<MeasurableNode | null>;
+    onExpose: () => void;
+    threshold?: number;
+    enabled?: boolean;
+    forceMountFallback?: boolean;
+}
+export declare function useExposeOnVisible({ viewRef, onExpose, threshold, enabled, forceMountFallback, }: UseExposeOnVisibleOptions): void;
+export {};

package/dist/service/track/useExposeOnVisible.js

@@ -0,0 +1,74 @@
+import { useContext, useEffect, useRef } from 'react';
+import { InteractionManager } from 'react-native';
+import { TrackScrollContext } from "./TrackScrollContext";
+import { isVisible } from "./intersect";
+/**
+ * viewRef 进入最近 TrackScrollContext 视口时触发一次 onExpose。
+ *
+ * - 没有 Provider 或 forceMountFallback → mount 触发降级（与升库前等价，保持向后兼容）
+ * - 有 Provider → 订阅 scroll/layout 通知；命中即 unsubscribe，稳态零开销
+ * - 初次检查走 InteractionManager 等 react-navigation 转场动画结束（v2 约 250ms）再测
+ */
+export function useExposeOnVisible({
+  viewRef,
+  onExpose,
+  threshold = 0,
+  enabled = true,
+  forceMountFallback = false
+}) {
+  const ctx = useContext(TrackScrollContext);
+  const exposedRef = useRef(false);
+  const onExposeRef = useRef(onExpose);
+  onExposeRef.current = onExpose;
+  useEffect(() => {
+    if (!enabled || exposedRef.current) return undefined;
+
+    // 没有 Provider 或调用方未挂 viewRef → mount 触发降级
+    if (forceMountFallback || !ctx) {
+      exposedRef.current = true;
+      onExposeRef.current();
+      return undefined;
+    }
+    let canceled = false;
+    let unsub;
+    const fire = () => {
+      if (exposedRef.current) return;
+      exposedRef.current = true;
+      onExposeRef.current();
+      unsub?.();
+    };
+    const check = () => {
+      if (exposedRef.current || canceled) return;
+      const itemNode = viewRef.current;
+      const containerNode = ctx.containerRef.current;
+      if (!itemNode || !containerNode) return;
+      itemNode.measureInWindow((ix, iy, iw, ih) => {
+        if (exposedRef.current || canceled) return;
+        if (iw <= 0 || ih <= 0) return;
+        containerNode.measureInWindow((cx, cy, cw, ch) => {
+          if (exposedRef.current || canceled) return;
+          const item = {
+            x: ix,
+            y: iy,
+            width: iw,
+            height: ih
+          };
+          const viewport = {
+            x: cx,
+            y: cy,
+            width: cw,
+            height: ch
+          };
+          if (isVisible(item, viewport, threshold)) fire();
+        });
+      });
+    };
+    unsub = ctx.subscribe(check);
+    const handle = InteractionManager.runAfterInteractions(check);
+    return () => {
+      canceled = true;
+      unsub?.();
+      handle.cancel?.();
+    };
+  }, [ctx, viewRef, threshold, enabled, forceMountFallback]);
+}

package/dist/service/track/usePageTrack.d.ts

@@ -0,0 +1,7 @@
+interface UsePageTrackOptions {
+    ref: string;
+    subRef?: string;
+    navigation?: any;
+}
+export declare function usePageTrack({ ref, subRef, navigation }: UsePageTrackOptions): void;
+export {};

package/dist/service/track/usePageTrack.js

@@ -0,0 +1,101 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { AppState } from 'react-native';
+import { setPageRef, reportTrack } from "./TrackService";
+/**
+ * 页面级埋点 hook。
+ *
+ * 协议（基于 react-navigation 2.16 + RN 0.61）：
+ *   - setPageRef 在 useLayoutEffect 中执行（不能放 render 期：render 期副作用违反 React 规则，
+ *     且栈式导航下前一页仍挂载并会因 spec 订阅频繁重渲染，render 期 setPageRef 会把 _currentRef
+ *     抢回本页造成串档）。useLayoutEffect 早于所有子组件的 useEffect 执行，仍能保证子卡曝光时
+ *     _currentRef 已就绪；依赖 [ref, subRef] 使其仅在页面标识变化时同步，重渲染不再触发。
+ *   - expose / view 由 willFocus / willBlur 驱动；v2 stack push/pop 不会卸载当前页，
+ *     所以 willFocus 必须负责把 _currentRef 切回当前页。
+ *   - Android 的页面 view 实际由 setPageRef→updatePluginPageRef(带公参) 在每次 ref 变化时
+ *     由 Native 自主产出；这里的 sendView 仅对 iOS 生效（reportTrack 内部按平台分流）。
+ *   - AppState 切前后台仅当前 focused 页响应，避免栈内多个 usePageTrack 实例多发。
+ *   - 没有 navigation 时（modal/wrapper）降级为 mount/unmount 触发。
+ */
+export function usePageTrack({
+  ref,
+  subRef,
+  navigation
+}) {
+  const isFocusedRef = useRef(false);
+  const startRef = useRef(Date.now());
+
+  // 页面 ref 同步：仅在副作用阶段执行，且只在 ref/subRef 变化时触发（见上方协议说明）。
+  useLayoutEffect(() => {
+    setPageRef(ref, subRef || ref);
+  }, [ref, subRef]);
+  useEffect(() => {
+    // 每次 effect 重跑时归零：防止 useRef.current 在 [ref,subRef] 变化时保留旧值，导致新周期
+    // 的 handleFocus 首次调用即 already=true 被短路。
+    isFocusedRef.current = false;
+    const sendExpose = () => {
+      // 切回页时把 _currentRef 切回当前页；同值由 setPageRef 内部 dedupe 短路
+      setPageRef(ref, subRef || ref);
+      // 显式带上本页 ref/sub_ref，避免因 focus/blur 时序被相邻页覆盖导致串档
+      // 页面级点位按事件区分：expose 专属 item_name='page_expose'，view 专属 duration
+      reportTrack(['expose'], {
+        ref,
+        sub_ref: subRef || ref,
+        item_type: 'ref',
+        item_name: 'page_expose'
+      });
+      startRef.current = Date.now();
+    };
+    // 页面停留 view：Android 由 setPageRef 的 updatePluginPageRef 驱动(reportTrack 内部会跳过 view)，
+    // iOS 走显式 reportEventRefChannel('view')，duration 在 JS 侧按 expose→blur 计算。
+    // 显式带上本页 ref/sub_ref，防止 focus/blur 时序被相邻页的 setPageRef 覆盖导致串档。
+    const sendView = () => {
+      reportTrack(['view'], {
+        ref,
+        sub_ref: subRef || ref,
+        item_type: 'ref',
+        duration: Date.now() - startRef.current
+      });
+    };
+    const handleFocus = () => {
+      if (isFocusedRef.current) return;
+      isFocusedRef.current = true;
+      sendExpose();
+    };
+    const handleBlur = () => {
+      if (!isFocusedRef.current) return;
+      isFocusedRef.current = false;
+      sendView();
+    };
+    const unsubWillFocus = navigation?.addListener?.('willFocus', handleFocus);
+    const unsubDidFocus = navigation?.addListener?.('didFocus', handleFocus);
+    const unsubWillBlur = navigation?.addListener?.('willBlur', handleBlur);
+    const unsubDidBlur = navigation?.addListener?.('didBlur', handleBlur);
+
+    // 挂载时无条件补发一次 focus。isFocusedRef 幂等保证不会重复：
+    //   - 无 navigation：兜底触发（modal/wrapper 场景）。
+    //   - initial route：Navigation/INIT 只派发 willFocus 不派发 didFocus，且 willFocus 早于本
+    //     useEffect 注册监听，addListener 抓不到；同时 screen 的 _isFocused 永远保持 false 使
+    //     isFocused() 永远返回 false，任何条件式补发都失效——只能无条件补发（MIIO-131315）。
+    //   - push 进入的二级页：willFocus 已早于本 useEffect 派发，同理需要无条件补发。
+    //   - 已在真派发链路中收到 focus：isFocusedRef 已 true，此处被短路。
+    handleFocus();
+
+    // RN 0.61 的 AppState 旧 API：addEventListener 不返回 subscription，必须 removeEventListener
+    const handleAppState = state => {
+      if (!isFocusedRef.current) return;
+      if (state === 'background') sendView();else if (state === 'active') sendExpose();
+    };
+    AppState.addEventListener('change', handleAppState);
+    return () => {
+      if (isFocusedRef.current) {
+        isFocusedRef.current = false;
+        sendView();
+      }
+      AppState.removeEventListener('change', handleAppState);
+      unsubWillFocus?.remove?.();
+      unsubDidFocus?.remove?.();
+      unsubWillBlur?.remove?.();
+      unsubDidBlur?.remove?.();
+    };
+  }, [ref, subRef]);
+}

package/dist/service/track/useTrack.d.ts

@@ -0,0 +1,7 @@
+import { reportTrack } from './TrackService';
+import type { TrackParams } from './types';
+export declare function useTrack(): {
+    track: typeof reportTrack;
+    click: (itemName: string, extra?: TrackParams) => void;
+    expose: (itemName: string, itemType?: any, extra?: TrackParams) => void;
+};

package/dist/service/track/useTrack.js

@@ -0,0 +1,23 @@
+import { useCallback } from 'react';
+import { reportTrack } from "./TrackService";
+export function useTrack() {
+  const click = useCallback((itemName, extra) => {
+    reportTrack(['click'], {
+      item_type: 'button',
+      item_name: itemName,
+      ...extra
+    });
+  }, []);
+  const expose = useCallback((itemName, itemType = 'item', extra) => {
+    reportTrack(['expose'], {
+      item_type: itemType,
+      item_name: itemName,
+      ...extra
+    });
+  }, []);
+  return {
+    track: reportTrack,
+    click,
+    expose
+  };
+}