Word. Content Control class

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

Propriedades

appearance	Especifica o aspeto do controlo de conteúdo. O valor pode ser "BoundingBox", "Tags" ou "Hidden".
cannotDelete	Especifica um valor que indica se o utilizador pode eliminar o controlo de conteúdo. Mutuamente exclusivo com a propriedade removeWhenEdited.
cannotEdit	Especifica um valor que indica se o utilizador pode editar os conteúdos do controlo de conteúdo.
checkboxContentControl	Especifica os dados relacionados com a caixa de verificação se o tipo do controlo de conteúdo for "Caixa de Verificação". Caso contrário, é nulo.
color	Especifica a cor do controlo de conteúdo. A cor é especificada no formato "#RRGGBB" ou utilizando o nome da cor.
comboBoxContentControl	Especifica os dados relacionados com a caixa de combinação se o tipo do controlo de conteúdo for "Caixa de Combinação". De `null` outra forma.
contentControls	Obtém a coleção de objetos de controle de conteúdo no controle de conteúdo.
context	O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
dropDownListContentControl	Especifica os dados relacionados com a lista pendente se o tipo do controlo de conteúdo for "DropDownList". Caso contrário, é nulo.
endnotes	Obtém a coleção de notas de fim no controlo de conteúdo.
fields	Obtém a coleção de objetos de campo no controlo de conteúdo.
font	Obtém o formato de texto do controle de conteúdo. Use isto para obter e definir o nome, o tamanho e a cor da fonte, além de outras propriedades.
footnotes	Obtém a coleção de notas de rodapé no controlo de conteúdo.
id	Obtém um número inteiro que representa o identificador do controle de conteúdo.
inlinePictures	Obtém a coleção de objetos InlinePicture no controlo de conteúdo. A coleção não inclui imagens flutuantes.
lists	Obtém a coleção de listas de objetos no controle de conteúdo.
paragraphs	Obtém a coleção de objetos de parágrafo no controlo de conteúdo.
parentBody	Obtém o corpo pai do controle de conteúdo.
parentContentControl	Obtém o controle de conteúdo que inclui o controle de conteúdo. Gera um `ItemNotFound` erro se não existir um controlo de conteúdo principal.
parentContentControlOrNullObject	Obtém o controle de conteúdo que inclui o controle de conteúdo. Se não existir um controlo de conteúdo principal, este método devolverá um objeto com a respetiva `isNullObject` propriedade definida como `true`. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).
parentTable	Obtém a tabela que contém o controle de conteúdo. Gera um `ItemNotFound` erro se não estiver contido numa tabela.
parentTableCell	Obtém a célula de tabela que contém o controle de conteúdo. Gera um `ItemNotFound` erro se não estiver contido numa célula de tabela.
parentTableCellOrNullObject	Obtém a célula de tabela que contém o controle de conteúdo. Se não estiver contido numa célula de tabela, este método devolverá um objeto com a respetiva `isNullObject` propriedade definida como `true`. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).
parentTableOrNullObject	Obtém a tabela que contém o controle de conteúdo. Se não estiver contido numa tabela, este método devolverá um objeto com a respetiva `isNullObject` propriedade definida como `true`. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).
placeholderText	Especifica o texto do marcador de posição do controlo de conteúdo. Quando o controle de conteúdo está vazio, o sistema exibe o texto esmaecido. Nota: a operação de conjunto para esta propriedade não é suportada no Word na Web.
removeWhenEdited	Especifica um valor que indica se o controlo de conteúdo é removido depois de ser editado. Mutuamente exclusivo com a propriedade cannotDelete.
style	Especifica o nome do estilo para o controlo de conteúdo. Use esta propriedade de estilos personalizados e nomes de estilo localizados. Para usar os estilos internos que são portáteis entre localidades, confira a propriedade "styleBuiltIn".
styleBuiltIn	Especifica o nome de estilo incorporado para o controlo de conteúdo. Use esta propriedade para estilos internos que são portáteis entre localidades. Para usar estilos personalizados ou nomes de estilo localizados, confira a propriedade "estilo".
subtype	Obtém o subtipo de controle de conteúdo. O subtipo pode ser "RichTextInline", "RichTextParagraphs", "RichTextTableCell", "RichTextTableRow" e "RichTextTable" para controlos de conteúdo de texto formatado ou "PlainTextInline" e "PlainTextParagraph" para controlos de conteúdo de texto simples ou "Caixa de Verificação" para controlos de conteúdo da caixa de verificação.
tables	Obtém a coleção de objetos de tabela no controle de conteúdo.
tag	Especifica uma etiqueta para identificar um controlo de conteúdo.
text	Obtém o texto do controle de conteúdo.
title	Especifica o título de um controlo de conteúdo.
type	Obtém o tipo de controle de conteúdo. Atualmente, só são suportados controlos de conteúdo de rich text, texto simples e caixa de verificação.

Métodos

