如何在 TypeScript 中处理图像和图形

本指南展示了如何使用 Aspose.PDF FOSS for TypeScript 在 PDF 页面上放置图像和矢量图形。Page.AddImage() 嵌入光栅字节，Page.Graphics() 返回一个用于形状绘制的 PageGraphics，Document.OptionalContent 将二者分组为可切换的层。它需要 Node.js 22 或更高版本。

分步指南

步骤 1：安装软件包

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

通过在新的 TypeScript 文件中导入 Document 类来验证安装——一旦软件包安装完成，此行应能够无错误解析：

import { Document } from '@asposefoss/pdf';

步骤 2：导入所需的类

导入 Document 以打开文件；AddImage()、Graphics() 和 AddBarcode() 直接在它返回的 Page 实例上调用：

import { Document } from '@asposefoss/pdf';

步骤 3：嵌入光栅图像

Page.AddImage(data, rect, opts) 将 JPEG 或 PNG 字节放入一个边界 rect 中，并按比例缩放以适配：

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

const imgW = 300;
const imgH = 237; // aspect preserved from a 1280x1014 source
page.AddImage(imageBytes, [150, 400, 150 + imgW, 400 + imgH]);

步骤 4：绘制矢量图形

Page.Graphics() 返回一个 PageGraphics，该对象会缓冲绘图调用，直到 apply() 提交它们。链式调用 setStrokeColor()、setFillColor()、setLineWidth()，以及诸如 rect()、circle()、drawLine() 等形状方法，然后使用 stroke() / fill() / fillStroke()：

const g = page.Graphics();

g.save()
  .setStrokeColor([0.55, 0.60, 0.75])
  .setLineWidth(1)
  .rect(80, 300, 435, 340)
  .stroke()
  .restore();

g.setFillColor([0.88, 0.91, 0.98])
  .setStrokeColor([0.45, 0.52, 0.75])
  .setLineWidth(1)
  .circle(120, 340, 13)
  .fillStroke();

g.apply();

步骤 5：将图像和图形绑定到可选内容层

doc.OptionalContent.AddLayer(name, opts) 创建一个可以在查看器的图层面板中切换的 Layer。将其作为 layer 传递给 AddImage()，或在 PageGraphics 调用中使用 BeginLayer() / EndLayer() 包装：

const oc = doc.OptionalContent;
const grid = oc.AddLayer('Grid', { visible: false }); // default off
const branding = oc.AddLayer('Branding');

const g2 = page.Graphics();
g2.BeginLayer(grid);
g2.save().setStrokeColor([0.72, 0.76, 0.88]).setLineWidth(0.4).setDash([3, 3]);
g2.drawLine(80, 300, 515, 300);
g2.stroke().restore();
g2.EndLayer();
g2.apply();

page.AddImage(logoBytes, [370, 606, 480, 640], { layer: branding });

步骤 6：添加条形码

Page.AddBarcode(spec, rect, opts) 绘制条形码符号；spec.type 选择符号集，spec.data 是编码负载。类似 AddImage()，它接受一个 layer 选项：

page.AddBarcode({ type: 'code128', data: 'ROOM-204' }, [370, 340, 500, 384], {
  layer: branding,
  text: true, // draw the human-readable payload beneath the symbol
});

常见问题与解决方案

使用绘制的图形 PageGraphics 未显示在页面上。 调用缓冲区直至 apply() 被调用 — 每个 PageGraphics 序列需要匹配的 apply() 在页面保存之前。

图层永远不会出现在查看器的图层面板中。 Confirm AddLayer() 通过…被调用 doc.OptionalContent, 不是作为独立对象创建的 — 必须在文档的可选内容配置中注册图层，才能列出。

图像或条形码会忽略图层的可见性切换。 Only AddImage(), AddBarcode(), 以及被包裹的内容 PageGraphics.BeginLayer() / EndLayer() 通过绑定到图层 /OC — 页面其他基础内容（例如未使用图层选项绘制的纯文本）不受任何图层切换的影响。

Page.AddImage() 会扭曲图像。 rect 直接设置放置的宽度和高度 — 如果图像不应拉伸，请先根据源图像自身的宽高比计算。

常见问题

图层可以默认隐藏吗？

是的 — 将 { visible: false } 传递给 OptionalContent.AddLayer()。

一个图层可以嵌套在另一个图层下吗？

是的 — 在调用 AddLayer() 时传递 { parent: someLayer }，以在图层面板的 /D /Order 中将新图层嵌套在已有图层下。

`Page.AddImage()` 接受哪些图像格式？

JPEG 和 PNG 光栅字节。

使用 `PageGraphics` 绘图是否支持透明度和虚线？

是的 — setOpacity(alpha) 设置填充/描边的 alpha，setDash(pattern, phase) 设置虚线模式；两者都可像其他 PageGraphics 设置器一样链式调用。