# @awesome-reveal/react 中文文档 规范地址：https://npmcn.com/package/%40awesome-reveal/react/ 版本：1\.0\.0 npm 元数据更新时间：2026-11-03T08:25:22.392Z 中文译文更新时间：2026-11-07T09:04:39.674Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40awesome-reveal/react 原文对照：https://npmcn.com/package/%40awesome-reveal/react/?lang=original 项目主页：https://awesome-reveal.dev/ 源码仓库：https://github.com/awesome-reveal/awesome-reveal ## 关键信息（来自 npm 元数据） - 包体积（解压后）：36.7 kB，17 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.19\.0 - 运行依赖：1 个 - peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0 - 首次发布：2026-10-11T09:56:40.936Z - 最新版本发布：2026-11-03T08:25:22.026Z - 近 30 天下载量：2157（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：17（近 12 个月 17 个） ## 中文简介 由网络动画API和Intersection Observator所建. React上回转动画. ## 安装 ```sh npm install @awesome-reveal/react ``` 也可以使用：`pnpm add @awesome-reveal/react`、`yarn add @awesome-reveal/react`、`bun add @awesome-reveal/react` ## README # @ aweosome-reveal/反应 相声回放动画. 环绕内容 ``,当它进入取景口时会逐渐淡出并滑入. [![npm version](https://badgen.net/npm/v/@awesome-reveal/react)](https://www.npmjs.com/package/@awesome-reveal/react) [![License](https://badgen.net/npm/license/@awesome-reveal/react)](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准备好了.** 服务器发送的内容会一直被隐藏到它揭示,没有闪光. 与 Next.js 服务器组件工作 . - **无障碍.** 遵循减动偏好,并在焦点上并用平面显示等待内容. - **CSP友好报.** 写入无内线样式和无内线脚本. 与回放18和19合作. ## 安装 ```sh npm install @awesome-reveal/react ``` 软件包自动加载其样式表。 仅 [两个设置](https://npmcn.com/package/%40awesome-reveal/react/#readme-stylesheet-setup) 需要一个步骤. ## 快开始 ```tsx import { Reveal } from "@awesome-reveal/react"; export const Hero = () => (