clear()	Limpa o conteúdo do controle de conteúdo. O usuário pode executar a operação de desfazer no conteúdo limpo.
delete(keepContent)	Exclui o controle de conteúdo e o respectivo conteúdo. Se `keepContent` estiver definido como verdadeiro, o conteúdo não é eliminado.
getComments()	Obtém comentários associados ao controlo de conteúdo.
getContentControls(options)	Obtém os controlos de conteúdo subordinado atualmente suportados neste controlo de conteúdo.
getHtml()	Obtém uma representação HTML do objeto de controlo de conteúdo. Quando composta numa página Web ou visualizador de HTML, a formatação será uma correspondência próxima, mas não exata, da formatação do documento. Este método não devolve exatamente o mesmo HTML para o mesmo documento em diferentes plataformas (Windows, Mac, Word na Web, etc.). Se precisar de fidelidade exata ou consistência entre plataformas, utilize `ContentControl.getOoxml()` e converta o XML devolvido em HTML.
getOoxml()	Obtém a representação OOXML (Office Open XML) do objeto do controle de conteúdo.
getRange(rangeLocation)	Obtém o controle de todo o conteúdo, ou então, os pontos inicial ou final do controle de conteúdo, como um intervalo.
getReviewedText(changeTrackingVersion)	Obtém o texto revisto com base na seleção ChangeTrackingVersion.
getReviewedText(changeTrackingVersionString)	Obtém o texto revisto com base na seleção ChangeTrackingVersion.
getTextRanges(endingMarks, trimSpacing)	Obtém os intervalos de texto no controlo de conteúdo utilizando marcas de pontuação e/ou outras marcas finais.
getTrackedChanges()	Obtém a coleção dos objetos TrackedChange no controlo de conteúdo.
insertBreak(breakType, insertLocation)	Insere uma quebra no local especificado no documento principal. Este método não pode ser utilizado com os controlos de conteúdo "RichTextTable", "RichTextTableRow" e "RichTextTableCell".
insertFileFromBase64(base64File, insertLocation)	Insere um documento no controlo de conteúdo na localização especificada.
insertHtml(html, insertLocation)	Insere HTML no local especificado dentro do controle de conteúdo.
insertInlinePictureFromBase64(base64EncodedImage, insertLocation)	Insere uma imagem embutida no local especificado dentro do controle de conteúdo.
insertOoxml(ooxml, insertLocation)	Insere OOXML no controlo de conteúdo na localização especificada.
insertParagraph(paragraphText, insertLocation)	Insere um parágrafo no local especificado.
insertTable(rowCount, columnCount, insertLocation, values)	Insere uma tabela com a quantidade especificada de linhas e colunas dentro ou próxima do controle de conteúdo.
insertText(text, insertLocation)	Insere texto no local especificado dentro do controle de conteúdo.
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.
resetState()	Repõe o estado do controlo de conteúdo.
search(searchText, searchOptions)	Efetua uma pesquisa com as SearchOptions especificadas no âmbito do objeto de controlo de conteúdo. Os resultados da pesquisa são uma coleção de objetos Range.
select(selectionMode)	Seleciona o controle de conteúdo. Isso faz com que o Word role até a seleção.
select(selectionModeString)	Seleciona o controle de conteúdo. Isso faz com que o Word role até a seleção.
set(properties, options)	Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.
set(properties)	Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.
setState(contentControlState)	Define o estado do controlo de conteúdo.
setState(contentControlStateString)	Define o estado do controlo de conteúdo.
split(delimiters, multiParagraphs, trimDelimiters, trimSpacing)	Divide o controle de conteúdo em intervalos filho usando delimitadores.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é transmitido para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que lhe é transmitido.) Enquanto o objeto original `Word.ContentControl` é um objeto de API, o `toJSON` método devolve um objeto JavaScript simples (escrito como `Word.Interfaces.ContentControlData`) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este 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, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez. Se este objeto fizer parte de uma coleção, também deve controlar a coleção principal.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta 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. Terá de chamar `context.sync()` antes de a libertação da memória ser aplicada.

Eventos

onCommentAdded	Ocorre quando são adicionados novos comentários.
onCommentChanged	Ocorre quando um comentário ou a respetiva resposta é alterada.
onCommentDeselected	Ocorre quando um comentário é desselecionado.
onCommentSelected	Ocorre quando um comentário é selecionado.
onDataChanged	Ocorre quando os dados no controlo de conteúdo são alterados. Para obter o novo texto, carregue este controlo de conteúdo no processador. Para obter o texto antigo, não o carregue.
onDeleted	Ocorre quando o controlo de conteúdo é eliminado. Não carregue este controlo de conteúdo no processador. Caso contrário, não conseguirá obter as respetivas propriedades originais.
onEntered	Ocorre quando o controlo de conteúdo é introduzido.
onExited	Ocorre quando o controlo de conteúdo é fechado, por exemplo, quando o cursor deixa o controlo de conteúdo.
onSelectionChanged	Ocorre quando a seleção no controlo de conteúdo é alterada.

Detalhes da propriedade

appearance

Especifica o aspeto do controlo de conteúdo. O valor pode ser "BoundingBox", "Tags" ou "Hidden".

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

Valor da propriedade

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

Comentários

cannotDelete

Especifica um valor que indica se o utilizador pode eliminar o controlo de conteúdo. Mutuamente exclusivo com a propriedade removeWhenEdited.

cannotDelete: boolean;

Valor da propriedade

boolean

Comentários

cannotEdit

Especifica um valor que indica se o utilizador pode editar os conteúdos do controlo de conteúdo.

cannotEdit: boolean;

Valor da propriedade

boolean

Comentários

checkboxContentControl

