Partager via

Word.ContentControl class

  • Référence
Paquet:
word

Représente un contrôle de contenu. Les contrôles de contenu sont des zones d’un document délimitées par des bordures et pouvant porter une étiquette qui servent à contenir certains types de contenu. Les contrôles de contenu individuels peuvent contenir des images, des tableaux ou des paragraphes de texte mis en forme. Actuellement, seuls les contrôles de texte enrichi, de texte brut et de contenu de case à cocher sont pris en charge.

Extends
OfficeExtension.ClientObject

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;

    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to load the properties on the first content control.
        contentControls.items[0].load(  'appearance,' +
                                        'cannotDelete,' +
                                        'cannotEdit,' +
                                        'color,' +
                                        'id,' +
                                        'placeHolderText,' +
                                        'removeWhenEdited,' +
                                        'title,' +
                                        'text,' +
                                        'type,' +
                                        'style,' +
                                        'tag,' +
                                        'font/size,' +
                                        'font/name,' +
                                        'font/color');

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Property values of the first content control:' +
            '   ----- appearance: ' + contentControls.items[0].appearance +
            '   ----- cannotDelete: ' + contentControls.items[0].cannotDelete +
            '   ----- cannotEdit: ' + contentControls.items[0].cannotEdit +
            '   ----- color: ' + contentControls.items[0].color +
            '   ----- id: ' + contentControls.items[0].id +
            '   ----- placeHolderText: ' + contentControls.items[0].placeholderText +
            '   ----- removeWhenEdited: ' + contentControls.items[0].removeWhenEdited +
            '   ----- title: ' + contentControls.items[0].title +
            '   ----- text: ' + contentControls.items[0].text +
            '   ----- type: ' + contentControls.items[0].type +
            '   ----- style: ' + contentControls.items[0].style +
            '   ----- tag: ' + contentControls.items[0].tag +
            '   ----- font size: ' + contentControls.items[0].font.size +
            '   ----- font name: ' + contentControls.items[0].font.name +
            '   ----- font color: ' + contentControls.items[0].font.color);
    }
});

Propriétés

appearance

Spécifie l’apparence du contrôle de contenu. La valeur peut être « BoundingBox », « Tags » ou « Hidden ».
cannotDelete

Spécifie une valeur qui indique si l’utilisateur peut supprimer le contrôle de contenu. Non compatible avec removeWhenEdited.
cannotEdit

Spécifie une valeur qui indique si l’utilisateur peut modifier le contenu du contrôle de contenu.
color

Spécifie la couleur du contrôle de contenu. La couleur est spécifiée au format « #RRGGBB » ou à l’aide du nom de la couleur.
contentControls

Obtient la collection d’objets de contrôle de contenu compris dans le contrôle de contenu.
context

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

Obtient le format de texte du contrôle de contenu. Utilisez cette propriété pour obtenir et définir le nom de la police, la taille, la couleur et d’autres propriétés.
id

Obtient un entier qui représente l’identificateur du contrôle de contenu.
inlinePictures

Obtient la collection d’objets InlinePicture dans le contrôle de contenu. La collection n’inclut pas d’images flottantes.
paragraphs

Obtient la collection d’objets de paragraphe dans le contrôle de contenu.
parentContentControl

Obtient le contrôle de contenu qui contient le contrôle de contenu spécifié. Génère une ItemNotFound erreur s’il n’existe pas de contrôle de contenu parent.
placeholderText

Spécifie le texte de l’espace réservé du contrôle de contenu. Ce texte apparaît de façon estompée lorsque le contrôle de contenu est vide.
removeWhenEdited

Spécifie une valeur qui indique si le contrôle de contenu est supprimé après sa modification. Non compatible avec cannotDelete.
style

Spécifie le nom du style pour le contrôle de contenu. Utilisez cette propriété pour les noms des styles personnalisés et localisés. Pour utiliser les styles prédéfinis qui sont portables entre différents paramètres régionaux, voir la propriété « styleBuiltIn ».
tag

Spécifie une balise pour identifier un contrôle de contenu.
text

Obtient le texte du contrôle de contenu.
title

Spécifie le titre d’un contrôle de contenu.
type

