Office Kit
docx
English

API リファレンス

@office-kit/docx のすべての公開エクスポートと、@office-kit/docx-preview の唯一の関数を、31 のグループに分けて掲載しています（計 475 個）。ライブラリは関数と定数だけで構成されており、クラスはありません。ほとんどの関数は第 1 引数に Docx を受け取ります。モジュールには副作用がないため、インポートしなかったものはバンドラーが取り除きます。

このページは CI で実際にビルドしたパッケージと照合しているため、内容が古くなることはありません。引数の型は、パッケージに同梱されている型定義かソースコードを参照してください。そのまま貼り付けて使えるコードははじめにとレシピにあります。

ライフサイクル

ドキュメントの作成、読み込み、複製、シリアライズ。

  • createDocx ({ paragraphs? }?) => Docx
  • openDocx (bytes: Uint8Array) => Docx
  • fromBlob (blob: Blob) => Promise<Docx>
  • toUint8Array (doc: Docx) => Uint8Array
  • toBlob (doc: Docx) => Blob
  • clone (doc: Docx) => Docx

段落とブロック

本文の段落、見出し、区切りの追加、挿入、削除。

  • appendParagraph
  • insertParagraphAt
  • removeParagraph
  • appendHeading
  • appendPageBreak
  • appendLineBreak
  • appendSectionBreak
  • clearBody
  • paragraphs

インラインとテキスト

検索と置換、ランとその書式、段落の配置、インデント、間隔、罫線、網かけ。

  • replaceText
  • replaceTextEverywhere
  • findText
  • findTextEverywhere
  • appendTextRun
  • setParagraphText
  • paragraphText
  • setRunFormat
  • clearRunFormat
  • getRunFormat
  • HIGHLIGHT_COLORS readonly HighlightColor[] — the only w:highlight values run-format writers accept
  • setParagraphAlignment
  • getParagraphAlignment
  • setParagraphIndent
  • setParagraphSpacing
  • setParagraphBorders
  • setParagraphShading
  • getParagraphStyle
  • getParagraphNumbering
  • mergeAdjacentRuns
  • mergeAdjacentRunsInBody
  • setRunOnOff
  • setRunValProp
  • getRunProp
  • setParagraphOnOff
  • setParagraphValProp
  • getParagraphProp
  • splitParagraphAt
  • mergeParagraphIntoPrevious
  • runTextLength
  • isolateParagraphRunRange

スタイルと段落番号

スタイル定義、箇条書きと番号付きリスト、デザイン済みテンプレートからのスタイルの取り込み。

  • addStyle
  • removeStyle
  • listStyles
  • ensureHeadingStyles
  • findStyleIdByName
  • setParagraphStyle
  • addBulletList
  • addNumberedList
  • applyListToParagraph
  • mergeStylesFromTemplate
  • setStyleOnOff
  • setStyleValProp
  • getStyleProp
  • setNumberingLevelOnOff
  • setNumberingLevelVal
  • getNumberingLevelProp

表

表の作成と、行、セルのテキスト、罫線、網かけ、配置の編集。

  • addTable
  • tables
  • removeTable
  • removeAllTables
  • unwrapTable
  • appendTableRow
  • removeTableRow
  • setTableRowAsHeader
  • setTableRowHeight
  • setTableBorders
  • setTableCellText
  • getTableCellText
  • setTableCellShading
  • setTableCellVerticalAlign

表のレイアウト

