Word.Field class

表示一个字段。

扩展

注解

API 集:WordApi 1.4

重要提示:要详细了解可以插入哪些字段,请参阅要求集 1.5 中引入的 Word.Range.insertField API。 对字段管理的支持类似于 Word UI 中提供的功能。 但是,Web 上的 Word UI 主要仅支持只读字段, (请参阅 Word 网页版中的字段代码) 。 若要深入了解更完全支持字段的 Word UI 客户端,请参阅“在 Word 中插入、编辑和查看字段”开头的产品列表。

使用方

示例

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

// Gets the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load(["code", "result", "locked", "type", "data", "kind"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    console.log("Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result), "Type of first field: " + field.type, "Is the first field locked? " + field.locked, "Kind of the first field: " + field.kind);
  }
});

属性

code

指定字段的代码指令。

context

与对象关联的请求上下文。 这将加载项的进程连接到 Office 主机应用程序的进程。

data

指定类型字段中 addin 的数据。 如果字段不是一个 addin 类型,它就是 null ,当代码尝试设置它时,它将引发常规异常。

kind

获取字段的种类。

linkFormat

获取表示 LinkFormat 字段链接选项的对象。

locked

指定字段是否已锁定。 true 如果该字段已锁定, false 则为否。

oleFormat

获取表示 OleFormat OLE 特征的对象 (而不是链接字段的) 。

parentBody

获取字段的父实体。

parentContentControl

获取包含该字段的内容控件。 如果没有父内容控件,则引发 ItemNotFound 错误。

parentContentControlOrNullObject

获取包含该字段的内容控件。 如果没有父内容控件,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

parentTable

获取包含字段的表。 如果表中未包含,则引发 ItemNotFound 错误。

parentTableCell

获取包含字段的表单元格。 如果表单元格中未包含错误,则引发 ItemNotFound 错误。

parentTableCellOrNullObject

获取包含字段的表单元格。 如果它未包含在表单元格中,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

parentTableOrNullObject

获取包含字段的表。 如果它未包含在表中,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

result

获取字段的结果数据。

showCodes

指定是否显示指定字段的字段代码。 true 如果显示域代码, false 否则。

type

获取字段的类型。

方法

copyToClipboard()

将字段复制到剪贴板。

cut()

从文档中删除字段并将其置于剪贴板中。

delete()

删除字段。

doClick()

单击该字段。

getNext()

获取下一个字段。 如果此字段是最后一个字段,则引发 ItemNotFound 错误。

getNextOrNullObject()

获取下一个字段。 如果此字段是最后一个字段,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

select(selectionMode)

选择该字段。

select(selectionMode)

选择该字段。

set(properties, options)

同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象,也可以传递另一个相同类型的 API 对象。

set(properties)

基于现有加载的对象,同时在对象上设置多个属性。

toJSON()

覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Word.Field 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Word.Interfaces.FieldData) ,其中包含从原始对象加载的任何子属性的浅层副本。

track()

根据文档中的相应更改来跟踪对象,以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果在调用中 .sync 使用此对象,并且在“.run”批处理的顺序执行之外使用此对象,并且在设置属性或对对象调用方法时收到“InvalidObjectPath”错误,则需要在首次创建对象时将对象添加到跟踪对象集合。 如果此对象是集合的一部分,您还应跟踪父集合。

unlink()

将字段替换为最新结果。

untrack()

释放与此对象关联的内存(如果先前已跟踪过)。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度,因此请在使用完毕后释放所添加的任何对象。 需要在内存释放生效之前调用 context.sync() 。

updateResult()

汇报字段。

updateSource()

将对 INCLUDETEXT 字段 的结果所做的更改保存回源文档。

属性详细信息

code

指定字段的代码指令。

code: string;

属性值

string

注解

API 集:WordApi 1.4

注意:WordApi 1.5 中引入了设置代码的功能。

示例

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

// Gets the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load(["code", "result", "locked", "type", "data", "kind"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    console.log("Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result), "Type of first field: " + field.type, "Is the first field locked? " + field.locked, "Kind of the first field: " + field.kind);
  }
});

context

与对象关联的请求上下文。 这将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

data