Obtient le type du contrôle de contenu. Seuls les contrôles de texte enrichi, de texte brut et de contenu de case à cocher sont actuellement pris en charge.

Méthodes

clear()

Efface le contenu du contrôle de contenu. L’utilisateur peut effectuer l’opération d’annulation sur le contenu effacé.
delete(keepContent)

Supprime le contrôle de contenu et son contenu. Si keepContent a la valeur true, le contenu n’est pas supprimé.
getHtml()

Obtient une représentation HTML de l’objet de contrôle de contenu. En cas de rendu dans une page web ou une visionneuse HTML, la mise en forme correspond à une correspondance proche, mais pas exacte, pour la mise en forme du document. Cette méthode ne retourne pas exactement le même code HTML pour le même document sur différentes plateformes (Windows, Mac, Word sur le web, etc.). Si vous avez besoin d’une fidélité exacte ou d’une cohérence entre les plateformes, utilisez ContentControl.getOoxml() et convertissez le code XML retourné au format HTML.
getOoxml()

Obtient la représentation Office Open XML (OOXML) de l’objet de contrôle de contenu.
insertBreak(breakType, insertLocation)

Insère un saut à l’emplacement spécifié du document principal. Cette méthode ne peut pas être utilisée avec les contrôles de contenu « RichTextTable », « RichTextTableRow » et « RichTextTableCell ».
insertFileFromBase64(base64File, insertLocation)

Insère un document dans le contrôle de contenu à l’emplacement spécifié.
insertHtml(html, insertLocation)

Insère du code HTML dans le contrôle de contenu, à l’emplacement spécifié.
insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

Insère une image incluse dans le contrôle de contenu, à l’emplacement spécifié.
insertOoxml(ooxml, insertLocation)

Insère OOXML dans le contrôle de contenu à l’emplacement spécifié.
insertParagraph(paragraphText, insertLocation)

Insère un paragraphe à l’emplacement spécifié.
insertText(text, insertLocation)

Insère du texte dans le contrôle de contenu, à l’emplacement spécifié.
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.
search(searchText, searchOptions)

Effectue une recherche avec les SearchOptions spécifiés dans l’étendue de l’objet de contrôle de contenu. Les résultats de la recherche sont un ensemble d’objets de plage.
select(selectionMode)

Sélectionne le contrôle de contenu. Word fait défiler le document jusqu’à accéder à la sélection.
select(selectionModeString)

Sélectionne le contrôle de contenu. Word fait défiler le document jusqu’à accéder à la sélection.
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.ContentControl est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Word.Interfaces.ContentControlDataque ) 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.

Détails de la propriété

appearance

Spécifie l’apparence du contrôle de contenu. La valeur peut être « BoundingBox », « Tags » ou « Hidden ».

appearance: Word.ContentControlAppearance | "BoundingBox" | "Tags" | "Hidden";

Valeur de propriété

Word.ContentControlAppearance | "BoundingBox" | "Tags" | "Hidden"

Remarques

[ Ensemble d’API : WordApi 1.1 ]

cannotDelete

Spécifie une valeur qui indique si l’utilisateur peut supprimer le contrôle de contenu. Non compatible avec removeWhenEdited.

cannotDelete: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : WordApi 1.1 ]

cannotEdit

Spécifie une valeur qui indique si l’utilisateur peut modifier le contenu du contrôle de contenu.

cannotEdit: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : WordApi 1.1 ]

color

Spécifie la couleur du contrôle de contenu. La couleur est spécifiée au format « #RRGGBB » ou à l’aide du nom de la couleur.

color: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : WordApi 1.1 ]

contentControls

Obtient la collection d’objets de contrôle de contenu compris dans le contrôle de contenu.

readonly contentControls: Word.ContentControlCollection;

Valeur de propriété

Word.ContentControlCollection

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é

Word.RequestContext

font

Obtient le format de texte du contrôle de contenu. Utilisez cette propriété pour obtenir et définir le nom de la police, la taille, la couleur et d’autres propriétés.

readonly font: Word.Font;

Valeur de propriété

Word.Font

Remarques

[ Ensemble d’API : WordApi 1.1 ]

id

Obtient un entier qui représente l’identificateur du contrôle de contenu.

readonly id: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : WordApi 1.1 ]

