Hey there! I’ve struggled with this exact problem before—trying to swap out text in a Word document without wiping out all the existing formatting (like bold, italics, font sizes) can be frustrating if you’re using python-docx the wrong way. Let’s walk through the correct approach, fix common errors, and get your replacement working while keeping your doc’s styling intact.

Why Direct Replacement Breaks Formatting #

When you try to do something simple like para.text = para.text.replace(old_str, new_str), you’re overwriting the entire paragraph’s text. But Word documents store text in Run objects—each Run has its own formatting rules. Overwriting the paragraph text resets all those Runs to a single default style, hence losing your original formatting.

The Fix: Work with Run Objects #

Instead of modifying entire paragraphs, we’ll target individual Runs, split them when they contain our target text, and clone their formatting for the new text. Here’s a step-by-step implementation:

Step 1: Full Replacement Function with Format Preservation #

from docx import Document

def replace_text_with_format(doc, old_text, new_text):
    # Process regular paragraphs
    for para in doc.paragraphs:
        _replace_in_run_group(para.runs, old_text, new_text)
    
    # Process text inside tables (easy to forget!)
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for para in cell.paragraphs:
                    _replace_in_run_group(para.runs, old_text, new_text)

def _replace_in_run_group(runs, old_text, new_text):
    # Iterate over a copy of the runs list to avoid index errors during modification
    for run in runs[:]:
        if old_text not in run.text:
            continue
        
        # Split the run's text around the target string
        text_parts = run.text.split(old_text)
        # Update the current run to hold the first part of the split text
        run.text = text_parts[0]
        
        # Add new runs for the replacement text and remaining content
        for part in text_parts[1:]:
            # Clone the original run's formatting for the replacement text
            replacement_run = run._element.addnext(run._element.clone())
            replacement_run.text = new_text
            # Clone again for the remaining text after the replacement
            remaining_run = replacement_run.addnext(run._element.clone())
            remaining_run.text = part
            
            # Add the new runs to our list (for future iterations if needed)
            runs.insert(runs.index(run) + 1, replacement_run)
            runs.insert(runs.index(replacement_run) + 1, remaining_run)

# Example usage
if __name__ == "__main__":
    doc = Document("your_input_doc.docx")
    replace_text_with_format(doc, "[CLIENT_NAME]", "Acme Corporation")
    doc.save("formatted_output.docx")

Key Details in This Code #

• runs[:]: We iterate over a slice of the runs list to avoid index errors when we add/remove runs mid-loop.
• run._element.clone(): This clones the underlying XML element of the run, preserving all formatting (font, color, bold, italics, etc.) instead of creating a new default run.
• Table Support: Most people forget to handle text inside tables—this function covers those too.

Fixing Common Errors #

Error 1: Some Text Doesn’t Get Replaced #

This usually happens because your target text is split across multiple Runs (e.g., part of a word is bold, part isn’t). To fix this, merge adjacent runs with identical formatting before replacement:

def merge_similar_runs(paragraph):
    runs = paragraph.runs
    i = 0
    while i < len(runs) - 1:
        current = runs[i]
        next_run = runs[i+1]
        
        # Check if runs have identical formatting (customize this check as needed)
        formats_match = (
            current.font.name == next_run.font.name
            and current.font.size == next_run.font.size
            and current.font.bold == next_run.font.bold
            and current.font.italic == next_run.font.italic
            and current.font.underline == next_run.font.underline
        )
        
        if formats_match:
            # Merge text and remove the next run
            current.text += next_run.text
            paragraph._element.remove(next_run._element)
            runs.pop(i+1)
        else:
            i += 1

Then update your main replacement function to merge runs first:

def replace_text_with_format(doc, old_text, new_text):
    for para in doc.paragraphs:
        merge_similar_runs(para)
        _replace_in_run_group(para.runs, old_text, new_text)
    
    # Repeat merging for table cells
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for para in cell.paragraphs:
                    merge_similar_runs(para)
                    _replace_in_run_group(para.runs, old_text, new_text)

Error 2: Formatting Still Gets Lost #

Double-check that you’re not modifying the paragraph.text property anywhere—this will always reset formatting. Stick strictly to modifying individual Run objects as shown.

Final Notes #

• This method works for most common formatting scenarios, but for extremely complex docs (e.g., nested fields, tracked changes), you might need to adjust the logic to handle those edge cases.
• Always test with a copy of your document first to avoid accidental data loss!

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