Word.ContentControlCollection class

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é

Obtient l’élément enfant chargé dans cette collection de sites.

readonly items: Word.ContentControl[];

Valeur de propriété

Obtient les contrôles de contenu qui ont l’état de suivi spécifié.

getByChangeTrackingStates(changeTrackingStates: Word.ChangeTrackingState[]): Word.ContentControlCollection;

Paramètres

Retours

Remarques

[ Ensemble d’API : WordApi 1.5 ]

Obtient un contrôle de contenu par son identificateur. Génère une ItemNotFound erreur s’il n’existe pas de contrôle de contenu avec l’identificateur dans cette collection.

getById(id: number): Word.ContentControl;

Paramètres

Retours

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 control that contains a specific id.
    const contentControl = context.document.contentControls.getById(30086310);

    // Queue a command to load the text property for a content control.
    contentControl.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The content control with that Id has been found in this document.');
});

Obtient un contrôle de contenu par son identificateur. S’il n’existe pas de contrôle de contenu avec l’identificateur dans cette collection, 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.

getByIdOrNullObject(id: number): Word.ContentControl;

Paramètres

Retours

Remarques

[ Ensemble d’API : WordApi 1.3 ]

Exemples

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

    // Create a proxy object for the content control that contains a specific id.
    const contentControl = context.document.contentControls.getByIdOrNullObject(30086310);

    // Queue a command to load the text property for a content control.
    contentControl.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControl.isNullObject) {
        console.log('There is no content control with that ID.')
    } else {
        console.log('The content control with that ID has been found in this document.');
    }
});

Obtient les contrôles de contenu qui portent l’indicateur spécifié.

getByTag(tag: string): Word.ContentControlCollection;

Paramètres

Retours

Remarques

[ Ensemble d’API : WordApi 1.1 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/90-scenarios/doc-assembly.yaml

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

    await context.sync();

    for (let i = 0; i < contentControls.items.length; i++) {
      contentControls.items[i].insertText("Fabrikam", "Replace");
    }

    await context.sync();
});

Obtient les contrôles de contenu qui ont le titre spécifié.

getByTitle(title: string): Word.ContentControlCollection;

Paramètres

Retours

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 title.
    const contentControlsWithTitle = context.document.contentControls.getByTitle('Enter Customer Address Here');

    // Queue a command to load the text property for all of content controls with a specific title.
    contentControlsWithTitle.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControlsWithTitle.items.length === 0) {
        console.log(
            "There isn't a content control with a title of 'Enter Customer Address Here' in this document.");
    } else {
        console.log(
            "The first content control with the title of 'Enter Customer Address Here' has this text: " + 
            contentControlsWithTitle.items[0].text);
    }
});

// The Word-Add-in-DocumentAssembly sample has another example of using the getByTitle method.
// https://github.com/OfficeDev/Word-Add-in-DocumentAssembly

Obtient les contrôles de contenu qui ont les types spécifiés.

getByTypes(types: Word.ContentControlType[]): Word.ContentControlCollection;

Paramètres

Retours

Remarques

[ Ensemble d’API : WordApi 1.3 ]

Obtient le premier contrôle de contenu de cette collection. Génère une ItemNotFound erreur si cette collection est vide.

getFirst(): Word.ContentControl;

Retours

Remarques

[ Ensemble d’API : WordApi 1.3 ]

Exemples

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

    // Create a proxy object for the first content control in the document.
    const contentControl = context.document.contentControls.getFirstOrNullObject();

    // Queue a command to load the text property for a content control.
    contentControl.load('text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControl.isNullObject) {
        console.log('There are no content controls in this document.')
    } else {
        console.log('The first content control has been found in this document.');
    }
});

Obtient le premier contrôle de contenu de cette collection. Si cette collection est vide, 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.

getFirstOrNullObject(): Word.ContentControl;

Retours

Remarques

[ Ensemble d’API : WordApi 1.3 ]

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 of the first checkbox content control found in the selection.
await Word.run(async (context) => {
  const selectedRange: Word.Range = context.document.getSelection();
  let selectedContentControl = selectedRange
    .getContentControls({
      types: [Word.ContentControlType.checkBox]
    })
    .getFirstOrNullObject();
  selectedContentControl.load("id,checkboxContentControl/isChecked");

  await context.sync();

  if (selectedContentControl.isNullObject) {
    const parentContentControl: Word.ContentControl = selectedRange.parentContentControl;
    parentContentControl.load("id,type,checkboxContentControl/isChecked");
    await context.sync();

    if (parentContentControl.isNullObject || parentContentControl.type !== Word.ContentControlType.checkBox) {
      console.warn("No checkbox content control is currently selected.");
      return;
    } else {
      selectedContentControl = parentContentControl;
    }
  }

  const isCheckedBefore = selectedContentControl.checkboxContentControl.isChecked;
  console.log("isChecked state before:", `id: ${selectedContentControl.id} ... isChecked: ${isCheckedBefore}`);
  selectedContentControl.checkboxContentControl.isChecked = !isCheckedBefore;
  selectedContentControl.load("id,checkboxContentControl/isChecked");
  await context.sync();

  console.log(
    "isChecked state after:",
    `id: ${selectedContentControl.id} ... isChecked: ${selectedContentControl.checkboxContentControl.isChecked}`
  );
});

Obtient un contrôle de contenu par son ID.

getItem(id: number): Word.ContentControl;

Paramètres

Retours

Remarques

[ Ensemble d’API : WordApi 1.1 ]

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.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ContentControlCollection;

Paramètres

Retours

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

// The Silly stories add-in sample shows how the load method is used
// to load the content control collection with the tag and title properties.
// https://aka.ms/sillystorywordaddin

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

Paramètres

Retours

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?: OfficeExtension.LoadOption): Word.ContentControlCollection;

Paramètres

Retours

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.ContentControlCollection est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Word.Interfaces.ContentControlCollectionDataque ) qui contient un tableau « items » avec des copies superficielles de toutes les propriétés chargées à partir des éléments de la collection.

toJSON(): Word.Interfaces.ContentControlCollectionData;

Retours

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

Retours

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

Retours