inlinePictures

Obtient la collection d’objets InlinePicture dans le contrôle de contenu. La collection n’inclut pas d’images flottantes.

readonly inlinePictures: Word.InlinePictureCollection;

Valeur de propriété

Word.InlinePictureCollection

Remarques

[ Ensemble d’API : WordApi 1.1 ]

paragraphs

Obtient la collection d’objets de paragraphe dans le contrôle de contenu.

readonly paragraphs: Word.ParagraphCollection;

Valeur de propriété

Word.ParagraphCollection

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Important : Pour les ensembles de conditions requises 1.1 et 1.2, les paragraphes des tables entièrement contenus dans ce contrôle de contenu ne sont pas retournés. À partir de l’ensemble de conditions requises 1.3, les paragraphes de ces tableaux sont également retournés.

parentContentControl

Obtient le contrôle de contenu qui contient le contrôle de contenu spécifié. Génère une ItemNotFound erreur s’il n’existe pas de contrôle de contenu parent.

readonly parentContentControl: Word.ContentControl;

Valeur de propriété

Word.ContentControl

Remarques

[ Ensemble d’API : WordApi 1.1 ]

placeholderText

Spécifie le texte de l’espace réservé du contrôle de contenu. Ce texte apparaît de façon estompée lorsque le contrôle de contenu est vide.

placeholderText: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : WordApi 1.1 ]

removeWhenEdited

Spécifie une valeur qui indique si le contrôle de contenu est supprimé après sa modification. Non compatible avec cannotDelete.

removeWhenEdited: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : WordApi 1.1 ]

style

Spécifie le nom du style pour le contrôle de contenu. Utilisez cette propriété pour les noms des styles personnalisés et localisés. Pour utiliser les styles prédéfinis qui sont portables entre différents paramètres régionaux, voir la propriété « styleBuiltIn ».

style: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : WordApi 1.1 ]

tag

Spécifie une balise pour identifier un contrôle de contenu.

tag: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

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

// Traverses each paragraph of the document and wraps a content control on each with either a even or odd tags.
await Word.run(async (context) => {
  let paragraphs = context.document.body.paragraphs;
  paragraphs.load("$none"); // Don't need any properties; just wrap each paragraph with a content control.

  await context.sync();

  for (let i = 0; i < paragraphs.items.length; i++) {
    let contentControl = paragraphs.items[i].insertContentControl();
    // For even, tag "even".
    if (i % 2 === 0) {
      contentControl.tag = "even";
    } else {
      contentControl.tag = "odd";
    }
  }
  console.log("Content controls inserted: " + paragraphs.items.length);

  await context.sync();
});

text

Obtient le texte du contrôle de contenu.

readonly text: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : WordApi 1.1 ]

title

Spécifie le titre d’un contrôle de contenu.

title: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : WordApi 1.1 ]

type

Obtient le type du contrôle de contenu. Seuls les contrôles de texte enrichi, de texte brut et de contenu de case à cocher sont actuellement pris en charge.

readonly type: Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText";

Valeur de propriété

Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText"

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Détails de la méthode

clear()

Efface le contenu du contrôle de contenu. L’utilisateur peut effectuer l’opération d’annulation sur le contenu effacé.

clear(): void;

Retours

void

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the content controls collection.
    contentControls.load('text');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        
    if (contentControls.items.length === 0) {
        console.log("There isn't a content control in this document.");
    } else {
        // Queue a command to clear the contents of the first content control.
        contentControls.items[0].clear();

        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control cleared of contents.');
    }
});

delete(keepContent)

Supprime le contrôle de contenu et son contenu. Si keepContent a la valeur true, le contenu n’est pas supprimé.

delete(keepContent: boolean): void;

Paramètres

keepContent

boolean

Obligatoire. Indique si le contenu doit être supprimé avec le contrôle de contenu. Si keepContent a la valeur true, le contenu n’est pas supprimé.

Retours

void

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the content controls collection.
    contentControls.load('text');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        
    if (contentControls.items.length === 0) {
        console.log("There isn't a content control in this document.");
    } else {            
        // Queue a command to delete the first content control. 
        // The contents will remain in the document.
        contentControls.items[0].delete(true);

        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control cleared of contents.'); 
    }
});

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

