# @embedpdf/plugin-stage 中文文档

规范地址：https://npmcn.com/package/%40embedpdf/plugin-stage/

版本：3\.2\.0
npm 元数据更新时间：2026-11-11T23:24:52.838Z
中文译文更新时间：2026-11-13T14:49:48.007Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40embedpdf/plugin-stage
原文对照：https://npmcn.com/package/%40embedpdf/plugin-stage/?lang=original
项目主页：https://github.com/embedpdf/embed-pdf-viewer#readme
源码仓库：https://github.com/embedpdf/embed-pdf-viewer

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

- 包体积（解压后）：793 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-08-05T21:41:57.646Z
- 最新版本发布：2026-11-11T23:24:52.556Z
- 近 30 天下载量：66483（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

舞台插件:一个坐标核心(scroll + Viewport + 缩放 + pan + spread)建于 @embedpdf/core-stage上. 纯意取取;无 DOM.

## 安装

```sh
npm install @embedpdf/plugin-stage
```

也可以使用：`pnpm add @embedpdf/plugin-stage`、`yarn add @embedpdf/plugin-stage`、`bun add @embedpdf/plugin-stage`

## README

# @embedpdf/plugin-阶段

"舞台"是观众的坐标系统 它把页面放入一个场景, 将相机对准它们,然后转动每个卷轴,缩放,调整大小,然后"转到第5页" 进入一个相机移动。 你看到的都是相机,所有你配置的 是一个如何允许相机移动的政策.

## 相机:一个心理模型

**每个相机动作都由它持有的固定物来定义.** 有五种类型 移动,每个都保持 完全一样的东西:

| 你确实.. | 保持固定的状态 | 由 |
| --- | --- | --- |
| 拖动、捏动、 ctrl+ 轮 | 指针下的内容 | 没什么,这就是物理 |
| 单击缩放/ 出放, `zoomTo`,切换到相机宽度 | 视图端口中的焦点 | **`zoomAlign`** |
| 调整容器大小, 旋转一页, 更改扩展 | 你刚才看的地方 | **`anchorAlign`** |
| `goToPage`, (中文(简体) ), `nextPage`编号 :`previousPage`, (中文(简体) ), `resetView` | 什么都没有,新上岸了 | **`arrivalAlign`** |
| 单击大纲条目、搜索点击、 PDF 链接 | 随便你怎么说 | 电话本身,按..`reveal` |

还有一个设置站在桌子外。 当内容轴时 **符合** 页:1 取景口,相机在该轴上没有自由——无处可卷. **`fitAlign`** 说明该情况下的内容所在(默认:居中)。 这是一个 b. 适用于 _每个_ 移动上面,不是自己的一动.

所有四个设置每个轴的词汇都是一样的—— `'start' | 'center' | 'end'`, (中文(简体) ), 加上三个移动策略的视图分数——和 `x`编号 :`y` 独立:

```ts
stagePlugin({
  arrivalAlign: { x: 'start', y: 'start' },
  zoomAlign: { x: 'center', y: 'center' },
  anchorAlign: { x: 'start', y: 'start' },
  fitAlign: { x: 'center', y: 'center' },
});
```

(上面的值是默认值——一种读取文档的感觉. 如果你是这样 想要, 配置什么。 )

## `arrivalAlign` ——通航地

当你 _导航_ (单位:千美元)`goToPage`, (中文(简体) ), `nextPage`, (中文(简体) ), `previousPage`, (中文(简体) ), `resetView`页:1 目标页面在同一地点登陆 **在每个缩放级别** 着陆是 政策,从来没有副作用 如何放大你碰巧是。 每个轴 :

| 数值 | 着陆 |
| --- | --- |
| `'start'` | 读取带有取景端边缘的边冲 (上/ 读起) —— 默认 |
| `'center'` | 页面居中——演示文稿感觉 |
| `'end'` | 远边冲出 |
| `0`– 说吧 –`1` | 此视图分数的页面中心( t)`0.35` qq 浏览器查找栏 |
| `'keep'` | 此轴完全不动 |

着陆夹住文件边缘,所以它们最能做第一 和末页——完全像浏览器.

