Partager via


Word.Document class

L’objet Document est l’objet de niveau supérieur. Un objet Document comporte des sections, des contrôles de contenu et le corps dans lequel se trouve le contenu du document.

Extends

Remarques

[ Ensemble d’API : WordApi 1.1 ]

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.

compare(filePath, documentCompareOptions)

Affiche des marques de révision qui indiquent en quoi le document spécifié diffère d'un autre document.

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)

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.DocumentDataque ) 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é

Remarques

[ Ensemble d’API : WordApi 1.1 ]

changeTrackingMode

Spécifie le mode ChangeTracking.

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

Valeur de propriété

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

Remarques

[ Ensemble d’API : WordApi 1.4 ]

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é

Remarques

[ Ensemble d’API : WordApi 1.1 ]

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é

customXmlParts

Obtient les parties XML personnalisées dans le document.

readonly customXmlParts: Word.CustomXmlPartCollection;

Valeur de propriété

Remarques

[ Ensemble d’API : WordApi 1.4 ]

properties

Obtient les propriétés du document.

readonly properties: Word.DocumentProperties;

Valeur de propriété

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

[ Ensemble d’API : WordApi 1.1 ]

sections

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

readonly sections: Word.SectionCollection;

Valeur de propriété

Remarques

[ Ensemble d’API : WordApi 1.1 ]

settings

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

readonly settings: Word.SettingCollection;

Valeur de propriété

Remarques

[ Ensemble d’API : WordApi 1.4 ]

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

Remarques

[ Ensemble d’API : WordApi 1.5 ]

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

Remarques

[ Ensemble d’API : WordApi 1.5 ]

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

[ Ensemble d’API : WordApi 1.5 ]

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

[ Ensemble d’API : WordApi 1.5 ]

compare(filePath, documentCompareOptions)

Affiche des marques de révision qui indiquent en quoi le document spécifié diffère d'un autre document.

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

Paramètres

filePath

string

Obligatoire. Chemin d’accès du document avec lequel le document spécifié est comparé.

documentCompareOptions
Word.DocumentCompareOptions

Optional. Options supplémentaires qui spécifient le comportement de comparaison de document.

Retours

void

Remarques

[ Ensemble d’API : WordApiDesktop 1.1 ]

Exemples

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

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

[ Ensemble d’API : WordApi 1.4 ]

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

Remarques

[ Ensemble d’API : WordApi 1.7 ]

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

Remarques

[ Ensemble d’API : WordApi 1.4 ]

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

Remarques

[ Ensemble d’API : WordApi 1.4 ]

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

Remarques

[ Ensemble d’API : WordApi 1.5 ]

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

Remarques

[ Ensemble d’API : WordApi 1.5 ]

getFootnoteBody()

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

getFootnoteBody(): Word.Body;

Retours

Remarques

[ Ensemble d’API : WordApi 1.5 ]

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

Remarques

[ Ensemble d’API : WordApi 1.6 ]

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

Remarques

[ Ensemble d’API : WordApi 1.1 ]

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

Remarques

[ Ensemble d’API : WordApi 1.5 ]

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)

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

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

Paramètres

stylesJson

string

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

Retours

Remarques

[ Ensemble d’API : WordApi 1.6 ]

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

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

Remarques

[ Ensemble d’API : WordApi 1.5 ]

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

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

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

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

[ Ensemble d’API : WordApi 1.1 ]

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

[ Ensemble d’API : WordApi 1.1 ]

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

Remarques

[ Ensemble d’API : WordApi 1.7 ]

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

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

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

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

[ Ensemble d’API : WordApi 1.7 ]

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

[ Ensemble d’API : WordApi 1.7 ]

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

[ Ensemble d’API : WordApi 1.7 ]

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

Remarques

[ Ensemble d’API : WordApi 1.7 ]

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

[ Ensemble d’API : WordApi 1.5 ]

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

[ Ensemble d’API : WordApi 1.6 ]

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

[ Ensemble d’API : WordApi 1.6 ]

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

[ Ensemble d’API : WordApi 1.6 ]

Exemples

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

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

  console.log("Added event handlers for when paragraphs are deleted.");
});

...

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