await Word.run(async (context) => {
  const contentControls: Word.ContentControlCollection = context.document.contentControls.getByTag("forTesting");
  contentControls.load("items");
  await context.sync();

  if (contentControls.items.length === 0) {
    console.log("There are no content controls in this document.");
  } else {
    console.log("Control to be deleted:", contentControls.items[0]);
    contentControls.items[0].delete(false);
    await context.sync();
  }
});

getHtml()

Obtient une représentation HTML de l’objet de contrôle de contenu. En cas de rendu dans une page web ou une visionneuse HTML, la mise en forme correspond à une correspondance proche, mais pas exacte, pour la mise en forme du document. Cette méthode ne retourne pas exactement le même code HTML pour le même document sur différentes plateformes (Windows, Mac, Word sur le web, etc.). Si vous avez besoin d’une fidélité exacte ou d’une cohérence entre les plateformes, utilisez ContentControl.getOoxml() et convertissez le code XML retourné au format HTML.

getHtml(): OfficeExtension.ClientResult<string>;

Retours

OfficeExtension.ClientResult<string>

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection that contains a specific tag.
    const contentControlsWithTag = context.document.contentControls.getByTag('Customer-Address');
    
    // Queue a command to load the tag property for all of content controls.
    contentControlsWithTag.load('tag');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControlsWithTag.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to get the HTML contents of the first content control.
        const html = contentControlsWithTag.items[0].getHtml();
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control HTML: ' + html.value);
    }
});

getOoxml()

Obtient la représentation Office Open XML (OOXML) de l’objet de contrôle de contenu.

getOoxml(): OfficeExtension.ClientResult<string>;

Retours

OfficeExtension.ClientResult<string>

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to get the OOXML contents of the first content control.
        const ooxml = contentControls.items[0].getOoxml();
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control OOXML: ' + ooxml.value);
    }
});

insertBreak(breakType, insertLocation)

Insère un saut à l’emplacement spécifié du document principal. Cette méthode ne peut pas être utilisée avec les contrôles de contenu « RichTextTable », « RichTextTableRow » et « RichTextTableCell ».

insertBreak(breakType: Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line", insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After"): void;

Paramètres

breakType

Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line"

Obligatoire. Type d’arrêt.

insertLocation

start | end | before | after | "Start" | "End" | "Before" | "After"

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

Retours

void

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of content controls.
    contentControls.load('id');
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    // We now will have access to the content control collection.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to insert a page break after the first content control.
        contentControls.items[0].insertBreak(Word.BreakType.page, Word.InsertLocation.after);
        
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted a page break after the first content control.');    
    }
});

insertFileFromBase64(base64File, insertLocation)

Insère un document dans le contrôle de contenu à l’emplacement spécifié.

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

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 ». 'Replace' ne peut pas être utilisé avec les contrôles de contenu 'RichTextTable' et 'RichTextTableRow'.

Retours

Word.Range

Remarques

[ Ensemble d’API : WordApi 1.1 ]

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.

insertHtml(html, insertLocation)

Insère du code HTML dans le contrôle de contenu, à l’emplacement spécifié.

insertHtml(html: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

Paramètres

html

string

Obligatoire. Code HTML à insérer dans le contrôle de contenu.

insertLocation

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

Obligatoire. La valeur doit être « Replace », « Start » ou « End ». 'Replace' ne peut pas être utilisé avec les contrôles de contenu 'RichTextTable' et 'RichTextTableRow'.

Retours

Word.Range

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to put HTML into the contents of the first content control.
        contentControls.items[0].insertHtml(
            '<strong>HTML content inserted into the content control.</strong>',
            'Start');
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted HTML in the first content control.');
    }
});

insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

Insère une image incluse dans le contrôle de contenu, à l’emplacement spécifié.

