xlsx-kit spec

API reference

Drawings & images

Picture / chart anchors, image format detection.

30 exports · 7 source files

Drawing

src/drawing/drawing.ts

# addChartAt function

src/drawing/drawing.ts:125

Anchor a chart to a worksheet at a single-cell ref. Lazy-allocates `ws.drawing`. `chart` is the same `ChartReference` shape `makeChart DrawingItem` accepts (`{ space }` for legacy chart, `{ cxSpace }` for chartex).

function addChartAt(ws: Worksheet, at: string, chart: ChartReference, opts?: { heightPx?: number; widthPx?: number }): DrawingItem

Parameters

NameTypeDescription
ws Worksheet
at string
chart ChartReference
opts? = {}{ heightPx?: number; widthPx?: number }

Returns

DrawingItem

# addImageAt function

src/drawing/drawing.ts:101

Drop an image onto a worksheet at a single-cell anchor. Lazy-allocates `ws.drawing` (as `makeDrawing([])`) on first call and appends a picture DrawingItem. `image` accepts either an `XlsxImage` (already loaded via `loadImage`) or raw image bytes — in the bytes case, this helper sniffs the format with `loadImage` itself. `at` is a cell ref like `"C3"`. Override `widthPx` / `heightPx` to scale; otherwise the helper uses 96×96 defaults that look fine for typical icons.

function addImageAt(ws: Worksheet, at: string, image: XlsxImage | Uint8Array<ArrayBufferLike>, opts?: { heightPx?: number; widthPx?: number }): DrawingItem

Parameters

NameTypeDescription
ws Worksheet
at string
image XlsxImage | Uint8Array<ArrayBufferLike>
opts? = {}{ heightPx?: number; widthPx?: number }

Returns

DrawingItem

# listChartsOnSheet function

src/drawing/drawing.ts:156

Read-only snapshot of every chart DrawingItem on the sheet. Each item has its anchor + chart reference.

function listChartsOnSheet(ws: Worksheet): readonly DrawingItem[]

Parameters

NameTypeDescription
ws Worksheet

Returns

readonly DrawingItem[]

# listImagesOnSheet function

src/drawing/drawing.ts:147

Read-only snapshot of every picture DrawingItem on the sheet. Returns the matching items (each with its anchor + picture reference). Empty array when the sheet has no drawing or only non-picture items.

function listImagesOnSheet(ws: Worksheet): readonly DrawingItem[]

Parameters

NameTypeDescription
ws Worksheet

Returns

readonly DrawingItem[]

# makeChartDrawingItem function

src/drawing/drawing.ts:72
function makeChartDrawingItem(anchor: DrawingAnchor, chart?: ChartReference): DrawingItem

Parameters

NameTypeDescription
anchor DrawingAnchor
chart? = {}ChartReference

Returns

DrawingItem

# makeDrawing function

src/drawing/drawing.ts:68
function makeDrawing(items?: DrawingItem[]): Drawing

Parameters

NameTypeDescription
items? = []DrawingItem[]

Returns

Drawing

# makePictureDrawingItem function

src/drawing/drawing.ts:76
function makePictureDrawingItem(anchor: DrawingAnchor, picture: PictureReference | XlsxImage): DrawingItem

Parameters

NameTypeDescription
anchor DrawingAnchor
picture PictureReference | XlsxImage

Returns

DrawingItem

# removeAllCharts function

src/drawing/drawing.ts:188

Drop every chart DrawingItem from the worksheet, leaving pictures and any other content kinds untouched. Returns the count removed.

function removeAllCharts(ws: Worksheet): number

Parameters

NameTypeDescription
ws Worksheet

Returns

number

# removeAllDrawingItems function

src/drawing/drawing.ts:166

Drop every DrawingItem from the worksheet. Returns the count removed. The `ws.drawing` field itself is left in place (empty) so subsequent `addImageAt` / `addChartAt` calls don't have to re-allocate.

function removeAllDrawingItems(ws: Worksheet): number

Parameters

NameTypeDescription
ws Worksheet

Returns

number

# removeAllImages function

src/drawing/drawing.ts:177

Drop every picture DrawingItem from the worksheet, leaving charts and any other content kinds untouched. Returns the count removed.

function removeAllImages(ws: Worksheet): number

Parameters

NameTypeDescription
ws Worksheet

Returns

number

Colors

src/drawing/dml/colors.ts

# makeColor function

src/drawing/dml/colors.ts:122
function makeColor(base: DmlColor, mods?: ColorMod[]): DmlColorWithMods

Parameters

NameTypeDescription
base DmlColor
mods? = []ColorMod[]

Returns

DmlColorWithMods

# makeSchemeColor function

src/drawing/dml/colors.ts:120
function makeSchemeColor(name: SchemeColorName): DmlColor

Parameters

NameTypeDescription
name SchemeColorName

Returns

DmlColor

# makeSrgbColor function

src/drawing/dml/colors.ts:118
function makeSrgbColor(rrggbb: string): DmlColor

Parameters

NameTypeDescription
rrggbb string

Returns

DmlColor

# SCHEME_COLOR_NAMES const

