TheaterJS 从 v1 迁移到 v2 完全指南

TheaterJS 从 v1 迁移到 v2 完全指南

TheaterJS Typing animation mimicking human behavior. 项目地址: https://gitcode.com/gh_mirrors/th/TheaterJS

前言

TheaterJS 是一个轻量级的 JavaScript 库，专门用于创建类似打字机效果的文本动画。在 v2 版本中，该项目进行了重大重构，虽然核心概念保持不变，但 API 设计更加清晰和现代化。本文将详细介绍如何从 v1 版本平滑迁移到 v2 版本。

主要变更概览

v2 版本主要进行了以下改进：

1. 更直观的 API 命名
2. 更简洁的演员(Actor)定义方式
3. 改进的回调处理机制
4. 内置的重放功能
5. 更清晰的场景(Scene)管理

实例化方式变更

v1 版本使用构造函数方式：

var theater = new TheaterJS()

v2 版本改为工厂函数：

var theater = theaterJS()

这一变更使 API 更加符合现代 JavaScript 的实践。

演员(Actor)定义变更

在 v1 中，定义演员需要指定多个参数：

theater.describe('vader', 0.8, '#vader')

v2 版本简化为：

theater.addActor('vader')

v2 版本会自动将演员名称作为选择器（即 #vader），打字速度等参数可以通过配置选项单独设置。

场景(Scene)管理变更

v1 使用 write 方法添加场景：

theater.write('vader:Luke...')

v2 改为更语义化的 addScene：

theater.addScene('vader:Luke...')

回调处理改进

v1 版本的回调处理较为复杂：

theater.write(function () { this.play(true) })

v2 版本提供了更优雅的解决方案：

theater.addScene(theater.replay)

对于自定义回调，v2 提供了 done 函数来处理异步操作：

theater.addScene(function (done) {
  // 异步操作
  setTimeout(done, 1000)
})

事件监听变更

v1 版本监听打字开始/结束事件：

theater.on('say:start, erase:start', function () { ... })

v2 版本改为更准确的命名：

theater.on('type:start, erase:start', function () { ... })

同时，访问当前演员的方式也从：

var currentActor = theater.current

变为：

var currentActor = theater.getCurrentActor()

完整迁移示例

下面是一个完整的从 v1 迁移到 v2 的示例：

v1 版本代码：

var theater = new TheaterJS()

theater
  .on('say:start, erase:start', function () {
    var currentActor = theater.current
    currentActor.voice.classList.add('blinking-caret')
  })
  .describe('vader', 0.8, '#vader')
  .write('vader:Luke...')
  .write(function () { this.play(true) })

v2 版本代码：

var theater = theaterJS()

theater
  .on('type:start, erase:start', function () {
    var currentActor = theater.getCurrentActor()
    currentActor.$element.classList.add('blinking-caret')
  })
  .addActor('vader')
  .addScene('vader:Luke...')
  .addScene(theater.replay)

迁移建议

1. 首先替换实例化方式
2. 将所有 describe 改为 addActor
3. 将所有 write 改为 addScene
4. 更新事件监听器中的事件名称
5. 重构回调函数使用新的 done 机制
6. 使用内置的 replay 方法替代手动重放

结语

TheaterJS v2 通过更清晰的 API 设计和更强大的功能，为创建文本动画提供了更好的开发体验。虽然迁移需要一些工作，但改进后的代码将更易于维护和理解。希望本指南能帮助你顺利完成从 v1 到 v2 的迁移。

TheaterJS Typing animation mimicking human behavior. 项目地址: https://gitcode.com/gh_mirrors/th/TheaterJS