使用Python程序化设置PDF文档的阅览偏好_Python

在实际办公与文档分发场景中，pdf 文件的阅读体验直接影响信息传递效率。许多用户在打开 pdf 文件时，经常遇到窗口大小不适配、工具栏遮挡内容、页面布局混乱等问题，需要手动调整窗口和视图设置才能正常阅读。对于需要批量分发的文档（如产品手册、培训资料、合同文件等），如果每个读者都需要自行调整阅读设置，不仅影响用户体验，还可能造成信息展示不一致的问题。

本文将介绍如何使用 python 程序化设置 pdf 文档的阅览偏好，包括窗口显示方式、页面布局模式、工具栏显示状态、缩放比例等核心设置。整个过程可以实现自动化，适用于批量文档处理、企业文档标准化、在线文档发布等多个业务场景。

本文使用的方法需要用到 free spire.pdf for python，可通过 pip 安装：

pip install spire.pdf.free

1. 设置窗口显示属性与界面元素

pdf 文档的窗口显示属性决定了文档打开时的窗口状态，包括窗口位置、标题显示、窗口大小适配以及界面元素的显示控制。

from spire.pdf.common import *
from spire.pdf import *
# 加载 pdf 文档
input_file = "sample.pdf"
output_file = "output/window_preferences.pdf"
doc = pdfdocument(input_file)
# === 窗口显示属性设置 ===
doc.viewerpreferences.centerwindow = true      # 窗口居中显示
doc.viewerpreferences.displaytitle = true      # 显示文档标题
doc.viewerpreferences.fitwindow = true         # 窗口大小适配页面
# doc.viewerpreferences.fitwindow = false      # 不自动适配窗口（与上面二选一）
# === 界面元素显示控制 ===
doc.viewerpreferences.hidemenubar = false      # 显示菜单栏
doc.viewerpreferences.hidetoolbar = false      # 显示工具栏
doc.viewerpreferences.hidewindowui = false     # 显示窗口ui元素（滚动条等）
# doc.viewerpreferences.hidemenubar = true     # 隐藏菜单栏（与上面二选一）
# doc.viewerpreferences.hidetoolbar = true     # 隐藏工具栏（与上面二选一）
# doc.viewerpreferences.hidewindowui = true    # 隐藏窗口ui元素（与上面二选一）
# 保存文档
doc.savetofile(output_file)
doc.close()

效果截图：

说明：

centerwindow：设置为 true 时，文档窗口将在屏幕中央打开。
displaytitle：设置为 true 时，窗口标题栏将显示文档标题而非文件名。
fitwindow：设置为 true 时，窗口大小将自动调整为适配第一页的尺寸。
hidemenubar、hidetoolbar、hidewindowui：分别控制是否隐藏菜单栏、工具栏和窗口ui元素。

应用场景：保留界面元素适合常规文档；隐藏界面元素适合演示或需要最大化阅读区域的场景。

2. 设置页面布局与显示模式

页面布局模式决定了文档打开时的页面显示方式，页面显示模式决定了显示的内容面板（如书签、缩略图等）。

from spire.pdf.common import *
from spire.pdf import *
# 加载 pdf 文档
input_file = "sample.pdf"
output_file = "output/page_layout_mode.pdf"
doc = pdfdocument(input_file)
# === 页面布局模式设置 ===
doc.viewerpreferences.pagelayout = pdfpagelayout.onecolumn  # 单页连续滚动（最常用）
# doc.viewerpreferences.pagelayout = pdfpagelayout.singlepage      # 单页显示
# doc.viewerpreferences.pagelayout = pdfpagelayout.twocolumnleft   # 双页并排（奇数页在左）
# doc.viewerpreferences.pagelayout = pdfpagelayout.twocolumnright  # 双页并排（奇数页在右）
# === 页面显示模式设置 ===
doc.viewerpreferences.pagemode = pdfpagemode.usethumbs      # 显示缩略图面板
# doc.viewerpreferences.pagemode = pdfpagemode.useoc  # 显示可选内容面板
# doc.viewerpreferences.pagemode = pdfpagemode.fullscreen        # 全屏显示模式
# doc.viewerpreferences.pagemode = pdfpagemode.useattachments     # 显示附件面板
# 保存文档
doc.savetofile(output_file)
doc.close()

