# @domchristie/turn 中文文档

规范地址：https://npmcn.com/package/%40domchristie/turn/

版本：3\.1\.1
npm 元数据更新时间：2023-09-20T07:27:05.652Z
中文译文更新时间：2026-11-12T15:32:35.101Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40domchristie/turn
原文对照：https://npmcn.com/package/%40domchristie/turn/?lang=original
项目主页：https://github.com/domchristie/turn#readme
源码仓库：https://github.com/domchristie/turn

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：28.7 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@hotwired/turbo ^7
- 首次发布：2022-10-09T16:30:56.699Z
- 最新版本发布：2023-09-20T07:27:05.453Z
- 近 30 天下载量：8282（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 0 个）

## 中文简介

Turbo Drive apps中的动画页面转换.

## 安装

```sh
npm install @domchristie/turn
```

也可以使用：`pnpm add @domchristie/turn`、`yarn add @domchristie/turn`、`bun add @domchristie/turn`

## README

# 转弯

动画页面转换 [涡轮驱动器](https://turbo.hotwired.dev/) 应用程序.

## 安装

安装 [@hotwired/涡轮](https://www.npmjs.com/package/@hotwired/turbo),则

```
npm install @domchristie/turn
```

## 使用量

1.  包括涡轮, `dist/turn.js` 财务报告和审定财务报表 `dist/turn.css` 无论如何,您正在构建您的 JavaScript & CSS
2.  添加 `data-turn-enter` 财务报告和审定财务报表 `data-turn-exit` 切入到您想要激活的元素中( 如果您只使用视图过渡即可选择)
3.  `import Turn from '@domchristie/turn'` 打电话 `Turn.start()` 在应用程序中 JavaScript
4.  导航在页面之间... {}

## 自定义动画

转动添加 `turn-before-exit`, (中文(简体) ), `turn-exit`,以及 `turn-enter` 分类到 HTML 元素。 应用自己的动画, 使用此选择器定义您的动画规则 。 例如:

```css
html.turn-advance.turn-exit [data-turn-exit] {
  animation-name: MY_ANIMATE_OUT;
  animation-duration: .3s;
  animation-fill-mode: forwards;
}

html.turn-advance.turn-enter [data-turn-enter] {
  animation-name: MY_ANIMATE_IN;
  animation-duration: .6s;
  animation-fill-mode: forwards;
}

@keyframes MY_ANIMATE_OUT {
  …
}

@keyframes MY_ANIMATE_IN {
  …
}
```

就是这样 `turn.css` 组织起来,所以你可能想 把文件全部删除. `animation-fill-mode: forwards` 建议防止您的过渡跳回.

### 自定义类名称

数值 `data-turn-exit` 财务报告和审定财务报表 `data-turn-enter` 属性将被用作该元素的类名。 这样您就可以自定义每个元素的动画 。 样式仍应以 `html.turn-exit` 财务报告和审定财务报表 `html.turn-enter`。 。 。 .

## 类列表

以下类名被添加到HTML元素中,在导航生命周期的不同时间.

### `turn-view-transitions`

如果设备支持视图过渡, 并启用视图过渡, 则在启动时添加 .

### `turn-no-view-transitions`

如果设备不支持 View Transits , 或 View Transits 已禁用, 启动时添加 .

### `turn-advance`

当访问开始, 动作是 `advance`. 你可能想用这个课来观察大多数动画. 在导航完成并所有动画结束时删除.

### `turn-restore`

当访问开始, 动作是 `restore`。鉴于可以向后/向后导航的方法数量多(后键,向左/向右刷出, `history.back()`),一般建议修复访问不是动画. 在导航完成并所有动画结束时删除.

### `turn-replace`

当访问开始, 动作是 `replace`。当导航完成并所有动画结束时删除.

### `turn-before-exit`

访问开始后添加. 用于优化动画 `will-change`. (见 `turn.css` 以实例为例。 ) 退出动画开始后删除 .

### `turn-exit`

访问开始后添加. 将此用于瞄准镜出局动画. 退出动画完成后删除 .

### `turn-before-transition` (如果支持视图过渡并启用)

在退出动画和任何请求完成后被添加,但在"视图过渡"取下快照之前被添加. 在将 View Transits 和自定义出/入动画合并时有用 。 为了避免内容闪出,使用这个类来瞄准已退出的元素,并在最终的"出局"状态下进行样式. (见 `turn.css` 以实例为例。 ) 过渡开始时删除 .

### `turn-transition` (如果支持视图过渡并启用)

在视图过渡中添加 。 在将 View Transits 和自定义出/入动画合并时有用 .

### `turn-enter`

在完成任何请求并完成之前的动画/过渡后添加. 动画完成后删除.

## 活动

`event.details` 可包含:

-   `action`访问的行动`advance` 或者说 `restore`(中文(简体) )
-   `initiator`: 访问所触发的元素( a) `a`, (中文(简体) ), `form`,或 `html` 如果后向/ 前向导航)
-   `referrer`: 页面正在转换的 URL
-   `url`: 页面正在转换到的 URL
-   `newBody`: 来者 `<body>` 转换到

### `turn:before-exit`

出发动画开始前发送. `event.detail` 包括:

-   `action`
-   `initiator`
-   `referrer`
-   `url`

### `turn:before-transition`

在视图过渡开始前( 如果存在退出动画之后) 已发送 。 理想设置 `view-transition-name`s 在视图过渡之前进行捕获. `event.detail` 包括:

-   `action`
-   `initiator`
-   `newBody`
-   `referrer`

### `turn:before-enter`

输入动画开始前的调度(如果在Vire Transiters之后). `event.detail` 包括:

-   `action`
-   `initiator`
-   `newBody`
-   `referrer`

### `turn:enter`

在所有过渡和动画完成后发送. `event.detail` 包括:

-   `action`
-   `referrer`
-   `url`
-   `timing`:访问的时间安排

### 使用 Tailwind CSS 软件

定义动画 `tailwind.config.js`,并添加一个对样式进行范围化的插件,例如:

```js
const plugin = require('tailwindcss/plugin')

module.exports = {
  theme: {
    extend: {
      animation: {
        exit: 'fade-out-up 0.3s cubic-bezier(0.65, 0.05, 0.35, 1) forwards',
        enter: 'fade-in-up 0.6s cubic-bezier(0.65, 0.05, 0.35, 1) forwards'
      },
      keyframes: {
        'fade-out-up': {/* … */},
        'fade-in-up': {/* … */}
      }
    }
  },

  plugins: [
    plugin(function ({ addVariant }) {
      addVariant('turn-exit', 'html.turn-exit &')
      addVariant('turn-enter', 'html.turn-enter &')
    })
  ]
}
```

然后在您的 HTML 中:

```html
<main data-turn-exit="turn-exit:animate-exit" data-turn-enter="turn-enter:animate-enter">
  <!-- … -->
</main>
```

## 残疾动画

添加 `data-turn="false"` 页:1 `<body>` 从该页面中选择退出动画.

(这目前相当基本,但受"涡轮事件"中可获得的信息的限制. 希望是临时的,如果 [`turbo:visit` 事件发生在启动要素上](https://github.com/hotwired/turbo/pull/750). ) (中文(简体) )

## 提示( T)

### 1\. 动能变化

避免整个动画 `body`. 动画应当针对在导航上发生变化的元素. 所以,不要动画 持久性头,而是动画 `main` 元素或仅其中的面板/卡.

### 2\. 巢穴

嵌入动画元素会引起人们的注意并给屏幕带来生命. 添加 `data-turn-exit`编号 :`data-turn-enter` 属性,指动画容器内的标题和关键图像等元素。 复合动画效果意味着它们会更快地退出,并比其他元素更慢地进入. 例如:

```html
<main data-turn-exit data-turn-enter>
  <h1 data-turn-exit data-turn-enter>Hello, world!</h1>
</main>
```

### 3.优化动画

跳出动画可以使用 `will-change` CSS财产. 转动增加一个 `turn-before-exit` 分类到 HTML 元素,然后添加退出类。 这为将即将发生的更改通知浏览器提供了机会. 例如,默认 `turn.css` 执行下列规定:

```css
html.turn-before-exit [data-turn-exit],
html.turn-exit [data-turn-exit] {
  will-change: transform, opacity;
}
```

### 4\. 装入自旋器

在慢请求上退出动画可以让用户留下空白屏幕. 改进退出动画后短时间出现的加载自旋器的经验. 例如,如果您的出局动画需要600ms,请添加一个自该后开始出现700ms的自旋器 `transition-delay`。这个旋转器可以永久生活在 `body` 并且只有在 `turn-exit` 应用类:

```css
.spinner {
  position: fixed;
  top: 15%;
  left: 50%;
  transform: translateX(-50%);
  opacity: 0;
  transition: opacity 100ms;
}
html.turn-exit .spinner {
  opacity: 1;
  transition-delay: 700ms
}
```

## 没看到动画吗?

检查您的设备偏好, 以查看您是否请求减少运动 。 转动只会在 `prefers-reduced-motion` 媒体查询不匹配 `reduce`。 。 。 .

## 怎么会这样?

在这样合适的时间转动增加出场并进入类:

1.  打开 `turbo:visit` 添加退出类别
2.  暂停 `turbo:before-render` _(等待退出动画完成后再恢复)_
3.  打开 `turbo:render`,删除退出类并添加输入类
4.  打开 `turbo:load`,在删除输入类之前等待输入动画完成

## 贷项

默认淡出/ 出动画 [乔恩·亚布隆斯基](https://jonyablonski.com/)是因为 [人道设计](https://humanebydesign.com/)。 。 。 .

## 许可证

版权:"2021+多姆·克莉丝蒂"并被MIT许可发行.

## 常见问题

### @domchristie/turn 是什么？

Turbo Drive apps中的动画页面转换\.

### 如何安装 @domchristie/turn？

在项目目录运行 npm install @domchristie/turn，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@hotwired/turbo（^7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @domchristie/turn 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/domchristie\_\_turn 是否存在。

### @domchristie/turn 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @domchristie/turn 可以商用吗？

@domchristie/turn 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @domchristie/turn 的下载量有多少？

根据 npm 官方下载统计，@domchristie/turn 在 2026/10/13 – 2026/11/11 这 30 天内被下载 8,282 次，日均约 276 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @domchristie/turn 还在维护吗？

最新版本 3\.1\.1 发布于 2023/09/20（3 年前）；至今共发布 17 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。