Especifica os dados relacionados com a caixa de verificação se o tipo do controlo de conteúdo for "Caixa de Verificação". Caso contrário, é nulo.

readonly checkboxContentControl: Word.CheckboxContentControl;

Valor da propriedade

Word.CheckboxContentControl

Comentários

[ Conjunto de API: WordApi 1.7 ]

Exemplos

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

color

Especifica a cor do controlo de conteúdo. A cor é especificada no formato "#RRGGBB" ou utilizando o nome da cor.

color: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

comboBoxContentControl

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Especifica os dados relacionados com a caixa de combinação se o tipo do controlo de conteúdo for "Caixa de Combinação". De null outra forma.

readonly comboBoxContentControl: Word.ComboBoxContentControl;

Valor da propriedade

Word.ComboBoxContentControl

Comentários

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/99-preview-apis/insert-and-change-combo-box-content-control.yaml

// Adds the provided list item to the first combo box content control in the selection.
await Word.run(async (context) => {
  const listItemText = $("#item-to-add")
    .val()
    .toString()
    .trim();
  const selectedRange: Word.Range = context.document.getSelection();
  let selectedContentControl = selectedRange
    .getContentControls({
      types: [Word.ContentControlType.comboBox]
    })
    .getFirstOrNullObject();
  selectedContentControl.load("id,comboBoxContentControl");
  await context.sync();

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

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

  selectedContentControl.comboBoxContentControl.addListItem(listItemText);
  await context.sync();

  console.log(`List item added to control with ID ${selectedContentControl.id}: ${listItemText}`);
});

contentControls

Obtém a coleção de objetos de controle de conteúdo no controle de conteúdo.

readonly contentControls: Word.ContentControlCollection;

Valor da propriedade

Word.ContentControlCollection

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Word.RequestContext

dropDownListContentControl

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Especifica os dados relacionados com a lista pendente se o tipo do controlo de conteúdo for "DropDownList". Caso contrário, é nulo.

readonly dropDownListContentControl: Word.DropDownListContentControl;

Valor da propriedade

Word.DropDownListContentControl

Comentários

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/99-preview-apis/insert-and-change-dropdown-list-content-control.yaml

// Adds the provided list item to the first dropdown list content control in the selection.
await Word.run(async (context) => {
  const listItemText = $("#item-to-add")
    .val()
    .toString()
    .trim();
  const selectedRange: Word.Range = context.document.getSelection();
  let selectedContentControl = selectedRange
    .getContentControls({
      types: [Word.ContentControlType.dropDownList]
    })
    .getFirstOrNullObject();
  selectedContentControl.load("id,dropDownListContentControl");
  await context.sync();

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

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

  selectedContentControl.dropDownListContentControl.addListItem(listItemText);
  await context.sync();

  console.log(`List item added to control with ID ${selectedContentControl.id}: ${listItemText}`);
});

endnotes

Obtém a coleção de notas de fim no controlo de conteúdo.

readonly endnotes: Word.NoteItemCollection;

Valor da propriedade

Word.NoteItemCollection

Comentários

fields

Obtém a coleção de objetos de campo no controlo de conteúdo.

readonly fields: Word.FieldCollection;

Valor da propriedade

Word.FieldCollection

Comentários

font

Obtém o formato de texto do controle de conteúdo. Use isto para obter e definir o nome, o tamanho e a cor da fonte, além de outras propriedades.

readonly font: Word.Font;

Valor da propriedade

Word.Font

Comentários

footnotes

Obtém a coleção de notas de rodapé no controlo de conteúdo.

readonly footnotes: Word.NoteItemCollection;

Valor da propriedade

Word.NoteItemCollection

Comentários

id

Obtém um número inteiro que representa o identificador do controle de conteúdo.

readonly id: number;

Valor da propriedade

number

Comentários

inlinePictures

Obtém a coleção de objetos InlinePicture no controlo de conteúdo. A coleção não inclui imagens flutuantes.

readonly inlinePictures: Word.InlinePictureCollection;

Valor da propriedade

Word.InlinePictureCollection

Comentários

lists

Obtém a coleção de listas de objetos no controle de conteúdo.

readonly lists: Word.ListCollection;

Valor da propriedade

Word.ListCollection

Comentários

paragraphs

Obtém a coleção de objetos de parágrafo no controlo de conteúdo.

readonly paragraphs: Word.ParagraphCollection;

Valor da propriedade

Word.ParagraphCollection

Comentários

Importante: para os conjuntos de requisitos 1.1 e 1.2, os parágrafos em tabelas totalmente contidas neste controlo de conteúdo não são devolvidos. A partir do conjunto de requisitos 1.3, os parágrafos nessas tabelas também são devolvidos.

parentBody

Obtém o corpo pai do controle de conteúdo.

readonly parentBody: Word.Body;

Valor da propriedade

Word.Body

Comentários

parentContentControl

Obtém o controle de conteúdo que inclui o controle de conteúdo. Gera um ItemNotFound erro se não existir um controlo de conteúdo principal.

readonly parentContentControl: Word.ContentControl;

Valor da propriedade

Word.ContentControl

Comentários

parentContentControlOrNullObject

Obtém o controle de conteúdo que inclui o controle de conteúdo. Se não existir um controlo de conteúdo principal, este método devolverá um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

readonly parentContentControlOrNullObject: Word.ContentControl;