Word の［レイアウト］（表ツール）タブの操作。任意の位置への行・列・セルの挿入、結合と分割、サイズ、余白、並べ替え、文字列への変換、計算式。

  • tableCellPlacements (table) => TableCellPlacement[][]
  • tableColumnCount
  • tableColumnWidths
  • tableCellBlocks
  • insertTableRow (table, index, { formatFrom? }?) => WmlTableRow
  • deleteTableRows
  • insertTableColumn (table, index, { widthTwips?, formatFrom? }?) => void
  • deleteTableColumns
  • deleteTableCells (table, range, 'left' | 'up') => void
  • mergeTableCells (table, range: TableCellRange) => void
  • splitTableCell (table, row, cell, { columns, rows }) => void
  • splitTable (doc, table, row) => WmlTable
  • setTableWidth
  • setTableAlignment
  • setTableIndent
  • setTableLayout
  • setTableCellSpacing
  • setTableDefaultCellMargins
  • setTableAltText
  • setTablePosition
  • setTableCellWidth
  • setTableCellMargins
  • setTableCellTextDirection
  • setTableColumnWidth
  • distributeTableColumns
  • autoFitTable (table, 'contents' | 'window' | 'fixed') => void
  • setTableRangeBorders (table, range, edges, border?) => void
  • sortTableRows (table, { keys, headerRow? }) => void
  • convertTextToTable (doc, first, last, { separator, columns? }) => WmlTable
  • evaluateTableFormula (table, row, cell, formula) => number
  • formatFieldNumber

表のスタイル

Word の組み込みの表スタイル（標準の表、グリッド テーブル、リスト テーブル）、表スタイルのオプション、表スタイルの書式。

  • BUILT_IN_TABLE_STYLES
  • addBuiltInTableStyle (doc, styleId) => void
  • builtInTableStyle
  • setTableStyle
  • getTableStyle
  • setTableLook (table, look: TableLook) => void
  • getTableLook
  • setTableStyleFormatting (doc, styleId, region, formatting) => void

画像

インライン画像の追加、ファイル内の画像の一覧取得、パーツ名または代替テキストによる差し替え。

  • addImage
  • addImageRun
  • insertImageInto
  • images
  • imageReferences
  • replaceImage
  • replaceImageByAltText
  • removeAllImages
  • imageDrawings
  • getImageInfo
  • setImageAltText
  • setImageSizeEmu

図、グラフ、配置

［図の形式］と［配置］の操作。文字列の折り返し、位置、重なり順、トリミング、図形、枠線、効果、色の調整に加え、ブックを埋め込んだ［挿入］▸［グラフ］。描画オブジェクトは imageDrawings のインデックスで指定します。

  • readDrawing (doc, drawing: XmlElement) => DrawingInfo
  • imagePixelSize (bytes) => ImagePixelSize | undefined
  • imageNaturalSizeEmu (bytes) => { widthEmu, heightEmu } | undefined
  • setDrawingWrap (doc, index, wrap: WrapStyle, position?) => void
  • setDrawingPosition (doc, index, { horizontal?, vertical? }) => void
  • setDrawingAnchorOptions (doc, index, AnchorOptions) => void
  • arrangeDrawing (doc, index, op: DrawingOrder) => void
  • setDrawingTransform (doc, index, { rotation?, flipH?, flipV? }) => void
  • setDrawingName (doc, index, name) => void
  • setDrawingHidden (doc, index, hidden) => void
  • setDrawingAspectLock (doc, index, locked) => void
  • setDrawingHyperlink (doc, index, url | undefined) => void
  • removeDrawing (doc, index) => void
  • setPictureCrop (doc, index, PictureCrop) => void
  • setPictureGeometry (doc, index, preset: string) => void
  • setPictureOutline (doc, index, PictureOutline | undefined) => void
  • setPictureEffects (doc, index, PictureEffects) => void
  • setPictureColorAdjustments (doc, index, PictureColorAdjustments) => void
  • changePicture (doc, index, bytes, contentType?) => void
  • resetPicture (doc, index, { size? }?) => void
  • addChartRun (doc, spec: ChartSpec, { widthEmu, heightEmu, name?, altText? }) => WmlRun
  • readChart (doc, drawing: XmlElement) => ChartSpec | undefined
  • setChart (doc, index, spec: ChartSpec) => void

ヘッダー、フッター、セクション

標準ページ・先頭ページ・偶数ページ用のヘッダーとフッター、用紙サイズ、余白、印刷の向き。

  • addHeader
  • addFooter
  • addPageNumberFooter
  • setPageSize
  • setPageMargins
  • setPageOrientation
  • headers
  • footers
  • removeAllHeaders
  • removeAllFooters

フィールドと変更履歴

