API reference

@apertura/pptx

PowerPoint presentation (.pptx) parser - PresentationML

31 exported symbols · 31 declared here · 0 re-exported

Functions

openPptx

function openPptx(source: ByteSource, options?: OpenOptions): Promise<PptxDocument>

Opens a PowerPoint presentation. Reads the table of contents: slide order and canvas size. Each slide is a separate package part and is therefore parsed on demand: showing the first slide need not touch the other ninety-nine.

parseBackground

function parseBackground(root: XmlElement): DiagramFill | undefined

Reads `p:cSld/p:bg`: what the slide, layout or master is drawn on. Two spellings. `p:bgPr` states the fill outright; `p:bgRef` names an entry of the theme's background list and the colour to fill its placeholder with, exactly as a shape's `a:fillRef` does — so the same resolution serves both, and the reference is returned as a solid fill of the referenced colour when the theme is not at hand.

parseDiagramDrawing

function parseDiagramDrawing(root: XmlElement): Shape[]

Reads `dsp:drawing`: the shapes PowerPoint laid a SmartArt diagram out into. The same tree as a slide's, in Microsoft's own diagram-drawing namespace, so the same reader walks it — which is the whole reason the walker takes a namespace at all.

parseListStyle

function parseListStyle(container: XmlElement | undefined): TextLevelStyle[]

Reads nine `a:lvlNpPr` out of a list style. The same nine levels appear in four places — the master's `p:txStyles`, a layout placeholder's `a:lstStyle`, the shape's own, and the presentation's default — and a paragraph takes the first answer it finds walking outwards. One reader serves all four.

parseSlide

function parseSlide(root: XmlElement): Shape[]

Parses a slide part (`ppt/slides/slideN.xml`). Shapes nest inside groups (`p:grpSp`), so the walk is recursive. Inheritance from the layout and master is deliberately not resolved here: that is a separate layer which needs access to the whole package, and it belongs to rendering rather than to parsing.

parseTableStyles

function parseTableStyles(root: XmlElement): Map<string, TableStyle>

Reads the part into a lookup by style id, braces and all.

parseTextBody

function parseTextBody(textBody: XmlElement): TextParagraph[]

shapesToText

function shapesToText(shapes: readonly Shape[]): string

Collects all shape text of a slide, for search and previews.

showsMasterShapes

function showsMasterShapes(root: XmlElement): boolean

Whether a part draws the master's own shapes. `showMasterSp="0"` on a layout or a slide means "my design, not the one behind me" — 88 parts of the corpus say so, and drawing the master's logo over a layout that turned it off is worse than not drawing it at all.

textStyleListFor

function textStyleListFor(styles: TextStyleDefaults, placeholderType: string | undefined): readonly TextLevelStyle[]

Which of the master's three lists describes a placeholder's text. Only three kinds of text exist as far as `p:txStyles` is concerned: a title, the body of a slide, and everything else.

Interfaces

PptxDocument

interface PptxDocument extends AperturaDocument, PresentationTheme

format

"pptx"

kind

"presentation"

metadata

DocumentMetadata

slides

readonly Slide[]

pageCount

number

Slide count.

slideSize

{ width: number; height: number; }

Slide size in EMUs, from `p:sldSz`.

loadImage

(slide: Slide, relationshipId: string) => Promise<{ bytes: Uint8Array; contentType: string; } | undefined>

imageUrl

(slide: Slide, relationshipId: string) => Promise<string | undefined>

A URL for a slide's picture, metafiles translated.

imageUrlFrom

(partName: string, relationshipId: string) => Promise<string | undefined>

The same, for a picture belonging to any part: a layout's background.

hyperlink

(slide: Slide, relationshipId: string) => Promise<string | undefined>

Where a run's `a:hlinkClick` points, when it points outside the deck.

Rect

interface Rect

A rectangle in EMUs, the DrawingML coordinate system.

number

width

number

height

number

Shape

interface Shape

A shape holding text or a picture.

string

name

string

frame

Rect | undefined

Position and size; `undefined` when inherited from the layout.

paragraphs

readonly TextParagraph[]

placeholderType

string | undefined

The shape role in the layout (`ph type`): `title`, `body`, `ctrTitle`. It tells the renderer that a shape is a title even when the styling lives in the slide layout rather than in the shape itself.

imageRelationshipId

string | undefined

Image relationship id when the shape is a picture (`p:pic`).

sourcePart

string | undefined

The part the shape was read from, when that is not the slide. A logo in the master is drawn on every slide of the deck, but the picture it points at is the master's: the relationship has to be resolved against the part that stated it, or the image is simply not found.

listStyle

readonly TextLevelStyle[] | undefined

