@office-kit/pptx 0.16.1 → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +84 -0
- package/README.md +139 -58
- package/dist/{api-Dt6q_IAv.js → api-0CdoUwvg.js} +2515 -480
- package/dist/api-0CdoUwvg.js.map +1 -0
- package/dist/{index-mFv1-sf4.d.ts → index-bswJVsv2.d.ts} +350 -10
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/node.d.ts +2 -2
- package/dist/node.js +2 -2
- package/package.json +1 -1
- package/dist/api-Dt6q_IAv.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,89 @@
|
|
|
1
1
|
# @office-kit/pptx
|
|
2
2
|
|
|
3
|
+
## 0.18.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 7e89e62: Validate enum inputs at authoring boundaries and throw a descriptive `RangeError`
|
|
8
|
+
instead of writing invalid PowerPoint XML or silently selecting another mode.
|
|
9
|
+
|
|
10
|
+
Affected APIs:
|
|
11
|
+
|
|
12
|
+
- Shapes: `addSlideShape` preset and text anchor, including calls through the TSX DSL.
|
|
13
|
+
- Strokes and fills: `setShapeStrokeDash`, `setShapeStrokeCap`, `setShapeStrokeJoin`,
|
|
14
|
+
`setShapeStrokeCompound`, `setShapeStrokeArrow` (end, type, width, length), and
|
|
15
|
+
`setShapeGradientFill` path.
|
|
16
|
+
- Text: `setShapeAlignment`, `setParagraphAlignment`, `setShapeTextAnchor`,
|
|
17
|
+
`setShapeTextAutoFit`, `setShapeTextWrap`, `setShapeTextDirection`, `setShapeBullets`,
|
|
18
|
+
`setParagraphBullet`, and `setShapeText` bullets; `setShapeTextFormat`,
|
|
19
|
+
`setShapeRunFormat`, and `setShapeParagraphs` formatting and alignment.
|
|
20
|
+
- Tables: `setTableCellAlignment`, `setTableCellTextFormat`, `setTableCellParagraphs`,
|
|
21
|
+
`setTableCellTextDirection`, `setTableCellAnchor`, and `setTableCellBorders` dash.
|
|
22
|
+
- Charts: `addSlideChart` and `setChartSpec` kind, grouping, axes, legend, layout,
|
|
23
|
+
data labels, series markers, line dash, trendlines, error bars, and chart styles.
|
|
24
|
+
- Slides: `setSlideSize` type, `setSlideTransition` speed and split orientation,
|
|
25
|
+
and `setShapeAnimation` effect.
|
|
26
|
+
|
|
27
|
+
Previously accepted inputs such as preset `'rounded-rect'`, alignment `'middle'`,
|
|
28
|
+
stroke dash `'dotted'`, text auto-fit `'shrink'`, and auto-numbering `'bogus'` now
|
|
29
|
+
throw `RangeError`. Underline and strike strings must be exact XSD tokens:
|
|
30
|
+
use `'sng'` / `'sngStrike'` (or `true`), not `'single'`. Existing JavaScript
|
|
31
|
+
`null` values for underline, strike, and cap still remove the corresponding
|
|
32
|
+
attributes; their TypeScript types are unchanged.
|
|
33
|
+
|
|
34
|
+
Unknown chart kinds now throw `RangeError: addSlideChart: kind: … is not one of: …`
|
|
35
|
+
instead of `Error: unsupported chart kind: …`; `setChartSpec` uses its own API name
|
|
36
|
+
in the new message. Code that checks the exception class or message should adapt.
|
|
37
|
+
|
|
38
|
+
Valid ECMA-376 shape presets remain supported, including presets outside the
|
|
39
|
+
TypeScript autocomplete list. Rejected bullets and transitions preserve existing
|
|
40
|
+
content, and rejected table-cell alignment or text-format enums do not create a
|
|
41
|
+
text body.
|
|
42
|
+
|
|
43
|
+
### Patch Changes
|
|
44
|
+
|
|
45
|
+
- 7e89e62: fix: Preserve valid table XML when setting alignment on a covered merged cell whose text was dropped. Recreated text bodies now include the required paragraph, so the alignment is applied and survives saving and reloading.
|
|
46
|
+
- 64fa3c7: Fix nested list indentation when changing a paragraph's level after applying bullets or numbering, including after copying or reloading a presentation. Indentation that differs from the previous level's default pair is preserved.
|
|
47
|
+
|
|
48
|
+
## 0.17.0
|
|
49
|
+
|
|
50
|
+
### Minor Changes
|
|
51
|
+
|
|
52
|
+
- 71deec5: feat: author every chart type — scatter, bubble, radar, stock, surface, the 3-D variants and pie-of-pie
|
|
53
|
+
|
|
54
|
+
`addSlideChart` / `setChartSpec` now write all sixteen plot types of ECMA-376, and `getShapeChartSpec` reads every one of them back.
|
|
55
|
+
|
|
56
|
+
- `kind: 'scatter' | 'bubble' | 'radar'` are authorable (they used to throw "read-only"). Scatter and bubble series carry their own `xValues` (and `bubbleSizes`); the embedded workbook lays them out per series so "Edit data" opens onto the right cells.
|
|
57
|
+
- New kinds `'stock'` (3 series: high, low, close; or 4 with open first, drawn as candlesticks) and `'surface'` (`surfaceContour` for the top-down contour plot, `surfaceWireframe` for the mesh).
|
|
58
|
+
- 3-D is a modifier: `view3D: { rotX, rotY, rightAngleAxes, perspective, depthPercent, heightPercent }` on `bar` / `column` / `line` / `area` / `pie` selects the 3-D element, with `bar3DShape` (cylinder, cone, pyramid, …), `gapDepthPct` and `seriesAxis`. `bubble3D` shades bubbles as spheres.
|
|
59
|
+
- `ofPie` turns a pie into a pie-of-pie / bar-of-pie chart.
|
|
60
|
+
- Per series: `errorBars` / `xErrorBars` (fixed, percentage, standard deviation, standard error, custom), `fillOpacity`.
|
|
61
|
+
- Per chart: `dataTable`, `upDownBars`, `categoryAxisDate` (date axis with time units), `categoryGroupLevels` (multi-level category labels), `categoryAxisScaling` (the x axis of scatter / bubble charts, or a date axis' range), `plotAreaLayout` / `titleLayout` / `legend.layout` (manual placement), `valueAxisLineHidden` / `categoryAxisLineHidden`, `valueAxis.displayUnitsLabel`.
|
|
62
|
+
- Data labels gain `showBubbleSize`, `showLegendKey`, `fillColor`, and per-point `text` (a literal label, e.g. naming one scatter point).
|
|
63
|
+
- A spec whose fields contradict each other (`view3D` on a scatter chart, error bars on a pie, a date axis with non-numeric categories, …) throws with a message naming the field, instead of writing a chart PowerPoint would repair.
|
|
64
|
+
|
|
65
|
+
Behavior changes when reading existing decks:
|
|
66
|
+
|
|
67
|
+
- A stock chart now reads as `kind: 'stock'` (was `'line'`) and a surface chart as `kind: 'surface'` (was `'column'`). `getPresentationChartKindCounts` has the two new keys.
|
|
68
|
+
- 3-D charts still read as their flat kind, now with `view3D` set, so `setChartSpec(chart, getShapeChartSpec(shape))` no longer flattens a 3-D chart.
|
|
69
|
+
- fix: for scatter / bubble charts `valueAxis` (and the other `valueAxis*` fields) described the **x** axis. They now describe the y axis; the x axis reads into `categoryAxis*` and `categoryAxisScaling`.
|
|
70
|
+
- fix: charts with more than 25 series wrote workbook references past column `Z` as invalid cell addresses.
|
|
71
|
+
|
|
72
|
+
`@office-kit/pptx-preview` draws stock charts as lines and surface charts as columns (as before), and honors `categoryAxisScaling` on scatter / bubble charts.
|
|
73
|
+
|
|
74
|
+
- 71deec5: feat: embed video, audio and online video with `addSlideMedia`, and read them back with `getShapeMedia`
|
|
75
|
+
|
|
76
|
+
- `addSlideMedia(slide, { kind: 'video' | 'audio', data, ... })` embeds a clip from bytes; `{ kind: 'online', url }` links an online video. YouTube watch / `youtu.be` / shorts URLs are rewritten to the embed URL; any other `http(s)` URL is stored as given, and anything else throws.
|
|
77
|
+
- The container is detected from the bytes (mp4, m4v, mov, webm, avi, wmv, mp3, wav, m4a, ogg, wma); pass `format` to override. An undetectable clip, an unreadable `poster`, or a bad URL throws before anything is added to the package.
|
|
78
|
+
- The new shape is a picture showing the poster frame: `setShapeImage` / `getShapeImageBytes` replace and read it. Without `poster`, a small built-in play-button image is used.
|
|
79
|
+
- The slide gets the `<p:video>` / `<p:audio>` time node PowerPoint writes itself, which is what makes the play controls appear in the slide show. Identical clip bytes are stored once per deck.
|
|
80
|
+
- `getShapeMedia(shape)` returns `{ kind: 'video' | 'audio', partName, contentType, bytes }` or `{ kind: 'online', url }`, also for media authored by PowerPoint, PptxGenJS or python-pptx. `findShapesWithMedia(slide)` lists a slide's clips.
|
|
81
|
+
- `@office-kit/pptx-dsl` gains a `Media` element with the same `kind` / `data` / `url` / `poster` props. It now requires `@office-kit/pptx` >= 0.17.0.
|
|
82
|
+
- `copyShape` gives the copied clip its own time node, `removeShape` / `clearSlideShapes` remove it, and `importSlide` now carries video / audio parts (copied once per clip) and online-video links across decks — previously an imported slide with media was left with dangling relationships.
|
|
83
|
+
- `setShapeAnimation` now works on a slide that holds a clip but no animation yet (it used to throw), and `clearSlideAnimations` keeps clips' time nodes instead of removing their play controls.
|
|
84
|
+
- fix: `duplicateSlide` copied a slide's video / audio bytes for every duplicate, because the library's video / audio / media relationship-type constants did not match the URIs PowerPoint writes. Clips are now shared between the original and the duplicate, as documented.
|
|
85
|
+
- `validatePresentation` reports a video / audio relationship whose part is missing, and a media time node whose shape is no longer on the slide.
|
|
86
|
+
|
|
3
87
|
## 0.16.1
|
|
4
88
|
|
|
5
89
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -34,9 +34,9 @@ For declarative TSX authoring, use the companion
|
|
|
34
34
|
template editing, a local watch preview and PPTX export, with no React or Vue
|
|
35
35
|
runtime. The dev package initializes a project with VSCode tasks and a
|
|
36
36
|
`CLAUDE.md` authoring guide. Start with the
|
|
37
|
-
[
|
|
38
|
-
|
|
39
|
-
|
|
37
|
+
[authoring guide](https://office-kit.github.io/pptx/docs/authoring): install the
|
|
38
|
+
Claude Code skill and describe your presentation. The agent handles project
|
|
39
|
+
setup, preview and export using the published npm packages.
|
|
40
40
|
|
|
41
41
|
- **It reads as well as it writes.** Open a deck made in PowerPoint, Keynote,
|
|
42
42
|
or Google Slides, change it, and save it. Every setter has a getter, and
|
|
@@ -50,9 +50,8 @@ source-checkout installation.
|
|
|
50
50
|
breaks Keynote is treated as a bug.
|
|
51
51
|
- **One ESM bundle for Node and the browser.** No `fs`, `Buffer`, or `zlib` on
|
|
52
52
|
the hot path, and one runtime dependency ([fflate](https://github.com/101arrowz/fflate), for ZIP).
|
|
53
|
-
- **You ship only what you import.** The API
|
|
54
|
-
|
|
55
|
-
142 KB. CI fails if either grows past its cap (`test/tree-shake.test.ts`).
|
|
53
|
+
- **You ship only what you import.** The API uses side-effect-free functions.
|
|
54
|
+
CI checks tree-shaking and bundle-size limits (`test/tree-shake.test.ts`).
|
|
56
55
|
- **Types follow the spec.** The model mirrors ECMA-376 Part 1 §19
|
|
57
56
|
(PresentationML). Positions are branded `Emu` numbers, so inches and points
|
|
58
57
|
cannot be mixed up by accident.
|
|
@@ -67,26 +66,25 @@ PptxGenJS cannot open it.
|
|
|
67
66
|
|
|
68
67
|
Compared against PptxGenJS 4.0.1:
|
|
69
68
|
|
|
70
|
-
| | `@office-kit/pptx`
|
|
71
|
-
| --------------------------------- |
|
|
72
|
-
| Open and edit an existing `.pptx` | ✅ Load, change, save; unknown parts are preserved
|
|
73
|
-
| Templates | Any `.pptx` a designer made in PowerPoint
|
|
74
|
-
| Read back what is in a deck | ✅ Every setter has a getter, plus deck-wide queries
|
|
75
|
-
| API shape | Tree-shakeable functions (`addSlideChart(slide, …)`)
|
|
76
|
-
| Module formats | ESM only
|
|
77
|
-
| Runtime dependencies | 1 (`fflate`)
|
|
78
|
-
| Slide transitions | ✅
|
|
79
|
-
| Animations | ✅ Four entrance / exit presets
|
|
80
|
-
| Comments | ✅
|
|
81
|
-
| Chart types you can author |
|
|
82
|
-
| Audio, video, YouTube embeds |
|
|
83
|
-
| HTML `<table>` to slides | ❌
|
|
84
|
-
| Render a slide to an image | ✅ SVG and PNG, via [`@office-kit/pptx-preview`](packages/preview)
|
|
85
|
-
| How output is checked | Open XML SDK validator and ECMA-376 XSDs, in CI
|
|
86
|
-
|
|
87
|
-
**Pick PptxGenJS** if you only ever generate new decks and need
|
|
88
|
-
|
|
89
|
-
`<script>`-tag build.
|
|
69
|
+
| | `@office-kit/pptx` | PptxGenJS |
|
|
70
|
+
| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
71
|
+
| Open and edit an existing `.pptx` | ✅ Load, change, save; unknown parts are preserved | ❌ Creates new files only |
|
|
72
|
+
| Templates | Any `.pptx` a designer made in PowerPoint | Slide masters defined in code (`defineSlideMaster`) |
|
|
73
|
+
| Read back what is in a deck | ✅ Every setter has a getter, plus deck-wide queries | ❌ The API is write-only |
|
|
74
|
+
| API shape | Tree-shakeable functions (`addSlideChart(slide, …)`) | One class with methods (`slide.addChart(…)`) |
|
|
75
|
+
| Module formats | ESM only | ESM, CommonJS, and a script-tag bundle |
|
|
76
|
+
| Runtime dependencies | 1 (`fflate`) | 4 (`jszip`, `image-size`, `https`, `@types/node`) |
|
|
77
|
+
| Slide transitions | ✅ | ❌ |
|
|
78
|
+
| Animations | ✅ Four entrance / exit presets | ❌ |
|
|
79
|
+
| Comments | ✅ | ❌ (speaker notes only) |
|
|
80
|
+
| Chart types you can author | ✅ All 16 ECMA-376 plot types, incl. 3-D, stock, surface, pie-of-pie; combos, error bars, data table, date axis | Bar, line, area, pie, doughnut, scatter, bubble, radar, 3-D bar / bubble; combos |
|
|
81
|
+
| Audio, video, YouTube embeds | ✅ Embedded from bytes (Node and browser), with read-back (`getShapeMedia`); clips de-duplicated per deck | ✅ From a path or base64; write-only |
|
|
82
|
+
| HTML `<table>` to slides | ❌ | ✅ With automatic paging |
|
|
83
|
+
| Render a slide to an image | ✅ SVG and PNG, via [`@office-kit/pptx-preview`](packages/preview) | ❌ |
|
|
84
|
+
| How output is checked | Open XML SDK validator and ECMA-376 XSDs, in CI | Manual runs in PowerPoint and other apps before a release |
|
|
85
|
+
|
|
86
|
+
**Pick PptxGenJS** if you only ever generate new decks and need HTML-table
|
|
87
|
+
import, CommonJS, or a `<script>`-tag build.
|
|
90
88
|
|
|
91
89
|
**Pick `@office-kit/pptx`** if a template, an existing deck, or a validation
|
|
92
90
|
requirement is involved, or if you need to read a deck as well as write one.
|
|
@@ -95,13 +93,14 @@ The two also work together. Decks written by PptxGenJS are part of this
|
|
|
95
93
|
library's test fixtures (`test/pptxgenjs-compat.test.ts`), so you can generate
|
|
96
94
|
with PptxGenJS and post-process the result here.
|
|
97
95
|
|
|
98
|
-
### The same slide
|
|
96
|
+
### The same slide with PptxGenJS, the core API, and TSX
|
|
99
97
|
|
|
100
98
|
```ts
|
|
101
99
|
// PptxGenJS
|
|
102
100
|
import pptxgen from 'pptxgenjs';
|
|
103
101
|
|
|
104
102
|
const pptx = new pptxgen();
|
|
103
|
+
pptx.layout = 'LAYOUT_WIDE';
|
|
105
104
|
const slide = pptx.addSlide();
|
|
106
105
|
slide.addText('Q3 Review', { x: 1, y: 0.5, w: 8, h: 1, fontSize: 28, bold: true });
|
|
107
106
|
slide.addChart(
|
|
@@ -119,28 +118,21 @@ await pptx.writeFile({ fileName: 'out.pptx' });
|
|
|
119
118
|
```
|
|
120
119
|
|
|
121
120
|
```ts
|
|
122
|
-
// @office-kit/pptx
|
|
123
|
-
import
|
|
124
|
-
addBlankSlide,
|
|
125
|
-
addSlideChart,
|
|
126
|
-
addSlideTextBox,
|
|
127
|
-
createPresentation,
|
|
128
|
-
inches,
|
|
129
|
-
setShapeTextFormat,
|
|
130
|
-
} from '@office-kit/pptx';
|
|
131
|
-
import { savePresentationToFile } from '@office-kit/pptx/node';
|
|
121
|
+
// @office-kit/pptx: the Node barrel includes the core API and file helpers.
|
|
122
|
+
import * as pptx from '@office-kit/pptx/node';
|
|
132
123
|
|
|
133
|
-
const
|
|
134
|
-
const
|
|
135
|
-
const
|
|
124
|
+
const { inches } = pptx;
|
|
125
|
+
const pres = pptx.createPresentation();
|
|
126
|
+
const slide = pptx.addBlankSlide(pres);
|
|
127
|
+
const title = pptx.addSlideTextBox(slide, {
|
|
136
128
|
x: inches(1),
|
|
137
129
|
y: inches(0.5),
|
|
138
130
|
w: inches(8),
|
|
139
131
|
h: inches(1),
|
|
140
132
|
text: 'Q3 Review',
|
|
141
133
|
});
|
|
142
|
-
setShapeTextFormat(title, { size: 28, bold: true });
|
|
143
|
-
addSlideChart(slide, {
|
|
134
|
+
pptx.setShapeTextFormat(title, { size: 28, bold: true });
|
|
135
|
+
pptx.addSlideChart(slide, {
|
|
144
136
|
x: inches(1),
|
|
145
137
|
y: inches(1.5),
|
|
146
138
|
w: inches(8),
|
|
@@ -151,13 +143,42 @@ addSlideChart(slide, {
|
|
|
151
143
|
series: [{ name: 'Revenue', values: [120, 180] }],
|
|
152
144
|
},
|
|
153
145
|
});
|
|
154
|
-
await savePresentationToFile(pres, 'out.pptx');
|
|
146
|
+
await pptx.savePresentationToFile(pres, 'out.pptx');
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```tsx
|
|
150
|
+
// @office-kit/pptx-dsl — deck.tsx
|
|
151
|
+
import { Presentation, Slide, Text, Chart } from '@office-kit/pptx-dsl';
|
|
152
|
+
|
|
153
|
+
export default (
|
|
154
|
+
<Presentation>
|
|
155
|
+
<Slide>
|
|
156
|
+
<Text x={1} y={0.5} width={8} height={1} size={28} bold>
|
|
157
|
+
Q3 Review
|
|
158
|
+
</Text>
|
|
159
|
+
<Chart
|
|
160
|
+
x={1}
|
|
161
|
+
y={1.5}
|
|
162
|
+
width={8}
|
|
163
|
+
height={4}
|
|
164
|
+
spec={{
|
|
165
|
+
kind: 'column',
|
|
166
|
+
categories: ['Q1', 'Q2'],
|
|
167
|
+
series: [{ name: 'Revenue', values: [120, 180] }],
|
|
168
|
+
}}
|
|
169
|
+
/>
|
|
170
|
+
</Slide>
|
|
171
|
+
</Presentation>
|
|
172
|
+
);
|
|
155
173
|
```
|
|
156
174
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
175
|
+
Save the TSX example as `deck.tsx` in an
|
|
176
|
+
[initialized authoring project](https://office-kit.github.io/pptx/docs/tsx), then
|
|
177
|
+
run `npx --no-install office-pptx build deck.tsx --out out.pptx`.
|
|
178
|
+
|
|
179
|
+
The core API uses explicit units (`inches(1)`, `cm(2.5)`, `pt(12)`). The DSL uses
|
|
180
|
+
inches for numeric geometry and points for font sizes, and compiles to the same
|
|
181
|
+
core model. Both produce editable PowerPoint text and charts.
|
|
161
182
|
|
|
162
183
|
## How output is checked
|
|
163
184
|
|
|
@@ -188,11 +209,10 @@ of level 4. Items marked "post-1.0" are not implemented yet:
|
|
|
188
209
|
| L3 | Authoring on top of existing themes / masters / layouts | ✅ |
|
|
189
210
|
| L3 | Rebranding a deck: theme colors and theme fonts | ✅ |
|
|
190
211
|
| L3 | Constructing new themes / masters / layouts from scratch | ❌ post-1.0 |
|
|
191
|
-
| L3 | Charts:
|
|
192
|
-
| L3 | Charts: scatter, radar, bubble | Read + preview only |
|
|
212
|
+
| L3 | Charts: all 16 plot types (incl. 3-D, stock, surface), and combos | ✅ |
|
|
193
213
|
| L4 | Notes, comments, transitions | ✅ |
|
|
194
214
|
| L4 | Simple animations (entrance / exit presets) | ✅ |
|
|
195
|
-
| L4 | Audio / video
|
|
215
|
+
| L4 | Audio / video / online video: embed, link and read back | ✅ |
|
|
196
216
|
| L4 | SmartArt authoring | ❌ post-1.0 (read pass-through) |
|
|
197
217
|
| L4 | Complex animation timing trees | ❌ post-1.0 |
|
|
198
218
|
| L4 | OLE / ActiveX authoring | ❌ post-1.0 (read pass-through) |
|
|
@@ -249,13 +269,31 @@ const out = await savePresentation(pres);
|
|
|
249
269
|
|
|
250
270
|
## Driving @office-kit/pptx from an AI agent
|
|
251
271
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
272
|
+
Install the Claude Code plugin once from the shared [Office Kit marketplace](https://github.com/office-kit/skills):
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
claude plugin marketplace add office-kit/skills
|
|
276
|
+
claude plugin install pptx@office-kit
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
In Claude Code, open `/plugin` → **Marketplaces** → **office-kit** and enable
|
|
280
|
+
**auto-update** once. Third-party marketplaces do not enable it by default.
|
|
281
|
+
Updates load after `/reload-plugins` or a new session.
|
|
282
|
+
|
|
283
|
+
Then ask Claude Code:
|
|
284
|
+
|
|
285
|
+
```text
|
|
286
|
+
/pptx:office-kit-pptx Create a quarterly business review with a revenue chart
|
|
287
|
+
and a next-actions table. Use labelled sample data where needed.
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
The [skill](skill/SKILL.md) creates a TSX project, starts the view-only preview,
|
|
291
|
+
checks the source and exports an editable PPTX. Ask for changes in the same
|
|
292
|
+
conversation; the preview updates as the agent edits TSX. You need Node.js 22.18+
|
|
293
|
+
and Git alongside Claude Code. See the
|
|
294
|
+
[authoring guide](https://office-kit.github.io/pptx/docs/authoring) for template
|
|
295
|
+
editing and manual setup. The bundled [core reference](skill/references/core-api.md)
|
|
296
|
+
and [tested example](skill/examples/business-deck.md) cover direct API use.
|
|
259
297
|
|
|
260
298
|
## Usage
|
|
261
299
|
|
|
@@ -371,6 +409,49 @@ moveSlide(pres, dup, 0);
|
|
|
371
409
|
const out: Uint8Array = await savePresentation(pres);
|
|
372
410
|
```
|
|
373
411
|
|
|
412
|
+
### Add video, audio or an online video
|
|
413
|
+
|
|
414
|
+
```ts
|
|
415
|
+
import { addSlideMedia, getShapeMedia, inches } from '@office-kit/pptx';
|
|
416
|
+
|
|
417
|
+
const box = { x: inches(1), y: inches(1.5), w: inches(8), h: inches(4.5) };
|
|
418
|
+
|
|
419
|
+
// Embedded video / audio, from bytes. The container is detected from the bytes.
|
|
420
|
+
const clip = addSlideMedia(slide, {
|
|
421
|
+
kind: 'video',
|
|
422
|
+
data: mp4Bytes,
|
|
423
|
+
poster: posterPngBytes,
|
|
424
|
+
...box,
|
|
425
|
+
});
|
|
426
|
+
addSlideMedia(slide, {
|
|
427
|
+
kind: 'audio',
|
|
428
|
+
data: mp3Bytes,
|
|
429
|
+
x: inches(0.5),
|
|
430
|
+
y: inches(6.5),
|
|
431
|
+
w: inches(0.6),
|
|
432
|
+
h: inches(0.6),
|
|
433
|
+
});
|
|
434
|
+
|
|
435
|
+
// Online video. YouTube watch / youtu.be / shorts URLs become the embed URL.
|
|
436
|
+
addSlideMedia(slide2, {
|
|
437
|
+
kind: 'online',
|
|
438
|
+
url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
|
|
439
|
+
...box,
|
|
440
|
+
});
|
|
441
|
+
|
|
442
|
+
const media = getShapeMedia(clip);
|
|
443
|
+
// { kind: 'video', partName: '/ppt/media/media1.mp4', contentType: 'video/mp4', bytes }
|
|
444
|
+
// an online video reads back as { kind: 'online', url }
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
The shape is an ordinary picture showing the poster frame, so `setShapeImage`
|
|
448
|
+
replaces the poster and `getShapeImageBytes` reads it. Without `poster` a neutral
|
|
449
|
+
play-button image is used. Containers detected from the bytes: mp4, m4v, mov,
|
|
450
|
+
webm, avi, wmv, mp3, wav, m4a, ogg, wma — pass `format` when the signature
|
|
451
|
+
check cannot tell which of those a file is. Identical clip bytes are stored once
|
|
452
|
+
per deck, and the clip survives `copyShape`, `duplicateSlide` and `importSlide`.
|
|
453
|
+
Whether a clip plays depends on the codecs of the application showing the deck.
|
|
454
|
+
|
|
374
455
|
### Replace an image in place
|
|
375
456
|
|
|
376
457
|
```ts
|
|
@@ -508,7 +589,7 @@ shown together.
|
|
|
508
589
|
| Transitions | `getSlideTransition` / `setSlideTransition` / `clearSlideTransition` |
|
|
509
590
|
| Animations | `getShapeAnimation` / `setShapeAnimation` (`fadeIn` / `fadeOut` / `appear` / `disappear`), `clearSlideAnimations` |
|
|
510
591
|
| Comments | `addSlideComment`, `getSlideComments`, `removeSlideComment`, `getCommentAuthors`, `getCommentText` / `getCommentAuthor` / `getCommentPosition` |
|
|
511
|
-
| Shape authoring | `addSlideTextBox`, `addSlideShape`, `addSlideLine`, `addSlideTable`, `addSlideImage`, `addSlideChart`
|
|
592
|
+
| Shape authoring | `addSlideTextBox`, `addSlideShape`, `addSlideLine`, `addSlideTable`, `addSlideImage`, `addSlideMedia`, `addSlideChart` |
|
|
512
593
|
| Shape lookup | `findShapeByName`, `findShapesByName`, `findShapesByKind`, `findShapeInPresentation`, `getAllShapes`, `getSlideShapes` |
|
|
513
594
|
| Shape text | `setShapeText`, `setShapeParagraphs`, `setShapeBullets`, `setShapeAlignment`, `setShapeTextFormat`, `setShapeHyperlink` / `getShapeHyperlink` |
|
|
514
595
|
| Per-paragraph | `setParagraphAlignment` / `getParagraphAlignment`, `setParagraphLevel` / `getParagraphLevel`, `setParagraphBullet` / `getParagraphBullet`, `setParagraphSpacing` / `getParagraphSpacing`, `setParagraphLineSpacing` / `getParagraphLineSpacing`, `getParagraphEndFormat` |
|