Word.ContentControl class
Representa um controle de conteúdo. Controles de conteúdo são regiões limitadas e possivelmente rotuladas de 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, apenas são suportados controlos de conteúdo de rich text, texto simples e caixa de verificação.
- Extends
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.
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". |
cannot |
Especifica um valor que indica se o utilizador pode eliminar o controlo de conteúdo. Mutuamente exclusivo com a propriedade removeWhenEdited. |
cannot |
Especifica um valor que indica se o utilizador pode editar os conteúdos do controlo de conteúdo. |
color | Especifica a cor do controlo de conteúdo. A cor é especificada no formato "#RRGGBB" ou utilizando o nome da cor. |
content |
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. |
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. |
id | Obtém um número inteiro que representa o identificador do controle de conteúdo. |
inline |
Obtém a coleção de objetos InlinePicture no controlo de conteúdo. A coleção não inclui imagens flutuantes. |
paragraphs | Obtém a coleção de objetos de parágrafo no controlo de conteúdo. |
parent |
Obtém o controle de conteúdo que inclui o controle de conteúdo. Gera um |
placeholder |
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. |
remove |
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". |
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(keep |
Exclui o controle de conteúdo e o respectivo conteúdo. Se |
get |
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 |
get |
Obtém a representação OOXML (Office Open XML) do objeto do controle de conteúdo. |
insert |
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". |
insert |
Insere um documento no controlo de conteúdo na localização especificada. |
insert |
Insere HTML no local especificado dentro do controle de conteúdo. |
insert |
Insere uma imagem embutida no local especificado dentro do controle de conteúdo. |
insert |
Insere OOXML no controlo de conteúdo na localização especificada. |
insert |
Insere um parágrafo no local especificado. |
insert |
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 |
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 |
search(search |
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(selection |
Seleciona o controle de conteúdo. Isso faz com que o Word role até a seleção. |
select(selection |
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. |
toJSON() | Substitui o método JavaScript |
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 |
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 |
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
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
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
Comentários
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
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
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
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
Comentários
[ Conjunto de API: WordApi 1.1 ]
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.
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
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.
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
tag
Especifica uma etiqueta para identificar um controlo de conteúdo.
tag: string;
Valor da propriedade
string
Comentários
[ Conjunto de API: WordApi 1.1 ]
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
Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText"
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
[ 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.
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
[ 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.
const contentControls = context.document.contentControls;
// Queue a command to load the content controls collection.
contentControls.load('text');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
if (contentControls.items.length === 0) {
console.log("There isn't a content control in this document.");
} else {
// Queue a command to delete the first content control.
// The contents will remain in the document.
contentControls.items[0].delete(true);
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
console.log('Content control cleared of contents.');
}
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-ondeleted-event.yaml
await Word.run(async (context) => {
const contentControls: Word.ContentControlCollection = context.document.contentControls.getByTag("forTesting");
contentControls.load("items");
await context.sync();
if (contentControls.items.length === 0) {
console.log("There are no content controls in this document.");
} else {
console.log("Control to be deleted:", contentControls.items[0]);
contentControls.items[0].delete(false);
await context.sync();
}
});
getHtml()
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
OfficeExtension.ClientResult<string>
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 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
OfficeExtension.ClientResult<string>
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.
const contentControls = context.document.contentControls;
// Queue a command to load the id property for all of the content controls.
contentControls.load('id');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
if (contentControls.items.length === 0) {
console.log('No content control found.');
}
else {
// Queue a command to get the OOXML contents of the first content control.
const ooxml = contentControls.items[0].getOoxml();
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
console.log('Content control OOXML: ' + ooxml.value);
}
});
insertBreak(breakType, insertLocation)
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.
Obrigatório. O valor tem de ser "Iniciar", "Terminar", "Antes" ou "Depois".
Retornos
void
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.
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.
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
Comentários
[ Conjunto de API: WordApi 1.1 ]
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.
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
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.
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.
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
Comentários
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.
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
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.
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.
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
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.
const contentControls = context.document.contentControls;
// Queue a command to load the id property for all of the content controls.
contentControls.load('id');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
if (contentControls.items.length === 0) {
console.log('No content control found.');
}
else {
// Queue a command to insert a paragraph after the first content control.
contentControls.items[0].insertParagraph('Text of the inserted paragraph.', 'After');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
console.log('Inserted a paragraph after the first content control.');
}
});
insertText(text, insertLocation)
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.
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
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.
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
Fornece opções para as propriedades do objeto a carregar.
Retornos
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
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
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
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.
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
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
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.
toJSON(): Word.Interfaces.ContentControlData;
Retornos
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
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;