diff --git a/README.md b/README.md index 79bac3a..ca9fa40 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ JavaScript (TypeScript) tweening engine for easy animations, incorporating optim [![NPM Downloads][downloads-image]][downloads-url] [![Build and Tests][ci-image]][ci-url] +More languages: [English](./README.md), [简体中文](./README_zh-CN.md) + --- ```html diff --git a/README_zh-CN.md b/README_zh-CN.md index 1b322eb..5d1cd07 100644 --- a/README_zh-CN.md +++ b/README_zh-CN.md @@ -1,213 +1,187 @@ # tween.js -tween.js 是用于简单动画的 JavaScript 补间引擎，结合了优化的 Robert Penner 方程。 +用于简单动画的 JavaScript (TypeScript) 补间引擎，结合优化的 Robert Penner 方程式。 [![NPM Version][npm-image]][npm-url] -[![NPM Downloads][downloads-image]][downloads-url] -[![Travis tests][travis-image]][travis-url] -[![Flattr this][flattr-image]][flattr-url] [![CDNJS][cdnjs-image]][cdnjs-url] +[![NPM Downloads][downloads-image]][downloads-url] +[![Build and Tests][ci-image]][ci-url] -```javascript -var box = document.createElement('div') -box.style.setProperty('background-color', '#008800') -box.style.setProperty('width', '100px') -box.style.setProperty('height', '100px') -document.body.appendChild(box) +更多语言: [English](./README.md), [简体中文](./README_zh-CN.md) -// 设置循环动画 -function animate(time) { +--- + +```html + + +
+ + + + ``` -[在线代码测试](https://codepen.io/mikebolt/pen/zzzvZg) +[在 CodePen 上试试这个例子](https://codepen.io/trusktr/pen/KKGaBVz?editors=1000) ## 安装 -下载 [library](https://raw.githubusercontent.com/tweenjs/tween.js/master/src/Tween.js) 并将它引入至你的代码中: +## 从 CDN 安装 + +从上例中的内容分发网络 (CDN) 安装。 + +cdnjs: ```html - + ``` -您也可以在代码中引用 CDN 托管的版本，这要感谢 cdnjs 。例如: +或者 unpkg.com: ```html - + ``` -See [tween.js](https://cdnjs.com/libraries/tween.js/) for more versions. +请注意，unpkg.com 支持 URL 中的 semver 版本，其中 URL 中的 `^` 告诉 unpkg 为你提供最新版本 20.x.x。 -查看更多 [tween.js](https://cdnjs.com/libraries/tween.js/) 版本. +## 使用 script 标签构建并包含在你的项目中 -### 更多高级用户想要的... +目前需要 npm 来构建项目。 -#### 使用 `npm` +```bash +git clone https://github.com/tweenjs/tween.js +cd tween.js +npm install +npm run build +``` + +这将在 `dist` 目录中创建一些构建。 目前有两种不同的库版本： + +- UMD : `tween.umd.js` +- ES6 Module : `tween.es.js` + +你现在可以将 tween.umd.js 复制到你的项目中，然后将其包含在一个 script 标签，它将 TWEEN 添加到全局范围， + +```html + +``` + +或将 TWEEN 作为 JavaScript 模块导入， + +```html + +``` + +其中 `path/to` 替换为你放置文件的位置。 + +## 使用 `npm install` 和 `import` 从 `node_modules` 中添加 + +你可以将 tween.js 添加为 npm 依赖项： ```bash npm install @tweenjs/tween.js ``` -然后用标准的 node.js `require` 包含 Tween.js 模块: +### 使用构建工具 + +如果你使用 [Node.js](https://nodejs.org/)、[Parcel](https://parceljs.org/)、[Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/)、[Vite](https://vitejs.dev/) 或者其他的构建工具，那么你现在可以使用以下方式来导入 tween.js： ```javascript -var TWEEN = require('@tweenjs/tween.js') +import * as TWEEN from '@tweenjs/tween.js' ``` -您可以像所有其他示例一样使用 Tween.js，例如: +### 没有构建工具 -```javascript -var t = new TWEEN.Tween(/* etc */) -t.start() -``` - -你将需要使用诸如`browserify`之类的工具将使用此风格的代码转换为可以在浏览器中运行的代码(浏览器无法识别 `require`) - -#### Use `bower` - -```bash -bower install @tweenjs/tweenjs --save -``` - -或者安装特定的 tag.他们是 git tags,如果你已经在本地克隆仓库，你可以在命令行中运行`git tag`查看 tag 列表,或者你可以查看下 [tween.js tags page](https://github.com/tweenjs/tween.js/tags) 列表.例如,安装 `v16.3.0`: - -```bash -bower install @tweenjs/tweenjs#v16.3.0 -``` - -然后引入库源码: +如果你将 `node_modules` 作为网站的一部分提供服务，则可以使用 `importmap` script 标签从 `node_modules` 导入。 首先，假设 `node_modules` 位于你网站的根目录，你可以编写一个导入映射： ```html - + ``` -## Features +现在，在任何 module script 中，你都可以通过包名导入它： -- 只做一件事且仅只做一件事: 补间特性 -- 不关注 CSS 单位 (e.g. appending `px`) -- 不插入颜色 -- 缓和功能可以在 Tween 之外重用 -- 也可以使用自定义缓动功能 +```javascript +import * as TWEEN from '@tweenjs/tween.js' +``` -## Documentation +# 特性 -- [使用指南](./docs/user_guide_zh-CN.md) -- [贡献者指南](./docs/contributor_guide_zh-CN.md) -- [教程](http://learningthreejs.com/blog/2011/08/17/tweenjs-for-smooth-animation/) using tween.js with three.js -- 其他: [libtween](https://github.com/jsm174/libtween), [jsm174](https://github.com/jsm174) 写的一个 C 语言版本的 tween.js. -- 其他: [es6-tween](https://github.com/tweenjs/es6-tween), [dalisoft](https://github.com/dalisoft) 写的一个 ES6/Harmony 版本的 tween.js. -- [理解 tween.js](https://mikebolt.me/article/understanding-tweenjs.html) +- 做一件事并且只做一件事：补间属性 +- 不处理 CSS 单位（例如附加 `px`） +- 不插值颜色 +- 缓动函数可在 Tween 之外重复使用 +- 也可以使用自定义缓动函数 -## 示例 +# 文档 - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
- - Custom functions + + hello world - Custom functions
- (source) + hello world
+ (source) 		- - Stop all chained tweens + + Bars - Stop all chained tweens
- (source) + Bars
+ (source)
- - Yoyo - - - Yoyo
- (source) - 		- - Relative values - - - Relative values
- (source) -
- - Repeat + + Black and red - Repeat
- (source) - 		- - Dynamic to - - - Dynamic to
- (source) -
- - Array interpolation - - - Array interpolation
- (source) - 		- - Video and time - - - Video and time
- (source) -
- - Simplest possible example - - - Simplest possible example
- (source) + Black and red
+ (source) 		- Graphs + Graphs @@ -217,81 +191,192 @@ bower install @tweenjs/tweenjs#v16.3.0
- - Black and red + + Simplest possible example - Black and red
- (source) + Simplest possible example
+ (source) 		- - Bars + + Video and time - Bars
- (source) + Video and time
+ (source)
- - hello world + + Array interpolation - hello world
- (source) + Array interpolation
+ (source) + 		+ + Dynamic to, object + + + Dynamic to, object
+ (source) +
+ + Dynamic to, interpolation array + + + Dynamic to, interpolation array
+ (source) + 		+ + Dynamic to, large interpolation array + + + Dynamic to, large interpolation array
+ (source) +
+ + Repeat + + + Repeat
+ (source) + 		+ + Relative values + + + Relative values
+ (source) +
+ + Yoyo + + + Yoyo
+ (source) + 		+ + Stop all chained tweens + + + Stop all chained tweens
+ (source) +
+ + Custom functions + + + Custom functions
+ (source) + 		+ + Relative start time + + + Relative start time
+ (source) +
+ + Pause tween + + + Pause tween
+ (source) + 		+ + Complex properties + + + Complex properties
+ (source) +
+ + Animate an array of values + + + Animate an array of values
+ (source)
-## Tests +# 测试 -你首先需要安装`npm`--基于 node.js,所以首先安装它.然后,进入到`tween.js`的目录下并运行: +你需要先安装 `npm`——它随 node.js 一起提供，因此请先安装它。 然后，cd 到 `tween.js` 的（或你克隆 repo 的任何地方）目录并运行： ```bash npm install ``` -如果是第一次运行测试,则为运行测试安装额外的依赖,然后运行 +运行测试： ```bash npm test ``` -每次你想运行测试. +如果你想添加任何功能或更改现有功能，你 _必须_ 运行测试以确保你没有破坏任何其他功能。任何拉取请求 (PR) 都需要在 `src/tests.ts` 中更新通过功能更改测试（或通过新功能或修复的新测试）才能接受 PR。 有关更多信息，请参阅 [贡献](CONTRIBUTING.md)。 -如果你想添加任何功能或改变现有的功能，你*必须*运行测试，以确保你没有影响别的东西.如果你发一个 pull request（PR）添加新的东西,它没有测试,或测试不通过,这个 PR 将不被接受.更详细的请看 [contributing](CONTRIBUTING.md). +# 使用 tween.js 的项目 -## People - -维护者: [mikebolt](https://github.com/mikebolt), [sole](https://github.com/sole). - -[所有贡献者](http://github.com/tweenjs/tween.js/contributors). - -## 使用 tween.js 的项目 - -[![A-Frame VR](http://tweenjs.github.io/tween.js/assets/projects/10_aframe.png)](https://aframe.io) -[![MOMA Inventing Abstraction 1910-1925](http://tweenjs.github.io/tween.js/assets/projects/09_moma.png)](http://www.moma.org/interactives/exhibitions/2012/inventingabstraction/) -[![Web Lab](http://tweenjs.github.io/tween.js/assets/projects/08_web_lab.png)](http://www.chromeweblab.com/) -[![MACCHINA I](http://tweenjs.github.io/tween.js/assets/projects/07_macchina.png)](http://5013.es/toys/macchina) -[![Minesweeper 3D](http://tweenjs.github.io/tween.js/assets/projects/06_minesweeper3d.png)](http://egraether.com/mine3d/) -[![ROME](http://tweenjs.github.io/tween.js/assets/projects/05_rome.png)](http://ro.me) -[![WebGL Globe](http://tweenjs.github.io/tween.js/assets/projects/04_webgl_globe.png)](http://data-arts.appspot.com/globe) -[![Androidify](http://tweenjs.github.io/tween.js/assets/projects/03_androidify.png)](http://www.androidify.com/) -[![The Wilderness Downtown](http://tweenjs.github.io/tween.js/assets/projects/01_wilderness.png)](http://thewildernessdowntown.com/) -[![Linechart](http://tweenjs.github.io/tween.js/assets/projects/00_linechart.png)](http://dejavis.org/linechart) +[Lume](https://lume.io) +[![A-Frame VR](https://tweenjs.github.io/tween.js/assets/projects/10_aframe.png)](https://aframe.io) +[![MOMA Inventing Abstraction 1910-1925](https://tweenjs.github.io/tween.js/assets/projects/09_moma.png)](http://www.moma.org/interactives/exhibitions/2012/inventingabstraction/) +[![Web Lab](https://tweenjs.github.io/tween.js/assets/projects/08_web_lab.png)](http://www.chromeweblab.com/) +[![MACCHINA I](https://tweenjs.github.io/tween.js/assets/projects/07_macchina.png)](http://5013.es/toys/macchina) +[![Minesweeper 3D](https://tweenjs.github.io/tween.js/assets/projects/06_minesweeper3d.png)](http://egraether.com/mine3d/) +[![ROME](https://tweenjs.github.io/tween.js/assets/projects/05_rome.png)](http://ro.me) +[![WebGL Globe](https://tweenjs.github.io/tween.js/assets/projects/04_webgl_globe.png)](http://data-arts.appspot.com/globe) +[![Androidify](https://tweenjs.github.io/tween.js/assets/projects/03_androidify.png)](http://www.androidify.com/) +[![The Wilderness Downtown](https://tweenjs.github.io/tween.js/assets/projects/01_wilderness.png)](http://thewildernessdowntown.com/) +[![Linechart](https://tweenjs.github.io/tween.js/assets/projects/00_linechart.png)](http://dejavis.org/linechart) [npm-image]: https://img.shields.io/npm/v/@tweenjs/tween.js.svg [npm-url]: https://npmjs.org/package/@tweenjs/tween.js [downloads-image]: https://img.shields.io/npm/dm/@tweenjs/tween.js.svg [downloads-url]: https://npmjs.org/package/@tweenjs/tween.js -[travis-image]: https://travis-ci.org/tweenjs/tween.js.svg?branch=master -[travis-url]: https://travis-ci.org/tweenjs/tween.js -[flattr-image]: https://api.flattr.com/button/flattr-badge-large.png -[flattr-url]: https://flattr.com/thing/45014/tween-js +[ci-image]: https://github.com/tweenjs/tween.js/workflows/build%20and%20tests/badge.svg?branch=master +[ci-url]: https://github.com/tweenjs/tween.js/actions [cdnjs-image]: https://img.shields.io/cdnjs/v/tween.js.svg [cdnjs-url]: https://cdnjs.com/libraries/tween.js diff --git a/docs/contributor_guide.md b/docs/contributor_guide.md index 23a6a2d..6eec404 100644 --- a/docs/contributor_guide.md +++ b/docs/contributor_guide.md @@ -1,5 +1,7 @@ # tween.js contributor guide +More languages: [English](./contributor_guide.md), [简体中文](./contributor_guide_zh-CN.md) + This guide is for people who want to _contribute_ to the library or are curious to learn what's behind the scenes: how is it tested? what do we automate? how do we do releases? etc. If you are looking for documentation on _how to use_ the library, the [user guide](./user_guide.md) is for you. diff --git a/docs/contributor_guide_zh-CN.md b/docs/contributor_guide_zh-CN.md index 7ab6104..e4b4a80 100644 --- a/docs/contributor_guide_zh-CN.md +++ b/docs/contributor_guide_zh-CN.md @@ -1,43 +1,49 @@ # tween.js 贡献者指南 -本指南适用于想要向库贡献的人,或者想了解背后的内容:如何进行测试?我们自动化什么?我们如何做发布?等等. +更多语言: [English](./contributor_guide.md), [简体中文](./contributor_guide_zh-CN.md) -如果您正在查找*如何使用*库的文档，[用户指南](./ user_guide_zh-CN.md)是适合你的。 +本指南适用于想要向库贡献的人，或者想了解背后的内容：如何进行测试？我们自动化什么？我们如何做发布？等等。 -**这个文档是一个正在进行的工作.更多内容将分阶段添加.如果你有问题,你想看到回答,请在 [as comments on this issue](https://github.com/tweenjs/tween.js/issues/323) 中提出.谢谢!** +如果你正在查找*如何使用*库的文档，[用户指南](./user_guide_zh-CN.md) 是适合你的。 + +**NOTE: 这个文档是一个正在进行的工作。更多内容将分阶段添加。如果你有问题，你想看到回答，请在 [as comments on this issue](https://github.com/tweenjs/tween.js/issues/323) 中提出，谢谢！** 目录: -- [开发者要求](#developer-requirements) -- [测试](#testing) -- [持续集成](#continuous-integration) -- [发布过程](#release-process) +- [tween.js 贡献者指南](#tween.js-贡献者指南) +- [开发者要求](#开发者要求) +- [测试](#测试) + - [单元测试](#单元测试) + - [代码风格和 lint 测试](#代码风格和-lint-测试) + - [其他类型的测试](#其他类型的测试) +- [持续集成](#持续集成) +- [发布流程](#发布流程) ## 开发者要求 -虽然 tween.js*不*需要 nodejs 工作,我们用它来开发.所以我们需要 [安装 nodejs](https://nodejs.org/en/download/),然后才能在库中工作. +虽然 tween.js *不*需要依赖 node.js 运行，但我们使用 node.js 来进行开发。所以我们需要先 [安装 node.js](https://nodejs.org/en/download/)，然后才能在库中工作。 -Node.js 包含了我们使用的`npm`工具来运行脚本,比如打包,运行测试等等.请确保它在你的系统中正常工作,然后再尝试运行下面详述的任何步骤。 +Node.js 包括我们用来运行脚本的 npm 工具，例如打包、运行测试等的脚本。在你尝试运行下面详述的任何步骤之前，请确保它在你的系统中正常工作。 -一旦安装了 node.js,请克隆 tween.js 仓库: +安装 node.js 后，克隆 tween.js 存储库： ```bash git clone https://github.com/tweenjs/tween.js.git ``` -进入该文件夹 +进入该文件夹： ```bash cd tween.js ``` -运行脚本安装依赖 +并运行脚本来安装开发依赖项： ```bash npm install ``` -或者三行: +或者分三行： ```bash git clone https://github.com/tweenjs/tween.js.git @@ -45,211 +51,71 @@ cd tween.js npm install ``` -一旦`npm install`成功,试着运行测试: +`npm install` 成功完成后，尝试运行测试： ```bash npm test ``` -如果您遇到上述任何问题,请尝试使用你的搜索引擎搜索错误文本.这通常是最快的路线,因为许多人可能已经遇到同样的问题。 +如果你在运行上述任何步骤时遇到问题，请尝试使用你选择的搜索引擎搜索错误文本。这通常是最快的解决方法，因为很多人可能已经遇到过同样的问题。 ## 测试 -`test`目录中有一套自动化测试. +`test` 目录中有一套自动化测试。 -这些可以快速找到代码上的回归,在添加新功能或更改代码以修复错误时非常有用;我们不想引入新的问题!他们还能发现代码风格问题,这有助于我们保持库 cohesive. +这些可以快速发现代码上的回归，在添加新功能或更改代码以修复 Bug 时很有用；我们不想引入新的 Bugs！自动化测试还会发现风格问题，这有助于我们保持库的凝聚力。 -运行测试用例,输入: +要运行测试，请输入： ```bash npm test ``` -在更改库中的代码后,你应该运行测试.如果你更改测试描述的行为,则测试将不会通过,你将得到指向失败测试的错误.这可能是因为... +你应该在更改库中的代码后运行测试。如果你更改测试描述的行为，测试将不会通过，你将得到指向失败测试的错误。 这可能是因为... -- 你忽略了一些东西,或者你的代码有错误,或者... +- 你忽略了一些东西，或者你的代码有错误，或者... - 库或测试本身是错误的 -经常发生的是第一次,但第二次发生了,有边缘情况 +以上两种情况，发生频率更高的是第一个，但第如果二个发生了，可能是边缘情况。 -**自动化测试通过之后,您应该执行的另一件事是运行`examples`文件夹中的示例**.这不常见,但是可能会发生这样的情况:您的更改引入了自动化测试未检查的外观差异,唯一注意到这一点的方法是运行示例,并在输出上产生差异.如果你不想捡出两个库的副本,你可以看看[在线例子](https://github.com/tweenjs/tween.js#examples). +**自动化测试通过之后，你应该做的另一件事是运行 `examples` 文件夹中的示例**。有种情况很少见，但可能会发生：你的更改引入了自动测试未检查的外观差异，注意到这一点的唯一方法是运行示例并让人工发现输出中的差异。如果你不想签出库的两个副本，可以查看[在线例子](https://github.com/tweenjs/tween.js#examples)。 ### 单元测试 -测试用例在`src/tests.ts`文件中. +测试用例在 `src/tests.ts` 文件中。 -测试使用[nodeunit](https://www.npmjs.com/package/nodeunit)执行. +测试使用 [nodeunit](https://www.npmjs.com/package/nodeunit) 执行。 -**TODO:** 如果在浏览器中打开`test/unit/nodeunit.html`,测试也应该能够正常工作,但是现在已经被破坏了.有一个[打开的问题](https://github.com/tweenjs/tween.js/issues/307)使他们再次工作。 +**TODO:** 如果在浏览器中打开 `test/unit/nodeunit.html`，测试也应该能够正常运行，但是现在已经被损坏。有一个 [打开的问题](https://github.com/tweenjs/tween.js/issues/307) 可以使他们再次工作。 -### 修正和样式测试 +### 代码风格和 lint 测试 -我们使用[JSCS](http://jscs.info/)和[JSHint](http://jshint.com/)来确保代码风格是统一的。 +我们使用 [JSCS](http://jscs.info/) 和 [JSHint](http://jshint.com/) 来保证代码风格的统一。 -#### JSCS +要自动格式化代码并报告不可被格式化的代码片段的任何错误，请运行： -这个工具可以帮助我们发现大部分"修饰"代码风格问题.例如,空格与制表符,括号之间的空格等. - -运行: - -```bash -npm run test-style +```base +npm run test-lint ``` -JSCS 规则在`test/jscs.json`中. - -#### JSHint - -这个工具帮助我们发现代码质量问题.例如,使用正确的相等运算符,未使用的变量等. - -运行: - -```bash -npm run test-correctness -``` - -JSHint 规则在`test/jshintrc`中. +Prettier 规则在 `.prettierrc.js` 中，ESLint 规则在 `.eslintrc.js` 中。 ### 其他类型的测试 -我们想测试性能回归,也就是说,如果变化使得事情变得更慢,或者说性能变差,那么我们可以比较不同浏览器之间相同代码的性能. +我们想回归测试性能，即如果更改使运行变得更慢，或者简单地测试性能，那么我们可以比较不同浏览器之间相同代码的性能。 -有一个[open issue](https://github.com/tweenjs/discuss/issues/3)来跟踪这方面的工作,但我们还没有取得进展.请求帮助!:-) +有一个[open issue](https://github.com/tweenjs/discuss/issues/3)来跟踪这方面的工作，但我们还没有取得进展。请求帮助！ :-) ## 持续集成 -我们实施了一个持续集成系统,为我们自动完成任务.它在每次发出拉取请求时自动运行测试,并且在某些情况下还可以自动发布新版本. +我们使用 GitHub Actions 进行持续集成，以便为每个 pull request 运行构建和测试。 `.github/workflows/tests.yml` 文件告诉 GitHub 要运行什么；在我们的例子中，我们在该文件中指定的操作系统和 Node.js 版本中运行 `npm install`，然后运行 `npm test`。 -如果建议的拉取请求中的变更破坏了任何内容,则贡献者可以获得反馈,而无需等待人员查看代码.此外,请求不能合并,直到测试通过. +**TODO**：将 macOS 和 Windows 添加到运行测试的操作系统。 请求帮助！ :) -我们正在使用 Travis CI 平台来运行测试.您会在拉请求页面的底部找到一个小信息区,让您了解测试的状态. +## 发布流程 -所有检查通过的例子: +目前发布过程是手动的。 -![Automated checks OK](./imgs/pull-request-checks.png) +当准备好在 `master` 分支上发布时，确保没有未提交的更改，然后运行 `npm run release:patch` 发布一个新版本，其补丁号已被修改，`npm run release:minor` ，修改 minor 版本号并发布一个新版本，或者 `npm run release:major` 修改 major 版本号并发布一个新版本。 -当检查失败时: - -![Automated checks failing](./imgs/pull-request-checks-failing.png) - -如果一个 pull request 通过添加新的提交被更新,测试将再次运行. - -Travis 配置了`.travis.yml`文件(如果你没有在你的文件浏览器或 Finder 中看到它,那是因为文件名以一个点开头,因此它被*隐藏*了)-尝试用终端打开). - -## 发布过程 - -我们使用[semantic-release](https://github.com/semantic-release/semantic-release)工具结合 Travis 自动[在 GitHub 上创建版本](https://github.com/tweenjs/tween.js/releases)并将它们发布到[npm](https://npmjs.org). - -每次 pull request 合并时,Travis 都会运行测试.如果他们通过没有错误.Travis 将运行`after_success`步骤： - -```yaml -after_success: - - npm run semantic-release -``` - -这反过来会运行`package.json`中的`semantic-release`脚本: - -```json -"semantic-release": "semantic-release pre && npm publish && semantic-release post" -``` - -当新版本发布时: - -- `semantic-release`决定了下一个版本号 -- 一个新的条目被添加到 GitHub 发布列表,以及包含在更改中的所有提交列表,以及一个包含该版本的 ZIP 文件,供希望下载 ZIP 的用户使用 -- git commit 是用版本号(像[Bower](http://bower.io/)这样的工具使用标签) -- 它也被发布到 npm,在 package.json 里有新的版本号 - -**Note:** `semantic-release`的默认配置选项只在分支名称为`master`的情况下运行.否则,我们会产生大量的推送和发布,因为 Travis 在每个 pull request 中运行! - -请注意`package.json`中的版本号是故意为`0.0.0-development`,因为我们不想鼓励任何人手动修改这个,但是我们也不能从文件中删除`version`字段,或者直接使用 git 仓库安装模块将会失败. - -### 如何确定新的版本号 - -和 npm 一样,`semantic-release`遵循[semver](http://semver.org/)约定,所以每个版本都由唯一的`MAJOR.MINOR.PATCH`版本号来标识.例如,给定版本`1.2.3`:1 = 重要，2 = 轻微，3 = 补丁。 - -在这个系统中,重大更改(例如,API 被修改,更新到新版本可能需要更新使用库的代码)应该增加主编号.如果存在向后兼容的更改(例如,不修改现有 API 的新功能),次要号码将会增加.较小的更改(如文档更新)只会增加修补程序编号. - -`semantic-release`使用提交消息自动决定下一个版本号. - -这真是*太好了*,因为跟踪版本号或决定新版本是主要还是次要的改变是一件非常无聊的事情,最好留给机器自己去做. - -为了自动构建,提交消息需要遵循一定的语法: - -`: .` - -下表使用[默认行为](https://github.com/semantic-release/commit-analyzer/blob/master/src/index.js)列出了提交类型及其对版本号的影响. - -| Type of commit | Description | Version increase? | -| --------------- | ----------------------------------------------------------------------- | ----------------- | -| fix | fixes a bug but does not change the API | Increases PATCH | -| style | formatting changes | | -| docs | adding/removing/changing docs | | -| refactor | rewriting code but not breaking changes, adding features or fixing bugs | | -| test | changes in tests, e.g. adding a missing one) | | -| feat | adding new features which do not change the API | Increases MINOR | -| BREAKING CHANGE | changes the API | Increases MAJOR | - -### 如何安装和配置`semantic-release` - -这主要是为了信息的目的,因为`semantic-release`已经配置了 Travis,贡献者不需要担心这一点,但是记录所有内容是很好的. - -#### Option 1: 使用 CLI 工具 - -首先安装全局 cli 工具: - -```bash -npm install -g semantic-release-cli -``` - -然后在现有的基于 node.js 的项目中(即`package.json`已经存在): - -```bash -semantic-release-cli setup -``` - -在项目上设置`semantic-release`时它会问你一系列的问题.如果一切顺利,下一次你推到 GitHub,一个新版本将自动发生. - -您需要在您的帐户中启用 TravisCI。 - -#### Option 2: 手动 - -安装模块: - -```bash -npm install --save-dev semantic-release -``` - -编辑`package.json`来添加`semantic-release`脚本: - -```javascript -"scripts": { - //... - "semantic-release": "semantic-release pre && npm publish && semantic-release post" - //... -}, -``` - -如果不存在,创建一个`.travis.yml`文件(这里是[帮助创建`travis.yml`文件](https://docs.travis-ci.com/user/getting-started/))或[看看我们的](https://github.com/tweenjs/tween.js/blob/master/.travis.yml). - -在`.travis.yml`中添加`after_success`部分，以运行`语义释放` -Add an `after_success` section to `.travis.yml`, in order to run `semantic-release`: - -```yaml -after_success: - - npm run semantic-release -``` - -现在我们需要在 Travis CI 中启用这个项目,所以请确保你有一个帐户并登录. - -在 Travis 中启用项目（如果你是维护者）或者请求维护者启用它,在[Travis 设置页面](https://travis-ci.org/profile/)中. - -点击项目名称附近的齿轮来配置一些选项. - -向下滚动，直到看到*环境变量*. - -添加`GH_TOKEN`和`NPM_TOKEN`的标记.确保这两个变量都是隐藏的：`构建日志中的显示值`应该是`Off`. - -你可以从[npm](https://www.npmjs.com/settings/tokens)和[GitHub](https://github.com/settings/tokens)获得令牌.这些允许像 Travis 这样的服务代表您,这就是为什么您需要确保它们不会显示在构建日志中. - -希望现在每次你提交并推送到 GitHub 时,`semantic-release`将运行（如果使用上述的`master`分支）,并且可能会发布一个新版本. +Tip: 请参阅 [semver.org](https://semver.org/) 和 [npm-semver](https://docs.npmjs.com/misc/semver) 文档以了解语义版本控制。 diff --git a/docs/user_guide.md b/docs/user_guide.md index fa26f98..4f2061c 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,5 +1,7 @@ # tween.js user guide +More languages: [English](./user_guide.md), [简体中文](./user_guide_zh-CN.md) + _**NOTE** This is a work in progress. If you find that something is unclear or missing details, please [file an issue](https://github.com/tweenjs/tween.js/issues/new) and help make this guide better. Or feel free to submit clarifications or improvements of your own if you feel you can help too!_ ## What is a tween? How do they work? Why do you want to use them? diff --git a/docs/user_guide_zh-CN.md b/docs/user_guide_zh-CN.md index e1a78ed..3e6e36e 100644 --- a/docs/user_guide_zh-CN.md +++ b/docs/user_guide_zh-CN.md @@ -1,16 +1,22 @@ -## tween 是什么？如何使用？你为什么想用它？ +## tween.js 用户指南 -中文用户指南最近更新为 Tween.js v18.5.0 +更多语言: [English](./user_guide.md), [简体中文](./user_guide_zh-CN.md) -补间(动画)（来自 [in-between](https://en.wikipedia.org/wiki/Inbetweening)）是一个概念，允许你以平滑的方式更改对象的属性。你只需告诉它哪些属性要更改，当补间结束运行时它们应该具有哪些最终值，以及这需要多长时间，补间引擎将负责计算从起始点到结束点的值。 +中文用户指南最近更新为 Tween.js v20.0.3 -例如，`position`对象拥有`x`和`y`两个坐标: +_**NOTE** 这是一个正在进行的工作。 如果你发现某些内容不清楚或缺少详细信息，请 [提出 issue](https://github.com/tweenjs/tween.js/issues/new) 并帮助改进本指南。 或者，如果你觉得自己也能提供帮助，请随时提交你自己的说明或改进！_ + +## 什么是 tween ？tween 是如何工作的？为什么要使用 tween ？ + +补间（动画）（来自 [in-between](https://en.wikipedia.org/wiki/Inbetweening)）是一个概念，允许你以平滑的方式更改对象的属性。你只需告诉它哪些属性要更改，当补间结束运行时它们应该具有哪些最终值，以及这需要多长时间，补间引擎将负责计算从起始点到结束点的值。 + +例如，`position` 对象拥有 `x` 和 `y` 两个坐标： ```js var position = {x: 100, y: 0} ``` -如果你想将`x`坐标的值从`100`变成`200`，你应该这么做： +如果你想将 `x` 坐标的值从 `100` 变成 `200` ，你应该这么做： ```js // 首先为位置创建一个补间(tween) @@ -20,14 +26,14 @@ var tween = new TWEEN.Tween(position) tween.to({x: 200}, 1000) ``` -一般来说这样还不够，tween 已经被创建了，但是它还没被激活(使用)，你需要这样启动： +通常来说这样还不够，tween 已经被创建了，但是它还没被激活(使用)，你需要这样启动： ```js // 启动 tween.start() ``` -最后，想要成功的完成这种效果，你需要在主函数中调用`TWEEN.update`，如下使用： +最后，想要成功的完成这种效果，你需要在主函数中调用 `TWEEN.update` ，如下使用： ```js animate() @@ -40,7 +46,7 @@ function animate() { } ``` -这样在更新每帧的时候都会运行补间动画；经过 1 秒后 (1000 毫秒) `position.x`将会变成 `200`。 +这样在更新每帧的时候都会运行补间动画；经过 1 秒（1000 毫秒）后 `position.x` 将会变成 `200`。 除非你在控制台中打印出 `x` 的值，不然你看不到它的变化。你可能想要使用 `onUpdate` 回调: @@ -50,11 +56,9 @@ tween.onUpdate(function (object) { }) ``` -> tips:你可能在这里获取不到 `object.x` ,具体的见我提的这个 [issue](https://github.com/tweenjs/tween.js/issues/402) +每次更新补间时都会调用此函数； 这种情况发生的频率取决于许多因素——例如，你的计算机或设备的速度有多快（以及有多繁忙！）。 -这个函数将会在动画每次更新的时候被调用；这种情况发生的频率取决于很多因素 - 例如，计算机或设备的速度有多快（以及如何繁忙）。 - -到目前为止，我们只使用补间动画向控制台输出值，但是您可以将它与 three.js 对象结合： +到目前为止，我们只使用 tweens 将值打印到控制台，但你可以将它用于 three.js 对象的动画位置之类的事情： ```js var tween = new TWEEN.Tween(cube.position).to({x: 100, y: 100, z: 100}, 10000).start() @@ -69,9 +73,9 @@ function animate() { } ``` -在这种情况下，因为 three.js 渲染器将在渲染之前查看对象的位置，所以不需要使用明确的`onUpdate`回调。 +在这种情况下，因为 three.js 渲染器将在渲染之前查看对象的位置，所以不需要使用的 `onUpdate` 回调。 -你可能也注意到了一些不同的地方：tween.js 可以链式调用！ 每个`tween`函数都会返回`tween`实例，所以你可以重写下面的代码： +你可能也注意到了一些不同的地方：tween.js 可以链式调用！ 每个 tween 函数都会返回 tween 实例，所以你可以重写下面的代码： ```js var tween = new TWEEN.Tween(position) @@ -85,7 +89,7 @@ tween.start() var tween = new TWEEN.Tween(position).to({x: 200}, 1000).start() ``` -在将会看到很多例子，所以熟悉它是很好的！比如 [04-simplest](https://github.com/tweenjs/tween.js/blob/master/examples/04_simplest.html) 这个例子。 +在将会看到很多例子，所以熟悉它是很好的！比如 [04-simplest](../examples/04_simplest.html) 这个例子。 ## tween.js 的动画 @@ -104,15 +108,15 @@ function animate() { } ``` -如果调用的时候不传入参数，`update` 将会判断当前时间点以确定自上次运行以来已经有多久。 +如果不带参数调用，`update` 将会判断当前时间点，以便找出自上次运行以来已经过了多长时间。 -当然你也可以传递一个明确的时间参数给 `update` +当然你也可以传递一个明确的时间参数给 `update` 来更新。因此： ```js TWEEN.update(100) ``` -意思是"更新时间 = 100 毫秒"。你可以使用它来确保代码中的所有时间相关函数都使用相同的时间值。例如，假设你有一个播放器，并希望同步运行补间。 你的 `animate` 函数可能看起来像这样： +意思是“更新时间 = 100 毫秒”。你可以使用它来确保代码中的所有时间相关函数都使用相同的时间值。例如，假设你有一个播放器，并希望同步运行补间。 你的 `animate` 函数可能看起来像这样： ```js var currentTime = player.currentTime @@ -123,9 +127,9 @@ TWEEN.update(currentTime) ## 控制一个补间 -### start 和 stop +### `start` 和 `stop` -到目前为止，我们已经了解了`Tween.start`方法，但是还有更多的方法来控制单个补间。 也许最重要的一个是 `start` 对应的方法：`停止` 。 如果你想取消一个补间，只要调用这个方法通过一个单独的补间: +到目前为止，我们已经了解了 `Tween.start` 方法，但是还有更多的方法来控制单个补间。也许最重要的一个是 `start` 对应的方法：`stop` 。 如果你想取消一个补间，只要调用这个方法通过一个单独的补间: ```js tween.stop() @@ -133,93 +137,139 @@ tween.stop() 停止一个从未开始或已经停止的补间没有任何效果。 没有错误被抛出。 -`start` 方法接受一个参数 `time`。如果你使用它，那么补间不会立即开始，直到特定时刻，否则会尽快启动（i.e 即在下次调用 `TWEEN.update`）。 +`start` 方法还接受一个 `time` 参数。如果你使用它，补间直到那个特定的时刻才会开始；否则它将立即开始（即在下一次调用 `TWEEN.update` 时）。 -### update +`start` 方法接受第二个布尔参数：当为 `true` 时，我们之前使用的补间将从目标对象中的值开始，而不是从头开始。用于停止补间，然后启动另一个将从当前位置继续的补间。 -补间也有一个更新的方法---这实际上是由 `TWEEN.update` 调用的。 你通常不需要直接调用它，除非你是个 疯狂的 hacker。 +### `startFromCurrentValues` -### chain +这是 `tween.start(undefined, true)` 的别名，使以前使用的补间从目标对象的最后一个值开始，而不是从头开始。 -当你顺序排列不同的补间时，事情会变得有趣，例如在上一个补间结束的时候立即启动另外一个补间。我们称这为链式补间，这使用 `chain` 方法去做。因此，为了使 `tweenB` 在 `tewwnA` 启动： +### `update` + +个别补间有一个 `update` 方法。 这实际上是由 `TWEEN.update` 调用的，用于仅使用一个参数构建的补间。 + +在下面的示例中，第二个参数告诉新的 Tween 不要将自己添加到默认组（`TWEEN` 是 `TWEEN.Group` 的一个实例）。如果补间不与组关联（请注意，可以通过将组作为第二个参数传递给构造函数来关联组），则补间需要使用其 `update` 方法手动更新，如下所示： + +```js +const tween = new TWEEN.Tween(someObject, false).to(/*...*/).start() + +function animate(time) { + tween.update(time) + requestAnimationFrame(animate) +} +``` + +> **Note** 如果你使用 `TWEEN.update()` 作为默认控制所有补间的方式，则无需直接调用 `tween.update()`，但是我们建议你直接如上例所示 [创建自己的补间组](#controlling-groups-of-tweens) 或手动更新补间。 使用组或单独控制的补间的概念很像避免在 JavaScript 代码中使用全局变量的做法：它可以防止一个组件意外破坏其他一些不相关组件的行为。 + +### `chain` + +当你按顺序排列不同的补间时，事情会变得更有趣，例如在上一个补间结束的时候立即启动另外一个补间。我们称此为链接补间，它是通过 `chain` 方法完成的。因此，要使 `tweenB` 在 `tweenA` 完成后开始： ```js tweenA.chain(tweenB) ``` -或者，对于一个无限的链式，设置 tweenA 一旦 tweenB 完成就开始： +或者，可以创造一个无限的链式，`tweenA` 完成时开始 `tweenB`，`tweenB` 完成时开始 `tweenA`： ```js tweenA.chain(tweenB) tweenB.chain(tweenA) ``` -关于无限的链式查看 [Hello world](https://github.com/tweenjs/tween.js/blob/master/examples/00_hello_world.html) 。 +关于无限的链式查看案例 [Hello world](../examples/00_hello_world.html) 。 -在其他情况下，您可能需要将多个补间链接到另一个补间，以使它们（链接的补间）同时开始动画： +在其他情况下，你可能希望将多个补间链接到另一个补间，使它们（链接的补间）都同时开始动画： ```js tweenA.chain(tweenB, tweenC) ``` -> 警告：调用 `tweenA.chain（tweenB）` 实际上修改了 tweenA，所以 tweenA 总是在 tweenA 完成时启动。 `chain` 的返回值只是 tweenA，不是一个新的 tween。 +> **Warning** 调用 `tweenA.chain（tweenB）` 实际上修改了 tweenA，所以 tweenB 总是在 tweenA 完成时启动。 `chain` 的返回值只是 tweenA，不是一个新的 tween。 -### repeat +### `repeat` -如果你想让一个补间永远重复，你可以链接到自己，但更好的方法是使用 `repeat` 方法。 它接受一个参数，描述第一个补间完成后需要多少次重复 +如果你想让一个补间永远重复，你可以链接到自己，但更好的方法是使用 `repeat` 方法。它接受一个参数，描述第一个补间完成后需要多少次重复： ```js tween.repeat(10) // 循环10次 tween.repeat(Infinity) // 无限循环 ``` -补间的总次数将是重复参数加上一个初始补间。查看 [Repeat](https://github.com/tweenjs/tween.js/blob/master/examples/08_repeat.html)。 +补间的总次数将是重复参数加上一个初始补间。查看 [Repeat](../examples/08_repeat.html) 。 -### yoyo +### `yoyo` -这个功能只有在独自使用 `repeat` 时才有效果。 活跃时，补间的行为将像 yoyo 一样，i.e 它会从起始值和结束值之间跳出，而不是从头开始重复相同的顺序。 +此功能仅在与 `repeat` 一起使用时才有效。 激活时，补间的行为将 _像溜溜球一样_，即它会在开始值和结束值之间来回跳动，而不是仅仅从头开始重复相同的顺序： -### delay +```js +tween.yoyo(false) // 默认值，动画只会从开始到结束值 +tween.yoyo(true) // tween 将在起始值和结束值之间“yoyo” +``` -更复杂的安排可能需要在实际开始运行之前延迟补间。 你可以使用 `delay` 方法来做到这一点 +### `delay` + +更复杂的安排可能需要在实际开始运行之前延迟补间。 你可以使用 `delay` 方法来做到这一点： ```js tween.delay(1000) tween.start() ``` -将在调用启动方法后的 1 秒钟后开始执行。 +将在调用 `start` 方法后的 1 秒钟后开始执行。 -## 控制所有补间 +### `repeatDelay` -在 TWEEN 全局对象中可以找到以下方法，除了 `update` 之外，通常不需要使用其中的大部分对象。 +通常，`delay` 时间应用于补间的重复之间，但如果向 `repeatDelay` 函数提供了一个值，则该值将确定补间重复之间经过的总时间。 -### TWEEN.update(time) +参考这个例子： -我们已经讨论过这种方法。 它用于更新所有活动的补间。 +```js +tween.delay(1000) +tween.repeatDelay(500) +tween.start() +``` + +补间的第一次迭代将在一秒后发生，第二次迭代将在第一次迭代结束后半秒发生，第三次迭代将在第二次迭代结束后半秒发生，依此类推。如果你想延迟初始迭代但不希望迭代之间有任何延迟，请确保调用 `tween.repeatDelay(0)` 。 + +### `dynamic` + +如果 `dynamic` 设置为 `true`（默认为 `false`），则传递给 `tween.to()` 的对象可以在补间动画的外部进行修改。这可用于在运行时动态修改补间的结果。 + +请参阅 [dynamic 示例](http://tweenjs.github.io/tween.js/examples/07_dynamic_to.html)。在那个例子中，在这两个场景中，兔子的位置都在动画期间更新。 兔子的位置恰好是传递给狐狸的 `tween.to()` 方法的对象。 随着兔子位置的更新，在第一个带有 `.dynamic(false)` 的场景中，狐狸向兔子的初始位置移动并且不跟随兔子，而在第二个带有 `.dynamic(true)` 的场景中，狐狸移动到兔子的最终目的地 狐狸因此也被更新，这使得狐狸跟随兔子。 + +> **Warning** 当 `dynamic` 设置为 `false` 时，Tween 复制传递给 `tween.to()` 的对象并且永远不会修改它（因此从外部更新原始对象不是动态的）。当 `dynamic` 为 `true` 时，Tween 在动画期间使用原始对象作为值的来源（每次更新都读取值，因此可以动态修改它们） **但请注意，在 dynamic 模式下，Tween 将修改传递给 `tween.to()` 的对象的任何插值数组，这可能会对也可能依赖于同一对象的任何外部代码造成副作用。** + +## 控制*所有*补间 + +在 TWEEN 全局对象中可以找到以下方法，除了 `update` 之外，你通常不需要使用其中的大部分方法。 + +### `TWEEN.update(time)` + +我们已经讨论过这种方法。它用于更新所有活动的补间。 如果 `time` 不指定，它将使用当前时间。 -### TWEEN.getAll and TWEEN.removeAll +### `TWEEN.getAll` and `TWEEN.removeAll` -用于获取对活动 `tweens` 数组的引用，并分别仅从一个调用中将它们全部从数组中删除 +用于获取对活动 `tweens` 数组的引用，并分别通过一次调用将它们从数组中移除。 -### TWEEN.add(tween) and TWEEN.remove(tween) +### `TWEEN.add(tween)` and `TWEEN.remove(tween)` -用于将补间添加到活动补间的列表，或者分别从列表中删除特定的补间。 +分别用于将补间添加到活动补间列表，或从列表中删除特定补间。 -这些方法通常只在内部使用，但是如果您想要做一些有趣的事情，则会被暴露。 +这些方法通常只在内部使用，但如果你想做一些*有趣*的事情，我们会公开这些方法。 -## 控制补间组 +## 控制补间集 -使用 `TWEEN` 单例来管理补间可能会导致包含许多组件的大型应用程序出现问题。 在这些情况下，您可能希望创建自己的更小的补间组。 +使用 `TWEEN` 单例来管理补间可能会导致包含许多组件的大型应用程序出现问题。在这些情况下，你可能想要创建自己的更小的补间集。 ### 示例：交叉组件冲突 -如果使用 `TWEEN` 有多个组件，并且每个组件都想管理自己的一组补间，则可能发生冲突。 如果一个组件调用 `TWEEN.update（）` 或 `TWEEN.removeAll（）`，则其他组件的补间也将被更新或删除。 +如果你有多个组件使用 `TWEEN`，并且每个组件都想管理自己的补间集，则可能会发生冲突。 如果一个组件调用 `TWEEN.update()` 或 `TWEEN.removeAll()`，其他组件的补间也将被更新或删除。 -### 创建你自己的补间组 +### 创建你自己的补间集 -为了解决这个问题，每个组件都可以创建自己的 `TWEEN.Group` 实例（这是全局的 `TWEEN` 对象在内部使用的）。 实例化新的补间时，可以将这些组作为第二个可选参数传入： +为了解决这个问题，每个组件都可以创建自己的 `TWEEN.Group` 实例（这是全局 `TWEEN` 对象在内部使用的实例）。 在实例化新补间时，这些组可以作为第二个可选参数传入： ```js var groupA = new TWEEN.Group() @@ -240,35 +290,35 @@ groupB.removeAll() // 只移除tweenB TWEEN.removeAll() // 只移除tweenC ``` -通过这种方式，每个组件都可以处理创建，更新和销毁自己的一组补间。 +这样，每个组件都可以处理创建、更新和销毁自己的补间集。 -## 改变缓动功能 +## 改变缓动功能（别名：让它弹） -Tween.js 将以线性方式执行值之间的插值（即缓动），所以变化将与流逝的时间成正比。 这是可以预见的，但在视觉上也是相当无趣的。 不要担心 - 使用缓动方法可以轻松更改此行为。 例如： +Tween.js 将以线性方式执行值之间的插值（即缓动），因此变化将与经过的时间成正比。 这是可以预见的，但在视觉上也很无趣。 不用担心——可以使用缓动方法轻松更改此行为。 例如： ```js tween.easing(TWEEN.Easing.Quadratic.In) ``` -这将导致缓慢地开始向最终值变化，向中间加速，然后迅速达到其最终值，相反，`TWEEN.Easing.Quadratic.Out` 一开始会加速，但随着值的接近最终放缓。 +这将导致补间缓慢开始向最终值变化，向中间加速，然后快速达到其最终值。 相比之下，`TWEEN.Easing.Quadratic.Out` 将开始向该值快速变化，但在接近最终值时会减慢速度。 -### 可用的缓动函数：TWEEN.Easing +### 可用的缓动函数：`TWEEN.Easing` -tween.js 提供了一些现有的缓动功能。它们按照它们表示的方程式进行分组：线性，二次，三次，四次，五次，正弦，指数，圆形，弹性，背部和弹跳，然后是缓动型：In，Out 和 InOut。 +tween.js 提供了一些现成的缓动功能。它们按照它们表示的方程类型进行分组：线性、二次、三次、四次、五次、正弦、指数、圆形、弹性、后退和反弹，然后按缓动类型：In、Out 和 InOut。 -除非您已经熟悉这些概念，否则这些名称可能不会对您说什么，所以您可能需要查看 [Graphs](https://github.com/tweenjs/tween.js/blob/master/examples/03_graphs.html) 示例，该示例将一个页面中的所有曲线进行图形化，以便比较它们如何看待一瞥。 +除非你已经熟悉这些概念，否则这些名称可能对你没有任何意义，所以现在可能是查看 [图表示例](../examples/17_generate_pow.html) 的时候了，该示例在一页中绘制了所有曲线，以便你可以比较它们的动画。 -这些功能是从 Robert Penner 慷慨地提供几年前作为自由软件提供的原始方程派生而来的，但是已经被优化以便与 JavaScript 很好地发挥作用。 +这些函数源自 Robert Penner 几年前慷慨地作为免费软件提供的原始方程，但已经过优化后，可以很好地与 JavaScript 配合使用。 ### 使用自定义缓动功能 -您不仅可以使用任何现有的功能，还可以提供您自己的功能，只要遵循一些约定即可： +你不仅可以使用任何现有的缓动函数，还可以提供自己的函数，只要它遵循一些约定即可： - 它必须接受一个参数： - - `k`: 缓动过程，或我们的补间所处的时间有多长。允许的值在[0，1]的范围内。 + - `k`: 缓动过程，或我们的补间所处的时间有多长。允许的值在[0, 1]的范围内。 - 它必须根据输入参数返回一个值。 -不管要修改多少个属性，easing 函数在每次更新时只调用一次。 然后将结果与初始值以及这个值和最终值之间的差值（delta）一起使用，就像这个伪代码一样： +无论要更改多少属性，每次更新时每个补间只调用一次缓动函数。 然后将结果与初始值以及此值和最终值之间的差值（_deltas_）一起使用，如以下伪代码所示： ```js easedElapsed = easing(k); @@ -276,9 +326,9 @@ for each property: newPropertyValue = initialPropertyValue + propertyDelta * easedElapsed; ``` -对于更注重性能表现的人来说：只有在补间上调用 `start()` 时才会计算增量值。 +对于更注重性能表现的人来说：只有在补间上调用 `start()` 时才会计算 deltas。 -因此，让我们假设您想使用一个缓解值的自定义缓动函数，但是将 Math.floor 应用于输出，所以只返回整数部分，从而产生一种梯级输出: +因此，假设你想要使用自定义缓动函数来缓动值但将 `Math.floor` 应用于输出，因此只会返回整数部分，从而产生一种阶梯式输出： ```js function tenStepEasing(k) { @@ -286,19 +336,19 @@ function tenStepEasing(k) { } ``` -你可以通过简单地调用它的缓动方法来使用它，就像我们之前看到的那样： +你可以通过简单地调用它的缓动方法在补间中使用它，就像我们之前看到的那样： ```js tween.easing(tenStepEasing) ``` -查看 [graphs for custom easing functions](https://github.com/tweenjs/tween.js/blob/master/examples/12_graphs_custom_functions.html) 示例，以查看这个动作（还有一些用于生成步进函数的元编程）。 +查看 [graphs for custom easing functions](../examples/12_graphs_custom_functions.html) 示例，以查看这个动作（还有一些用于生成步进函数的 _metaprogramming_ ）。 ## 回调函数 另一个强大的特性是能够在每个补间的生命周期的特定时间运行自己的功能。 当更改属性不够时，通常需要这样做。 -例如，假设你正在试图给一些不能直接访问属性的对象设置动画，但是需要你调用 setter。 您可以使用 `update` 回调来读取新的更新值，然后手动调用 setters。 所有的回调函数都将补间对象作为唯一的参数。 +例如，假设你正在试图给一些不能直接访问属性的对象设置动画，但是需要你调用 setter。 你可以使用 `update` 回调来读取新的更新值，然后手动调用 setters。 所有的回调函数都将补间对象作为唯一的参数。 ```js var trickyObjTween = new TWEEN.Tween({ @@ -312,7 +362,7 @@ var trickyObjTween = new TWEEN.Tween({ }) ``` -或者想象一下，当一个补间开始时，你想播放声音。你可以使用 `start` 回调： +或者假设你想在开始补间时播放声音。 你可以使用 `start` 回调： ```js var tween = new TWEEN.Tween(obj).to({x: 100}).onStart(function () { @@ -320,34 +370,167 @@ var tween = new TWEEN.Tween(obj).to({x: 100}).onStart(function () { }) ``` -每个回调的范围是补间对象--在这种情况下，是 `obj`。 +每个回调的范围是补间对象——在本例中为 `obj`。 ### onStart -在补间开始之前执行--i.e. 在计算之前。每个补间只能执行一次，i.e. 当通过 `repeat()` 重复补间时，它将不会运行。 +在补间开始动画之前执行，在 `delay` 方法指定的任何延迟时间之后。 每个补间只会执行一次，即当补间通过 `repeat()` 重复时不会运行。 -同步到其他事件或触发您要在补间启动时发生的操作是非常好的。 +`onStart` 非常适合与其他事件同步，或触发需要在补间开始时执行的操作。 + +补间对象作为第一个参数传入。 + +### onEveryStart + +和 `onStart` 类似，单 `onEveryStart` 在每次重复补间时也会运行。 补间对象作为第一个参数传入。 ### onStop -当通过 `stop()` 显式停止补间时执行，但在正常完成时并且在停止任何可能的链补间之前执行补间。 +当补间通过 `stop()` 显式停止时执行，但不会在它正常完成时执行，并且在停止任何可能的链接补间之前执行。 补间对象作为第一个参数传入。 ### onUpdate -每次补间更新时执行，实际更新后的值。 +每次更新补间时执行，在实际更新值之后。 补间对象作为第一个参数传入。 ### onComplete -当补间正常完成（即不停止）时执行。 +当补间正常完成（即未停止）时执行。 补间对象作为第一个参数传入。 +### onRepeat + +每当补间刚刚完成一个重复并将开始另一个重复时执行。 + +补间对象作为第一个参数传入。 + +要阐明何时调用 `onStart`、`onEveryStart` 和 `onRepeat`，请参考： + +```js +const obj = {x: 0} + +const t = new TWEEN.Tween(obj) + .to({x: 5}, 5) + .repeat(Infinity) + .onStart(() => { + console.log('onStart') + }) + .onRepeat(() => { + console.log('onRepeat') + }) + .onEveryStart(() => { + console.log('onEveryStart') + }) + .start(0) + +for (let ticks = 0; ticks < 22; ticks += 1) { + console.log('Tick', ticks) + TWEEN.update(ticks) + + console.log(obj) + console.log() +} +``` + +输出如下所示，左侧如上，右侧带有 `.delay(5)`： + +```txt +Tick 0 Tick 0 +onStart { x: 0 } +onEveryStart +{ x: 0 } + +Tick 1 Tick 1 +{ x: 1 } { x: 0 } + +Tick 2 Tick 2 +{ x: 2 } { x: 0 } + +Tick 3 Tick 3 +{ x: 3 } { x: 0 } + +Tick 4 Tick 4 +{ x: 4 } { x: 0 } + +Tick 5 Tick 5 +onRepeat onStart +{ x: 5 } onEveryStart + { x: 0 } + +Tick 6 Tick 6 +onEveryStart { x: 1 } +{ x: 1 } + +Tick 7 Tick 7 +{ x: 2 } { x: 2 } + +Tick 8 Tick 8 +{ x: 3 } { x: 3 } + +Tick 9 Tick 9 +{ x: 4 } { x: 4 } + +Tick 10 Tick 10 +onRepeat onRepeat +{ x: 5 } { x: 5 } + +Tick 11 Tick 11 +onEveryStart { x: 5 } +{ x: 1 } + +Tick 12 Tick 12 +{ x: 2 } { x: 5 } + +Tick 13 Tick 13 +{ x: 3 } { x: 5 } + +Tick 14 Tick 14 +{ x: 4 } { x: 5 } + +Tick 15 Tick 15 +onRepeat onEveryStart +{ x: 5 } { x: 0 } + +Tick 16 Tick 16 +onEveryStart { x: 1 } +{ x: 1 } + +Tick 17 Tick 17 +{ x: 2 } { x: 2 } + +Tick 18 Tick 18 +{ x: 3 } { x: 3 } + +Tick 19 Tick 19 +{ x: 4 } { x: 4 } + +Tick 20 Tick 20 +onRepeat onRepeat +{ x: 5 } { x: 5 } + +Tick 21 Tick 21 +onEveryStart { x: 5 } +{ x: 1 } +``` + +## 补间状态 + +### `isPlaying` + +开始时为 `true`（即使是暂停）。 + +当补间停止时，`isPlaying` 和 `isPaused` 都将为 `false`。 + +### `isPaused` + +暂停时为 `true`。 `isPlaying` 也将为 `true`。 如果补间已启动但未暂停，则 `isPlaying` 将为 `true` 而 `isPaused` 将为 `false`。 + ## 高级补间 ### 相对值 @@ -356,33 +539,41 @@ var tween = new TWEEN.Tween(obj).to({x: 100}).onStart(function () { **但是你需要使用引号**，否则这些值将被视为绝对的。 我们来看一个例子: ```js -// This will make the `x` property be 100, always +// 这将使 `x` 属性始终为 100 var absoluteTween = new TWEEN.Tween(absoluteObj).to({x: 100}) -// Suppose absoluteObj.x is 0 now -absoluteTween.start() // Makes x go to 100 +// 假设 absoluteObj.x 现在为 0 +absoluteTween.start() // 使 x 变为 100 -// Suppose absoluteObj.x is -100 now -absoluteTween.start() // Makes x go to 100 +// 假设 absoluteObj.x 现在是 -100 +absoluteTween.start() // 使 x 变为 100 -// In contrast... +// 相比之下... -// This will make the `x` property be 100 units more, -// relative to the actual value when it starts +// 这将使 `x` 属性相对于开始时的实际值多 100 个单位 var relativeTween = new TWEEN.Tween(relativeObj).to({x: '+100'}) -// Suppose relativeObj.x is 0 now -relativeTween.start() // Makes x go to 0 +100 = 100 +// 假设 relativeObj.x 现在是 0 +relativeTween.start() // 使 x 变为 0 +100 = 100 -// Suppose relativeObj.x is -100 now -relativeTween.start() // Makes x go to -100 +100 = 0 +// 假设 relativeObj.x 现在是 -100 +relativeTween.start() // 使 x 变为 -100 +100 = 0 ``` -查看 [09_relative_values](https://github.com/tweenjs/tween.js/blob/master/examples/09_relative_values.html) 示例。 +查看 [09_relative_values](../examples/09_relative_values.html) 示例。 + +### 补间嵌套对象 + +Tween.js 还可以跨嵌套对象更改属性。 例如： + +```js +var nestedObject = {scale: {x: 0, y: 0}, alpha: 0} +var tween = new TWEEN.Tween(nestedObject).to({scale: {x: 100, y: 100}, alpha: 1}) +``` ### 补间值的数组 -除了补间为绝对值或相对值之外，还可以让 Tween.js 跨一系列值更改属性。 要做到这一点，你只需要指定一个数组的值，而不是一个属性的单个值。 例如： +除了补间到绝对值或相对值之外，你还可以让 Tween.js 更改一系列值的属性。 为此，你只需为属性指定一个值数组而不是单个值。 例如： ```js var tween = new TWEEN.Tween(relativeObj).to({x: [0, -100, 100]}) @@ -398,7 +589,7 @@ var tween = new TWEEN.Tween(relativeObj).to({x: [0, -100, 100]}) 例如，当补间刚刚启动（进度为 0）时，插值函数将返回数组中的第一个值。 当补间到一半时，插值函数将返回一个大约在数组中间的值，当补间结束时，插值函数将返回最后一个值。 -您可以使用插值方法更改插值函数。 例如： +你可以使用插值方法更改插值函数。 例如： ```js tween.interpolation(TWEEN.Interpolation.Bezier) @@ -412,18 +603,18 @@ tween.interpolation(TWEEN.Interpolation.Bezier) 默认是 `Linear`。 -请注意，插值函数对于与同一补间中的数组进行补间的所有属性是全局的。 -您不能使用数组和线性函数进行属性 A 的更改，也不能使用相同的补间进行数组 B 的属性 B 和 Bezier 函数的更改; 您应该使用运行在同一对象上的两个补间对象，但修改不同的属性并使用不同的插值函数。 +请注意，插值函数对于在同一补间中与数组补间的所有属性都是全局的。 +你不能使用数组和线性函数更改属性 A，也不能使用数组和使用相同补间的贝塞尔函数更改属性 B； 你应该使用两个运行在同一对象上但修改不同属性并使用不同插值函数的补间对象。 -查看 [06_array_interpolation](https://github.com/tweenjs/tween.js/blob/master/examples/06_array_interpolation.html) 示例。 +查看 [06_array_interpolation](../examples/06_array_interpolation.html) 示例。 ## 获得最佳性能 -虽然 Tween.js 试图自己执行，但是没有什么能够阻止你以一种反作用的方式使用它。 这里有一些方法可以避免在使用 Tween.js 时（或者在网页中进行动画制作时）减慢项目速度。 +虽然 Tween.js 试图靠自己发挥性能，但没有什么能阻止你以反性能的方式使用它。 以下是一些在使用 Tween.js 时（或通常在 Web 中制作动画时）可以避免拖慢项目速度的方法。 ### 使用高性能的 CSS -当您尝试在页面中设置元素的位置时，最简单的解决方案是为 `top` 和 `left` 属性设置动画，如下所示： +当你尝试为页面中元素的位置设置动画时，最简单的解决方案是为 `top` 和 `left` 样式属性设置动画，如下所示： ```js var element = document.getElementById('myElement') @@ -433,7 +624,7 @@ var tween = new TWEEN.Tween({top: 0, left: 0}).to({top: 100, left: 100}, 1000).o }) ``` -但这实际上是效率低下的，因为改变这些属性会迫使浏览器在每次更新时重新计算布局，这是非常昂贵的操作。 相反的，您应该使用 `transform`，这不会使布局无效，并且在可能的情况下也将被硬件加速，比如： +但这确实效率低下，因为更改这些属性会强制浏览器在每次更新时重新计算布局，这是一项非常消耗性能的操作。你应该使用 `transform`，它不会使布局无效，并且在可能的情况下也会进行硬件加速，如下所示： ```js var element = document.getElementById('myElement') @@ -442,16 +633,15 @@ var tween = new TWEEN.Tween({top: 0, left: 0}).to({top: 100, left: 100}, 1000).o }) ``` -如果你想了解更多关于这个，看看[这篇文章](https://www.paulirish.com/2012/why-moving-elements-with-translate-is-better-than-posabs-topleft/)。 +如果你想了解更多关于高性能的 CSS，看看[这篇文章](https://www.paulirish.com/2012/why-moving-elements-with-translate-is-better-than-posabs-topleft/)。 -但是，如果您的动画需求非常简单，那么在适用的情况下使用 CSS 动画或转换可能会更好，以便浏览器尽可能优化。 -当您的动画需要涉及复杂的布局时，Tween.js 是非常有用的，也就是说，您需要将多个补间同步到一起，在完成一些动作之后，循环多次等等。 +但是，如果你的动画需求就这么简单，最好只使用 CSS 动画或过渡（在适用的情况下），这样浏览器就可以尽可能地进行优化。 +当你的动画需要涉及复杂的操作时，Tween.js 是非常有用，也就是说，你需要将多个补间同步在一起，在一个完成后开始，循环多次，具有不是使用 CSS 而是使用 Canvas 渲染的图形或 WebGL 等等。 ### 对垃圾收集器（别名 GC） -如果你使用 onUpdate 回调函数，你需要非常小心的使用它。 因为这个函数每秒钟会被调用很多次，所以如果每次更新都要花费很多的代价，那么你可能会阻塞主线程并导致可怕的结果，或者如果你的操作涉及到内存分配的话， 垃圾收集器运行太频繁，也导致结果。 所以只是不要做些事情中的其中一个。 保持你的 onUpdate 回调非常轻量级，并确保在开发时也使用内存分析器。 +如果你使用 `onUpdate` 回调，你需要非常小心你放在它上面的东西。 这个函数每秒会被调用很多次，所以如果你在每次更新时都做代价高昂的操作，你可能会阻塞主线程并导致可怕的卡顿，或者——如果你的操作涉及内存分配，你最终会得到 垃圾收集器运行过于频繁，也会导致卡顿。 所以不要做这两件事。 保持你的 `onUpdate` 回调非常轻量级，并确保在开发时也使用内存分析器。 ### 疯狂的补间 -这是你可能不经常使用的东西，但是你可以在 Tween.js 之外使用补间公式。 毕竟，它们只是功能。 所以你可以使用它们来计算平滑曲线作为输入数据。 -例如，他们用于在 [这个实验](http://5013.es/toys/tween.audio/) 中生成音频数据。 +这是你可能不经常使用的东西，但你可以在 Tween.js 之外使用补间方程式。 毕竟，它们只是函数。 因此，你可以使用它们来计算平滑曲线作为输入数据。 例如，它们用于在[此实验](<(http://5013.es/toys/tween.audio/)>)中生成音频数据。