HexaPDF导入文档页面时自定义字体丢失，字符显示方块问题求助

问题根源 #

你遇到的方块显示问题，核心是页面引用的字体资源与target_doc中加载的字体没有建立正确关联：虽然你手动给target_doc加了字体文件，但target_doc.import(page)导入页面时，页面里的字体引用还是指向source_doc中的字体ID，而target_doc里单独加载的字体是新的ID，导致页面无法找到对应字体，最终显示方块。直接保存source_doc正常，是因为所有字体和页面的关联都在同一个文档内，没有引用错位。

两种解决办法 #

办法一：直接修改原文档后保存（最简便） #

如果不需要保留原source_doc，直接在source_doc上完成文本添加后保存即可，完全绕开资源导入的问题：

source_doc = HexaPDF::Document.open("source.pdf")
page = source_doc.pages[0]
canvas = page.canvas(type: :overlay)

font_file = "new_font.ttf"
source_doc.fonts.add(font_file)
canvas.font(font_file)
canvas.text(text, at: [x, y])
canvas.font(FONT_FAMILY, size: FONT_SIZE)

# 直接保存修改后的原文档
source_doc.write(output_file)

办法二：正确导入字体资源到新文档 #

如果必须使用新的target_doc，需要先把source_doc中已关联的字体对象导入到target_doc，再导入页面，确保页面的字体引用能匹配到target_doc中的资源：

target_doc = HexaPDF::Document.new
source_doc = HexaPDF::Document.open("source.pdf")
page = source_doc.pages[0]
canvas = page.canvas(type: :overlay)

font_file = "new_font.ttf"
# 在source_doc中添加字体并获取字体对象
source_font = source_doc.fonts.add(font_file)
canvas.font(source_font)
canvas.text(text, at: [x, y])
canvas.font(FONT_FAMILY, size: FONT_SIZE)

# 关键步骤：先导入source_doc中的字体对象到target_doc
target_doc.import(source_font)
# 再导入页面，此时页面的字体引用会自动映射到target_doc中的对应字体
source_doc.pages.each { |page| target_doc.pages << target_doc.import(page) }

target_doc.write(output_file)

原理说明 #

HexaPDF的import方法处理页面时，只会复制页面的内容结构，但不会自动复制页面依赖的所有资源（比如字体）。只有先手动导入页面依赖的字体对象，才能让导入后的页面在target_doc中找到正确的字体资源，避免字符显示为方块。

内容的提问来源于stack exchange，提问作者alexey_the_cat