福昕开发者文档中心

打印文档 ​

福昕 PDF SDK（Web）支持通过内置 UI 打印组件或公开的 PDFViewer.print 接口打印当前文档。内置 UI 适合直接使用完整阅读器的场景；如果您需要在自定义业务流程中主动发起打印、控制打印范围或调整打印参数，建议使用 PDFViewer.print。

通过内置 UI 打印 ​

如果您使用 UIExtension 完整阅读器，SDK 已提供 <print:print-dialog> 打印组件。用户可以通过内置工具栏或菜单打开打印对话框，并按界面选项完成打印。

默认打印组件适合大多数桌面浏览器场景。它由 SDK 内部封装打印流程，开发者通常不需要直接处理页面转换或打印任务。

通过 PDFViewer.print 打印 ​

PDFViewer.print 是公开的底层打印接口。该接口会将指定页面内容转换为图像后交给浏览器打印，因此也常用于提升部分浏览器环境下的打印兼容性，例如 iOS Safari。

javascript
const pdfViewer = await pdfui.getPDFViewer();

await pdfViewer.print({
    pages: [0, 1],
    printType: ['page', 'annot'],
    quality: 100,
    showHeaderFooter: false
}, function(message) {
    switch (message.state) {
        case 'start':
            console.log('开始生成页面图像');
            break;
        case 'progress':
            console.log('页面图像已生成', message.pageIndex, message.total);
            break;
        case 'end':
            console.log('完成页面图像生成');
            break;
    }
});

参数说明 ​

参数类型说明默认值
pagesArray<number | object>指定打印页面。传入数字表示页面索引；传入包含 pageIndex 和 rect 的对象时，可打印指定页面区域。[]
printTypeArray<string>打印内容类型，可包含 'page'、'annot'、'stamps'、'form'。['page']
progressProgressComponent | boolean打印进度显示控制。为 true 或不传时显示默认进度；为 false 时不显示；也可传入自定义进度组件。true
qualitynumber打印质量，按百分比计算，有效范围为 100 到 1000。100
showHeaderFooterboolean是否显示页眉页脚。该选项仅在 Chrome、Firefox 和 Chromium Edge 中可用。取自默认打印设置
printerobject自定义打印器对象。一般场景无需传入。undefined

备注：

pages 中的页面索引从 0 开始。例如，0 表示第 1 页。

打印指定页面 ​

javascript
const pdfViewer = await pdfui.getPDFViewer();

await pdfViewer.print({
    pages: [0, 2, 4],
    printType: ['page', 'annot'],
    quality: 100
});

打印指定区域 ​

如果只需要打印页面中的部分区域，可以在 pages 中传入包含 rect 的对象。

javascript
const pdfViewer = await pdfui.getPDFViewer();

await pdfViewer.print({
    pages: [{
        pageIndex: 0,
        rect: {
            x: 100,
            y: 100,
            width: 400,
            height: 300
        }
    }],
    printType: ['page'],
    quality: 200
});

打印当前视图 ​

PDFViewer.printCurrentView() 可打印当前显示区域。需要注意，如果当前显示内容跨越多个页面，该接口不会打印内容。

javascript
const pdfViewer = await pdfui.getPDFViewer();

await pdfViewer.printCurrentView();

自定义进度提示 ​

progress 可以传入自定义进度组件对象。该对象需要提供 show、hide 和 updateProgress 方法。详细信息，参阅 进度条组件

javascript
const customProgress = {
    show() {
        console.log('显示打印进度');
    },
    hide() {
        console.log('隐藏打印进度');
    },
    updateProgress(progress) {
        console.log(`打印进度：${progress.current}/${progress.total}`);
    }
};

await pdfViewer.print({
    pages: [0, 1, 2],
    progress: customProgress,
    quality: 150
});

Image-Based 打印 ​

PDFViewer.print 会通过图像方式完成打印。与默认 UI 打印流程相比，该方式在部分浏览器中兼容性更好，但打印清晰度、内存占用和打印速度可能受到 quality、页数和页面复杂度影响。

如果您使用内置 <print:print-dialog>，可以通过 UI Fragments 为打印组件启用 image-based 打印。例如，只在 iOS Safari 中启用：

javascript
new UIExtension.PDFUI({
    appearance: UIExtension.appearances.adaptive.extend({
        getDefaultFragments() {
            return [{
                target: '@print:print-dialog',
                config: {
                    attrs: {
                        'is-image-based': PDFViewCtrl.DeviceInfo.isIOS && PDFViewCtrl.BrowserInfo.isSafari
                    }
                }
            }];
        }
    })
});

权限限制 ​

打印前，SDK 会检查当前文档是否允许打印。如果文档权限不允许打印，PDFViewer.print 会抛出权限相关错误。

javascript
try {
    await pdfViewer.print({
        pages: [0],
        printType: ['page']
    });
} catch (error) {
    console.error('打印失败', error);
}

注意事项 ​

  • 高质量打印会增加浏览器内存消耗。处理大文档时，建议谨慎设置超过 300 的 quality。
  • showHeaderFooter 仅在 Chrome、Firefox 和 Chromium Edge 中可用。
  • image-based 打印会将页面转换为图像后打印，打印效果可能与默认打印方式存在差异。
  • 如果需要打印注释、图章或表单内容，请在 printType 中明确传入对应类型。
  • 建议在移动端或兼容性要求较高的浏览器环境中充分测试打印效果。