Valor da propriedade

Word.ContentControl

Comentários

parentTable

Obtém a tabela que contém o controle de conteúdo. Gera um ItemNotFound erro se não estiver contido numa tabela.

readonly parentTable: Word.Table;

Valor da propriedade

Word.Table

Comentários

parentTableCell

Obtém a célula de tabela que contém o controle de conteúdo. Gera um ItemNotFound erro se não estiver contido numa célula de tabela.

readonly parentTableCell: Word.TableCell;

Valor da propriedade

Word.TableCell

Comentários

parentTableCellOrNullObject

Obtém a célula de tabela que contém o controle de conteúdo. Se não estiver contido numa célula de tabela, este método devolverá um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

readonly parentTableCellOrNullObject: Word.TableCell;

Valor da propriedade

Word.TableCell

Comentários

parentTableOrNullObject

Obtém a tabela que contém o controle de conteúdo. Se não estiver contido numa tabela, este método devolverá um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

readonly parentTableOrNullObject: Word.Table;

Valor da propriedade

Word.Table

Comentários

placeholderText

Especifica o texto do marcador de posição do controlo de conteúdo. Quando o controle de conteúdo está vazio, o sistema exibe o texto esmaecido.

Nota: a operação de conjunto para esta propriedade não é suportada no Word na Web.

placeholderText: string;

Valor da propriedade

string

Comentários

removeWhenEdited

Especifica um valor que indica se o controlo de conteúdo é removido depois de ser editado. Mutuamente exclusivo com a propriedade cannotDelete.

removeWhenEdited: boolean;

Valor da propriedade

boolean

Comentários

style

Especifica o nome do estilo para o controlo de conteúdo. Use esta propriedade de estilos personalizados e nomes de estilo localizados. Para usar os estilos internos que são portáteis entre localidades, confira a propriedade "styleBuiltIn".

style: string;

Valor da propriedade

string

Comentários

styleBuiltIn

Especifica o nome de estilo incorporado para o controlo de conteúdo. Use esta propriedade para estilos internos que são portáteis entre localidades. Para usar estilos personalizados ou nomes de estilo localizados, confira a propriedade "estilo".

styleBuiltIn: Word.BuiltInStyleName | "Other" | "Normal" | "Heading1" | "Heading2" | "Heading3" | "Heading4" | "Heading5" | "Heading6" | "Heading7" | "Heading8" | "Heading9" | "Toc1" | "Toc2" | "Toc3" | "Toc4" | "Toc5" | "Toc6" | "Toc7" | "Toc8" | "Toc9" | "FootnoteText" | "Header" | "Footer" | "Caption" | "FootnoteReference" | "EndnoteReference" | "EndnoteText" | "Title" | "Subtitle" | "Hyperlink" | "Strong" | "Emphasis" | "NoSpacing" | "ListParagraph" | "Quote" | "IntenseQuote" | "SubtleEmphasis" | "IntenseEmphasis" | "SubtleReference" | "IntenseReference" | "BookTitle" | "Bibliography" | "TocHeading" | "TableGrid" | "PlainTable1" | "PlainTable2" | "PlainTable3" | "PlainTable4" | "PlainTable5" | "TableGridLight" | "GridTable1Light" | "GridTable1Light_Accent1" | "GridTable1Light_Accent2" | "GridTable1Light_Accent3" | "GridTable1Light_Accent4" | "GridTable1Light_Accent5" | "GridTable1Light_Accent6" | "GridTable2" | "GridTable2_Accent1" | "GridTable2_Accent2" | "GridTable2_Accent3" | "GridTable2_Accent4" | "GridTable2_Accent5" | "GridTable2_Accent6" | "GridTable3" | "GridTable3_Accent1" | "GridTable3_Accent2" | "GridTable3_Accent3" | "GridTable3_Accent4" | "GridTable3_Accent5" | "GridTable3_Accent6" | "GridTable4" | "GridTable4_Accent1" | "GridTable4_Accent2" | "GridTable4_Accent3" | "GridTable4_Accent4" | "GridTable4_Accent5" | "GridTable4_Accent6" | "GridTable5Dark" | "GridTable5Dark_Accent1" | "GridTable5Dark_Accent2" | "GridTable5Dark_Accent3" | "GridTable5Dark_Accent4" | "GridTable5Dark_Accent5" | "GridTable5Dark_Accent6" | "GridTable6Colorful" | "GridTable6Colorful_Accent1" | "GridTable6Colorful_Accent2" | "GridTable6Colorful_Accent3" | "GridTable6Colorful_Accent4" | "GridTable6Colorful_Accent5" | "GridTable6Colorful_Accent6" | "GridTable7Colorful" | "GridTable7Colorful_Accent1" | "GridTable7Colorful_Accent2" | "GridTable7Colorful_Accent3" | "GridTable7Colorful_Accent4" | "GridTable7Colorful_Accent5" | "GridTable7Colorful_Accent6" | "ListTable1Light" | "ListTable1Light_Accent1" | "ListTable1Light_Accent2" | "ListTable1Light_Accent3" | "ListTable1Light_Accent4" | "ListTable1Light_Accent5" | "ListTable1Light_Accent6" | "ListTable2" | "ListTable2_Accent1" | "ListTable2_Accent2" | "ListTable2_Accent3" | "ListTable2_Accent4" | "ListTable2_Accent5" | "ListTable2_Accent6" | "ListTable3" | "ListTable3_Accent1" | "ListTable3_Accent2" | "ListTable3_Accent3" | "ListTable3_Accent4" | "ListTable3_Accent5" | "ListTable3_Accent6" | "ListTable4" | "ListTable4_Accent1" | "ListTable4_Accent2" | "ListTable4_Accent3" | "ListTable4_Accent4" | "ListTable4_Accent5" | "ListTable4_Accent6" | "ListTable5Dark" | "ListTable5Dark_Accent1" | "ListTable5Dark_Accent2" | "ListTable5Dark_Accent3" | "ListTable5Dark_Accent4" | "ListTable5Dark_Accent5" | "ListTable5Dark_Accent6" | "ListTable6Colorful" | "ListTable6Colorful_Accent1" | "ListTable6Colorful_Accent2" | "ListTable6Colorful_Accent3" | "ListTable6Colorful_Accent4" | "ListTable6Colorful_Accent5" | "ListTable6Colorful_Accent6" | "ListTable7Colorful" | "ListTable7Colorful_Accent1" | "ListTable7Colorful_Accent2" | "ListTable7Colorful_Accent3" | "ListTable7Colorful_Accent4" | "ListTable7Colorful_Accent5" | "ListTable7Colorful_Accent6";

