# @cardstack/view-transitions 中文文档

规范地址：https://npmcn.com/package/%40cardstack/view-transitions/

版本：0\.2\.0
npm 元数据更新时间：2026-04-17T13:44:24.838Z
中文译文更新时间：2026-11-09T06:41:24.442Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：14.5 kB，9 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：ember-modifier \>= 4\.0\.0
- 首次发布：2025-12-17T18:43:21.993Z
- 最新版本发布：2025-12-17T19:02:21.432Z
- 近 30 天下载量：4687（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

在 Ember apps 中支持视图过渡 API 的公用事业

## 安装

```sh
npm install @cardstack/view-transitions
```

也可以使用：`pnpm add @cardstack/view-transitions`、`yarn add @cardstack/view-transitions`、`bun add @cardstack/view-transitions`

## README

# @ cardstack/ 视图- 过渡

启动本地视图过渡 API 动画的 Ember 工具 .

## 兼容性

-   Ember.js v5.8或以上 (中文(简体) )
-   嵌入或嵌入自动导入 v2

## 安装

```
ember install @cardstack/view-transitions
```

## 使用量

你需要学习 [查看过渡 API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) 来利用这个图书馆。 这个库提供了一些小的公用设施,使得在Ember应用中可以方便地使用 View Transits.

### 可模拟值

```ts
export function animatable<T>(
  initialValue: T,
  opts?: { equals?: (a: T, b: T) => boolean },
): Animatable<T>

export interface Animatable<T> {
  readonly current: T;
  set(newValue: T): void;
}
```

创建一个值,在视图转换时触发它. `current` 拨打时不会立即更新 `set`,改为 `current` 允许在“视图过渡”已经为“视图过渡”绘制“前”状态后更新.

```gts
import { animatable } from '@cardstack/view-transitions';

const expanded = animatable(false);

function toggleExpanded() {
  expanded.set(!expanded.current);
}

<template>
  <button {{on "click" toggleExpanded}}>Toggle</button>
  {{#if expanded.current}}
    <ExpandedContentHere />
  {{else}}
    <CollapsedContentHere />
  {{/if}}
</template>
```

可想象值也必然 `tracked`,用于与Ember其他部分的完全互操作性. 你可以像其他有轨电车状态一样消耗它们,并且会自动进行再接力,附加的奖金是重新接力之前和之后的DOM状态会被浏览器捕获并可以平稳地进行动画.

### 视图转换Name

设置 `view-transition-name` CSS财产. 可用于基于模型ID等程序指定独有名称. 接受任意数量的字符串或数字,并缩合它们形成视图-过渡-名称.

```ts
viewTransitionName: FunctionBasedModifier<{
  Args: {
      Positional: (string | number)[];
  };
  Element: HTMLElement;
}>;
```

```gts
import { viewTransitionName } from '@cardstack/view-transitions';
<template>
  {{#each @products as |product|}}
    <div {{viewTransitionName "product" product.id}}>
      {{product.title}}
    </div>
  {{/each}}
</template>
```

关键是理解 `view-transition-name` CSS属性是,它必须在整个页面上独有. 它既可以在DOM的"旧"和"新"状态中出现,但不能同时出现一次以上. 它控制了哪些元素在视图转换过程中被捕获(思考:"被截取"),以及新旧元素如何关联.

## 演示应用程序

这个repo包含一个演示应用程序. 运行它:

```sh
pnpm install
pnpm start
```

## 捐款

见 [捐款](https://npmcn.com/package/%40cardstack/view-transitions/CONTRIBUTING.md) 详细指南.

## 许可证

本项目根据以下规定获得许可证: [MIT 许可证](https://npmcn.com/package/%40cardstack/view-transitions/LICENSE.md)。 。 。 .

## 常见问题

### @cardstack/view-transitions 是什么？

在 Ember apps 中支持视图过渡 API 的公用事业

### 如何安装 @cardstack/view-transitions？

在项目目录运行 npm install @cardstack/view-transitions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ember-modifier（\>= 4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cardstack/view-transitions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cardstack/view-transitions 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cardstack/view-transitions 可以商用吗？

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

### @cardstack/view-transitions 的下载量有多少？

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

### @cardstack/view-transitions 还在维护吗？

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