# React Native Skia — 最佳实践和性能指南 > @shopify/react-native-skia 2.x / React Native >= 0.79 / React >= 19 / Reanimated v3+ ## 关键规则 1. **永远不要在 JSX 渲染中读取`.value` - 直接将共享值作为 props 传递：`` 而不是 ``。 2. **永远不要在渲染中创建 Skia 对象** — 对 Paint、Path、PictureRecorder、RuntimeEffect 使用 `useMemo`。 3. **始终在 `useDerivedValue` 回调中使用 `"worklet"` 指令标记工作集函数**。 4. **动画属性，而不是结构** - 保持组件树静态；仅对数字/颜色道具进行动画处理。 5. **使用 Atlas 处理 10 多个相似元素** — 单个绘制调用胜过 N 个单独的组件。 6. **重用 Paint 和 PictureRecorder 对象** — 每帧创建会导致 GC 压力和帧下降。 7. **对于 UI 动画更喜欢保留模式**（接近零的 FFI 成本）；仅对可变绘制命令计数（粒子、生成艺术、游戏）使用立即模式（图片 API）。 8. **对于简单的形状，使用 BlurMask 而不是 Blur** - 它更便宜。 9. **按最便宜的顺序排列滤镜** — MatrixColorFilter 在模糊之前。 10. **使用`useFont`/`useImage`在组件级别加载字体/图像** - 在渲染之前处理空加载状态。 ## 版本兼容性反应本机 Skia |反应本机 |反应 | iOS |安卓 ---|---|---|---|--- 2.x | >= 0.79 | >= 19 | >= 14 | API >= 21 1.12.4 | 1.12.4 <= 0.78 | <= 18 | >= 14 | API >= 21 视频支持需要 Android API 26+。 ## 安装 npm 安装@shopify/react-native-skia # 安装后下载预构建的 Skia 二进制文件 — 必须运行 # Bun：bun add --trust @shopify/react-native-skia # pnpm v10+：添加到 package.json 中的 pnpm.onlyBuiltDependencies iOS：`cd ios && pod install`。 Android ProGuard：添加 `-keep class com.shopify.reactnative.skia.** { *; }`。 ## 必需进口品导入{ 画布、圆形、矩形、圆角矩形、线条、路径、组、填充、文本、段落、图像、ImageSVG、线性渐变、径向渐变、扫描渐变、模糊、模糊蒙版、阴影、背景模糊、MatrixColorFilter、 RuntimeShader、FractalNoise、湍流、ImageShader、图集、图片、顶点、补丁、DiffRect、FitBox、盒子、 useFont、useImage、useSVG、useCanvasRef、 Skia、vec、矩形、rrect、drawAsImage、 usePathInterpolation、useRSXformBuffer、useRectBuffer、useClock、插值颜色，来自“@shopify/react-native-skia”；导入{ useSharedValue、useDerivedValue、withTiming、withSpring、 withRepeat、withSequence、withDelay、withDecay、cancelAnimation、来自“react-native-reanimated”； ## 核心模式——保留模式动画 const x = useSharedValue(0); const 比例 = useSharedValue(1); 使用效果（（）=> { x.value = withSpring(200); 比例.值 = withSpring(1.5); }, []); 返回（ <画布样式={{ flex: 1 }}> <组变换={[{translateX:x},{scale}]}> <圆 cx={0} cy={100} r={50} color="cyan" /> ）； ## 渲染模式选择场景 |模式|为什么 ---|---|--- 用户界面动画 |保留 | FFI 接近于零，显示列表已缓存图表和图表 |保留 |静态结构、动画道具粒子系统|立即 |可变绘制命令计数游戏 |立即 |完全控制每帧生成艺术|立即 |不可预测的场景变化混合|两者 |粒子图片 + UI 组 ## 性能快速参考最快（自由使用）：圆形、矩形、直线、组变换、MatrixColorFilter 快速（适度使用）：Path（简单）、BlurMask、LinearGradient 慢（谨慎使用）：BackdropBlur、RuntimeShader、DisplacementMap、Blur（大半径） **目标**：60fps = 16.67ms 预算，120fps = 8.33ms 预算。内存<100MB。 JS 线程 < 50%。 ## 修复视线中的反模式反模式|修复 ---|--- JSX 中的 `cx={x.value}` `cx={x}` — 直接传递共享值渲染主体中的`Skia.Paint()`包裹在 `useMemo(() => Skia.Paint(), [])` 渲染主体中的`Skia.Path.Make()`包裹在 `useMemo` 中 `{items.map(i => )}` 超过 10 个项目 |将“Atlas”与“useRSXformBuffer”结合使用 `<模糊模糊={0} />` |删除 — 无操作过滤器浪费循环动态组件列表每帧都会变化 |使用立即模式（图片 API） `useState` 驱动 Skia 动画 |使用“useSharedValue” `useDerivedValue` 中缺少 `"worklet"` |添加指令作为第一个语句字体/图像未进行空检查 |用 `if (!font) return null` 进行防护 `` 包裹大面积 |限制剪辑区域或使用“BlurMask” ## 代码审查行动当被要求审查/审核/检查 Skia 代码时： 1. **扫描**所有导入 `@shopify/react-native-skia` 的文件。 2. **根据关键规则和反模式表检查**。 3. 表中**报告**：`|文件 |线路|问题 |严重性 |修复|` 4. **严重性**：严重（崩溃/渲染损坏）、高（丢帧）、中（次优）、低（风格）。 5. **修复**所有问题（如果已确认），然后重新扫描以验证零违规。 ## 参考文件根据需要阅读这些内容以获取详细的 API 文档、示例和模式： * **[入门]()**：安装 (npm/yarn/Expo/Bun/pnpm)、平台设置 (iOS/Android/Web)、安装后脚本、Hello World、Canvas 组件、Skia 对象 API、项目结构、构建错误故障排除、包大小。 * **[Canvas& Rendering Modes]()**：保留模式（声明性组件、显示列表、接近零的 FFI）、即时模式（Picture API、PictureRecorder、直接绘制命令）、组合两种模式、离屏/无头渲染、画布快照、自定义渲染器、平台注意事项。 * **[形状和绘图]()**：所有形状组件（圆形、矩形、圆角矩形、椭圆形、直线、点、填充、带有 SVG 表示法的路径、Atlas/RSXform 精灵批处理、顶点、补丁、DiffRect）、组变换/混合模式/剪切、绘制组件、FitBox、带阴影的框、路径修剪动画。 * **[Animations]()** ：重新启动的 v3 集成（共享值作为直接道具）、动画类型（timing/spring/decay/repeat/sequence）、派生值、Skia 挂钩（usePathInterpolation、usePathValue、useClock、 useRectBuffer、useRSXformBuffer）、颜色动画（interpolateColors）、手势集成（平移/捏合/旋转/多点触控）、完整示例（脉冲按钮、旋转器、弹跳球）。 * **[着色器和渐变]()**：线性/径向/扫描/TwoPointConical 渐变、动画渐变、分形噪声/湍流、自定义 SkSL 运行时着色器（波形畸变、色差、辉光、极光、水波纹）、ShaderLib 函数、ImageShader 纹理、着色器组成、性能（半精度、缓存程序）。 * **[滤镜和效果]()**：图像滤镜（模糊、偏移、形态、位移贴图、阴影、运行时着色器）、遮罩滤镜（模糊遮罩样式：法线/实体/外部/内部）、颜色滤镜（MatrixColorFilter with灰度/棕褐色/反转/亮度/对比度矩阵、BlendColor、LumaColorFilter、Lerp）、路径效果（离散、虚线、角、Path1D、Path2D、Line2D、Sum）、BackdropBlur/BackdropFilter、遮罩（alpha/亮度）、磨砂玻璃/霓虹灯发光/复古照片示例。 * **[文本和字体]()**：文本组件（基线定位）、useFont 挂钩、系统字体、matchFont、段落生成器（富文本、样式、对齐方式）、TextPath（沿曲线的文本）、TextBlob、字形、字体指标/测量、动画文本（位置、字体大小）、选框/打字机/阴影示例。 * **[图像和媒体]()**：useImage hook (require/URL/bundle)、图像组件（适合模式、采样）、程序化图像创建（base64、原始像素、drawAsImage）、图像操作（调整大小、编码、读取像素）、AnimatedImage (GIF/WebP)、SVG（useSVG、ImageSVG、来自字符串）、视频播放（useVideo、控件）、Skottie/Lottie（动画、动态属性、插槽）、画布快照、图像效果。 * **[性能优化]()**：渲染管道(JS→UI→GPU)、60fps/120fps帧预算、保留与立即模式特征、动画性能(共享值、派生值、批处理、worklet)、组件结构优化(扁平树、组、静态图片）、内存管理（重用对象、处理图像、调整大小）、高性能渲染图集、过滤器成本层次结构、特定于平台的技巧（iOS Metal、Android OpenGL/androidWarmup、Web CanvasKit）、分析（useFrameCallback FPS 计数器、React DevTools、本机分析器）、常见陷阱清单。 * **[高级模式]()**：架构（组件组成、DrawingContext、原子/分子组件、自定义钩子、渲染道具）、真实示例（交互式条形图、带 Atlas 的粒子系统、带手势的绘图画布、进度环、波形可视化工具），设计系统集成（带有 Skia 颜色的主题提供程序）、测试（单元测试、视觉回归）、调试（视觉网格覆盖、性能监视器）、常见模式（骨架加载、波纹效果、五彩纸屑）。

斯基亚

包含技能