Valor da propriedade

Comentários

subtype

Obtém o subtipo de controle de conteúdo. O subtipo pode ser "RichTextInline", "RichTextParagraphs", "RichTextTableCell", "RichTextTableRow" e "RichTextTable" para controlos de conteúdo de texto formatado ou "PlainTextInline" e "PlainTextParagraph" para controlos de conteúdo de texto simples ou "Caixa de Verificação" para controlos de conteúdo da caixa de verificação.

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

Valor da propriedade

Comentários

tables

Obtém a coleção de objetos de tabela no controle de conteúdo.

readonly tables: Word.TableCollection;

Valor da propriedade

Word.TableCollection

Comentários

tag

Especifica uma etiqueta para identificar um controlo de conteúdo.

tag: string;

Valor da propriedade

string

Comentários

Exemplos

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

Obtém o texto do controle de conteúdo.

readonly text: string;

Valor da propriedade

string

Comentários

title

Especifica o título de um controlo de conteúdo.

title: string;

Valor da propriedade

string

Comentários

type

Obtém o tipo de controle de conteúdo. Atualmente, só são suportados controlos de conteúdo de rich text, texto simples e caixa de verificação.

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

Valor da propriedade

Comentários

Detalhes do método

clear()

Limpa o conteúdo do controle de conteúdo. O usuário pode executar a operação de desfazer no conteúdo limpo.

clear(): void;

Retornos

void

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

Exclui o controle de conteúdo e o respectivo conteúdo. Se keepContent estiver definido como verdadeiro, o conteúdo não é eliminado.

delete(keepContent: boolean): void;

Parâmetros

keepContent: boolean

Obrigatório. Indica se o conteúdo deve ser excluído com o controle de conteúdo. Se keepContent estiver definido como verdadeiro, o conteúdo não é eliminado.

Retornos

void

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

getComments()

Obtém comentários associados ao controlo de conteúdo.

getComments(): Word.CommentCollection;

Retornos

Word.CommentCollection

Comentários

getContentControls(options)

Obtém os controlos de conteúdo subordinado atualmente suportados neste controlo de conteúdo.

getContentControls(options?: Word.ContentControlOptions): Word.ContentControlCollection;

Parâmetros

options: Word.ContentControlOptions

Opcional. Opções que definem os controlos de conteúdo que são devolvidos.

Retornos

Word.ContentControlCollection

Comentários

Importante: se forem fornecidos tipos específicos no parâmetro de opções, apenas são devolvidos controlos de conteúdo de tipos suportados. Tenha em atenção que será gerada uma exceção através de métodos de um Word.ContentControl genérico que não são relevantes para o tipo específico. Com o tempo, podem ser suportados tipos adicionais de controlos de conteúdo. Por conseguinte, o suplemento deve pedir e processar tipos específicos de controlos de conteúdo.

getHtml()

Obtém uma representação HTML do objeto de controlo de conteúdo. Quando composta numa página Web ou visualizador de HTML, a formatação será uma correspondência próxima, mas não exata, da formatação do documento. Este método não devolve exatamente o mesmo HTML para o mesmo documento em diferentes plataformas (Windows, Mac, Word na Web, etc.). Se precisar de fidelidade exata ou consistência entre plataformas, utilize ContentControl.getOoxml() e converta o XML devolvido em HTML.

getHtml(): OfficeExtension.ClientResult<string>;

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 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()

Obtém a representação OOXML (Office Open XML) do objeto do controle de conteúdo.

getOoxml(): OfficeExtension.ClientResult<string>;

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

getRange(rangeLocation)

Obtém o controle de todo o conteúdo, ou então, os pontos inicial ou final do controle de conteúdo, como um intervalo.

getRange(rangeLocation?: Word.RangeLocation | "Whole" | "Start" | "End" | "Before" | "After" | "Content"): Word.Range;

Parâmetros

rangeLocation: Word.RangeLocation | "Whole" | "Start" | "End" | "Before" | "After" | "Content"