insertInlinePictureFromBase64(base64EncodedImage: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.InlinePicture;

Paramètres

base64EncodedImage

string

Obligatoire. Image encodée en Base64 à insérer dans le contrôle de contenu.

insertLocation

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

Obligatoire. La valeur doit être « Replace », « Start » ou « End ». 'Replace' ne peut pas être utilisé avec les contrôles de contenu 'RichTextTable' et 'RichTextTableRow'.

Retours

Word.InlinePicture

Remarques

[ Ensemble d’API : WordApi 1.2 ]

insertOoxml(ooxml, insertLocation)

Insère OOXML dans le contrôle de contenu à l’emplacement spécifié.

insertOoxml(ooxml: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

Paramètres

ooxml

string

Obligatoire. OOXML à insérer dans le contrôle de contenu.

insertLocation

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

Obligatoire. La valeur doit être « Replace », « Start » ou « End ». 'Replace' ne peut pas être utilisé avec les contrôles de contenu 'RichTextTable' et 'RichTextTableRow'.

Retours

Word.Range

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to put OOXML into the contents of the first content control.
        contentControls.items[0].insertOoxml("<pkg:package xmlns:pkg='http://schemas.microsoft.com/office/2006/xmlPackage'><pkg:part pkg:name='/_rels/.rels' pkg:contentType='application/vnd.openxmlformats-package.relationships+xml' pkg:padding='512'><pkg:xmlData><Relationships xmlns='http://schemas.openxmlformats.org/package/2006/relationships'><Relationship Id='rId1' Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument' Target='word/document.xml'/></Relationships></pkg:xmlData></pkg:part><pkg:part pkg:name='/word/document.xml' pkg:contentType='application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml'><pkg:xmlData><w:document xmlns:w='http://schemas.openxmlformats.org/wordprocessingml/2006/main' ><w:body><w:p><w:pPr><w:spacing w:before='360' w:after='0' w:line='480' w:lineRule='auto'/><w:rPr><w:color w:val='70AD47' w:themeColor='accent6'/><w:sz w:val='28'/></w:rPr></w:pPr><w:r><w:rPr><w:color w:val='70AD47' w:themeColor='accent6'/><w:sz w:val='28'/></w:rPr><w:t>This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.</w:t></w:r></w:p></w:body></w:document></pkg:xmlData></pkg:part></pkg:package>", "End");
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted OOXML in the first content control.');
    }
});  

// Read "Create better add-ins for Word with Office Open XML" for guidance on working with OOXML.
// https://learn.microsoft.com/office/dev/add-ins/word/create-better-add-ins-for-word-with-office-open-xml

insertParagraph(paragraphText, insertLocation)

Insère un paragraphe à l’emplacement spécifié.

insertParagraph(paragraphText: string, insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After"): Word.Paragraph;

Paramètres

paragraphText

string

Obligatoire. Texte de paragraphe à insérer.

insertLocation

start | end | before | after | "Start" | "End" | "Before" | "After"

Obligatoire. La valeur doit être « Start », « End », « Before » ou « After ». Impossible d’utiliser « Before » et « After » avec les contrôles de contenu « RichTextTable », « RichTextTableRow » et « RichTextTableCell ».

Retours

Word.Paragraph

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to insert a paragraph after the first content control.
        contentControls.items[0].insertParagraph('Text of the inserted paragraph.', 'After');
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted a paragraph after the first content control.');
    }
});

insertText(text, insertLocation)

Insère du texte dans le contrôle de contenu, à l’emplacement spécifié.

insertText(text: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

Paramètres

text

string

Obligatoire. Texte à insérer dans le contrôle de contenu.

insertLocation

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

Obligatoire. La valeur doit être « Replace », « Start » ou « End ». 'Replace' ne peut pas être utilisé avec les contrôles de contenu 'RichTextTable' et 'RichTextTableRow'.

Retours

Word.Range

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to replace text in the first content control.
        contentControls.items[0].insertText('Replaced text in the first content control.', 'Replace');
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Replaced text in the first content control.');
    }
});  

// The Silly stories add-in sample shows how to use the insertText method.
// https://aka.ms/sillystorywordaddin

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.ContentControlLoadOptions): Word.ContentControl;

Paramètres

options
Word.Interfaces.ContentControlLoadOptions

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

Retours

Word.ContentControl

Exemples