指定类型字段中 addin 的数据。 如果字段不是一个 addin 类型,它就是 null ,当代码尝试设置它时,它将引发常规异常。

data: string;

属性值

string

注解

API 集:WordApi 1.5

kind

获取字段的种类。

readonly kind: Word.FieldKind | "None" | "Hot" | "Warm" | "Cold";

属性值

Word.FieldKind | "None" | "Hot" | "Warm" | "Cold"

注解

API 集:WordApi 1.5

示例

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

// Gets the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load(["code", "result", "locked", "type", "data", "kind"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    console.log("Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result), "Type of first field: " + field.type, "Is the first field locked? " + field.locked, "Kind of the first field: " + field.kind);
  }
});

linkFormat

获取表示 LinkFormat 字段链接选项的对象。

readonly linkFormat: Word.LinkFormat;

属性值

注解

API 集:WordApiDesktop 1.4

locked

指定字段是否已锁定。 true 如果该字段已锁定, false 则为否。

locked: boolean;

属性值

boolean

注解

API 集:WordApi 1.5

示例

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

// Gets the first field in the selection and toggles between setting it to locked or unlocked.
await Word.run(async (context) => {
  let field = context.document.getSelection().fields.getFirstOrNullObject();
  field.load(["code", "result", "type", "locked"]);
  await context.sync();

  if (field.isNullObject) {
    console.log("The selection has no fields.");
  } else {
    console.log(`The first field in the selection is currently ${field.locked ? "locked" : "unlocked"}.`);
    field.locked = !field.locked;
    await context.sync();

    console.log(`The first field in the selection is now ${field.locked ? "locked" : "unlocked"}.`);
  }
});

oleFormat

获取表示 OleFormat OLE 特征的对象 (而不是链接字段的) 。

readonly oleFormat: Word.OleFormat;

属性值

注解

API 集:WordApiDesktop 1.4

parentBody

获取字段的父实体。

readonly parentBody: Word.Body;

属性值

注解

API 集:WordApi 1.4

示例

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

// Gets the parent body of the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load("parentBody/text");

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    const parentBody: Word.Body = field.parentBody;
    console.log("Text of first field's parent body: " + JSON.stringify(parentBody.text));
  }
});

parentContentControl

获取包含该字段的内容控件。 如果没有父内容控件,则引发 ItemNotFound 错误。

readonly parentContentControl: Word.ContentControl;

属性值

注解

API 集:WordApi 1.4

parentContentControlOrNullObject

获取包含该字段的内容控件。 如果没有父内容控件,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

readonly parentContentControlOrNullObject: Word.ContentControl;

属性值

注解

API 集:WordApi 1.4

parentTable

获取包含字段的表。 如果表中未包含,则引发 ItemNotFound 错误。

readonly parentTable: Word.Table;

属性值

注解

API 集:WordApi 1.4

parentTableCell

获取包含字段的表单元格。 如果表单元格中未包含错误,则引发 ItemNotFound 错误。

readonly parentTableCell: Word.TableCell;

属性值

注解

API 集:WordApi 1.4

parentTableCellOrNullObject

获取包含字段的表单元格。 如果它未包含在表单元格中,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

readonly parentTableCellOrNullObject: Word.TableCell;

属性值

注解

API 集:WordApi 1.4

parentTableOrNullObject

获取包含字段的表。 如果它未包含在表中,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

readonly parentTableOrNullObject: Word.Table;

属性值

注解

API 集:WordApi 1.4

result

获取字段的结果数据。

readonly result: Word.Range;

属性值

注解

API 集:WordApi 1.4

示例

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

// Gets the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load(["code", "result", "locked", "type", "data", "kind"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    console.log("Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result), "Type of first field: " + field.type, "Is the first field locked? " + field.locked, "Kind of the first field: " + field.kind);
  }
});

showCodes

指定是否显示指定字段的字段代码。 true 如果显示域代码, false 否则。

showCodes: boolean;

属性值

boolean

注解

API 集:WordApiDesktop 1.1

type

获取字段的类型。

