iofficeai--officecli/examples/word/charts.md

Word Charts Showcase

This demo consists of four files that work together:

• charts.sh — CLI script that calls officecli to build the document. Each chart is preceded by a # Features: comment listing the properties it exercises.
• charts.py — Python SDK twin (officecli-sdk). One resident, all paragraphs and charts shipped over the named pipe in a single doc.batch(...).
• charts.docx — the generated document: 14 inline charts, each under its own heading.
• charts.md — this file. Maps each chart to the features it demonstrates.

How charts work in Word

Unlike Excel (where a chart pulls a dataRange out of a worksheet grid), a Word chart is an inline DrawingML object anchored on a paragraph, and it carries its data inline:

officecli add file.docx /body/p[N] --type chart \
  --prop chartType=column \
  --prop 'data=East:120,135,148;West:110,118,130' \
  --prop categories="Q1,Q2,Q3"

Data can be given three ways (same as pptx/xlsx charts):

• data="Name1:1,2,3;Name2:4,5,6" — inline shorthand, one series per ;
• series1="Name:1,2,3" / series2=... — one prop per series
• series1.name= / series1.values= — dotted per-series keys

Word has no worksheet to reference, so inline data is idiomatic — there is no dataRange.

Addressing charts

You add a chart at its host paragraph (/body/p[N]), but once created the chart is addressed document-globally as /chart[M] for get / set / query — not /body/p[N]/chart[M]:

officecli add   file.docx /body/p[4] --type chart --prop chartType=pie ...
officecli query file.docx chart              # lists /chart[1], /chart[2], ...
officecli get   file.docx '/chart[1]'        # read one chart back
officecli set   file.docx '/chart[1]' --prop title="New Title"

Regenerate

cd examples/word
bash charts.sh            # CLI
# or:
python3 charts.py         # Python SDK twin
# → charts.docx

Charts

Each chart sits under a Heading2 paragraph naming its demo. Extended cx:chart types (funnel, treemap, waterfall) are supported alongside the classic DrawingML c:chart types.

1. Column — axis titles, scaling & gridlines

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=column \
  --prop 'data=East:120,135,148,162;West:110,118,130,145;South:95,108,115,128' \
  --prop categories="Q1,Q2,Q3,Q4" \
  --prop colors=4472C4,ED7D31,70AD47 \
  --prop catTitle=Quarter --prop axisTitle="Revenue (K)" \
  --prop axisMin=0 --prop axisMax=200 --prop axisNumFmt="#,##0" \
  --prop gridlines=D9D9D9:0.5:dot --prop legend=bottom \
  --prop width=16cm --prop height=9cm

Features: chartType=column, data, categories, colors, catTitle, axisTitle, axisMin, axisMax, axisNumFmt, gridlines, legend, width/height

2. Bar — gap width & data labels

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=bar \
  --prop 'data=Units:320,280,410,190,360' \
  --prop categories="Laptop,Phone,Tablet,Watch,Buds" \
  --prop gapwidth=80 \
  --prop dataLabels=value --prop labelPos=outsideEnd \
  --prop labelfont=9:333333:Calibri --prop legend=none

Features: chartType=bar, gapwidth, dataLabels=value, labelPos, labelfont (size:color:name)

3. Line — markers, smoothing & drop lines

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=line \
  --prop 'data=2023:120,180,210,250,280,310;2024:150,220,260,300,340,380' \
  --prop categories="Jan,Feb,Mar,Apr,May,Jun" \
  --prop marker=circle:6 --prop smooth=true \
  --prop droplines=808080:0.5 --prop linewidth=2 --prop legend=bottom

Features: chartType=line, marker (symbol:size:color), smooth, droplines, linewidth

4. Pie — percent labels & slice explosion

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=pie \
  --prop 'data=Share:42,28,18,12' \
  --prop categories="Alpha,Beta,Gamma,Other" \
  --prop dataLabels=percent --prop explosion=8 \
  --prop firstSliceAngle=90 --prop legend=right

Features: chartType=pie, dataLabels=percent, explosion, firstSliceAngle, colors

5. Area — gradient fill (areafill)

areafill is a docx-specific shortcut: a solid color or gradient (c1-c2[:angle]) applied to every series shape. Readback surfaces as gradient.

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=area \
  --prop 'data=Visits:20,35,30,55,48,70,65' \
  --prop categories="Mon,Tue,Wed,Thu,Fri,Sat,Sun" \
  --prop areafill=4472C4-A5C8FF:90 \
  --prop gridlines=E0E0E0:0.5:solid --prop legend=none

Features: chartType=area, areafill (gradient), gridlines

6. Scatter — smoothMarker style

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=scatter \
  --prop series1="Latency:12,18,27,41,60,88" \
  --prop categories="10,20,40,80,160,320" \
  --prop scatterstyle=smoothMarker --prop marker=diamond:7:C00000 \
  --prop catTitle="Concurrent Users" --prop axisTitle="ms"

