Word. Document class

Exemplos

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

// Gets the current change tracking mode.
await Word.run(async (context) => {
  const document: Word.Document = context.document;
  document.load("changeTrackingMode");
  await context.sync();

  if (document.changeTrackingMode === Word.ChangeTrackingMode.trackMineOnly) {
    console.log("Only my changes are being tracked.");
  } else if (document.changeTrackingMode === Word.ChangeTrackingMode.trackAll) {
    console.log("Everyone's changes are being tracked.");
  } else {
    console.log("No changes are being tracked.");
  }
});

Propriedades

body	Obtém o objeto do corpo do main documento. O corpo é o texto que exclui cabeçalhos, rodapés, notas de rodapé, caixas de texto, etc.
changeTrackingMode	Especifica o modo ChangeTracking.
contentControls	Obtém a coleção de objetos de controlo de conteúdo no documento. Isto inclui controlos de conteúdo no corpo do documento, cabeçalhos, rodapés, caixas de texto, etc.
context	O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
customXmlParts	Obtém as partes XML personalizadas no documento.
properties	Obtém as propriedades do documento.
saved	Indica se as alterações do documento foram salvas. Um valor true indica que o documento não foi alterado desde que foi salvo.
sections	Obtém a coleção de objetos de secção no documento.
settings	Obtém as definições do suplemento no documento.

Métodos

addStyle(name, type)	Adiciona um estilo ao documento por nome e tipo.
addStyle(name, typeString)	Adiciona um estilo ao documento por nome e tipo.
close(closeBehavior)	Fecha o documento atual. Nota: esta API não é suportada no Word na Web.
close(closeBehaviorString)	Fecha o documento atual. Nota: esta API não é suportada no Word na Web.
compare(filePath, documentCompareOptions)	Exibe marcas de revisão que indicam onde o documento especificado difere de um outro documento.
compareFromBase64(base64File, documentCompareOptions)	Exibe marcas de revisão que indicam onde o documento especificado difere de um outro documento.
deleteBookmark(name)	Elimina um marcador, se existir, do documento.
getAnnotationById(id)	Obtém a anotação por ID. Gera um `ItemNotFound` erro se a anotação não for encontrada.
getBookmarkRange(name)	Obtém o intervalo de um marcador. Gera um `ItemNotFound` erro se o marcador não existir.
getBookmarkRangeOrNullObject(name)	Obtém o intervalo de um marcador. Se o marcador não existir, este método devolverá um objeto com a respetiva `isNullObject` propriedade definida como `true`. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).
getContentControls(options)	Obtém os controlos de conteúdo atualmente suportados no documento.
getEndnoteBody()	Obtém as notas de fim do documento num único corpo.
getFootnoteBody()	Obtém as notas de rodapé do documento num único corpo.
getParagraphByUniqueLocalId(id)	Obtém o parágrafo pelo ID local exclusivo. Gera um `ItemNotFound` erro se a coleção estiver vazia.
getSelection()	Obtém a seleção atual do documento. Não são suportadas múltiplas seleções.
getStyles()	Obtém um objeto StyleCollection que representa todo o conjunto de estilos do documento.
importStylesFromJson(stylesJson)	Importar estilos de uma cadeia formatada em JSON.
insertFileFromBase64(base64File, insertLocation, insertFileOptions)	Insere um documento no documento de destino numa localização específica com propriedades adicionais. Os cabeçalhos, rodapés, marcas d'água e outras propriedades de secção são copiados por predefinição.
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.
save(saveBehavior, fileName)	Salva o documento.
save(saveBehaviorString, fileName)	Salva o documento.
search(searchText, searchOptions)	Efetua uma pesquisa com as opções de pesquisa especificadas no âmbito de todo o documento. Os resultados da pesquisa são uma coleção de objetos Range.
set(properties, options)	Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.
set(properties)	Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é transmitido para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que lhe é transmitido.) Enquanto o objeto original `Word.Document` é um objeto de API, o `toJSON` método devolve um objeto JavaScript simples (escrito como `Word.Interfaces.DocumentData`) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este 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, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez. Se este objeto fizer parte de uma coleção, também deve controlar a coleção principal.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta 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. Terá de chamar `context.sync()` antes de a libertação da memória ser aplicada.

