Word.ContentControlCollection class
Contém uma coleção de Word. Objetos ContentControl. Os controles de conteúdo são regiões associadas e potencialmente rotuladas em um documento que servem como contêineres para tipos específicos de conteúdo. Os controles de conteúdo individuais podem incluir conteúdo, como imagens, tabelas ou parágrafos de texto formatado. Atualmente, há suporte apenas para controles de conteúdo de texto e texto simples.
- Extends
Comentários
[ Conjunto de API: WordApi 1.1 ]
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
get |
Obtém os controles de conteúdo que têm o estado de acompanhamento especificado. |
get |
Obtém um controle de conteúdo pelo respectivo identificador. Gerará um |
get |
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 |
get |
Obtém os controles de conteúdo com a marca especificada. |
get |
Obtém os controles de conteúdo com o título especificado. |
get |
Obtém os controles de conteúdo que têm os tipos especificados. |
get |
Obtém o primeiro controle de conteúdo nesta coleção. Gerará um |
get |
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 |
get |
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 |
load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
toJSON() | Substitui o método JavaScript |
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 |
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 |
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
items
Obtém os itens filhos carregados nesta coleção.
readonly items: Word.ContentControl[];
Valor da propriedade
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
Obrigatório. Uma matriz de estados de controle de conteúdo de controle de alterações.
Retornos
Comentários
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
Comentários
[ Conjunto de API: WordApi 1.1 ]
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
Comentários
[ Conjunto de API: WordApi 1.3 ]
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
[ Conjunto de API: WordApi 1.1 ]
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
[ Conjunto de API: WordApi 1.1 ]
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
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
Comentários
[ Conjunto de API: WordApi 1.3 ]
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
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
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
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.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.
toJSON(): Word.Interfaces.ContentControlCollectionData;
Retornos
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
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de