Word.CustomXmlPart class

Stellt ein benutzerdefiniertes XML-Teil dar.

Hinweise

Verwendet von

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part.yaml

// Adds a custom XML part.
await Word.run(async (context) => {
  const originalXml =
    "<Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
  const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.add(originalXml);
  customXmlPart.load("id");
  const xmlBlob = customXmlPart.getXml();

  await context.sync();

  const readableXml = addLineBreaksToXML(xmlBlob.value);
  console.log("Added custom XML part:", readableXml);

  // Store the XML part's ID in a setting so the ID is available to other functions.
  const settings: Word.SettingCollection = context.document.settings;
  settings.add("ContosoReviewXmlPartId", customXmlPart.id);

  await context.sync();
});

Eigenschaften

builtIn	Ruft ab, ob der `CustomXmlPart` integriert ist.
context	Der dem Objekt zugeordnete Anforderungskontext. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden.
documentElement	Ruft das Stammelement eines gebundenen Datenbereichs im Dokument ab. Wenn der Bereich leer ist, wird die Eigenschaft zurückgegeben `Nothing`.
errors	Ruft ein `CustomXmlValidationErrorCollection` Objekt ab, das Zugriff auf XML-Validierungsfehler ermöglicht.
id	Ruft die ID des benutzerdefinierten XML-Teils ab.
namespaceManager	Ruft den Satz von Namespacepräfixzuordnungen ab, die für das aktuelle `CustomXmlPart` Objekt verwendet werden.
namespaceUri	Ruft den Namespace-URI des benutzerdefinierten XML-Teils ab.
schemaCollection	Gibt ein `CustomXmlSchemaCollection` Objekt an, das den Satz von Schemas darstellt, die an einen gebundenen Datenbereich im Dokument angefügt sind.
xml	Ruft die XML-Darstellung des aktuellen `CustomXmlPart` Objekts ab.

Methoden

addNode(parent, options)	Fügt der XML-Struktur einen Knoten hinzu.
delete()	Löscht die benutzerdefinierte XML-Komponente.
deleteAttribute(xpath, namespaceMappings, name)	Löscht ein Attribut mit dem angegebenen Namen aus dem durch xpath identifizierten Element.
deleteElement(xpath, namespaceMappings)	Löscht das durch xpath identifizierte Element.
getXml()	Ruft den vollständigen XML-Inhalt des benutzerdefinierten XML-Teils ab.
insertAttribute(xpath, namespaceMappings, name, value)	Fügt ein Attribut mit dem angegebenen Namen und Wert in das durch xpath identifizierte Element ein.
insertElement(xpath, xml, namespaceMappings, index)	Fügt die angegebene XML unter dem durch xpath identifizierten übergeordneten Element am Index der untergeordneten Position ein.
load(options)	Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "`context.sync()`" aufrufen.
load(propertyNames)	Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "`context.sync()`" aufrufen.
load(propertyNamesAndPaths)	Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "`context.sync()`" aufrufen.
loadXml(xml)	Füllt das `CustomXmlPart` Objekt aus einer XML-Zeichenfolge.
query(xpath, namespaceMappings)	Fragt den XML-Inhalt des benutzerdefinierten XML-Teils ab.
selectNodes(xPath)	Wählt eine Auflistung von Knoten aus einer benutzerdefinierten XML-Komponente aus.
selectSingleNode(xPath)	Wählt einen einzelnen Knoten in einer benutzerdefinierten XML-Komponente aus, der einem XPath-Ausdruck entspricht.
set(properties, options)	Legt mehrere Eigenschaften eines Objekts gleichzeitig fest. Sie können entweder ein einfaches Objekt mit den entsprechenden Eigenschaften oder ein anderes API-Objekt desselben Typs übergeben.
set(properties)	Legt mehrere Eigenschaften für das Objekt gleichzeitig fest, basierend auf einem vorhandenen geladenen Objekt.
setXml(xml)	Legt den vollständigen XML-Inhalt des benutzerdefinierten XML-Teils fest.
toJSON()	Überschreibt die JavaScript-Methode `toJSON()` , um eine nützlichere Ausgabe bereitzustellen, wenn ein API-Objekt an `JSON.stringify()`übergeben wird. (`JSON.stringify`ruft wiederum die `toJSON` Methode des Objekts auf, das an sie übergeben wird.) Während das ursprüngliche `Word.CustomXmlPart` Objekt ein API-Objekt ist, gibt die `toJSON` Methode ein einfaches JavaScript-Objekt (als `Word.Interfaces.CustomXmlPartData`) zurück, das flache Kopien aller geladenen untergeordneten Eigenschaften des ursprünglichen Objekts enthält.
track()	Nachverfolgung des Objekts zwecks automatischer Anpassung auf der Grundlage der umgebenden Änderungen im Dokument. Dieser Aufruf ist eine Kurzform für context.trackedObjects.add(thisObject). Wenn Sie dieses Objekt aufrufübergreifend `.sync` und außerhalb der sequenziellen Ausführung eines ".run"-Batches verwenden und beim Festlegen einer Eigenschaft oder beim Aufrufen einer Methode für das Objekt ein "InvalidObjectPath"-Fehler angezeigt wird, müssen Sie das Objekt der nachverfolgten Objektsammlung hinzufügen, wenn das Objekt zum ersten Mal erstellt wurde. Wenn dieses Objekt Teil einer Sammlung ist, sollten Sie auch die übergeordnete Sammlung nachverfolgen.
untrack()	Gibt den diesem Objekt zugewiesenen Arbeitsspeicher frei, wenn das Objekt zuvor nachverfolgt wurde. Dieser Aufruf ist die Kurzform für context.trackedObjects.remove(thisObject). Viele nachverfolgte Objekte verlangsamen die Ausführung der Hostanwendung, also achten Sie darauf, alle hinzugefügten Objekte nach abgeschlossener Verwendung freizugeben. Sie müssen einen Aufruf durchführen `context.sync()` , bevor die Speicherfreigabe wirksam wird.
updateAttribute(xpath, namespaceMappings, name, value)	Updates den Wert eines Attributs mit dem angegebenen Namen des durch XPath identifizierten Elements.
updateElement(xpath, xml, namespaceMappings)	Updates den XML-Code des durch xpath identifizierten Elements.

