使用fitz库替换PDF文本时触发ValueError错误求助

需求：替换PDF中的指定单词"Férias"为"Vacations"，使用fitz库时出现错误。

原代码 #

import fitz

doc = fitz.open([FILE HERE])
for page in doc:
    areas = page.search_for("Férias")
    print(page)
    for area in areas:
        writer = fitz.TextWriter(page, area)
        writer.write_text("Vacations", fontsize=10, fontname="helv", color=(1, 1, 0))

报错信息 #

ValueError                                Traceback (most recent call last)
~\AppData\Local\Temp\ipykernel_13768\3906041629.py in ?()
      2 for page in doc:
      3     areas = page.search_for("Férias")
      4     print(page)
      5     for area in areas:
----> 6         writer = fitz.TextWriter(page, area)
      7         writer.write_text("Vacations", fontsize=10, fontname="helv", color=(1, 1, 0))
      8 

c:\Users\hh100801\AppData\Local\Programs\Python\Python311\Lib\site-packages\fitz\__init__.py in ?(self, page_rect, opacity, color)
  12983         self.this = mupdf.fz_new_text()
  12984 
  12985         self.opacity = opacity
  12986         self.color = color
> 12987         self.rect = Rect(page_rect)
  12988         self.ctm = Matrix(1, 0, 0, -1, 0, self.rect.height)
  12989         self.ictm = ~self.ctm
  12990         self.last_point = Point()

c:\Users\hh100801\AppData\Local\Programs\Python\Python311\Lib\site-packages\fitz\__init__.py in ?(self, p0, p1, x0, y0, x1, y1, *args)
  10946 
  10947         Explicit keyword args p0, p1, x0, y0, x1, y1 override earlier settings
  10948         if not None.
...
  20513     if p0 is not None:  ret_x0, ret_y0 = get_xy(p0)
  20514     if p1 is not None:  ret_x1, ret_y1 = get_xy(p1)
  20515     if x0 is not None:  ret_x0 = x0

错误原因 #

fitz.TextWriter的第一个参数需要传入页面的矩形区域（page.rect），而非page对象本身。另外，替换文本时需要先覆盖原文字区域，避免新旧文本重叠。

修正后的代码 #

import fitz

# 打开PDF文档
doc = fitz.open("[FILE HERE]")  # 替换为你的PDF文件路径
# 遍历每一页
for page in doc:
    # 搜索目标文本的位置
    areas = page.search_for("Férias")
    for area in areas:
        # 1. 用白色矩形覆盖原文本区域（避免重叠）
        page.draw_rect(area, color=(1, 1, 1), fill=(1, 1, 1), overlay=True)
        # 2. 创建TextWriter，传入页面的矩形区域
        writer = fitz.TextWriter(page.rect)
        # 3. 在原文本位置写入新文本，指定坐标为区域的左上角
        writer.write_text(area.tl, "Vacations", fontsize=10, fontname="helv", color=(0, 0, 0))
        # 4. 将写入的文本应用到页面
        writer.write_text(page)
# 保存修改后的文档
doc.save("modified.pdf")
doc.close()

关键说明 #

• page.draw_rect用白色填充原文本区域，确保原文字被完全覆盖。
• TextWriter初始化时传入page.rect，而非page对象。
• write_text的第一个参数指定文本起始位置（这里用area.tl即区域的左上角，可根据实际排版微调）。
• 最后必须调用writer.write_text(page)将内容渲染到页面，再保存文档。

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