@shbernal/ts-pptx

---

@shbernal/ts-pptx / node / TsPptx

Class: TsPptx

Defined in: src/node.ts:12

The Node entry, reached through the node export condition — a consumer importing the bare @shbernal/ts-pptx specifier under Node lands here without naming this subpath.

Same authoring API as every other entry (see entry-surface.ts); the runtime adapter is what differs. This one can reach the filesystem, so writeFile writes a real file and media may be loaded from a path — both of which throw on the runtime-agnostic entry.

Extends

• default

Constructors

Constructor

new TsPptx(): TsPptx

Defined in: src/node.ts:13

Returns

TsPptx

Overrides

PresentationCore.constructor

Accessors

author

Get Signature

get author(): string

Defined in: src/presentation.ts:152

Returns

string

Set Signature

set author(value): void

Defined in: src/presentation.ts:148

Parameters

value

string

Returns

void

Inherited from

PresentationCore.author

---

company

Get Signature

get company(): string

Defined in: src/presentation.ts:164

Returns

string

Set Signature

set company(value): void

Defined in: src/presentation.ts:160

Parameters

value

string

Returns

void

Inherited from

PresentationCore.company

---

firstSlideNum

Get Signature

get firstSlideNum(): number

Defined in: src/presentation.ts:223

Returns

number

Set Signature

set firstSlideNum(value): void

Defined in: src/presentation.ts:219

Parameters

value

number

Returns

void

Inherited from

PresentationCore.firstSlideNum

---

layout

Get Signature

get layout(): string

Defined in: src/presentation.ts:132

Returns

string

Set Signature

set layout(value): void

Defined in: src/presentation.ts:116

Parameters

value

string | StandardLayout

Returns

void

Inherited from

PresentationCore.layout

---

masterSlide

Get Signature

get masterSlide(): Slide

Defined in: src/presentation.ts:242

Returns

Slide

Inherited from

PresentationCore.masterSlide

---

presLayout

Get Signature

get presLayout(): PresLayout

Defined in: src/presentation.ts:295

Returns

PresLayout

Inherited from

PresentationCore.presLayout

---

revision

Get Signature

get revision(): string

Defined in: src/presentation.ts:177

Returns

string

Set Signature

set revision(value): void

Defined in: src/presentation.ts:173

Parameters

value

string

Returns

void

Inherited from

PresentationCore.revision

---

rtlMode

Get Signature

get rtlMode(): boolean

Defined in: src/presentation.ts:236

Returns

boolean

Set Signature

set rtlMode(value): void

Defined in: src/presentation.ts:232

Parameters

value

boolean

Returns

void

Inherited from

PresentationCore.rtlMode

---

sections

Get Signature

get sections(): SectionProps[]

Defined in: src/presentation.ts:254

Returns

SectionProps[]

Inherited from

PresentationCore.sections

---

slideLayouts

Get Signature

get slideLayouts(): SlideLayout[]

Defined in: src/presentation.ts:268

Returns

SlideLayout[]

Inherited from

PresentationCore.slideLayouts

---

slides

Get Signature

get slides(): Slide[]

Defined in: src/presentation.ts:248

Returns

Slide[]

Inherited from

PresentationCore.slides

---

subject

Get Signature

get subject(): string

Defined in: src/presentation.ts:189

Returns

string

Set Signature

set subject(value): void

Defined in: src/presentation.ts:185

Parameters

value

string

Returns

void

Inherited from

PresentationCore.subject

---

theme

Get Signature

get theme(): ThemeProps

Defined in: src/presentation.ts:201

Returns

ThemeProps

Set Signature

set theme(value): void

Defined in: src/presentation.ts:197

Parameters

value

ThemeProps

Returns

void

Inherited from

PresentationCore.theme

---

title

Get Signature

get title(): string

Defined in: src/presentation.ts:213

Returns

string

Set Signature

set title(value): void

Defined in: src/presentation.ts:209

Parameters

value

string

Returns

void

Inherited from

PresentationCore.title

---

version

Get Signature

get version(): string

Defined in: src/presentation.ts:140

Returns

string

Inherited from

PresentationCore.version

Methods

addSection()

addSection(section): void

Defined in: src/presentation.ts:850

Add a new Section to Presentation

Parameters

section

SectionProps

section properties

Returns

void

Example

pptx.addSection({ title:'Charts' });

Inherited from

PresentationCore.addSection

---

addSlide()

addSlide(options?): Slide

Defined in: src/presentation.ts:881

Add a new Slide to Presentation

Parameters

options?

AddSlideProps

slide options

Returns

Slide

the new Slide

Inherited from

PresentationCore.addSlide

---

defineLayout()

defineLayout(layout): void

Defined in: src/presentation.ts:951

Create a custom Slide Layout in any size

