react-native-skia

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Native Skia v2

When to use this skill

何时使用本技能

Use this skill for React Native or Expo work that depends on

@shopify/react-native-skia

, especially when the user wants a custom animated element, canvas-driven interaction, shader effect, exported graphic, or performance-sensitive motion system.

Reach for it when the request mentions:

Skia, Canvas, shaders, RuntimeEffect, RuntimeShader, paths, pictures, atlas, Paragraph, snapshots, Skottie, video, CanvasKit, or headless rendering
visual language such as glass, glow, blob, liquid, particle, shimmer, parallax, neon, morph, premium loader, hero background, or "make this feel expensive"
frame-rate or interaction concerns such as 60 fps, 120 fps, GPU-friendly, stutter, jank, gesture-driven, or "keep this off the JS thread"

Do not use this skill for ordinary layout, forms, lists, settings screens, or standard view animation unless the user clearly wants a Skia or canvas-based solution.

当React Native或Expo开发工作依赖

@shopify/react-native-skia

时，尤其是用户需要自定义动画元素、画布驱动交互、着色器效果、导出图形或对性能敏感的动效系统时，可使用本技能。

当请求中提及以下内容时，可采用本技能：

Skia、Canvas、着色器、RuntimeEffect、RuntimeShader、路径、图片、图集、Paragraph、快照、Skottie、视频、CanvasKit或无头渲染
视觉风格相关描述，如毛玻璃、发光、Blob、液态、粒子、闪光、视差、霓虹、变形、高端加载器、主背景或“让这个看起来更高级”
帧率或交互相关需求，如60 fps、120 fps、GPU友好、卡顿、手势驱动或“让这部分脱离JS线程”

请勿将本技能用于普通布局、表单、列表、设置页面或标准视图动画，除非用户明确需要基于Skia或画布的解决方案。

Default workflow

默认工作流程

Audit the repo first in existing projects.
- Run:
  bash
```
python3 scripts/audit_skia_repo.py --root . --format markdown
```
- Read the findings before editing code.
Lock the real constraints up front.
- Platforms: iOS / Android / Web
- Desired feel: ambient, tactile, energetic, technical, playful, premium
- Interaction model: passive loop, tap, drag, pinch, scrub, scroll-linked
- Performance expectations: decorative only, hero element, many instances, always-on animation
- Asset needs: custom fonts, images, video, Lottie JSON, captured React Native views
- Accessibility: reduced motion, readable text, tappable overlays
If the aesthetic is underspecified, propose 2-3 directions before coding.
- Give distinct options with trade-offs such as:
  - Retained polish: gradients, blur, layered shapes, safest and simplest
  - Shader-led: most distinctive, best for backgrounds and procedural effects
  - High-instance field: Atlas or Picture driven, best for particles / sprites / trails
- Then implement the best fit.
Choose the simplest architecture that satisfies the effect.
- Use
```
references/decision-tree.md
```
  .
- Default to retained mode.
- Escalate to
```
Picture
```
  ,
```
Atlas
```
  , textures, shaders, or headless only when the workload actually needs it.
Implement a complete patch, not fragments.
- Update imports, assets, bootstrap code, and fallbacks together.
- Include null guards for async fonts, images, and video frames.
- If web matters, include CanvasKit bootstrapping as part of the change.
Review both polish and performance before finishing.
- Run the review checklist in
```
references/performance-playbook.md
```
  and
```
references/motion-design-playbook.md
```
  .
- Mention platform caveats, reduced-motion behaviour, and testing steps.

现有项目中先审核代码库
- 运行：
  bash
```
python3 scripts/audit_skia_repo.py --root . --format markdown
```
- 在编辑代码前先查看审核结果。
提前明确实际约束条件
- 平台：iOS / Android / Web
- 预期风格：氛围感、触感、活力感、科技感、趣味性、高端感
- 交互模式：被动循环、点击、拖拽、捏合、滑动、滚动联动
- 性能预期：仅装饰用、核心视觉元素、多实例、持续动画
- 资源需求：自定义字体、图片、视频、Lottie JSON、捕获的React Native视图
- 无障碍适配：简化动效、可读文本、可点击覆盖层
若美学需求不明确，编码前先提出2-3个方向
- 提供带有取舍的不同选项，例如：
  - 保留精致感：渐变、模糊、分层形状，最安全简单
  - 着色器主导：辨识度最高，最适合背景和程序化效果
  - 多实例场：基于Atlas或Picture，最适合粒子/精灵/轨迹
- 然后实现最契合的方案。
选择能满足效果的最简架构
- 参考
```
references/decision-tree.md
```
- 默认使用保留模式
- 仅当工作负载确实需要时，才升级为
```
Picture
```
  、
```
Atlas
```
  、纹理、着色器或无头渲染
实现完整的补丁，而非片段
- 同时更新导入、资源、启动代码和降级方案
- 为异步字体、图片和视频帧添加空值防护
- 若涉及Web端，需将CanvasKit启动配置作为变更的一部分
完成前同时检查精致度和性能
- 运行
```
references/performance-playbook.md
```
  和
```
references/motion-design-playbook.md
```
  中的审核清单