`p:txBody/a:lstStyle`: what this shape sets for each outline level. The third rung of the ladder a paragraph climbs — its own properties, then its shape's list style, then the one its placeholder inherits from the layout and the master, then the master's `p:txStyles`. Layouts state 7 561 non-empty list styles across the corpus, and every one of them was ignored.

inheritedListStyle

readonly TextLevelStyle[] | undefined

The list style of the layout or master placeholder this shape matches.

geometry

DiagramGeometry | undefined

How the shape is painted, `p:spPr`. The same three things a shape has in a workbook and in a document — geometry, fill, outline — read into the same types, so that the renderer that draws an Excel shape draws this one.

fill

DiagramColor | undefined

filled

boolean

paint

DiagramFill | undefined

The fill as stated, when it is not a flat colour. A gradient panel, a hatched box and a shape filled with a photograph were all drawn as nothing, because only `a:solidFill` was read.

outline

DiagramOutline | undefined

style

ShapeStyleReference | undefined

`p:style`: how the deck's theme paints this shape. Most shapes state no colour at all — they name an entry of the theme's format scheme and the colour to fill its placeholder with. Ignored, they are drawn unpainted, with their labels in the default colour on the default background: which is white on white for a third of the corpus's slides.

shadow

DiagramShadow | undefined

`a:effectLst/a:outerShdw`: the shadow the shape casts, if any.

rotation

number

`a:xfrm/@rot`, in degrees clockwise; a slide states sixtieths of one.

flipHorizontal

boolean

`a:xfrm/@flipH` and `@flipV`: the shape drawn mirrored.

flipVertical

boolean

verticalAlignment

"center" | "top" | "bottom" | undefined

`a:bodyPr`: where the text sits inside the shape. A shape is a box and its text is placed in it: `@anchor` says against which edge, `@lIns` and friends say how far from it. Both have defaults that are not zero and not centre — PowerPoint anchors to the top and insets by a tenth of an inch — so a reader that ignores them puts every caption in a different place from the one the deck was designed with.

insets

{ left: number; top: number; right: number; bottom: number; } | undefined

wrap

boolean

`a:bodyPr/@wrap`: `none` lets a long line run past the shape.

textDirection

"horizontal" | "vertical" | "vertical270" | "eastAsian"

`a:bodyPr/@vert`: text set on its side. A side caption, a table's rotated header, the spine of a poster: the file turns the text rather than the shape. Drawn horizontally it overflows the narrow box it was given and covers whatever is beside it.

fontScale

number | undefined

`a:normAutofit/@fontScale`: how far PowerPoint shrank the text to fit. A stated number rather than a guess — the application worked it out when the deck was saved and wrote it down, so a reader that ignores it draws text at a size the author never saw, overflowing the box it was shrunk to fit.

lineSpacingReduction

number | undefined

`a:normAutofit/@lnSpcReduction`, as a fraction.

table

SlideTable | undefined

`a:tbl` inside a graphic frame: the rows, in reading order.

chartRelationshipId

string | undefined

`p:graphicFrame` pointing at a chart part, by relationship id.

diagram

readonly Shape[] | undefined

A SmartArt diagram, once the drawing PowerPoint saved with it is read. The diagram itself is a data model and a layout algorithm — laying it out is a program, not a parse — but every deck written since 2010 also carries the shapes the application produced, in ordinary DrawingML. Those are what is drawn: 54 decks of the corpus have one, and without it a SmartArt frame is an empty rectangle in the middle of the slide.

diagramData

string | undefined

`dgm:relIds/@r:dm`: the data part, which names the drawing beside it.

chart

ChartDefinition | undefined

The chart itself, once the slide has read the part it points at. Parsed rather than referenced: `c:chartSpace` is the same part on a slide as in a workbook, and the renderer that draws it is the same too.

Slide

interface Slide

index

number

Zero-based position in the presentation.

partName

string

load

() => Promise<SlideContent>

SlideBackground

interface SlideBackground

A background, and the part whose relationships resolve its picture.

styleIndex?

number | undefined

`p:bgRef/@idx`, zero-based: the entry of the theme's background list. Present only when the part named one. The fill beside it is the colour that entry is filled *with*; the entry itself may be a picture, and only the theme knows.

fill

DiagramFill

partName

string

The part the fill was found in: a slide, a layout or a master.

SlideContent

interface SlideContent

shapes

readonly Shape[]

themePart?

string | undefined

The theme part this slide inherits, reached through its layout and master. A deck has one theme per master and a notes theme besides, and the document's own `theme` can only be one of them. A slide knows which is its own, and it is the only thing that does.

colorMap?

Readonly<Record<string, string>> | undefined

`p:clrMap`, as this slide inherits it: which theme colour each role uses. Per slide because a layout may override it and the layouts of one deck differ — a dark section in a light deck is exactly this and nothing else.

notes

string | undefined