builtIn

Ruft ab, ob der CustomXmlPart integriert ist.

readonly builtIn: boolean;

Eigenschaftswert

boolean

Hinweise

API-Satz: WordApiDesktop 1.3

context

Der dem Objekt zugeordnete Anforderungskontext. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden.

context: RequestContext;

Eigenschaftswert

Word.RequestContext

documentElement

Ruft das Stammelement eines gebundenen Datenbereichs im Dokument ab. Wenn der Bereich leer ist, wird die Eigenschaft zurückgegeben Nothing.

readonly documentElement: Word.CustomXmlNode;

Eigenschaftswert

Word.CustomXmlNode

Hinweise

API-Satz: WordApiDesktop 1.3

errors

Hinweis

Diese API wird als Vorschau für Entwickler bereitgestellt. Je nachdem, welches Feedback wir dazu erhalten, werden möglicherweise Änderungen vorgenommen. Verwenden Sie diese API nicht in einer Produktionsumgebung.

Ruft ein CustomXmlValidationErrorCollection Objekt ab, das Zugriff auf XML-Validierungsfehler ermöglicht.

readonly errors: Word.CustomXmlValidationErrorCollection;

Eigenschaftswert

Word.CustomXmlValidationErrorCollection

Hinweise

API-Satz: WordApi BETA (NUR VORSCHAU)

id

Ruft die ID des benutzerdefinierten XML-Teils ab.

readonly id: string;

Eigenschaftswert

string

Hinweise

API-Satz: WordApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part.yaml

// Adds a custom XML part.
await Word.run(async (context) => {
  const originalXml =
    "<Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
  const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.add(originalXml);
  customXmlPart.load("id");
  const xmlBlob = customXmlPart.getXml();

  await context.sync();

  const readableXml = addLineBreaksToXML(xmlBlob.value);
  console.log("Added custom XML part:", readableXml);

  // Store the XML part's ID in a setting so the ID is available to other functions.
  const settings: Word.SettingCollection = context.document.settings;
  settings.add("ContosoReviewXmlPartId", customXmlPart.id);

  await context.sync();
});

namespaceManager