Opcional. A localização do intervalo tem de ser "Inteiro", "Iniciar", "Terminar", "Antes", "Depois" ou "Conteúdo".

Retornos

Word.Range

Comentários

getReviewedText(changeTrackingVersion)

Obtém o texto revisto com base na seleção ChangeTrackingVersion.

getReviewedText(changeTrackingVersion?: Word.ChangeTrackingVersion): OfficeExtension.ClientResult<string>;

Parâmetros

changeTrackingVersion: Word.ChangeTrackingVersion

Opcional. O valor tem de ser "Original" ou "Atual". A predefinição é "Atual".

Retornos

Comentários

getReviewedText(changeTrackingVersionString)

Obtém o texto revisto com base na seleção ChangeTrackingVersion.

getReviewedText(changeTrackingVersionString?: "Original" | "Current"): OfficeExtension.ClientResult<string>;

Parâmetros

changeTrackingVersionString: "Original" | "Current"

Opcional. O valor tem de ser "Original" ou "Atual". A predefinição é "Atual".

Retornos

Comentários

getTextRanges(endingMarks, trimSpacing)

Obtém os intervalos de texto no controlo de conteúdo utilizando marcas de pontuação e/ou outras marcas finais.

getTextRanges(endingMarks: string[], trimSpacing?: boolean): Word.RangeCollection;

Parâmetros

endingMarks: string[]

Obrigatório. As marcas de pontuação e/ou outras marcas finais como uma matriz de cadeias.

trimSpacing: boolean

Opcional. Indica se deve cortar carateres de espaçamento (espaços, separadores, quebras de coluna e marcas de fim de parágrafo) a partir do início e fim dos intervalos devolvidos na coleção de intervalos. A predefinição é false, o que indica que os carateres de espaçamento no início e no fim dos intervalos estão incluídos na coleção de intervalos.

Retornos

Word.RangeCollection

Comentários

getTrackedChanges()

Obtém a coleção dos objetos TrackedChange no controlo de conteúdo.

getTrackedChanges(): Word.TrackedChangeCollection;

Retornos

Word.TrackedChangeCollection

Comentários

[ Conjunto de API: WordApi 1.6 ]

insertBreak(breakType, insertLocation)

Insere uma quebra no local especificado no documento principal. Este método não pode ser utilizado com os controlos de conteúdo "RichTextTable", "RichTextTableRow" e "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;

Parâmetros

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

Obrigatório. Tipo de quebra.

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

Obrigatório. O valor tem de ser "Iniciar", "Terminar", "Antes" ou "Depois".

Retornos

void

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

Insere um documento no controlo de conteúdo na localização especificada.

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

Parâmetros

base64File: string

Obrigatório. O conteúdo codificado em Base64 de um ficheiro .docx.

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

Obrigatório. O valor tem de ser "Substituir", "Iniciar" ou "Terminar". Não é possível utilizar "Substituir" com controlos de conteúdo "RichTextTable" e "RichTextTableRow".

Retornos

Word.Range

Comentários

Nota: a inserção não é suportada se o documento que está a ser inserido contiver um controlo ActiveX (provavelmente num campo de formulário). Considere substituir tal campo de formulário por um controlo de conteúdo ou outra opção adequada para o seu cenário.

insertHtml(html, insertLocation)

Insere HTML no local especificado dentro do controle de conteúdo.

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

Parâmetros

html: string

Obrigatório. O HTML a inserir no controle de conteúdo.

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

Obrigatório. O valor tem de ser "Substituir", "Iniciar" ou "Terminar". Não é possível utilizar "Substituir" com controlos de conteúdo "RichTextTable" e "RichTextTableRow".

Retornos

Word.Range

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

Insere uma imagem embutida no local especificado dentro do controle de conteúdo.

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

Parâmetros

base64EncodedImage: string

Obrigatório. A imagem codificada com Base64 a inserir no controlo de conteúdo.

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

Obrigatório. O valor tem de ser "Substituir", "Iniciar" ou "Terminar". Não é possível utilizar "Substituir" com controlos de conteúdo "RichTextTable" e "RichTextTableRow".

Retornos

Word.InlinePicture

Comentários

[ Conjunto de API: WordApi 1.2 ]

insertOoxml(ooxml, insertLocation)

Insere OOXML no controlo de conteúdo na localização especificada.

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

Parâmetros

ooxml: string

Obrigatório. O OOXML a inserir no controlo de conteúdo.

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

Obrigatório. O valor tem de ser "Substituir", "Iniciar" ou "Terminar". Não é possível utilizar "Substituir" com controlos de conteúdo "RichTextTable" e "RichTextTableRow".

Retornos

Word.Range

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

Insere um parágrafo no local especificado.

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

Parâmetros

paragraphText: string

Obrigatório. O texto do parágrafo a ser inserido.

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

Obrigatório. O valor tem de ser "Iniciar", "Terminar", "Antes" ou "Depois". Não é possível utilizar "Antes" e "Depois" com os controlos de conteúdo "RichTextTable", "RichTextTableRow" e "RichTextTableCell".

Retornos

Word.Paragraph

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

insertTable(rowCount, columnCount, insertLocation, values)

Insere uma tabela com a quantidade especificada de linhas e colunas dentro ou próxima do controle de conteúdo.

