Charts and tables
Insert a native Word chart at a size you choose, change its data, series and type without losing the formatting the file already has, restyle it, and set the width and row heights of a table. Every example is a list of operations: save it as ops.json and run it with batch, or pass it as operations to execute_batch. These features arrived in version 0.5.3.
Insert a chart with a size and a description
widthIn and heightIn set the size in inches; widthEmu and heightEmu set it in EMU. Give one unit for each dimension, not both. A new two-dimensional chart is 6 by 2.6 inches, the allowed range is 0.1 to 22 inches, and a chart wider than the usable page width is inserted with a layoutWarning. altText is the description a screen reader reads.
[
{ "action": "chart", "operation": "insert", "anchor": "end", "id": "rev", "chartType": "column", "title": "Revenue",
"categories": ["Q1", "Q2", "Q3"],
"series": [{ "name": "North", "values": [4, 5, 7] }, { "name": "South", "values": [3, 4, 4] }],
"widthIn": 6, "heightIn": 3, "altText": "Revenue by quarter, North and South" }
]The style guide can set the defaults for every chart: a ## Charts section with Width, Height, 3D Width, 3D Height, Gridline Color, Font Family, Font Size and Title Size. A value in the operation beats the guide, and the guide beats the built-in default.
Change a chart in place
On chart update, a series list with more entries than the chart has adds series, removeSeries takes names or numbers and removes them, and a change among column, bar, stacked and percent types keeps the chart part and its formatting.
[
{ "action": "chart", "operation": "update", "target": "<chartNodeId>",
"series": [{ "name": "North", "values": [4, 5, 7] }, { "name": "South", "values": [3, 4, 4] }, { "name": "East", "values": [2, 3, 5] }] },
{ "action": "chart", "operation": "update", "target": "<chartNodeId>", "removeSeries": ["South"] },
{ "action": "chart", "operation": "update", "target": "<chartNodeId>", "chartType": "bar" }
]A chart node ID lasts for one session; read it again with inspect after you reopen the file. In a file written by Word, the chart part must be named word/charts/chart<number>.xml to be edited; the update says so when it is not.
What needs allowRebuild
Anything else that changes the structure of the chart (a different family such as column to pie, scatter, a combination chart, two-dimensional to three-dimensional) means writing the chart part again. ASTra does not do that silently. The call is refused before anything is written, and the refusal names what would be lost, for example a colour or a line width. Pass allowRebuild: true to accept it; the result then lists what the rebuild dropped under chartUpdates (formattingNotKept, styleNotApplied, updateMode).
[{ "action": "chart", "operation": "update", "target": "<chartNodeId>", "chartType": "pie", "allowRebuild": true }]Chart data and the embedded workbook
- A call that does not change data never touches the workbook stored inside the chart.
- A call that changes data needs a workbook that ASTra can prove it wrote: rebuilt from the stored data, it must be the same part for part. Any other workbook is refused unless you pass
allowRebuild: true. - A workbook that two charts share is refused or copied for the chart you update. A linked workbook is always refused.
Style a chart
The style key restyles an existing chart or sets the style on insert. The keys that came in 0.5.3:
titleFormat | Size (sizePt), bold and color of the existing title. Needs at least one of them, and a title to format. |
removeTitle | Update only. Removes the title and shows no automatic one. |
axis gridlineColor | Colour of the gridlines. |
series[].points[] | A colour for one point, counted from 1, in column, bar, pie, doughnut, line and scatter charts. |
chartFont | Font family and colour everywhere, and size everywhere except the title. |
bars | gapPercent and overlapPercent. |
lines | widthPt, smooth and showMarkers. |
chartArea, plotArea | fillColor and borderColor. |
axis labelSizePt, labelRotationDeg, showAxisLine | Axis labels and the axis line. |
[
{ "action": "chart", "operation": "update", "target": "<chartNodeId>",
"style": { "titleFormat": { "sizePt": 14, "bold": true, "color": "1E293B" },
"chartFont": { "family": "Calibri", "color": "334155" },
"bars": { "gapPercent": 60, "overlapPercent": 0 },
"plotArea": { "fillColor": "F8FAFC" } } }
]Impossible values are refused at the call with a message that names the key. trendline.series is now trendline.seriesNumbers, counted from 1; the old key is refused.
Table width and row heights
setTableWidth takes one of widthIn, widthPercent (of the text width, or of the parent cell for a nested table) or widthTwips. columns: "scale" (the default) resizes the columns in proportion and rewrites every cell width; columns: "keep" changes only the table width. setRowHeights takes heightIn or heightTwips with a rule of atLeast or exact; auto removes the height.
[
{ "action": "table", "operation": "setTableWidth", "target": "<tableNodeId>", "widthPercent": 100, "columns": "scale" },
{ "action": "table", "operation": "setRowHeights", "target": "<tableNodeId>", "heightIn": 0.4, "rule": "atLeast" }
]A floating table, a table whose cell spans do not add up, or a grid that cannot be trusted is refused and nothing is written. Percent widths use the real page: the paper size and the number of text columns of the section.
Known limits
- Word and LibreOffice draw a few chart details differently, for example a smoothed line in a combination chart and the legend of a one-series chart with coloured points. The MCP specification lists them.
- The charts, tables and layout of 0.5.3 are checked with the Open XML SDK, LibreOffice and by opening files in desktop Word. They are not part of the published benchmark.
- A chart node ID lasts for one session.