Ruft den Satz von Namespacepräfixzuordnungen ab, die für das aktuelle CustomXmlPart Objekt verwendet werden.

readonly namespaceManager: Word.CustomXmlPrefixMappingCollection;

Eigenschaftswert

Word.CustomXmlPrefixMappingCollection

Hinweise

API-Satz: WordApiDesktop 1.3

namespaceUri

Ruft den Namespace-URI des benutzerdefinierten XML-Teils ab.

readonly namespaceUri: string;

Eigenschaftswert

string

Hinweise

API-Satz: WordApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml

// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Gets the namespace URI from a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");

  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
    customXmlPart.load("namespaceUri");
    await context.sync();

    const namespaceUri = customXmlPart.namespaceUri;
    console.log(`Namespace URI: ${JSON.stringify(namespaceUri)}`);
  } else {
    console.warn("Didn't find custom XML part.");
  }
});

schemaCollection

Gibt ein CustomXmlSchemaCollection Objekt an, das den Satz von Schemas darstellt, die an einen gebundenen Datenbereich im Dokument angefügt sind.

schemaCollection: Word.CustomXmlSchemaCollection;

Eigenschaftswert

Word.CustomXmlSchemaCollection

Hinweise

API-Satz: WordApiDesktop 1.3

xml

Ruft die XML-Darstellung des aktuellen CustomXmlPart Objekts ab.

readonly xml: string;

Eigenschaftswert

string

Hinweise

API-Satz: WordApiDesktop 1.3

addNode(parent, options)

Fügt der XML-Struktur einen Knoten hinzu.

addNode(parent: Word.CustomXmlNode, options?: Word.CustomXmlAddNodeOptions): OfficeExtension.ClientResult<number>;

Parameter

parent: Word.CustomXmlNode

Der übergeordnete Knoten, dem der neue Knoten hinzugefügt wird.

options: Word.CustomXmlAddNodeOptions

Optional. Die Optionen, die den hinzuzufügenden Knoten definieren.

Gibt zurück

OfficeExtension.ClientResult<number>

Hinweise

API-Satz: WordApiDesktop 1.3

delete()

Löscht die benutzerdefinierte XML-Komponente.

delete(): void;

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part.yaml

// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Deletes a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    let customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
    const xmlBlob = customXmlPart.getXml();
    customXmlPart.delete();
    customXmlPart = context.document.customXmlParts.getItemOrNullObject(xmlPartIDSetting.value);

    await context.sync();

    if (customXmlPart.isNullObject) {
      console.log(`The XML part with the ID ${xmlPartIDSetting.value} has been deleted.`);

      // Delete the associated setting too.
      xmlPartIDSetting.delete();

      await context.sync();
    } else {
      const readableXml = addLineBreaksToXML(xmlBlob.value);
      console.error(`This is strange. The XML part with the id ${xmlPartIDSetting.value} wasn't deleted:`, readableXml);
    }
  } else {
    console.warn("Didn't find custom XML part to delete.");
  }
});

...

// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Deletes a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    let customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
    const xmlBlob = customXmlPart.getXml();
    customXmlPart.delete();
    customXmlPart = context.document.customXmlParts.getItemOrNullObject(xmlPartIDSetting.value);

    await context.sync();

    if (customXmlPart.isNullObject) {
      console.log(`The XML part with the ID ${xmlPartIDSetting.value} has been deleted.`);

      // Delete the associated setting too.
      xmlPartIDSetting.delete();

      await context.sync();
    } else {
      const readableXml = addLineBreaksToXML(xmlBlob.value);
      console.error(
        `This is strange. The XML part with the id ${xmlPartIDSetting.value} wasn't deleted:`,
        readableXml
      );
    }
  } else {
    console.warn("Didn't find custom XML part to delete.");
  }
});

deleteAttribute(xpath, namespaceMappings, name)

Löscht ein Attribut mit dem angegebenen Namen aus dem durch xpath identifizierten Element.

deleteAttribute(xpath: string, namespaceMappings: {
            [key: string]: string;
        }, name: string): void;

Parameter

xpath: string

Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

name: string

Name des Attributs.

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

deleteElement(xpath, namespaceMappings)

Löscht das durch xpath identifizierte Element.

