768 lines
27 KiB
Python
768 lines
27 KiB
Python
#!/usr/bin/env python3
|
||
|
||
from __future__ import annotations
|
||
|
||
from copy import deepcopy
|
||
from pathlib import Path
|
||
from typing import Any, Iterable, Optional
|
||
|
||
from _docx_common import W_NS, input_file, qn
|
||
|
||
|
||
MAX_BLOCKS = 1_000
|
||
MAX_TABLE_CELLS = 20_000
|
||
MAX_IMAGES = 100
|
||
ALIGNMENTS = {
|
||
"left": 0,
|
||
"center": 1,
|
||
"right": 2,
|
||
"justify": 3,
|
||
"distribute": 4,
|
||
}
|
||
VERTICAL_ALIGNMENTS = {
|
||
"top": 0,
|
||
"center": 1,
|
||
"bottom": 3,
|
||
}
|
||
HEX_COLOR_LENGTHS = {6, 8}
|
||
|
||
|
||
def expect_object(value: Any, label: str) -> dict[str, Any]:
|
||
if not isinstance(value, dict):
|
||
raise ValueError(f"{label} 必须是对象")
|
||
return value
|
||
|
||
|
||
def expect_list(value: Any, label: str) -> list[Any]:
|
||
if not isinstance(value, list):
|
||
raise ValueError(f"{label} 必须是数组")
|
||
return value
|
||
|
||
|
||
def color(value: Any, label: str) -> str:
|
||
text = str(value).strip().lstrip("#")
|
||
if len(text) not in HEX_COLOR_LENGTHS:
|
||
raise ValueError(f"{label} 必须是 6 位或 8 位十六进制颜色")
|
||
try:
|
||
int(text, 16)
|
||
except ValueError as exc:
|
||
raise ValueError(f"{label} 必须是十六进制颜色") from exc
|
||
return text.upper()[-6:]
|
||
|
||
|
||
def set_run_font_name(run: Any, name: str, east_asia: Optional[str] = None) -> None:
|
||
run.font.name = name
|
||
fonts = run._element.get_or_add_rPr().get_or_add_rFonts()
|
||
fonts.set(qn("ascii"), name)
|
||
fonts.set(qn("hAnsi"), name)
|
||
fonts.set(qn("eastAsia"), east_asia or name)
|
||
|
||
|
||
def apply_run_style(run: Any, raw_spec: Any, defaults: Optional[dict[str, Any]] = None) -> None:
|
||
from docx.enum.text import WD_UNDERLINE
|
||
from docx.shared import Pt, RGBColor
|
||
|
||
spec = {**(defaults or {}), **expect_object(raw_spec, "run")}
|
||
allowed = {
|
||
"text",
|
||
"bold",
|
||
"italic",
|
||
"underline",
|
||
"strike",
|
||
"color",
|
||
"highlight",
|
||
"font",
|
||
"east_asia_font",
|
||
"size",
|
||
"superscript",
|
||
"subscript",
|
||
"small_caps",
|
||
"all_caps",
|
||
"style",
|
||
"hyperlink",
|
||
}
|
||
unknown = set(spec) - allowed
|
||
if unknown:
|
||
raise ValueError(f"run 包含未知字段：{sorted(unknown)}")
|
||
if "bold" in spec:
|
||
run.bold = bool(spec["bold"])
|
||
if "italic" in spec:
|
||
run.italic = bool(spec["italic"])
|
||
if "underline" in spec:
|
||
underline = spec["underline"]
|
||
if underline in {True, "single"}:
|
||
run.underline = True
|
||
elif underline in {False, None}:
|
||
run.underline = False
|
||
elif underline == "double":
|
||
run.underline = WD_UNDERLINE.DOUBLE
|
||
else:
|
||
raise ValueError("underline 仅支持 true、false、single、double")
|
||
if "strike" in spec:
|
||
run.font.strike = bool(spec["strike"])
|
||
if "color" in spec:
|
||
run.font.color.rgb = RGBColor.from_string(color(spec["color"], "run.color"))
|
||
if "font" in spec or "east_asia_font" in spec:
|
||
font_name = str(spec.get("font", "Arial"))
|
||
set_run_font_name(run, font_name, str(spec.get("east_asia_font", font_name)))
|
||
if "size" in spec:
|
||
size = float(spec["size"])
|
||
if size < 1 or size > 200:
|
||
raise ValueError("run.size 必须在 1 到 200 之间")
|
||
run.font.size = Pt(size)
|
||
for key in ("superscript", "subscript", "small_caps", "all_caps"):
|
||
if key in spec:
|
||
setattr(run.font, key, bool(spec[key]))
|
||
if "style" in spec:
|
||
run.style = str(spec["style"])
|
||
|
||
|
||
def _add_hyperlink(
|
||
paragraph: Any,
|
||
text: str,
|
||
url: str,
|
||
raw_spec: dict[str, Any],
|
||
) -> Any:
|
||
from docx.oxml import OxmlElement
|
||
from docx.opc.constants import RELATIONSHIP_TYPE
|
||
|
||
relationship_id = paragraph.part.relate_to(
|
||
url,
|
||
RELATIONSHIP_TYPE.HYPERLINK,
|
||
is_external=True,
|
||
)
|
||
hyperlink = OxmlElement("w:hyperlink")
|
||
hyperlink.set(f"{{http://schemas.openxmlformats.org/officeDocument/2006/relationships}}id", relationship_id)
|
||
run = paragraph.add_run(text)
|
||
apply_run_style(run, raw_spec)
|
||
run_properties = run._element.get_or_add_rPr()
|
||
if run_properties.find(qn("color")) is None:
|
||
color_element = OxmlElement("w:color")
|
||
color_element.set(qn("val"), "0563C1")
|
||
run_properties.append(color_element)
|
||
if run_properties.find(qn("u")) is None:
|
||
underline = OxmlElement("w:u")
|
||
underline.set(qn("val"), "single")
|
||
run_properties.append(underline)
|
||
paragraph._p.remove(run._element)
|
||
hyperlink.append(run._element)
|
||
paragraph._p.append(hyperlink)
|
||
return run
|
||
|
||
|
||
def add_runs(
|
||
paragraph: Any,
|
||
*,
|
||
text: Optional[str] = None,
|
||
runs: Optional[list[Any]] = None,
|
||
defaults: Optional[dict[str, Any]] = None,
|
||
) -> None:
|
||
if runs is not None and text is not None:
|
||
raise ValueError("段落不能同时提供 text 和 runs")
|
||
if runs is None:
|
||
run = paragraph.add_run("" if text is None else str(text))
|
||
if defaults:
|
||
apply_run_style(run, defaults)
|
||
return
|
||
for index, raw_run in enumerate(runs):
|
||
if isinstance(raw_run, str):
|
||
run = paragraph.add_run(raw_run)
|
||
if defaults:
|
||
apply_run_style(run, defaults)
|
||
continue
|
||
spec = expect_object(raw_run, f"runs[{index}]")
|
||
run_text = str(spec.get("text", ""))
|
||
if spec.get("hyperlink"):
|
||
_add_hyperlink(
|
||
paragraph,
|
||
run_text,
|
||
str(spec["hyperlink"]),
|
||
{**(defaults or {}), **spec},
|
||
)
|
||
else:
|
||
run = paragraph.add_run(run_text)
|
||
apply_run_style(run, spec, defaults)
|
||
|
||
|
||
def apply_paragraph_format(paragraph: Any, raw_spec: Any) -> None:
|
||
from docx.shared import Inches, Pt
|
||
|
||
spec = expect_object(raw_spec, "paragraph")
|
||
if "style" in spec:
|
||
paragraph.style = str(spec["style"])
|
||
if "alignment" in spec:
|
||
alignment = str(spec["alignment"]).lower()
|
||
if alignment not in ALIGNMENTS:
|
||
raise ValueError(f"段落对齐方式无效：{alignment}")
|
||
paragraph.alignment = ALIGNMENTS[alignment]
|
||
paragraph_format = paragraph.paragraph_format
|
||
points = {
|
||
"space_before": "space_before",
|
||
"space_after": "space_after",
|
||
"line_spacing": "line_spacing",
|
||
}
|
||
for source, target in points.items():
|
||
if source in spec:
|
||
value = float(spec[source])
|
||
if value < 0 or value > 500:
|
||
raise ValueError(f"{source} 超出合理范围")
|
||
setattr(paragraph_format, target, Pt(value))
|
||
inches = {
|
||
"left_indent": "left_indent",
|
||
"right_indent": "right_indent",
|
||
"first_line_indent": "first_line_indent",
|
||
}
|
||
for source, target in inches.items():
|
||
if source in spec:
|
||
setattr(paragraph_format, target, Inches(float(spec[source])))
|
||
for key in (
|
||
"keep_with_next",
|
||
"keep_together",
|
||
"page_break_before",
|
||
"widow_control",
|
||
):
|
||
if key in spec:
|
||
setattr(paragraph_format, key, bool(spec[key]))
|
||
|
||
|
||
def add_paragraph_from_spec(
|
||
container: Any,
|
||
raw_spec: Any,
|
||
*,
|
||
style: Optional[str] = None,
|
||
default_run_style: Optional[dict[str, Any]] = None,
|
||
) -> Any:
|
||
spec = (
|
||
{"text": raw_spec}
|
||
if isinstance(raw_spec, str)
|
||
else expect_object(raw_spec, "paragraph")
|
||
)
|
||
paragraph = container.add_paragraph()
|
||
if style:
|
||
paragraph.style = style
|
||
add_runs(
|
||
paragraph,
|
||
text=str(spec["text"]) if "text" in spec else None,
|
||
runs=spec.get("runs"),
|
||
defaults=default_run_style,
|
||
)
|
||
apply_paragraph_format(paragraph, spec)
|
||
return paragraph
|
||
|
||
|
||
def _set_cell_shading(cell: Any, fill: str) -> None:
|
||
from docx.oxml import OxmlElement
|
||
|
||
properties = cell._tc.get_or_add_tcPr()
|
||
existing = properties.find(qn("shd"))
|
||
if existing is not None:
|
||
properties.remove(existing)
|
||
shading = OxmlElement("w:shd")
|
||
shading.set(qn("fill"), color(fill, "table.shading"))
|
||
properties.append(shading)
|
||
|
||
|
||
def _set_cell_width(cell: Any, width_inches: float) -> None:
|
||
from docx.oxml import OxmlElement
|
||
|
||
cell.width = _inches(width_inches)
|
||
properties = cell._tc.get_or_add_tcPr()
|
||
width = properties.find(qn("tcW"))
|
||
if width is None:
|
||
width = OxmlElement("w:tcW")
|
||
properties.append(width)
|
||
width.set(qn("w"), str(round(width_inches * 1440)))
|
||
width.set(qn("type"), "dxa")
|
||
|
||
|
||
def _inches(value: float) -> Any:
|
||
from docx.shared import Inches
|
||
|
||
return Inches(float(value))
|
||
|
||
|
||
def _repeat_table_row(row: Any) -> None:
|
||
from docx.oxml import OxmlElement
|
||
|
||
properties = row._tr.get_or_add_trPr()
|
||
repeat = OxmlElement("w:tblHeader")
|
||
repeat.set(qn("val"), "true")
|
||
properties.append(repeat)
|
||
|
||
|
||
def _prevent_row_split(row: Any) -> None:
|
||
from docx.oxml import OxmlElement
|
||
|
||
properties = row._tr.get_or_add_trPr()
|
||
cannot_split = OxmlElement("w:cantSplit")
|
||
properties.append(cannot_split)
|
||
|
||
|
||
def add_table(container: Any, raw_spec: Any) -> Any:
|
||
from docx.enum.table import WD_CELL_VERTICAL_ALIGNMENT, WD_TABLE_ALIGNMENT
|
||
|
||
spec = expect_object(raw_spec, "table")
|
||
rows = expect_list(spec.get("rows"), "table.rows")
|
||
if not rows:
|
||
raise ValueError("table.rows 不能为空")
|
||
normalized_rows = [expect_list(row, "table.rows[]") for row in rows]
|
||
column_count = max((len(row) for row in normalized_rows), default=0)
|
||
if column_count < 1:
|
||
raise ValueError("表格必须至少有一列")
|
||
if len(rows) * column_count > MAX_TABLE_CELLS:
|
||
raise ValueError("单个表格超过单元格数量限制")
|
||
table = container.add_table(rows=len(rows), cols=column_count)
|
||
table.style = str(spec.get("style", "Table Grid"))
|
||
table.autofit = bool(spec.get("autofit", False))
|
||
alignment = str(spec.get("alignment", "center")).lower()
|
||
if alignment not in {"left", "center", "right"}:
|
||
raise ValueError("table.alignment 仅支持 left、center、right")
|
||
table.alignment = {
|
||
"left": WD_TABLE_ALIGNMENT.LEFT,
|
||
"center": WD_TABLE_ALIGNMENT.CENTER,
|
||
"right": WD_TABLE_ALIGNMENT.RIGHT,
|
||
}[alignment]
|
||
|
||
widths = spec.get("column_widths")
|
||
if widths is not None:
|
||
widths = expect_list(widths, "table.column_widths")
|
||
if len(widths) != column_count:
|
||
raise ValueError("table.column_widths 数量必须等于列数")
|
||
widths = [float(item) for item in widths]
|
||
|
||
header_rows = int(spec.get("header_rows", 1))
|
||
if header_rows < 0 or header_rows > len(rows):
|
||
raise ValueError("table.header_rows 超出范围")
|
||
header_fill = str(spec.get("header_fill", "1F4E78"))
|
||
header_font_color = str(spec.get("header_font_color", "FFFFFF"))
|
||
vertical = str(spec.get("vertical_alignment", "center")).lower()
|
||
if vertical not in VERTICAL_ALIGNMENTS:
|
||
raise ValueError("table.vertical_alignment 无效")
|
||
|
||
for row_index, (row, values) in enumerate(zip(table.rows, normalized_rows)):
|
||
_prevent_row_split(row)
|
||
if row_index < header_rows:
|
||
_repeat_table_row(row)
|
||
for column_index, cell in enumerate(row.cells):
|
||
if widths:
|
||
_set_cell_width(cell, widths[column_index])
|
||
cell.vertical_alignment = {
|
||
0: WD_CELL_VERTICAL_ALIGNMENT.TOP,
|
||
1: WD_CELL_VERTICAL_ALIGNMENT.CENTER,
|
||
3: WD_CELL_VERTICAL_ALIGNMENT.BOTTOM,
|
||
}[VERTICAL_ALIGNMENTS[vertical]]
|
||
if column_index >= len(values):
|
||
continue
|
||
value = values[column_index]
|
||
paragraph = cell.paragraphs[0]
|
||
if isinstance(value, dict):
|
||
value_spec = expect_object(value, "table cell")
|
||
add_runs(
|
||
paragraph,
|
||
text=str(value_spec["text"]) if "text" in value_spec else None,
|
||
runs=value_spec.get("runs"),
|
||
)
|
||
apply_paragraph_format(paragraph, value_spec)
|
||
else:
|
||
add_runs(paragraph, text="" if value is None else str(value))
|
||
if row_index < header_rows:
|
||
_set_cell_shading(cell, header_fill)
|
||
for run in paragraph.runs:
|
||
run.bold = True
|
||
from docx.shared import RGBColor
|
||
|
||
run.font.color.rgb = RGBColor.from_string(
|
||
color(header_font_color, "header_font_color")
|
||
)
|
||
|
||
for raw_merge in spec.get("merges", []):
|
||
merge = expect_object(raw_merge, "table.merges[]")
|
||
start = expect_list(merge.get("start"), "table.merge.start")
|
||
end = expect_list(merge.get("end"), "table.merge.end")
|
||
if len(start) != 2 or len(end) != 2:
|
||
raise ValueError("table merge 坐标必须是 [row, column]")
|
||
table.cell(int(start[0]), int(start[1])).merge(
|
||
table.cell(int(end[0]), int(end[1]))
|
||
)
|
||
return table
|
||
|
||
|
||
def _add_page_number(
|
||
paragraph: Any,
|
||
*,
|
||
prefix: str = "",
|
||
suffix: str = "",
|
||
) -> None:
|
||
from docx.oxml import OxmlElement
|
||
|
||
if prefix:
|
||
paragraph.add_run(prefix)
|
||
run = paragraph.add_run()
|
||
begin = OxmlElement("w:fldChar")
|
||
begin.set(qn("fldCharType"), "begin")
|
||
instruction = OxmlElement("w:instrText")
|
||
instruction.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
|
||
instruction.text = " PAGE "
|
||
separate = OxmlElement("w:fldChar")
|
||
separate.set(qn("fldCharType"), "separate")
|
||
value = OxmlElement("w:t")
|
||
value.text = "1"
|
||
end = OxmlElement("w:fldChar")
|
||
end.set(qn("fldCharType"), "end")
|
||
run._r.extend([begin, instruction, separate, value, end])
|
||
if suffix:
|
||
paragraph.add_run(suffix)
|
||
|
||
|
||
def _add_toc(container: Any, raw_spec: Any) -> Any:
|
||
from docx.oxml import OxmlElement
|
||
|
||
spec = expect_object(raw_spec, "toc")
|
||
levels = str(spec.get("levels", "1-3"))
|
||
if spec.get("title"):
|
||
title = container.add_paragraph(str(spec["title"]))
|
||
title.style = str(spec.get("title_style", "Heading 1"))
|
||
title.paragraph_format.keep_with_next = True
|
||
paragraph = container.add_paragraph()
|
||
run = paragraph.add_run()
|
||
begin = OxmlElement("w:fldChar")
|
||
begin.set(qn("fldCharType"), "begin")
|
||
instruction = OxmlElement("w:instrText")
|
||
instruction.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
|
||
instruction.text = f'TOC \\o "{levels}" \\h \\z \\u'
|
||
separate = OxmlElement("w:fldChar")
|
||
separate.set(qn("fldCharType"), "separate")
|
||
placeholder = OxmlElement("w:t")
|
||
placeholder.text = "目录将在打开文档时更新"
|
||
end = OxmlElement("w:fldChar")
|
||
end.set(qn("fldCharType"), "end")
|
||
run._r.extend([begin, instruction, separate, placeholder, end])
|
||
return paragraph
|
||
|
||
|
||
def _add_horizontal_rule(container: Any, raw_spec: Any) -> Any:
|
||
from docx.oxml import OxmlElement
|
||
|
||
spec = expect_object(raw_spec, "horizontal_rule")
|
||
paragraph = container.add_paragraph()
|
||
properties = paragraph._p.get_or_add_pPr()
|
||
borders = OxmlElement("w:pBdr")
|
||
bottom = OxmlElement("w:bottom")
|
||
bottom.set(qn("val"), str(spec.get("style", "single")))
|
||
bottom.set(qn("sz"), str(int(spec.get("size", 6))))
|
||
bottom.set(qn("space"), str(int(spec.get("space", 1))))
|
||
bottom.set(qn("color"), color(spec.get("color", "808080"), "rule.color"))
|
||
borders.append(bottom)
|
||
properties.append(borders)
|
||
return paragraph
|
||
|
||
|
||
def _add_image(container: Any, raw_spec: Any) -> Any:
|
||
from docx.enum.text import WD_ALIGN_PARAGRAPH
|
||
|
||
spec = expect_object(raw_spec, "image")
|
||
image_path = input_file(
|
||
str(spec.get("path", "")),
|
||
{".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tif", ".tiff"},
|
||
)
|
||
paragraph = container.add_paragraph()
|
||
alignment = str(spec.get("alignment", "center")).lower()
|
||
if alignment not in ALIGNMENTS:
|
||
raise ValueError("image.alignment 无效")
|
||
paragraph.alignment = ALIGNMENTS[alignment]
|
||
run = paragraph.add_run()
|
||
kwargs: dict[str, Any] = {}
|
||
if "width_inches" in spec:
|
||
kwargs["width"] = _inches(float(spec["width_inches"]))
|
||
if "height_inches" in spec:
|
||
kwargs["height"] = _inches(float(spec["height_inches"]))
|
||
run.add_picture(str(image_path), **kwargs)
|
||
if spec.get("caption"):
|
||
caption = container.add_paragraph(str(spec["caption"]))
|
||
caption.style = str(spec.get("caption_style", "Caption"))
|
||
caption.alignment = WD_ALIGN_PARAGRAPH.CENTER
|
||
return paragraph
|
||
|
||
|
||
def _add_section(document: Any, raw_spec: Any) -> Any:
|
||
from docx.enum.section import WD_SECTION
|
||
|
||
spec = expect_object(raw_spec, "section_break")
|
||
break_type = str(spec.get("break_type", "new_page")).lower()
|
||
mapping = {
|
||
"continuous": WD_SECTION.CONTINUOUS,
|
||
"new_column": WD_SECTION.NEW_COLUMN,
|
||
"new_page": WD_SECTION.NEW_PAGE,
|
||
"even_page": WD_SECTION.EVEN_PAGE,
|
||
"odd_page": WD_SECTION.ODD_PAGE,
|
||
}
|
||
if break_type not in mapping:
|
||
raise ValueError(f"section_break.break_type 无效：{break_type}")
|
||
section = document.add_section(mapping[break_type])
|
||
apply_page_settings(section, spec)
|
||
return section
|
||
|
||
|
||
def add_blocks(document: Any, container: Any, raw_blocks: Any) -> dict[str, int]:
|
||
from docx.enum.text import WD_BREAK
|
||
|
||
blocks = expect_list(raw_blocks, "blocks")
|
||
if len(blocks) > MAX_BLOCKS:
|
||
raise ValueError(f"blocks 不能超过 {MAX_BLOCKS} 项")
|
||
counts = {
|
||
"paragraphs": 0,
|
||
"tables": 0,
|
||
"images": 0,
|
||
"page_breaks": 0,
|
||
"sections": 0,
|
||
}
|
||
for index, raw_block in enumerate(blocks):
|
||
block = expect_object(raw_block, f"blocks[{index}]")
|
||
kind = str(block.get("type", "paragraph"))
|
||
if kind == "paragraph":
|
||
add_paragraph_from_spec(container, block)
|
||
counts["paragraphs"] += 1
|
||
elif kind == "heading":
|
||
level = int(block.get("level", 1))
|
||
if level < 1 or level > 9:
|
||
raise ValueError("heading.level 必须在 1 到 9 之间")
|
||
paragraph = container.add_paragraph(style=f"Heading {level}")
|
||
add_runs(
|
||
paragraph,
|
||
text=str(block["text"]) if "text" in block else None,
|
||
runs=block.get("runs"),
|
||
)
|
||
apply_paragraph_format(paragraph, block)
|
||
paragraph.paragraph_format.keep_with_next = True
|
||
counts["paragraphs"] += 1
|
||
elif kind in {"bullet_list", "numbered_list"}:
|
||
items = expect_list(block.get("items"), f"{kind}.items")
|
||
base_style = "List Bullet" if kind == "bullet_list" else "List Number"
|
||
level = int(block.get("level", 0))
|
||
style = base_style if level == 0 else f"{base_style} {min(level + 1, 3)}"
|
||
for item in items:
|
||
add_paragraph_from_spec(container, item, style=style)
|
||
counts["paragraphs"] += 1
|
||
elif kind == "table":
|
||
add_table(container, block)
|
||
counts["tables"] += 1
|
||
elif kind == "image":
|
||
if counts["images"] >= MAX_IMAGES:
|
||
raise ValueError(f"图片数量不能超过 {MAX_IMAGES}")
|
||
_add_image(container, block)
|
||
counts["images"] += 1
|
||
counts["paragraphs"] += 1
|
||
elif kind == "page_break":
|
||
paragraph = container.add_paragraph()
|
||
paragraph.add_run().add_break(WD_BREAK.PAGE)
|
||
counts["page_breaks"] += 1
|
||
counts["paragraphs"] += 1
|
||
elif kind == "horizontal_rule":
|
||
_add_horizontal_rule(container, block)
|
||
counts["paragraphs"] += 1
|
||
elif kind == "toc":
|
||
_add_toc(container, block)
|
||
counts["paragraphs"] += 1
|
||
elif kind == "section_break":
|
||
if container is not document:
|
||
raise ValueError("页眉或页脚中不能添加 section_break")
|
||
_add_section(document, block)
|
||
counts["sections"] += 1
|
||
elif kind == "spacer":
|
||
paragraph = container.add_paragraph()
|
||
paragraph.paragraph_format.space_after = _points(
|
||
float(block.get("points", 6))
|
||
)
|
||
counts["paragraphs"] += 1
|
||
else:
|
||
raise ValueError(f"不支持的 block.type：{kind}")
|
||
return counts
|
||
|
||
|
||
def _points(value: float) -> Any:
|
||
from docx.shared import Pt
|
||
|
||
return Pt(value)
|
||
|
||
|
||
def apply_page_settings(section: Any, raw_spec: Any) -> None:
|
||
from docx.enum.section import WD_ORIENT
|
||
from docx.shared import Cm, Inches, Mm
|
||
|
||
spec = expect_object(raw_spec, "page")
|
||
size = str(spec.get("size", "A4")).upper()
|
||
if size == "A4":
|
||
width, height = Mm(210), Mm(297)
|
||
elif size == "LETTER":
|
||
width, height = Inches(8.5), Inches(11)
|
||
elif size == "LEGAL":
|
||
width, height = Inches(8.5), Inches(14)
|
||
else:
|
||
if "width_inches" not in spec or "height_inches" not in spec:
|
||
raise ValueError("自定义纸张必须提供 width_inches 和 height_inches")
|
||
width = Inches(float(spec["width_inches"]))
|
||
height = Inches(float(spec["height_inches"]))
|
||
orientation = str(spec.get("orientation", "portrait")).lower()
|
||
if orientation not in {"portrait", "landscape"}:
|
||
raise ValueError("page.orientation 只能是 portrait 或 landscape")
|
||
if orientation == "landscape":
|
||
section.orientation = WD_ORIENT.LANDSCAPE
|
||
section.page_width, section.page_height = height, width
|
||
else:
|
||
section.orientation = WD_ORIENT.PORTRAIT
|
||
section.page_width, section.page_height = width, height
|
||
|
||
margin_defaults = {
|
||
"top": 0.85,
|
||
"bottom": 0.85,
|
||
"left": 0.9,
|
||
"right": 0.9,
|
||
"header": 0.35,
|
||
"footer": 0.35,
|
||
}
|
||
margins = expect_object(spec.get("margins", {}), "page.margins")
|
||
for key, default in margin_defaults.items():
|
||
value = float(margins.get(key, default))
|
||
if value < 0 or value > 5:
|
||
raise ValueError(f"page.margins.{key} 超出合理范围")
|
||
target = f"{key}_margin" if key in {"top", "bottom", "left", "right"} else f"{key}_distance"
|
||
setattr(section, target, Inches(value))
|
||
if "gutter" in margins:
|
||
section.gutter = Inches(float(margins["gutter"]))
|
||
|
||
|
||
def apply_document_defaults(document: Any, raw_spec: Any) -> None:
|
||
from docx.shared import Pt, RGBColor
|
||
|
||
spec = expect_object(raw_spec, "default_font")
|
||
name = str(spec.get("name", "Arial"))
|
||
east_asia = str(spec.get("east_asia", "Noto Sans CJK SC"))
|
||
size = float(spec.get("size", 10.5))
|
||
normal = document.styles["Normal"]
|
||
normal.font.name = name
|
||
normal.font.size = Pt(size)
|
||
normal_fonts = normal._element.get_or_add_rPr().get_or_add_rFonts()
|
||
normal_fonts.set(qn("ascii"), name)
|
||
normal_fonts.set(qn("hAnsi"), name)
|
||
normal_fonts.set(qn("eastAsia"), east_asia)
|
||
normal.paragraph_format.space_after = Pt(float(spec.get("space_after", 6)))
|
||
normal.paragraph_format.line_spacing = float(spec.get("line_spacing", 1.15))
|
||
if "color" in spec:
|
||
normal.font.color.rgb = RGBColor.from_string(
|
||
color(spec["color"], "default_font.color")
|
||
)
|
||
|
||
|
||
def apply_named_styles(document: Any, raw_spec: Any) -> None:
|
||
from docx.shared import Pt, RGBColor
|
||
|
||
styles = expect_object(raw_spec, "styles")
|
||
for style_name, raw_style in styles.items():
|
||
if style_name not in document.styles:
|
||
raise ValueError(f"文档样式不存在：{style_name}")
|
||
spec = expect_object(raw_style, f"styles.{style_name}")
|
||
style = document.styles[style_name]
|
||
if "font" in spec:
|
||
font_name = str(spec["font"])
|
||
style.font.name = font_name
|
||
fonts = style._element.get_or_add_rPr().get_or_add_rFonts()
|
||
fonts.set(qn("ascii"), font_name)
|
||
fonts.set(qn("hAnsi"), font_name)
|
||
if "east_asia_font" in spec:
|
||
style._element.get_or_add_rPr().get_or_add_rFonts().set(
|
||
qn("eastAsia"),
|
||
str(spec["east_asia_font"]),
|
||
)
|
||
if "size" in spec:
|
||
style.font.size = Pt(float(spec["size"]))
|
||
if "bold" in spec:
|
||
style.font.bold = bool(spec["bold"])
|
||
if "italic" in spec:
|
||
style.font.italic = bool(spec["italic"])
|
||
if "color" in spec:
|
||
style.font.color.rgb = RGBColor.from_string(
|
||
color(spec["color"], f"styles.{style_name}.color")
|
||
)
|
||
if "space_before" in spec:
|
||
style.paragraph_format.space_before = Pt(float(spec["space_before"]))
|
||
if "space_after" in spec:
|
||
style.paragraph_format.space_after = Pt(float(spec["space_after"]))
|
||
if "keep_with_next" in spec:
|
||
style.paragraph_format.keep_with_next = bool(spec["keep_with_next"])
|
||
|
||
|
||
def apply_core_properties(document: Any, raw_spec: Any) -> None:
|
||
spec = expect_object(raw_spec, "properties")
|
||
allowed = {
|
||
"title",
|
||
"subject",
|
||
"author",
|
||
"last_modified_by",
|
||
"category",
|
||
"keywords",
|
||
"comments",
|
||
"language",
|
||
"identifier",
|
||
"version",
|
||
}
|
||
unknown = set(spec) - allowed
|
||
if unknown:
|
||
raise ValueError(f"properties 包含未知字段：{sorted(unknown)}")
|
||
properties = document.core_properties
|
||
for key, value in spec.items():
|
||
setattr(properties, key, value)
|
||
|
||
|
||
def _clear_container(container: Any) -> None:
|
||
for paragraph in list(container.paragraphs):
|
||
container._element.remove(paragraph._element)
|
||
for table in list(container.tables):
|
||
container._element.remove(table._element)
|
||
|
||
|
||
def apply_header_footer(document: Any, raw_header: Any, raw_footer: Any) -> None:
|
||
for section in document.sections:
|
||
if raw_header is not None:
|
||
spec = expect_object(raw_header, "header")
|
||
_clear_container(section.header)
|
||
if "blocks" in spec:
|
||
add_blocks(document, section.header, spec["blocks"])
|
||
else:
|
||
paragraph = section.header.add_paragraph()
|
||
add_runs(
|
||
paragraph,
|
||
text=str(spec.get("text", "")),
|
||
runs=spec.get("runs"),
|
||
)
|
||
apply_paragraph_format(paragraph, spec)
|
||
if raw_footer is not None:
|
||
spec = expect_object(raw_footer, "footer")
|
||
_clear_container(section.footer)
|
||
if "blocks" in spec:
|
||
add_blocks(document, section.footer, spec["blocks"])
|
||
else:
|
||
paragraph = section.footer.add_paragraph()
|
||
add_runs(
|
||
paragraph,
|
||
text=str(spec.get("text", "")),
|
||
runs=spec.get("runs"),
|
||
)
|
||
apply_paragraph_format(paragraph, spec)
|
||
if spec.get("page_number"):
|
||
_add_page_number(
|
||
paragraph,
|
||
prefix=str(spec.get("page_number_prefix", "")),
|
||
suffix=str(spec.get("page_number_suffix", "")),
|
||
)
|
||
|
||
|
||
def set_update_fields(document: Any) -> None:
|
||
from docx.oxml import OxmlElement
|
||
|
||
settings = document.settings._element
|
||
existing = settings.find(qn("updateFields"))
|
||
if existing is None:
|
||
existing = OxmlElement("w:updateFields")
|
||
settings.append(existing)
|
||
existing.set(qn("val"), "true")
|