Word.CustomXmlPart class

  • Referenz
Paket:
word

Stellt eine benutzerdefinierte XML-Komponente dar.

Extends
OfficeExtension.ClientObject

Hinweise

[ API-Satz: WordApi 1.4 ]

Eigenschaften

context

Der Anforderungskontext, der dem -Objekt zugeordnet ist. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden.
id

Ruft die ID des benutzerdefinierten XML-Teils ab.
namespaceUri

Ruft den Namespace-URI der benutzerdefinierten XML-Komponente ab.

Methoden

delete()

Löscht die benutzerdefinierte XML-Komponente.
deleteAttribute(xpath, namespaceMappings, name)

Löscht ein Attribut mit dem angegebenen Namen aus dem von xpath identifizierten Element.
deleteElement(xpath, namespaceMappings)

Löscht das von xpath identifizierte Element.
getXml()

Ruft den vollständigen XML-Inhalt der benutzerdefinierten XML-Komponente ab.
insertAttribute(xpath, namespaceMappings, name, value)

Fügt ein Attribut mit dem angegebenen Namen und Wert in das von xpath identifizierte Element ein.
insertElement(xpath, xml, namespaceMappings, index)

Fügt den angegebenen XML-Code unter dem übergeordneten Element ein, das von xpath am untergeordneten Positionsindex identifiziert wird.
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.
query(xpath, namespaceMappings)

Fragt den XML-Inhalt des benutzerdefinierten XML-Teils ab.
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.stringifyruft wiederum die toJSON -Methode des Objekts auf, das an das Objekt übergeben wird.) Die ursprüngliche Word. Das CustomXmlPart-Objekt ist ein API-Objekt. Die toJSON Methode gibt ein einfaches JavaScript-Objekt (typisiert als Word.Interfaces.CustomXmlPartData) zurück, das flache Kopien aller geladenen untergeordneten Eigenschaften aus dem ursprünglichen Objekt 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 über .sync Aufrufe hinweg 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 den Fehler "InvalidObjectPath" erhalten, müssen Sie das Objekt der nachverfolgten Objektauflistung hinzufügen, als das Objekt zum ersten Mal erstellt wurde. Wenn dieses Objekt Teil einer Auflistung ist, sollten Sie auch die übergeordnete Auflistung 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 aufrufen 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.

Details zur Eigenschaft

context

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

context: RequestContext;

Eigenschaftswert

Word.RequestContext

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 = 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:");
  console.log(readableXml);

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

  await context.sync();
});

namespaceUri

Ruft den Namespace-URI der benutzerdefinierten XML-Komponente 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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");

  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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");
  }
});

Details zur Methode

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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    let 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);
      const strangeMessage = `This is strange. The XML part with the id ${xmlPartIDSetting.value} wasn't deleted:\n${readableXml}`;
      console.error(strangeMessage);
    }
  } 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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    let 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);
      const strangeMessage = `This is strange. The XML part with the id ${xmlPartIDSetting.value} wasn't deleted:\n${readableXml}`;
      console.error(strangeMessage);
    }
  } 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 von xpath identifizierten Element.

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

Parameter

xpath

string

Erforderlich. Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der Schrägstrich "/".

name

string

Erforderlich. 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 in der Regel aber nicht immer ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur sieht wie folgt aus:

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

Der xpath muss <Week> /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 von xpath identifizierte Element.

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

Parameter

xpath

string

Erforderlich. Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der 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 in der Regel aber nicht immer ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur sieht wie folgt aus:

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