- 提及平台注意事项、简化动效的表现和测试步骤

Hard rules for expert Skia work

Skia专业开发的硬性规则

Keep animation state on the UI thread with Reanimated shared or derived values whenever practical.
Pass shared or derived values directly to Skia props. Do not wrap Skia nodes with
```
createAnimatedComponent
```
or
```
useAnimatedProps
```
just to animate them.
Avoid reading shared values on the JS thread during normal rendering logic.
Prefer animating
```
transform
```
, opacity, shader uniforms, and other non-layout properties over layout-affecting view changes.
Memoise gesture objects and frame callbacks in component code.
Use retained mode by default. Use
```
Picture
```
when the number of draw commands changes frame to frame. Use
```
Atlas
```
when many instances share the same texture. Use texture hooks when a pre-rendered result is reused often.
Keep business data, theme context, and layout decisions outside the canvas tree unless you explicitly re-inject context.
Use
```
Paragraph
```
for wrapped or multi-style text. Load fonts explicitly when custom families matter.
Treat
```
Paragraph
```
,
```
Picture
```
,
```
Skottie
```
, and SVG as special cases for effects: use
```
layer
```
when you need blur, filters, or other paint effects on them.
Treat
```
useImage()
```
returning
```
null
```
as normal. Never assume the image is synchronously ready.
When capturing React Native content with
```
makeImageFromView
```
, keep
```
collapsable={false}
```
on the captured root view.
When using
```
RuntimeShader
```
as an image filter, account for pixel density and supersample if the result looks soft.
On web, gate rendering until CanvasKit has loaded. In Expo web, rerun
```
setup-skia-web
```
after Skia upgrades unless CanvasKit comes from a CDN.
Only use
```
androidWarmup
```
for static, fully opaque canvases. Avoid it for animated or translucent scenes.
Respect reduced motion. Offer a static or lighter fallback when the effect is decorative.

只要可行，就用Reanimated共享值或派生值将动画状态保存在UI线程
将共享值或派生值直接传递给Skia属性。不要为了动画而用
```
createAnimatedComponent
```
或
```
useAnimatedProps
```
包裹Skia节点
在正常渲染逻辑中，避免在JS线程读取共享值
优先动画
```
transform
```
、透明度、着色器 uniforms 和其他非布局属性，而非影响布局的视图变更
在组件代码中对手势对象和帧回调进行记忆化处理
默认使用保留模式。当每一帧的绘制命令数量变化时，使用
```
Picture
```
。当多个实例共享同一纹理时，使用
```
Atlas
```
。当预渲染结果经常被重用时，使用纹理钩子
除非明确重新注入上下文，否则将业务数据、主题上下文和布局决策放在画布树之外
对于换行或多样式文本，使用
```
Paragraph
```
。当自定义字体很重要时，显式加载字体
将
```
Paragraph
```
、
```
Picture
```
、
```
Skottie
```
和SVG视为特殊效果场景：当需要对它们应用模糊、滤镜或其他绘制效果时，使用
```
layer
```
将
```
useImage()
```
返回
```
null
```
视为正常情况。永远不要假设图片已同步加载完成
使用
```
makeImageFromView
```
捕获React Native内容时，在捕获的根视图上保持
```
collapsable={false}
```
当使用
```
RuntimeShader
```
作为图像滤镜时，考虑像素密度，如果结果看起来模糊则进行超采样
在Web端，要等CanvasKit加载完成后再开始渲染。在Expo Web中，除非CanvasKit来自CDN，否则Skia升级后要重新运行
```
setup-skia-web
```
仅对静态、完全不透明的画布使用
```
androidWarmup
```
。避免在动画或半透明场景中使用
遵循简化动效原则。当效果仅为装饰性时，提供静态或更轻量化的降级方案

Motion-design heuristics

动效设计启发规则

Use these rules unless the user asks for a very specific visual style:

Anchor each scene with one stable focal layer. Let one hero motion lead, one secondary motion support, and keep the rest quiet.
Put soft, large, low-frequency motion in the background and small, sharp highlights in the foreground.
Phase-offset loops so everything does not crest at the same time.
Keep blur and transparency doing compositional work, not hiding weak geometry.
Place the brightest contrast near the point of action or label, not the canvas edge.
Clamp gesture-driven motion and spring back to rest states.
Prefer visuals that can degrade gracefully to a static frame.

See

references/motion-design-playbook.md

for deeper guidance and pattern recipes.

除非用户要求非常特定的视觉风格，否则遵循以下规则：

用一个稳定的焦点层锚定每个场景。让一个核心动效主导，一个辅助动效配合，其余保持简洁
将柔和、大尺寸、低频次的动效放在背景，小尺寸、鲜明的高亮效果放在前景
循环动效设置相位偏移，避免所有元素同时达到峰值
让模糊和透明度起到构图作用，而非掩盖劣质几何图形
将最鲜明的对比度放在交互点或标签附近，而非画布边缘
限制手势驱动的动效，并回弹到静止状态
优先选择可以优雅降级为静态帧的视觉效果

如需更深入的指导和模式参考，请查看

references/motion-design-playbook.md

