wehub-resource-sync
8cb1f9f479
Publish SDK (PyPI) / publish (push) Has been cancelled
Publish SDK (npm) / publish (@aionui/officecli-sdk) (push) Has been cancelled
SDK smoke / smoke (windows-latest) (push) Has been cancelled
Publish SDK (npm) / publish (@officecli/officecli-sdk) (push) Has been cancelled
Publish SDK (npm) / publish (@officecli/sdk) (push) Has been cancelled
Publish SDK (npm) / publish (officecli-sdk) (push) Has been cancelled
SDK smoke / smoke (macos-latest) (push) Has been cancelled
SDK smoke / smoke (ubuntu-latest) (push) Has been cancelled
Skill parity / diff (push) Has been cancelled
422 lines
18 KiB
Markdown
422 lines
18 KiB
Markdown
# Paragraph Formatting Showcase
|
||
|
||
Exercises the docx **paragraph** property surface. Three files:
|
||
|
||
- **paragraph-formatting.sh** — builds the document with `officecli` (155 lines, ~55 commands).
|
||
- **paragraph-formatting.docx** — generated output, one paragraph per property group.
|
||
- **paragraph-formatting.md** — this file.
|
||
|
||
## Regenerate
|
||
|
||
```bash
|
||
cd examples/word
|
||
bash paragraph-formatting.sh
|
||
# → paragraph-formatting.docx
|
||
```
|
||
|
||
## Alignment
|
||
|
||
The four standard paragraph alignment values.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Left aligned (default)" --prop align=left
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Center aligned" --prop align=center
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Right aligned" --prop align=right
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Justified text stretched edge to edge..." --prop align=both
|
||
```
|
||
|
||
**Features:** `align` (left/center/right/both/distribute/thai/mediumKashida/highKashida/lowKashida)
|
||
|
||
## Indentation
|
||
|
||
Left, right, first-line, and hanging indent — all accepting twips, cm, or in.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Left indent 1cm" --prop indent=1cm
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Right indent 2cm..." --prop rightIndent=2cm
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=First-line indent — only the first line is pushed in." \
|
||
--prop firstLineIndent=1cm
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Hanging indent — first line hangs left." \
|
||
--prop indent=1cm --prop hangingIndent=1cm
|
||
```
|
||
|
||
**Features:** `indent` (left indent; twips, cm, in, pt), `rightIndent`, `firstLineIndent` (positive → indent first line extra), `hangingIndent` (positive → all-but-first lines indented; combine with `indent` of equal value)
|
||
|
||
## Spacing
|
||
|
||
Space before/after in points, and line spacing as a multiplier or fixed value.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Space before 18pt, after 6pt" \
|
||
--prop spaceBefore=18pt --prop spaceAfter=6pt
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Line spacing 1.5x across a longer paragraph..." \
|
||
--prop lineSpacing=1.5x
|
||
```
|
||
|
||
**Features:** `spaceBefore` (space above; accepts `18pt`, `0.5cm`, `360` twips), `spaceAfter`, `lineSpacing` (1.5x/150%/18pt/bare number; normalised via `SpacingConverter`)
|
||
|
||
## Pagination Flags
|
||
|
||
Control how Word breaks pages around this paragraph.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=keepNext — stays with the following paragraph" \
|
||
--prop keepNext=true
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=keepLines — lines stay together, never split across pages" \
|
||
--prop keepLines=true
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=widowControl on" --prop widowControl=true
|
||
```
|
||
|
||
**Features:** `keepNext` (force this paragraph and the next onto the same page), `keepLines` (prevent page break within the paragraph), `widowControl` (prevent single-line orphans/widows)
|
||
|
||
## Paragraph-Level Run Formatting
|
||
|
||
Properties set at the paragraph level apply to **every run** in the paragraph (equivalent to selecting all and formatting).
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Whole paragraph bold + red + 13pt" \
|
||
--prop bold=true --prop color=C00000 --prop size=13
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Whole paragraph italic + highlighted" \
|
||
--prop italic=true --prop highlight=yellow
|
||
```
|
||
|
||
**Features:** `bold`, `italic`, `color`, `size`, `highlight` — when set on `--type paragraph` these become paragraph-level run defaults (`w:pPr/w:rPr`), not inline run properties.
|
||
|
||
## Shading
|
||
|
||
Paragraph background fill color, with optional pattern.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Light gray paragraph shading" --prop shading.fill=D9D9D9
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Pale blue shading" --prop shading.fill=DDEBF7
|
||
```
|
||
|
||
**Features:** `shading.fill` (solid fill hex color; writer defaults `w:shd/@val` to `clear`), `shd` (shorthand alias for `shading.fill`), `shading.val` (pattern type: pct15/pct25/pct50/…), `shading.color` (pattern foreground color)
|
||
|
||
## Paragraph-Mark Formatting (markRPr)
|
||
|
||
The paragraph mark (¶ pilcrow) has its own run properties, distinct from the paragraph's run defaults. This controls what formatting a newly typed run at the end of the paragraph inherits.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=The mark glyph is bold+red (distinct from run text)" \
|
||
--prop markRPr.bold=true --prop markRPr.color=C00000
|
||
|
||
# Full markRPr set
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=mark: italic/strike/underline/size/highlight/fonts" \
|
||
--prop markRPr.italic=true --prop markRPr.strike=true \
|
||
--prop markRPr.underline=single --prop markRPr.size=14pt \
|
||
--prop markRPr.highlight=yellow \
|
||
--prop markRPr.font.latin=Georgia \
|
||
--prop markRPr.font.ea=SimSun --prop markRPr.font.cs=Arial
|
||
```
|
||
|
||
**Features:** `markRPr.bold`, `markRPr.italic`, `markRPr.strike`, `markRPr.underline`, `markRPr.size`, `markRPr.color`, `markRPr.highlight`, `markRPr.font.latin`, `markRPr.font.ea`, `markRPr.font.cs`
|
||
|
||
> Setting `bold=true` on a paragraph makes every run bold. Setting `markRPr.bold=true` formats only the ¶ mark — they are independent and both settable/gettable.
|
||
|
||
## Outline Level
|
||
|
||
Assign a paragraph to the document outline (affects navigation pane, table of contents, heading styles).
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Outline level 1 (shows in document map)" --prop outlineLvl=1
|
||
```
|
||
|
||
**Features:** `outlineLvl` (0–8; 0 = body text, 1–8 = heading levels; 9 = no outline level)
|
||
|
||
## Paragraph Strike & Underline
|
||
|
||
Strike-through and underline can also be applied at the paragraph level (to all runs).
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Whole paragraph struck out" --prop strike=true
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Underlined paragraph (red wave)" \
|
||
--prop underline=wave --prop underline.color=#FF0000
|
||
```
|
||
|
||
**Features:** `strike` (paragraph-level single strikethrough), `underline` (paragraph-level underline style), `underline.color` (accepts leading `#` — stripped before storage)
|
||
|
||
## Complex-Script (cs) Properties
|
||
|
||
Separate formatting for complex-script (bidirectional, Arabic, Hebrew) glyph runs.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=cs bold/italic/14pt + RTL" \
|
||
--prop bold.cs=true --prop italic.cs=true \
|
||
--prop size.cs=14pt --prop direction=rtl
|
||
```
|
||
|
||
**Features:** `bold.cs`, `italic.cs`, `size.cs` (complex-script weight/style/size), `direction` (rtl sets `w:bidi` on the paragraph)
|
||
|
||
## Spacing & Pagination Extras
|
||
|
||
Additional spacing and pagination controls beyond the basic set.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=contextualSpacing (collapse between same-style paras)" \
|
||
--prop contextualSpacing=true
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=lineSpacing 14pt, lineRule=atLeast" \
|
||
--prop lineSpacing=14pt --prop lineRule=atLeast
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=pageBreakBefore" --prop pageBreakBefore=true
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=wordWrap off (break long URLs anywhere)" --prop wordWrap=false
|
||
```
|
||
|
||
**Features:** `contextualSpacing` (suppress space-before/after between paragraphs of the same style), `lineRule` (atLeast/exactly/auto), `pageBreakBefore` (force a page break before this paragraph), `wordWrap` (false = break at any character, not just word boundaries)
|
||
|
||
## Chars-Based Indent
|
||
|
||
CJK-friendly indentation in 1/100-character units (avoids relying on absolute twip values).
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=first-line 200 chars, hanging 100 chars" \
|
||
--prop firstLineChars=200 --prop hangingChars=100
|
||
```
|
||
|
||
**Features:** `firstLineChars` (first-line indent in 1/100-char units; 200 = 2 characters), `hangingChars`
|
||
|
||
## Fonts (Explicit & Theme)
|
||
|
||
Per-script font families and theme font slots.
|
||
|
||
```bash
|
||
# Shorthand — sets all scripts
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=font shorthand Times New Roman" \
|
||
--prop font="Times New Roman"
|
||
|
||
# Explicit per-script
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=per-script latin/ea/cs" \
|
||
--prop font.latin=Calibri --prop font.ea=SimSun --prop font.cs=Arial
|
||
|
||
# Theme references
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=theme fonts" \
|
||
--prop font.asciiTheme=minorHAnsi --prop font.hAnsiTheme=minorHAnsi \
|
||
--prop font.eaTheme=minorEastAsia --prop font.csTheme=minorBidi
|
||
```
|
||
|
||
**Features:** `font` (all-scripts shorthand), `font.latin`, `font.ea`, `font.cs`, `font.asciiTheme` (majorHAnsi/minorHAnsi), `font.hAnsiTheme`, `font.eaTheme`, `font.csTheme`
|
||
|
||
## Styles
|
||
|
||
Apply a named paragraph style or a character style to all runs.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Paragraph style Heading1" --prop style=Heading1
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Character style on the run" --prop rStyle=Emphasis
|
||
```
|
||
|
||
**Features:** `style` (paragraph style ID; e.g. `Heading1`, `Normal`, `ListBullet`), `rStyle` (character style ID applied to the paragraph's default run properties)
|
||
|
||
## Shading Variants
|
||
|
||
Different ways to express paragraph background shading.
|
||
|
||
```bash
|
||
# Shorthand alias
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=shd shorthand (yellow)" --prop shd=FFFF00
|
||
|
||
# Decomposed: pattern + fill color + pattern foreground color
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=pct15 pattern, blue fill, red pattern color" \
|
||
--prop shading.val=pct15 --prop shading.fill=DDEBF7 --prop shading.color=C00000
|
||
```
|
||
|
||
**Features:** `shd` (shorthand alias for `shading.fill`), `shading.val` (pattern: clear/pct5/pct10/pct15/pct25/pct50/solid/…), `shading.fill` (fill color hex), `shading.color` (pattern foreground hex)
|
||
|
||
## Tab Stops
|
||
|
||
Declare tab stop positions in twips.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Tabs at 720 and 1440 twips" --prop tabs=720,1440
|
||
```
|
||
|
||
**Features:** `tabs` (comma-separated list of tab positions in twips; 720 = 0.5in, 1440 = 1in)
|
||
|
||
## Text Frame (framePr)
|
||
|
||
A framed paragraph floats in its own positioned box, with body text optionally wrapping around it. Dimensions use twips.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Framed paragraph — floats in a 3-inch box with text wrapping." \
|
||
--prop framePr.w=4320 --prop framePr.h=720 --prop framePr.wrap=around \
|
||
--prop framePr.hAnchor=margin --prop framePr.vAnchor=text \
|
||
--prop framePr.hSpace=180 --prop framePr.vSpace=180
|
||
```
|
||
|
||
**Features:** `framePr.w` (frame width in twips; 4320 = 3in), `framePr.h` (height), `framePr.wrap` (around/notBeside/none/tight/through), `framePr.hAnchor` (margin/page/text), `framePr.vAnchor`, `framePr.hSpace` (horizontal clearance), `framePr.vSpace`
|
||
|
||
## Paragraph Borders (pBdr)
|
||
|
||
Whole-box shorthand (`border=`) sets all four sides at once, accepting `style`, `style;size;color`, or `style;size;color;space`. Per-side keys (`border.top`, `border.bottom`, `border.left`, `border.right`) take the same value and can be mixed for a partial box (e.g. a rule above and below only).
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Box border, all sides (single)" --prop border=single
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Red 1pt box (style;size;color)" \
|
||
--prop "border=single;8;FF0000"
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Per-side: top + bottom only (rule above and below)" \
|
||
--prop "border.top=single;8;0070C0" --prop "border.bottom=single;8;0070C0"
|
||
```
|
||
|
||
**Features:** `border` (whole-box paragraph border; format `style` or `style;size;color` or `style;size;color;space`; style values: single/double/thick/dotted/dashed/dotDash/…), `border.top`/`border.bottom`/`border.left`/`border.right` (per-side, same value format)
|
||
|
||
## Vertical Text Alignment
|
||
|
||
Control how glyphs align vertically within the line box (distinct from cell vertical alignment).
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=textAlignment=center (glyphs centered on the line box)" \
|
||
--prop textAlignment=center
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=textAlignment=top" --prop textAlignment=top
|
||
```
|
||
|
||
**Features:** `textAlignment` (top/center/baseline/bottom/auto)
|
||
|
||
## EastAsian Typography
|
||
|
||
CJK line-breaking and spacing rules.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=kinsoku off — permit breaks at forbidden CJK chars" \
|
||
--prop kinsoku=false
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=autoSpace off — no auto gap between CJK and Latin/digits" \
|
||
--prop autoSpaceDE=false --prop autoSpaceDN=false
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=overflowPunct + topLinePunct on" \
|
||
--prop overflowPunct=true --prop topLinePunct=true
|
||
```
|
||
|
||
**Features:** `kinsoku` (Japanese line-break constraint; false = allow breaks at forbidden positions), `autoSpaceDE` (auto spacing between CJK and Latin), `autoSpaceDN` (auto spacing between CJK and digits), `overflowPunct` (allow punctuation to hang outside margin), `topLinePunct` (compress leading punctuation to top of line)
|
||
|
||
## Line & Indent Flags
|
||
|
||
Miscellaneous line-number, hyphenation, and indent behaviour toggles.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=suppressLineNumbers + suppressAutoHyphens" \
|
||
--prop suppressLineNumbers=true --prop suppressAutoHyphens=true
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=mirrorIndents on, adjustRightInd off, snapToGrid off" \
|
||
--prop mirrorIndents=true --prop adjustRightInd=false --prop snapToGrid=false
|
||
```
|
||
|
||
**Features:** `suppressLineNumbers` (exclude from line number count), `suppressAutoHyphens` (disable hyphenation), `mirrorIndents` (swap left/right indent on alternate pages for book layout), `adjustRightInd` (auto-adjust right indent for document grid), `snapToGrid` (snap paragraph to the document character grid)
|
||
|
||
## Web / Textbox Hints
|
||
|
||
Layout hints for web view and textbox flow.
|
||
|
||
```bash
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=divId (web division id) + textboxTightWrap=allLines" \
|
||
--prop divId=123456 --prop textboxTightWrap=allLines
|
||
```
|
||
|
||
**Features:** `divId` (integer web-division ID for HTML round-trip), `textboxTightWrap` (none/allLines/firstAndLastLine/firstLineOnly/lastLineOnly)
|
||
|
||
## List Numbering
|
||
|
||
Attach a paragraph to a list via a high-level style shorthand or direct numPr references.
|
||
|
||
```bash
|
||
# High-level shorthand
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Bulleted item" --prop listStyle=bullet
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Ordered item starting at 5" \
|
||
--prop listStyle=ordered --prop start=5
|
||
|
||
# Direct numPr reference
|
||
officecli add paragraph-formatting.docx /body --type paragraph \
|
||
--prop "text=Explicit numId=1 level 0" --prop numId=1 --prop numLevel=0
|
||
```
|
||
|
||
**Features:** `listStyle` (bullet/ordered — creates or reuses a numbering definition automatically), `start` (override starting counter for this instance), `numId` (direct reference to a `w:num` element by id), `numLevel` (alias: `ilvl`; 0-based indent level)
|
||
|
||
## Complete Feature Coverage
|
||
|
||
| Feature | Section |
|
||
|---------|---------|
|
||
| `align` (left/center/right/both) | Alignment |
|
||
| `indent`, `rightIndent`, `firstLineIndent`, `hangingIndent` | Indentation |
|
||
| `spaceBefore`, `spaceAfter`, `lineSpacing` | Spacing |
|
||
| `keepNext`, `keepLines`, `widowControl` | Pagination Flags |
|
||
| `bold`, `italic`, `color`, `size`, `highlight` (paragraph-level) | Paragraph-Level Run Formatting |
|
||
| `shading.fill`, `shd` | Shading |
|
||
| `markRPr.*` (full set) | Paragraph-Mark Formatting |
|
||
| `outlineLvl` | Outline Level |
|
||
| `strike`, `underline`, `underline.color` (paragraph-level) | Paragraph Strike & Underline |
|
||
| `bold.cs`, `italic.cs`, `size.cs`, `direction` | Complex-Script |
|
||
| `contextualSpacing`, `lineRule`, `pageBreakBefore`, `wordWrap` | Spacing & Pagination Extras |
|
||
| `firstLineChars`, `hangingChars` | Chars-Based Indent |
|
||
| `font`, `font.latin/ea/cs`, theme fonts | Fonts |
|
||
| `style`, `rStyle` | Styles |
|
||
| `shading.val`, `shading.fill`, `shading.color` | Shading Variants |
|
||
| `tabs` | Tab Stops |
|
||
| `framePr.*` (w/h/wrap/hAnchor/vAnchor/hSpace/vSpace) | Text Frame |
|
||
| `border` (whole-box pBdr) | Paragraph Borders |
|
||
| `textAlignment` | Vertical Text Alignment |
|
||
| `kinsoku`, `autoSpaceDE`, `autoSpaceDN`, `overflowPunct`, `topLinePunct` | EastAsian Typography |
|
||
| `suppressLineNumbers`, `suppressAutoHyphens`, `mirrorIndents`, `adjustRightInd`, `snapToGrid` | Line & Indent Flags |
|
||
| `divId`, `textboxTightWrap` | Web / Textbox Hints |
|
||
| `listStyle`, `start`, `numId`, `numLevel` | List Numbering |
|
||
|
||
## Inspect the Generated File
|
||
|
||
```bash
|
||
# List every paragraph path
|
||
officecli query paragraph-formatting.docx paragraph
|
||
|
||
# Inspect a paragraph's full property set
|
||
officecli get paragraph-formatting.docx "/body/p[5]"
|
||
|
||
# Check the paragraph-mark formatting of a specific paragraph
|
||
officecli get paragraph-formatting.docx "/body/p[20]"
|
||
|
||
# Find all paragraphs with a shading fill set
|
||
officecli query paragraph-formatting.docx paragraph --find shading.fill
|
||
```
|