Word.CustomXmlPart class

パッケージ:

word

カスタム XML パーツを表します。

Extends

OfficeExtension.ClientObject

注釈

[ API セット: WordApi 1.4 ]

例

// 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();
});

プロパティ

builtIn	CustomXmlPartが組み込まれているかどうかを示す値を取得します。
context	オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
documentElement	ドキュメント内のデータのバインドされた領域のルート要素を取得します。 リージョンが空の場合、プロパティは Nothingを返します。
errors	XML 検証エラーへのアクセスを提供する CustomXmlValidationErrorCollection オブジェクトを取得します。
id	カスタム XML パーツの ID を取得します。
namespaceManager	現在の CustomXmlPart オブジェクトに対して使用される名前空間プレフィックス マッピングのセットを取得します。
namespaceUri	カスタム XML パーツの名前空間 URI を取得します。
schemaCollection	ドキュメント内のデータのバインドされた領域にアタッチされているスキーマのセットを表す CustomXmlSchemaCollection オブジェクトを指定します。
xml	現在の CustomXmlPart オブジェクトの XML 表現を取得します。

メソッド

addNode(parent, options)	XML ツリーにノードを追加します。
delete()	カスタム XML パーツを削除します。
deleteAttribute(xpath, namespaceMappings, name)	xpath によって識別される要素から、指定された名前の属性を削除します。
deleteElement(xpath, namespaceMappings)	xpath によって識別される要素を削除します。
getXml()	カスタム XML パーツの完全な XML コンテンツを取得します。
insertAttribute(xpath, namespaceMappings, name, value)	指定された名前と値を持つ属性を xpath によって識別される要素に挿入します。
insertElement(xpath, xml, namespaceMappings, index)	子位置インデックスで xpath によって識別される親要素の下に、指定された XML を挿入します。
load(options)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNames)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNamesAndPaths)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
loadXml(xml)	XML 文字列から CustomXmlPart オブジェクトを設定します。
query(xpath, namespaceMappings)	カスタム XML パーツの XML コンテンツを照会します。
selectNodes(xPath)	カスタム XML 部分からノードのコレクションを選択します。
selectSingleNode(xPath)	カスタム XML 部分から XPath 式に一致するシングル ノードを選択します。
set(properties, options)	オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。
set(properties)	既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。
setXml(xml)	カスタム XML パーツの完全な XML コンテンツを設定します。
toJSON()	API オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (JSON.stringify、それに渡されるオブジェクトの toJSON メソッドを呼び出します)。元の Word.CustomXmlPart オブジェクトは API オブジェクトですが、 toJSON メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( Word.Interfaces.CustomXmlPartData として型指定) を返します。
track()	ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。 このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。
untrack()	前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 context.sync() を呼び出す必要があります。
updateAttribute(xpath, namespaceMappings, name, value)	xpath によって識別される要素の指定された名前を持つ属性の値をUpdatesします。
updateElement(xpath, xml, namespaceMappings)	xpath によって識別される要素の XML をUpdatesします。

プロパティの詳細

builtIn

CustomXmlPartが組み込まれているかどうかを示す値を取得します。

readonly builtIn: boolean;

プロパティ値

boolean

注釈

[ API set: WordApiDesktop 1.3 ]

context

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。

context: RequestContext;

プロパティ値

Word.RequestContext

documentElement

ドキュメント内のデータのバインドされた領域のルート要素を取得します。 リージョンが空の場合、プロパティは Nothingを返します。

readonly documentElement: Word.CustomXmlNode;

プロパティ値

Word.CustomXmlNode

注釈

[ API set: WordApiDesktop 1.3 ]

errors

注意

この API は開発者向けにプレビューとして提供されており、寄せられたフィードバックにもとづいて変更される場合があります。 この API は運用環境で使用しないでください。

XML 検証エラーへのアクセスを提供する CustomXmlValidationErrorCollection オブジェクトを取得します。

readonly errors: Word.CustomXmlValidationErrorCollection;

プロパティ値

Word.CustomXmlValidationErrorCollection

注釈

[ API セット: WordApi BETA (プレビューのみ) ]

id

カスタム XML パーツの ID を取得します。

readonly id: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.4 ]

例

// 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

現在の CustomXmlPart オブジェクトに対して使用される名前空間プレフィックス マッピングのセットを取得します。

readonly namespaceManager: Word.CustomXmlPrefixMappingCollection;

プロパティ値

Word.CustomXmlPrefixMappingCollection

注釈

[ API set: WordApiDesktop 1.3 ]

namespaceUri

カスタム XML パーツの名前空間 URI を取得します。

readonly namespaceUri: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.4 ]

例

// 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

ドキュメント内のデータのバインドされた領域にアタッチされているスキーマのセットを表す CustomXmlSchemaCollection オブジェクトを指定します。

schemaCollection: Word.CustomXmlSchemaCollection;

プロパティ値

Word.CustomXmlSchemaCollection

注釈

[ API set: WordApiDesktop 1.3 ]

xml

現在の CustomXmlPart オブジェクトの XML 表現を取得します。

readonly xml: string;

プロパティ値

string

注釈

[ API set: WordApiDesktop 1.3 ]

メソッドの詳細

addNode(parent, options)

XML ツリーにノードを追加します。

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

パラメーター

parent

Word.CustomXmlNode

新しいノードが追加される親ノード。

options

Word.CustomXmlAddNodeOptions

省略可能。 追加するノードを定義するオプション。

戻り値

OfficeExtension.ClientResult<number>

注釈

[ API set: WordApiDesktop 1.3 ]

delete()

カスタム XML パーツを削除します。

delete(): void;

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

例

// 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)

xpath によって識別される要素から、指定された名前の属性を削除します。

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

