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
233 lines
9.4 KiB
Markdown
233 lines
9.4 KiB
Markdown
# Animation Showcase
|
||
|
||
Demonstrates the first-class pptx **`animation` element** and its full property
|
||
surface. Three files work together:
|
||
|
||
- **animations.sh** — Shell script driving `officecli create/open/add/set/close`.
|
||
- **animations.py** — SDK twin (`officecli-sdk`), same deck via `doc.batch(...)`.
|
||
- **animations.pptx** — The generated 7-slide deck.
|
||
|
||
## The animation element
|
||
|
||
An animation is a child element of a **shape** (or **chart**):
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[N]/shape[M] --type animation \
|
||
--prop effect=fade --prop class=entrance --prop duration=800
|
||
```
|
||
|
||
`add ... --type animation` gives you the full timing model. (The legacy
|
||
`set --prop animation=fade-entrance-800` compound-token shortcut still works for
|
||
quick one-liners, but the element form is what exposes trigger/delay/repeat/
|
||
autoReverse/restart/motion-paths.)
|
||
|
||
On `get`, each facet is its own key — there is **no** composite `animation` key
|
||
in readback:
|
||
|
||
```bash
|
||
officecli get animations.pptx /slide[2]/shape[3]/animation[1]
|
||
# → effect=fade class=entrance presetId=10 trigger=onClick duration=800
|
||
```
|
||
|
||
## Regenerate
|
||
|
||
```bash
|
||
cd examples/ppt
|
||
bash animations.sh # → animations.pptx (7 slides, 44 animations)
|
||
# or the SDK twin:
|
||
python3 animations.py
|
||
```
|
||
|
||
## Property reference
|
||
|
||
| Prop | Values / format | Notes |
|
||
|---|---|---|
|
||
| `effect` | preset name (see catalog below) | The animation preset. Some effects require a specific `class`. |
|
||
| `class` | `entrance` \| `exit` \| `emphasis` \| `motion` | Category. `spin/grow/wave` need `emphasis`; `motion` needs `path=`. |
|
||
| `trigger` | `onClick` \| `withPrevious` \| `afterPrevious` | When it starts. Default `onClick`. |
|
||
| `duration` | ms integer (alias `dur`) | e.g. `500` = 0.5s. |
|
||
| `delay` | ms integer | Delay before starting. |
|
||
| `repeat` | positive int \| `indefinite` | Loop count, or loop forever. |
|
||
| `autoReverse` | `true` / `false` | Play forward then reverse (doubles the visible run). |
|
||
| `restart` | `always` \| `whenNotActive` \| `never` | Behavior when re-triggered. |
|
||
| `direction` | `in`/`out`/`left`/`right`/`up`/`down` (+ aliases `top`/`bottom`, `l/r/u/d`) | For directional effects. |
|
||
| `path` | `line` \| `arc` \| `circle` \| `diamond` \| `triangle` \| `square` \| `custom` | Motion preset (only with `class=motion`). |
|
||
| `d` | SVG-like path, coords 0..1 of slide | Custom motion path (only with `path=custom`; auto-appends `E`). |
|
||
|
||
Get-only facets: `presetId`, `easein`, `easeout`, `motionPath`.
|
||
|
||
## Timing model
|
||
|
||
Animations on a slide play as an ordered list. Each animation's `trigger`
|
||
decides how it relates to the one before it:
|
||
|
||
- **`onClick`** — waits for a mouse click to start (the default).
|
||
- **`afterPrevious`** — starts automatically when the previous animation ends
|
||
(add `delay=` for a gap).
|
||
- **`withPrevious`** — starts at the same instant as the previous animation.
|
||
|
||
Chaining `onClick → afterPrevious → withPrevious …` builds a self-playing
|
||
sequence off a single click (see Slide 6).
|
||
|
||
## Effect catalog
|
||
|
||
**Entrance / Exit** (same names, pick via `class=`):
|
||
`appear`, `fade`, `fly`, `zoom`, `wipe`, `bounce`, `float`, `swivel`, `split`,
|
||
`wheel`, `checkerboard`, `blinds`, `dissolve`, `flash`, `box`, `circle`,
|
||
`diamond`, `plus`, `strips`, `wedge`, `random`.
|
||
|
||
**Emphasis** (`class=emphasis`):
|
||
motion — `spin`, `grow`, `wave`, `bold`, `growShrink`, `teeter`, `pulse`;
|
||
color — `fillColor`, `lineColor`, `transparency`, `complementaryColor`,
|
||
`complementaryColor2`, `contrastingColor`, `darken`, `desaturate`, `lighten`,
|
||
`objectColor`, `colorPulse`.
|
||
|
||
**Motion** (`class=motion` + `path=`): `line`, `arc`, `circle`, `diamond`,
|
||
`triangle`, `square`, `custom`.
|
||
|
||
**Template exit effects** (`class=exit`, verbatim PowerPoint OOXML):
|
||
`contract`, `centerRevolve`, `collapse`, `floatOut`, `shrinkTurn`, `sinkDown`,
|
||
`spinner`, `basicZoom`, `stretchy`, `boomerang`, `credits`, `curveDown`,
|
||
`pinwheel`, `spiralOut`, `basicSwivel`.
|
||
|
||
> **Known limitation — template exit effects are lossy on readback.** These 15
|
||
> effects are backed by byte-for-byte PowerPoint-authored OOXML, so they render
|
||
> correctly in PowerPoint but **ignore the `duration` prop** (they keep the
|
||
> authored timing) and **do not round-trip their effect name** — `get` reports
|
||
> them as a generic `effect=fade`/`split`/`unknown` plus a `presetId`. Because
|
||
> the effect name doesn't survive a round-trip, this demo builds its slides from
|
||
> the effects that round-trip cleanly. Use the template effects directly in a
|
||
> deck when you want their exact PowerPoint look; just don't rely on `get`
|
||
> echoing the name back.
|
||
|
||
## Slides
|
||
|
||
### Slide 1 — Title
|
||
|
||
Radial-gradient title slide (`layout=title`, `background=radial:`, title +
|
||
subtitle placeholders, `transition=fade`).
|
||
|
||
### Slide 2 — Entrance Effects
|
||
|
||
Twelve entrance effects on a 4-column grid, each with its own `duration`.
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[2]/shape[2] --type animation \
|
||
--prop effect=appear --prop class=entrance --prop duration=400
|
||
officecli add animations.pptx /slide[2]/shape[3] --type animation \
|
||
--prop effect=fade --prop class=entrance --prop duration=800
|
||
# … fly, zoom, wipe, bounce, float, swivel, split, wheel, box, circle
|
||
```
|
||
|
||
**Features:** `effect=` (entrance family), `class=entrance`, `duration=`.
|
||
|
||
### Slide 3 — Exit Effects
|
||
|
||
Ten exit effects; directional ones (`fly`, `wipe`) add `direction=`.
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[3]/shape[3] --type animation \
|
||
--prop effect=fly --prop class=exit --prop direction=down --prop duration=600
|
||
officecli add animations.pptx /slide[3]/shape[6] --type animation \
|
||
--prop effect=wipe --prop class=exit --prop direction=left --prop duration=600
|
||
```
|
||
|
||
**Features:** `class=exit`, `direction=` on directional effects.
|
||
|
||
### Slide 4 — Emphasis & Color Effects
|
||
|
||
Six emphasis effects on ellipses — motion (`spin`, `grow`, `wave`, `growShrink`,
|
||
`teeter`) and `pulse`.
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[4]/shape[2] --type animation \
|
||
--prop effect=spin --prop class=emphasis --prop duration=1000
|
||
officecli add animations.pptx /slide[4]/shape[5] --type animation \
|
||
--prop effect=growShrink --prop class=emphasis --prop duration=800
|
||
```
|
||
|
||
**Features:** `class=emphasis`; color-change and motion emphasis effects.
|
||
|
||
### Slide 5 — Motion Paths
|
||
|
||
Preset paths (`line`, `arc`, `circle`, `diamond`, `square`) plus a custom `d=`.
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[5]/shape[2] --type animation \
|
||
--prop class=motion --prop path=line --prop direction=right --prop duration=1000
|
||
# Custom path — coords are 0..1 of the slide; a trailing 'E' is auto-appended
|
||
officecli add animations.pptx /slide[5]/shape[8] --type animation \
|
||
--prop class=motion --prop path=custom \
|
||
--prop d='M 0 0 L 0.3 -0.1 L 0.6 0.1 E' --prop duration=1500
|
||
```
|
||
|
||
**Features:** `class=motion`, `path=<preset|custom>`, `direction=`, `d=`.
|
||
`get` echoes the resolved path back as `motionPath=`.
|
||
|
||
### Slide 6 — Timing & Trigger Chaining
|
||
|
||
Five shapes chained into a self-playing sequence off one click, plus a `delay=`
|
||
and a slow (2000ms) run.
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[6]/shape[2] --type animation \
|
||
--prop effect=fade --prop class=entrance --prop trigger=onClick --prop duration=500
|
||
officecli add animations.pptx /slide[6]/shape[3] --type animation \
|
||
--prop effect=fly --prop class=entrance --prop trigger=afterPrevious --prop duration=600
|
||
officecli add animations.pptx /slide[6]/shape[4] --type animation \
|
||
--prop effect=zoom --prop class=entrance --prop trigger=withPrevious --prop duration=600
|
||
officecli add animations.pptx /slide[6]/shape[5] --type animation \
|
||
--prop effect=wipe --prop class=entrance --prop trigger=afterPrevious \
|
||
--prop delay=800 --prop duration=700
|
||
```
|
||
|
||
**Features:** `trigger=onClick|afterPrevious|withPrevious`, `delay=`, duration
|
||
range (500–2000ms).
|
||
|
||
### Slide 7 — Repeat, autoReverse & Restart
|
||
|
||
```bash
|
||
officecli add animations.pptx /slide[7]/shape[2] --type animation \
|
||
--prop effect=spin --prop class=emphasis --prop repeat=3 --prop duration=800
|
||
officecli add animations.pptx /slide[7]/shape[3] --type animation \
|
||
--prop effect=pulse --prop class=emphasis --prop repeat=indefinite \
|
||
--prop trigger=withPrevious --prop duration=600
|
||
officecli add animations.pptx /slide[7]/shape[4] --type animation \
|
||
--prop effect=grow --prop class=emphasis --prop autoReverse=true \
|
||
--prop repeat=2 --prop duration=700
|
||
officecli add animations.pptx /slide[7]/shape[5] --type animation \
|
||
--prop effect=teeter --prop class=emphasis --prop restart=whenNotActive \
|
||
--prop repeat=indefinite --prop duration=500
|
||
```
|
||
|
||
**Features:** `repeat=<int>`, `repeat=indefinite`, `autoReverse=true`,
|
||
`restart=whenNotActive`.
|
||
|
||
## Complete feature coverage
|
||
|
||
| Feature | Slide |
|
||
|---------|-------|
|
||
| `add --type animation` element | 2–7 |
|
||
| `effect=` entrance family | 2 |
|
||
| `effect=` exit family | 3 |
|
||
| `effect=` emphasis (motion + color) | 4 |
|
||
| `class=entrance` / `exit` / `emphasis` / `motion` | 2 / 3 / 4 / 5 |
|
||
| `duration=` (400–2000ms) | 2–7 |
|
||
| `delay=` | 6 |
|
||
| `direction=` on directional effects | 3, 5 |
|
||
| `trigger=onClick` / `afterPrevious` / `withPrevious` | 6 |
|
||
| `repeat=<int>` / `repeat=indefinite` | 7 |
|
||
| `autoReverse=true` | 7 |
|
||
| `restart=whenNotActive` | 7 |
|
||
| `path=` preset motion + `d=` custom | 5 |
|
||
| `transition=` (fade, wipe, push, zoom, split, reveal) | 1–7 |
|
||
|
||
## Inspect the generated file
|
||
|
||
```bash
|
||
officecli query animations.pptx animation
|
||
officecli get animations.pptx /slide[2]/shape[3]/animation[1]
|
||
officecli get animations.pptx /slide[6]/shape[5]/animation[1]
|
||
officecli get animations.pptx /slide[7]/shape[4]/animation[1]
|
||
```
|