Eventos

onAnnotationClicked	Ocorre quando o utilizador clica numa anotação (ou seleciona-a com Alt+Seta Para Baixo).
onAnnotationHovered	Ocorre quando o utilizador paira o cursor sobre uma anotação.
onAnnotationInserted	Ocorre quando o utilizador adiciona uma ou mais anotações.
onAnnotationPopupAction	Ocorre quando o utilizador executa uma ação num menu de pop-up de anotação.
onAnnotationRemoved	Ocorre quando o utilizador elimina uma ou mais anotações.
onContentControlAdded	Ocorre quando é adicionado um controlo de conteúdo. Execute context.sync() no processador para obter as propriedades do novo controlo de conteúdo.
onParagraphAdded	Ocorre quando o utilizador adiciona novos parágrafos.
onParagraphChanged	Ocorre quando o utilizador altera parágrafos.
onParagraphDeleted	Ocorre quando o utilizador elimina parágrafos.

Detalhes da propriedade

body

Obtém o objeto do corpo do main documento. O corpo é o texto que exclui cabeçalhos, rodapés, notas de rodapé, caixas de texto, etc.

readonly body: Word.Body;

Valor da propriedade

Word.Body

Comentários

changeTrackingMode

Especifica o modo ChangeTracking.

changeTrackingMode: Word.ChangeTrackingMode | "Off" | "TrackAll" | "TrackMineOnly";

Valor da propriedade

Word.ChangeTrackingMode | "Off" | "TrackAll" | "TrackMineOnly"

Comentários

Exemplos

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

// Gets the current change tracking mode.
await Word.run(async (context) => {
  const document: Word.Document = context.document;
  document.load("changeTrackingMode");
  await context.sync();

  if (document.changeTrackingMode === Word.ChangeTrackingMode.trackMineOnly) {
    console.log("Only my changes are being tracked.");
  } else if (document.changeTrackingMode === Word.ChangeTrackingMode.trackAll) {
    console.log("Everyone's changes are being tracked.");
  } else {
    console.log("No changes are being tracked.");
  }
});

contentControls

Obtém a coleção de objetos de controlo de conteúdo no documento. Isto inclui controlos de conteúdo no corpo do documento, cabeçalhos, rodapés, caixas de texto, etc.

readonly contentControls: Word.ContentControlCollection;

Valor da propriedade

Word.ContentControlCollection

Comentários

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Word.RequestContext

customXmlParts

Obtém as partes XML personalizadas no documento.

readonly customXmlParts: Word.CustomXmlPartCollection;

Valor da propriedade

Word.CustomXmlPartCollection

Comentários

properties

Obtém as propriedades do documento.

readonly properties: Word.DocumentProperties;

Valor da propriedade

Word.DocumentProperties

Comentários

[ Conjunto de API: WordApi 1.3 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/30-properties/get-built-in-properties.yaml

await Word.run(async (context) => {
    const builtInProperties: Word.DocumentProperties = context.document.properties;
    builtInProperties.load("*"); // Let's get all!

    await context.sync();
    console.log(JSON.stringify(builtInProperties, null, 4));
});

saved

Indica se as alterações do documento foram salvas. Um valor true indica que o documento não foi alterado desde que foi salvo.

readonly saved: boolean;

Valor da propriedade

boolean

Comentários

sections

Obtém a coleção de objetos de secção no documento.

readonly sections: Word.SectionCollection;

Valor da propriedade

Word.SectionCollection

Comentários

settings

Obtém as definições do suplemento no documento.

readonly settings: Word.SettingCollection;

Valor da propriedade

Word.SettingCollection

Comentários

Exemplos

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

// Gets all custom settings this add-in set on this document.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  settings.load("items");
  await context.sync();

  if (settings.items.length == 0) {
    console.log("There are no settings.");
  } else {
    console.log("All settings:");
    for (let i = 0; i < settings.items.length; i++) {
      console.log(settings.items[i]);
    }
  }
});

