Не просто дивіться на розмір шрифту для заголовків Word: стиль є кращою структурною підказкою

Якщо ви використовуєте сценарій для пакетного вилучення змісту або розділів документів Word, ви можете зіткнутися з пропущеним «заголовком першого рівня» або неправильним визначенням розділу, виділеним жирним шрифтом. Зазвичай це відбувається не тому, що регулярні вирази написані недостатньо добре, а тому, що абзац не має стилю заголовка, наприклад Heading 1, застосованого до нього, але розмір шрифту збільшується вручну, а текст виділено жирним шрифтом. Під час обробки структури документа Word візуальне представлення не дорівнює структурі, і paragraph.style є більш надійною семантичною підказкою.

Вміст, наведений нижче, підходить для розробників та інженерів, відповідальних за автоматизацію документів, пакетний аналіз або перевірку перед перекладом. Приклади в цій статті використовують синтетичні зразки та генеруються в пам’яті для легкого відтворення та розуміння. Код було перевірено з прикладами в ізольованому середовищі, але це не є гарантією всіх реальних файлів або продуктивності продукту. Перед обробкою важливих документів збережіть оригінали та перегляньте їх відповідно до меж і пунктів прийняття в тексті.

Як визначити заголовки Word? Висновок одним реченням

Висновок одним реченням: використовуйте paragraph.style як основну основу для оцінювання назв, а також використовуйте англійські внутрішні назви або таблиці зіставлення, щоб знайти стилі. Не дивіться лише на розмір шрифту та жирний шрифт.

Чому ми повинні використовувати англійські внутрішні імена для пошуку стилів?

python-docx працює з основними файлами WordprocessingML, а не з інтерфейсом програми Word. Незалежно від того, чи є Word користувача китайською, японською чи німецькою, збережені назви вбудованих стилів англійською мовою. Наприклад, «Заголовок 1», який відображається в китайській версії інтерфейсу Word, записується як Heading 1 у XML. Щоб дізнатися про методи зберігання стилів і правила іменування, зверніться до Розуміння стилів - опис концепції python-docx.

Якщо styles['标题 1'] використовується для пошуку в коді, програма безпосередньо викине KeyError. Це одна з поширених підводних каменів під час роботи з багатомовними документами.

Користувальницькі стилі не підпадають під це обмеження, і їхні назви в XML точно такі, як користувач бачить їх в інтерфейсі. Таким чином, під час написання надійної логіки синтаксичного аналізу ви можете побудувати таблицю зіставлення з локалізованих відображуваних імен на внутрішні імена англійською мовою або ви можете вимагати, щоб суб’єкти документів використовували стандартний шаблон.

Приклад синтезу: правильний вихід і крайові випадки

Щоб продемонструвати логіку розпізнавання стилю, побудуємо синтетичний зразок, що містить три типових абзаци:

1. Параграф A: застосовано стиль Heading 1, а текст — «Вступ до глави 1».
2. Абзац B: стиль Normal, але розмір шрифту та жирний шрифт вручну встановлено на 16 пунктів, а текст – «Важливо».
3. Параграф C: застосовано настроюваний стиль MyCustomTitle, а текст — «Опис додатка».

Очікуваний результат: Синтаксичний аналізатор має повернути структурований список лише з абзацами A та C, позначеними як вузли заголовка. Незважаючи на те, що абзац B є візуально помітним, через відсутність семантичного стилю його слід класифікувати як звичайний текст або позначити як «підозрюваний заголовок, який потрібно підтвердити вручну», і не може бути автоматично підвищений до структурного вузла.

Помилка та межа введення: Якщо абзац у документі посилається на стиль, який було видалено, тобто w:pStyle w:val="DeletedStyle" існує в XML, але визначення стилю відсутнє, тоді python-docx звертається до paragraph.style.name може повернути None або викинути виняток. Більш розсудливий підхід полягає в тому, щоб перевірити, чи існує об’єкт стилю, перш ніж отримати до нього доступ, або знизити такі абзаци до обробки звичайного тексту, щоб уникнути переривання всього процесу аналізу.

Зразок конструкції пам'яті та код затвердження стилю

Наведений нижче код показує, як перевірити логіку розпізнавання стилю в контрольованому середовищі. Він використовується для демонстрації використання API та ідей тверджень і не є аналізатором робочого рівня. Під час фактичного використання запустіть його в середовищі, де ви заблокували версію залежностей. Рекомендується python-docx>=0.8.11. Для конкретного використання стилів, будь ласка, зверніться до Робота зі стилями - офіційна документація python-docx.

from docx import Document
from docx.enum.style import WD_STYLE_TYPE
from docx.shared import Pt

