Controlli del contenuto
I controlli contenuto consentono di progettare documenti e modelli con le funzionalità seguenti:
Un'interfaccia utente con un input controllato come un form.
Restrizioni che impediscono agli utenti di modificare le sezioni protette del documento o del modello. Per ulteriori informazioni, vedere Protezione di parti dei documenti mediante i controlli contenuto.
Associazione dati a un'origine dati. Per ulteriori informazioni, vedere Associazione di dati ai controlli contenuto.
Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento e di applicazione per Word 2007 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.
.gif "Collegamento a video")
Per una dimostrazione video correlata, vedere Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0) (la pagina potrebbe essere in inglese).
Cenni preliminari sui controlli contenuto
I controlli contenuto forniscono un'interfaccia utente ottimizzata sia per l'input dell'utente che per la stampa. Quando si aggiunge un controllo contenuto a un documento, il controllo viene identificato da un bordo, un titolo e un testo temporaneo che può fornire istruzioni all'utente. Il bordo e il titolo del controllo non vengono visualizzati nelle versioni stampate del documento.
Ad esempio, se si desidera che l'utente immetta una data in una sezione del documento, è possibile aggiungere un controllo contenuto di selezione data al documento. Quando gli utenti fanno clic sul controllo, viene visualizzata l'interfaccia utente di selezione data standard. È anche possibile configurare le proprietà del controllo in modo da impostare il calendario regionale visualizzato e specificare il formato della data. Dopo che l'utente sceglie una data, l'interfaccia utente del controllo è nascosta e se l'utente stampa il documento viene stampata solo la data.
I controlli contenuto consentono anche di eseguire le operazioni seguenti:
Impedire agli utenti di modificare o eliminare parti del documento. Ciò risulta utile se si hanno informazioni in un documento o un modello che gli utenti devono essere in grado di leggere ma non di modificare o se si desidera che gli utenti siano in grado di modificare i controlli contenuto ma non di eliminarli.
Associare parti di un documento o di un modello ai dati. È possibile associare i controlli contenuto a campi del database, oggetti gestiti in .NET Framework, elementi XML memorizzati nel documento e altre origini dati.
Nei progetti a livello di documento, è possibile aggiungere controlli contenuto al documento in fase di progettazione o di esecuzione. Nei progetti a livello di applicazione, è possibile aggiungere controlli del contenuto a qualsiasi documento aperto in fase di esecuzione. Per ulteriori informazioni, vedere Procedura: aggiungere controlli del contenuto ai documenti di Word.
Nota
È possibile utilizzare i controlli del contenuto solo nei documenti salvati nel formato Open XML. Non è possibile utilizzare i controlli del contenuto nei documenti salvati nel formato documento di Word 97-2003 (doc).
Tipi di controlli contenuto
Esistono nove tipi diversi di controlli contenuto che è possibile aggiungere ai documenti. La maggior parte dei controlli contenuto ha un tipo corrispondente nello spazio dei nomi Microsoft.Office.Tools.Word. È anche possibile utilizzare un oggetto ContentControl generico, che può rappresentare qualsiasi controllo contenuto disponibile. Per una procedura dettagliata che dimostri come utilizzare ognuno dei controlli contenuto disponibile, vedere Procedura dettagliata: creazione di un modello utilizzando i controlli del contenuto.
Raccolta di blocchi predefiniti
Una raccolta di blocchi predefiniti consente agli utenti di selezionare un blocco da un elenco di blocchi predefiniti del documento da inserire in un documento. Un blocco predefinito del documento è un elemento di contenuto creato per essere utilizzato più volte, ad esempio un frontespizio comune, una tabella formattata o un'intestazione. Per ulteriori informazioni, vedere il tipo BuildingBlockGalleryContentControl. Per ulteriori informazioni sui blocchi predefiniti, vedere Novità per gli sviluppatori in Word 2007.
Casella di controllo
Una casella di controllo fornisce un'interfaccia utente che rappresenta uno stato binario: selezionato o deselezionato. Questo tipo di controllo contenuto è disponibile solo in Word 2010.
A differenza degli altri tipi di controlli contenuto, Runtime di Visual Studio Tools per Office non fornisce un tipo specifico che rappresenta un controllo contenuto della casella di controllo. In altre parole, non esiste un tipo CheckBoxContentControl. È comunque possibile creare un controllo contenuto della casella di controllo aggiungendo un oggetto ContentControl generico a un documento a livello di codice. Per ulteriori informazioni, vedere Controlli contenuto della casella di controllo nei progetti di Word 2010.
Casella combinata
Una casella combinata visualizza un elenco di elementi che gli utenti possono selezionare. A differenza di un elenco a discesa, la casella combinata consente agli utenti di aggiungere elementi. Per ulteriori informazioni, vedere il tipo ComboBoxContentControl.
Selezione data
Una selezione data fornisce un'interfaccia utente del calendario per la selezione di una data. Quando l'utente finale fa clic sulla freccia a discesa del controllo, viene visualizzato il calendario. È possibile utilizzare calendari regionali e formati della data diversi. Per ulteriori informazioni, vedere il tipo DatePickerContentControl.
Elenco a discesa
Un elenco a discesa visualizza un elenco di elementi che gli utenti possono selezionare. A differenza di una casella combinata, l'elenco a discesa non consente agli utenti di aggiungere o modificare elementi. Per ulteriori informazioni, vedere il tipo DropDownListContentControl.
Gruppo
Un controllo di gruppo definisce una regione protetta di un documento che gli utenti non possono modificare o eliminare. Un controllo di gruppo può contenere qualsiasi elemento del documento, ad esempio testo, tabelle, grafica e altri controlli contenuto. Per ulteriori informazioni, vedere il tipo GroupContentControl.
Foto
Un controllo immagine consente di visualizzare un'immagine. È possibile specificare l'immagine in fase di progettazione o di esecuzione. In alternativa è possibile fare clic su questo controllo per selezionare un'immagine da inserire nel documento. Per ulteriori informazioni, vedere il tipo PictureContentControl.
Formato RTF
Un controllo RTF contiene testo o altri elementi, ad esempio tabelle, immagini o altri controlli contenuto. Per ulteriori informazioni, vedere il tipo RichTextContentControl.
Testo normale
Un controllo di testo normale contiene testo. Un controllo di testo normale non può contenere altri elementi, ad esempio tabelle, immagini o altri controlli contenuto. In aggiunta, tutto il testo in un controllo di testo normale ha la stessa formattazione. Ad esempio, se si applica il corsivo a una parola di una frase che si trova in un controllo di testo normale, tutto il testo del controllo viene formattato in corsivo. Per ulteriori informazioni, vedere il tipo PlainTextContentControl.
Controllo contenuto generico
Un controllo contenuto generico è un oggetto ContentControl che può rappresentare uno qualsiasi dei tipi di controlli contenuto disponibili. È possibile modificare un oggetto ContentControl in modo che si comporti come un tipo diverso di controllo contenuto utilizzando la proprietà Type. Ad esempio, se si crea un oggetto ContentControl che rappresenta un controllo di testo normale, è possibile modificarlo in fase di esecuzione in modo che si comporti come una casella combinata.
È possibile creare oggetti ContentControl solo in fase di esecuzione, non in fase di progettazione. Per ulteriori informazioni, vedere Procedura: aggiungere controlli del contenuto ai documenti di Word.
Funzionalità comuni dei controlli contenuto
La maggior parte dei controlli del contenuto condivide un set di membri che è possibile utilizzare per eseguire attività comuni. Nella tabella riportata di seguito vengono descritte alcune attività che è possibile eseguire utilizzando tali membri.
Per questa attività: |
Eseguire questa operazione: |
|---|---|
Ottenere o impostare il testo visualizzato nel controllo. |
Utilizzare la proprietà Text. .gif "Nota") Nota
I tipi PictureContentControl e ContentControl non dispongono di questa proprietà.
|
Ottenere o impostare il testo temporaneo visualizzato nel controllo fino a quando un utente modifica il controllo, il controllo viene popolato con i dati da un'origine dati o il contenuto del controllo viene eliminato. |
Utilizzare la proprietà PlaceholderText. Nota
Il tipo PictureContentControl non dispone di questa proprietà.
|
Ottenere o impostare il titolo visualizzato nel bordo del controllo contenuto quando l'utente fa clic su di esso. |
Utilizzare la proprietà Title. |
Rimuovere automaticamente il controllo dal documento dopo che l'utente ha modificato il controllo. Il testo del controllo rimane nel documento. |
Utilizzare la proprietà Temporary. |
Eseguire codice quando l'utente fa clic nel controllo contenuto o quando il cursore viene spostato a livello di codice nel controllo contenuto. |
Gestire l'evento Entering del controllo. |
Eseguire codice quando l'utente fa clic all'esterno del controllo contenuto o quando il cursore viene spostato all'esterno del controllo contenuto a livello di codice. |
Gestire l'evento Exiting del controllo. |
Eseguire codice dopo che il controllo contenuto viene aggiunto al documento come risultato di una fase di rollforward o di un'operazione di annullamento. |
Gestire l'evento Added del controllo. |
Eseguire codice poco prima che il controllo contenuto venga eliminato dal documento. |
Gestire l'evento Deleting del controllo. |
Protezione di parti dei documenti mediante i controlli contenuto
Quando si protegge una parte di un documento, si impedisce agli utenti di modificare o eliminare il contenuto in quella parte del documento. Esistono diversi modi per proteggere parti di un documento utilizzando i controlli contenuto.
Se l'area che si desidera proteggere è all'interno di un controllo contenuto, è possibile utilizzare le proprietà del controllo contenuto per impedire agli utenti di modificare o eliminare il controllo:
La proprietà LockContents impedisce agli utenti di modificare il contenuto.
La proprietà LockContentControl impedisce agli utenti di eliminare il controllo.
Se l'area che si desidera proteggere non è all'interno di un controllo contenuto o se si desidera proteggere un'area che contiene controlli contenuto e altri tipi di contenuto, è possibile inserire l'area intera in un oggetto GroupContentControl. A differenza degli altri controlli contenuto, un oggetto GroupContentControl non fornisce un'interfaccia utente visibile all'utente. Il suo unico scopo è definire un'area che gli utenti non possono modificare.
Nota
Se si crea un oggetto GroupContentControl che contiene controlli contenuto incorporati, i controlli contenuto incorporati non vengono protetti automaticamente. È necessario utilizzare la proprietà LockContents di ogni controllo incorporato per impedire agli utenti di modificare il contenuto.
Per ulteriori informazioni sull'utilizzo dei controlli contenuto per proteggere parti dei documenti, vedere Procedura: proteggere parti di documenti mediante i controlli del contenuto.
Associazione di dati ai controlli contenuto
È possibile visualizzare dati nei documenti associando un controllo contenuto a un'origine dati. Quando l'origine dati viene aggiornata, il controllo contenuto rifletterà le modifiche. È anche possibile salvare nell'origine dati le modifiche apportate nel controllo contenuto.
I controlli contenuto forniscono le opzioni di associazione dati seguenti:
È possibile associare i controlli contenuto a campi o oggetti gestiti del database utilizzando lo stesso modello di associazione dati di Windows Form.
È possibile associare i controlli contenuto agli elementi in parti di XML (denominate anche web part XML personalizzate) che sono incorporate nel documento.
Per informazioni generali sull'associazione di controlli host nelle soluzioni Office ai dati, vedere Associazione di dati ai controlli nelle soluzioni Office.
Utilizzo del modello di associazione dati di Windows Form
La maggior parte dei controlli contenuto supporta il modello di associazione dati semplice utilizzato da Windows Form. L'associazione dati semplice si verifica quando un controllo viene associato a un singolo elemento di dati, come un valore in una colonna di una tabella dati. Per ulteriori informazioni, vedere Associazione dati e Windows Form.
Nei progetti a livello di documento, è inoltre possibile associare dati ai controlli del contenuto utilizzando la finestra Origini dati in Visual Studio. Per ulteriori informazioni sull'aggiunta di controlli del contenuto associati a dati ai documenti, vedere Procedura: popolare documenti con dati da un database e Procedura: compilare documenti con dati da oggetti.
Nella tabella seguente sono elencati i controlli contenuto che è possibile associare a ogni tipo di dati nella finestra Origini dati.
Tipo di dati |
Controllo contenuto predefinito |
Altri controlli contenuto associabili a questo tipo di dati |
|---|---|---|
|
Matrice Byte |
Nessuno |
Nei progetti a livello di documento e a livello di applicazione, è possibile inoltre associare un controllo del contenuto a un'origine dati a livello di codice utilizzando il metodo Add() della proprietà DataBindings del controllo. In questo caso, passare la stringa Text al parametro propertyName del metodo Add(). La proprietà Text è la proprietà di associazione dati predefinita dei controlli contenuto.
I controlli contenuto supportano anche l'associazione dati bidirezionale, nella quale le modifiche nel controllo vengono aggiornate nell'origine dati. Per ulteriori informazioni, vedere Procedura: aggiornare un'origine dati con i dati inviati da un controllo host.
Nota
I controlli contenuto non supportano l'associazione dati complessa. Se si associa un oggetto DropDownListContentControl o ComboBoxContentControl a un'origine dati utilizzando il modello di dati di Windows Form, gli utenti vedranno un solo valore quando fanno clic sul controllo. Se si desidera associare questi controlli a un insieme di valori di dati da cui gli utenti possono scegliere, è possibile associare questi controlli agli elementi in una web part XML personalizzata.
Associazione dei controlli contenuto a web part XML personalizzate
È possibile associare alcuni controlli contenuto agli elementi in web part XML personalizzate che sono incorporate nel documento. Per ulteriori informazioni sulle web part XML personalizzate, vedere Cenni preliminari sulle web part XML personalizzate.
Per associare un controllo contenuto a un elemento in una web part XML personalizzata, utilizzare la proprietà XMLMapping del controllo. Nell'esempio di codice seguente viene mostrato come associare un oggetto PlainTextContentControl all'elemento Price sotto il nodo Product in una web part XML personalizzata che è già stata aggiunta al documento.
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);
Per una procedura dettagliata che illustri in maggiore dettaglio come associare i controlli contenuto alle web part XML personalizzate, vedere Procedura dettagliata: associazione dei controlli del contenuto a parti XML personalizzate.
Quando si associa un controllo contenuto a una web part XML personalizzata, l'associazione dati bidirezionale viene attivata automaticamente. Se un utente modifica il testo del controllo, gli elementi XML corrispondenti vengono aggiornati automaticamente. Analogamente, se i valori degli elementi nelle web part XML personalizzate vengono modificati, i controlli contenuto associati agli elementi XML visualizzeranno i nuovi dati.
È possibile associare i tipi seguenti di controlli contenuto alle web part XML personalizzate:
Eventi di associazione dati per i controlli contenuto
Tutti i controlli contenuto forniscono un insieme di eventi che è possibile gestire per eseguire attività relative ai dati, ad esempio verificare che il testo in un controllo soddisfi determinati criteri prima che l'origine dati venga aggiornata. Nella tabella riportata di seguito sono elencati gli eventi dei controlli contenuto correlati all'associazione dati.
Attività |
Evento |
|---|---|
Eseguire il codice poco prima che Word aggiorni automaticamente il testo in un controllo contenuto associato a una web part XML personalizzata. |
|
Eseguire il codice poco prima che Word aggiorni automaticamente i dati in una web part XML personalizzata associata a un controllo contenuto, vale a dire dopo la modifica del testo nel controllo contenuto. |
|
Eseguire codice personalizzato per convalidare il contenuto del controllo secondo criteri personalizzati. |
|
Eseguire il codice dopo che il contenuto del controllo sia stato convalidato correttamente. |
Limiti dei controlli contenuto
Quando si utilizzano i controlli del contenuto nei progetti di Office, tenere presenti le limitazioni seguenti.
Differenze di comportamento tra la fase di progettazione e quella di esecuzione
Molte delle limitazioni che Microsoft Office Word impone sui controlli contenuto in fase di esecuzione non vengono applicate in fase di progettazione. Quando si progetta l'interfaccia utente di una soluzione a livello di documento in Visual Studio, assicurarsi di modificare i controlli del contenuto solo con le modalità supportate in fase di esecuzione.
Se in fase di progettazione si modifica un controllo contenuto con modalità che il controllo non supporta in fase di esecuzione, la finestra di progettazione di Visual Studio non avviserà delle modifiche non supportate. Tuttavia, quando si esegue il debug o si esegue il progetto, o se si salva e quindi si riapre il progetto, Word visualizzerà un messaggio di errore e richiederà l'autorizzazione per ripristinare il documento. Quando si ripristina il documento, tutto il contenuto e la formattazione non supportati verranno rimossi dal controllo.
Ad esempio, Word non impedisce di aggiungere una tabella a un oggetto PlainTextContentControl in fase di progettazione. Tuttavia, poiché gli oggetti PlainTextContentControl non possono contenere tabelle in fase di esecuzione, in Word verrà visualizzato un messaggio di errore quando il documento viene aperto.
Si noti inoltre che molte proprietà che definiscono il comportamento dei controlli contenuto non hanno effetto in fase di progettazione. Ad esempio, se si imposta la proprietà LockContents di un controllo contenuto su True in fase di progettazione, è comunque possibile modificare il testo del controllo nella finestra di progettazione di Visual Studio. Questa proprietà impedisce agli utenti solo di modificare il controllo in fase di esecuzione.
Limitazioni relative agli eventi
I controlli contenuto non forniscono un evento che viene generato quando l'utente modifica il testo o gli altri elementi del controllo. Ad esempio, non viene generato alcun evento quando un utente seleziona un elemento diverso in un oggetto DropDownListContentControl o ComboBoxContentControl.
Per determinare quando un utente modifica il contenuto di un controllo contenuto, è possibile associare il controllo a una web part XML personalizzata e quindi gestire l'evento StoreUpdating. Questo evento viene generato quando l'utente modifica il contenuto di un controllo associato a una web part XML personalizzata. Per una procedura dettagliata che illustri come associare un controllo contenuto a una web part XML personalizzata, vedere Procedura dettagliata: associazione dei controlli del contenuto a parti XML personalizzate.
Controlli contenuto della casella di controllo nei progetti di Word 2010
In Word 2010 è stato introdotto un nuovo tipo di controllo contenuto che rappresenta una casella di controllo. In Runtime di Visual Studio Tools per Office, tuttavia, non viene fornito un tipo CheckBoxContentControl corrispondente per l'utilizzo nei progetti di Office. Per creare un controllo contenuto della casella di controllo in un progetto di Word 2010, utilizzare il metodo AddContentControl per creare un oggetto Microsoft.Office.Tools.Word.ContentControl e passare il valore wdContentControlCheckBox al metodo per specificare un controllo contenuto della casella di controllo. Nell'esempio di codice riportato di seguito viene illustrato come procedere.
Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)
' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True
' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True
this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 =
this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);
// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;
// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;
Nota
La proprietà Checked degli oggetti Microsoft.Office.Tools.Word.ContentControl può essere utilizzata direttamente solo nei progetti destinati a .NET Framework 4. Nei progetti destinati a .NET Framework 3.5, è necessario utilizzare la proprietà InnerObject per accedere alla proprietà Checked dell'oggetto Microsoft.Office.Interop.Word.ContentControl sottostante. Per ulteriori informazioni, vedere Limitazioni a livello di codice degli elementi e dei controlli host.
Vedere anche
Attività
Procedura: aggiungere controlli del contenuto ai documenti di Word
Procedura dettagliata: creazione di un modello utilizzando i controlli del contenuto
Concetti
Automazione di Word utilizzando oggetti estesi
Limitazioni a livello di codice degli elementi e dei controlli host