Detalhes do método

addStyle(name, type)

Adiciona um estilo ao documento por nome e tipo.

addStyle(name: string, type: Word.StyleType): Word.Style;

Parâmetros

name: string

Obrigatório. Uma cadeia que representa o nome do estilo.

type: Word.StyleType

Obrigatório. O tipo de estilo, incluindo caráter, lista, parágrafo ou tabela.

Retornos

Word.Style

Comentários

Exemplos

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

// Adds a new style.
await Word.run(async (context) => {
  const newStyleName = $("#new-style-name").val() as string;
  if (newStyleName == "") {
    console.warn("Enter a style name to add.");
    return;
  }

  const style: Word.Style = context.document.getStyles().getByNameOrNullObject(newStyleName);
  style.load();
  await context.sync();

  if (!style.isNullObject) {
    console.warn(
      `There's an existing style with the same name '${newStyleName}'! Please provide another style name.`
    );
    return;
  }

  const newStyleType = ($("#new-style-type").val() as unknown) as Word.StyleType;
  context.document.addStyle(newStyleName, newStyleType);
  await context.sync();

  console.log(newStyleName + " has been added to the style list.");
});

addStyle(name, typeString)

Adiciona um estilo ao documento por nome e tipo.

addStyle(name: string, typeString: "Character" | "List" | "Paragraph" | "Table"): Word.Style;

Parâmetros

name: string

Obrigatório. Uma cadeia que representa o nome do estilo.

typeString: "Character" | "List" | "Paragraph" | "Table"

Obrigatório. O tipo de estilo, incluindo caráter, lista, parágrafo ou tabela.

Retornos

Word.Style

Comentários

close(closeBehavior)

Fecha o documento atual.

Nota: esta API não é suportada no Word na Web.

close(closeBehavior?: Word.CloseBehavior): void;

Parâmetros

closeBehavior: Word.CloseBehavior

Opcional. O comportamento de fecho tem de ser "Guardar" ou "IgnorarGuardar". O valor predefinido é "Guardar".

Retornos

void

Comentários

Exemplos

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

// Closes the document with default behavior
// for current state of the document.
await Word.run(async (context) => {
  context.document.close();
});

close(closeBehaviorString)

Fecha o documento atual.

Nota: esta API não é suportada no Word na Web.

close(closeBehaviorString?: "Save" | "SkipSave"): void;

Parâmetros

closeBehaviorString: "Save" | "SkipSave"

Opcional. O comportamento de fecho tem de ser "Guardar" ou "IgnorarGuardar". O valor predefinido é "Guardar".

Retornos

void

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

compare(filePath, documentCompareOptions)

Exibe marcas de revisão que indicam onde o documento especificado difere de um outro documento.

compare(filePath: string, documentCompareOptions?: Word.DocumentCompareOptions): void;

Parâmetros

filePath: string

Obrigatório. O caminho do documento com o qual o documento especificado é comparado.

documentCompareOptions: Word.DocumentCompareOptions

Opcional. As opções adicionais que especificam o comportamento da comparação de documentos.

Retornos

void

Comentários

[ Conjunto de API: WordApiDesktop 1.1 ]

Exemplos

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

// Compares the current document with a specified external document.
await Word.run(async (context) => {
  // Absolute path of an online or local document.
  const filePath = $("#filePath")
    .val()
    .toString();
  // Options that configure the compare operation.
  const options: Word.DocumentCompareOptions = {
    compareTarget: Word.CompareTarget.compareTargetCurrent,
    detectFormatChanges: false
    // Other options you choose...
    };
  context.document.compare(filePath, options);

  await context.sync();

  console.log("Differences shown in the current document.");
});

compareFromBase64(base64File, documentCompareOptions)

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.

Exibe marcas de revisão que indicam onde o documento especificado difere de um outro documento.

compareFromBase64(base64File: string, documentCompareOptions?: Word.DocumentCompareOptions): void;

Parâmetros

base64File: string

Obrigatório. O conteúdo codificado com Base64 do documento com o qual o documento especificado é comparado.

documentCompareOptions: Word.DocumentCompareOptions

