Office Kit
xlsx

Drawings & images

Picture / chart anchors, image format detection.

34 exports from 9 source files

Drawing

src/drawing/drawing.ts

addChartAt function

src/drawing/drawing.ts:193

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:169

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:224

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:215

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:136
function makeChartDrawingItem(anchor: DrawingAnchor, chart?: ChartReference): DrawingItem

Parameters

NameTypeDescription
anchor DrawingAnchor
chart? = {}ChartReference

Returns

DrawingItem

makeDrawing function

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

Parameters

NameTypeDescription
items? = []DrawingItem[]

Returns

Drawing

makePictureDrawingItem function

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

Parameters

NameTypeDescription
anchor DrawingAnchor
picture PictureReference | XlsxImage

Returns

DrawingItem

makeShapeDrawingItem function

src/drawing/drawing.ts:147
function makeShapeDrawingItem(anchor: DrawingAnchor, shape: ShapeReference): DrawingItem

Parameters

NameTypeDescription
anchor DrawingAnchor
shape ShapeReference

Returns

DrawingItem

removeAllCharts function

src/drawing/drawing.ts:256

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:234

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:245

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>

Geometry

src/drawing/dml/geometry.ts

makePresetGeometry function

src/drawing/dml/geometry.ts:303
function makePresetGeometry(prst: string, avLst?: ShapeGuide[]): PresetGeometry

Parameters

NameTypeDescription
prst string
avLst? ShapeGuide[]

Returns

PresetGeometry

PRESET_SHAPE_NAMES const

src/drawing/dml/geometry.ts:16

ECMA-376 §20.1.10.55 preset shape catalogue (ST_PresetShapeType, 187 entries). Pulled from openpyxl's PresetGeometry2D.prst Set so the test corpus stays directly comparable.

const PRESET_SHAPE_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

Line

src/drawing/dml/line.ts

makeLine function

src/drawing/dml/line.ts:47
function makeLine(opts?: Partial<LineProperties>): LineProperties

Parameters

NameTypeDescription
opts? = {}Partial<LineProperties>

Returns

LineProperties

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