Word. Document class

Ejemplos

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

Propiedades

body	Obtiene el objeto body del documento principal. El cuerpo es el texto que excluye encabezados, pies de página, notas al pie, cuadros de texto, etc.
changeTrackingMode	Especifica el modo ChangeTracking.
contentControls	Obtiene la colección de objetos de control de contenido del documento. Esto incluye controles de contenido en el cuerpo del documento, encabezados, pies de página, cuadros de texto, etc.
context	Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.
customXmlParts	Obtiene los elementos XML personalizados del documento.
properties	Obtiene las propiedades del documento.
saved	Indica si se guardaron los cambios en el documento. Un valor de true indica que el documento no cambió desde que se guardó.
sections	Obtiene la colección de objetos de sección del documento.
settings	Obtiene la configuración del complemento en el documento.

Métodos

addStyle(name, type)	Agrega un estilo al documento por nombre y tipo.
addStyle(name, typeString)	Agrega un estilo al documento por nombre y tipo.
close(closeBehavior)	Cierra el documento actual. Nota: Esta API no se admite en Word en la web.
close(closeBehaviorString)	Cierra el documento actual. Nota: Esta API no se admite en Word en la web.
compare(filePath, documentCompareOptions)	Muestra las marcas de revisión para indicar dónde están las diferencias entre ambos documentos.
compareFromBase64(base64File, documentCompareOptions)	Muestra las marcas de revisión para indicar dónde están las diferencias entre ambos documentos.
deleteBookmark(name)	Elimina un marcador, si existe, del documento.
getAnnotationById(id)	Obtiene la anotación por identificador. Produce un `ItemNotFound` error si no se encuentra la anotación.
getBookmarkRange(name)	Obtiene el intervalo de un marcador. Produce un `ItemNotFound` error si el marcador no existe.
getBookmarkRangeOrNullObject(name)	Obtiene el intervalo de un marcador. Si el marcador no existe, este método devolverá un objeto con su `isNullObject` propiedad establecida en `true`. Para obtener más información, vea OrNullObject methods and properties( Métodos y propiedades de OrNullObject).
getContentControls(options)	Obtiene los controles de contenido admitidos actualmente en el documento.
getEndnoteBody()	Obtiene las notas al final del documento en un solo cuerpo.
getFootnoteBody()	Obtiene las notas al pie del documento en un único cuerpo.
getParagraphByUniqueLocalId(id)	Obtiene el párrafo por su identificador local único. Produce un `ItemNotFound` error si la colección está vacía.
getSelection()	Obtiene la selección actual del documento. No se admiten varias selecciones.
getStyles()	Obtiene un objeto StyleCollection que representa todo el conjunto de estilos del documento.
importStylesFromJson(stylesJson)	Importar estilos desde una cadena con formato JSON.
insertFileFromBase64(base64File, insertLocation, insertFileOptions)	Inserta un documento en el documento de destino en una ubicación específica con propiedades adicionales. Los encabezados, pies de página, marcas de agua y otras propiedades de sección se copian de forma predeterminada.
load(options)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
load(propertyNames)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
load(propertyNamesAndPaths)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
save(saveBehavior, fileName)	Guarda el documento.
save(saveBehaviorString, fileName)	Guarda el documento.
search(searchText, searchOptions)	Realiza una búsqueda con las opciones de búsqueda especificadas en el ámbito de todo el documento. Los resultados de la búsqueda son una colección de objetos de intervalo.
set(properties, options)	Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto de API del mismo tipo.
set(properties)	Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.
toJSON()	Invalida el método JavaScript `toJSON()` para proporcionar una salida más útil cuando se pasa un objeto de API a `JSON.stringify()`. (`JSON.stringify`a su vez, llama al `toJSON` método del objeto que se le pasa). Mientras que el objeto original `Word.Document` es un objeto de API, el `toJSON` método devuelve un objeto JavaScript sin formato (escrito como `Word.Interfaces.DocumentData`) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.
track()	Realiza un seguimiento del objeto de ajuste automático según cambios adyacentes en el documento. Esta llamada es una abreviatura para context.trackedObjects.add(thisObject). Si usa este objeto entre `.sync` llamadas y fuera de la ejecución secuencial de un lote ".run" y obtiene un error "InvalidObjectPath" al establecer una propiedad o invocar un método en el objeto, debe agregar el objeto a la colección de objetos de seguimiento cuando se creó el objeto por primera vez. Si este objeto forma parte de una colección, también debe realizar un seguimiento de la colección primaria.
untrack()	Libere la memoria asociada a este objeto, si se ha realizado un seguimiento de él anteriormente. Esta llamada es abreviada para context.trackedObjects.remove(thisObject). Tener muchos objetos marcados ralentiza la aplicación host, así que debe recordar liberar los objetos que agregue cuando haya terminado con ellos. Tendrá que llamar `context.sync()` a antes de que la versión de memoria surta efecto.