Opcional. As opções adicionais que especificam o comportamento para comparar os documentos. Tenha em atenção que a opção compareTarget não está autorizada a estar CompareTargetSelected nesta API.

Retornos

void

Comentários

deleteBookmark(name)

Elimina um marcador, se existir, do documento.

deleteBookmark(name: string): void;

Parâmetros

name: string

Obrigatório. O nome do marcador não sensível a maiúsculas e minúsculas.

Retornos

void

Comentários

getAnnotationById(id)

Obtém a anotação por ID. Gera um ItemNotFound erro se a anotação não for encontrada.

getAnnotationById(id: string): Word.Annotation;

Parâmetros

id: string

O ID da anotação a obter.

Retornos

Word.Annotation

Comentários

getBookmarkRange(name)

Obtém o intervalo de um marcador. Gera um ItemNotFound erro se o marcador não existir.

getBookmarkRange(name: string): Word.Range;

Parâmetros

name: string

Obrigatório. O nome do marcador não sensível a maiúsculas e minúsculas.

Retornos

Word.Range

Comentários

getBookmarkRangeOrNullObject(name)

Obtém o intervalo de um marcador. Se o marcador não existir, este método devolverá um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getBookmarkRangeOrNullObject(name: string): Word.Range;

Parâmetros

name: string

Obrigatório. O nome do marcador não sensível a maiúsculas e minúsculas.

Retornos

Word.Range

Comentários

getContentControls(options)

Obtém os controlos de conteúdo atualmente suportados no documento.

getContentControls(options?: Word.ContentControlOptions): Word.ContentControlCollection;

Parâmetros

options: Word.ContentControlOptions

Opcional. Opções que definem os controlos de conteúdo que são devolvidos.

Retornos

Word.ContentControlCollection

Comentários

Importante: se forem fornecidos tipos específicos no parâmetro de opções, apenas são devolvidos controlos de conteúdo de tipos suportados. Tenha em atenção que será gerada uma exceção através de métodos de um Word genérico. ContentControl que não são relevantes para o tipo específico. Com o tempo, podem ser suportados tipos adicionais de controlos de conteúdo. Por conseguinte, o suplemento deve pedir e processar tipos específicos de controlos de conteúdo.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/insert-and-change-checkbox-content-control.yaml

// Toggles the isChecked property on all checkbox content controls.
await Word.run(async (context) => {
  let contentControls = context.document.getContentControls({
    types: [Word.ContentControlType.checkBox]
  });
  contentControls.load("items");

  await context.sync();

  const length = contentControls.items.length;
  console.log(`Number of checkbox content controls: ${length}`);

  if (length <= 0) {
    return;
  }

  const checkboxContentControls = [];
  for (let i = 0; i < length; i++) {
    let contentControl = contentControls.items[i];
    contentControl.load("id,checkboxContentControl/isChecked");
    checkboxContentControls.push(contentControl);
  }

  await context.sync();

  console.log("isChecked state before:");
  const updatedCheckboxContentControls = [];
  for (let i = 0; i < checkboxContentControls.length; i++) {
    const currentCheckboxContentControl = checkboxContentControls[i];
    const isCheckedBefore = currentCheckboxContentControl.checkboxContentControl.isChecked;
    console.log(`id: ${currentCheckboxContentControl.id} ... isChecked: ${isCheckedBefore}`);

    currentCheckboxContentControl.checkboxContentControl.isChecked = !isCheckedBefore;
    currentCheckboxContentControl.load("id,checkboxContentControl/isChecked");
    updatedCheckboxContentControls.push(currentCheckboxContentControl);
  }

  await context.sync();

  console.log("isChecked state after:");
  for (let i = 0; i < updatedCheckboxContentControls.length; i++) {
    const currentCheckboxContentControl = updatedCheckboxContentControls[i];
    console.log(
      `id: ${currentCheckboxContentControl.id} ... isChecked: ${currentCheckboxContentControl.checkboxContentControl.isChecked}`
    );
  }
});

getEndnoteBody()

Obtém as notas de fim do documento num único corpo.