目次や差し込みフィールドなどの複合フィールドと、変更履歴の挿入・削除の一括承諾・却下。

  • appendField
  • addTableOfContents
  • appendMergeField
  • acceptAllRevisions
  • rejectAllRevisions

指定位置への挿入

Word の［挿入］タブで段落内の文字位置に配置できるもの。計算結果付きの複合フィールド、リンク、ブックマーク、記号と特殊文字、数式、ドロップ キャップ、署名欄。

  • insertField (doc, paragraph, offset, instruction, { result?, rPr?, lang?, context? }?) => WmlRun[]
  • buildComplexField (instruction, result, rPr?, beginChildren?) => WmlRun[]
  • updateFields (doc, { now?, page?, pageCount?, types? … }?) => number
  • complexFields (doc) => FieldInfo[]
  • insertFormField (doc, paragraph, offset, FormFieldOptions) => WmlRun[]
  • formatDatePicture (date, picture, locale?) => string
  • quoteFieldArgument (value) => string
  • insertHyperlink (doc, paragraph, offset, text, { url? | bookmark?, tooltip?, targetFrame? }) => XmlElement
  • paragraphHyperlinks (doc, paragraph) => HyperlinkInfo[]
  • editHyperlink
  • removeHyperlink
  • insertBookmark (doc, name, start: TextPoint, end?: TextPoint) => number
  • isValidBookmarkName (name) => boolean
  • ensureReferenceBookmark (doc, paragraph, run?) => string
  • insertSymbol (doc, paragraph, offset, SymbolSpec, rPr?) => WmlRun
  • insertEquation (doc, paragraph, offset, linear, { display? }?) => XmlElement
  • buildEquation (linear, { display? }?) => XmlElement
  • equationLinear (element) => string
  • paragraphEquations (paragraph) => XmlElement[]
  • setEquation (doc, paragraph, index, linear) => XmlElement
  • getDropCap (doc, paragraph) => DropCapOptions
  • setDropCap (doc, paragraph, { position, lines?, distanceTwips?, font? }) => void
  • insertSignatureLine (doc, paragraph, offset, SignatureLineOptions) => WmlRun

ページ、ヘッダー、ページ番号

表紙、ヘッダーとフッターの内容、ページ番号とその書式、別のドキュメントの内容の取り込み（［挿入］▸［オブジェクト］▸［ファイルからテキスト］）。

  • insertCoverPage (doc, paragraphs) => void
  • removeCoverPage (doc) => boolean
  • hasCoverPage (doc) => boolean
  • setDifferentFirstPage (doc, on) => void
  • headerFooterParagraphs (doc, kind, type?) => WmlParagraph[]
  • setHeaderFooterParagraphs (doc, kind, type, paragraphs) => void
  • removeHeaderFooter (doc, kind, type?) => boolean
  • ensureHeaderFooterStyle (doc, kind) => string
  • insertPageNumbers (doc, { position, align, style? }) => void
  • removePageNumbers (doc) => number
  • setPageNumberFormat (doc, { format?, start?, chapterStyle?, chapterSeparator? }) => void
  • getPageNumberFormat (doc) => PageNumberFormatOptions
  • PAGE_NUMBER_FORMATS
  • CHAPTER_SEPARATORS
  • insertDocumentContent (doc, source: Docx, blockIndex) => number

ドキュメントのプロパティ

コアプロパティとアプリケーションプロパティ。タイトルと作成者にはショートカットがあります。

  • coreProperties
  • setCoreProperties
  • appProperties
  • setAppProperties
  • title
  • author
  • setTitle
  • setAuthor
  • getDocumentSetting
  • setDocumentSettingOnOff
  • setDocumentSettingVal

図形、テキストボックス、ワードアート、インク（VML）