一个价值值得重新审视: **`x: 'keep'`** - 页面向前移动而不丢失 你的横向位置。 被放大成两栏纸的左栏, `nextPage()` 带您到下一页的左栏。 (这是PDF) `/XYZ null` 语义,作为默认. )

任何单一的导航都可以覆盖设置:

```ts
stage.goToPage(page, { arrivalAlign: { y: 'center' } });
```

## `zoomAlign` ——何等无焦放大相

硬币和克特勒+轮子总是在指针周围放大——这是不可配置的, 因为其他的都觉得破碎了. `zoomAlign` 回答剩余情况: 缩放 **无指针位置** ——工具栏按钮,键盘快捷键, `zoomTo`,在匹配模式之间切换.

默认 `{ x: 'center', y: 'center' }`: 你看到的东西的中间 留在原地 风景在四周膨胀 设定 `y: 'start'` 用于上平稳缩放——第一个 可见行在一切生长在其下方(文本编辑器感觉)时会站住. 数值 : `'start' | 'center' | 'end' |` 分数.

## `anchorAlign` ——什么活下来的重构

当世界在被动相机下重塑时——容器会调整大小,一个页面就是 旋转或删除, 间隙或扩展更改—— 阶段使您继续查看 你刚才在看什么. `anchorAlign` 说 **在风景区** 那个 参考点生命:在变化之前它就在那里被捕获并在那里被恢复 过后.

默认 `{ x: 'start', y: 'start' }` ——浏览器滚动模型:什么的顶端 生长或收缩发生在下面。 这就是为什么一个容器 上面是小的,然后扩展,不会向下推入文档:顶部 保持原地,额外的高度显示更多的页面.

设定 `{ x: 'center', y: 'center' }` 用于画布样式的再框:中间是 被钉住并调整了气球的大小对称性(法格玛的感觉).

## `viewRotation` ——旋转视图,不是文档

Adobe的"旋转视图":如何应用四分之一回转 **每页显示在 此镜头**在每一页的上方 `/Rotate`。 。 。 .

```ts
stage.rotateViewBy(90); // toolbar verb: one quarter-turn clockwise from here
stage.setViewRotation(180); // absolute
stage.getViewRotation(); // 0 | 90 | 180 | 270
stagePlugin({ viewRotation: 90 }); // or start rotated
```

三个属性定义它:

-   **非生灭相.** 没有写给PDF——没有引擎呼叫,没有 登记修订。 保存文档保存已装入的 。 常设理事会 每页旋转为 `plugin-page-edit`是因为 `rotateBy`编号 :`setRotation`; 保留 两个在不同的按钮.
-   **每一个镜头.** 这是一个 `StageSettings` 字段类似 `zoom` 或者说 `layout`,所以请 主取景器在缩略镜保持正上方时旋转——或共享一个 如果你的产品要他们同意的话 设定横镜.
-   **重塑框架.** 改变它 `anchorAlign` 点像任何其他 场景变化(上表中的"旋转一页"行),和相配模式 重新解开相接的脚印.

将内容放入阅读取向的注释工具(印出, 自由文本)反旋转 **共计** 显示旋转 - `/Rotate` + 键 `viewRotation` - 通过其 `upright` 选项,所以作者将读取 水平上跟他们看到的完全一样.

## 食谱

**文件读取** ——默认. 配置无所取.

**演示文稿/施工表** – 每个动作都保留当前工作表 居中;每次到达都会呈现工作表如幻灯片:

```ts
stagePlugin({
  arrivalAlign: { x: 'center', y: 'center' },
  zoomAlign: { x: 'center', y: 'center' },
  anchorAlign: { x: 'center', y: 'center' },
});
```

**放大读取扫描的两栏纸** ——在栏下按住 呼叫,从上方降落3个舒适点:

```ts
stagePlugin({ arrivalAlign: { x: 'keep', y: 0.35 } });
```

“预设”只是你保存和传递的物体 `stagePlugin()` 设置时或 `stage.updateSettings()` 在运行时间。 插件没有命名预设; 那 分类学属于你的产品.

## 卷轴合同——卷轴条,小相机,"%读"