insertTable(rowCount: number, columnCount: number, insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After", values?: string[][]): Word.Table;

Parâmetros

rowCount: number

Obrigatório. A quantidade de linhas na tabela.

columnCount: number

Obrigatório. A quantidade de colunas na tabela.

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

values: string[][]

Matriz 2D opcional. As células serão preenchidas se as cadeias de caracteres correspondentes estiverem especificadas na matriz.

Retornos

Word.Table

Comentários

insertText(text, insertLocation)

Insere texto no local especificado dentro do controle de conteúdo.

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

Parâmetros

text: string

Obrigatório. O texto a inserir no controle de conteúdo.

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

Obrigatório. O valor tem de ser "Substituir", "Iniciar" ou "Terminar". Não é possível utilizar "Substituir" com controlos de conteúdo "RichTextTable" e "RichTextTableRow".

Retornos

Word.Range

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

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

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

Parâmetros

options: Word.Interfaces.ContentControlLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

Word.ContentControl

Exemplos

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

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

Parâmetros

propertyNames: string | string[]

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

Retornos

Word.ContentControl

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?: {
            select?: string;
            expand?: string;
        }): Word.ContentControl;

Parâmetros

propertyNamesAndPaths: { select?: string; expand?: string; }

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

Retornos

Word.ContentControl

resetState()

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Repõe o estado do controlo de conteúdo.

resetState(): void;

Retornos

void

Comentários

Exemplos

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

// Resets the state of the first content control.
await Word.run(async (context) => {
  let firstContentControl = context.document.contentControls.getFirstOrNullObject();
  await context.sync();

  if (firstContentControl.isNullObject) {
    console.warn("There are no content controls in this document.");
    return;
  }
  
  firstContentControl.resetState();
  firstContentControl.load("id");
  await context.sync();

  console.log(`Reset state of first content control with ID: ${firstContentControl.id}`);
});

search(searchText, searchOptions)

Efetua uma pesquisa com as SearchOptions especificadas no âmbito do objeto de controlo de conteúdo. Os resultados da pesquisa são uma coleção de objetos Range.

search(searchText: string, searchOptions?: Word.SearchOptions | {
            ignorePunct?: boolean;
            ignoreSpace?: boolean;
            matchCase?: boolean;
            matchPrefix?: boolean;
            matchSuffix?: boolean;
            matchWholeWord?: boolean;
            matchWildcards?: boolean;
        }): Word.RangeCollection;

Parâmetros

searchText: string

Obrigatório. O texto da pesquisa.

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

Opcional. Opções da pesquisa.

Retornos

Word.RangeCollection

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

Seleciona o controle de conteúdo. Isso faz com que o Word role até a seleção.

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

Parâmetros

selectionMode: Word.SelectionMode

Opcional. O modo de seleção tem de ser "Selecionar", "Iniciar" ou "Terminar". 'Select' é o padrão.

Retornos

void

Comentários

select(selectionModeString)

Seleciona o controle de conteúdo. Isso faz com que o Word role até a seleção.

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

Parâmetros

selectionModeString: "Select" | "Start" | "End"

Opcional. O modo de seleção tem de ser "Selecionar", "Iniciar" ou "Terminar". 'Select' é o padrão.

Retornos

void

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