Word のギャラリーにある図形、テキストボックス、ワードアート、インクのストローク、描画キャンバスを ECMA-376 の VML（`w:pict`）として描画し、塗りつぶし、枠線、影、レイアウト、文字列の折り返し、重なり順、テキスト、グループ化を編集します。図形のハンドルは VML 要素そのものです。

  • addShape (doc, paragraph, { preset, width, height, left?, top?, wrap?, fill?, stroke?, text?, points?, ink? }, index?) => XmlElement
  • addWordArt (doc, paragraph, { text, width, height, font?, size?, bold?, italic? }, index?) => XmlElement
  • addDrawingCanvas (doc, paragraph, { width, height }, index?) => XmlElement
  • addShapeToGroup (doc, group, options) => XmlElement
  • vmlShapes (doc) => XmlElement[]
  • runShape (run) => XmlElement | undefined
  • shapeKind
  • shapePreset
  • SHAPE_PRESETS
  • SHAPE_CATEGORIES
  • changeShapePreset
  • getShapePoints
  • setShapePoints
  • getShapeLayout
  • setShapeLayout
  • getShapeWrap
  • setShapeWrap
  • setShapeOrder
  • setShapeMoveWithText
  • getShapeFill
  • setShapeFill
  • vmlImageData
  • FILL_PATTERNS
  • getShapeStroke
  • setShapeStroke
  • getShapeShadow
  • setShapeShadow
  • shapeText
  • setShapeText
  • getTextBoxLayout
  • setTextBoxLayout
  • linkTextBoxes
  • linkedTextBox
  • getWordArt
  • setWordArt
  • getShapeAltText
  • setShapeAltText
  • getShapeName
  • setShapeName
  • removeShape
  • groupShapes
  • ungroupShapes
  • groupMembers

SmartArt

SmartArt グラフィック（DrawingML のダイアグラム。データモデル、レイアウト、スタイル、色の各パーツ）の挿入と、箇条書き、レイアウト、色、スタイル、サイズの編集。

  • addSmartArt (doc, paragraph, { layout, nodes, width?, height?, colors?, style? }, index?) => WmlRun
  • smartArts (doc) => SmartArtRef[]
  • runSmartArt (doc, run) => SmartArtRef | undefined
  • getSmartArt
  • setSmartArtNodes
  • setSmartArtLayout
  • setSmartArtColors
  • setSmartArtStyle
  • setSmartArtSize
  • removeSmartArt
  • SMARTART_LAYOUTS
  • SMARTART_COLORS
  • SMARTART_STYLES

診断

パッケージの検証と、ドキュメント内容の読み取り（アウトライン、フィールド、統計情報、プレーンテキスト）。

  • validate
  • validatePackage
  • statistics
  • outline
  • fields
  • text

校閲: 変更履歴

変更履歴の一覧取得、承諾、却下。挿入・削除・書式変更の変更履歴としての記録と、2 つのドキュメントの比較。

  • revisions (doc: Docx) => RevisionInfo[]
  • acceptRevisions (doc: Docx, ids: readonly string[]) => number
  • rejectRevisions (doc: Docx, ids: readonly string[]) => number
  • insertTrackedText
  • deleteTrackedText
  • paragraphMarkRevision
  • trackParagraphMark
  • trackRunFormatChange
  • trackParagraphFormatChange
  • compareDocuments (original: Docx, revised: Docx, options: CompareOptions) => Docx

校閲: コメント、文章校正、アクセシビリティ

コメントの読み取りと編集、校正言語の設定、Word と同じ方法での文字数カウント、アクセシビリティ チェック。

  • comments (doc: Docx) => CommentInfo[]
  • setCommentText
  • removeComment
  • getRunLanguage
  • setRunLanguage
  • wordCount (doc: Docx, options?: WordCountOptions) => WordCount
  • checkAccessibility (doc: Docx) => AccessibilityIssue[]
  • contrastRatio

ドキュメントの保護

編集の制限（パスワードは任意）、編集を許可する例外、常に読み取り専用で開く設定。

  • documentProtection
  • protectDocument (doc: Docx, options: ProtectOptions) => void
  • unprotectDocument (doc: Docx, password: string) => boolean
  • verifyProtectionPassword
  • writeProtection
  • setWriteProtection
  • editableRanges
  • addEditableRange
  • removeEditableRange

表示とユーザー設定のプロパティ

ドキュメントを開いたときの表示モードとズーム、ユーザー設定のドキュメント プロパティ。

  • documentView
  • setDocumentView
  • documentZoom
  • setDocumentZoom
  • customProperties
  • setCustomProperty
  • removeCustomProperty

