@embedpdf/plugin-stage

中文文档
3.2.0发布于 2026/11/12Apache-2.0TypeScriptESM + CJS近 30 天下载 6.6万

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

中文使用文档
文档目录8 节
  1. 相机:一个心理模型
  2. arrivalAlign ——通航地
  3. zoomAlign ——何等无焦放大相
  4. anchorAlign ——什么活下来的重构
  5. viewRotation ——旋转视图,不是文档
  6. 食谱
  7. 卷轴合同——卷轴条,小相机,"%读"
  8. 这些设置从未触及

@embedpdf/plugin-阶段

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

相机:一个心理模型

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

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

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

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

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 语义,作为默认. )

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

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。 。 。 .

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 选项,所以作者将读取 水平上跟他们看到的完全一样.

食谱

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

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

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

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

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

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

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

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

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 共发布 27 个版本,首次发布于 2026/08/06;过去 12 个月发布了 27 个版本。

版本发布日期距今
3.2.0latest2026/11/121 天前
3.1.02026/11/094 天前
3.0.02026/11/076 天前
3.0.0-next.23next2026/11/076 天前
3.0.0-next.222026/11/049 天前
3.0.0-next.212026/11/0310 天前

关于 @embedpdf/plugin-stage 的常见问题

@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 和提交记录判断。