说明：

页面布局模式：

singlepage：每次只显示一页，适合逐页阅读或打印预览。
onecolumn：页面以单列形式连续排列，支持垂直滚动浏览，是最常用的阅读模式。
twocolumnleft / twocolumnright：双页并排显示，适合书籍、杂志类文档。

页面显示模式：

usebookmarks：显示书签面板，适合包含多级目录结构的技术文档。
usethumbnails：显示页面缩略图，适合页数较多的文档。
fullscreen：全屏模式，适合演示文稿、培训材料。
useattachments：显示附件面板，适合包含补充材料的文档。

3. 设置文档打开时的缩放比例

除了窗口和布局设置，还可以控制文档打开时的缩放比例，确保内容以合适的比例显示。

from spire.pdf.common import *
from spire.pdf import *
# 加载 pdf 文档
input_file = "sample.pdf"
output_file = "output/set_zoom_factor.pdf"
doc = pdfdocument(input_file)
# 获取第一页
page = doc.pages[0]
# 创建 pdf 目标对象
dest = pdfdestination(page)
# === 缩放模式设置（选择一种） ===
# 方式1：设置固定缩放比例
dest.mode = pdfdestinationmode.location
dest.location = pointf(-40.0, -40.0)
dest.zoom = 1.0  # 100% 缩放
# dest.zoom = 0.8  # 80% 缩放
# dest.zoom = 1.5  # 150% 缩放
# 方式2：适应页面宽度（注释掉上面的代码，取消下面注释）
# dest.mode = pdfdestinationmode.fith  # 适应水平宽度
# dest.location = pointf(0.0, 0.0)
# 方式3：适应页面高度
# dest.mode = pdfdestinationmode.fitv  # 适应垂直高度
# dest.location = pointf(0.0, 0.0)
# 创建跳转动作并设置为文档打开动作
goto_action = pdfgotoaction(dest)
doc.afteropenaction = goto_action
# 保存文档
doc.savetofile(output_file)
doc.close()

说明：

pdfdestinationmode.location：以位置模式显示，配合缩放比例使用。
dest.zoom：设置缩放比例，1.0 表示 100%，0.8 表示 80%，1.5 表示 150%。
pdfdestinationmode.fith：页面宽度适配窗口宽度。
pdfdestinationmode.fitv：页面高度适配窗口高度。

4. 获取现有文档的阅览偏好设置

在处理已有文档时，可能需要先了解其当前的阅览偏好设置，再进行针对性调整。

from spire.pdf.common import *
from spire.pdf import *
# 加载 pdf 文档
input_file = "sample.pdf"
output_file = "output/viewer_preferences_info.txt"
doc = pdfdocument()
doc.loadfromfile(input_file)
# 获取阅览偏好对象
viewer = doc.viewerpreferences
# 收集阅览偏好信息
info = []
info.append("=== pdf 文档阅览偏好信息 ===")
info.append("")
info.append("窗口显示设置：")
info.append(f"  窗口居中显示: {viewer.centerwindow}")
info.append(f"  显示文档标题: {viewer.displaytitle}")
info.append(f"  窗口适配页面: {viewer.fitwindow}")
info.append("")
info.append("界面元素显示：")
info.append(f"  隐藏菜单栏: {viewer.hidemenubar}")
info.append(f"  隐藏工具栏: {viewer.hidetoolbar}")
info.append(f"  隐藏窗口ui: {viewer.hidewindowui}")
info.append("")
info.append("页面布局设置：")
info.append(f"  页面布局模式: {viewer.pagelayout}")
info.append(f"  页面显示模式: {viewer.pagemode}")
# 获取缩放比例信息
action = doc.afteropenaction
if action is not none and action.destination is not none:
    zoom_value = action.destination.zoom
    zoom_percent = zoom_value * 100
    info.append("")
    info.append("缩放设置：")
    info.append(f"  文档打开时的缩放比例: {zoom_percent:.1f}%")
