# @awesome-reveal/vue 中文文档

规范地址：https://npmcn.com/package/%40awesome-reveal/vue/

版本：1\.0\.0
npm 元数据更新时间：2026-11-03T08:26:30.455Z
中文译文更新时间：2026-11-08T14:49:35.589Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40awesome-reveal/vue
原文对照：https://npmcn.com/package/%40awesome-reveal/vue/?lang=original
项目主页：https://awesome-reveal.dev/
源码仓库：https://github.com/awesome-reveal/awesome-reveal

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

- 包体积（解压后）：29 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：1 个
- peer 依赖：vue ^3\.5\.0
- 首次发布：2026-10-11T13:29:50.926Z
- 最新版本发布：2026-11-03T08:26:29.835Z
- 近 30 天下载量：1774（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

由网络动画API和Intersection Observator所建. Vue的回光相接相接动画.

## 安装

```sh
npm install @awesome-reveal/vue
```

也可以使用：`pnpm add @awesome-reveal/vue`、`yarn add @awesome-reveal/vue`、`bun add @awesome-reveal/vue`

## README

# @awesome-reveal/ veue (音乐)

(原始内容存档于2018-10-21). Reveal-on-scroll 动画为Vue. 环绕内容 `<Reveal>`,或添加 `v-reveal` 到一个元素,当它进入取景口时,它会淡出并滑入其中.

