pypdf 查看器首选项Viewer Preferences完全指南创建、读取与校验【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf本文围绕 pypdf 的查看器首选项Viewer Preferences功能展开说明如何在写入 PDF 时通过PdfWriter.create_viewer_preferences()控制阅读器/打印器行为如隐藏工具栏、双面打印、打印缩放等以及如何通过PdfReader.viewer_preferences读取已有 PDF 中的设置。读完本文你将掌握/ViewerPreferences字典的完整属性映射、合法取值与校验规则并能直接套用可运行的示例代码。什么是查看器首选项查看器首选项是 PDF 文档目录document catalog中一个可选的/ViewerPreferences字典用于指定阅读器打开文档时的初始显示与打印行为其语义定义于 PDF 1.7 规范 第 12.2 节对应 PDF 2.0 参考手册的 Table 147 等条目。典型用途包括控制窗口外观隐藏工具栏、菜单栏、窗口 UI控制页面布局窗口适配、居中、是否显示文档标题控制非全屏模式、阅读方向控制打印行为打印缩放、双面打印、打印页码范围、份数等。关键前提/ViewerPreferences字典默认并不存在。写入端必须先调用PdfWriter.create_viewer_preferences()创建它之后才能通过writer.viewer_preferences属性赋值读取端如果 PDF 中不存在该字典PdfReader.viewer_preferences属性会返回None。完整示例从零创建一个带查看器首选项的 PDF以下示例来自官方文档 docs/user/viewer-preferences.md完整覆盖了 pypdf 支持的全部查看器首选项属性。注意赋值时使用的名称如/HideToolbar、/UseNone是 PDF 文件格式层面的名称Name 对象以斜杠开头pypdf 保留这些名称便于开发者对照 PDF 规范检索from pypdf import PdfWriter from pypdf.generic import ArrayObject, NumberObject writer PdfWriter() # 创建 /ViewerPreferences 字典必须显式调用字典默认不存在 writer.create_viewer_preferences() # --- 窗口外观布尔型首选项 --- # /HideToolbar隐藏阅读器的工具栏 writer.viewer_preferences.hide_toolbar True # /HideMenubar隐藏阅读器的菜单栏 writer.viewer_preferences.hide_menubar True # /HideWindowUI隐藏窗口中的用户界面元素如滚动条 writer.viewer_preferences.hide_windowui True # /FitWindow打开文档时窗口适配页面 writer.viewer_preferences.fit_window True # /CenterWindow打开文档时窗口居中 writer.viewer_preferences.center_window True # /DisplayDocTitle窗口标题栏显示文档标题而非文件名 writer.viewer_preferences.display_doctitle True # --- 非全屏页面模式Name 型首选项 --- # /NonFullScreenPageMode定义全屏退出后的页面布局 writer.viewer_preferences.non_fullscreen_pagemode /UseNone # 默认值无额外面板 writer.viewer_preferences.non_fullscreen_pagemode /UseOutlines # 显示书签/大纲 writer.viewer_preferences.non_fullscreen_pagemode /UseThumbs # 显示缩略图 writer.viewer_preferences.non_fullscreen_pagemode /UseOC # 显示可选内容图层面板 # --- 阅读方向Name 型首选项 --- # /Direction页面文字阅读顺序 writer.viewer_preferences.direction /L2R # 默认值从左到右 writer.viewer_preferences.direction /R2L # 从右到左 # --- 页面边界框选择Name 型首选项 --- # 合法取值均为页面边界框名称/MediaBox /CropBox /BleedBox /TrimBox /ArtBox # /ViewArea页面显示区域 writer.viewer_preferences.view_area /CropBox # /ViewClip页面显示时的裁剪区域 writer.viewer_preferences.view_clip /CropBox # /PrintArea打印时使用的页面区域 writer.viewer_preferences.print_area /CropBox # /PrintClip打印时裁剪区域 writer.viewer_preferences.print_clip /CropBox # --- 打印缩放Name 型首选项 --- # /PrintScaling打印时的缩放方式 writer.viewer_preferences.print_scaling /None # 禁止缩放 writer.viewer_preferences.print_scaling /AppDefault # 按应用默认值PDF 规范默认 # --- 双面打印Name 型首选项 --- # /Duplex双面打印模式 writer.viewer_preferences.duplex /Simplex # 单面 writer.viewer_preferences.duplex /DuplexFlipShortEdge # 双面沿短边翻页 writer.viewer_preferences.duplex /DuplexFlipLongEdge # 双面沿长边翻页 # --- 其余布尔 / 数组 / 整数型首选项 --- # /PickTrayByPDFSize按页面尺寸选择进纸盒 writer.viewer_preferences.pick_tray_by_pdfsize True # /PrintPageRange打印页码范围须为“首尾成对”的数组 writer.viewer_preferences.print_pagerange ArrayObject( [NumberObject(1), NumberObject(10), NumberObject(20), NumberObject(30)] ) # /NumCopies打印份数 writer.viewer_preferences.num_copies 2 # 添加若干页面并写出 for i in range(40): writer.add_blank_page(10, 10) writer.write(out.pdf)运行后生成的out.pdf打开时阅读器将隐藏工具栏与菜单栏、窗口适配并居中、显示文档标题同时携带规定的打印行为不缩放、双面短边翻页、仅打印 1–10 与 20–30 页、2 份。属性与 PDF 键的完整对照表所有属性定义于 pypdf/generic/_viewerpref.py 的ViewerPreferences类继承自DictionaryObject。下表汇总了每个 Python 属性对应的 PDF 字典键、类型及合法取值Python 属性PDF 键类型合法取值 / 说明hide_toolbar/HideToolbarbool默认Falsehide_menubar/HideMenubarbool默认Falsehide_windowui/HideWindowUIbool默认Falsefit_window/FitWindowbool默认Falsecenter_window/CenterWindowbool默认Falsedisplay_doctitle/DisplayDocTitlebool默认Falsenon_fullscreen_pagemode/NonFullScreenPageModeName/UseNone默认、/UseOutlines、/UseThumbs、/UseOCdirection/DirectionName/L2R默认、/R2Lview_area/ViewAreaName/MediaBox、/CropBox、/BleedBox、/TrimBox、/ArtBoxview_clip/ViewClipName同上边界框名print_area/PrintAreaName同上边界框名print_clip/PrintClipName同上边界框名print_scaling/PrintScalingName/None、/AppDefaultduplex/DuplexName/Simplex、/DuplexFlipShortEdge、/DuplexFlipLongEdgepick_tray_by_pdfsize/PickTrayByPDFSizebool无默认值print_pagerange/PrintPageRangeArray页面“首尾成对”的整数数组长度必须为偶数num_copies/NumCopiesint非负整数 0enforce/EnforceArray需要强制执行的查看器首选项名称数组五个边界框名称集中定义在ViewerPreferences模块顶部的BOX_NAMES列表中其常量值来自 pypdf/constants.py 的PageAttributes/MediaBox、/CropBox、/BleedBox、/TrimBox、/ArtBox见 L204–L208。取值校验与默认值源码级说明ViewerPreferences的属性并非逐一手写而是在__new__中通过_add_prop_bool、_add_prop_name、_add_prop_arr、_add_prop_int四个工厂函数动态生成的见 pypdf/generic/_viewerpref.py。从源码可以确认以下校验规则Name 型属性_set_name值必须以/开头否则抛出ValueError若属性声明了合法取值列表且值不在列表中同样抛出ValueError。例如给non_fullscreen_pagemode赋toto或/toto都会失败而print_scaling只接受/None与/AppDefault。数组型属性_set_arr必须传入ArrayObject否则抛出ValueErrorprint_pagerange的数组长度必须为偶数首尾成对奇数长度会抛出/PrintPageRange holds page pairs, got N entries错误传入None则删除该键。整数型属性_set_intnum_copies为负数时抛出ValueError。布尔型默认值六个窗口外观布尔属性统一使用模块级常量f_obj BooleanObject(False)作为默认值键不存在时读取返回False而pick_tray_by_pdfsize无默认值返回None。这些规则在 tests/test_writer.py 中有对应测试test_print_scaling_accepts_the_spec_valuesL3617与test_print_scaling_rejects_other_valuesL3626、test_box_preferences_accept_the_page_boxesL3640与test_box_preferences_reject_other_namesL3651、test_print_pagerange_rejects_an_odd_lengthL3661与test_print_pagerange_accepts_page_pairsL3673、test_num_copies_rejects_negativeL3684与test_num_copies_accepts_zero_and_aboveL3694。底层实现原理创建与读取两条路径写入端PdfWriter.create_viewer_preferences()定义于 pypdf/_writer.py。它构造一个新的ViewerPreferences()实例将其作为独立对象注册进 writerself._add_object(o)然后挂到文档目录的/ViewerPreferences键常量CatalogAttributes.VIEWER_PREFERENCES下最后返回该实例。因此必须先调用此方法才能通过writer.viewer_preferences访问并赋值未调用时直接访问会得到None。测试 tests/test_writer.py 验证了刚创建时字典为空长度为 0赋一个值后长度为 1。读取端PdfReader.viewer_preferences定义于 pypdf/_doc_common.py从文档目录中查找/ViewerPreferences键不存在时返回None键存在但指向非字典对象时记录logger_warning警告并返回None对应测试 tests/test_doc_common.py 的“malformed entry”场景键存在且是普通字典时会将其包装为ViewerPreferences实例若该对象带有间接引用则同步替换 writer/reader 中解析的对象保证缓存一致性测试 tests/test_doc_common.py 验证了id(reader.viewer_preferences)多次访问一致。create_viewer_preferences()与viewer_preferences读取在PdfWriter与PdfReader上共享同一套属性接口因此写入后可以立即用PdfReader回读验证。测试test_viewer_preferences__reads_a_well_formed_dictionarytests/test_doc_common.py演示了完整的“写入 → 回读”闭环writer.create_viewer_preferences().center_window True写出的 PDF经PdfReader(stream).viewer_preferences读回为{/CenterWindow: True}。修改已有 PDF 中的查看器首选项如果目标 PDF 已包含/ViewerPreferences字典可以先读取再改写。官方文档给出的路径是用PdfReader读取原始文件用PdfWriter(clone_fromreader)克隆随后通过writer.viewer_preferences直接修改已有值。测试 tests/test_writer.py 展示了这一模式克隆后读取v.center_window得到原有值将其改为False后writer.root_object[/ViewerPreferences][/CenterWindow]立即反映新值同时print_area /CropBox等原有设置被完整保留。需要注意的是若原文件不存在该字典writer.viewer_preferences为None此时仍需先调用create_viewer_preferences()。小结/ViewerPreferences字典默认不存在写入端必须先调用PdfWriter.create_viewer_preferences()读取端PdfReader.viewer_preferences在字典缺失时返回None所有属性都带有严格的取值校验Name 值必须以/开头并在白名单内print_pagerange必须为偶数长度的ArrayObjectnum_copies必须非负五个边界框属性view_area、view_clip、print_area、print_clip只接受BOX_NAMES中的五种页面边界框名称布尔型窗口首选项的默认值均为Falsenon_fullscreen_pagemode与direction的默认值分别为/UseNone与/L2R。对照 PDF 规范查阅这些以斜杠开头的名称时可直接在 pypdf 文档中搜索/HideToolbar、/PrintScaling、/Duplex等键名属性和 PDF 键一一对应便于快速定位。【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考