Eventos

onAnnotationClicked	Se produce cuando el usuario hace clic en una anotación (o la selecciona con Alt+Abajo).
onAnnotationHovered	Se produce cuando el usuario mantiene el cursor sobre una anotación.
onAnnotationInserted	Se produce cuando el usuario agrega una o varias anotaciones.
onAnnotationPopupAction	Se produce cuando el usuario realiza una acción en un menú emergente de anotación.
onAnnotationRemoved	Se produce cuando el usuario elimina una o varias anotaciones.
onContentControlAdded	Se produce cuando se agrega un control de contenido. Ejecute context.sync() en el controlador para obtener las propiedades del nuevo control de contenido.
onParagraphAdded	Se produce cuando el usuario agrega nuevos párrafos.
onParagraphChanged	Se produce cuando el usuario cambia los párrafos.
onParagraphDeleted	Se produce cuando el usuario elimina párrafos.

Detalles de las propiedades

body

Obtiene el objeto body del documento principal. El cuerpo es el texto que excluye encabezados, pies de página, notas al pie, cuadros de texto, etc.

readonly body: Word.Body;

Valor de propiedad

Word.Body

Comentarios

changeTrackingMode

Especifica el modo ChangeTracking.

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

Valor de propiedad

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

Comentarios

Ejemplos

// 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

Obtiene la colección de objetos de control de contenido del documento. Esto incluye controles de contenido en el cuerpo del documento, encabezados, pies de página, cuadros de texto, etc.

readonly contentControls: Word.ContentControlCollection;

Valor de propiedad

Word.ContentControlCollection

Comentarios

context

Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.

context: RequestContext;

Valor de propiedad

Word.RequestContext

customXmlParts

Obtiene los elementos XML personalizados del documento.

readonly customXmlParts: Word.CustomXmlPartCollection;

Valor de propiedad

Word.CustomXmlPartCollection

Comentarios

properties

Obtiene las propiedades del documento.

readonly properties: Word.DocumentProperties;

Valor de propiedad

Word.DocumentProperties

Comentarios

[ Conjunto de API: WordApi 1.3 ]

Ejemplos

// 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 si se guardaron los cambios en el documento. Un valor de true indica que el documento no cambió desde que se guardó.

readonly saved: boolean;

Valor de propiedad

boolean

Comentarios

sections

Obtiene la colección de objetos de sección del documento.

readonly sections: Word.SectionCollection;

Valor de propiedad

Word.SectionCollection

Comentarios

settings

Obtiene la configuración del complemento en el documento.

readonly settings: Word.SettingCollection;

Valor de propiedad

Word.SettingCollection

Comentarios

Ejemplos

// 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]);
    }
  }
});

Detalles del método

addStyle(name, type)

Agrega un estilo al documento por nombre y tipo.

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

Parámetros

name: string

Obligatorio. Cadena que representa el nombre del estilo.

type: Word.StyleType

Obligatorio. Tipo de estilo, incluido el carácter, la lista, el párrafo o la tabla.

Devoluciones

Word.Style

Comentarios

Ejemplos

// 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)

Agrega un estilo al documento por nombre y tipo.

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

Parámetros

name: string

Obligatorio. Cadena que representa el nombre del estilo.

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

Obligatorio. Tipo de estilo, incluido el carácter, la lista, el párrafo o la tabla.