[![npm version](https://badgen.net/npm/v/@awesome-reveal/vue)](https://www.npmjs.com/package/@awesome-reveal/vue) [![License](https://badgen.net/npm/license/@awesome-reveal/vue)](https://github.com/awesome-reveal/awesome-reveal/blob/main/LICENSE)

![Elements fade, slide, scale, blur and rotate in as the page scrolls](https://raw.githubusercontent.com/awesome-reveal/awesome-reveal/main/.github/assets/demo.gif)

-   **很简单.** 两个组成部分,两个指令, 和几个选项.
-   **原产地.** 由Intersection Observer和Web Animations API所建,没有动画库.
-   **SSR准备好了.** 服务器发送的内容会一直被隐藏到它揭示,没有闪光.
-   **无障碍.** 遵循减动偏好,并在焦点上并用平面显示等待内容.
-   **CSP友好报.** 写入无内线样式和无内线脚本.

与Vue 3.5及后作相通.

## 安装

```sh
npm install @awesome-reveal/vue
```

软件包自动加载其样式表。 只有一个 [Astro岛](https://npmcn.com/package/%40awesome-reveal/vue/#readme-stylesheet-setup) 需要一个步骤.

## 快开始

```vue
<script setup lang="ts">
import { Reveal, vReveal } from "@awesome-reveal/vue";
</script>

<template>
  <Reveal><h1>Hello</h1></Reveal>
  <p v-reveal>No wrapper element</p>
</template>
```

内容在进入取景口时会逐渐淡出并向上移动一次.

## 使用量

`Reveal` 财务报告和审定财务报表 `v-reveal` 接受同样的选择. `Reveal` 制作一个 `div` 围绕它的槽 `as` 更改标签. `v-reveal` 动画一个您已经渲染的元素 .

### 选择入口

`from` 设置元素的起始位置。 一边会变淡 有24个px运动 默认是 `"bottom"`。 。 。 .

```vue
<template>
  <Reveal from="left">From the left</Reveal>
  <p v-reveal="{ from: 'right' }">From the right</p>
</template>
```

对于不同的出入口,给出一个起步状态. 元素动画从此状态到中性值:完全不透明,没有偏移,比例为1,不旋转和不模糊. 元素自身对动画属性的价值仅在入场后适用. 启动状态取代默认状态, 所以添加 `opacity: 0` 如果你想要一个淡出.

```vue
<template>
  <Reveal :from="{ opacity: 0 }">Fade only</Reveal>
  <Reveal :from="{ scale: 0.9 }">Scale only</Reveal>
  <Reveal :from="{ opacity: 0, x: '-100%', rotate: '-5deg', blur: 8 }">All together</Reveal>
</template>
```

启动状态有属性 `opacity`, (中文(简体) ), `x`, (中文(简体) ), `y`, (中文(简体) ), `scale`, (中文(简体) ), `rotate` 财务报告和审定财务报表 `blur`数字 `x`, (中文(简体) ), `y` 或者说 `blur` ,数字为 `rotate` 是度数。 一个字符串可以包含带有其单位的 CSS 值.

### 使用自己的键框

全面控制,如放宽习俗,给予土著 [键框](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) 改为 `from`。以元素的休息风格结束它们.

```vue
<template>
  <Reveal
    :keyframes="[
      { opacity: 0, transform: 'scale(.8)', easing: 'cubic-bezier(.34,1.56,.64,1)' },
      { opacity: 1, transform: 'scale(1)' },
    ]"
  >
    Bounce in
  </Reveal>
</template>
```

### 更改时间

```vue
<template>
  <Reveal as="h2" from="left" :duration="800">Title</Reveal>
  <Reveal :from="{ opacity: 0 }" :delay="200">Starts after the title</Reveal>
  <Reveal :threshold="0.5">Reveals when half of it is visible</Reveal>
</template>
```

保留 `delay` 低于约300毫秒。 长时间的延迟让内容在用户快速滚动时出现很晚.

### 打开列表

`Cascade` 财务报告和审定财务报表 `v-cascade` 当容器进入景点时,一个接一个地揭示直系子女. `interval` 设定两个孩子之间的时间,默认时间为80毫秒.

```vue
<script setup lang="ts">
import { Cascade, vCascade } from "@awesome-reveal/vue";
</script>

<template>
  <Cascade as="ul" from="left" :interval="120">
    <li>Fast</li>
    <li>Small</li>
  </Cascade>
  <ol v-cascade>
    <li>Install</li>
    <li>Import</li>
  </ol>
</template>
```

对于长列表,虚拟列表,或比取景端高的网格,使用 `Reveal` 或者说 `v-reveal` 每个项目。 级联同时安排所有的孩子,所以最后一个孩子开始晚或出视.

### 控制显示

`when` 控制你所在的入口. `true` 弹奏它,和 `false` 以无出局动画重置. 与 `null` 或没有值,取景器控制它。 变化 `true` 改为 `null` 保持元素显示.

`when` 不显示或隐藏内容。 与 `when: false`,元素是透明的,但屏幕阅读器读取它,键盘可以将它聚焦. `inert` 不隐藏内容:它只屏蔽焦点、点击和辅助技术。 要隐藏内容, 还设置 `hidden`,或使用 `v-if`数字 :

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Reveal } from "@awesome-reveal/vue";

const open = ref(false);
</script>

<template>
  <button :aria-expanded="open" @click="open = !open">Toggle</button>
  <Reveal :when="open" :hidden="!open" :from="{ opacity: 0 }">Details</Reveal>
</template>
```

准备再次出场 `when` 改为 `false`,然后改为 `true`。 。 。 .

### 在显示处运行代码

`Reveal` 发射 `reveal` 与显示开始时的元素,并给出 `revealed` 切入默认位置. `v-reveal` 接受一个 `onReveal` 选项。 等待入口的结束,等待 `finished` 动画中的承诺:

```vue
<script setup lang="ts">
import { Reveal } from "@awesome-reveal/vue";

function entered(element: Element) {
  Promise.all(element.getAnimations().map((animation) => animation.finished))
    .then(() => element.classList.add("entered"))
    .catch(() => {});
}
</script>

<template>
  <Reveal v-slot="{ revealed }" @reveal="entered">
    {{ revealed ? "Hello" : "Waiting" }}
  </Reveal>
</template>
```

承诺在入口提前停止时拒绝,例如之后 `when: false` 或无所取出. 抓住拒绝。 当没有入口游戏时,例如减少运动时,它立即解决。 它也等待着您自己对元素的动画. 用于级联 `getAnimations({ subtree: true })`因为孩子们有活力 永远重复的动画永远不会完成,所以承诺是不会解决的.

## API 密码

### `<Reveal>`, (中文(简体) ), `<Cascade>`, (中文(简体) ), `v-reveal` 财务报告和审定财务报表 `v-cascade`

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `as` (仅包括构成部分) | `string` | `"div"` | 制成的标签 |
| `from` | `Side | StartState` | `"bottom"` | 入口的侧面或起始状态 |
| `keyframes` | `Keyframe[]` | —— 说 | 原生键框. 你不能一起使用它们 `from` |
| `duration` | `number` | `600` | 入口时间, 以毫秒计 |
| `delay` | `number` | `0` | 入口之间的时间,以毫秒计 |
| `threshold` | `number` | `0` | 可见分数,从0到1,显示元素 |
| `when` | `boolean | null` | —— 说 | `true` 演奏出入口, `false` 再来一次 |
| `onReveal` (仅指示) | `(element) => void` | —— 说 | 运行一次每次曝光, 当它开始 |
| `interval` (只装腔作势) | `number` | `80` | 两个孩子入口之间的时间, 以毫秒计 |

发射部件 `reveal` 与元素,给予 `revealed` ,然后将其他属性传递给已渲染的元素.

### 行为

-   入门一回打. 观察止于出处.
-   这个 `reveal` 事件和 `onReveal` 在没有入口播放时也会运行,例如减少动作或焦点. 之后 `when: false`下一次揭发会再次曝光.
-   更改为 `when` 或者说 `threshold` 立即申请。 下一次披露时将适用对其他选项的更改.
-   `when: false` 期间 `delay` 重新设置出入口,出入口不播放.

## 样式表设置

软件包样式表隐藏服务器提交的内容,直到其披露为止. 软件包模块导入它, 您的捆绑器将其添加到页面中 。 Astro岛需要一步:Astro没有获得一个岛屿的CSS,所以在页面或布局中导入.

```astro
---
import "@awesome-reveal/vue/reveal.css";
---
```

## 服务器侧渲染

服务器标记被隐藏到元素显示为止 。 如果脚本失败,内容会在5秒后显示. 水合物急切地揭示出含量:懒惰的水合物,例如: `hydrateOnVisible()` 或 纳克特 `hydrate-on-visible` 组件,内容可以显示,然后再次隐藏,直到揭示.

## 无障碍

-   与 `prefers-reduced-motion: reduce`,所有的内容立即显示,没有动画。 减少动议比入口优先 `when: false`,所以请 `reveal` 事件和 `onReveal` 别再跑了.
-   在等待元素中的焦点立刻显示,所以键盘用户不会将隐性内容聚焦. 这不适用于 `when: false`。 。 。 .
-   延迟或入口期间的注意力集中,立即完成入口.
-   在脚本加载前,服务器标记显示同时它有焦点.
-   等待内容显示为打印和JavaScript关闭时.
-   隐藏的内容留在无障碍树上. 不要让重要内容依赖于装饰运动.

## 很高兴知道

丝带

-   级联显示时会读取孩子 一个没有动画的显示后添加的孩子.
-   只有直接元素儿童活跃。 文本与子类 `display: contents` 立即显示.
-   不要在级联内直接显示 两个出入口融合在同一元素上.
-   A 类 `<TransitionGroup>` 作为直系儿童,在孩子们身上增加了自己的动画.
-   `delay` 移动整个序列的开始。 这个 `reveal` 事件和 `onReveal` 去拿货柜.

样式表如何隐藏内容

-   服务器标记有 `data-awesome-reveal="hidden"`,或 `data-awesome-reveal="cascade"` 为级联。 一揽子储备 `data-awesome-reveal` 财务报告和审定财务报表 `data-awesome-reveal-attached`。 。 。 .
-   样式表在脚本附着元素前隐藏内容最多为5秒. 如果附件发生后,内容会显示,然后再次隐藏,直到揭示.
-   样式表与 `awesome-reveal-hold` CSS 动画, 取代您自己的 `animation` 在等待中,直到它显现出来。 把自己的动画放在内在元素上. 守火场 `animationstart` 财务报告和审定财务报表 `animationend` 事件,并显示在 `getAnimations()`。 。 。 .
-   内含 `opacity` 与 `!important`,或者你自己的 `animation` 与 `!important`,可以在披露前显示元素.
-   样式表没有达到阴影根 .
-   在没有 `scripting` 媒体功能,如Safari 16,内容在JavaScript关机后5秒后显示.

内容安全政策

软件包没有写 `style` 属性和无内行脚本。 类似政策 `style-src 'self'; script-src 'self'` 当您的捆绑者将软件包 CSS 作为文件发布时, 在生产架构中工作 .

入口详情

这个 `@awesome-reveal/core` README描述了入口如何运作,高而被剪取的内容的门槛,性能和出错. 读吧 [无](https://www.npmjs.com/package/@awesome-reveal/core)。 。 。 .

## 代理技能

软件包包括 `adding-reveal-animations` 技能,它教一个编码代理 API 。 Pnpm可以在你批准后将它链接到你的项目中.

## 许可证

[麻省理工学院](https://github.com/awesome-reveal/awesome-reveal/blob/main/LICENSE)

## 常见问题

### @awesome-reveal/vue 是什么？

由网络动画API和Intersection Observator所建\. Vue的回光相接相接动画\.

### 如何安装 @awesome-reveal/vue？

在项目目录运行 npm install @awesome-reveal/vue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @awesome-reveal/vue 支持 TypeScript 吗？

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

### @awesome-reveal/vue 支持 ESM 还是 CommonJS？

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

### @awesome-reveal/vue 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @awesome-reveal/vue 可以商用吗？

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

### @awesome-reveal/vue 的下载量有多少？

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

### @awesome-reveal/vue 还在维护吗？

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