反应原生模式

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

目的

使用 React Native 和 Expo 托管工作流程构建的供应商移动应用程序的生产模式。涵盖列表渲染性能、重新动画、Expo Router 导航、NativeWind v5 样式、本机模块使用、状态管理和特定于平台的模式。

世博会管理工作流程

留在托管工作流程中 - 不要弹出,除非本机模块通过 Expo SDK 或社区 Expo 模块绝对不可用。弹出会破坏 OTA 更新。使用 expo-dev-client 进行自定义本机模块的开发构建——而不是裸露的工作流程。通过 Expo Updates 进行 OTA 更新 — 保持 JS 包较小。本机更改需要新的构建。应用程序配置位于app.json / app.config.ts。托管工作流程中无需手动进行Info.plist或AndroidManifest.xml编辑。

列表渲染(关键性能)

对于任何超过 10 个项目的列表,始终使用 FlashList(来自 @shopify/flash-list)而不是 FlatList 或 ScrollView。 FlashList需要estimatedItemSize——测量真实物品,不要猜测。记忆列表项:将项目组件包装在React.memo中。确保 props 稳定(没有内联对象/函数)。稳定回调:在组件外部定义renderItem、keyExtractor、onEndReached或与useCallback一起定义——不稳定的函数会导致完整列表重新渲染。

动画(复活3)

对所有动画使用 React Native Reanimated 3 (react-native-reanimated)。仅适用于 GPU 的属性:transform(translateX、translateY、缩放、旋转)、opacity。切勿对 width、height、top、left、margin、padding 进行动画处理 — 这些会在每一帧上触发布局重新计算。派生值:useDerivedValue从共享值计算动画值——在UI线程上运行,而不是JS线程上。

导航(Expo 路由器)

使用 Expo Router(基于文件,基于 React Navigation 构建)——而不是纯粹的 React Navigation。在 app/ 目录中路由文件 — 镜像 Next.js App Router 约定。动态路线:app/listings/[id].tsx。选项卡导航:来自 Expo Router 的app/(tabs)/_layout.tsx 和 <Tabs>。堆栈导航:app/(stack)/_layout.tsx 和 <Stack>。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# React Native Patterns (Expo Managed + NativeWind v5)

## Purpose
Production patterns for the vendor mobile app built with React Native and Expo managed workflow. Covers list rendering performance, Reanimated animations, navigation with Expo Router, NativeWind v5 styling, native module usage, state management, and platform-specific patterns.

## Core Rules

### Expo Managed Workflow
* Stay within managed workflow — do not eject unless a native module is absolutely unavailable via Expo SDK or a community Expo module. Ejecting breaks OTA updates.
* Use `expo-dev-client` for development builds with custom native modules — not bare workflow.
* OTA updates via Expo Updates — keep JS bundle small. Native changes require a new build.
* App configuration in `app.json` / `app.config.ts`. No manual `Info.plist` or `AndroidManifest.xml` edits in managed workflow.
* Target `expo@latest` SDK. Pin the SDK version explicitly — do not use `*`.

### List Rendering (CRITICAL Performance)
* **Always use `FlashList`** (from `@shopify/flash-list`) instead of `FlatList` or `ScrollView` for any list with more than 10 items.
* `FlashList` requires `estimatedItemSize` — measure a real item, do not guess.
* Memoize list items: wrap item component in `React.memo`. Ensure props are stable (no inline objects/functions).
* Stable callbacks: define `renderItem`, `keyExtractor`, `onEndReached` outside the component or with `useCallback` — unstable functions cause full list re-renders.
* Avoid inline objects in `renderItem`: `renderItem={({ item }) => <Item data={item} />}` is fine; `renderItem={({ item }) => <Item style={{ padding: 8 }} />}` re-renders every scroll.
* Images in lists: use `expo-image` (not `Image` from React Native) — it caches, handles `blurhash`, and recycles efficiently.
* Never use `ScrollView` + `map()` for potentially long lists. It renders all items at once.

### Animations (Reanimated 3)
* Use **React Native Reanimated 3** (`react-native-reanimated`) for all animations.
* **GPU-friendly properties only**: `transform` (translateX, translateY, scale, rotate), `opacity`. Never animate `width`, `height`, `top`, `left`, `margin`, `padding` — these trigger layout recalculation on every frame.
* Derived values: `useDerivedValue` to compute animation values from shared values — runs on the UI thread, not JS thread.
* Gestures: `react-native-gesture-handler` with `GestureDetector`. Never use `onPress` on `Animated.View` — use `Pressable` or `GestureDetector`.
* Shared values: `useSharedValue` for values driven by gestures or timers. `useAnimatedStyle` to map shared values to style.
* `withSpring`, `withTiming` for declarative animations. Avoid `Animated.loop` with Reanimated — use `withRepeat`.

### Navigation (Expo Router)
* Use **Expo Router** (file-based, built on React Navigation) — not bare React Navigation.
* Route files in `app/` directory — mirrors Next.js App Router conventions.
* Dynamic routes: `app/listings/[id].tsx`.
* Tab navigation: `app/(tabs)/_layout.tsx` with `<Tabs>` from Expo Router.
* Stack navigation: `app/(stack)/_layout.tsx` with `<Stack>`.
* Deep linking configured via `app.json` `scheme` field — automatically handled by Expo Router.
* Use native navigators (`native` prop) — renders platform-native navigation chrome (UINavigationController on iOS, Fragment on Android).
* Never use `router.back()` for predictable navigation — use `router.push()` or `router.replace()` with explicit paths.

