Word. Content Control Collection class

Propriedades

context	O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.
items	Obtém os itens filhos carregados nesta coleção.

Métodos

getByChangeTrackingStates(changeTrackingStates)	Obtém os controles de conteúdo que têm o estado de acompanhamento especificado.
getById(id)	Obtém um controle de conteúdo pelo respectivo identificador. Gerará um `ItemNotFound` erro se não houver um controle de conteúdo com o identificador nesta coleção.
getByIdOrNullObject(id)	Obtém um controle de conteúdo pelo respectivo identificador. Se não houver um controle de conteúdo com o identificador nesta coleção, esse método retornará um objeto com sua `isNullObject` propriedade definida como `true`. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
getByTag(tag)	Obtém os controles de conteúdo com a marca especificada.
getByTitle(title)	Obtém os controles de conteúdo com o título especificado.
getByTypes(types)	Obtém os controles de conteúdo que têm os tipos especificados.
getFirst()	Obtém o primeiro controle de conteúdo nesta coleção. Gerará um `ItemNotFound` erro se essa coleção estiver vazia.
getFirstOrNullObject()	Obtém o primeiro controle de conteúdo nesta coleção. Se essa coleção estiver vazia, esse método retornará um objeto com sua `isNullObject` propriedade definida como `true`. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
getItem(id)	Obtém um controle de conteúdo por sua ID.
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é passado para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que é passado para ele.) Considerando que o objeto original `Word.ContentControlCollection` é um objeto API, o `toJSON` método retorna um objeto JavaScript simples (digitado como `Word.Interfaces.ContentControlCollectionData`) que contém uma matriz de "itens" com cópias rasas de quaisquer propriedades carregadas dos itens da coleção.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação para context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre `.sync` chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, você precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará chamar `context.sync()` antes que a versão da memória entre em vigor.

Detalhes da propriedade

context

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

Word.RequestContext

items

Obtém os itens filhos carregados nesta coleção.

readonly items: Word.ContentControl[];

Valor da propriedade

Word.ContentControl[]

Detalhes do método

getByChangeTrackingStates(changeTrackingStates)

Obtém os controles de conteúdo que têm o estado de acompanhamento especificado.

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

Parâmetros

changeTrackingStates: Word.ChangeTrackingState[]

Obrigatório. Uma matriz de estados de controle de conteúdo de controle de alterações.

Retornos

Comentários

[ Conjunto de API: WordApi 1.5 ]

getById(id)

Obtém um controle de conteúdo pelo respectivo identificador. Gerará um ItemNotFound erro se não houver um controle de conteúdo com o identificador nesta coleção.

getById(id: number): Word.ContentControl;

Parâmetros

id: number

Obrigatório. Um identificador de controle de conteúdo.

Retornos

Word.ContentControl

Comentários

Exemplos

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

getByIdOrNullObject(id)

Obtém um controle de conteúdo pelo respectivo identificador. Se não houver um controle de conteúdo com o identificador nesta coleção, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

getByIdOrNullObject(id: number): Word.ContentControl;

Parâmetros

id: number

Obrigatório. Um identificador de controle de conteúdo.

Retornos

Word.ContentControl

Comentários

Exemplos

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

getByTag(tag)

Obtém os controles de conteúdo com a marca especificada.

getByTag(tag: string): Word.ContentControlCollection;

Parâmetros

tag: string

Obrigatório. Uma marca definida em um controle de conteúdo.

Retornos

Comentários

Exemplos

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

getByTitle(title)

Obtém os controles de conteúdo com o título especificado.

getByTitle(title: string): Word.ContentControlCollection;

Parâmetros

title: string

Obrigatório. O título de um controle de conteúdo.

Retornos

Comentários

Exemplos

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

getByTypes(types)

Obtém os controles de conteúdo que têm os tipos especificados.

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

Parâmetros

types: Word.ContentControlType[]

Obrigatório. Uma matriz de tipos de controle de conteúdo.

Retornos

Comentários

getFirst()

Obtém o primeiro controle de conteúdo nesta coleção. Gerará um ItemNotFound erro se essa coleção estiver vazia.

getFirst(): Word.ContentControl;

Retornos

Word.ContentControl

Comentários

Exemplos

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

getFirstOrNullObject()

Obtém o primeiro controle de conteúdo nesta coleção. Se essa coleção estiver vazia, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

getFirstOrNullObject(): Word.ContentControl;

Retornos

Word.ContentControl

Comentários

getItem(id)

Obtém um controle de conteúdo por sua ID.

getItem(id: number): Word.ContentControl;

Parâmetros

id: number

A ID do controle de conteúdo.

Retornos

Word.ContentControl

Comentários

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(options?: Word.Interfaces.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ContentControlCollection;

Parâmetros

options: Word.Interfaces.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions

Fornece opções para quais propriedades do objeto carregar.

Retornos

Exemplos

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

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

propertyNames: string | string[]

Uma cadeia de caracteres delimitada por vírgulas ou uma matriz de cadeias de caracteres que especificam as propriedades a serem carregadas.

Retornos

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ContentControlCollection;

Parâmetros

propertyNamesAndPaths: OfficeExtension.LoadOption

propertyNamesAndPaths.select é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades de navegação a serem carregadas.

Retornos

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que é passado para ele.) Considerando que o objeto original Word.ContentControlCollection é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado como Word.Interfaces.ContentControlCollectionData) que contém uma matriz de "itens" com cópias rasas de quaisquer propriedades carregadas dos itens da coleção.

toJSON(): Word.Interfaces.ContentControlCollectionData;

Retornos

Word.Interfaces.ContentControlCollectionData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação para context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, você precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.

track(): Word.ContentControlCollection;

Retornos

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará chamar context.sync() antes que a versão da memória entre em vigor.

untrack(): Word.ContentControlCollection;

Retornos