React Navigation 集成

通过启用 EAS Observe 的 React Navigation 集成，跟踪每个屏幕的渲染和交互耗时。

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

EAS Observe 提供了一个可选的 React Navigation 集成，用于收集按屏幕划分的指标，并使用该屏幕的路由名路径进行标记（例如，/Tabs/Sessions）。这样你就可以在仪表板中按屏幕比较导航性能，而不只是查看全应用范围的汇总数据。

如果你的应用使用的是 Expo Router，请改用 Expo Router 集成。本页面适用于直接使用 React Navigation 的应用。

前提条件

import { Observe } from 'expo-observe';

Observe.configure({
  integrations: { 'react-navigation': true },
});

import { Observe } from 'expo-observe';
import { ObserveNavigationContainer } from 'expo-observe/integrations/react-navigation';

Observe.configure({
  integrations: { 'react-navigation': true },
});

export default function App() {
  return <ObserveNavigationContainer>{/* your navigators */}</ObserveNavigationContainer>;
}

import { createStaticNavigation, useNavigationContainerRef } from '@react-navigation/native';
import { Observe } from 'expo-observe';
import { ObserveNavigationProvider } from 'expo-observe/integrations/react-navigation';

import { RootStack } from './navigation';

Observe.configure({
  integrations: { 'react-navigation': true },
});

const Navigation = createStaticNavigation(RootStack);

export default function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <ObserveNavigationProvider navigationRef={navigationRef}>
      <Navigation ref={navigationRef} />
    </ObserveNavigationProvider>
  );
}

import { useObserve } from 'expo-observe';
import { useEffect } from 'react';

export default function Home() {
  const { markInteractive } = useObserve();

  useEffect(() => {
    markInteractive();
  }, [markInteractive]);

  return (/* your screen content */);
}

指标

按屏幕首次渲染（cold_ttr）

它衡量的内容： 从导航动作被派发时开始计算（例如 navigation.navigate()），到目标屏幕首次获得焦点为止的时间。对于应用启动后的第一次获得焦点，该测量从 JS bundle 加载时开始，且事件会包含 isAppLaunch: true。

在单个会话中，每个屏幕实例最多发出一次。

事件参数：

按屏幕热渲染（warm_ttr）

它衡量的内容： 与 cold_ttr 相同，但适用于在获得焦点之前就已经渲染过的屏幕，通常是因为它们已被预加载，或者用户返回到了这些屏幕。选项卡导航器中的兄弟屏幕只有在挂载之后才算作热渲染。使用 React Navigation v7 的默认 lazy: true 时，未聚焦的选项卡会保持未挂载状态，它们的首次聚焦会被记录为 cold_ttr。

事件参数：

按屏幕交互就绪时间（tti）

它衡量的内容： 从导航动作被派发时开始计算，到目标屏幕调用 markInteractive() 为止的时间。每次导航只记录第一次调用，因此可以安全地多次调用 markInteractive()。

事件参数：

注意事项和故障排查

• routeName 是根据路由名构建的（/Tabs/Sessions），因此路由参数永远不会出现在路径中。这使得指标在不同参数值之间保持稳定，仪表板会将它们归为同一类。参数值仍可通过 routeParams 在事件中获取。
• 该集成仅在运行时安装了 @react-navigation/native 时才会激活。如果未安装该包，useObserve() 仍然可用，但不会发出按屏幕划分的导航指标。在未安装 @react-navigation/native 的情况下渲染 <ObserveNavigationContainer> 或 <ObserveNavigationProvider> 会抛出错误。
• 必须在挂载前通过 Observe.configure({ integrations: { 'react-navigation': true } }) 启用该集成。在应用挂载后，或在 <ObserveNavigationContainer> / <ObserveNavigationProvider> 已经挂载后再切换它，都会抛出错误。
• 使用静态配置时，请将同一个 ref 同时传给 <ObserveNavigationProvider> 和 <Navigation> 元素。如果 provider 接收到的 ref 并未连接到导航容器，则不会发出按屏幕指标。
• markInteractive() 只有在屏幕获得焦点后才会记录。在未聚焦的屏幕上调用会更新内部状态，但在该屏幕获得焦点之前不会发出 tti 事件。
• 请在屏幕组件内部调用 useObserve()，不要放在更高层的包装组件中。如果屏幕的身份在渲染之间发生变化，hook 会记录警告。如果 markInteractive() 记录了 Calling markInteractive on unmounted screen 或 No metadata available for the current screen，说明该调用发生在屏幕组件之外或在卸载之后。请将调用移动到屏幕组件内的 useEffect 中。
• 关于 EAS Observe 的常规问题，请参阅 故障排查。