Devoluciones

Word.Style

Comentarios

close(closeBehavior)

Cierra el documento actual.

Nota: Esta API no se admite en Word en la web.

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

Parámetros

closeBehavior: Word.CloseBehavior

Opcional. El comportamiento de cierre debe ser "Guardar" o "Omitirguardar". El valor predeterminado es "Guardar".

Devoluciones

void

Comentarios

Ejemplos

// 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)

Cierra el documento actual.

Nota: Esta API no se admite en Word en la web.

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

Parámetros

closeBehaviorString: "Save" | "SkipSave"

Opcional. El comportamiento de cierre debe ser "Guardar" o "Omitirguardar". El valor predeterminado es "Guardar".

Devoluciones

void

Comentarios

[ Conjunto de API: WordApi BETA (SOLO VERSIÓN PRELIMINAR) ]

compare(filePath, documentCompareOptions)

Muestra las marcas de revisión para indicar dónde están las diferencias entre ambos documentos.

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

Parámetros

filePath: string

Obligatorio. Ruta de acceso del documento con el que se compara el documento especificado.

documentCompareOptions: Word.DocumentCompareOptions

Opcional. Opciones adicionales que especifican el comportamiento de comparar el documento.

Devoluciones

void

Comentarios

[ Conjunto de API: WordApiDesktop 1.1 ]

Ejemplos

// 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)

Nota

Esta API se ofrece a los desarrolladores como versión preliminar y puede cambiar en función de los comentarios que recibamos. No utilice esta API en un entorno de producción.

Muestra las marcas de revisión para indicar dónde están las diferencias entre ambos documentos.

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

Parámetros

base64File: string

Obligatorio. Contenido codificado en Base64 del documento con el que se compara el documento especificado.

documentCompareOptions: Word.DocumentCompareOptions

Opcional. Opciones adicionales que especifican el comportamiento para comparar los documentos. Tenga en cuenta que la compareTarget opción no puede estar CompareTargetSelected en esta API.

Devoluciones

void

Comentarios

deleteBookmark(name)

Elimina un marcador, si existe, del documento.

deleteBookmark(name: string): void;

Parámetros

name: string

Obligatorio. Nombre del marcador que no distingue mayúsculas de minúsculas.

Devoluciones

void

Comentarios

getAnnotationById(id)

Obtiene la anotación por identificador. Produce un ItemNotFound error si no se encuentra la anotación.

getAnnotationById(id: string): Word.Annotation;

Parámetros

id: string

Identificador de la anotación que se va a obtener.

Devoluciones

Word.Annotation

Comentarios

getBookmarkRange(name)

Obtiene el intervalo de un marcador. Produce un ItemNotFound error si el marcador no existe.

getBookmarkRange(name: string): Word.Range;

Parámetros

name: string

Obligatorio. Nombre del marcador que no distingue mayúsculas de minúsculas.

Devoluciones

Word.Range

Comentarios

getBookmarkRangeOrNullObject(name)

Obtiene el intervalo de un marcador. Si el marcador no existe, este método devolverá un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).

getBookmarkRangeOrNullObject(name: string): Word.Range;

Parámetros

name: string

Obligatorio. Nombre del marcador que no distingue mayúsculas de minúsculas.

Devoluciones

Word.Range

Comentarios

getContentControls(options)

Obtiene los controles de contenido admitidos actualmente en el documento.

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

Parámetros

options: Word.ContentControlOptions

Opcional. Opciones que definen qué controles de contenido se devuelven.

Devoluciones

Word.ContentControlCollection

Comentarios

Importante: Si se proporcionan tipos específicos en el parámetro options, solo se devuelven los controles de contenido de los tipos admitidos. Tenga en cuenta que se iniciará una excepción en el uso de métodos de un Word genérico. ContentControl que no son relevantes para el tipo específico. Con el tiempo, se pueden admitir tipos adicionales de controles de contenido. Por lo tanto, el complemento debe solicitar y controlar tipos específicos de controles de contenido.

Ejemplos

// 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()

Obtiene las notas al final del documento en un solo cuerpo.

