# @awesome-reveal/core 中文文档

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

版本：1\.0\.0
npm 元数据更新时间：2026-11-03T08:23:10.719Z
中文译文更新时间：2026-11-07T09:02:54.193Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：39 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：0 个
- 首次发布：2026-10-11T09:56:19.949Z
- 最新版本发布：2026-11-03T08:23:10.383Z
- 近 30 天下载量：2466（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

网络动画 API 与 Intersection Observator 和 Intersections 相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相.

## 安装

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

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

## README

# @ awesoome-reveal/ 核心

平原JavaScript中的回光相接动画. 给一个选择器,元素在进入取景口时会淡出并滑入.

[![npm version](https://badgen.net/npm/v/@awesome-reveal/core)](https://www.npmjs.com/package/@awesome-reveal/core) [![License](https://badgen.net/npm/license/@awesome-reveal/core)](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)

-   **小一点.** 不足 2 kB gziped, 没有依赖性和样式表 .
-   **原产地.** 由互通观察员和网络动画API所建.
-   **无障碍.** 遵循减动偏好,并在焦点上并用平面显示等待内容.
-   **CSP友好报.** 写出无内线样式,因此它与严格的内容安全政策相配合.

你使用React,Vue还是Astro? 使用 [`@awesome-reveal/react`](https://www.npmjs.com/package/@awesome-reveal/react), (中文(简体) ), [`@awesome-reveal/vue`](https://www.npmjs.com/package/@awesome-reveal/vue) 或者说 [`@awesome-reveal/astro`](https://www.npmjs.com/package/@awesome-reveal/astro)。它们也会隐藏服务器所传送的内容,直到它揭示出来.

## 安装

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

## 快开始

```ts
import { cascade, reveal } from "@awesome-reveal/core";

reveal(".card"); // Fade in and move up
reveal(".hero", { from: "left" }); // Fade in from the left
cascade(".features"); // Reveal the children of .features one after the other
```

每个元素都会动画一次,当它进入取景口时.

## 使用量

### 选择入口

`from` 设置元素的起始位置。 一方让一个淡出 和24px运动:

| `from` | 开始偏移 |
| --- | --- |
| `"top"` | y: -24 px (中文(简体) ) |
| `"right"` | x: 24页 |
| `"bottom"` (默认) | y: 24 px (中文(简体) ) |
| `"left"` | x: -24 px (中文(简体) ) |

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

```ts
import { reveal } from "@awesome-reveal/core";

reveal(".caption", { from: { opacity: 0 } }); // Fade only
reveal(".logo", { from: { scale: 0.9 } }); // Scale only
reveal(".card", { from: { opacity: 0, x: "-100%", rotate: "-5deg", blur: "0.5rem" } });
```

启动状态有属性 `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`数字 :

```ts
import { reveal } from "@awesome-reveal/core";

reveal(".logo", {
  keyframes: [
    { opacity: 0, transform: "scale(.8)", easing: "cubic-bezier(.34,1.56,.64,1)" },
    { opacity: 1, transform: "scale(1)" },
  ],
});
```

-   在元素的休息样式下结束键框. 动画在结束后没有保留其最后一个键框.
-   给第一个键框提供明确的值 。 打开的 WebKit 错误([212409 (英语)](https://bugs.webkit.org/show_bug.cgi?id=212409))可以从更早的动画中取出隐含的起动值.
-   以元素本身的值结尾,以中性添加剂键框等结尾 `{ opacity: 0, composite: "add" }`。 。 。 .

### 更改时间

```ts
import { reveal } from "@awesome-reveal/core";

reveal(".hero h1", { from: "left", duration: 800 });
reveal(".hero p", { from: { opacity: 0 }, delay: 200 }); // Starts after the heading
reveal(".chart", { threshold: 0.5 }); // Reveals when half of it is visible
```

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

### 打开列表

`cascade()` 当容器进入取景口时,一个接一个地揭示容器的直接子女。 处于位置的儿童 `index` 开始于 `delay + index * interval` 毫秒长.

```ts
import { cascade } from "@awesome-reveal/core";

cascade(".features", { from: { opacity: 0, y: 16 }, interval: 120 });
```

对于长列表,或者比取景口高的网格,使用 `reveal(".item")` 换句话说 级联同时安排所有的孩子,所以最后一个孩子开始晚或出视.

### 清理

每一次通话都返回一个手柄. 打电话 `dispose()` 当您在元素显示前将其删除时, 例如当一个单页应用程序更改路径时 :

```ts
import { reveal } from "@awesome-reveal/core";

const handle = reveal(".card");

// Later, when you remove the cards:
handle.dispose();
```

`dispose()` 停止观察并取消动画,元素回归自己的风格. 在呼叫完成后, 核心不提及元素, 所以你不需要 `dispose()`。 。 。 .

### 手动播放一个入口

有些内容没有到达观察者手中,例如其轨道剪辑的旋转木马滑行. 为了播放它的等待入口,播放它的暂停动画:

```ts
import { reveal } from "@awesome-reveal/core";

reveal(".slide", { from: "left" });

export function playEntrance(slide: Element) {
  for (const animation of slide.getAnimations()) {
    if (animation.playState === "paused") animation.play();
  }
}
```

对于级联,呼叫 `getAnimations({ subtree: true })` 在容器上。 循环在元素上还播放了您自己的暂停动画.

## API 密码

### `reveal(target, options?)`

进入取景口时揭示出每个目标. 回返a `RevealHandle`。 。 。 .

### `cascade(target, options?)`

揭示每个目标的直接元素子,一个接一个地,当目标进入取景口时. 回返a `RevealHandle`。 。 。 .

### 目标

`target` 其中包括:

-   一个元素
-   a CSS 选择器
-   元素可移动
-   类似数组的集合,例如 `children`

Core一次找到目标 和级联孩子 当你调用功能时 它看不到您稍后添加的元素 .

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `from` | `Side | StartState` | `"bottom"` | 入口的侧面或起始状态 |
| `keyframes` | `Keyframe[]` | —— 说 | 原生键框. 你不能一起使用它们 `from` |
| `duration` | `number` | `600` | 入口时间, 以毫秒计 |
| `delay` | `number` | `0` | 入口之间的时间,以毫秒计 |
| `threshold` | `number` | `0` | 可见分数,从0到1,显示元素 |
| `interval` (单位:千美元)`cascade` 仅限) | `number` | `80` | 两个孩子入口之间的时间, 以毫秒计 |

软件包还导出类型 `Side`, (中文(简体) ), `StartState`, (中文(简体) ), `RevealOptions`, (中文(简体) ), `CascadeOptions`, (中文(简体) ), `RevealTarget` 财务报告和审定财务报表 `RevealHandle`编辑 `@awesome-reveal/core/adapter` 条目是用于官方框架软件包。 这不是一个公共API.

## 无障碍

-   与 `prefers-reduced-motion: reduce`,所有内容立即显示,没有动画和延迟。 如果偏好发生变化,核心会取消等待和运行中的动画.
-   在等待元素中的焦点立刻显示,所以键盘用户不会将隐性内容聚焦. 集中在等待级联的容器里 显示它的所有儿童.
-   延迟或入口期间的注意力集中,立即完成入口.
-   等待内容显示为打印 。 印后再相等. 核心用户 `beforeprint` 财务报告和审定财务报表 `afterprint` 事件,所以开发工具中的打印仿真不会显示内容.
-   隐藏的内容留在无障碍树上. 不要让重要内容依赖于装饰运动.

## 服务器侧渲染

您可以导入服务器上的软件包, 但打电话 `reveal()` 财务报告和审定财务报表 `cascade()` 仅在浏览器中。 Core在您的脚本运行前不隐藏内容, 因此服务器发送的内容可以显示, 然后是动画 。 React, Vue 和 Astro 包用样式表隐藏它.

## 很高兴知道

入口如何运作

-   核心电话 `element.animate(keyframes, { duration, delay, fill: "backwards" })` 并暂停动画的开头。 它在元素进入取景口时播放动画. 入口播放一次,观察会停止在出入口. 没有退出动画.
-   入口动画 `opacity` 个人 `translate`, (中文(简体) ), `scale`, (中文(简体) ), `rotate` 财务报告和审定财务报表 `filter` 属性,但只有启动状态设置的属性。 属于你的 `transform` 继续有效,例如 `translate(-50%, -50%)` 中间对话框.
-   在元素等待和进入期间,元素自身对动画属性的值不适用. 为了保持其中的一个值,把它放入一个内元素,或者使用本地键框.
-   在两次通话中不要显示一个要素。 后一出入口取代了前一出入口.
-   您无法改变生成的入口的松动 。 为了不同的放松,使用本地键框.
-   如果您的代码在显示前完成或取消已暂停的动画,元素会在休息时显示,入口则不播放.
-   暂停动画没有完成 。 如果你的代码等待所有 `document.getAnimations()`,跳过动画 `playState === "paused"`。 。 。 .

丝带

-   只有直接元素儿童活跃。 文本节点和更深的后人不会动静.
-   要叠加文本中的单词, 将每个单词包入元素 。 改造需要一个可转换的元素, 所以给内线儿童 `display: inline-block`。 。 。 .
-   负数 `interval` 给负面的延迟, 所以每个后期的孩子开始 进入它的入口.
-   `cascade()` 观察不移动的容器.

门槛和被剪切的内容

-   如果视门太小不能显示 `threshold` 中,元素在进入取景口时会显示。 在一个太小的卷轴容器中,当它离开可见的区域时,它会显示出来. 高元素和长级级联的默认值为0.
-   起始状态 `opacity: 0`,如相相相相相相相相相相相相相相相相相相相相相相相相相等. 其他起始状态和原生键框在它们的第一个键框上等待,因此它们的抵消,缩放和旋转会改变观察者看到的框.
-   如果一个祖先 `overflow` 将元素完全剪辑,元素不显示。 手动播放出入口.

业绩

-   所生成的出入口会运行在堆肥上,因此一个繁忙的主线不会使它口吃. 起始状态 `blur` 例外:铬在主线上运行.
-   在自己的键框中,动画 `opacity`, (中文(简体) ), `transform`, (中文(简体) ), `translate`, (中文(简体) ), `scale` 财务报告和审定财务报表 `rotate` 可能的话 布局属性, 例如 `width`, (中文(简体) ), `top` 或者说 `margin`,使每个相框上有一个布局和一个油漆.
-   Chromium在主线上运行有添加键框的动画.
-   不添加 `will-change` 为了揭发。 浏览器将动画属性当作 `will-change` 已经命名它.

错误

-   `reveal()` 财务报告和审定财务报表 `cascade()` 不丢弃无效的选项。 浏览器验证选项 。 如果它拒绝放松或持续时间,则元素显示时没有动画. 如果拒绝门槛,入口立即出场.
-   无效的 CSS 选择器 `SyntaxError` 联 合 国 `querySelectorAll`。 。 。 .
-   浏览器忽略了密钥框架中无效的 CSS 值, 并且不报告任何信息 .
-   Core从微任务中报告浏览器出错,所以控制台和您的错误跟踪器都会得到. 它在一页上报告每个消息一次. WebKit为不同的放行和持续时间出错给出了相同的消息,因此修正了第一个出错并重新加载页面以查看下一个出错.

内容安全政策

核心写出否 `style` 属性,无内置脚本和 CSS 。 用这个 `element.animate()`,其中内容安全政策不作限制。 类似政策 `style-src 'self'; script-src 'self'` 工作与核心.

## 浏览器支持

Chrome 104, Edge 104, Firefox 74和Safari 14.1 (iOS 14.5) 或后作. 本地密钥框架 `composite` 需要Firefox 80或Safari 16号。 没有互通观察员,入口会同时出场. 无 `Element.animate()`,内容显示没有动画。 在这两种情况下,内容都无法隐藏.

## 代理技能

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

## 许可证

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

## 常见问题

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

网络动画 API 与 Intersection Observator 和 Intersections 相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相\.

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

在项目目录运行 npm install @awesome-reveal/core，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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