deleteElement(xpath: string, namespaceMappings: {
            [key: string]: string;
        }): void;

Parameter

xpath: string

Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

getXml()

Ruft den vollständigen XML-Inhalt des benutzerdefinierten XML-Teils ab.

getXml(): OfficeExtension.ClientResult<string>;

Gibt zurück

OfficeExtension.ClientResult<string>

Hinweise

API-Satz: WordApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml

// Adds a custom XML part.
// If you want to populate the CustomXml.namespaceUri property, you must include the xmlns attribute.
await Word.run(async (context) => {
  const originalXml =
    "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
  const customXmlPart = context.document.customXmlParts.add(originalXml);
  customXmlPart.load(["id", "namespaceUri"]);
  const xmlBlob = customXmlPart.getXml();

  await context.sync();

  const readableXml = addLineBreaksToXML(xmlBlob.value);
  console.log(`Added custom XML part with namespace URI ${customXmlPart.namespaceUri}:`, readableXml);

  // Store the XML part's ID in a setting so the ID is available to other functions.
  const settings: Word.SettingCollection = context.document.settings;
  settings.add("ContosoReviewXmlPartIdNS", customXmlPart.id);

  await context.sync();
});

...

// Adds a custom XML part.
await Word.run(async (context) => {
  const originalXml =
    "<Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
  const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.add(originalXml);
  customXmlPart.load("id");
  const xmlBlob = customXmlPart.getXml();

  await context.sync();

  const readableXml = addLineBreaksToXML(xmlBlob.value);
  console.log("Added custom XML part:", readableXml);

  // Store the XML part's ID in a setting so the ID is available to other functions.
  const settings: Word.SettingCollection = context.document.settings;
  settings.add("ContosoReviewXmlPartId", customXmlPart.id);

  await context.sync();
});

insertAttribute(xpath, namespaceMappings, name, value)

Fügt ein Attribut mit dem angegebenen Namen und Wert in das durch xpath identifizierte Element ein.

insertAttribute(xpath: string, namespaceMappings: {
            [key: string]: string;
        }, name: string, value: string): void;

Parameter

xpath: string

Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

name: string

Name des Attributs.

value: string

Wert des Attributs.

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml

// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Inserts an attribute into a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);

    // The insertAttribute method inserts an attribute with the given name and value into the element identified by the xpath parameter.
    customXmlPart.insertAttribute(
      "/contoso:Reviewers",
      { contoso: "http://schemas.contoso.com/review/1.0" },
      "Nation",
      "US"
    );
    const xmlBlob = customXmlPart.getXml();
    await context.sync();

    const readableXml = addLineBreaksToXML(xmlBlob.value);
    console.log("Successfully inserted attribute:", readableXml);
  } else {
    console.warn("Didn't find custom XML part to insert attribute into.");
  }
});

...

// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Inserts an attribute into a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);

    // The insertAttribute method inserts an attribute with the given name and value into the element identified by the xpath parameter.
    customXmlPart.insertAttribute("/Reviewers", { contoso: "http://schemas.contoso.com/review/1.0" }, "Nation", "US");
    const xmlBlob = customXmlPart.getXml();
    await context.sync();

    const readableXml = addLineBreaksToXML(xmlBlob.value);
    console.log("Successfully inserted attribute:", readableXml);
  } else {
    console.warn("Didn't find custom XML part to insert attribute into.");
  }
});

insertElement(xpath, xml, namespaceMappings, index)

Fügt die angegebene XML unter dem durch xpath identifizierten übergeordneten Element am Index der untergeordneten Position ein.

insertElement(xpath: string, xml: string, namespaceMappings: {
            [key: string]: string;
        }, index?: number): void;

Parameter

xpath: string

Absoluter Pfad zum einzelnen übergeordneten Element in XPath-Notation.

xml: string

XML-Inhalt, der eingefügt werden soll.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

index: number

Optional. Nullbasis, an der das neue XML eingefügt werden soll. Wenn er weggelassen wird, wird der XML-Code als letztes untergeordnetes Element dieses übergeordneten Elements angefügt.

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml

// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Inserts an element into a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);

    // The insertElement method inserts the given XML under the parent element identified by the xpath parameter at the provided child position index.
    customXmlPart.insertElement(
      "/contoso:Reviewers",
      "<Lead>Mark</Lead>",
      { contoso: "http://schemas.contoso.com/review/1.0" },
      0
    );
    const xmlBlob = customXmlPart.getXml();
    await context.sync();

    const readableXml = addLineBreaksToXML(xmlBlob.value);
    console.log("Successfully inserted element:", readableXml);
  } else {
    console.warn("Didn't find custom XML part to insert element into.");
  }
});

...

// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Inserts an element into a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);

    // The insertElement method inserts the given XML under the parent element identified by the xpath parameter at the provided child position index.
    customXmlPart.insertElement(
      "/Reviewers",
      "<Lead>Mark</Lead>",
      { contoso: "http://schemas.contoso.com/review/1.0" },
      0
    );
    const xmlBlob = customXmlPart.getXml();
    await context.sync();

    const readableXml = addLineBreaksToXML(xmlBlob.value);
    console.log("Successfully inserted element:", readableXml);
  } else {
    console.warn("Didn't find custom XML part to insert element into.");
  }
});

load(options)

Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.

load(options?: Word.Interfaces.CustomXmlPartLoadOptions): Word.CustomXmlPart;

Parameter

options: Word.Interfaces.CustomXmlPartLoadOptions

Stellt Optionen für die zu ladenden Eigenschaften des Objekts bereit.

Gibt zurück

Word.CustomXmlPart

load(propertyNames)

Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.

load(propertyNames?: string | string[]): Word.CustomXmlPart;

Parameter

propertyNames: string | string[]

Eine durch Trennzeichen getrennte Zeichenfolge oder ein Array von Zeichenfolgen, die die zu ladenden Eigenschaften angeben.

Gibt zurück

Word.CustomXmlPart

load(propertyNamesAndPaths)

Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.CustomXmlPart;

Parameter

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select ist eine durch Kommas getrennte Zeichenfolge, die die zu ladenden Eigenschaften angibt, und propertyNamesAndPaths.expand eine durch Kommas getrennte Zeichenfolge, die die zu ladenden Navigationseigenschaften angibt.

Gibt zurück

Word.CustomXmlPart

loadXml(xml)

Füllt das CustomXmlPart Objekt aus einer XML-Zeichenfolge.

loadXml(xml: string): OfficeExtension.ClientResult<boolean>;

Parameter

xml: string

Die zu ladende XML-Zeichenfolge.

Gibt zurück

OfficeExtension.ClientResult<boolean>

Hinweise

API-Satz: WordApiDesktop 1.3

query(xpath, namespaceMappings)

Fragt den XML-Inhalt des benutzerdefinierten XML-Teils ab.

query(xpath: string, namespaceMappings: {
            [key: string]: string;
        }): OfficeExtension.ClientResult<string[]>;

Parameter

xpath: string

Eine XPath-Abfrage.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

Gibt zurück

OfficeExtension.ClientResult<string[]>

Ein Array, in dem jedes Element einen Eintrag darstellt, mit dem die XPath-Abfrage übereinstimmt.

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml

// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Queries a custom XML part for elements matching the search terms.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");

  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
    const xpathToQueryFor = "/contoso:Reviewers";
    const clientResult = customXmlPart.query(xpathToQueryFor, {
      contoso: "http://schemas.contoso.com/review/1.0"
    });

    await context.sync();

    console.log(`Queried custom XML part for ${xpathToQueryFor} and found ${clientResult.value.length} matches:`);
    for (let i = 0; i < clientResult.value.length; i++) {
      console.log(clientResult.value[i]);
    }
  } else {
    console.warn("Didn't find custom XML part to query.");
  }
});

...

// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Queries a custom XML part for elements matching the search terms.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");

  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
    const xpathToQueryFor = "/Reviewers/Reviewer";
    const clientResult = customXmlPart.query(xpathToQueryFor, {
      contoso: "http://schemas.contoso.com/review/1.0"
    });

    await context.sync();

    console.log(`Queried custom XML part for ${xpathToQueryFor} and found ${clientResult.value.length} matches:`);
    for (let i = 0; i < clientResult.value.length; i++) {
      console.log(clientResult.value[i]);
    }
  } else {
    console.warn("Didn't find custom XML part to query.");
  }
});