低レベルのパーツ アクセス

解析済みの補助パーツ。上記の関数では手が届かない場合に使います。

  • stylesPart
  • numberingPart
  • commentsPart
  • footnotesPart
  • endnotesPart
  • xmlPartNames
  • getRawPartRoot
  • markRawPartDirty
  • childElementsOf
  • appendChildElement
  • makePropsElement
  • getElementAttr
  • setElementAttr
  • getElementProp
  • setElementOnOff
  • setElementValProp

ストーリーとセクションのヘッダー

ヘッダー、フッター、脚注、文末脚注、コメントを型付きのブロック コンテンツとして扱う関数と、各セクションに表示するヘッダー・フッターの指定。

  • storyBody (doc, ref: StoryRef) => WmlBody | undefined
  • contentControlBlocks (block: WmlBlock) => readonly WmlBlock[] | undefined
  • wrappedRuns (inline: WmlInline) => readonly WmlRun[] | undefined
  • storyView (doc, ref: StoryRef) => Docx | undefined
  • storyKey (ref: StoryRef) => string
  • parseStoryKey (key: string) => StoryRef | undefined
  • sectionProperties (doc) => Array<XmlElement | undefined>
  • resolveHeaderFooter (doc, section, kind, type) => { partName, section } | undefined
  • ensureHeaderFooter (doc, section, kind, type) => string
  • isHeaderFooterLinked (doc, section, kind, type) => boolean
  • setHeaderFooterLinked (doc, section, kind, type, linked) => void

文字書式と段落書式

テーマの色、すべての下線スタイル、テーマのフォント、ランの網かけと罫線、段落の辺ごとの罫線、タブ位置、ルビ、囲い文字、リストの定義、Word の組み込みスタイル。

  • setRunColor (run, color: ColorValue | undefined) => void
  • setRunUnderline (run, underline: UnderlineValue | undefined) => void
  • setRunFont (run, script, font: FontChoice | undefined) => void
  • setRunShading (run, shading: ShadingOptions | undefined) => void
  • setRunBorder (run, line: BorderLine | undefined) => void
  • setParagraphBorder (p, side, line: BorderLine | undefined) => void
  • setParagraphTabs (p, tabs: TabStop[]) => void
  • getParagraphTabs (p) => TabStop[]
  • buildRubyRun (base, ruby, options, rPr?) => WmlRun
  • readRuby (run) => RubyInfo | undefined
  • buildEnclosedCharacterRuns (text, options, rPr?) => WmlRun[]
  • addListDefinition (doc, levels: ListLevel[]) => number
  • restartList (doc, numId, ilvl, start) => number | undefined
  • ensureBuiltinStyle (doc, styleId) => boolean
  • builtinStyles () => BuiltinStyleInfo[]
  • updateStyleFormatting (doc, styleId, { run?, paragraph? }) => boolean
  • THEME_COLORS
  • UNDERLINE_STYLES
  • SHADING_PATTERNS
  • BORDER_LINE_STYLES
  • RUBY_ALIGNMENTS
  • ENCLOSURES
  • NUMBER_FORMATS

用紙サイズと余白の定数

setPageSize と setPageMargins にそのまま渡せる値と、ライブラリのバージョン。

  • PAGE_SIZE_A4
  • PAGE_SIZE_LETTER
  • MARGINS_NORMAL
  • VERSION

セクションのレイアウト

セクション単位の段組み、行番号、ページ罫線、垂直方向の配置、文字グリッド、セクション区切り。

  • sectionCount (doc) => number
  • sectionIndexAt (doc, blockIndex) => number
  • getSectionProperties (doc, section?) => SectionProperties
  • setSectionProperties (doc, patch, scope?) => void
  • insertSectionBreak (doc, blockIndex, start?) => number
  • PAGE_BORDER_LINE_STYLES readonly string[] — line styles for page borders
  • PAGE_BORDER_ART readonly string[] — art border names (ST_Border)

デザイン: テーマ、スタイル セット、ページの背景

