Theatre.js 是一个面向 Web 的动态设计编辑器与动画库，核心特点是将可视化时间线编辑器（Studio）与代码中的程序化控制结合起来。它可用于实现动效设计、时间线动画、可视化动画编辑器、Three.js/R3F 场景动画以及关键帧动画。
一、用途与定位 资料将其描述为“Motion design editor and animation library for the web”，即同时提供可视化编辑与代码驱动的动画库。动画数据以项目为单位组织，可通过 Studio 编辑并导出为 JSON 状态，供生产环境使用。
二、核心概念
- Project（项目）：所有动画数据的容器，对应导出的 JSON 状态。
- Sheet（表单）：一个场景或组件，包含对象与一个序列。
- Object（对象）：带有类型化属性的可动画实体。
- Sequence（序列）：包含关键帧的时间线，控制播放。
- Props（属性）：类型化值，如 number、compound、rgba 等。
三、安装与集成 核心与 Studio（开发环境）： npm install @theatre/core@0.7 @theatre/studio@0.7 React Three Fiber 集成： npm install @theatre/r3f@0.7 React 工具： npm install @theatre/react 简化控件 Theatric： npm install theatric
四、基本使用方式 初始化 Studio（仅开发环境）： import * as core from '@theatre/core' import studio from '@theatre/studio' if (import.meta.env.DEV) { studio.initialize() } 创建项目、表单与对象，读取值并监听变化： const project = core.getProject('My Project') const sheet = project.sheet('Main') const obj = sheet.object('Box', { position: { x: 0, y: 0 }, opacity: 1 }) console.log(obj.value.position.x) obj.onValuesChange((values) => { /* 应用到 DOM */ }) sheet.sequence.play({ iterationCount: Infinity }) 序列播放支持选项，如 iterationCount、range、rate、direction，也可 pause、设置 position 跳转及 await 播放完成。
五、框架集成 @theatre/react 提供 useVal、usePrism 等 hooks。@theatre/r3f 提供 editable 组件与 SheetProvider，配合 studio.extend(extension) 可在 Studio 中获得三维控制；可编辑组件需要 theatreKey。Theatric 提供更简单的 useControls 与 types 控件写法。
六、常见模式与注意事项 资料列出多种常见模式：为 DOM 元素绑定 x、y、rotation、scale、opacity 等属性并监听变化；通过 sequence.play 的参数控制循环、区间、速率和方向；在 R3F 场景中用 e.mesh、e.pointLight 等可编辑元素配合 theatreKey。 需避免的关键错误包括：生产环境误引入 Studio（应只在开发环境初始化）；生产环境缺少导出的状态（应 getProject('Name', { state }) 加载 state.json）；对象 key 冲突（同一 sheet 内同名 object 会共享/覆盖）；R3F 缺少 extension；可编辑元素忘记 theatreKey。
七、适用场景与限制 适用于网页动效、时间线关键帧动画、可视化编辑与三维场景动画开发。资料未提供价格、平台支持范围、性能指标或与其他动画库的对比信息，这些内容暂未提供。