selectNodes(xPath)

Wählt eine Auflistung von Knoten aus einer benutzerdefinierten XML-Komponente aus.

selectNodes(xPath: string): Word.CustomXmlNodeCollection;

Parameter

xPath: string

Der auszuwertende XPath-Ausdruck.

Gibt zurück

Word.CustomXmlNodeCollection

Hinweise

API-Satz: WordApiDesktop 1.3

selectSingleNode(xPath)

Wählt einen einzelnen Knoten in einer benutzerdefinierten XML-Komponente aus, der einem XPath-Ausdruck entspricht.

selectSingleNode(xPath: string): Word.CustomXmlNode;

Parameter

xPath: string

Der auszuwertende XPath-Ausdruck.

Gibt zurück

Word.CustomXmlNode

Hinweise

API-Satz: WordApiDesktop 1.3

set(properties, options)

Legt mehrere Eigenschaften eines Objekts gleichzeitig fest. Sie können entweder ein einfaches Objekt mit den entsprechenden Eigenschaften oder ein anderes API-Objekt desselben Typs übergeben.

set(properties: Interfaces.CustomXmlPartUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameter

properties: Word.Interfaces.CustomXmlPartUpdateData

Ein JavaScript-Objekt mit Eigenschaften, die isomorph zu den Eigenschaften des Objekts strukturiert sind, für das die Methode aufgerufen wird.

options: OfficeExtension.UpdateOptions

Bietet eine Option zum Unterdrücken von Fehlern, wenn das properties-Objekt versucht, schreibgeschützte Eigenschaften festzulegen.

Gibt zurück

void

set(properties)

Legt mehrere Eigenschaften für das Objekt gleichzeitig fest, basierend auf einem vorhandenen geladenen Objekt.

set(properties: Word.CustomXmlPart): void;

Parameter

properties: Word.CustomXmlPart

Gibt zurück

void

setXml(xml)

Legt den vollständigen XML-Inhalt des benutzerdefinierten XML-Teils fest.

setXml(xml: string): void;

Parameter

xml: string

XML-Inhalt, der festgelegt werden soll.

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml

// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>

// Replaces a custom XML part.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  const xmlPartIDSetting: Word.Setting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const customXmlPart: Word.CustomXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
    const originalXmlBlob = customXmlPart.getXml();
    await context.sync();

    let readableXml = addLineBreaksToXML(originalXmlBlob.value);
    console.log("Original custom XML part:", readableXml);

    // The setXml method replaces the entire XML part.
    customXmlPart.setXml(
      "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>John</Reviewer><Reviewer>Hitomi</Reviewer></Reviewers>"
    );
    const updatedXmlBlob = customXmlPart.getXml();
    await context.sync();

    readableXml = addLineBreaksToXML(updatedXmlBlob.value);
    console.log("Replaced custom XML part:", readableXml);
  } else {
    console.warn("Didn't find custom XML part to replace.");
  }
});

toJSON()

Überschreibt die JavaScript-Methode toJSON() , um eine nützlichere Ausgabe bereitzustellen, wenn ein API-Objekt an JSON.stringify()übergeben wird. (JSON.stringifyruft wiederum die toJSON Methode des Objekts auf, das an sie übergeben wird.) Während das ursprüngliche Word.CustomXmlPart Objekt ein API-Objekt ist, gibt die toJSON Methode ein einfaches JavaScript-Objekt (als Word.Interfaces.CustomXmlPartData) zurück, das flache Kopien aller geladenen untergeordneten Eigenschaften des ursprünglichen Objekts enthält.

toJSON(): Word.Interfaces.CustomXmlPartData;

Gibt zurück

Word.Interfaces.CustomXmlPartData

track()

Nachverfolgung des Objekts zwecks automatischer Anpassung auf der Grundlage der umgebenden Änderungen im Dokument. Dieser Aufruf ist eine Kurzform für context.trackedObjects.add(thisObject). Wenn Sie dieses Objekt aufrufübergreifend .sync und außerhalb der sequenziellen Ausführung eines ".run"-Batches verwenden und beim Festlegen einer Eigenschaft oder beim Aufrufen einer Methode für das Objekt ein "InvalidObjectPath"-Fehler angezeigt wird, müssen Sie das Objekt der nachverfolgten Objektsammlung hinzufügen, wenn das Objekt zum ersten Mal erstellt wurde. Wenn dieses Objekt Teil einer Sammlung ist, sollten Sie auch die übergeordnete Sammlung nachverfolgen.