def build_sample_doc():
    """构建含混合样式的合成文档，无需外部文件"""
    doc = Document()
    # 标准内置标题
    doc.add_heading('Chapter One', level=1)
    # 视觉像标题但无样式
    p_visual = doc.add_paragraph('Visual Fake Title')
    run = p_visual.runs[0]
    run.bold = True
    run.font.size = Pt(15)  # 使用Pt单位确保API规范
    # 自定义样式
    if 'MyCustomTitle' not in [s.name for s in doc.styles]:
        doc.styles.add_style('MyCustomTitle', WD_STYLE_TYPE.PARAGRAPH)
    doc.add_paragraph('Appendix Note', style='MyCustomTitle')
    return doc

def extract_semantic_headings(doc):
    """仅提取具有明确样式的标题，忽略直接格式化"""
    headings = []
    for para in doc.paragraphs:
        style_name = para.style.name if para.style else None
        # 严格匹配：内置Heading或已知自定义标题样式
        if style_name and (style_name.startswith('Heading ') or style_name == 'MyCustomTitle'):
            headings.append({'text': para.text, 'style': style_name})
    return headings

# 验证逻辑
sample = build_sample_doc()
result = extract_semantic_headings(sample)

assert len(result) == 2, f"期望2个语义标题，实际得到{len(result)}个"
assert result[0]['style'] == 'Heading 1'
assert result[1]['style'] == 'MyCustomTitle'
assert all('Visual Fake' not in item['text'] for item in result)

Цей код явно виключає використання лише атрибутів шрифту для визначення заголовків. assert використовується для підтвердження того, що логіка відповідає очікуванням, але в реальних документах твердження можна замінити механізмами журналювання або збору винятків, щоб полегшити уніфікований перегляд проблем під час пакетної обробки.

Контрольний список приймання та межі перевірки вручну

Автоматичний аналіз не може охопити всі звички верстки. У наведеній нижче таблиці підсумовано рішення щодо обробки для поширених сценаріїв, щоб допомогти командам провести межі між машинною та людською співпрацею.

Зауважте, що ця таблиця призначена для перевірки логіки на рівні демонстрації коду, а наскрізний ефект потрібно оцінювати на основі конкретних типів документів. Наприклад, «застереження про визначення» в юридичному договорі може використовувати окремий стиль і не повинно розглядатися як назва розділу; «Примітка» в технічному посібнику може вимагати спеціального лікування під час перекладу, навіть якщо в ньому використовується Heading 3. У разі зустрічі з такими правилами, пов’язаними з доменом, слід включити процес перевірки вручну.

📊 Основне порівняння

🎯 Який спосіб вам підходить?

Якщо вам потрібно витягти зміст або структуру розділу з Word

Надайте перевагу використанню paragraph.style замість того, щоб покладатися на розмір шрифту та жирний шрифт.

Якщо ви хочете обробляти локалізовані версії документів Word, наприклад китайську та японську

Знайдіть вбудовані стилі за допомогою внутрішніх імен англійською мовою або створіть таблицю зіставлення локалізованих імен із внутрішніми іменами.

Якщо ваш документ написаний декількома людьми і формат неоднаковий

Перегляд вручну зарезервовано для абзаців зі стилем Normal, але які візуально помітні, а інформація про розташування записується.

Якщо ви маєте справу з юридичними контрактами чи технічними посібниками

Спочатку відсортуйте конкретні правила стилю в полі, а потім визначте, які абзаци можна розпізнавати автоматично, а які потребують оцінки вручну.

❓ Часті запитання (FAQ)

1. Чому я не можу безпосередньо використовувати styles['标题 1'], щоб знайти назву?

Оскільки python-docx читає базовий XML, вбудовані стилі зберігаються в XML як англійські імена, наприклад Heading 1. «Заголовок 1», який відображається в китайській версії інтерфейсу Word, викличе KeyError, якщо його використовувати в коді.

2. Якщо абзац має лише великий розмір шрифту та жирний шрифт, чи можна його використовувати як заголовок?

Не рекомендується автоматично використовувати його як назву. Абзацу цього типу бракує семантичного стилю, тому його слід позначити як «підозрюваний заголовок» і підтвердити вручну, перш ніж вирішити, чи включати його в структуру.

3. Що робити, якщо стиль абзацу None?

Рекомендується реєструвати попередження та розглядати їх як звичайний текст. Якщо такі ситуації відбуваються у великій кількості в пакетних файлах, слід запланувати перевірку вручну.

4. Чи можна використовувати спеціальні стилі як заголовки?

Якщо настроюваний стиль успадковується від Heading 1 і ланцюжок успадкування base_style є повним, його можна вважати дійсним заголовком.

📝 Підсумок

Оцінюючи назви Word, головною основою має бути стиль, а не лише візуальні ефекти. Після того, як перевірку коду пройдено, його все ще потрібно поєднати з певними типами документів і перевірити вручну, щоб підтвердити надійність результатів.

Спробуйте зараз: завантажте документ, щоб розпочати переклад, зберігаючи вихідний макет