Parameters

layout

PresLayout

layout properties

Returns

void

Example

pptx.defineLayout({ name:'A3', width:16.5, height:11.7 });

Inherited from

PresentationCore.defineLayout

---

defineSlideMaster()

defineSlideMaster(props): void

Defined in: src/presentation.ts:975

Create a new slide master [layout] for the Presentation

Parameters

props

SlideMasterProps

layout properties

Returns

void

Inherited from

PresentationCore.defineSlideMaster

---

embedFont()

embedFont(opts): Promise<void>

Defined in: src/presentation.ts:658

Embed a font face so the deck renders with it even on machines that do not have it installed. The whole face is embedded (not glyph-subset) under /ppt/fonts/ and wired into presentation.xml (p:embeddedFontLst + embedTrueTypeFonts="1"), exactly as PowerPoint's "Embed fonts in the file" does. Call once per face/weight you use.

The declared typeface MUST match the family name used in your run/fontFace typefaces (e.g. addText('hi', { fontFace: 'Silkscreen' })) or PowerPoint will not bind the embedded bytes to the text. Repeated calls with the same typeface and different style accumulate into one p:embeddedFont entry.

Font licensing is the caller's responsibility: the bytes are embedded as handed over; OS/2.fsType embedding-permission bits are not enforced.

Parameters

opts

font source + identity

data?

string | ArrayBuffer | Uint8Array<ArrayBufferLike>

raw font bytes, or a base64 string, in lieu of path

path?

string

font file path (Node) or URL (web) to a .ttf/.otf

style?

"bold" | "italic" | "regular" | "boldItalic"

face slot; defaults to 'regular'

typeface

string

family name as referenced by run/fontFace typefaces

Returns

Promise<void>

Examples

await pptx.embedFont({ path: '/fonts/Silkscreen-Regular.ttf', typeface: 'Silkscreen' })

await pptx.embedFont({ path: '/fonts/Silkscreen-Bold.ttf', typeface: 'Silkscreen', style: 'bold' })

Inherited from

PresentationCore.embedFont

---

extractSlides()

extractSlides(opts?): Promise<ExtractedSlides>

Defined in: src/presentation.ts:458

Author + serialize this presentation's slides as injectable descriptors, WITHOUT producing a .pptx package. Runs the same media-encode, placeholder backfill, and measured-fit passes write() uses, then serializes each slide body and resolves its image media to decoded bytes — so a loaded deck can splice the slides in via Presentation.appendSlides() (see ts-pptx/read) while keeping its own masters/layouts/theme byte-identical.

Returns the deck's slide size (EMU, for the destination size check) and one descriptor per authored slide. Charts, audio/video media, online media, and internal slide-to-slide hyperlinks are surfaced as descriptors alongside the serialized body — this method does not resolve them into a package; the append path consumes each descriptor to reserve the parts and rebuild the rel graph.

Parameters

opts?

onMediaError?

"placeholder" | "throw"

Returns

Promise<ExtractedSlides>

Inherited from

PresentationCore.extractSlides

---

measureText()

measureText(text, opts): TextMeasurement

Defined in: src/presentation.ts:724

Measure how tall text wraps at a given width, using the same calibrated wrap model the export-time autofit bake uses — so a layout-time prediction matches the value fit:'shrink'/'resize' would bake. Synchronous: register the face's metrics first with TsPptx.registerFontMetrics (lookup is sync).

Lets a consumer size its own geometry before export — grow a card to fit its text, reflow a grid, or detect overflow at layout time. Heights err tall (conservative), so the returned height is ≥ what PowerPoint/LibreOffice render.

Parameters

text

string | TextProps[]

a string or run array (per-run options override the defaults in opts)

opts

MeasureTextOptions

width (inches), font size/face (points), and spacing

Returns

TextMeasurement

laid-out height + line count + fit helpers

Examples

const m = pptx.measureText('Long heading…', { wIn: 3, fontSize: 18, fontFace: 'Aptos' })

if (pptx.measureText(runs, { wIn, fontSize, fontFace }).heightIn > cardHeightIn) growCard()

Inherited from

PresentationCore.measureText

---

overflowsBox()

overflowsBox(text, opts): boolean

Defined in: src/presentation.ts:738

Convenience overflow check: true if text does not fit a box of inner size wIn×hIn (inches) at full size. Because the model errs tall, this is a conservative (slightly over-reporting) check — appropriate for a build-time warning, not a hard gate. An unmeasurable (unnamed theme-default) face reports false (no overflow) so the linter does not false-positive on faces it cannot measure.

Parameters

text

string | TextProps[]

a string or run array

opts

OverflowBoxOptions

MeasureTextOptions plus the box inner height hIn

Returns

boolean

true if the text overflows the box