getEndnoteBody(): Word.Body;

Devoluciones

Word.Body

Comentarios

getFootnoteBody()

Obtiene las notas al pie del documento en un único cuerpo.

getFootnoteBody(): Word.Body;

Devoluciones

Word.Body

Comentarios

getParagraphByUniqueLocalId(id)

Obtiene el párrafo por su identificador local único. Produce un ItemNotFound error si la colección está vacía.

getParagraphByUniqueLocalId(id: string): Word.Paragraph;

Parámetros

id: string

Obligatorio. Identificador local único en formato GUID estándar 8-4-4-4-12 sin llaves. Tenga en cuenta que el identificador difiere entre sesiones y coautores.

Devoluciones

Word.Paragraph

Comentarios

Ejemplos

// 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()

Obtiene la selección actual del documento. No se admiten varias selecciones.

getSelection(): Word.Range;

Devoluciones

Word.Range

Comentarios

Ejemplos

// 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()

Obtiene un objeto StyleCollection que representa todo el conjunto de estilos del documento.

getStyles(): Word.StyleCollection;

Devoluciones

Word.StyleCollection

Comentarios

Ejemplos

// 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 desde una cadena con formato JSON.

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

Parámetros

stylesJson: string

Obligatorio. Cadena con formato JSON que representa los estilos.

Devoluciones

OfficeExtension.ClientResult<string[]>

Comentarios

Ejemplos

// 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)

Inserta un documento en el documento de destino en una ubicación específica con propiedades adicionales. Los encabezados, pies de página, marcas de agua y otras propiedades de sección se copian de forma predeterminada.

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

Obligatorio. Contenido codificado en Base64 de un archivo .docx.

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

Obligatorio. El valor debe ser "Replace", "Start" o "End".

insertFileOptions: Word.InsertFileOptions

Opcional. Propiedades adicionales que se deben importar al documento de destino.

Devoluciones

Word.SectionCollection

Comentarios

Nota: La inserción no se admite si el documento que se está insertando contiene un control ActiveX (probablemente en un campo de formulario). Considere la posibilidad de reemplazar este tipo de campo de formulario por un control de contenido u otra opción adecuada para su escenario.

Ejemplos

// 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)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

load(options?: Word.Interfaces.DocumentLoadOptions): Word.Document;

Parámetros

options: Word.Interfaces.DocumentLoadOptions

Proporciona opciones para las propiedades del objeto que se van a cargar.

Devoluciones

Word.Document

Ejemplos

// 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)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

propertyNames: string | string[]

Una cadena delimitada por comas o una matriz de cadenas que especifican las propiedades que se van a cargar.

Devoluciones

Word.Document

load(propertyNamesAndPaths)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

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

propertyNamesAndPaths.select es una cadena delimitada por comas que especifica las propiedades que se van a cargar y propertyNamesAndPaths.expand es una cadena delimitada por comas que especifica las propiedades de navegación que se van a cargar.

Devoluciones

Word.Document

save(saveBehavior, fileName)

Guarda el documento.

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

Parámetros

saveBehavior: Word.SaveBehavior

Opcional. El comportamiento de guardado debe ser "Guardar" o "Preguntar". El valor predeterminado es "Guardar".

fileName: string

Opcional. Nombre de archivo (extensión de archivo de exclusión). Solo surte efecto para un documento nuevo.

Devoluciones

void

Comentarios

Nota: Los saveBehavior parámetros y fileName se introdujeron en WordApi 1.5.

Ejemplos

// 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)

Guarda el documento.

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

Parámetros

saveBehaviorString: "Save" | "Prompt"

Opcional. El comportamiento de guardado debe ser "Guardar" o "Preguntar". El valor predeterminado es "Guardar".

fileName: string

Opcional. Nombre de archivo (extensión de archivo de exclusión). Solo surte efecto para un documento nuevo.

Devoluciones

void

Comentarios

Nota: Los saveBehavior parámetros y fileName se introdujeron en WordApi 1.5.

search(searchText, searchOptions)

