word textbox

Word: Textbox

DrawingML text box (w:drawing → wps:wsp with txBox="1"). Carries an inner wps:txbx body that can hold paragraphs and runs.

Path: /body/textbox[N]

Operations

• add, set, get, remove
• Get returns raw XML preview only — no structured Format readback of any property below. Use get --depth N to inspect the raw XML, or raw for the full part.

Add properties

Property	Description
text	Initial text content (single run shortcut)
width / height	Box size (cm/in/pt/EMU). Defaults ~6cm × ~2.4cm.
geometry / shape	Shape preset outline (rect, roundRect, ellipse, …)
wrap	Text-wrap mode of surrounding body text: square, tight, through, topAndBottom, behind, front, none
hAlign / halign	Relative horizontal alignment (<wp:align>): left, center, right, inside, outside. Ignored if anchor.x is also set.
vAlign / valign	Relative vertical alignment: top, center, bottom, inside, outside. Ignored if anchor.y is also set.
hRelative / hrelative	What horizontal position is measured from: margin, page, column, character, leftMargin, rightMargin, insideMargin, outsideMargin
vRelative / vrelative	What vertical position is measured from: margin, page, paragraph, line, topMargin, bottomMargin, insideMargin, outsideMargin
anchor.x / hposition	Horizontal position offset from the hRelative origin
anchor.y / vposition	Vertical position offset from the vRelative origin
fill / fillcolor	Fill color (hex/name), or none for no fill
fill.gradient / gradient	Gradient fill spec, overrides solid fill
fill.opacity / opacity	Fill opacity percentage
line.color / linecolor	Outline color
line.width / linewidth	Outline width
line.style / linestyle	Outline dash style
inset.left / inset.top / inset.right / inset.bottom	Internal text padding. Defaults: left/right 0.1in, top/bottom 0.05in.
textDirection / vert	Text flow direction inside the box (e.g. vertical)
textAnchor	Vertical anchoring of text within the box (top/center/bottom)
autoFit	Bool — resize the box to fit its text (<a:spAutoFit/>)
rotation / rot	Rotation in degrees
shadow	Drop-shadow preset
alt / name	Accessibility / object name (docPr name). Default Text Box.

No x/y shorthand — position is anchor.x/anchor.y (or hAlign/vAlign for relative alignment), not bare x/y.

Set properties

Only a subset is settable on an existing textbox — everything else (position, rotation, text direction, wrap, alignment, insets, fit, alt text) is add-only:

Property	Description
width / height	Box size
geometry / shape	Shape preset outline
fill / fillcolor	Fill color, or none
line.color / line.width / line.style (and their lowercase aliases)	Outline

Examples

# Floating textbox at fixed position (anchor.x/anchor.y, not x/y)
officecli add report.docx /body --type textbox --prop anchor.x=2cm --prop anchor.y=4cm --prop hRelative=page --prop vRelative=page --prop width=8cm --prop height=3cm --prop fill=FFF2CC --prop text="Sidebar note"

# Rounded textbox with outline
officecli add report.docx /body --type textbox --prop geometry=roundRect --prop line.color=4472C4 --prop line.width=1pt --prop text="Pull-quote"

# Rotated vertical textbox with gradient
officecli add report.docx /body --type textbox \
  --prop rotation=15 --prop textDirection=eaVert \
  --prop fill.gradient="4472C4-ED7D31:45" \
  --prop text="标题"

# Resize an existing textbox (Set only touches size/geometry/fill/line)
officecli set report.docx /body/textbox[1] --prop width=10cm --prop fill=none

See Also

• Word: Shape — bare wps:wsp without text body
• Word Reference

---

Based on OfficeCLI v1.0.129