set(properties: Interfaces.ContentControlUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parâmetros

properties: Word.Interfaces.ContentControlUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options: OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

Exemplos

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

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

set(properties: Word.ContentControl): void;

Parâmetros

properties: Word.ContentControl

Retornos

void

setState(contentControlState)

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Define o estado do controlo de conteúdo.

setState(contentControlState: Word.ContentControlState): void;

Parâmetros

contentControlState: Word.ContentControlState

Estado a definir.

Retornos

void

Comentários

Exemplos

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

// Sets the state of the first content control.
await Word.run(async (context) => {
  const state = ($("#state-to-set").val() as unknown) as Word.ContentControlState;
  let firstContentControl = context.document.contentControls.getFirstOrNullObject();
  await context.sync();

  if (firstContentControl.isNullObject) {
    console.warn("There are no content controls in this document.");
    return;
  }

  firstContentControl.setState(state);
  firstContentControl.load("id");
  await context.sync();

  console.log(`Set state of first content control with ID ${firstContentControl.id} to ${state}.`);
});

setState(contentControlStateString)

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Define o estado do controlo de conteúdo.

setState(contentControlStateString: "Error" | "Warning"): void;

Parâmetros

contentControlStateString: "Error" | "Warning"

Estado a definir.

Retornos

void

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

split(delimiters, multiParagraphs, trimDelimiters, trimSpacing)

Divide o controle de conteúdo em intervalos filho usando delimitadores.

split(delimiters: string[], multiParagraphs?: boolean, trimDelimiters?: boolean, trimSpacing?: boolean): Word.RangeCollection;

Parâmetros

delimiters: string[]

Obrigatório. Os delimitadores como uma matriz de cadeias.

multiParagraphs: boolean

Opcional. Indica se um intervalo subordinado devolvido pode abranger vários parágrafos. A predefinição é falsa, o que indica que os limites de parágrafo também são utilizados como delimitadores.

trimDelimiters: boolean

Opcional. Indica se pretende cortar delimitadores dos intervalos na coleção de intervalos. A predefinição é falsa, o que indica que os delimitadores estão incluídos nos intervalos devolvidos na coleção de intervalos.

trimSpacing: boolean

Retornos

Word.RangeCollection

Comentários

OfficeExtension.EventHandlers<Word.CommentEventArgs>

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Word.ContentControl é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Word.Interfaces.ContentControlData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Word.Interfaces.ContentControlData;

Retornos

Word.Interfaces.ContentControlData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este 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, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez. Se este objeto fizer parte de uma coleção, também deve controlar a coleção principal.

track(): Word.ContentControl;

Retornos

Word.ContentControl

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta 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. Terá de chamar context.sync() antes de a libertação da memória ser aplicada.

untrack(): Word.ContentControl;

Retornos

Word.ContentControl

Detalhes do evento

onCommentAdded

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Ocorre quando são adicionados novos comentários.

readonly onCommentAdded: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

onCommentChanged

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Ocorre quando um comentário ou a respetiva resposta é alterada.

readonly onCommentChanged: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Word.CommentEventArgs>

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

onCommentDeselected

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Ocorre quando um comentário é desselecionado.

readonly onCommentDeselected: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Word.CommentEventArgs>

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

onCommentSelected

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Ocorre quando um comentário é selecionado.

readonly onCommentSelected: OfficeExtension.EventHandlers<Word.CommentEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Word.CommentEventArgs>

Comentários

[ Conjunto de API: WordApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

onDataChanged

Ocorre quando os dados no controlo de conteúdo são alterados. Para obter o novo texto, carregue este controlo de conteúdo no processador. Para obter o texto antigo, não o carregue.

readonly onDataChanged: OfficeExtension.EventHandlers<Word.ContentControlDataChangedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Word.ContentControlDataChangedEventArgs>

Comentários

OfficeExtension.EventHandlers<Word.ContentControlDeletedEventArgs>

Exemplos

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

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

  // Register the onDataChanged event handler on each content control.
  if (contentControls.items.length === 0) {
    console.log("There aren't any content controls in this document so can't register event handlers.");
  } else {
    for (let i = 0; i < contentControls.items.length; i++) {
      eventContexts[i] = contentControls.items[i].onDataChanged.add(contentControlDataChanged);
      contentControls.items[i].track();
    }

    await context.sync();

    console.log("Added event handlers for when data is changed in content controls.");
  }
});

...

async function contentControlDataChanged(event: Word.ContentControlDataChangedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. IDs of content controls where data was changed:`, event.ids);
  });
}

onDeleted

Ocorre quando o controlo de conteúdo é eliminado. Não carregue este controlo de conteúdo no processador. Caso contrário, não conseguirá obter as respetivas propriedades originais.

readonly onDeleted: OfficeExtension.EventHandlers<Word.ContentControlDeletedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.ContentControlEnteredEventArgs>

Exemplos

// 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;
  contentControls.load("items");
  await context.sync();

  // Register the onDeleted event handler on each content control.
  if (contentControls.items.length === 0) {
    console.log("There aren't any content controls in this document so can't register event handlers.");
  } else {
    for (let i = 0; i < contentControls.items.length; i++) {
      eventContexts[i] = contentControls.items[i].onDeleted.add(contentControlDeleted);
      contentControls.items[i].track();
    }

    await context.sync();

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

...

async function contentControlDeleted(event: Word.ContentControlDeletedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. IDs of content controls that were deleted:`, event.ids);
  });
}

onEntered

Ocorre quando o controlo de conteúdo é introduzido.

readonly onEntered: OfficeExtension.EventHandlers<Word.ContentControlEnteredEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.ContentControlExitedEventArgs>

Exemplos

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

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

  // Register the onEntered event handler on each content control.
  if (contentControls.items.length === 0) {
    console.log("There aren't any content controls in this document so can't register event handlers.");
  } else {
    for (let i = 0; i < contentControls.items.length; i++) {
      eventContexts[i] = contentControls.items[i].onEntered.add(contentControlEntered);
      contentControls.items[i].track();
    }

    await context.sync();

    console.log("Added event handlers for when the cursor is placed in content controls.");
  }
});

...

async function contentControlEntered(event: Word.ContentControlEnteredEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. ID of content control that was entered: ${event.ids[0]}`);
  });
}

onExited

Ocorre quando o controlo de conteúdo é fechado, por exemplo, quando o cursor deixa o controlo de conteúdo.

readonly onExited: OfficeExtension.EventHandlers<Word.ContentControlExitedEventArgs>;

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Word.ContentControlSelectionChangedEventArgs>

Exemplos

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

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

  // Register the onExited event handler on each content control.
  if (contentControls.items.length === 0) {
    console.log("There aren't any content controls in this document so can't register event handlers.");
  } else {
    for (let i = 0; i < contentControls.items.length; i++) {
      eventContexts[i] = contentControls.items[i].onExited.add(contentControlExited);
      contentControls.items[i].track();
    }

    await context.sync();

    console.log("Added event handlers for when the cursor is removed from within content controls.");
  }
});

...

async function contentControlExited(event: Word.ContentControlExitedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. ID of content control that was exited: ${event.ids[0]}`);
  });
}

onSelectionChanged

Ocorre quando a seleção no controlo de conteúdo é alterada.

readonly onSelectionChanged: OfficeExtension.EventHandlers<Word.ContentControlSelectionChangedEventArgs>;

Tipo de evento

Comentários