// Load all of the content control properties
// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    } else {
        // Queue a command to load the properties on the first content control.
        contentControls.items[0].load(  'appearance,' +
                                        'cannotDelete,' +
                                        'cannotEdit,' +
                                        'id,' +
                                        'placeHolderText,' +
                                        'removeWhenEdited,' +
                                        'title,' +
                                        'text,' +
                                        'type,' +
                                        'style,' +
                                        'tag,' +
                                        'font/size,' +
                                        'font/name,' +
                                        'font/color');             
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Property values of the first content control:' + 
            '   ----- appearance: ' + contentControls.items[0].appearance + 
            '   ----- cannotDelete: ' + contentControls.items[0].cannotDelete +
            '   ----- cannotEdit: ' + contentControls.items[0].cannotEdit +
            '   ----- color: ' + contentControls.items[0].color +
            '   ----- id: ' + contentControls.items[0].id +
            '   ----- placeHolderText: ' + contentControls.items[0].placeholderText +
            '   ----- removeWhenEdited: ' + contentControls.items[0].removeWhenEdited +
            '   ----- title: ' + contentControls.items[0].title +
            '   ----- text: ' + contentControls.items[0].text +
            '   ----- type: ' + contentControls.items[0].type +
            '   ----- style: ' + contentControls.items[0].style +
            '   ----- tag: ' + contentControls.items[0].tag +
            '   ----- font size: ' + contentControls.items[0].font.size +
            '   ----- font name: ' + contentControls.items[0].font.name +
            '   ----- font color: ' + contentControls.items[0].font.color);
    }
});

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

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.ContentControl

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

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.ContentControl

search(searchText, searchOptions)

Effectue une recherche avec les SearchOptions spécifiés dans l’étendue de l’objet de contrôle de contenu. 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

Obligatoire. Texte de recherche.

searchOptions

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

Optional. Options de la recherche.

Retours

Word.RangeCollection

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to select the first content control.
        contentControls.items[0].select();
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Selected the first content control.');
    }
});

select(selectionMode)

Sélectionne le contrôle de contenu. Word fait défiler le document jusqu’à accéder à la sélection.

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

Paramètres

selectionMode
Word.SelectionMode

Optional. Le mode de sélection doit être « Select », « Start » ou « End ». « Select » (sélectionner) est la valeur par défaut.

Retours

void

Remarques

[ Ensemble d’API : WordApi 1.1 ]

select(selectionModeString)

Sélectionne le contrôle de contenu. Word fait défiler le document jusqu’à accéder à la sélection.

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

Paramètres

selectionModeString

"Select" | "Start" | "End"

Optional. Le mode de sélection doit être « Select », « Start » ou « End ». « Select » (sélectionner) est la valeur par défaut.

Retours

void

Remarques

[ Ensemble d’API : WordApi 1.1 ]

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.ContentControlUpdateData, options?: OfficeExtension.UpdateOptions): void;

Paramètres

properties
Word.Interfaces.ContentControlUpdateData

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

Exemples

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

// Adds title and colors to odd and even content controls and changes their appearance.
await Word.run(async (context) => {
  // Get the complete sentence (as range) associated with the insertion point.
  let evenContentControls = context.document.contentControls.getByTag("even");
  let oddContentControls = context.document.contentControls.getByTag("odd");
  evenContentControls.load("length");
  oddContentControls.load("length");

  await context.sync();

  for (let i = 0; i < evenContentControls.items.length; i++) {
    // Change a few properties and append a paragraph.
    evenContentControls.items[i].set({
      color: "red",
      title: "Odd ContentControl #" + (i + 1),
      appearance: Word.ContentControlAppearance.tags
    });
    evenContentControls.items[i].insertParagraph("This is an odd content control", "End");
  }

  for (let j = 0; j < oddContentControls.items.length; j++) {
    // Change a few properties and append a paragraph.
    oddContentControls.items[j].set({
      color: "green",
      title: "Even ContentControl #" + (j + 1),
      appearance: "Tags"
    });
    oddContentControls.items[j].insertHtml("This is an <b>even</b> content control", "End");
  }

  await context.sync();
});

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.ContentControl): void;

Paramètres

properties
Word.ContentControl

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.ContentControl est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Word.Interfaces.ContentControlDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

toJSON(): Word.Interfaces.ContentControlData;

Retours

Word.Interfaces.ContentControlData

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

Retours

Word.ContentControl

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

Retours

Word.ContentControl