readonly type: Word.FieldType | "Addin" | "AddressBlock" | "Advance" | "Ask" | "Author" | "AutoText" | "AutoTextList" | "BarCode" | "Bibliography" | "BidiOutline" | "Citation" | "Comments" | "Compare" | "CreateDate" | "Data" | "Database" | "Date" | "DisplayBarcode" | "DocProperty" | "DocVariable" | "EditTime" | "Embedded" | "EQ" | "Expression" | "FileName" | "FileSize" | "FillIn" | "FormCheckbox" | "FormDropdown" | "FormText" | "GotoButton" | "GreetingLine" | "Hyperlink" | "If" | "Import" | "Include" | "IncludePicture" | "IncludeText" | "Index" | "Info" | "Keywords" | "LastSavedBy" | "Link" | "ListNum" | "MacroButton" | "MergeBarcode" | "MergeField" | "MergeRec" | "MergeSeq" | "Next" | "NextIf" | "NoteRef" | "NumChars" | "NumPages" | "NumWords" | "OCX" | "Page" | "PageRef" | "Print" | "PrintDate" | "Private" | "Quote" | "RD" | "Ref" | "RevNum" | "SaveDate" | "Section" | "SectionPages" | "Seq" | "Set" | "Shape" | "SkipIf" | "StyleRef" | "Subject" | "Subscriber" | "Symbol" | "TA" | "TC" | "Template" | "Time" | "Title" | "TOA" | "TOC" | "UserAddress" | "UserInitials" | "UserName" | "XE" | "Empty" | "Others" | "Undefined";

属性值

Word.FieldType | "Addin" | "AddressBlock" | "Advance" | "Ask" | "Author" | "AutoText" | "AutoTextList" | "BarCode" | "Bibliography" | "BidiOutline" | "Citation" | "Comments" | "Compare" | "CreateDate" | "Data" | "Database" | "Date" | "DisplayBarcode" | "DocProperty" | "DocVariable" | "EditTime" | "Embedded" | "EQ" | "Expression" | "FileName" | "FileSize" | "FillIn" | "FormCheckbox" | "FormDropdown" | "FormText" | "GotoButton" | "GreetingLine" | "Hyperlink" | "If" | "Import" | "Include" | "IncludePicture" | "IncludeText" | "Index" | "Info" | "Keywords" | "LastSavedBy" | "Link" | "ListNum" | "MacroButton" | "MergeBarcode" | "MergeField" | "MergeRec" | "MergeSeq" | "Next" | "NextIf" | "NoteRef" | "NumChars" | "NumPages" | "NumWords" | "OCX" | "Page" | "PageRef" | "Print" | "PrintDate" | "Private" | "Quote" | "RD" | "Ref" | "RevNum" | "SaveDate" | "Section" | "SectionPages" | "Seq" | "Set" | "Shape" | "SkipIf" | "StyleRef" | "Subject" | "Subscriber" | "Symbol" | "TA" | "TC" | "Template" | "Time" | "Title" | "TOA" | "TOC" | "UserAddress" | "UserInitials" | "UserName" | "XE" | "Empty" | "Others" | "Undefined"

注解

API 集:WordApi 1.5

示例

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

// Gets the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load(["code", "result", "locked", "type", "data", "kind"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    console.log("Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result), "Type of first field: " + field.type, "Is the first field locked? " + field.locked, "Kind of the first field: " + field.kind);
  }
});

方法详细信息

copyToClipboard()

将字段复制到剪贴板。

copyToClipboard(): void;

返回

void

注解

API 集:WordApiDesktop 1.4

cut()

从文档中删除字段并将其置于剪贴板中。

cut(): void;

返回

void

注解

API 集:WordApiDesktop 1.4

delete()

删除字段。

delete(): void;

返回

void

注解

API 集:WordApi 1.5

示例

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

// Deletes the first field in the document.
await Word.run(async (context) => {
  const field: Word.Field = context.document.body.fields.getFirstOrNullObject();
  field.load();

  await context.sync();

  if (field.isNullObject) {
    console.log("This document has no fields.");
  } else {
    field.delete();
    await context.sync();

    console.log("The first field in the document was deleted.");
  }
});

doClick()

单击该字段。

doClick(): void;

返回

void

注解

API 集:WordApiDesktop 1.4

