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
297 lines
10 KiB
Markdown
297 lines
10 KiB
Markdown
# 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**:
|
||
|
||
```bash
|
||
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]`:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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`.
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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`).
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
```
|