Realiza una búsqueda con las opciones de búsqueda especificadas en el ámbito de todo el documento. Los resultados de la búsqueda son una colección de objetos de intervalo.

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

Devoluciones

Word.RangeCollection

Comentarios

OfficeExtension.EventHandlers<Word.AnnotationClickedEventArgs>

set(properties, options)

Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto de API del mismo tipo.

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

Parámetros

properties: Word.Interfaces.DocumentUpdateData

Objeto JavaScript con propiedades estructuradas isomórficamente con las propiedades del objeto al que se llama al método.

options: OfficeExtension.UpdateOptions

Proporciona una opción para suprimir errores si el objeto properties intenta establecer propiedades de solo lectura.

Devoluciones

void

set(properties)

Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.

set(properties: Word.Document): void;

Parámetros

properties: Word.Document

Devoluciones

void

toJSON()

Invalida el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify(). (JSON.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto original Word.Document es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Word.Interfaces.DocumentData) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.

toJSON(): Word.Interfaces.DocumentData;

Devoluciones

Word.Interfaces.DocumentData

track()

Realiza un seguimiento del objeto de ajuste automático según cambios adyacentes en el documento. Esta llamada es una abreviatura para context.trackedObjects.add(thisObject). Si usa este objeto entre .sync llamadas y fuera de la ejecución secuencial de un lote ".run" y obtiene un error "InvalidObjectPath" al establecer una propiedad o invocar un método en el objeto, debe agregar el objeto a la colección de objetos de seguimiento cuando se creó el objeto por primera vez. Si este objeto forma parte de una colección, también debe realizar un seguimiento de la colección primaria.

track(): Word.Document;

Devoluciones

Word.Document

untrack()

Libere la memoria asociada a este objeto, si se ha realizado un seguimiento de él anteriormente. Esta llamada es abreviada para context.trackedObjects.remove(thisObject). Tener muchos objetos marcados ralentiza la aplicación host, así que debe recordar liberar los objetos que agregue cuando haya terminado con ellos. Tendrá que llamar context.sync() a antes de que la versión de memoria surta efecto.

untrack(): Word.Document;

Devoluciones

Word.Document

Detalles del evento

onAnnotationClicked

Se produce cuando el usuario hace clic en una anotación (o la selecciona con Alt+Abajo).

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

Tipo de evento

Comentarios

OfficeExtension.EventHandlers<Word.AnnotationHoveredEventArgs>

Ejemplos

// 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

Se produce cuando el usuario mantiene el cursor sobre una anotación.

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

Tipo de evento

Comentarios

OfficeExtension.EventHandlers<Word.AnnotationInsertedEventArgs>

Ejemplos

// 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

Se produce cuando el usuario agrega una o varias anotaciones.

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

Tipo de evento

Comentarios

OfficeExtension.EventHandlers<Word.AnnotationPopupActionEventArgs>

Ejemplos

// 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

Se produce cuando el usuario realiza una acción en un menú emergente de anotación.

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

Tipo de evento

Comentarios

[ Conjunto de API: WordApi 1.8 ]

Ejemplos

// 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

Se produce cuando el usuario elimina una o varias anotaciones.

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

Tipo de evento

OfficeExtension.EventHandlers<Word.AnnotationRemovedEventArgs>

Comentarios

OfficeExtension.EventHandlers<Word.ContentControlAddedEventArgs>

Ejemplos

// 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

Se produce cuando se agrega un control de contenido. Ejecute context.sync() en el controlador para obtener las propiedades del nuevo control de contenido.

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

Tipo de evento

Comentarios

OfficeExtension.EventHandlers<Word.ParagraphAddedEventArgs>

Ejemplos

// 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

Se produce cuando el usuario agrega nuevos párrafos.

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

Tipo de evento

Comentarios

OfficeExtension.EventHandlers<Word.ParagraphChangedEventArgs>

Ejemplos

// 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

Se produce cuando el usuario cambia los párrafos.

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

Tipo de evento

Comentarios

OfficeExtension.EventHandlers<Word.ParagraphDeletedEventArgs>

Ejemplos

// 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

Se produce cuando el usuario elimina párrafos.

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

Tipo de evento

Comentarios