Customui Ribbon

CUSTOMUI_2006_NAMESPACE

_const

The customUI root namespaces, one per RibbonDialect.

const CUSTOMUI_2006_NAMESPACE: "http://schemas.microsoft.com/office/2006/01/customui"

---

CUSTOMUI_2007_REL_TYPE

_const

const CUSTOMUI_2007_REL_TYPE: "http://schemas.microsoft.com/office/2006/relationships/ui/extensibility"

---

CUSTOMUI_2009_NAMESPACE

_const

const CUSTOMUI_2009_NAMESPACE: "http://schemas.microsoft.com/office/2009/07/customui"

---

CUSTOMUI_2010_REL_TYPE

_const

const CUSTOMUI_2010_REL_TYPE: "http://schemas.microsoft.com/office/2007/relationships/ui/extensibility"

---

CustomUiDocument

_interface

A parsed customUI part. dialect records which schema it was written against (derived from the root namespace, the authoritative signal). ribbon is the parsed <ribbon> subtree, or undefined when the document customises only backstage/QAT/commands (which v1 does not parse). Future work can extend this with backstage/qat without changing the shape callers already depend on.

interface CustomUiDocument {
  readonly dialect: RibbonDialect;
  readonly ribbon?: Ribbon;
}

---

isCustomUiRelType

_function

Whether a package-root relationship Type URI points at a customUI ribbon part.

function isCustomUiRelType(type: string): boolean;

---

parseCustomUi

_function

Parse a customUI part (raw UTF-8 bytes or its decoded text) into a CustomUiDocument.

function parseCustomUi(input: string | Uint8Array): CustomUiDocument;

Throws: CustomUiParseError if the XML is malformed, the root is not a <customUI> element in a recognised namespace, or the tree nests beyond MAX_DEPTH.

---

Ribbon

_interface

The parsed <ribbon> element: whether it starts from a blank ribbon, and its custom tabs. Only the <tabs> subtree is modelled; qat and contextualTabs are not parsed in v1.

interface Ribbon {
  /** `startFromScratch="true"` reduces the built-in ribbon to a minimal set before custom tabs apply. */
  readonly startFromScratch: boolean;
  readonly tabs: readonly RibbonTab[];
}

---

RibbonControl

_interface

A control element inside a ribbon group. kind is the element's local name, narrowed to the closed set of RibbonX control elements (RibbonControlKind); an element outside that set is surfaced as unknown rather than dropped. The three identity attributes (id a document-defined control, idQ a qualified id, idMso a built-in control) and the two most-consulted display/behaviour attributes (label, onAction) are lifted out as typed conveniences; every attribute the element actually carried, including the many get* dynamic callbacks and layout hints not modelled here, is preserved verbatim in attributes, so nothing is lost. Container controls (a menu, splitButton, gallery, dropDown, box, …) carry their nested controls/items in children.

interface RibbonControl {
  readonly kind: RibbonControlKind;
  /** A document-defined control id. */
  readonly id?: string;
  /** A namespace-qualified control id (`idQ`), used to reference a control across add-ins. */
  readonly idQ?: string;
  /** The id of a built-in (Microsoft-defined) control this element repurposes or places against. */
  readonly idMso?: string;
  /** The static label, when the element carries one (a dynamic label uses `getLabel`, in {@link attributes}). */
  readonly label?: string;
  /** The callback procedure name invoked on activation: the macro a click runs. */
  readonly onAction?: string;
  /** Every attribute on the element, verbatim and entity-decoded. The typed fields above are lifted from
   * here; this map is the complete record, including attributes this model does not lift out. */
  readonly attributes: Readonly<Record<string, string>>;
  /** Nested controls or items, for a container control; absent for a leaf control. */
  readonly children?: readonly RibbonControl[];
}

---

RibbonControlKind

_type

The RibbonX control elements this reader recognises. item is a dropDown/gallery/comboBox entry; unknown is the fallback for any element outside this set (never silently dropped).

type RibbonControlKind =
  | 'button'
  | 'toggleButton'
  | 'checkBox'
  | 'editBox'
  | 'dropDown'
  | 'comboBox'
  | 'gallery'
  | 'menu'
  | 'dynamicMenu'
  | 'splitButton'
  | 'buttonGroup'
  | 'box'
  | 'labelControl'
  | 'separator'
  | 'menuSeparator'
  | 'dialogBoxLauncher'
  | 'control'
  | 'item'
  | 'unknown';

---

RibbonDialect

_type

The customUI schema a part is written against. The read model keys off this, not the (frequently mis-copied) relationship type. 2007 is the original RibbonX (customUI.xml); 2010 is the later schema (customUI14.xml) that also carries backstage/QAT/commands.

type RibbonDialect = '2007' | '2010';

---

RibbonGroup

_interface

A <group> within a ribbon tab: its identity/label attributes and the controls it contains.

interface RibbonGroup {
  readonly id?: string;
  readonly idQ?: string;
  readonly idMso?: string;
  readonly label?: string;
  /** Every attribute on the `<group>`, verbatim. */
  readonly attributes: Readonly<Record<string, string>>;
  readonly controls: readonly RibbonControl[];
}

---

RibbonTab

_interface

A <tab> within the ribbon: its identity/label attributes and the groups it contains.

interface RibbonTab {
  readonly id?: string;
  readonly idQ?: string;
  readonly idMso?: string;
  readonly label?: string;
  /** Every attribute on the `<tab>`, verbatim. */
  readonly attributes: Readonly<Record<string, string>>;
  readonly groups: readonly RibbonGroup[];
}