getEndnoteBody(): Word.Body;

Retornos

Word.Body

Comentários

getFootnoteBody()

Obtém as notas de rodapé do documento num único corpo.

getFootnoteBody(): Word.Body;

Retornos

Word.Body

Comentários

getParagraphByUniqueLocalId(id)

Obtém o parágrafo pelo ID local exclusivo. Gera um ItemNotFound erro se a coleção estiver vazia.

getParagraphByUniqueLocalId(id: string): Word.Paragraph;

Parâmetros

id: string

Obrigatório. ID local exclusivo no formato GUID padrão 8-4-4-4-12 sem chavetas. Tenha em atenção que o ID difere entre sessões e cocriadores.

Retornos

Word.Paragraph

Comentários

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/onadded-event.yaml

await Word.run(async (context) => {
  const paragraphId = $("#paragraph-id").val() as string;
  const paragraph: Word.Paragraph = context.document.getParagraphByUniqueLocalId(paragraphId);
  paragraph.load();
  await paragraph.context.sync();

  console.log(paragraph);
});

getSelection()

Obtém a seleção atual do documento. Não são suportadas múltiplas seleções.

getSelection(): Word.Range;

Retornos

Word.Range

Comentários

Exemplos

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    const textSample = 'This is an example of the insert text method. This is a method ' + 
        'which allows users to insert text into a selection. It can insert text into a ' +
        'relative location or it can overwrite the current selection. Since the ' +
        'getSelection method returns a range object, look up the range object documentation ' +
        'for everything you can do with a selection.';
    
    // Create a range proxy object for the current selection.
    const range = context.document.getSelection();
    
    // Queue a command to insert text at the end of the selection.
    range.insertText(textSample, Word.InsertLocation.end);
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Inserted the text at the end of the selection.');
});

getStyles()

Obtém um objeto StyleCollection que representa todo o conjunto de estilos do documento.

getStyles(): Word.StyleCollection;

Retornos

Word.StyleCollection

Comentários

Exemplos

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

// Gets the number of available styles stored with the document.
await Word.run(async (context) => {
  const styles: Word.StyleCollection = context.document.getStyles();
  const count = styles.getCount();
  await context.sync();

  console.log(`Number of styles: ${count.value}`);
});

importStylesFromJson(stylesJson)

Importar estilos de uma cadeia formatada em JSON.

importStylesFromJson(stylesJson: string): OfficeExtension.ClientResult<string[]>;

Parâmetros

stylesJson: string

Obrigatório. Uma cadeia formatada em JSON que representa os estilos.

Retornos

OfficeExtension.ClientResult<string[]>

Comentários

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/manage-custom-style.yaml