src/drawing/dml/colors.ts:31
const SCHEME_COLOR_NAMES: ReadonlyArray<SchemeColorName>

# VALUED_COLOR_MOD_KINDS const

src/drawing/dml/colors.ts:90

Color mod kinds that carry a numeric `val` attribute.

const VALUED_COLOR_MOD_KINDS: ReadonlyArray<ColorMod["kind"]>

# VALUELESS_COLOR_MOD_KINDS const

src/drawing/dml/colors.ts:87

Color mod kinds that take no `val` attribute (their elements are empty).

const VALUELESS_COLOR_MOD_KINDS: ReadonlyArray<ColorMod["kind"]>

Text

src/drawing/dml/text.ts

# makeBreak function

src/drawing/dml/text.ts:230
function makeBreak(rPr?: RunProperties): TextRun

Parameters

NameTypeDescription
rPr? RunProperties

Returns

TextRun

# makeParagraph function

src/drawing/dml/text.ts:232
function makeParagraph(runs: TextRun[], pPr?: ParagraphProperties, endParaRPr?: RunProperties): TextParagraph

Parameters

NameTypeDescription
runs TextRun[]
pPr? ParagraphProperties
endParaRPr? RunProperties

Returns

TextParagraph

# makeRun function

src/drawing/dml/text.ts:227
function makeRun(text: string, rPr?: RunProperties): TextRun

Parameters

NameTypeDescription
text string
rPr? RunProperties

Returns

TextRun

# makeRunProperties function

src/drawing/dml/text.ts:225
function makeRunProperties(opts?: Partial<RunProperties>): RunProperties

Parameters

NameTypeDescription
opts? = {}Partial<RunProperties>

Returns

RunProperties

# makeSimpleTextBody function

src/drawing/dml/text.ts:253

Convenience: build a single-paragraph body with one run.

function makeSimpleTextBody(text: string, rPr?: RunProperties): TextBody

Parameters

NameTypeDescription
text string
rPr? RunProperties

Returns

TextBody

# makeTextBody function

src/drawing/dml/text.ts:242
function makeTextBody(paragraphs: TextParagraph[], bodyPr?: TextBodyProperties, lstStyle?: TextListStyle): TextBody

Parameters

NameTypeDescription
paragraphs TextParagraph[]
bodyPr? = {}TextBodyProperties
lstStyle? TextListStyle

Returns

TextBody

Fill

src/drawing/dml/fill.ts

# makeGradientFill function

src/drawing/dml/fill.ts:84
function makeGradientFill(opts: { flip?: TileFlip; lineDir?: GradientLineDir; rotWithShape?: boolean; stops: GradientStop[] }): Fill

Parameters

NameTypeDescription
opts { flip?: TileFlip; lineDir?: GradientLineDir; rotWithShape?: boolean; stops: GradientStop[] }

Returns

Fill

# makeNoFill function

src/drawing/dml/fill.ts:81
function makeNoFill(): Fill

Returns

Fill

# makePatternFill function

src/drawing/dml/fill.ts:97
function makePatternFill(opts: { bgClr?: DmlColorWithMods; fgClr?: DmlColorWithMods; preset: string }): Fill

Parameters

NameTypeDescription
opts { bgClr?: DmlColorWithMods; fgClr?: DmlColorWithMods; preset: string }

Returns

Fill

# makeSolidFill function

src/drawing/dml/fill.ts:82
function makeSolidFill(color: DmlColorWithMods): Fill

Parameters

NameTypeDescription
color DmlColorWithMods

Returns

Fill

# PRESET_PATTERN_NAMES const

src/drawing/dml/fill.ts:109

Excel's preset pattern names (54 entries, ECMA-376 §20.1.10.50; matches openpyxl).

const PRESET_PATTERN_NAMES: ReadonlyArray<string>

Anchor

src/drawing/anchor.ts

# makeOneCellAnchor function

src/drawing/anchor.ts:71

Build a one-cell anchor pinned at `from` with an explicit pixel extent.

function makeOneCellAnchor(opts: { from: string | AnchorMarker; heightPx: number; widthPx: number }): DrawingAnchor

Parameters

NameTypeDescription
opts { from: string | AnchorMarker; heightPx: number; widthPx: number }

Returns

DrawingAnchor

Image

src/drawing/image.ts

# loadImage function

src/drawing/image.ts:253

Build an `XlsxImage` from raw bytes. Detects the format and dimensions automatically. Caller may pass an explicit `format` to override detection (e.g. when bytes were read from a `data:` URL with a known MIME type) or `width`/`height` to skip the parser.

function loadImage(bytes: Uint8Array, opts?: { format?: XlsxImageFormat; height?: number; width?: number }): XlsxImage

Parameters

NameTypeDescription
bytes Uint8Array
opts? = {}{ format?: XlsxImageFormat; height?: number; width?: number }

Returns

XlsxImage

Shape properties

src/drawing/dml/shape-properties.ts

# makeShapeProperties function

src/drawing/dml/shape-properties.ts:57
function makeShapeProperties(opts?: Partial<ShapeProperties>): ShapeProperties

Parameters

NameTypeDescription
opts? = {}Partial<ShapeProperties>

Returns

ShapeProperties