else:
    info.append("")
    info.append("缩放设置：")
    info.append("  文档未设置特定的打开缩放比例")
# 保存信息到文本文件
with open(output_file, "w", encoding="utf-8") as f:
    f.write("\n".join(info))
print("阅览偏好信息已保存")

说明：

通过 viewerpreferences 属性可以读取文档的所有阅览偏好设置。
afteropenaction：获取文档打开时执行的动作，用于检查缩放设置。
此方法可用于分析现有文档的设置、批量检查文档是否符合标准。

5. 综合应用：创建标准化的企业文档

在实际应用中，通常需要综合设置多项阅览偏好，创建符合企业标准的文档。

from spire.pdf.common import *
from spire.pdf import *
# 加载 pdf 文档
input_file = "company_manual.pdf"
output_file = "output/standardized_manual.pdf"
doc = pdfdocument(input_file)
# === 窗口显示设置 ===
doc.viewerpreferences.centerwindow = true      # 窗口居中
doc.viewerpreferences.displaytitle = true      # 显示标题
doc.viewerpreferences.fitwindow = false        # 不自动适配窗口
# === 界面元素设置 ===
doc.viewerpreferences.hidemenubar = false      # 显示菜单栏
doc.viewerpreferences.hidetoolbar = false      # 显示工具栏
doc.viewerpreferences.hidewindowui = false     # 显示ui元素
# === 页面布局设置 ===
doc.viewerpreferences.pagelayout = pdfpagelayout.onecolumn  # 单页连续滚动
# === 页面显示模式 ===
doc.viewerpreferences.pagemode = pdfpagemode.useoc  # 显示可选内容面板
# === 缩放设置 ===
page = doc.pages[0]
dest = pdfdestination(page)
dest.mode = pdfdestinationmode.location
dest.location = pointf(-40.0, -40.0)
dest.zoom = 1.0  # 100% 缩放
goto_action = pdfgotoaction(dest)
doc.afteropenaction = goto_action
# 保存标准化后的文档
doc.savetofile(output_file)
doc.close()
print("企业文档标准化设置完成")

说明：

此示例展示了企业文档标准化的典型配置：

窗口居中 + 显示标题：提供专业的视觉体验
保留界面元素：便于用户使用阅读器功能
单页连续滚动 + 书签面板：便于快速导航和阅读
100% 缩放：确保内容清晰显示

此配置适合企业手册、技术文档、培训材料等需要标准化分发的文档。

关键类与方法说明表

为了便于查阅，下面整理本文中主要使用到的类、属性与方法。

类 / 属性 / 方法	说明
`pdfdocument`	表示 pdf 文档对象，用于加载和保存文档
`viewerpreferences`	文档阅览偏好设置对象
`centerwindow`	布尔值，设置窗口是否居中显示
`displaytitle`	布尔值，设置是否在标题栏显示文档标题
`fitwindow`	布尔值，设置窗口是否适配页面大小
`hidemenubar`	布尔值，设置是否隐藏菜单栏
`hidetoolbar`	布尔值，设置是否隐藏工具栏
`hidewindowui`	布尔值，设置是否隐藏窗口ui元素
`pagelayout`	页面布局模式，值为 `pdfpagelayout` 枚举
`pagemode`	页面显示模式，值为 `pdfpagemode` 枚举
`pdfpagelayout.singlepage`	单页显示模式
`pdfpagelayout.onecolumn`	单页连续滚动模式
`pdfpagelayout.twocolumnleft`	双页并排显示模式（奇数页在左）
`pdfpagemode.usebookmarks`	显示书签面板
`pdfpagemode.usethumbnails`	显示缩略图面板
`pdfpagemode.fullscreen`	全屏显示模式
`pdfpagemode.useattachments`	显示附件面板
`pdfdestination`	定义文档目标位置和显示方式
`pdfdestinationmode.location`	以指定位置和缩放比例显示
`pdfdestinationmode.fith`	适配页面宽度
`zoom`	缩放比例，1.0 表示 100%
`pdfgotoaction`	跳转到指定目标的动作
`afteropenaction`	文档打开后执行的动作