// Imports styles from JSON.
await Word.run(async (context) => {
  const str =
    '{"styles":[{"baseStyle":"Default Paragraph Font","builtIn":false,"inUse":true,"linked":false,"nameLocal":"NewCharStyle","priority":2,"quickStyle":true,"type":"Character","unhideWhenUsed":false,"visibility":false,"paragraphFormat":null,"font":{"name":"DengXian Light","size":16.0,"bold":true,"italic":false,"color":"#F1A983","underline":"None","subscript":false,"superscript":true,"strikeThrough":true,"doubleStrikeThrough":false,"highlightColor":null,"hidden":false},"shading":{"backgroundPatternColor":"#FF0000"}},{"baseStyle":"Normal","builtIn":false,"inUse":true,"linked":false,"nextParagraphStyle":"NewParaStyle","nameLocal":"NewParaStyle","priority":1,"quickStyle":true,"type":"Paragraph","unhideWhenUsed":false,"visibility":false,"paragraphFormat":{"alignment":"Centered","firstLineIndent":0.0,"keepTogether":false,"keepWithNext":false,"leftIndent":72.0,"lineSpacing":18.0,"lineUnitAfter":0.0,"lineUnitBefore":0.0,"mirrorIndents":false,"outlineLevel":"OutlineLevelBodyText","rightIndent":72.0,"spaceAfter":30.0,"spaceBefore":30.0,"widowControl":true},"font":{"name":"DengXian","size":14.0,"bold":true,"italic":true,"color":"#8DD873","underline":"Single","subscript":false,"superscript":false,"strikeThrough":false,"doubleStrikeThrough":true,"highlightColor":null,"hidden":false},"shading":{"backgroundPatternColor":"#00FF00"}},{"baseStyle":"Table Normal","builtIn":false,"inUse":true,"linked":false,"nextParagraphStyle":"NewTableStyle","nameLocal":"NewTableStyle","priority":100,"type":"Table","unhideWhenUsed":false,"visibility":false,"paragraphFormat":{"alignment":"Left","firstLineIndent":0.0,"keepTogether":false,"keepWithNext":false,"leftIndent":0.0,"lineSpacing":12.0,"lineUnitAfter":0.0,"lineUnitBefore":0.0,"mirrorIndents":false,"outlineLevel":"OutlineLevelBodyText","rightIndent":0.0,"spaceAfter":0.0,"spaceBefore":0.0,"widowControl":true},"font":{"name":"DengXian","size":20.0,"bold":false,"italic":true,"color":"#D86DCB","underline":"None","subscript":false,"superscript":false,"strikeThrough":false,"doubleStrikeThrough":false,"highlightColor":null,"hidden":false},"tableStyle":{"allowBreakAcrossPage":true,"alignment":"Left","bottomCellMargin":0.0,"leftCellMargin":0.08,"rightCellMargin":0.08,"topCellMargin":0.0,"cellSpacing":0.0},"shading":{"backgroundPatternColor":"#60CAF3"}}]}';
  const styles = context.document.importStylesFromJson(str);
  await context.sync();
  console.log("Styles imported from JSON:", styles);
});

insertFileFromBase64(base64File, insertLocation, insertFileOptions)

Insere um documento no documento de destino numa localização específica com propriedades adicionais. Os cabeçalhos, rodapés, marcas d'água e outras propriedades de secção são copiados por predefinição.

insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End", insertFileOptions?: Word.InsertFileOptions): Word.SectionCollection;

Parâmetros

base64File: string

Obrigatório. O conteúdo codificado em Base64 de um ficheiro .docx.

insertLocation: replace | start | end | "Replace" | "Start" | "End"

Obrigatório. O valor tem de ser "Substituir", "Iniciar" ou "Terminar".

insertFileOptions: Word.InsertFileOptions

Opcional. As propriedades adicionais que devem ser importadas para o documento de destino.

Retornos

Word.SectionCollection

Comentários

Nota: a inserção não é suportada se o documento que está a ser inserido contiver um controlo ActiveX (provavelmente num campo de formulário). Considere substituir tal campo de formulário por um controlo de conteúdo ou outra opção adequada para o seu cenário.

Exemplos

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

// Inserts content (applying selected settings) from another document passed in as a Base64-encoded string.
await Word.run(async (context) => {
  // Use the Base64-encoded string representation of the selected .docx file.
  context.document.insertFileFromBase64(externalDocument, "Replace", {
    importTheme: true,
    importStyles: true,
    importParagraphSpacing: true,
    importPageColor: true,
    importChangeTrackingMode: true,
    importCustomProperties: true,
    importCustomXmlParts: true,
    importDifferentOddEvenPages: true
  });
  await context.sync();
});

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.DocumentLoadOptions): Word.Document;

Parâmetros

options: Word.Interfaces.DocumentLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

Word.Document

Exemplos

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the document.
    const thisDocument = context.document;
    
    // Queue a command to load content control properties.
    thisDocument.load('contentControls/id, contentControls/text, contentControls/tag');
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (thisDocument.contentControls.items.length !== 0) {
        for (let i = 0; i < thisDocument.contentControls.items.length; i++) {
            console.log(thisDocument.contentControls.items[i].id);
            console.log(thisDocument.contentControls.items[i].text);
            console.log(thisDocument.contentControls.items[i].tag);
        }
    } else {
        console.log('No content controls in this document.');
    }
});

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.Document;

Parâmetros

propertyNames: string | string[]

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

Retornos

Word.Document

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.Document;

Parâmetros

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

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