Hello

 ); ``` 内容在进入取景口时会逐渐淡出并向上移动一次. ## 使用量 ### 选择入口 `from` 设置元素的起始位置。 一边会变淡 有24个px运动 默认是 `"bottom"`。 。 。 . ```jsx From the left ``` 对于不同的出入口,给出一个起步状态. 元素动画从此状态到中性值:完全不透明,没有偏移,比例为1,不旋转和不模糊. 元素自身对动画属性的价值仅在入场后适用. 启动状态取代默认状态, 所以添加 `opacity: 0` 如果你想要一个淡出. ```jsx Fade only Scale only All together ``` 启动状态有属性 `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`。以元素的休息风格结束它们. ```jsx Bounce in ``` ### 更改时间 ```jsx Title Starts after the title Reveals when half of it is visible ``` 保留 `delay` 低于约300毫秒。 长时间的延迟让内容在用户快速滚动时出现很晚. ### 打开列表 `Cascade` 当它进入景点时, 它的直系子孙一个接一个地显现出来. `interval` 设定两个孩子之间的时间,默认时间为80毫秒. ```tsx import { Cascade } from "@awesome-reveal/react"; export const Features = () => (
  • Fast
  • Small
  • Accessible
    •  ); ``` 对于长列表,虚拟列表,或比取景端高的网格,将每个项目围入 `Reveal` 换句话说 级联同时安排所有的孩子,所以最后一个孩子开始晚或出视. ### 激活你自己的元素 `Reveal` 制作一个 `div` 环绕着孩子 要更改标签, 请使用 `as`。将您自己的元素以无包装方式激活,使用 `useReveal`数字 : ```tsx import { useReveal } from "@awesome-reveal/react"; export function Card() { const { getProps, revealed } = useReveal({ from: "left", threshold: 0.3 }); return
    {revealed ? "Hello" : "Waiting"}
    ; } ``` 展开 `getProps()` 一个DOM元素。 如果你有你自己的话 `ref`,给它 `getProps()`,而钩子将其合并. 对于自定义组件,请通过 `ref` 编辑 `data-awesome-reveal` dOM元素的道具. `useCascade` 连锁店也一样. ### 控制显示 `when` 控制你所在的入口. `true` 弹奏它,和 `false` 以无出局动画重置. 无 `when`风景区控制着它 变化 `true` 以至没有值来显示元素. `when` 不显示或隐藏内容。 与 `when={false}`,元素是透明的,但屏幕阅读器读取它,键盘可以将它聚焦. `inert` 不隐藏内容:它只屏蔽焦点、点击和辅助技术。 要隐藏内容, 还设置 `hidden`,或不使其: ```tsx import { useState } from "react"; import { Reveal } from "@awesome-reveal/react"; export function Details() { const [open, setOpen] = useState(false); return ( <> ); } ``` 准备再次出场 `when` 改为 `false`,然后改为 `true`。 。 。 . ### 在显示处运行代码 `onReveal` 打开时获得元素。 等待入口的结束,等待 `finished` 它的动画承诺: ```tsx import { Reveal } from "@awesome-reveal/react"; export const Card = () => ( Promise.all(element.getAnimations().map((animation) => animation.finished)) .then(() => element.classList.add("entered")) .catch(() => {}) } > Hello ); ``` 承诺在入口提前停止时拒绝,例如之后 `when={false}` 或无所取出. 抓住拒绝。 当没有入口游戏时,例如减少运动时,它立即解决。 它也等待着您自己对元素的动画. 用于级联 `getAnimations({ subtree: true })`因为孩子们有活力 永远重复的动画永远不会完成,所以承诺是不会解决的. ## API 密码 ### `` 财务报告和审定财务报表 `` | Prop | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | `as` | HTML 或 SVG 标签 | `"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` (单位:千美元)`Cascade` 仅限) | `number` | `80` | 两个孩子入口之间的时间, 以毫秒计 | 部件通过其他道具,例如 `className` 财务报告和审定财务报表 `ref`,对已交付元素. ### `useReveal(options?)` 财务报告和审定财务报表 `useCascade(options?)` 他们接受同样的选择,但 `as`它们返回 `getProps(props?)`,它为您的元素提供了道具,以及 `revealed`,它显示元素是否被揭示. ### 行为 - 入门一回打. 观察止于出处. - `onReveal` 在没有入场演奏时也会运行,例如减少运动或焦点. 它运行一次每个披露, 也在严格模式。 之后 `when={false}`下一次揭发会再次运行它. - 更改为 `when` 或者说 `threshold` 立即申请。 下一次披露时将适用对其他选项的更改. - `when={false}` 期间 `delay` 重新设置出入口,出入口不播放. ## 样式表设置 软件包样式表隐藏服务器提交的内容,直到其披露为止. 软件包模块导入它, 您的捆绑器将其添加到页面中 。 两个设置需要一步: - **阿斯特罗岛.** Astro没有获得一个岛屿的CSS. 在页面或布局中导入 : ```astro --- import "@awesome-reveal/react/reveal.css"; --- ``` - **下一页 有网络包装的路由器.** Next.js 不允许软件包导入全局CSS. 将软件包添加到 `transpilePackages`数字 : ```js // next.config.mjs export default { transpilePackages: ["@awesome-reveal/react"] }; ``` Next.js App路由器和涡轮包不需要任何步骤. ## 服务器侧渲染 `Reveal` 财务报告和审定财务报表 `Cascade` 是客户端组件,所以服务器组件可以用可串行道具,也可以用本地键框来制作. 钩子和 `onReveal` 需要客户端组件. 服务器标记被隐藏到元素显示为止 。 如果脚本失败,内容会在5秒后显示. 水合物急切地揭示出内容:如果水合物需要超过5秒,则内容显示,然后再次隐藏到揭示为止. ## 无障碍 - 与 `prefers-reduced-motion: reduce`,所有的内容立即显示,没有动画。 减少动议比入口优先 `when={false}`这样 `onReveal` 不再运行. - 在等待元素中的焦点立刻显示,所以键盘用户不会将隐性内容聚焦. 这不适用于 `when={false}`。 。 。 . - 延迟或入口期间的注意力集中,立即完成入口. - 在脚本加载前,服务器标记显示同时它有焦点. - 等待内容显示为打印和JavaScript关闭时. - 隐藏的内容留在无障碍树上. 不要让重要内容依赖于装饰运动. ## 很高兴知道 丝带 - 级联显示时会读取孩子 一个没有动画的显示后添加的孩子. - 只有直接元素儿童活跃。 文本与子类 `display: contents` 立即显示. - 别放 `Reveal` 直接内置 a `Cascade`。两个出入口合并在同一元素上. - 返回碎片的组件给碎片的每个元素一个孩子. - `delay` 移动整个序列的开始. `onReveal` 去拿货柜. 样式表如何隐藏内容 - 服务器标记有 `data-awesome-reveal="hidden"`,或 `data-awesome-reveal="cascade"` 为级联。 一揽子储备 `data-awesome-reveal` 财务报告和审定财务报表 `data-awesome-reveal-attached`。 。 。 . - 样式表与 `awesome-reveal-hold` CSS 动画, 取代您自己的 `animation` 在等待中,直到它显现出来。 把自己的动画放在内在元素上. 守火场 `animationstart` 财务报告和审定财务报表 `animationend` 事件,并显示在 `getAnimations()`。 。 。 . - 内含 `opacity` 与 `!important`,或者你自己的 `animation` 与 `!important`,可以在披露前显示元素. - 样式表没有达到阴影根 . - 在没有 `scripting` 媒体功能,如Safari 16,内容在JavaScript关机后5秒后显示. - 懒水合物,如Astro `client:visible` 5秒后经常被附着 然后内容显示, 并再次隐藏直到它揭示. 内容安全政策 软件包没有写 `style` 属性和无内行脚本。 类似政策 `style-src 'self'; script-src 'self'` 当您的捆绑者将软件包 CSS 作为文件发布时, 在生产架构中工作 。 Next.js添加了自己的内行脚本,所以它需要一个nice,如Next.js docs所描述. 入口详情 这个 `@awesome-reveal/core` README描述了入口如何运作,高而被剪取的内容的门槛,性能和出错. 读吧 [无](https://www.npmjs.com/package/@awesome-reveal/core)。 。 。 . ## 从 v4 迁移 `react-awesome-reveal` 版本5再导出此包. 升级或安装 `@awesome-reveal/react`然后采取这些步骤: 1. 如果没有其他代码使用"情感",请去掉. 2. 导入 `Reveal` 作为命名导出。 v4 还存在默认导出. 3. 将每个效果组件替换为 `Reveal`数字 : - 为了消退,使用 `from={{ opacity: 0 }}`。 。 。 . - 为方向运动设定 `from` 到元素开始的一侧。 4号 `up` 变成 `from="bottom"`,以及 `down` 变成 `from="top"`。 。 。 . - 对于更复杂的效果,使用本地键框. 4. 替换 `fraction` 与 `threshold`。 。 。 . 5. 删除 `triggerOnce`。在v4中,入口默认每次播放。 现在它演奏一次。 再来一次,准备好 `when` 改为 `false`,然后改为 `true`。 。 。 . 6. 替换 `cascade` 与 `Cascade` 组件。 设定 `interval` 到v4时 `duration * damping`,以毫秒计. 7. 自己写短信 库不分割文本 . 默认持续时间为600 ms,v4使用1000 ms. 一个v4 `` 没有 `keyframes` 从左边输入。 为了保持这个运动,使用 `from={{ opacity: 0, x: "-100%" }}`。 。 。 . `Reveal` 使一个元素围绕它的所有儿童,v4将每个元素的孩子包裹在一个 `div`。 。 。 . ## 代理技能 套件包括编码代理的两种技能. Pnpm可以在你批准后 把它们与你的计划联系起来. - `adding-reveal-animations` 教这个 API. - `migrating-from-v4` 列出 v4 的所有更改. ## 许可证 [麻省理工学院](https://github.com/awesome-reveal/awesome-reveal/blob/main/LICENSE) ## 常见问题 ### @awesome-reveal/react 是什么？ 由网络动画API和Intersection Observator所建\. React上回转动画\. ### 如何安装 @awesome-reveal/react？ 在项目目录运行 npm install @awesome-reveal/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @awesome-reveal/react 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @awesome-reveal/react 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @awesome-reveal/react 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @awesome-reveal/react 可以商用吗？ @awesome-reveal/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @awesome-reveal/react 的下载量有多少？ 根据 npm 官方下载统计，@awesome-reveal/react 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,157 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @awesome-reveal/react 还在维护吗？ 最新版本 1\.0\.0 发布于 2026/11/03（4 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/10/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。