@nguyenphp/antigravity-marketing 1.0.18 → 1.0.19

package/templates/.agent/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Core/Samples/FieldAndTocSamples.cs

@@ -0,0 +1,624 @@
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+
+namespace MiniMaxAIDocx.Core.Samples;
+
+/// <summary>
+/// Reference implementations for field codes and Table of Contents (TOC).
+///
+/// KEY CONCEPTS:
+/// - SimpleField: single-element shorthand, e.g. &lt;w:fldSimple w:instr="PAGE"/&gt;
+/// - Complex field: three FieldChar elements (Begin / Separate / End) with FieldCode between them.
+///   Word always writes complex fields; SimpleField is only used for trivial cases.
+/// - TOC is a structured document tag (SdtBlock) wrapping a complex field.
+/// - UpdateFieldsOnOpen tells Word to recalculate all fields when opening.
+/// </summary>
+public static class FieldAndTocSamples
+{
+    // ──────────────────────────────────────────────
+    // 1. InsertToc — TOC levels 1-3 inside SdtBlock
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a Table of Contents covering heading levels 1-3.
+    /// Uses an SdtBlock wrapper with a complex field code:
+    ///   TOC \o "1-3" \h \z \u
+    ///
+    /// Switches:
+    ///   \o "1-3" — outline levels 1-3
+    ///   \h       — hyperlinks
+    ///   \z       — hide tab leaders / page numbers in Web Layout
+    ///   \u       — use applied paragraph outline level
+    /// </summary>
+    public static SdtBlock InsertToc(Body body)
+    {
+        var sdtBlock = new SdtBlock();
+
+        // SdtProperties — mark as TOC
+        var sdtPr = new SdtProperties();
+        sdtPr.Append(new SdtContentDocPartObject(
+            new DocPartGallery { Val = "Table of Contents" },
+            new DocPartUnique()));
+        sdtBlock.Append(sdtPr);
+
+        // SdtContent — contains the field code paragraph(s)
+        var sdtContent = new SdtContentBlock();
+
+        // TOC title paragraph
+        var titlePara = new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
+            new Run(new Text("Table of Contents")));
+        sdtContent.Append(titlePara);
+
+        // Complex field paragraph for TOC
+        var fieldPara = new Paragraph();
+        InsertComplexFieldInline(fieldPara, " TOC \\o \"1-3\" \\h \\z \\u ");
+        sdtContent.Append(fieldPara);
+
+        sdtBlock.Append(sdtContent);
+        body.Append(sdtBlock);
+        return sdtBlock;
+    }
+
+    // ──────────────────────────────────────────────
+    // 2. InsertTocWithCustomLevels — TOC 1-4 levels
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a TOC covering heading levels 1-4.
+    /// Identical structure to <see cref="InsertToc"/> but with "\o 1-4".
+    /// </summary>
+    public static SdtBlock InsertTocWithCustomLevels(Body body)
+    {
+        var sdtBlock = new SdtBlock();
+
+        var sdtPr = new SdtProperties();
+        sdtPr.Append(new SdtContentDocPartObject(
+            new DocPartGallery { Val = "Table of Contents" },
+            new DocPartUnique()));
+        sdtBlock.Append(sdtPr);
+
+        var sdtContent = new SdtContentBlock();
+
+        var titlePara = new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
+            new Run(new Text("Table of Contents")));
+        sdtContent.Append(titlePara);
+
+        // 1-4 levels instead of 1-3
+        var fieldPara = new Paragraph();
+        InsertComplexFieldInline(fieldPara, " TOC \\o \"1-4\" \\h \\z \\u ");
+        sdtContent.Append(fieldPara);
+
+        sdtBlock.Append(sdtContent);
+        body.Append(sdtBlock);
+        return sdtBlock;
+    }
+
+    // ──────────────────────────────────────────────
+    // 3. InsertSimpleField — PAGE, NUMPAGES, DATE, etc.
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a SimpleField element into a paragraph.
+    ///
+    /// SimpleField is the compact form: &lt;w:fldSimple w:instr=" PAGE "&gt;&lt;w:r&gt;...&lt;/w:r&gt;&lt;/w:fldSimple&gt;
+    ///
+    /// Common instructions: "PAGE", "NUMPAGES", "DATE", "TIME", "FILENAME".
+    /// The run inside is the cached display value; Word recalculates on open.
+    /// </summary>
+    public static SimpleField InsertSimpleField(Paragraph para, string instruction)
+    {
+        var simpleField = new SimpleField { Instruction = $" {instruction} " };
+
+        // Cached display value — Word replaces this on recalculation
+        simpleField.Append(new Run(
+            new RunProperties(new NoProof()),
+            new Text("«" + instruction + "»")));
+
+        para.Append(simpleField);
+        return simpleField;
+    }
+
+    // ──────────────────────────────────────────────
+    // 4. InsertComplexField — Begin/Separate/End
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a complex field into a paragraph using the FieldChar Begin/Separate/End pattern.
+    ///
+    /// Structure:
+    ///   Run1: FieldChar(Begin) + FieldCode(" PAGE ")
+    ///   Run2: FieldChar(Separate)
+    ///   Run3: Text("1")              ← cached display value
+    ///   Run4: FieldChar(End)
+    ///
+    /// Use complex fields when you need dirty flags, lock, or nested fields.
+    /// </summary>
+    public static void InsertComplexField(Paragraph para, string instruction)
+    {
+        InsertComplexFieldInline(para, $" {instruction} ");
+    }
+
+    // ──────────────────────────────────────────────
+    // 5. InsertDateField — DATE with format switch
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a DATE field with a format switch: DATE \@ "yyyy-MM-dd"
+    ///
+    /// The \@ switch specifies the date/time picture.
+    /// Common formats:
+    ///   \@ "yyyy-MM-dd"         → 2026-03-22
+    ///   \@ "MMMM d, yyyy"      → March 22, 2026
+    ///   \@ "M/d/yyyy h:mm am/pm" → 3/22/2026 2:30 PM
+    /// </summary>
+    public static void InsertDateField(Paragraph para, string format)
+    {
+        // Field instruction with date-time picture switch
+        string instruction = $" DATE \\@ \"{format}\" ";
+        InsertComplexFieldInline(para, instruction);
+    }
+
+    // ──────────────────────────────────────────────
+    // 6. InsertCrossReference — REF field
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a REF cross-reference field that refers to a bookmark.
+    ///
+    /// Instruction: REF bookmarkName \h
+    ///   \h — creates a hyperlink to the bookmark
+    ///   \p — inserts "above" or "below" relative position
+    ///   \n — inserts paragraph number of the bookmark
+    /// </summary>
+    public static void InsertCrossReference(Paragraph para, string bookmarkName)
+    {
+        string instruction = $" REF {bookmarkName} \\h ";
+        InsertComplexFieldInline(para, instruction);
+    }
+
+    // ──────────────────────────────────────────────
+    // 7. InsertSequenceField — SEQ for numbering
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a SEQ (sequence) field for auto-numbering figures, tables, etc.
+    ///
+    /// Usage pattern for "Figure 1":
+    ///   1. Append a run with text "Figure " to the paragraph
+    ///   2. Call InsertSequenceField(para, "Figure")
+    ///
+    /// Usage pattern for "Table 1":
+    ///   1. Append a run with text "Table " to the paragraph
+    ///   2. Call InsertSequenceField(para, "Table")
+    ///
+    /// Each unique seqName maintains its own counter across the document.
+    /// </summary>
+    public static void InsertSequenceField(Paragraph para, string seqName)
+    {
+        string instruction = $" SEQ {seqName} \\* ARABIC ";
+        InsertComplexFieldInline(para, instruction);
+    }
+
+    // ──────────────────────────────────────────────
+    // 8. InsertMergeField — MERGEFIELD for mail merge
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a MERGEFIELD for mail merge scenarios.
+    ///
+    /// Instruction: MERGEFIELD fieldName \* MERGEFORMAT
+    ///   \* MERGEFORMAT — preserves formatting applied to the field result
+    ///   \b "text"     — text before if field is non-empty
+    ///   \f "text"     — text after if field is non-empty
+    ///
+    /// The cached display shows «fieldName» as a placeholder.
+    /// </summary>
+    public static void InsertMergeField(Paragraph para, string fieldName)
+    {
+        string instruction = $" MERGEFIELD {fieldName} \\* MERGEFORMAT ";
+
+        // Begin
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Begin }));
+
+        // Field code
+        para.Append(new Run(
+            new FieldCode(instruction) { Space = SpaceProcessingModeValues.Preserve }));
+
+        // Separate
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Separate }));
+
+        // Cached value — shows merge field placeholder
+        para.Append(new Run(
+            new RunProperties(new NoProof()),
+            new Text($"\u00AB{fieldName}\u00BB") { Space = SpaceProcessingModeValues.Preserve }));
+
+        // End
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.End }));
+    }
+
+    // ──────────────────────────────────────────────
+    // 9. InsertConditionalField — IF field
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts an IF conditional field.
+    ///
+    /// Syntax: IF expression1 operator expression2 "true-text" "false-text"
+    /// Example: IF { MERGEFIELD Gender } = "Male" "Mr." "Ms."
+    ///
+    /// This example checks if MERGEFIELD Amount > 1000 and displays different text.
+    /// Nested fields (MERGEFIELD inside IF) require nested Begin/End pairs.
+    /// </summary>
+    public static void InsertConditionalField(Paragraph para)
+    {
+        // Outer IF field Begin
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Begin }));
+
+        para.Append(new Run(
+            new FieldCode(" IF ") { Space = SpaceProcessingModeValues.Preserve }));
+
+        // Nested MERGEFIELD inside the IF condition
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Begin }));
+        para.Append(new Run(
+            new FieldCode(" MERGEFIELD Amount ") { Space = SpaceProcessingModeValues.Preserve }));
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Separate }));
+        para.Append(new Run(
+            new Text("0") { Space = SpaceProcessingModeValues.Preserve }));
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.End }));
+
+        // Continuation of IF instruction
+        para.Append(new Run(
+            new FieldCode(" > \"1000\" \"High Value\" \"Standard\" ") { Space = SpaceProcessingModeValues.Preserve }));
+
+        // Separate — cached result
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Separate }));
+        para.Append(new Run(
+            new RunProperties(new NoProof()),
+            new Text("Standard") { Space = SpaceProcessingModeValues.Preserve }));
+
+        // End
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.End }));
+    }
+
+    // ──────────────────────────────────────────────
+    // 10. InsertStyleRef — STYLEREF for running headers
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a STYLEREF field, commonly used in headers/footers
+    /// to display the current chapter or section title.
+    ///
+    /// Instruction: STYLEREF "Heading 1"
+    ///   Displays the text of the nearest paragraph with style "Heading 1".
+    ///   \l — search from bottom of page up (for last instance on page)
+    ///   \n — insert the paragraph number, not text
+    /// </summary>
+    public static void InsertStyleRef(Paragraph para)
+    {
+        string instruction = " STYLEREF \"Heading 1\" ";
+        InsertComplexFieldInline(para, instruction);
+    }
+
+    // ──────────────────────────────────────────────
+    // 11. EnableUpdateFieldsOnOpen
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Sets the UpdateFieldsOnOpen property so Word recalculates
+    /// all fields (PAGE, TOC, SEQ, etc.) when the document is opened.
+    ///
+    /// Without this, TOC and cross-references show stale cached values
+    /// until the user manually presses Ctrl+A, F9 to update.
+    /// </summary>
+    public static void EnableUpdateFieldsOnOpen(DocumentSettingsPart settingsPart)
+    {
+        settingsPart.Settings ??= new Settings();
+        var existing = settingsPart.Settings.GetFirstChild<UpdateFieldsOnOpen>();
+        if (existing != null)
+        {
+            existing.Val = true;
+        }
+        else
+        {
+            settingsPart.Settings.Append(new UpdateFieldsOnOpen { Val = true });
+        }
+        settingsPart.Settings.Save();
+    }
+
+    // ──────────────────────────────────────────────
+    // 12. CreateTocStyles — TOC1/2/3 with tab leaders
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates TOC1, TOC2, TOC3 paragraph styles with right-aligned tab stops
+    /// and dot leaders (the "....." between entry text and page number).
+    ///
+    /// Each TOC level is indented further:
+    ///   TOC1 — 0 indent
+    ///   TOC2 — 240 twips (1/6 inch)
+    ///   TOC3 — 480 twips (1/3 inch)
+    ///
+    /// Tab leader: dot-filled right tab at 9360 twips (6.5 inches for letter paper).
+    /// </summary>
+    public static void CreateTocStyles(StyleDefinitionsPart stylesPart)
+    {
+        stylesPart.Styles ??= new Styles();
+
+        string[] tocStyleIds = ["TOC1", "TOC2", "TOC3"];
+        string[] tocStyleNames = ["toc 1", "toc 2", "toc 3"];
+        int[] indents = [0, 240, 480]; // twips
+
+        // Right tab position: 6.5 inches = 9360 twips (standard for US Letter)
+        const int tabPosition = 9360;
+
+        for (int i = 0; i < tocStyleIds.Length; i++)
+        {
+            var style = new Style
+            {
+                Type = StyleValues.Paragraph,
+                StyleId = tocStyleIds[i],
+                CustomStyle = false
+            };
+
+            style.Append(new StyleName { Val = tocStyleNames[i] });
+            style.Append(new BasedOn { Val = "Normal" });
+            style.Append(new NextParagraphStyle { Val = "Normal" });
+            style.Append(new UIPriority { Val = 39 });
+
+            var pPr = new StyleParagraphProperties();
+
+            // Indentation for nested levels
+            if (indents[i] > 0)
+            {
+                pPr.Append(new Indentation { Left = indents[i].ToString() });
+            }
+
+            // Spacing: no space after for compact TOC
+            pPr.Append(new SpacingBetweenLines { After = "0", Line = "276", LineRule = LineSpacingRuleValues.Auto });
+
+            // Right-aligned tab with dot leader
+            var tabs = new Tabs();
+            tabs.Append(new TabStop
+            {
+                Val = TabStopValues.Right,
+                Leader = TabStopLeaderCharValues.Dot,
+                Position = tabPosition
+            });
+            pPr.Append(tabs);
+
+            style.Append(pPr);
+            stylesPart.Styles.Append(style);
+        }
+
+        stylesPart.Styles.Save();
+    }
+
+    // ──────────────────────────────────────────────
+    // 13. CreateMixedTocStructure — Real-world TOC
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Real-world TOC structure: Mixed SDT block + static entries + field code.
+    ///
+    /// IMPORTANT: Most templates do NOT have a clean TOC field code alone.
+    /// Instead, they contain:
+    /// 1. An SDT (Structured Document Tag) wrapper with alias "TOC"
+    /// 2. Inside the SDT: a field code BEGIN + SEPARATE + static example entries + END
+    /// 3. The static entries are placeholder text (e.g., "第1章 绪论...........1")
+    ///    that Word replaces when user presses "Update Fields"
+    ///
+    /// When applying a template (Scenario C), you should:
+    /// - KEEP the entire SDT block from the template (don't rebuild it)
+    /// - DO NOT replace static entries with programmatic content
+    /// - The entries will auto-update when the user opens in Word and updates fields
+    /// - If you must update entries programmatically, replace the content INSIDE
+    ///   the SDT between fldChar separate and fldChar end
+    ///
+    /// Common mistake: Treating TOC as pure field code and rebuilding it from scratch,
+    /// which destroys the SDT wrapper and breaks Word's "Update Table" functionality.
+    /// </summary>
+    public static void CreateMixedTocStructure(string outputPath)
+    {
+        using var doc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
+        var mainPart = doc.AddMainDocumentPart();
+        mainPart.Document = new Document();
+        var body = new Body();
+        mainPart.Document.Append(body);
+
+        // Add styles part with TOC styles
+        var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
+        CreateTocStyles(stylesPart);
+
+        // ─── SDT Block wrapping the entire TOC ───
+        var sdtBlock = new SdtBlock();
+
+        // SDT Properties: alias "TOC", tag, and DocPartGallery
+        var sdtPr = new SdtProperties();
+        sdtPr.Append(new SdtAlias { Val = "TOC" });
+        sdtPr.Append(new Tag { Val = "TOC" });
+        sdtPr.Append(new SdtContentDocPartObject(
+            new DocPartGallery { Val = "Table of Contents" },
+            new DocPartUnique()));
+        sdtBlock.Append(sdtPr);
+
+        // SDT Content: field code + static entries
+        var sdtContent = new SdtContentBlock();
+
+        // ─── TOC title paragraph ───
+        var titlePara = new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
+            new Run(new Text("目  录")));
+        sdtContent.Append(titlePara);
+
+        // ─── Field code BEGIN paragraph ───
+        var fieldBeginPara = new Paragraph();
+
+        // fldChar Begin
+        fieldBeginPara.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Begin }));
+
+        // instrText: TOC \o "1-3" \h \z \u
+        fieldBeginPara.Append(new Run(
+            new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }));
+
+        // fldChar Separate
+        fieldBeginPara.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Separate }));
+
+        sdtContent.Append(fieldBeginPara);
+
+        // ─── Static placeholder entries (TOC1/TOC2/TOC3) ───
+        // These are the example entries that Word will replace when user clicks "Update Table".
+        // In real templates, these show example chapter titles with dot leaders and page numbers.
+
+        // TOC level 1 entry: "第1章 绪论...........1"
+        sdtContent.Append(CreateStaticTocEntry("TOC1", "第1章 绪论", "1"));
+
+        // TOC level 2 entry: "1.1 研究背景...........1"
+        sdtContent.Append(CreateStaticTocEntry("TOC2", "1.1 研究背景", "1"));
+
+        // TOC level 2 entry: "1.2 研究目的...........2"
+        sdtContent.Append(CreateStaticTocEntry("TOC2", "1.2 研究目的", "2"));
+
+        // TOC level 1 entry: "第2章 文献综述...........3"
+        sdtContent.Append(CreateStaticTocEntry("TOC1", "第2章 文献综述", "3"));
+
+        // TOC level 2 entry: "2.1 国内研究现状...........3"
+        sdtContent.Append(CreateStaticTocEntry("TOC2", "2.1 国内研究现状", "3"));
+
+        // TOC level 3 entry: "2.1.1 早期研究...........4"
+        sdtContent.Append(CreateStaticTocEntry("TOC3", "2.1.1 早期研究", "4"));
+
+        // TOC level 1 entry: "第3章 研究方法...........5"
+        sdtContent.Append(CreateStaticTocEntry("TOC1", "第3章 研究方法", "5"));
+
+        // ─── Field code END paragraph ───
+        var fieldEndPara = new Paragraph();
+        fieldEndPara.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.End }));
+        sdtContent.Append(fieldEndPara);
+
+        sdtBlock.Append(sdtContent);
+        body.Append(sdtBlock);
+
+        // ─── Actual heading paragraphs (what the TOC references) ───
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+            new Run(new Text("第1章 绪论"))));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
+            new Run(new Text("1.1 研究背景"))));
+
+        body.Append(new Paragraph(
+            new Run(new Text("本研究旨在探讨……"))));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
+            new Run(new Text("1.2 研究目的"))));
+
+        body.Append(new Paragraph(
+            new Run(new Text("研究目的包括……"))));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+            new Run(new Text("第2章 文献综述"))));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
+            new Run(new Text("2.1 国内研究现状"))));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading3" }),
+            new Run(new Text("2.1.1 早期研究"))));
+
+        body.Append(new Paragraph(
+            new Run(new Text("早期研究表明……"))));
+
+        body.Append(new Paragraph(
+            new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+            new Run(new Text("第3章 研究方法"))));
+
+        body.Append(new Paragraph(
+            new Run(new Text("本章介绍研究方法……"))));
+
+        // ─── Enable UpdateFieldsOnOpen so TOC auto-refreshes ───
+        var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+        EnableUpdateFieldsOnOpen(settingsPart);
+
+        mainPart.Document.Save();
+    }
+
+    /// <summary>
+    /// Helper: creates a single static TOC entry paragraph with style, text, tab leader, and page number.
+    /// This mirrors what Word generates inside a TOC SDT block.
+    /// </summary>
+    private static Paragraph CreateStaticTocEntry(string tocStyleId, string entryText, string pageNumber)
+    {
+        var para = new Paragraph();
+
+        // Paragraph properties: TOC style + right-aligned tab with dot leader
+        var pPr = new ParagraphProperties();
+        pPr.Append(new ParagraphStyleId { Val = tocStyleId });
+        para.Append(pPr);
+
+        // Run with entry text
+        para.Append(new Run(
+            new RunProperties(new NoProof()),
+            new Text(entryText) { Space = SpaceProcessingModeValues.Preserve }));
+
+        // Tab character (creates the dot leader between text and page number)
+        para.Append(new Run(new TabChar()));
+
+        // Page number
+        para.Append(new Run(
+            new RunProperties(new NoProof()),
+            new Text(pageNumber)));
+
+        return para;
+    }
+
+    // ──────────────────────────────────────────────
+    // Private helper: insert complex field inline
+    // ──────────────────────────────────────────────
+
+    /// <summary>
+    /// Shared helper that appends Begin / FieldCode / Separate / CachedValue / End
+    /// runs to a paragraph.
+    /// </summary>
+    private static void InsertComplexFieldInline(Paragraph para, string instruction)
+    {
+        // Run 1: FieldChar Begin
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Begin }));
+
+        // Run 2: FieldCode (the instruction text)
+        para.Append(new Run(
+            new FieldCode(instruction) { Space = SpaceProcessingModeValues.Preserve }));
+
+        // Run 3: FieldChar Separate
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.Separate }));
+
+        // Run 4: Cached display value (placeholder until Word recalculates)
+        para.Append(new Run(
+            new RunProperties(new NoProof()),
+            new Text("1") { Space = SpaceProcessingModeValues.Preserve }));
+
+        // Run 5: FieldChar End
+        para.Append(new Run(
+            new FieldChar { FieldCharType = FieldCharValues.End }));
+    }
+}