Deliverable expectations

交付物要求

When you produce code with this skill:

provide a full runnable TSX component or a coherent repository patch
explain why the chosen primitives and rendering mode fit the task
call out the likely performance profile and any trade-offs
mention web/native setup needs if relevant
include reduced-motion behaviour for decorative or always-on motion
when the request is broad, provide 2-3 concept options first and then implement the best one

使用本技能生成代码时：

提供完整可运行的TSX组件或连贯的代码库补丁
解释为何所选的原语和渲染模式适合该任务
说明预期的性能表现和任何取舍
若相关，提及Web/原生端的配置需求
为装饰性或持续动效添加简化动效的适配逻辑
当请求范围较广时，先提供2-3个概念选项，再实现最佳方案

Bundled resources

内置资源

Official doc distillation:
```
references/official-doc-notes.md
```
Architecture and primitive selection:
```
references/decision-tree.md
```
Motion direction and polish heuristics:
```
references/motion-design-playbook.md
```
Performance rules and anti-patterns:
```
references/performance-playbook.md
```
Symptom-to-fix guide:
```
references/debugging-matrix.md
```
Pattern cookbook:
```
references/animated-element-recipes.md
```
Eval workflow notes:
```
references/eval-strategy.md
```
Ready-to-adapt TSX templates:
```
assets/templates/
```
Repo audit script:
```
scripts/audit_skia_repo.py
```
Trigger and output-quality evals:
```
evals/
```

官方文档提炼：
```
references/official-doc-notes.md
```
架构与原语选择：
```
references/decision-tree.md
```
动效方向与精致度启发规则：
```
references/motion-design-playbook.md
```
性能规则与反模式：
```
references/performance-playbook.md
```
症状-修复指南：
```
references/debugging-matrix.md
```
模式手册：
```
references/animated-element-recipes.md
```
评估流程说明：
```
references/eval-strategy.md
```
可直接适配的TSX模板：
```
assets/templates/
```
代码库审核脚本：
```
scripts/audit_skia_repo.py
```
触发与输出质量评估：
```
evals/
```

Quick path by task

按任务分类的快速路径

New animated decorative element

新的装饰性动画元素

Read
```
references/animated-element-recipes.md
```
.
Pick a concept lane from
```
references/motion-design-playbook.md
```
.
Start from the closest file in
```
assets/templates/
```
.
Keep the structure retained-mode unless the workload clearly needs
```
Picture
```
,
```
Atlas
```
, or a shader.

阅读
```
references/animated-element-recipes.md
```
从
```
references/motion-design-playbook.md
```
中选择一个风格方向
从
```
assets/templates/
```
中选择最接近的文件开始
除非工作负载明确需要
```
Picture
```
、
```
Atlas
```
或着色器，否则保持保留模式结构

Gesture-driven surface

手势驱动界面

Confirm
```
react-native-gesture-handler
```
and Reanimated are correctly installed.
Prefer shared values for transforms and memoised gestures.
If per-element hit-testing is needed, use overlay views that mirror the canvas transforms.

确认
```
react-native-gesture-handler
```
和Reanimated已正确安装
优先使用共享值进行变换，对手势进行记忆化处理
如果需要逐元素命中测试，使用与画布变换镜像的覆盖视图

Performance tuning

性能调优

Run
```
scripts/audit_skia_repo.py
```
.
Read
```
references/performance-playbook.md
```
.
Decide whether the real problem is JS-thread churn, too many draw nodes, wrong render mode, missing web bootstrap, or expensive filters.
Only escalate complexity when there is clear evidence.

运行
```
scripts/audit_skia_repo.py
```
阅读
```
references/performance-playbook.md
```
判断实际问题是JS线程负载过高、绘制节点过多、渲染模式错误、Web端启动配置缺失还是滤镜开销过大
只有当有明确证据时，才提升复杂度

Text or badge UI

文本或徽章UI

Prefer
```
Paragraph
```
.
Load fonts explicitly if typography matters.
Keep text crisp; do not bury active text inside broad blur/filter layers.

优先使用
```
Paragraph
```
如果排版很重要，显式加载字体
保持文本清晰；不要将可交互文本放在大面积模糊/滤镜层内

Web blank screen or setup problems

Web端空白屏幕或配置问题

Check web bootstrap and CanvasKit loading first.
Check
```
setup-skia-web
```
, Babel/worklets config, and version compatibility before rewriting components.

首先检查Web端启动配置和CanvasKit加载情况
在重写组件前，先检查
```
setup-skia-web
```
、Babel/worklets配置和版本兼容性

Sprite or particle fields

精灵或粒子场

Use retained mode only if the structure is fixed and modest.
Use
```
Atlas
```
for many instances of the same texture.
Use
```
Picture
```
for dynamic command lists such as trails, generative art, or changing entity counts.
Use texture hooks if pre-rendering saves repeated work.

仅当结构固定且规模适中时，使用保留模式
对于同一纹理的多实例，使用
```
Atlas
```
对于动态命令列表（如轨迹、生成艺术或实体数量变化），使用
```
Picture
```
如果预渲染能节省重复工作，使用纹理钩子