Retornos

Word.Document

save(saveBehavior, fileName)

Salva o documento.

save(saveBehavior?: Word.SaveBehavior, fileName?: string): void;

Parâmetros

saveBehavior: Word.SaveBehavior

Opcional. O comportamento de guardar tem de ser "Guardar" ou "Pedido". O valor predefinido é "Guardar".

fileName: string

Opcional. O nome do ficheiro (exclua a extensão de ficheiro). Só tem efeito para um novo documento.

Retornos

void

Comentários

Nota: os saveBehavior parâmetros e fileName foram introduzidos no WordApi 1.5.

Exemplos

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the document.
    const thisDocument = context.document;

    // Queue a command to load the document save state (on the saved property).
    thisDocument.load('saved');    
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        
    if (thisDocument.saved === false) {
        // Queue a command to save this document.
        thisDocument.save();
        
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Saved the document');
    } else {
        console.log('The document has not changed since the last save.');
    }
});

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

// Saves the document with default behavior
// for current state of the document.
await Word.run(async (context) => {
  context.document.save();
  await context.sync();
});

save(saveBehaviorString, fileName)

Salva o documento.

save(saveBehaviorString?: "Save" | "Prompt", fileName?: string): void;

Parâmetros

saveBehaviorString: "Save" | "Prompt"

Opcional. O comportamento de guardar tem de ser "Guardar" ou "Pedido". O valor predefinido é "Guardar".

fileName: string

Opcional. O nome do ficheiro (exclua a extensão de ficheiro). Só tem efeito para um novo documento.

Retornos

void

Comentários

Nota: os saveBehavior parâmetros e fileName foram introduzidos no WordApi 1.5.

search(searchText, searchOptions)

Efetua uma pesquisa com as opções de pesquisa especificadas no âmbito de todo o documento. Os resultados da pesquisa são uma coleção de objetos Range.

search(searchText: string, searchOptions?: Word.SearchOptions | {
            ignorePunct?: boolean;
            ignoreSpace?: boolean;
            matchCase?: boolean;
            matchPrefix?: boolean;
            matchSuffix?: boolean;
            matchWholeWord?: boolean;
            matchWildcards?: boolean;
        }): Word.RangeCollection;

Parâmetros

searchText: string

searchOptions: Word.SearchOptions | { ignorePunct?: boolean; ignoreSpace?: boolean; matchCase?: boolean; matchPrefix?: boolean; matchSuffix?: boolean; matchWholeWord?: boolean; matchWildcards?: boolean; }

Retornos

Word.RangeCollection

Comentários

OfficeExtension.EventHandlers<Word.AnnotationClickedEventArgs>

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

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

Parâmetros

properties: Word.Interfaces.DocumentUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options: OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

set(properties)

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

set(properties: Word.Document): void;

Parâmetros

properties: Word.Document

Retornos

void

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Word.Document é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Word.Interfaces.DocumentData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Word.Interfaces.DocumentData;

Retornos

Word.Interfaces.DocumentData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este 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, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez. Se este objeto fizer parte de uma coleção, também deve controlar a coleção principal.

track(): Word.Document;

Retornos

Word.Document

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta 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. Terá de chamar context.sync() antes de a libertação da memória ser aplicada.

untrack(): Word.Document;

Retornos

Word.Document

Detalhes do evento

onAnnotationClicked

Ocorre quando o utilizador clica numa anotação (ou seleciona-a com Alt+Seta Para Baixo).

readonly onAnnotationClicked: OfficeExtension.EventHandlers<Word.AnnotationClickedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.AnnotationHoveredEventArgs>