Speaker notes, when the package contains that part.

background

SlideBackground | undefined

What the slide is drawn on: its own background, or the one it inherits. Slides state a background 41 times in the corpus and masters 505 — a deck's background is a property of its design, not of its slides — so a reader that looks only at the slide draws every designed deck on white.

SlideTable

interface SlideTable

A table on a slide: column widths and rows of cells.

columns

readonly number[]

Column widths in EMUs, from `a:gridCol`.

rows

readonly SlideTableRow[]

styleId

string | undefined

`a:tableStyleId`: the GUID of the style in `ppt/tableStyles.xml`. A table states almost nothing about its own look; it names a style and sets the flags below, and the part says what those mean. Without it every table in every deck is drawn as the same grey grid.

firstRow

boolean

`a:tblPr` flags: which special parts of the style apply.

lastRow

boolean

firstColumn

boolean

lastColumn

boolean

bandRow

boolean

bandColumn

boolean

SlideTableCell

interface SlideTableCell

paragraphs

readonly TextParagraph[]

merged

boolean

Cells a merge swallowed carry no content and are not drawn.

columnSpan

number

rowSpan

number

fill

DiagramColor | undefined

SlideTableRow

interface SlideTableRow

height

number

Row height in EMUs, from `a:tr/@h`; Word calls this a minimum.

cells

readonly SlideTableCell[]

TableBorder

interface TableBorder

A rule, stated outright or as a reference into the theme's line list.

outline

DiagramOutline | undefined

reference

StyleReference | undefined

TableBorders

interface TableBorders

left

TableBorder | undefined

right

TableBorder | undefined

top

TableBorder | undefined

bottom

TableBorder | undefined

insideHorizontal

TableBorder | undefined

insideVertical

TableBorder | undefined

TablePartStyle

interface TablePartStyle

One part of a table style: the whole table, a band, a header row.

fill

DiagramFill | undefined

`a:tcStyle/a:fill`, stated outright.

fillReference

StyleReference | undefined

`a:tcStyle/a:fillRef`: the theme entry the part is filled from.

bold

boolean | undefined

italic

boolean | undefined

textColor

DiagramColor | undefined

textReference

StyleReference | undefined

borders

TableBorders

TableStyle

interface TableStyle

A whole table style: the parts, in the order they override each other. PowerPoint applies them from the least specific to the most: the whole table, then the banding, then the first and last rows and columns. A cell in the header row of a banded table is painted by three of them in turn.

wholeTable

TablePartStyle | undefined

band1Horizontal

TablePartStyle | undefined

band2Horizontal

TablePartStyle | undefined

band1Vertical

TablePartStyle | undefined

band2Vertical

TablePartStyle | undefined

firstRow

TablePartStyle | undefined

lastRow

TablePartStyle | undefined

firstColumn

TablePartStyle | undefined

lastColumn

TablePartStyle | undefined

TextLevelStyle

interface TextLevelStyle

What the master sets for one outline level of one kind of placeholder. `p:txStyles` is the deck's typography: it says a title is 40pt, bold, and coloured `tx2`, and a first-level bullet 20pt in `tx1`. Reading only the size out of it — which is where this started — gives every deck the right scale in the wrong colour.

sizePoints

number | undefined

color

DiagramColor | undefined

bold

boolean | undefined

italic

boolean | undefined

typeface

string | undefined

alignment

"left" | "center" | "right" | "justify" | undefined

lineSpacing

TextSpacing | undefined

The spacing and the bullet the level carries. The master is where a deck's list looks like a list: the step between lines, the gap above an item, how far it is indented, and which glyph marks it. A slide states these only when it departs from them, so a reader that takes them from the paragraph alone renders most decks unbulleted and unspaced.

spaceBefore

TextSpacing | undefined

spaceAfter

TextSpacing | undefined

marginLeft

number | undefined

indent

number | undefined

bulletChar

string | undefined

bulletNone

boolean

bulletColor

DiagramColor | undefined

bulletSizePercent

number | undefined

bulletFont

string | undefined

kerningFrom

number | undefined

`a:defRPr/@kern`: the size from which text at this level is kerned. The masters state it and the runs almost never do — the shipped template writes `kern="1200"` on every level of every style — so a rule that read the run alone kerned nothing at all. `45541_Footer` shows the cost on its title: 711 pixels in PowerPoint and 743 in ours, four and a half per cent of a line that has to wrap in the same place.

TextParagraph

interface TextParagraph

A paragraph of a text body (`a:p`).

runs

readonly TextRun[]

level

number

List nesting level; 0 is the top level.

alignment

"left" | "center" | "right" | "justify" | undefined

bulletChar

string | undefined

Bullet glyph, when the paragraph is bulleted.

bulletNumbering

{ readonly scheme: string; readonly startAt: number; } | undefined

