Word.Field class
表示一个字段。
注解
重要提示:要详细了解可以插入哪些字段,请参阅要求集 1.5 中引入的 Word.Range.insertField API。 对字段管理的支持类似于 Word UI 中提供的功能。 但是,Web 上的 Word UI 主要仅支持只读字段, (请参阅 Word 网页版中的字段代码) 。 若要深入了解更完全支持字段的 Word UI 客户端,请参阅“在 Word 中插入、编辑和查看字段”开头的产品列表。
使用方
- Word.FieldCollection: getFirst, getFirstOrNullObject, items
- Word.范围:insertField
- Word.按选定内容: nextField, previousField
- Word.TableOfAuthoritiesCollection: markCitation
- Word.TableOfContentsCollection: markTocEntry
- Word.TableOfFiguresCollection: markTocEntry
示例
// 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 | 指定类型字段中 |
| kind | 获取字段的种类。 |
| link |
获取表示 |
| locked | 指定字段是否已锁定。
|
| ole |
获取表示 |
| parent |
获取字段的父实体。 |
| parent |
获取包含该字段的内容控件。 如果没有父内容控件,则引发 |
| parent |
获取包含该字段的内容控件。 如果没有父内容控件,则此方法将返回其 |
| parent |
获取包含字段的表。 如果表中未包含,则引发 |
| parent |
获取包含字段的表单元格。 如果表单元格中未包含错误,则引发 |
| parent |
获取包含字段的表单元格。 如果它未包含在表单元格中,则此方法将返回其 |
| parent |
获取包含字段的表。 如果它未包含在表中,则此方法将返回其 |
| result | 获取字段的结果数据。 |
| show |
指定是否显示指定字段的字段代码。
|
| type | 获取字段的类型。 |
方法
| copy |
将字段复制到剪贴板。 |
| cut() | 从文档中删除字段并将其置于剪贴板中。 |
| delete() | 删除字段。 |
| do |
单击该字段。 |
| get |
获取下一个字段。 如果此字段是最后一个字段,则引发 |
| get |
获取下一个字段。 如果此字段是最后一个字段,则此方法将返回其 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| select(selection |
选择该字段。 |
| select(selection |
选择该字段。 |
| set(properties, options) | 同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象,也可以传递另一个相同类型的 API 对象。 |
| set(properties) | 基于现有加载的对象,同时在对象上设置多个属性。 |
| toJSON() | 覆盖 JavaScript |
| track() | 根据文档中的相应更改来跟踪对象,以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果在调用中 |
| unlink() | 将字段替换为最新结果。 |
| untrack() | 释放与此对象关联的内存(如果先前已跟踪过)。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度,因此请在使用完毕后释放所添加的任何对象。 需要在内存释放生效之前调用 |
| update |
汇报字段。 |
| update |
将对 INCLUDETEXT 字段 的结果所做的更改保存回源文档。 |
属性详细信息
code
指定字段的代码指令。
code: string;
属性值
string
注解
注意: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
data
指定类型字段中 addin 的数据。 如果字段不是一个 addin 类型,它就是 null ,当代码尝试设置它时,它将引发常规异常。
data: string;
属性值
string
注解
kind
获取字段的种类。
readonly kind: Word.FieldKind | "None" | "Hot" | "Warm" | "Cold";
属性值
Word.FieldKind | "None" | "Hot" | "Warm" | "Cold"
注解
示例
// 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;
属性值
注解
locked
指定字段是否已锁定。
true 如果该字段已锁定, false 则为否。
locked: boolean;
属性值
boolean
注解
示例
// 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;
属性值
注解
parentBody
获取字段的父实体。
readonly parentBody: Word.Body;
属性值
注解
示例
// 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;
属性值
注解
parentContentControlOrNullObject
获取包含该字段的内容控件。 如果没有父内容控件,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。
readonly parentContentControlOrNullObject: Word.ContentControl;
属性值
注解
parentTable
获取包含字段的表。 如果表中未包含,则引发 ItemNotFound 错误。
readonly parentTable: Word.Table;
属性值
注解
parentTableCell
获取包含字段的表单元格。 如果表单元格中未包含错误,则引发 ItemNotFound 错误。
readonly parentTableCell: Word.TableCell;
属性值
注解
parentTableCellOrNullObject
获取包含字段的表单元格。 如果它未包含在表单元格中,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。
readonly parentTableCellOrNullObject: Word.TableCell;
属性值
注解
parentTableOrNullObject
获取包含字段的表。 如果它未包含在表中,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。
readonly parentTableOrNullObject: Word.Table;
属性值
注解
result
获取字段的结果数据。
readonly result: Word.Range;
属性值
注解
示例
// 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
注解
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"
注解
示例
// 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()
cut()
delete()
删除字段。
delete(): void;
返回
void
注解
示例
// 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()
getNext()
获取下一个字段。 如果此字段是最后一个字段,则引发 ItemNotFound 错误。
getNext(): Word.Field;
返回
注解
getNextOrNullObject()
获取下一个字段。 如果此字段是最后一个字段,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。
getNextOrNullObject(): Word.Field;
返回
注解
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
注解
示例
// 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
注解
set(properties, options)
同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象,也可以传递另一个相同类型的 API 对象。
set(properties: Interfaces.FieldUpdateData, options?: OfficeExtension.UpdateOptions): void;
参数
- properties
- Word.Interfaces.FieldUpdateData
一个 JavaScript 对象,其属性与调用该方法的对象的属性同构结构。
- options
- OfficeExtension.UpdateOptions
提供一个选项,用于在 properties 对象尝试设置任何只读属性时禁止错误。
返回
void
set(properties)
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()
untrack()
释放与此对象关联的内存(如果先前已跟踪过)。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度,因此请在使用完毕后释放所添加的任何对象。 需要在内存释放生效之前调用 context.sync() 。
untrack(): Word.Field;
返回
updateResult()
汇报字段。
updateResult(): void;
返回
void
注解
示例
// 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));
}
});