パラメーター

xpath

string

XPath 表記の単一要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

name

string

属性の名前。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。

deleteElement(xpath, namespaceMappings)

xpath によって識別される要素を削除します。

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

パラメーター

xpath

string

XPath 表記の単一要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。

getXml()

カスタム XML パーツの完全な XML コンテンツを取得します。

getXml(): OfficeExtension.ClientResult<string>;

戻り値

OfficeExtension.ClientResult<string>

注釈

[ API セット: WordApi 1.4 ]

例

// 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)

指定された名前と値を持つ属性を xpath によって識別される要素に挿入します。

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

パラメーター

xpath

string

XPath 表記の単一要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

name

string

属性の名前。

value

string

属性の値。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。

例

// 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)

子位置インデックスで xpath によって識別される親要素の下に、指定された XML を挿入します。

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

パラメーター

xpath

string

XPath 表記の単一の親要素への絶対パス。

xml

string

挿入する XML コンテンツ。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

index

number

省略可能。 挿入する新しい XML の位置を 0 から始めます。 省略すると、この親の最後の子として XML が追加されます。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。

例

// 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)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

options

Word.Interfaces.CustomXmlPartLoadOptions

読み込むオブジェクトのプロパティのオプションを提供します。

戻り値

Word.CustomXmlPart

load(propertyNames)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

propertyNames

string | string[]

読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。

戻り値

Word.CustomXmlPart

load(propertyNamesAndPaths)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

propertyNamesAndPaths

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

propertyNamesAndPaths.select は読み込むプロパティを指定するコンマ区切りの文字列で、 propertyNamesAndPaths.expand は読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。

戻り値

Word.CustomXmlPart

loadXml(xml)

XML 文字列から CustomXmlPart オブジェクトを設定します。

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

パラメーター

xml

string

読み込む XML 文字列。

戻り値

OfficeExtension.ClientResult<boolean>

注釈

[ API set: WordApiDesktop 1.3 ]

query(xpath, namespaceMappings)

カスタム XML パーツの XML コンテンツを照会します。

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

パラメーター

xpath

string

XPath クエリ。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

戻り値

OfficeExtension.ClientResult<string[]>

各項目が XPath クエリと一致するエントリを表す配列。

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。

例

// 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)

カスタム XML 部分からノードのコレクションを選択します。

selectNodes(xPath: string): Word.CustomXmlNodeCollection;

パラメーター

xPath

string

評価する XPath 式。

戻り値

Word.CustomXmlNodeCollection

注釈

[ API set: WordApiDesktop 1.3 ]

selectSingleNode(xPath)

カスタム XML 部分から XPath 式に一致するシングル ノードを選択します。

selectSingleNode(xPath: string): Word.CustomXmlNode;

パラメーター

xPath

string

評価する XPath 式。

戻り値

Word.CustomXmlNode

注釈

[ API set: WordApiDesktop 1.3 ]

set(properties, options)

オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。

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

パラメーター

properties

Word.Interfaces.CustomXmlPartUpdateData

メソッドが呼び出されるオブジェクトのプロパティに等形的に構造化されたプロパティを持つ JavaScript オブジェクト。

options

OfficeExtension.UpdateOptions

properties オブジェクトが読み取り専用プロパティを設定しようとした場合にエラーを抑制するオプションを提供します。

戻り値

void

set(properties)

既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。

set(properties: Word.CustomXmlPart): void;

パラメーター

properties

Word.CustomXmlPart

戻り値

void

setXml(xml)

カスタム XML パーツの完全な XML コンテンツを設定します。

setXml(xml: string): void;

パラメーター

xml

string

設定する XML コンテンツ。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

例

// 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()

API オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (JSON.stringify、それに渡されるオブジェクトの toJSON メソッドを呼び出します)。元の Word.CustomXmlPart オブジェクトは API オブジェクトですが、 toJSON メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( Word.Interfaces.CustomXmlPartData として型指定) を返します。

toJSON(): Word.Interfaces.CustomXmlPartData;

戻り値

Word.Interfaces.CustomXmlPartData

track()

ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。 このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。

track(): Word.CustomXmlPart;

戻り値

Word.CustomXmlPart

untrack()

前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 context.sync() を呼び出す必要があります。

untrack(): Word.CustomXmlPart;

戻り値

Word.CustomXmlPart

updateAttribute(xpath, namespaceMappings, name, value)

xpath によって識別される要素の指定された名前を持つ属性の値をUpdatesします。

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

パラメーター

xpath

string

XPath 表記の単一要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

name

string

属性の名前。

value

string

属性の新しい値。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。

updateElement(xpath, xml, namespaceMappings)

xpath によって識別される要素の XML をUpdatesします。

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

パラメーター

xpath

string

XPath 表記の単一要素への絶対パス。

xml

string

格納する新しい XML コンテンツ。

namespaceMappings

{ [key: string]: string; }

プロパティ値が名前空間名であり、そのプロパティ名が対応する名前空間のエイリアスであるオブジェクト。 たとえば、 {greg: "http://calendartypes.org/xsds/GregorianCalendar"}。 プロパティ名 ("greg" など) には、スラッシュ "/" などの予約済み XPath 文字を使用しない任意の文字列を指定できます。

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

ツリー内の要素に xmlns 属性 (通常は値は URI ではなく) がある場合、その属性値のエイリアスは xpath パラメーターの要素名の前に付ける必要があります。 たとえば、ツリーが次の例であるとします。

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

<Week>への xpath は /Day/greg:Month/Week である必要があります。ここで、greg は namespaceMappings パラメーターの "http://calendartypes.org/xsds/GregorianCalendar" にマップされるエイリアスです。