track(): Word.CustomXmlPart;

Gibt zurück

Word.CustomXmlPart

untrack()

Gibt den diesem Objekt zugewiesenen Arbeitsspeicher frei, wenn das Objekt zuvor nachverfolgt wurde. Dieser Aufruf ist die Kurzform für context.trackedObjects.remove(thisObject). Viele nachverfolgte Objekte verlangsamen die Ausführung der Hostanwendung, also achten Sie darauf, alle hinzugefügten Objekte nach abgeschlossener Verwendung freizugeben. Sie müssen einen Aufruf durchführen context.sync() , bevor die Speicherfreigabe wirksam wird.

untrack(): Word.CustomXmlPart;

Gibt zurück

Word.CustomXmlPart

updateAttribute(xpath, namespaceMappings, name, value)

Updates den Wert eines Attributs mit dem angegebenen Namen des durch XPath identifizierten Elements.

updateAttribute(xpath: string, namespaceMappings: {
            [key: string]: string;
        }, name: string, value: string): void;

Parameter

xpath: string

Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

name: string

Name des Attributs.

value: string

Neuer Wert des Attributs

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

updateElement(xpath, xml, namespaceMappings)

Updates den XML-Code des durch xpath identifizierten Elements.

updateElement(xpath: string, xml: string, namespaceMappings: {
            [key: string]: string;
        }): void;

Parameter

xpath: string

Absoluter Pfad zum einzelnen Element in XPath-Notation.

xml: string

Neuer XML-Inhalt, der gespeichert werden soll.

namespaceMappings: { [key: string]: string; }

Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Die Eigenschaftsnamen (z. B. "greg") können eine beliebige Zeichenfolge sein, die keine reservierten XPath-Zeichen verwendet, wie z. B. den Schrägstrich "/".

Gibt zurück

void

Hinweise

API-Satz: WordApi 1.4

Wenn ein Element in der Struktur über ein xmlns-Attribut verfügt (dessen Wert normalerweise, aber nicht immer, ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur ist wie folgt:

<Day>
  <Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
    <Week>something</Week>
  </Month>
</Day>

Der Xpath <Week> muss /Day/greg:Month/Week sein, wobei greg ein Alias ist, der "http://calendartypes.org/xsds/GregorianCalendar" im namespaceMappings-Parameter zugeordnet ist.

Hinweise

Verwendet von

Beispiele

Eigenschaften

Methoden

Details zur Eigenschaft

builtIn

Eigenschaftswert

Hinweise

context

Eigenschaftswert

documentElement

Eigenschaftswert

Hinweise

errors

Eigenschaftswert

Hinweise

id

Eigenschaftswert

Hinweise

Beispiele

namespaceManager

Eigenschaftswert

Hinweise

namespaceUri

Eigenschaftswert

Hinweise

Beispiele

schemaCollection

Eigenschaftswert

Hinweise

xml

Eigenschaftswert

Hinweise

Details zur Methode

addNode(parent, options)

Parameter

Gibt zurück

Hinweise

delete()

Gibt zurück

Hinweise

Beispiele

deleteAttribute(xpath, namespaceMappings, name)

Parameter

Gibt zurück

Hinweise

deleteElement(xpath, namespaceMappings)

Parameter

Gibt zurück

Hinweise

getXml()

Gibt zurück

Hinweise

Beispiele

insertAttribute(xpath, namespaceMappings, name, value)

Parameter

Gibt zurück

Hinweise

Beispiele

insertElement(xpath, xml, namespaceMappings, index)

Parameter

Gibt zurück

Hinweise

Beispiele

load(options)

Parameter

Gibt zurück

load(propertyNames)

Parameter

Gibt zurück

load(propertyNamesAndPaths)

Parameter

Gibt zurück

loadXml(xml)

Parameter

Gibt zurück

Hinweise

query(xpath, namespaceMappings)