Inherited from

PresentationCore.overflowsBox

---

registerFontMetrics()

registerFontMetrics(face, source, opts?): Promise<void>

Defined in: src/presentation.ts:623

Register a font's metrics so fit:'shrink' text boxes are measured and a real fontScale is baked at export time (text renders pre-shrunk in headless renderers and on plain file-open, with no manual edit/resize).

Without registered metrics, fit:'shrink' keeps its current behavior (a bare <a:normAutofit/> that only PowerPoint recomputes on edit). Register the same face once per weight/style you use; bold/italic advances differ.

Parameters

face

string

font family name as used in fontFace (e.g. 'Aptos')

source

string | ArrayBuffer | Uint8Array<ArrayBufferLike>

font file path/URL (Node/web) or raw TTF/OTF bytes

opts?

variant flags; advances differ per weight/style

bold?

boolean

italic?

boolean

Returns

Promise<void>

Examples

await pptx.registerFontMetrics('Aptos', '/usr/share/fonts/Aptos.ttf')

await pptx.registerFontMetrics('Aptos', aptosBoldBytes, { bold: true })

Inherited from

PresentationCore.registerFontMetrics

---

setCustomProperty()

setCustomProperty(name, value): void

Defined in: src/presentation.ts:840

Set a custom document property stored in docProps/custom.xml. Calling with the same name replaces the existing value.

Parameters

name

string

property name

value

CustomPropertyValue

string, integer/float number, boolean, or Date

Returns

void

Inherited from

PresentationCore.setCustomProperty

---

stream()

stream(props?): Promise<string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob>

Defined in: src/presentation.ts:772

Export the current Presentation to stream

Parameters

props?

WriteBaseProps

output properties

Returns

Promise<string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob>

file stream

Inherited from

PresentationCore.stream

---

tableLayout()

tableLayout(rows, opts): TableLayoutResult

Defined in: src/presentation.ts:761

Compute the per-cell geometry of a table laid out at opts.x/y/w, without adding it to a slide — so a consumer can place images or shapes precisely over cells. Column widths (cell x/w) are exact, derived from the same logic the writer uses. Row heights (y/h) are exact when pinned by rowH (array or scalar) or table h; an auto-height row is estimated with the same conservative (tall) text model as TsPptx.measureText and flagged heightExact:false (register the cell font via TsPptx.registerFontMetrics for an exact estimate). Geometry is for a single, un-paginated table — autoPage paging is not modeled.

Parameters

rows

TableRow[]

the same rows passed to slide.addTable

opts

TableProps

the same table options (x, y, w, colW, rowH, h, …)

Returns

TableLayoutResult

per-cell rectangles (inches) plus overall table bounds

Example

const g = pptx.tableLayout(rows, { x: 1, y: 1, w: 8, colW: [2, 3, 3] })
const c = g.cells.find(c => c.row === 0 && c.col === 2)
slide.addImage({ path: 'logo.png', x: c.xIn, y: c.yIn, w: c.wIn, h: c.hIn })

Inherited from

PresentationCore.tableLayout

---

toParts()

toParts(props?): Promise<PackagePart[]>

Defined in: src/presentation.ts:808

Assemble the current Presentation into its OOXML package parts WITHOUT zipping — the raw path → bytes contents write() would compress into the .pptx. Use this to stream parts into a custom container, inspect individual parts, or feed a pipeline that does its own archiving. To produce a real .pptx file, use write / writeFile instead.

The returned parts are byte-identical, per part, to what write() emits for the same deck, and their order is the package's emission order. Both are a stability-guaranteed observable contract: adding a new part in a later release is backward-compatible as long as existing part paths and their relative order do not shift; renaming or reordering an existing part is a breaking change. Each call returns fresh Uint8Array views over per-call buffers (a new assembly runs each time), so callers may retain or transfer them without defensive copying.

Parameters

props?

PartsProps

assembly options (onMediaError only; compression/output shape are zip concerns that do not apply to unzipped parts)

Returns

Promise<PackagePart[]>

the package parts in emission order

Inherited from

PresentationCore.toParts

---

write()

write(props?): Promise<string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob>

Defined in: src/presentation.ts:784

Export the current Presentation as ZIP content with the selected type

Parameters

props?

WriteProps

output properties

Returns

Promise<string | ArrayBuffer | Uint8Array<ArrayBufferLike> | Blob>

file content in selected type

Inherited from

PresentationCore.write

---

writeFile()

writeFile(props?): Promise<string>

Defined in: src/presentation.ts:820

Export the current Presentation. Write the generated presentation to disk (Node) or trigger a download (browser).

Parameters

props?

WriteFileProps

output file properties

Returns

Promise<string>

the presentation name

Inherited from

PresentationCore.writeFile