Word.Field class

Referência

Pacote:: word

Representa um campo.

Extends: OfficeExtension.ClientObject

Comentários

Importante: para saber mais sobre quais campos podem ser inseridos, consulte o Word. API Range.insertField introduzida no conjunto de requisitos 1.5. O suporte para o gerenciamento de campos é semelhante ao que está disponível na interface do usuário Word. No entanto, enquanto o Word interface do usuário na Web dá suporte principalmente apenas a campos como somente leitura (consulte Códigos de campo em Word para a Web), o Addin campo é editável. Para saber mais sobre Word clientes de interface do usuário que oferecem suporte mais completo aos campos, confira a lista de produtos no início dos campos Inserir, editar e exibir em Word.

Propriedades

code	Especifica as instruções de código do campo.
context	O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.
data	Especifica dados em um campo "Addin". Se o campo não for um campo "Addin", ele será nulo e gerará uma exceção geral quando o código tentar defini-lo.
kind	Obtém o tipo do campo.
locked	Especifica se o campo está bloqueado. `true` se o campo estiver bloqueado, `false` caso contrário.
parentBody	Obtém o corpo pai do campo.
parentContentControl	Obtém o controle de conteúdo que contém o campo. Gerará um `ItemNotFound` erro se não houver um controle de conteúdo pai.
parentContentControlOrNullObject	Obtém o controle de conteúdo que contém o campo. Se não houver um controle de conteúdo pai, esse método retornará um objeto com sua `isNullObject` propriedade definida como `true`. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
parentTable	Obtém a tabela que contém o campo. Gerará um `ItemNotFound` erro se ele não estiver contido em uma tabela.
parentTableCell	Obtém a célula de tabela que contém o campo. Gerará um `ItemNotFound` erro se ele não estiver contido em uma célula de tabela.
parentTableCellOrNullObject	Obtém a célula de tabela que contém o campo. Se ele não estiver contido em uma célula de tabela, esse método retornará um objeto com sua `isNullObject` propriedade definida como `true`. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
parentTableOrNullObject	Obtém a tabela que contém o campo. Se ele não estiver contido em uma tabela, esse método retornará um objeto com sua `isNullObject` propriedade definida como `true`. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
result	Obtém os dados de resultado do campo.
showCodes	Especifica se os códigos de campo são exibidos para o campo especificado. `true` se os códigos de campo forem exibidos, `false` caso contrário.
type	Obtém o tipo do campo.

Métodos

delete()	Exclui o campo.
getNext()	Obtém o próximo campo. Gerará um `ItemNotFound` erro se este campo for o último.
getNextOrNullObject()	Obtém o próximo campo. Se esse campo for o último, esse método retornará um objeto com sua `isNullObject` propriedade definida como `true`. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
select(selectionMode)	Seleciona o campo.
select(selectionModeString)	Seleciona o campo.
set(properties, options)	Define várias propriedades de um objeto ao mesmo tempo. Você pode passar um objeto simples com as propriedades apropriadas ou outro objeto de API do mesmo tipo.
set(properties)	Define várias propriedades no objeto ao mesmo tempo, com base em um objeto carregado existente.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é passado para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que é passado para ele.) Enquanto o Word original. Objeto field é um objeto API, o `toJSON` método retorna um objeto JavaScript simples (digitado como `Word.Interfaces.FieldData`) que contém cópias rasas de quaisquer propriedades filho carregadas do objeto original.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação para context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre `.sync` chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, você precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará chamar `context.sync()` antes que a versão da memória entre em vigor.
updateResult()	Atualizações campo.

Detalhes da propriedade

code

Especifica as instruções de código do campo.

code: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: WordApi 1.4 ]

Observação: a capacidade de definir o código foi introduzida no WordApi 1.5.

Exemplos

// 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 = 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);
    console.log("Result of first field: " + JSON.stringify(field.result));
    console.log("Type of first field: " + field.type);
    console.log("Is the first field locked? " + field.locked);
    console.log("Kind of the first field: " + field.kind);
  }
});

context

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

Word.RequestContext

data

Especifica dados em um campo "Addin". Se o campo não for um campo "Addin", ele será nulo e gerará uma exceção geral quando o código tentar defini-lo.

data: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: WordApi 1.5 ]

kind

Obtém o tipo do campo.

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

Valor da propriedade

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

Comentários

[ Conjunto de API: WordApi 1.5 ]

Exemplos

// 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 = 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);
    console.log("Result of first field: " + JSON.stringify(field.result));
    console.log("Type of first field: " + field.type);
    console.log("Is the first field locked? " + field.locked);
    console.log("Kind of the first field: " + field.kind);
  }
});

locked

Especifica se o campo está bloqueado. true se o campo estiver bloqueado, false caso contrário.

locked: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: WordApi 1.5 ]

Exemplos

// 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) => {
  var 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"}.`);
  }
});

parentBody

Obtém o corpo pai do campo.

readonly parentBody: Word.Body;

Valor da propriedade

Word.Body

Comentários

[ Conjunto de API: WordApi 1.4 ]

Exemplos

// 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 = 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 = field.parentBody;
    console.log("Text of first field's parent body: " + JSON.stringify(parentBody.text));
  }
});

parentContentControl

Obtém o controle de conteúdo que contém o campo. Gerará um ItemNotFound erro se não houver um controle de conteúdo pai.

readonly parentContentControl: Word.ContentControl;

Valor da propriedade

Word.ContentControl

Comentários

[ Conjunto de API: WordApi 1.4 ]

parentContentControlOrNullObject

Obtém o controle de conteúdo que contém o campo. Se não houver um controle de conteúdo pai, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

readonly parentContentControlOrNullObject: Word.ContentControl;