`a:buAutoNum`: the paragraph is numbered rather than bulleted. The scheme names the shape of the number — `arabicPeriod` is `1.`, `alphaLcParenR` is `a)` — and `startAt` restarts the count. The number itself is not in the file: it is the paragraph's position among its neighbours at the same level, which only the renderer knows.

bulletNone

boolean

`a:buNone`: the paragraph states that it has no bullet at all.

bulletColor

DiagramColor | undefined

`a:buClr`, `a:buSzPct`, `a:buFont`: how the marker itself is set.

bulletSizePercent

number | undefined

bulletFont

string | undefined

lineSpacing

TextSpacing | undefined

The spacing a paragraph asks for, which nothing used to read. `a:lnSpc` is the step between its lines and `a:spcBef`/`a:spcAft` the gaps around it, each stated either as a percentage of the type size or as a number of points. Ignored, every list in every deck comes out at the browser's own line height with no space between items: the commonest thing in a presentation, set wrong.

spaceBefore

TextSpacing | undefined

spaceAfter

TextSpacing | undefined

marginLeft

number | undefined

`a:pPr/@marL` and `@indent`, in EMUs: the list's own indentation.

indent

number | undefined

TextRun

interface TextRun

text

string

properties

TextRunProperties

interface TextRunProperties

Formatting of a text fragment (`a:rPr`).

bold?

boolean | undefined

italic?

boolean | undefined

underline?

boolean | undefined

fontSize?

number | undefined

Size in points; the file stores hundredths of a point.

fontFamily?

string | undefined

color?

string | undefined

Colour as `RRGGBB`, when given literally.

colorReference?

DiagramColor | undefined

The colour as the file states it, theme slots and all. Most templates colour their text by theme (`a:schemeClr val="tx1"`) rather than literally, and a reader that only takes `a:srgbClr` renders those runs in whatever the stylesheet happens to inherit.

hyperlinkId?

string | undefined

`a:hlinkClick`: the relationship the run links through.

shadow?

DiagramShadow | undefined

`a:rPr/a:effectLst/a:outerShdw`: the shadow behind the letters. The commonest effect in the corpus by a distance — 514 runs of 1 044 effect lists — because a title over a photograph is unreadable without one.

textOutline?

DiagramOutline | undefined

`a:rPr/a:ln`: the line drawn around the letters. A title outlined in white over a photograph is the commonest use, and fourteen decks of the corpus draw one on their first slide alone. Without it such a title is the fill alone, which over a busy picture is nothing.

textPicture?

string | undefined

`a:rPr/a:blipFill`: the picture the letters are filled with. Twenty-two decks of the corpus do it — a heading cut out of a photograph or a pattern — and drawn as flat text it is the wrong colour entirely. The relationship belongs to the part the shape came from.

baseline?

number | undefined

`@baseline`: the run is raised or lowered, as a share of the type size. How a presentation writes a superscript — 522 runs of the corpus do — and drawn on the baseline they read as ordinary digits: "m2" for "m²".

letterSpacing?

number | undefined

`@spc`: letter spacing in points, positive to open the line up.

caps?

"all" | "small" | undefined

`@cap`: `all` for capitals, `small` for small ones.

strike?

"single" | "double" | undefined

`@strike`: `sngStrike` or `dblStrike`.

kerningFrom?

number | undefined

`@kern`: the size, in points, from which the run is kerned. A *threshold*, not a switch, and its absence means no kerning at all — which is not the browser's default and never was. The probe `kerning` measures the difference: the same line of Times New Roman at 44 points comes out 694 pixels wide when the file states `kern="1200"` and **743** when it states nothing, and a line seven per cent wide wraps a word early — after which neither side has the same lines at all.

eastAsianFont?

string | undefined

`a:ea`: the typeface for East Asian text, when it differs from the Latin.

TextSpacing

interface TextSpacing

A spacing, as a share of the type size or as an absolute measure.

percent

number | undefined

`a:spcPct/@val`, as a fraction: 1.5 for one and a half lines.

points

number | undefined

`a:spcPts/@val`, in points.

Values

DEFAULT_SLIDE_SIZE

DEFAULT_SLIDE_SIZE: { readonly width: 12192000; readonly height: 6858000; }

Default slide size: widescreen 16:9, 13.333 by 7.5 inches.

DEFAULT_TEXT_INSETS

DEFAULT_TEXT_INSETS: { readonly left: 91440; readonly top: 45720; readonly right: 91440; readonly bottom: 45720; }

`a:bodyPr` insets when the file states none, in EMUs. A tenth of an inch left and right, a twentieth top and bottom — PowerPoint's defaults, and not zero, so text never touches the edge of its shape.

pptxParser

pptxParser: ParserPlugin<PptxDocument>