Features: chartType=scatter, scatterstyle, marker, catTitle, axisTitle

7. Radar — filled style (radarstyle)

radarstyle is a docx-specific shortcut for the radar subtype (standard/marker/filled).

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=radar \
  --prop 'data=Model A:4,5,3,4,5;Model B:5,3,4,5,3' \
  --prop categories="Speed,Battery,Camera,Price,Display" \
  --prop radarstyle=filled --prop colors=4472C4,ED7D31 \
  --prop transparency=40 --prop legend=bottom

Features: chartType=radar, radarstyle=filled, transparency, colors

8. Doughnut — hole size & percent labels

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=doughnut \
  --prop 'data=Budget:35,25,20,20' \
  --prop categories="R&D,Sales,Ops,Admin" \
  --prop holeSize=55 --prop dataLabels=percent --prop legend=right

Features: chartType=doughnut, holeSize, dataLabels=percent, colors

9. Stock — high / low / close series

The three ordered series map to High, Low, Close. hilowlines connects the high/low extremes.

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=stock \
  --prop series1="High:32,35,34,38,37" \
  --prop series2="Low:28,29,30,32,33" \
  --prop series3="Close:30,34,31,37,35" \
  --prop categories="Mon,Tue,Wed,Thu,Fri" --prop hilowlines=true

Features: chartType=stock, ordered series, hilowlines

10. Combo — column + line on secondary axis

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=combo \
  --prop series1="Revenue:120,180,250,310,380" \
  --prop series2="Growth %:50,33,39,24,23" \
  --prop categories="2021,2022,2023,2024,2025" \
  --prop combotypes="column,line" --prop secondaryaxis=2 \
  --prop colors=2E75B6,C00000

Features: chartType=combo, combotypes (one type per series), secondaryaxis

11. Column — display units & rounded corners

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=column \
  --prop 'data=Revenue:12000,18500,22000,31000,45000' \
  --prop categories="2021,2022,2023,2024,2025" \
  --prop dispUnits=thousands --prop axisNumFmt="#,##0" \
  --prop roundedcorners=true --prop chartFill=F8F8F8 \
  --prop title.font=Georgia --prop title.size=15 \
  --prop title.color=1F4E79 --prop title.bold=true

Features: dispUnits, roundedcorners, chartFill, title.font/.size/ .color/.bold

12. Funnel — extended (cx) chart

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=funnel \
  --prop 'data=Stage:1000,720,430,210,95' \
  --prop categories="Visitors,Leads,MQL,SQL,Won"

Features: chartType=funnel (extended cx:chart)

13. Treemap — extended (cx) chart

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=treemap \
  --prop 'data=Size:420,310,180,90,45' \
  --prop categories="Video,Images,Docs,Audio,Other"

Features: chartType=treemap (extended cx:chart)

14. Waterfall — increase / decrease / total colors

officecli add charts.docx /body/p[N] --type chart \
  --prop chartType=waterfall \
  --prop 'data=Cash:100,-30,50,-20,80' \
  --prop categories="Start,Q1,Q2,Q3,End" \
  --prop increaseColor=00AA00 --prop decreaseColor=C00000 --prop totalColor=4472C4

Features: chartType=waterfall (extended cx:chart), increaseColor, decreaseColor, totalColor (all add-time only)

Complete Feature Coverage

Feature	Chart
Classic types: column, bar, line, pie, area, scatter, radar, doughnut, stock, combo	1–10
Extended (cx) types: funnel, treemap, waterfall	12–14
Data input: data (shorthand), series{N}, categories	all
Colors: colors, areafill (gradient)	1–8, 5
Axis scaling: axisMin, axisMax, axisNumFmt, dispUnits	1, 11
Axis titles: catTitle, axisTitle	1, 6
Gridlines: gridlines (styled)	1, 5
Data labels: dataLabels (value/percent), labelPos, labelfont	2, 4, 8
Legend: position (bottom/right/none)	all
Line/scatter: marker, smooth, droplines, linewidth, scatterstyle	3, 6
Pie/doughnut: explosion, firstSliceAngle, holeSize	4, 8
Radar: radarstyle=filled	7
Stock: ordered High/Low/Close series, hilowlines	9
Combo: combotypes, secondaryaxis	10
Fills & effects: chartFill, transparency, roundedcorners	7, 11
Title styling: title.font/.size/.color/.bold	11
Bar geometry: gapwidth	2
Waterfall colors: increaseColor, decreaseColor, totalColor	14
Sizing: width, height (cm/in/pt/EMU)	all

Inspect the Generated File

officecli query charts.docx chart              # list all 14 charts
officecli get   charts.docx '/chart[1]'        # full column chart props
officecli get   charts.docx '/chart[5]'        # area chart — areafill → gradient
officecli get   charts.docx '/chart[14]'       # waterfall — increase/decrease/total colors