テーマ パーツ（配色、フォント、効果）、スタイル セット、段落の既定の間隔、ページの色、透かし。

  • setTheme (doc, theme: ThemeDefinition) => void
  • getTheme (doc) => ThemeInfo | undefined
  • setThemeColors (doc, colors: ThemeColorScheme) => void
  • setThemeFonts (doc, fonts: ThemeFontScheme) => void
  • setThemeEffects (doc, effects: ThemeEffectScheme) => void
  • themeColorValue (colors, themeColor, { shade?, tint? }?) => string | undefined
  • applyStyleSet (doc, set: StyleSetDefinition) => void
  • currentStyleSet (doc) => StyleSetDefinition | undefined
  • setDefaultParagraphSpacing (doc, { before, after, line }) => void
  • getDefaultParagraphSpacing (doc) => DefaultParagraphSpacing | undefined
  • setPageColor (doc, color: PageColor | undefined) => void
  • getPageColor (doc) => PageColor | undefined
  • setWatermark (doc, watermark: Watermark | undefined) => void
  • getWatermark (doc) => WatermarkInfo | undefined
  • THEMES
  • THEME_COLOR_SCHEMES
  • THEME_COLOR_SLOTS
  • THEME_FONT_SCHEMES
  • THEME_EFFECT_SCHEMES
  • STYLE_SETS
  • PARAGRAPH_SPACING_PRESETS

参考資料

Word の［参考資料］タブ。目次と図表目次、脚注と文末脚注、引用文献と文献目録、図表番号、索引、引用文献一覧を、計算済みのフィールド結果とともに扱います。

  • insertTableOfContents (doc, at, options?) => void
  • tableOfContentsInstruction
  • removeTableOfContents
  • setTocLevel (doc, paragraph, level | 'none') => void
  • tocLevel
  • updateTables (doc, { types?, pageOf? }?) => number
  • insertNote (doc, paragraph, offset, 'footnote' | 'endnote', options?) => number
  • noteMarks
  • noteText
  • setNoteText
  • noteProperties
  • setNoteProperties
  • convertNotes
  • bibliographySources
  • setBibliographySources
  • bibliographyStyle
  • setBibliographyStyle
  • suggestSourceTag
  • citationInstruction
  • insertCitation
  • insertBibliography
  • insertCaption (doc, blockIndex, 'above' | 'below', options) => WmlParagraph
  • captionLabels
  • addCaptionLabel
  • indexEntryInstruction
  • markIndexEntry
  • markAllIndexEntries
  • indexInstruction
  • insertIndex
  • markAuthorityCitation
  • insertTableOfAuthorities
  • CITATION_STYLES
  • SOURCE_TYPES
  • SOURCE_FIELDS
  • BIBLIOGRAPHY_TITLES
  • CAPTION_LABELS
  • AUTHORITY_CATEGORIES

差し込み文書

封筒、ラベル、差し込み印刷。データ ソースの設定、差し込みフィールドとルール、宛先のプレビュー、新規文書への差し込み。

  • addEnvelope
  • removeEnvelope
  • createLabelDocument (options) => Docx
  • updateLabels
  • mailMergeSettings
  • setMailMergeDocumentType
  • parseRecipientCsv
  • recipientListToCsv
  • attachRecipientList
  • autoFieldMap
  • mailMergeFieldMap
  • setMailMergeFieldMap
  • setRecipientInclusion
  • recipientInclusion
  • mergeFieldInstruction
  • insertMergeField
  • addressBlockInstruction
  • insertAddressBlock
  • greetingLineInstruction
  • insertGreetingLine
  • insertMergeRule
  • mergeFieldNames
  • mergeFieldErrors
  • previewMailMerge (doc, list, index | undefined, options?) => void
  • mergeToNewDocument (doc, list, options?) => Docx
  • ENVELOPE_SIZES
  • LABEL_PRODUCTS
  • ADDRESS_FIELDS
  • ADDRESS_NAME_FORMATS
  • GREETING_NAME_FORMATS

ブラウザー プレビュー（@office-kit/docx-preview）

姉妹パッケージの唯一のエントリーポイント。

  • previewToDOM (source, container, options?) => Promise<Handle>