舞台是双重的 **虚拟滚动元素**。 。 。 . `getScrollMetrics()` 项目 摄像头输入原生的 DOM 词汇表 – 每个字段都完全是指什么 表示在一个 `<div>`,在屏幕px。 它住在主机的镜头上 (单位:千美元)`@embedpdf/plugin-stage/contract/host`),相同的运行时能力键入 更宽,因为滚动条是驱动相机的铬:

```ts
import { StageToken } from '@embedpdf/plugin-stage/contract/host';

const stage = kernel.capability(StageToken);
const metrics = stage.getScrollMetrics();
// metrics.scrollTop / metrics.scrollLeft       — where you are
// metrics.scrollHeight / metrics.scrollWidth   — how much there is
// metrics.clientHeight / metrics.clientWidth   — how much you see
// metrics.scrollableY / metrics.scrollableX    — false = nothing to scroll (hide the bar)

stage.scrollTo({ top: 0 }); // Element.scrollTo semantics
stage.scrollBy({ top: metrics.clientHeight * 0.9 }); // page down
```

在反应中, `useScrollMetrics()` 反应读取相同的数字 `<Scrollbar axis="y" />` 从他们那里划出一个土生土长的栏杆 `@embedpdf/react/stage`) (中文(简体) ).

这是整个合同。 滚动条拇指是 `clientHeight / scrollHeight` 轨道,位于 `scrollTop / scrollHeight`;读取进度指标为: `scrollTop / (scrollHeight − clientHeight)`; 微型地图是相同的数字 画得小. 你从来不碰相机数学.

衡量标准来自 **相同的行驶范围 :**这样 滚动条不会对平板块实际上停止的地方产生异议:

-   **缩放** 重塑活动范围——缩放和拇指缩放 像一个更长的文件.
-   **页面流量** 滚动当前项目:栏反映一页(或 当它适合的时候,它就隐藏起来.
-   **合适的轴** 报告 `scrollableX: false` (或 `scrollableY`与 `scrollWidth === clientWidth` ——本地"无酒吧"条件,免费.
-   **拉特** 保持物理状态 : `scrollLeft` 表示区域左侧的偏移 边缘,故意避开DOM的负 --`scrollLeft` 行为.

**无边相取法格玛卷轴条.** 与 `bounded: false` 范围 是内容和您当前视图的结合: 关闭为空画布 财务报告和审定财务报表 `scrollHeight` 渐渐地,拇指向边缘缩出,但拖住 到另一端总是让你穿越内容 当一切 可见,两轴都报告不可滚动,栏杆也消失了.

`scrollTo`编号 :`scrollBy` 默认为 `behavior: 'instant'` (DOM's(DOM's `'auto'`(三); 通过 `'smooth'` 为相机的扭矩。 这个 `scrollBehavior` _设置_ 没有 咨询——它管理导航动词(`goToPage`, (中文(简体) ), `nextPage`),没有滚动.

## 这些设置从未触及

-   **手势.** 潘接住指针 物理,不是政策.
-   **明入道场.** `reveal(page, { rect, zoom, anchor })` 搜索点击, 大纲点击, PDF 目的地—— 携带自己的主机, 总是击败 设置。 裸体 `reveal(page)` 保持最小移动: 它滚动到 需要使页面可见,而不是像素进一步.
-   **保存视图 .** `goToPage(page, { viewpoint })` 完全恢复原样 被俘虏.

## 常见问题

### @embedpdf/plugin-stage 是什么？

舞台插件:一个坐标核心\(scroll \+ Viewport \+ 缩放 \+ pan \+ spread\)建于 @embedpdf/core-stage上\. 纯意取取;无 DOM\.

### 如何安装 @embedpdf/plugin-stage？

在项目目录运行 npm install @embedpdf/plugin-stage，或使用 pnpm add / yarn add / bun add。

### @embedpdf/plugin-stage 支持 TypeScript 吗？

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

### @embedpdf/plugin-stage 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @embedpdf/plugin-stage 可以商用吗？

@embedpdf/plugin-stage 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @embedpdf/plugin-stage 的下载量有多少？

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

### @embedpdf/plugin-stage 还在维护吗？

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