### NativeWind v5 Styling
* NativeWind v5 + Tailwind CSS v4 — no Babel configuration needed (Metro transformer).
* Import platform-aware components from `react-native-css` wrapper: `View`, `Text`, `ScrollView`, `Pressable`, `TextInput`, `Image`, `Link`.
* `className` prop on these wrapped components — same Tailwind classes as web.
* Platform-specific styles via CSS media queries: `@media (platform: ios) { ... }`, `@media (platform: android) { ... }`.
* Custom theme variables in `src/global.css` via `@theme` block.
* Apple semantic colours: `light-dark()` function in CSS for automatic dark mode. Use `platformColor()` for native system colours (e.g., iOS `systemBlue`).
* `tailwind-merge` and `clsx` for conditional class composition — same as web pattern.
* Never use React Native's `StyleSheet.create` alongside NativeWind on the same component. Pick one approach per component.

### State Management
* Zustand for global state (auth session, user preferences, offline queue).
* TanStack Query for server state — auto-caches, handles background refresh, works offline with `networkMode: 'offlineFirst'`.
* Local component state (`useState`) for UI state that doesn't escape the component.
* Never use Context for frequently-updating state — causes wide re-renders. Use Zustand.
* Offline queue: persist pending mutations in Zustand (with MMKV storage) and replay on reconnect.

### Platform-Specific Code
* Platform-specific file extensions: `Component.ios.tsx` / `Component.android.tsx` for significantly different implementations.
* `Platform.OS === 'ios'` / `Platform.OS === 'android'` for minor inline differences only. Excessive inline checks are a code smell.
* Safe area: always use `useSafeAreaInsets()` or `SafeAreaView` from `react-native-safe-area-context`. Never hardcode status bar heights.
* Keyboard: `KeyboardAvoidingView` with `behavior="padding"` (iOS) / `behavior="height"` (Android).

### Native APIs (Expo SDK)
* Camera: `expo-camera`. Location: `expo-location`. Notifications: `expo-notifications`. File system: `expo-file-system`.
* Always request permissions before accessing native APIs. Handle `denied` and `undetermined` states explicitly — show explanatory UI before the permission prompt.
* Biometrics: `expo-local-authentication` for secure local authentication.
* Storage: `expo-secure-store` for sensitive data (tokens). `@react-native-async-storage/async-storage` or MMKV for non-sensitive persistent data.

### Performance Rules
* No `console.log` in production — remove or gate behind `__DEV__`.
* Avoid anonymous functions in JSX (`onPress={() => handler()}`) in list items — breaks `memo`. Extract to named handlers.
* `InteractionManager.runAfterInteractions` for expensive operations after navigation animations complete.
* `useFocusEffect` instead of `useEffect` for screen-level data refresh — runs only when screen is focused.

## Patterns / Examples

### FlashList with memoised item
```tsx
import { FlashList } from '@shopify/flash-list';
import { memo, useCallback } from 'react';

const ListingItem = memo(({ item, onPress }: { item: Listing; onPress: (id: string) => void }) => (
  <Pressable className="p-4 border-b border-border" onPress={() => onPress(item.id)}>
    <Text className="text-base font-semibold text-foreground">{item.title}</Text>
    <Text className="text-sm text-muted-foreground">{item.price}</Text>
  </Pressable>
));

export function ListingsList({ listings }: { listings: Listing[] }) {
  const router = useRouter();
  const handlePress = useCallback((id: string) => router.push(`/listings/${id}`), [router]);

  return (
    <FlashList
      data={listings}
      renderItem={({ item }) => <ListingItem item={item} onPress={handlePress} />}
      estimatedItemSize={72}
      keyExtractor={item => item.id}
    />
  );
}
```

### Swipe-to-action animation (Reanimated + Gesture Handler)
```tsx
import { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
import { GestureDetector, Gesture } from 'react-native-gesture-handler';

export function SwipeableListItem({ children, onDelete }: Props) {
  const translateX = useSharedValue(0);

  const panGesture = Gesture.Pan()
    .onUpdate(e => { translateX.value = Math.min(0, e.translationX); })
    .onEnd(e => {
      if (e.translationX < -80) { runOnJS(onDelete)(); }
      else { translateX.value = withSpring(0); }
    });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
  }));

  return (
    <GestureDetector gesture={panGesture}>
      <Animated.View style={animatedStyle}>{children}</Animated.View>
    </GestureDetector>
  );
}
```

### NativeWind + platform colour
```tsx
// src/global.css
@theme {
  --color-primary: platformColor(systemBlue, #3b82f6);
  --color-background: light-dark(#ffffff, #0a0a0a);
}

// Component
<View className="bg-background p-4">
  <Text className="text-primary font-bold">Hello</Text>
</View>
```

## When to Use
* Any vendor mobile app screen, component, or navigation flow
* List rendering, animations, gestures in the mobile app
* Expo SDK API usage (camera, location, notifications)
* NativeWind styling decisions
* Any mobile feature implementation or mobile story

## When NOT to Use
* Customer portal (Next.js — see `nextjs-patterns`)
* Admin SPA (React + Vite — see `react-admin-patterns`)
* Web-specific patterns (CSS Grid, DOM APIs, SSR)

---
> Source: [ajorobert/SpecPipeline](https://github.com/ajorobert/SpecPipeline) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。