getNext()

获取下一个字段。 如果此字段是最后一个字段,则引发 ItemNotFound 错误。

getNext(): Word.Field;

返回

注解

API 集:WordApi 1.4

getNextOrNullObject()

获取下一个字段。 如果此字段是最后一个字段,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。

getNextOrNullObject(): Word.Field;

返回

注解

API 集:WordApi 1.4

load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(options?: Word.Interfaces.FieldLoadOptions): Word.Field;

参数

options
Word.Interfaces.FieldLoadOptions

为要加载的对象属性提供选项。

返回

load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

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

参数

propertyNames

string | string[]

指定要加载的属性的逗号分隔的字符串或字符串数组。

返回

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

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

参数

propertyNamesAndPaths

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

propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串,以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。

返回

select(selectionMode)

选择该字段。

select(selectionMode?: Word.SelectionMode): void;

参数

selectionMode
Word.SelectionMode

可选。 选择模式必须为 select、 、start 或 end。 select 为默认值。

返回

void

注解

API 集:WordApi 1.5

示例

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

// Gets and updates the first field in the selection.
await Word.run(async (context) => {
  let field = context.document.getSelection().fields.getFirstOrNullObject();
  field.load(["code", "result", "type", "locked"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("No field in selection.");
  } else {
    console.log("Before updating:", "Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result));

    field.updateResult();
    field.select();
    await context.sync();

    field.load(["code", "result"]);
    await context.sync();

    console.log("After updating:", "Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result));
  }
});

select(selectionMode)

选择该字段。

select(selectionMode?: "Select" | "Start" | "End"): void;

参数

selectionMode

"Select" | "Start" | "End"

可选。 选择模式必须为 select、 、start 或 end。 select 为默认值。

返回

void

注解

API 集:WordApi 1.5

set(properties, options)

同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象,也可以传递另一个相同类型的 API 对象。

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

参数

properties
Word.Interfaces.FieldUpdateData

一个 JavaScript 对象,其属性与调用该方法的对象的属性同构结构。

options
OfficeExtension.UpdateOptions

提供一个选项,用于在 properties 对象尝试设置任何只读属性时禁止错误。

返回

void

set(properties)

基于现有加载的对象,同时在对象上设置多个属性。

set(properties: Word.Field): void;

参数

properties
Word.Field

返回

void

toJSON()

覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Word.Field 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Word.Interfaces.FieldData) ,其中包含从原始对象加载的任何子属性的浅层副本。

toJSON(): Word.Interfaces.FieldData;

返回

track()

根据文档中的相应更改来跟踪对象,以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果在调用中 .sync 使用此对象,并且在“.run”批处理的顺序执行之外使用此对象,并且在设置属性或对对象调用方法时收到“InvalidObjectPath”错误,则需要在首次创建对象时将对象添加到跟踪对象集合。 如果此对象是集合的一部分,您还应跟踪父集合。

track(): Word.Field;

返回

将字段替换为最新结果。

unlink(): void;

返回

void

注解

API 集:WordApiDesktop 1.4

untrack()

释放与此对象关联的内存(如果先前已跟踪过)。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度,因此请在使用完毕后释放所添加的任何对象。 需要在内存释放生效之前调用 context.sync() 。

untrack(): Word.Field;

返回

updateResult()

汇报字段。

updateResult(): void;

返回

void

注解

API 集:WordApi 1.5

示例

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

// Gets and updates the first field in the selection.
await Word.run(async (context) => {
  let field = context.document.getSelection().fields.getFirstOrNullObject();
  field.load(["code", "result", "type", "locked"]);

  await context.sync();

  if (field.isNullObject) {
    console.log("No field in selection.");
  } else {
    console.log("Before updating:", "Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result));

    field.updateResult();
    field.select();
    await context.sync();

    field.load(["code", "result"]);
    await context.sync();

    console.log("After updating:", "Code of first field: " + field.code, "Result of first field: " + JSON.stringify(field.result));
  }
});

updateSource()

将对 INCLUDETEXT 字段 的结果所做的更改保存回源文档。

updateSource(): void;

返回

void

注解

API 集:WordApiDesktop 1.4