Exemplos

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

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onClickedHandler(args: Word.AnnotationClickedEventArgs) {
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationClicked: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

onAnnotationHovered

Ocorre quando o utilizador paira o cursor sobre uma anotação.

readonly onAnnotationHovered: OfficeExtension.EventHandlers<Word.AnnotationHoveredEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.AnnotationInsertedEventArgs>

Exemplos

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

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onHoveredHandler(args: Word.AnnotationHoveredEventArgs) {
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationHovered: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

onAnnotationInserted

Ocorre quando o utilizador adiciona uma ou mais anotações.

readonly onAnnotationInserted: OfficeExtension.EventHandlers<Word.AnnotationInsertedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.AnnotationPopupActionEventArgs>

Exemplos

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

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onInsertedHandler(args: Word.AnnotationInsertedEventArgs) {
  await Word.run(async (context) => {
    const annotations = [];
    for (let i = 0; i < args.ids.length; i++) {
      let annotation: Word.Annotation = context.document.getAnnotationById(args.ids[i]);
      annotation.load("id,critiqueAnnotation");

      annotations.push(annotation);
    }

    await context.sync();

    for (let annotation of annotations) {
      console.log(`AnnotationInserted: ID ${annotation.id}:`, annotation.critiqueAnnotation.critique);
    }
  });
}

onAnnotationPopupAction

Ocorre quando o utilizador executa uma ação num menu de pop-up de anotação.

readonly onAnnotationPopupAction: OfficeExtension.EventHandlers<Word.AnnotationPopupActionEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: WordApi 1.8 ]

Exemplos

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

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onPopupActionHandler(args: Word.AnnotationPopupActionEventArgs) {
  await Word.run(async (context) => {
    let message = `AnnotationPopupAction: ID ${args.id} = `;
    if (args.action === "Accept") {
      message += `Accepted: ${args.critiqueSuggestion}`;
    } else {
      message += "Rejected";
    }

    console.log(message);
  });
}

onAnnotationRemoved

Ocorre quando o utilizador elimina uma ou mais anotações.

readonly onAnnotationRemoved: OfficeExtension.EventHandlers<Word.AnnotationRemovedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Word.AnnotationRemovedEventArgs>

Comentários

OfficeExtension.EventHandlers<Word.ContentControlAddedEventArgs>

Exemplos

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

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onRemovedHandler(args: Word.AnnotationRemovedEventArgs) {
  await Word.run(async (context) => {
    for (let id of args.ids) {
      console.log(`AnnotationRemoved: ID ${id}`);
    }
  });
}

onContentControlAdded

Ocorre quando é adicionado um controlo de conteúdo. Execute context.sync() no processador para obter as propriedades do novo controlo de conteúdo.

readonly onContentControlAdded: OfficeExtension.EventHandlers<Word.ContentControlAddedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.ParagraphAddedEventArgs>

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-onadded-event.yaml

// Registers the onAdded event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onContentControlAdded.add(contentControlAdded);
  await context.sync();

  console.log("Added event handler for when content controls are added.");
});

...

async function contentControlAdded(event: Word.ContentControlAddedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. IDs of content controls that were added:`, event.ids);
  });
}

onParagraphAdded

Ocorre quando o utilizador adiciona novos parágrafos.

readonly onParagraphAdded: OfficeExtension.EventHandlers<Word.ParagraphAddedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.ParagraphChangedEventArgs>

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/onadded-event.yaml

// Registers the onParagraphAdded event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onParagraphAdded.add(paragraphAdded);
  await context.sync();

  console.log("Added event handler for when paragraphs are added.");
});

...

async function paragraphAdded(event: Word.ParagraphAddedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.type} event detected. IDs of paragraphs that were added:`, event.uniqueLocalIds);
  });
}

onParagraphChanged

Ocorre quando o utilizador altera parágrafos.

readonly onParagraphChanged: OfficeExtension.EventHandlers<Word.ParagraphChangedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.ParagraphDeletedEventArgs>

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/onchanged-event.yaml

// Registers the onParagraphChanged event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onParagraphChanged.add(paragraphChanged);
  await context.sync();

  console.log("Added event handler for when content is changed in paragraphs.");
});

...

async function paragraphChanged(event: Word.ParagraphChangedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.type} event detected. IDs of paragraphs where content was changed:`, event.uniqueLocalIds);
  });
}

onParagraphDeleted

Ocorre quando o utilizador elimina parágrafos.

readonly onParagraphDeleted: OfficeExtension.EventHandlers<Word.ParagraphDeletedEventArgs>;

Tipo de evento

Comentários