Word. Document class

Exemples

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

Propriétés

body	Obtient l’objet body du document main. Le corps est le texte qui exclut les en-têtes, les pieds de page, les notes de bas de page, les zones de texte, etc.
changeTrackingMode	Spécifie le mode ChangeTracking.
contentControls	Obtient la collection d’objets de contrôle de contenu dans le document. Cela inclut les contrôles de contenu dans le corps du document, les en-têtes, les pieds de page, les zones de texte, etc.
context	Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.
customXmlParts	Obtient les parties XML personnalisées dans le document.
properties	Obtient les propriétés du document.
saved	Indique si les modifications apportées au document ont été enregistrées. La valeur true indique que le document n’a pas été modifié depuis son enregistrement.
sections	Obtient la collection d’objets de section dans le document.
settings	Obtient les paramètres du complément dans le document.

Méthodes

addStyle(name, type)	Ajoute un style dans le document par nom et par type.
addStyle(name, typeString)	Ajoute un style dans le document par nom et par type.
close(closeBehavior)	Ferme le document actif. Remarque : cette API n’est pas prise en charge dans Word sur le web.
close(closeBehaviorString)	Ferme le document actif. Remarque : cette API n’est pas prise en charge dans Word sur le web.
deleteBookmark(name)	Supprime un signet, s’il existe, du document.
getAnnotationById(id)	Obtient l’annotation par ID. Génère une `ItemNotFound` erreur si l’annotation est introuvable.
getBookmarkRange(name)	Obtient la plage d’un signet. Génère une `ItemNotFound` erreur si le signet n’existe pas.
getBookmarkRangeOrNullObject(name)	Obtient la plage d’un signet. Si le signet n’existe pas, cette méthode retourne un objet avec sa `isNullObject` propriété définie sur `true`. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.
getContentControls(options)	Obtient les contrôles de contenu actuellement pris en charge dans le document.
getEndnoteBody()	Obtient les notes de fin du document dans un corps unique.
getFootnoteBody()	Obtient les notes de bas de page du document dans un seul corps.
getParagraphByUniqueLocalId(id)	Obtient le paragraphe par son ID local unique. Génère une `ItemNotFound` erreur si la collection est vide.
getSelection()	Obtient la sélection actuelle du document. Les sélections multiples ne sont pas prises en charge.
getStyles()	Obtient un objet StyleCollection qui représente l’ensemble du jeu de styles du document.
importStylesFromJson(stylesJson, importedStylesConflictBehavior)	Importer des styles à partir d’une chaîne au format JSON.
importStylesFromJson(stylesJson, importedStylesConflictBehaviorString)	Importer des styles à partir d’une chaîne au format JSON.
insertFileFromBase64(base64File, insertLocation, insertFileOptions)	Insère un document dans le document cible à un emplacement spécifique avec des propriétés supplémentaires. Les en-têtes, pieds de page, filigranes et autres propriétés de section sont copiés par défaut.
load(options)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
load(propertyNames)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
load(propertyNamesAndPaths)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
save(saveBehavior, fileName)	Enregistre le document.
save(saveBehaviorString, fileName)	Enregistre le document.
search(searchText, searchOptions)	Effectue une recherche avec les options de recherche spécifiées sur l’étendue de l’ensemble du document. Les résultats de la recherche sont un ensemble d’objets de plage.
set(properties, options)	Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.
set(properties)	Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.
toJSON()	Remplace la méthode JavaScript `toJSON()` afin de fournir une sortie plus utile lorsqu’un objet API est passé à `JSON.stringify()`. (`JSON.stringify`, à son tour, appelle la `toJSON` méthode de l’objet qui lui est passé.) Alors que l’objet d’origine `Word.Document` est un objet API, la `toJSON` méthode renvoie un objet JavaScript brut (typé en tant `Word.Interfaces.DocumentData`que ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.
track()	Effectuer le suivi de l’objet pour l’ajustement automatique en fonction environnant des modifications dans le document. Cet appel est un raccourci pour context.trackedObjects.add(thisObject). Si vous utilisez cet objet sur des `.sync` appels et en dehors de l’exécution séquentielle d’un lot « .run », et que vous obtenez une erreur « InvalidObjectPath » lors de la définition d’une propriété ou de l’appel d’une méthode sur l’objet, vous devez ajouter l’objet à la collection d’objets suivie lors de la première création de l’objet. Si cet objet fait partie d’une collection, vous devez également suivre la collection parente.
untrack()	Publication mémoire associée à cet objet si elle a été précédemment suivie. Cet appel est abrégé pour context.trackedObjects.remove(thisObject). Vous rencontrez de nombreux objets suivies ralentit l’application hôte, donc n’oubliez pas de libérer les objets que l'on ajoute, une fois que vous avez terminé à les utiliser. Vous devez appeler `context.sync()` avant que la mise en production de la mémoire ne prenne effet.

Événements

onAnnotationClicked	Se produit lorsque l’utilisateur clique sur une annotation (ou la sélectionne à l’aide de Alt+Bas).
onAnnotationHovered	Se produit lorsque l’utilisateur place le curseur sur une annotation.
onAnnotationInserted	Se produit lorsque l’utilisateur ajoute une ou plusieurs annotations.
onAnnotationPopupAction	Se produit lorsque l’utilisateur effectue une action dans un menu contextuel d’annotation.
onAnnotationRemoved	Se produit lorsque l’utilisateur supprime une ou plusieurs annotations.
onContentControlAdded	Se produit lorsqu’un contrôle de contenu est ajouté. Exécutez context.sync() dans le gestionnaire pour obtenir les propriétés du nouveau contrôle de contenu.
onParagraphAdded	Se produit lorsque l’utilisateur ajoute de nouveaux paragraphes.
onParagraphChanged	Se produit lorsque l’utilisateur modifie des paragraphes.
onParagraphDeleted	Se produit lorsque l’utilisateur supprime des paragraphes.

Détails de la propriété

body

Obtient l’objet body du document main. Le corps est le texte qui exclut les en-têtes, les pieds de page, les notes de bas de page, les zones de texte, etc.

readonly body: Word.Body;

Valeur de propriété

Word.Body

Remarques

changeTrackingMode

Spécifie le mode ChangeTracking.

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

Valeur de propriété

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

Remarques

Exemples

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

Obtient la collection d’objets de contrôle de contenu dans le document. Cela inclut les contrôles de contenu dans le corps du document, les en-têtes, les pieds de page, les zones de texte, etc.

readonly contentControls: Word.ContentControlCollection;

Valeur de propriété

Word.ContentControlCollection

Remarques

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

context: RequestContext;

Valeur de propriété

Word.RequestContext

customXmlParts

Obtient les parties XML personnalisées dans le document.

readonly customXmlParts: Word.CustomXmlPartCollection;

Valeur de propriété

Word.CustomXmlPartCollection

Remarques

properties

Obtient les propriétés du document.

readonly properties: Word.DocumentProperties;

Valeur de propriété

Word.DocumentProperties

Remarques

[ Ensemble d’API : WordApi 1.3 ]

Exemples

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

Indique si les modifications apportées au document ont été enregistrées. La valeur true indique que le document n’a pas été modifié depuis son enregistrement.

readonly saved: boolean;

Valeur de propriété

boolean

Remarques

sections

Obtient la collection d’objets de section dans le document.

readonly sections: Word.SectionCollection;

Valeur de propriété

Word.SectionCollection

Remarques

settings

Obtient les paramètres du complément dans le document.

readonly settings: Word.SettingCollection;

Valeur de propriété

Word.SettingCollection

Remarques

Exemples

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

Détails de la méthode

addStyle(name, type)

Ajoute un style dans le document par nom et par type.

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

Paramètres

name: string

Obligatoire. Chaîne représentant le nom du style.

type: Word.StyleType

Obligatoire. Type de style, y compris caractère, liste, paragraphe ou tableau.

Retours

Word.Style

Remarques

Exemples

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

Ajoute un style dans le document par nom et par type.

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

Paramètres

name: string

Obligatoire. Chaîne représentant le nom du style.

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

Obligatoire. Type de style, y compris caractère, liste, paragraphe ou tableau.

Retours

Word.Style

Remarques

close(closeBehavior)

Ferme le document actif.

Remarque : cette API n’est pas prise en charge dans Word sur le web.

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

Paramètres

closeBehavior: Word.CloseBehavior

Optional. Le comportement de fermeture doit être « Enregistrer » ou « SkipSave ». La valeur par défaut est « Save ».

Retours

void

Remarques

Exemples

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

Ferme le document actif.

Remarque : cette API n’est pas prise en charge dans Word sur le web.

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

Paramètres

closeBehaviorString: "Save" | "SkipSave"

Optional. Le comportement de fermeture doit être « Enregistrer » ou « SkipSave ». La valeur par défaut est « Save ».

Retours

void

Remarques

deleteBookmark(name)

Supprime un signet, s’il existe, du document.

deleteBookmark(name: string): void;

Paramètres

name: string

Obligatoire. Nom de signet qui ne respecte pas la casse.

Retours

void

Remarques

getAnnotationById(id)

Obtient l’annotation par ID. Génère une ItemNotFound erreur si l’annotation est introuvable.

getAnnotationById(id: string): Word.Annotation;

Paramètres

id: string

ID de l’annotation à obtenir.

Retours

Word.Annotation

Remarques

getBookmarkRange(name)

Obtient la plage d’un signet. Génère une ItemNotFound erreur si le signet n’existe pas.

getBookmarkRange(name: string): Word.Range;

Paramètres

name: string

Obligatoire. Nom de signet qui ne respecte pas la casse.

Retours

Word.Range

Remarques

getBookmarkRangeOrNullObject(name)

Obtient la plage d’un signet. Si le signet n’existe pas, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getBookmarkRangeOrNullObject(name: string): Word.Range;

Paramètres

name: string

Obligatoire. Nom de signet qui ne respecte pas la casse.

Retours

Word.Range

Remarques

getContentControls(options)

Obtient les contrôles de contenu actuellement pris en charge dans le document.

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

Paramètres

options: Word.ContentControlOptions

Optional. Options qui définissent les contrôles de contenu qui sont retournés.

Retours

Word.ContentControlCollection

Remarques

Important : si des types spécifiques sont fournis dans le paramètre options, seuls les contrôles de contenu des types pris en charge sont retournés. N’oubliez pas qu’une exception sera levée à l’aide de méthodes d’un Word générique. ContentControl qui ne sont pas pertinents pour le type spécifique. Avec le temps, d’autres types de contrôles de contenu peuvent être pris en charge. Par conséquent, votre complément doit demander et gérer des types spécifiques de contrôles de contenu.

Exemples

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

Obtient les notes de fin du document dans un corps unique.

getEndnoteBody(): Word.Body;

Retours

Word.Body

Remarques

getFootnoteBody()

Obtient les notes de bas de page du document dans un seul corps.

getFootnoteBody(): Word.Body;

Retours

Word.Body

Remarques

getParagraphByUniqueLocalId(id)

Obtient le paragraphe par son ID local unique. Génère une ItemNotFound erreur si la collection est vide.

getParagraphByUniqueLocalId(id: string): Word.Paragraph;

Paramètres

id: string

Obligatoire. ID local unique au format GUID 8-4-4-4-12 standard sans accolades. Notez que l’ID diffère entre les sessions et les co-auteurs.

Retours

Word.Paragraph

Remarques

Exemples

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

Obtient la sélection actuelle du document. Les sélections multiples ne sont pas prises en charge.

getSelection(): Word.Range;

Retours

Word.Range

Remarques

Exemples

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

Obtient un objet StyleCollection qui représente l’ensemble du jeu de styles du document.

getStyles(): Word.StyleCollection;

Retours

Word.StyleCollection

Remarques

Exemples

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

Importer des styles à partir d’une chaîne au format JSON.

importStylesFromJson(stylesJson: string, importedStylesConflictBehavior?: Word.ImportedStylesConflictBehavior): OfficeExtension.ClientResult<string[]>;

Paramètres

stylesJson: string

Obligatoire. Chaîne au format JSON représentant les styles.

importedStylesConflictBehavior: Word.ImportedStylesConflictBehavior

Optional. Spécifie comment gérer les styles importés portant le même nom que les styles existants dans le document actif.

Retours

OfficeExtension.ClientResult<string[]>

Remarques

Remarque : Le importedStylesConflictBehavior paramètre a été introduit dans WordApiDesktop 1.1.

Exemples

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

importStylesFromJson(stylesJson, importedStylesConflictBehaviorString)

Importer des styles à partir d’une chaîne au format JSON.

importStylesFromJson(stylesJson: string, importedStylesConflictBehaviorString?: "Ignore" | "Overwrite" | "CreateNew"): OfficeExtension.ClientResult<string[]>;

Paramètres

stylesJson: string

Obligatoire. Chaîne au format JSON représentant les styles.

importedStylesConflictBehaviorString: "Ignore" | "Overwrite" | "CreateNew"

Optional. Spécifie comment gérer les styles importés portant le même nom que les styles existants dans le document actif.

Retours

OfficeExtension.ClientResult<string[]>

Remarques

Remarque : Le importedStylesConflictBehavior paramètre a été introduit dans WordApiDesktop 1.1.

insertFileFromBase64(base64File, insertLocation, insertFileOptions)

Insère un document dans le document cible à un emplacement spécifique avec des propriétés supplémentaires. Les en-têtes, pieds de page, filigranes et autres propriétés de section sont copiés par défaut.

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

Paramètres

base64File: string

Obligatoire. Contenu encodé en Base64 d’un fichier .docx.

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

Obligatoire. La valeur doit être « Replace », « Start » ou « End ».

insertFileOptions: Word.InsertFileOptions

Optional. Propriétés supplémentaires qui doivent être importées dans le document de destination.

Retours

Word.SectionCollection

Remarques

Remarque : l’insertion n’est pas prise en charge si le document inséré contient un contrôle ActiveX (probablement dans un champ de formulaire). Envisagez de remplacer un tel champ de formulaire par un contrôle de contenu ou une autre option appropriée pour votre scénario.

Exemples

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

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

options: Word.Interfaces.DocumentLoadOptions

Fournit des options pour les propriétés de l’objet à charger.

Retours

Word.Document

Exemples

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

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

propertyNames: string | string[]

Chaîne délimitée par des virgules ou tableau de chaînes qui spécifient les propriétés à charger.

Retours

Word.Document

load(propertyNamesAndPaths)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

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

propertyNamesAndPaths.select est une chaîne délimitée par des virgules qui spécifie les propriétés à charger, et propertyNamesAndPaths.expand est une chaîne délimitée par des virgules qui spécifie les propriétés de navigation à charger.

Retours

Word.Document

save(saveBehavior, fileName)

Enregistre le document.

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

Paramètres

saveBehavior: Word.SaveBehavior

Optional. Le comportement d’enregistrement doit être « Enregistrer » ou « Demander ». La valeur par défaut est « Save ».

fileName: string

Optional. Nom de fichier (exclure l’extension de fichier). Prend effet uniquement pour un nouveau document.

Retours

void

Remarques

Remarque : Les saveBehavior paramètres et fileName ont été introduits dans WordApi 1.5.

Exemples

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

Enregistre le document.

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

Paramètres

saveBehaviorString: "Save" | "Prompt"

Optional. Le comportement d’enregistrement doit être « Enregistrer » ou « Demander ». La valeur par défaut est « Save ».

fileName: string

Optional. Nom de fichier (exclure l’extension de fichier). Prend effet uniquement pour un nouveau document.

Retours

void

Remarques

Remarque : Les saveBehavior paramètres et fileName ont été introduits dans WordApi 1.5.

search(searchText, searchOptions)

Effectue une recherche avec les options de recherche spécifiées sur l’étendue de l’ensemble du document. Les résultats de la recherche sont un ensemble d’objets de plage.

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

Paramètres

searchText: string

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

Retours

Word.RangeCollection

Remarques

OfficeExtension.EventHandlers<Word.AnnotationClickedEventArgs>

set(properties, options)

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.

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

Paramètres

properties: Word.Interfaces.DocumentUpdateData

Objet JavaScript avec des propriétés qui sont structurées isomorphes en fonction des propriétés de l’objet sur lequel la méthode est appelée.

options: OfficeExtension.UpdateOptions

Fournit une option permettant de supprimer les erreurs si l’objet properties tente de définir des propriétés en lecture seule.

Retours

void

set(properties)

Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.

set(properties: Word.Document): void;

Paramètres

properties: Word.Document

Retours

void

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringify, à son tour, appelle la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine Word.Document est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Word.Interfaces.DocumentDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

toJSON(): Word.Interfaces.DocumentData;

Retours

Word.Interfaces.DocumentData

track()

Effectuer le suivi de l’objet pour l’ajustement automatique en fonction environnant des modifications dans le document. Cet appel est un raccourci pour context.trackedObjects.add(thisObject). Si vous utilisez cet objet sur des .sync appels et en dehors de l’exécution séquentielle d’un lot « .run », et que vous obtenez une erreur « InvalidObjectPath » lors de la définition d’une propriété ou de l’appel d’une méthode sur l’objet, vous devez ajouter l’objet à la collection d’objets suivie lors de la première création de l’objet. Si cet objet fait partie d’une collection, vous devez également suivre la collection parente.

track(): Word.Document;

Retours

Word.Document

untrack()

Publication mémoire associée à cet objet si elle a été précédemment suivie. Cet appel est abrégé pour context.trackedObjects.remove(thisObject). Vous rencontrez de nombreux objets suivies ralentit l’application hôte, donc n’oubliez pas de libérer les objets que l'on ajoute, une fois que vous avez terminé à les utiliser. Vous devez appeler context.sync() avant que la mise en production de la mémoire ne prenne effet.

untrack(): Word.Document;

Retours

Word.Document

Détails de l'événement

onAnnotationClicked

Se produit lorsque l’utilisateur clique sur une annotation (ou la sélectionne à l’aide de Alt+Bas).

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

Type d'événement

Remarques

OfficeExtension.EventHandlers<Word.AnnotationHoveredEventArgs>

Exemples

// 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 produit lorsque l’utilisateur place le curseur sur une annotation.

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

Type d'événement

Remarques

OfficeExtension.EventHandlers<Word.AnnotationInsertedEventArgs>

Exemples

// 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 produit lorsque l’utilisateur ajoute une ou plusieurs annotations.

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

Type d'événement

Remarques

OfficeExtension.EventHandlers<Word.AnnotationPopupActionEventArgs>

Exemples

// 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 produit lorsque l’utilisateur effectue une action dans un menu contextuel d’annotation.

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

Type d'événement

Remarques

[ Ensemble d’API : WordApi 1.8 ]

Exemples

// 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 produit lorsque l’utilisateur supprime une ou plusieurs annotations.

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

Type d'événement

OfficeExtension.EventHandlers<Word.AnnotationRemovedEventArgs>

Remarques

OfficeExtension.EventHandlers<Word.ContentControlAddedEventArgs>

Exemples

// 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 produit lorsqu’un contrôle de contenu est ajouté. Exécutez context.sync() dans le gestionnaire pour obtenir les propriétés du nouveau contrôle de contenu.

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

Type d'événement

Remarques

OfficeExtension.EventHandlers<Word.ParagraphAddedEventArgs>

Exemples

// 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 produit lorsque l’utilisateur ajoute de nouveaux paragraphes.

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

Type d'événement

Remarques

OfficeExtension.EventHandlers<Word.ParagraphChangedEventArgs>

Exemples

// 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 produit lorsque l’utilisateur modifie des paragraphes.

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

Type d'événement

Remarques

OfficeExtension.EventHandlers<Word.ParagraphDeletedEventArgs>

Exemples

// 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 produit lorsque l’utilisateur supprime des paragraphes.

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

Type d'événement

Remarques