Valor da propriedade

Word.ContentControl

Comentários

[ Conjunto de API: WordApi 1.4 ]

parentTable

Obtém a tabela que contém o campo. Gerará um ItemNotFound erro se ele não estiver contido em uma tabela.

readonly parentTable: Word.Table;

Valor da propriedade

Word.Table

Comentários

[ Conjunto de API: WordApi 1.4 ]

parentTableCell

Obtém a célula de tabela que contém o campo. Gerará um ItemNotFound erro se ele não estiver contido em uma célula de tabela.

readonly parentTableCell: Word.TableCell;

Valor da propriedade

Word.TableCell

Comentários

[ Conjunto de API: WordApi 1.4 ]

parentTableCellOrNullObject

Obtém a célula de tabela que contém o campo. Se ele não estiver contido em uma célula de tabela, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

readonly parentTableCellOrNullObject: Word.TableCell;

Valor da propriedade

Word.TableCell

Comentários

[ Conjunto de API: WordApi 1.4 ]

parentTableOrNullObject

Obtém a tabela que contém o campo. Se ele não estiver contido em uma tabela, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

readonly parentTableOrNullObject: Word.Table;

Valor da propriedade

Word.Table

Comentários

[ Conjunto de API: WordApi 1.4 ]

result

Obtém os dados de resultado do campo.

readonly result: Word.Range;

Valor da propriedade

Word.Range

Comentários

[ Conjunto de API: WordApi 1.4 ]

Exemplos

// 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 = 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);
    console.log("Result of first field: " + JSON.stringify(field.result));
    console.log("Type of first field: " + field.type);
    console.log("Is the first field locked? " + field.locked);
    console.log("Kind of the first field: " + field.kind);
  }
});

showCodes

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Especifica se os códigos de campo são exibidos para o campo especificado. true se os códigos de campo forem exibidos, false caso contrário.

showCodes: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: WordApi BETA (SOMENTE VERSÃO PRÉVIA) ]

type

Obtém o tipo do campo.

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";

Valor da propriedade

Comentários

[ Conjunto de API: WordApi 1.5 ]

Exemplos

// 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 = 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);
    console.log("Result of first field: " + JSON.stringify(field.result));
    console.log("Type of first field: " + field.type);
    console.log("Is the first field locked? " + field.locked);
    console.log("Kind of the first field: " + field.kind);
  }
});

Detalhes do método

delete()

Exclui o campo.

delete(): void;

Retornos

void

Comentários

[ Conjunto de API: WordApi 1.5 ]

Exemplos

// 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 = 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.");
  }
});

getNext()

Obtém o próximo campo. Gerará um ItemNotFound erro se este campo for o último.

getNext(): Word.Field;

Retornos

Word.Field

Comentários

[ Conjunto de API: WordApi 1.4 ]

getNextOrNullObject()

Obtém o próximo campo. Se esse campo for o último, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

getNextOrNullObject(): Word.Field;

Retornos

Word.Field

Comentários

[ Conjunto de API: WordApi 1.4 ]

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

options: Word.Interfaces.FieldLoadOptions

Fornece opções para quais propriedades do objeto carregar.

Retornos

Word.Field

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

propertyNames: string | string[]

Uma cadeia de caracteres delimitada por vírgulas ou uma matriz de cadeias de caracteres que especificam as propriedades a serem carregadas.

Retornos

Word.Field

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

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

propertyNamesAndPaths.select é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades de navegação a serem carregadas.

Retornos

Word.Field

select(selectionMode)

Seleciona o campo.

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

Parâmetros

selectionMode: Word.SelectionMode

Opcional. O modo de seleção deve ser 'Select', 'Start' ou 'End'. 'Select' é o padrão.

Retornos

void

Comentários

[ Conjunto de API: WordApi 1.5 ]

Exemplos

// 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) => {
  var 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:");
    console.log("Code of first field: " + field.code);
    console.log("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:");
    console.log("Code of first field: " + field.code);
    console.log("Result of first field: " + JSON.stringify(field.result));
  }
});

select(selectionModeString)

Seleciona o campo.

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

Parâmetros

selectionModeString: "Select" | "Start" | "End"

Opcional. O modo de seleção deve ser 'Select', 'Start' ou 'End'. 'Select' é o padrão.

Retornos

void

Comentários

[ Conjunto de API: WordApi 1.5 ]

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Você pode passar um objeto simples com as propriedades apropriadas ou outro objeto de API do mesmo tipo.

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

Parâmetros

properties: Word.Interfaces.FieldUpdateData

Um objeto JavaScript com propriedades estruturadas isomorficamente para as propriedades do objeto no qual o método é chamado.

options: OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto properties tentar definir quaisquer propriedades somente leitura.

Retornos

void

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base em um objeto carregado existente.

set(properties: Word.Field): void;

Parâmetros

properties: Word.Field

Retornos

void

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o Word original. Objeto field é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado como Word.Interfaces.FieldData) que contém cópias rasas de quaisquer propriedades filho carregadas do objeto original.

toJSON(): Word.Interfaces.FieldData;

Retornos

Word.Interfaces.FieldData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação para context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, você precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.

track(): Word.Field;

Retornos

Word.Field

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará chamar context.sync() antes que a versão da memória entre em vigor.

untrack(): Word.Field;

Retornos

Word.Field

updateResult()

Atualizações campo.

updateResult(): void;

Retornos

void

Comentários

[ Conjunto de API: WordApi 1.5 ]

Exemplos

// 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) => {
  var 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:");
    console.log("Code of first field: " + field.code);
    console.log("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:");
    console.log("Code of first field: " + field.code);
    console.log("Result of first field: " + JSON.stringify(field.result));
  }
});