Der xpath muss <Week> /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 der benutzerdefinierten XML-Komponente 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}:`);
  console.log(readableXml);

  // Store the XML part's ID in a setting so the ID is available to other functions.
  const settings = 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 = 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:");
  console.log(readableXml);

  // Store the XML part's ID in a setting so the ID is available to other functions.
  const settings = 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 von xpath identifizierte Element ein.

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

Parameter

xpath

string

Erforderlich. Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der Schrägstrich "/".

name

string

Erforderlich. Name des Attributs.

value

string

Erforderlich. 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 in der Regel aber nicht immer ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur sieht wie folgt aus:

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

Der xpath muss <Week> /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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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:");
    console.log(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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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:");
    console.log(readableXml);
  } else {
    console.warn("Didn't find custom XML part to insert attribute into");
  }
});

insertElement(xpath, xml, namespaceMappings, index)

Fügt den angegebenen XML-Code unter dem übergeordneten Element ein, das von xpath am untergeordneten Positionsindex identifiziert wird.

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

Parameter

xpath

string

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

xml

string

Erforderlich. Xml-Inhalt, der eingefügt werden soll.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der Schrägstrich "/".

index

number

Optional. Nullbasierte Position, an der der neue XML-Code eingefügt werden soll. Wenn nicht angegeben, 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 in der Regel aber nicht immer ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur sieht wie folgt aus:

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

Der xpath muss <Week> /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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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:");
    console.log(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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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:");
    console.log(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 dafür bereit, welche Eigenschaften des -Objekts geladen werden sollen.

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 Trennzeichen getrennte Zeichenfolge, die die zu ladenden Eigenschaften angibt, und propertyNamesAndPaths.expand eine durch Trennzeichen getrennte Zeichenfolge, die die zu ladenden Navigationseigenschaften angibt.

Gibt zurück

Word.CustomXmlPart

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

Erforderlich. Eine XPath-Abfrage.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der Schrägstrich "/".

Gibt zurück

OfficeExtension.ClientResult<string[]>

Ein Array, bei dem jedes Element einen Eintrag darstellt, der von der XPath-Abfrage abgeglichen wird.

Hinweise

[ API-Satz: WordApi 1.4 ]

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

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

Der xpath muss <Week> /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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");

  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");

  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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");
  }
});

setXml(xml)

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

setXml(xml: string): void;

Parameter

xml

string

Erforderlich. Festzulegenden XML-Inhalt.

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 = context.document.settings;
  const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
  await context.sync();

  if (xmlPartIDSetting.value) {
    const 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:");
    console.log(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:");
    console.log(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 das Objekt übergeben wird.) Die ursprüngliche Word. Das CustomXmlPart-Objekt ist ein API-Objekt. Die toJSON Methode gibt ein einfaches JavaScript-Objekt (typisiert als Word.Interfaces.CustomXmlPartData) zurück, das flache Kopien aller geladenen untergeordneten Eigenschaften aus dem ursprünglichen Objekt 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 über .sync Aufrufe hinweg 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 den Fehler "InvalidObjectPath" erhalten, müssen Sie das Objekt der nachverfolgten Objektauflistung hinzufügen, als das Objekt zum ersten Mal erstellt wurde. Wenn dieses Objekt Teil einer Auflistung ist, sollten Sie auch die übergeordnete Auflistung 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 aufrufen 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

Erforderlich. Absoluter Pfad zum einzelnen Element in XPath-Notation.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der Schrägstrich "/".

name

string

Erforderlich. Name des Attributs.

value

string

Erforderlich. 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 in der Regel aber nicht immer ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur sieht wie folgt aus:

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

Der xpath muss <Week> /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

Erforderlich. Absoluter Pfad zum einzelnen Element in XPath-Notation.

xml

string

Erforderlich. Neuer xml-Inhalt, der gespeichert werden soll.

namespaceMappings

{ [key: string]: string; }

Erforderlich. Ein Objekt, dessen Eigenschaftswerte Namespacenamen sind und dessen Eigenschaftsnamen Aliase für die entsprechenden Namespaces sind. Beispiel: {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. Bei den Eigenschaftennamen (z. B. "greg") kann es sich um eine beliebige Zeichenfolge handeln, die keine reservierten XPath-Zeichen verwendet, z. B. der 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 in der Regel aber nicht immer ein URI ist), muss ein Alias für diesen Attributwert dem Elementnamen im xpath-Parameter vorangestellt werden. Angenommen, die Struktur sieht wie folgt aus:

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

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