Panoramica degli elementi host e dei controlli host
Gli elementi e i controlli host sono tipi che consentono di fornire il modello di programmazione per le soluzioni Office create tramite gli strumenti di sviluppo di Office in Visual Studio. Rendono l'interazione con i modelli a oggetti di Microsoft Office Word e Microsoft Office Excel, basati su COM, analoga all'interazione con gli oggetti gestiti, ad esempio i controlli Windows Form.
Si applica a: le informazioni contenute in questo argomento si applicano ai progetti a livello di documento e ai progetti di componente aggiuntivo VSTO per Excel e Word. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.
Elementi host
Gli elementi host sono tipi che si trovano al livello più elevato delle gerarchie del modello a oggetti nei progetti di Office. Il runtime di Strumenti di Visual Studio per Office definisce gli elementi host seguenti per le soluzioni Word ed Excel:
-
Ognuno di questi tipi estende un oggetto presente a livello nativo nel modello a oggetti di Word o Excel, denominato oggetto nativo di Office. Ad esempio, l'elemento host Document estende l'oggetto Document , definito nell'assembly di interoperabilità primario per Word.
Gli elementi host hanno generalmente la stessa funzionalità di base degli oggetti Office corrispondenti, ma sono potenziati con le funzionalità seguenti:
Possibilità di ospitare i controlli gestiti, inclusi i controlli host e quelli Windows Form.
Modelli di eventi più ricchi. Alcuni eventi relativi a documenti, cartelle di lavoro e fogli di lavoro nei modelli a oggetti nativi di Word ed Excel vengono generati soltanto a livello di applicazione. Gli elementi host forniscono questi eventi a livello di documento, in modo che sia più semplice gestire gli eventi per un documento specifico.
Informazioni sugli elementi host nei progetti a livello di documento
Nei progetti a livello di documento, gli elementi host forniscono un punto di ingresso per il codice e contengono finestre di progettazione che consentono di sviluppare la soluzione.
Gli elementi host Document e Worksheet contengono finestre di progettazione associate che rappresentano visivamente il documento o il foglio di lavoro, in maniera analoga a quanto avviene per una finestra di progettazione di Windows Form. Questa finestra di progettazione può essere usata per modificare il contenuto del documento o del foglio di lavoro direttamente in Word o Excel e per trascinare i controlli nell'area di progettazione. Per altre informazioni, vedere Elemento host del documento e elemento host foglio di lavoro.
L'elemento host Workbook non funge da contenitore per i controlli che hanno un'interfaccia utente. La finestra di progettazione per questo elemento host funge invece da barra dei componenti che consente il trascinamento di un componente, ad esempio DataSet, nell'area di progettazione. Per altre informazioni, vedere Elemento host della cartella di lavoro.
Non è possibile creare elementi host a livello di codice nei progetti a livello di documento. Al contrario, si possono usare le classi ThisDocument, ThisWorkbooko Sheetn , generate automaticamente da Visual Studio nel progetto in fase di progettazione. Queste classi generate derivano dagli elementi host e forniscono un punto di ingresso per il codice. Per altre informazioni, vedere Limitazioni a livello di codice degli elementi host e dei controlli host.
Informazioni sugli elementi host nei progetti di componente aggiuntivo VSTO
Quando si crea un componente aggiuntivo VSTO, per impostazione predefinita non si ha accesso ad alcun elemento host. Tuttavia, è possibile generare gli elementi host Document, Workbooke Worksheet nei componenti aggiuntivi VSTO di Word e di Excel in fase di esecuzione.
Dopo aver generato un elemento host, è possibile eseguire attività quali l'aggiunta di controlli ai documenti. Per altre informazioni, vedere Estendere documenti di Word e cartelle di lavoro di Excel nei componenti aggiuntivi VSTO in fase di esecuzione.
Controlli host
I controlli host consentono di estendere vari oggetti dell'interfaccia utente nei modelli a oggetti di Word ed Excel, ad esempio gli oggetti Microsoft.Office.Interop.Word.ContentControl e Range.
Per i progetti Excel sono disponibili i controlli host seguenti:
-
Per i progetti Word sono disponibili i controlli host seguenti:
-
I controlli host aggiunti ai documenti di Office si comportano come gli oggetti nativi di Office, ma dispongono di funzionalità aggiuntive che includono eventi e funzionalità di data binding. Ad esempio, per acquisire gli eventi di un oggetto Range nativo in Excel, è necessario per prima cosa gestire l'evento di modifica del foglio di lavoro. Quindi, è necessario determinare se la modifica è avvenuta all'interno di Range. Il controllo host NamedRange contiene invece un evento Change che è possibile gestire direttamente.
La relazione tra un elemento host e i controlli host è simile alla relazione tra un Windows Form e i controlli Windows Form. Posizionare un controllo NamedRange in un elemento host Worksheet esattamente come si posiziona un controllo casella di testo in un oggetto Windows Form. L'illustrazione seguente mostra la relazione tra elementi host e controlli host.
È anche possibile usare i controlli Windows Form nelle soluzioni Office aggiungendoli direttamente nell'area del documento di Word ed Excel. Per altre informazioni, vedere panoramica dei controlli Windows Form nei documenti di Office.
Nota
L'aggiunta di controlli host o di controlli Windows Form a un documento secondario di Word non è supportata.
Aggiungere controlli host ai documenti
Nei progetti a livello di documento è possibile aggiungere controlli host ai documenti di Word o ai fogli di lavoro di Excel in fase di progettazione nei modi seguenti:
Aggiungere i controlli host a un documento in fase di progettazione nello stesso modo in cui si aggiunge un oggetto nativo.
Trascinare i controlli host dalla Casella degli strumenti nei documenti e nei fogli di lavoro. I controlli host di Excel sono disponibili nella scheda Controlli Excel dei progetti Excel, mentre i controlli host di Word sono disponibili nella scheda Controlli Word dei progetti Word.
Trascinare i controlli host dalla finestra Origini dati nei documenti e nei fogli di lavoro. In questo modo è possibile aggiungere controlli già associati ai dati. Per altre informazioni, vedere Associare i dati ai controlli nelle soluzioni Office.
Nei progetti a livello di documento e in quelli di componenti aggiuntivi VSTO è anche possibile aggiungere alcuni controlli host ai documenti in fase di esecuzione. Per altre informazioni, vedere Aggiungere controlli ai documenti di Office in fase di esecuzione.
Per altre informazioni su come aggiungere i controlli host ai documenti, vedere gli argomenti seguenti:
Procedura: Aggiungere controlli ListObject ai fogli di lavoro
Procedura: Aggiungere controlli NamedRange ai fogli di lavoro
Procedura: Aggiungere controlli XMLMappedRange ai fogli di lavoro
Procedura: Aggiungere controlli Segnalibro ai documenti di Word
Procedura: Aggiungere controlli contenuto ai documenti di Word
Procedura: Aggiungere controlli XMLNode ai documenti di Word
Procedura: Aggiungere controlli XMLNodes ai documenti di Word
Controlli host dei nomi
Quando si trascina un controllo host dalla Casella degli strumenti nel documento, il controllo viene automaticamente denominato usando il tipo del controllo con un numero incrementale alla fine. I segnalibri saranno, ad esempio, denominati bookmark1, bookmark2e così via. Se si usa la funzionalità nativa di Word o Excel per aggiungere il controllo, è possibile assegnare un nome specifico al momento della creazione. È anche possibile rinominare i controlli modificando il valore della proprietà Name nella finestra Proprietà .
Nota
Nell'assegnazione di nomi ai controlli host non è possibile usare parole riservate. Se ad esempio si aggiunge un controllo NamedRange a un foglio di lavoro e si cambia il nome in System, si verificheranno degli errori durante la compilazione del progetto.
Eliminare i controlli host
Nei progetti a livello di documento è possibile eliminare i controlli host in fase di progettazione selezionando il controllo nel foglio di lavoro di Excel o nel documento di Word e premendo il tasto Elimina . Per eliminare i controlli in Excel è tuttavia necessario usare la finestra di dialogo Definisci nome NamedRange .
Se si aggiunge un controllo host a un documento in fase di progettazione, non rimuoverlo a livello di codice in fase di esecuzione perché al successivo tentativo di utilizzo del controllo nel codice verrà generata un'eccezione. Il metodo Delete di un controllo host rimuove solo i controlli host aggiunti al documento in fase di esecuzione. Se si chiama il metodo Delete di un controllo host creato in fase di progettazione, viene generata un'eccezione.
Ad esempio, il metodo Delete di un oggetto NamedRange consente di eliminare correttamente l'oggetto NamedRange solo se è stato aggiunto a livello di codice al foglio di lavoro, operazione nota come creazione di controlli host in modo dinamico. I controlli host creati dinamicamente possono essere rimossi anche passando il nome del controllo al metodo Remove della proprietà Controls o Controls . Per altre informazioni, vedere Aggiungere controlli ai documenti di Office in fase di esecuzione.
Se un utente finale elimina un controllo host dal documento in fase di esecuzione, la soluzione potrebbe non riuscire con risultati imprevisti. Per proteggere i controlli host dall'eliminazione è possibile usare le funzionalità di protezione dei documenti. Per altre informazioni, vedere Esempi di sviluppo di Office e procedure dettagliate.
Nota
Non rimuovere i controlli a livello di codice usando il gestore eventi Shutdown del documento o del foglio di lavoro. Gli elementi dell'interfaccia utente non sono più disponibili quando si verifica l'evento Shutdown . Se si vogliono rimuovere i controlli prima della chiusura dell'applicazione, aggiungere il codice a un altro gestore eventi, ad esempio BeforeClose o BeforeSave.
Programmare gli eventi di controllo host
Uno dei modi in cui i controlli host estendono gli oggetti Office è tramite l'aggiunta di eventi. Ad esempio, l'oggetto in Excel e Bookmark l'oggetto Range in Word non hanno eventi, ma il Strumenti di Visual Studio per il runtime di Office estende questi oggetti aggiungendo eventi programmabili. È possibile accedere a questi eventi e codificarli nello stesso modo in cui si accede agli eventi dei controlli presenti in Windows Form, ovvero tramite l'elenco a discesa degli eventi di Visual Basic e la pagina delle proprietà degli eventi in C#. Per altre informazioni, vedere Procedura dettagliata: Programma sugli eventi di un controllo NamedRange.
Nota
Non è necessario impostare la proprietà EnableEvents dell'oggetto Application in Excel su false. Impostando questa proprietà su false si impedisce a Excel di generare eventi, inclusi gli eventi dei controlli host.
Contenuto correlato
- Limitazioni a livello di codice degli elementi host e dei controlli host
- Programmare componenti aggiuntivi VSTO
- Programmare personalizzazioni a livello di documento
- Automatizzare Word usando oggetti estesi
- Automatizzare Excel usando oggetti estesi
- Controlli nei documenti di Office
- Associare i dati ai controlli nelle soluzioni Office