-
Notifications
You must be signed in to change notification settings - Fork 530
word numbering
Multi-level lists (numbered/bulleted) live under the /numbering part. OfficeCLI exposes the full Word numbering model via three element types:
-
abstractNum— a numbering template (per-level format, text, indent, fonts) -
num— a numbering instance that references an abstractNum (with optional per-level overrides) -
lvl— an individual level inside an abstractNum
A paragraph picks up numbering by setting numId (referencing a num) and ilvl (the level).
Path:
-
/numbering/abstractNum[@id=N]— numbering template -
/numbering/abstractNum[@id=N]/level[L]— single level (L = 0..8) -
/numbering/num[@id=N]— numbering instance
Positional indices /numbering/abstractNum[N] and /numbering/num[N] are accepted on Set and normalized to the canonical [@id=K] form.
officecli add report.docx /numbering --type abstractNum [--prop ...]
| Property | Description |
|---|---|
name |
Template name (returned in Get readback) |
type |
singleLevel, multilevel, hybridMultilevel, bullet
|
styleLink |
Style link target |
numStyleLink |
NumStyle link target |
| Sub-property | Description |
|---|---|
format |
decimal, lowerLetter, upperLetter, lowerRoman, upperRoman, bullet, none
|
text |
Level format string (e.g. %1., %1.%2., •) |
start |
Starting number |
indent |
Left indent (twips or unit-qualified: 0.5in, 1cm) |
hanging |
Hanging indent |
justification |
left, center, right
|
suff |
Suffix character: tab, space, nothing
|
font |
Font family for the marker |
size |
Marker font size (pt) |
color |
Marker font color (hex) |
bold |
Marker bold |
italic |
Marker italic |
lvlRestart |
Restart counter at this level |
isLgl |
Legal-style numbering |
Levels left unset cycle through decimal / lowerLetter / lowerRoman (or bullet glyphs for type=bullet) — same fallback as the high-level liststyle path.
# Multilevel template with custom level 0 + level 1 officecli add report.docx /numbering --type abstractNum --prop name="MyOutline" \ --prop type=multilevel \ --prop level0.format=decimal --prop "level0.text=%1." --prop level0.indent=0.5in \ --prop level1.format=lowerLetter --prop "level1.text=%2)" --prop level1.indent=1in # Bullet template officecli add report.docx /numbering --type abstractNum \ --prop type=bullet \ --prop level0.font=Symbol --prop "level0.text=●くろまる" \ --prop level1.font=Symbol --prop "level1.text=○しろまる"
officecli add report.docx /numbering --type num [--prop ...]
Three modes:
| Mode | Trigger | Behavior |
|---|---|---|
| A auto-create | No abstractNumId
|
Auto-creates a matching abstractNum from format/text/indent/type props (same builder as --type abstractNum) |
| B reuse template | abstractNumId=N |
References an existing abstractNum |
| C override starts |
start=N or startOverride.0..8=N
|
Per-level start overrides |
# Mode B: reuse existing template officecli add report.docx /numbering --type num --prop abstractNumId=3 # Mode C: per-level start overrides officecli add report.docx /numbering --type num \ --prop abstractNumId=3 \ --prop startOverride.0=5 --prop startOverride.1=1 # Mode A: auto-create template inline officecli add report.docx /numbering --type num \ --prop type=multilevel --prop level0.format=decimal
officecli add report.docx /numbering/abstractNum[@id=N] --type lvl --prop ilvl=L [--prop ...]| Property | Required | Description |
|---|---|---|
ilvl |
yes | Level index (0..8) |
start |
no | Starting number |
format, text, indent, hanging, justification, suff, font, size, color, bold, italic, lvlRestart, isLgl
|
no | Same as per-level dotted props above |
Set on /numbering/abstractNum[@id=N]/level[L] and /lvl[@ilvl=L] accept the same properties.
add --type style and set /styles/X accept numId and ilvl directly:
officecli set report.docx /styles/Heading1 --prop numId=3 --prop ilvl=0Paragraphs inheriting via pStyle then pick up numbering through ResolveNumPrFromStyle without their own numPr — the canonical Heading1..9 multi-level pattern in Word templates.
| Rejection | Error |
|---|---|
Paragraph numId references a missing <w:num>
|
Reference rejected at Set time (no zombie references) |
--type style with numId=N where N has no <w:num>
|
Rejected at add and set |
Negative numId on paragraph |
Rejected |
ilvl outside 0..8 on paragraph Set |
Clamped to range |
Removing a num clears any paragraph numPr references that pointed at it |
Automatic cleanup |
Selectors numbering, abstractNum, num are supported:
officecli query report.docx 'abstractNum' officecli query report.docx 'num[@id=5]'
/numbering/num[@id=N], /numbering/abstractNum[@id=N], and /numbering/abstractNum[@id=N]/level[L] return canonical Format dicts. abstractNum Get returns a Children list of all 9 levels.
officecli get report.docx '/numbering/abstractNum[@id=2]' officecli get report.docx '/numbering/abstractNum[@id=2]/level[0]' officecli get report.docx '/numbering/num[@id=5]'
Tab stops can be added to a paragraph or to a paragraph/table style:
officecli add report.docx /body/p[3] --type tab \ --prop pos=720 --prop val=left --prop leader=dot officecli add report.docx /styles/MyStyle --type tab --prop pos=2880 --prop val=right
| Property | Description |
|---|---|
pos |
Tab position (twips or unit-qualified) |
val |
Tab type: left, center, right, decimal, bar, clear, num
|
leader |
Leader: none, dot, hyphen, underscore, heavy, middleDot
|
Both val and leader are validated against an allowlist with friendly error messages.
- Style — Paragraph and run styles
-
Paragraph set —
numIdandilvlon individual paragraphs - Word Reference — All Word elements
Based on OfficeCLI v1.0.64