Word.CustomXmlPart class

パッケージ:

word

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

Extends

OfficeExtension.ClientObject

注釈

API セット: WordApi 1.4

使用元

• Word.CustomXmlNode: ownerPart
• Word.CustomXmlPartCollection: add, getItem, getItemOrNullObject, items
• Word.CustomXmlPartScopedCollection: getItem、getItemOrNullObject、getOnlyItem、getOnlyItemOrNullObject、items
• Word.ドキュメント: selectUnlinkedControls
• Word.XmlMapping: customXmlPart
• Word.XmlSetMappingOptions: ソース

例

// 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)	指定された XML を、子位置インデックスの xpath で識別される親要素の下に挿入します。
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)	Updates 属性の値を、xpath によって識別される要素の名前にします。
updateElement(xpath, xml, namespaceMappings)	Updates xpath によって識別される要素の XML を更新します。

プロパティの詳細

builtIn

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

readonly builtIn: boolean;

プロパティ値

boolean

注釈

API セット: WordApiDesktop 1.3

context

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

context: RequestContext;

プロパティ値

Word.RequestContext

documentElement

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

readonly documentElement: Word.CustomXmlNode;

プロパティ値

Word.CustomXmlNode

注釈

API セット: WordApiDesktop 1.3

errors

注意

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

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

readonly errors: Word.CustomXmlValidationErrorCollection;

プロパティ値

Word.CustomXmlValidationErrorCollection

注釈

API セット: WordApi ベータ版 (プレビューのみ)

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 セット: 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 セット: WordApiDesktop 1.3

xml

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

readonly xml: string;

プロパティ値

string

注釈

API セット: 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 セット: 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 表記の 1 つの要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

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

name

string

属性の名前。

返品

void

注釈

API セット: WordApi 1.4

ツリー内の要素に xmlns 属性がある場合 (その値は通常、URI になりますが、常に 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 表記の 1 つの要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

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

返品

void

注釈

API セット: WordApi 1.4

ツリー内の要素に xmlns 属性がある場合 (その値は通常、URI になりますが、常に 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 表記の 1 つの要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

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

name

string

属性の名前。

value

string

属性の値。

返品

void

注釈

API セット: WordApi 1.4

ツリー内の要素に xmlns 属性がある場合 (その値は通常、URI になりますが、常に 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)

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

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 になりますが、常に 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 セット: 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 になりますが、常に 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 セット: WordApiDesktop 1.3

selectSingleNode(xPath)

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

selectSingleNode(xPath: string): Word.CustomXmlNode;

パラメーター

xPath

string

評価する XPath 式。

返品

Word.CustomXmlNode

注釈

API セット: WordApiDesktop 1.3

set(properties, options)

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

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

パラメーター

properties

Word.Interfaces.CustomXmlPartUpdateData

メソッドが呼び出されたオブジェクトのプロパティと同型構造のプロパティを持つ JavaScript オブジェクト。

options

OfficeExtension.UpdateOptions

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

返品

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)

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

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

パラメーター

xpath

string

XPath 表記の 1 つの要素への絶対パス。

namespaceMappings

{ [key: string]: string; }

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

name

string

属性の名前。

value

string

属性の新しい値。

返品

void

注釈

API セット: WordApi 1.4

ツリー内の要素に xmlns 属性がある場合 (その値は通常、URI になりますが、常に 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)

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

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

パラメーター

xpath

string

XPath 表記の 1 つの要素への絶対パス。

xml

string

保存する新しい XML コンテンツ。

namespaceMappings

{ [key: string]: string; }

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

返品

void

注釈

API セット: WordApi 1.4

ツリー内の要素に xmlns 属性がある場合 (その値は通常、URI になりますが、常に 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" にマップされるエイリアスです。