API reference / Common / Engine types / TextSpan

Type Alias: TextSpan

type TextSpan = 
  | {
  regular: TextRegular;
}
  | {
  break: TextBreak;
}
  | {
  tab: TextTab;
}
  | {
  simpleField: TextSimpleField;
}
  | {
  complexFieldStart: TextComplexFieldStart;
}
  | {
  complexFieldEnd: TextComplexFieldEnd;
}
  | {
  bookmarkStart: TextBookmarkStart;
}
  | {
  bookmarkEnd: TextBookmarkEnd;
}
  | {
  control: TextControlSpan;
}
  | {
  customXml: TextCustomXmlSpan;
}
  | {
  smartTag: TextSmartTagSpan;
}
  | {
  drawing: TextDrawing;
}
  | {
  embeddedObject: TextEmbeddedObject;
}
  | {
  math: TextMath;
};

One span in a TextParagraph — the text leaf, a special inline, or a container of nested spans.

A Regular span is the text leaf: it carries the String directly (a span is already the maximal stretch of uniform character properties, so there is no separate text node below it).

Break, Tab, Drawing, EmbeddedObject, Math, SimpleField and a complex field's two marks are all single-unit inlines — an object-replacement position a caret can sit before and after, and never inside. A bookmark's two marks are units too, but metadata the caret steps over. The containers are Control, CustomXml and SmartTag — siblings of w:r in EG_ContentRunContent, alike in shape, each bracketing nested spans that live in the paragraph's own offset space.

The two field variants are two field systems, sharing no type. A SimpleField is one self-contained element that computes its own value; a complex field is a ComplexFieldStart … ComplexFieldEnd pair with the result as ordinary spans between them, wherever the file put them — including in another paragraph. Neither is a container, which is why there is no field variant holding spans. See Text Fields.

The set is a superset union across the office family, and maps one variant to one run-content element. Two variants carry only DrawingML's subset: DrawingML has no explicit Tab (it uses a literal tab char in a Regular span) and folds every Break onto TextBreakKind::Line; the two embedding variants and the complex marks are docx-only, since an a:txBody paragraph holds nothing but a:r / a:br / a:fld. Hyperlinks are not a span — they live in [TextCharacterProperties] (a:rPr/a:hlinkClick), which is how DrawingML models them and where docx's w:hyperlink container normalizes to. A bookmark is a token pair like a complex field — BookmarkStart … BookmarkEnd — but paired by id, since bookmarks may overlap; see Text Model.