Condividi tramite

Programmare personalizzazioni a livello di documento

Quando si estende Microsoft Office Word o Microsoft Office Excel utilizzando una personalizzazione a livello di documento, è possibile eseguire le attività seguenti:

  • Automatizzare l'applicazione usando il relativo modello a oggetti.

  • Aggiungere controlli alla superficie del documento.

  • Chiamare il codice di Visual Basic for Applications (VBA) nel documento dall'assembly di personalizzazione.

  • Chiamare il codice nell'assembly di personalizzazione da VBA.

  • Gestire alcuni aspetti del documento mentre si trova in un server in cui non è installato Microsoft Office.

  • Personalizzare l'interfaccia utente dell'applicazione.

    Si applica a: Le informazioni contenute in questo argomento si applicano ai progetti a livello di documento per Excel e Word. Per altre informazioni, vedere Funzionalità disponibili per l'applicazione e il tipo di progetto di Office.

    Alcuni aspetti della scrittura di codice nei progetti a livello di documento sono diversi da altri tipi di progetti in Visual Studio. Molte di queste differenze sono causate dal modo in cui i modelli a oggetti di Office vengono esposti al codice gestito. Per altre informazioni, vedere Scrivere codice nelle soluzioni Office.

    Per informazioni generali sulle personalizzazioni a livello di documento e su altri tipi di soluzioni che è possibile creare usando gli strumenti di sviluppo di Office in Visual Studio, vedere Panoramica dello sviluppo di soluzioni Office (VSTO).

Usare le classi generate nei progetti a livello di documento

Quando si crea un progetto a livello di documento, Visual Studio genera automaticamente una classe nel progetto che è possibile usare per iniziare a scrivere il codice. Visual Studio genera classi diverse per Word ed Excel:

  • Nei progetti a livello di documento per Word, la classe viene chiamata ThisDocument per impostazione predefinita.

  • I progetti a livello di documento per Excel hanno più classi generate: una per la cartella di lavoro stessa e una per ogni foglio di lavoro. Per impostazione predefinita, queste classi hanno i nomi seguenti:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    La classe generata include gestori eventi che vengono chiamati quando il documento viene aperto o chiuso. Per eseguire il codice all'apertura del documento, aggiungere codice al Startup gestore eventi. Per eseguire il codice subito prima della chiusura del documento, aggiungere codice al Shutdown gestore eventi. Per altre informazioni, vedere Eventi nei progetti di Office.

Comprendere la progettazione delle classi generate

Nei progetti destinati a .NET Framework 4 o .NET Framework 4.5, i tipi di elemento host nel runtime di Visual Studio Tools per Office sono interfacce, quindi le classi generate non possono derivare l'implementazione da tali classi. Le classi generate derivano invece la maggior parte dei relativi membri dalle classi di base seguenti:

  • ThisDocument: deriva da DocumentBase.

  • ThisWorkbook: deriva da WorkbookBase.

  • Sheet n: deriva da WorksheetBase.

    Queste classi di base reindirizzano tutte le chiamate ai relativi membri alle implementazioni interne delle interfacce degli elementi host corrispondenti nel runtime di Visual Studio Tools per Office. Ad esempio, se si chiama il Protect metodo della ThisDocument classe , la DocumentBase classe reindirizza questa chiamata all'implementazione interna dell'interfaccia Document nel runtime di Visual Studio Tools per Office .

Accedere al modello a oggetti dell'applicazione host

Per accedere al modello a oggetti dell'applicazione host, usare i membri della classe generata nel progetto. Ognuna di queste classi corrisponde a un oggetto nel modello a oggetti di Excel o Word e contiene la maggior parte delle stesse proprietà, metodi ed eventi. Ad esempio, la ThisDocument classe in un progetto a livello di documento per Word fornisce la maggior parte degli stessi membri dell'oggetto Document nel modello a oggetti di Word.

Nell'esempio di codice seguente viene illustrato come utilizzare il modello a oggetti di Word per salvare il documento che fa parte di una personalizzazione a livello di documento per Word. Questo esempio deve essere eseguito dalla ThisDocument classe .

this.Save();

Per eseguire la stessa operazione dall'esterno della ThisDocument classe, usare l'oggetto Globals per accedere alla ThisDocument classe . Ad esempio, puoi aggiungere questo codice a un file di codice del riquadro azioni se vuoi includere un pulsante Salva nell'interfaccia utente del riquadro azioni.

Globals.ThisDocument.Save();

Poiché la ThisDocument classe ottiene la maggior parte dei relativi membri dall'elemento Document host, il Save metodo chiamato in questo codice è in realtà il Save metodo dell'elemento Document host. Questo metodo corrisponde al Save metodo dell'oggetto Document nel modello a oggetti di Word.

Per altre informazioni sull'uso dei modelli a oggetti di Word ed Excel, vedere Panoramica del modello a oggetti di Word e Panoramica del modello a oggetti di Excel.

Per altre informazioni sull'oggetto Globals , vedere Accesso globale agli oggetti nei progetti di Office.

Aggiungere controlli ai documenti

Per personalizzare l'interfaccia utente del documento, è possibile aggiungere controlli Windows Form o controlli host all'area di documento. Combinando diversi set di controlli e scrivendo codice, è possibile associare i controlli ai dati, raccogliere informazioni dall'utente e rispondere alle azioni dell'utente.

I controlli host sono classi che estendono alcuni degli oggetti nel modello a oggetti di Word ed Excel. Ad esempio, il ListObject controllo host fornisce tutte le funzionalità di ListObject in Excel. Tuttavia, il ListObject controllo host include anche eventi aggiuntivi e funzionalità di data binding.

Per altre informazioni, vedere Panoramica degli elementi host e dei controlli host e Panoramica dei controlli Windows Forms nei documenti di Office.

Combinare personalizzazioni a livello di documento e VBA

È possibile usare il codice VBA in un documento che fa parte di una personalizzazione a livello di documento. Puoi chiamare il codice VBA presente nel documento dall'assembly di personalizzazione e inoltre configurare il progetto per permettere al codice VBA nel documento di richiamare il codice nell'assembly di personalizzazione.

Per altre informazioni, vedere Combinare personalizzazioni a livello di documento e VBA.

Gestire i documenti in un server

È possibile gestire diversi aspetti delle personalizzazioni a livello di documento in un server in cui non è installato Microsoft Office Word o Microsoft Office Excel. Ad esempio, è possibile accedere e modificare i dati nella cache dei dati del documento. È anche possibile gestire l'assembly di personalizzazione associato al documento. Ad esempio, è possibile rimuovere a livello di codice l'assembly dal documento in modo che il documento non esegua più il codice oppure è possibile allegare un assembly a livello di codice a un documento.

Per altre informazioni, vedere Gestire documenti in un server tramite la classe ServerDocument.

Personalizzare l'interfaccia utente delle applicazioni di Microsoft Office

È possibile personalizzare l'interfaccia utente di Word ed Excel nei modi seguenti usando una personalizzazione a livello di documento:

Ottenere oggetti estesi dagli oggetti nativi di Office nelle personalizzazioni a livello di documento

Molti gestori eventi per gli eventi di Office ricevono un oggetto office nativo che rappresenta la cartella di lavoro, il foglio di lavoro o il documento che ha generato l'evento. In alcuni casi, è possibile eseguire codice solo se la cartella di lavoro o il documento nella personalizzazione a livello di documento ha generato l'evento. Ad esempio, in una personalizzazione del documento per Excel, è possibile eseguire del codice quando l'utente attiva uno dei fogli nella cartella di lavoro personalizzata, ma non quando attiva un foglio di lavoro in un'altra cartella che è già aperta contemporaneamente.

Quando si dispone di un oggetto Office nativo, è possibile verificare se tale oggetto è stato esteso in un elemento host o un controllo host in una personalizzazione a livello di documento. Gli elementi host e i controlli host sono tipi forniti dal runtime di Visual Studio Tools per Office che aggiungono funzionalità agli oggetti presenti in modo nativo nei modelli a oggetti di Word o Excel (denominati oggetti nativi di Office). Collettivamente, gli elementi host e i controlli host sono detti anche oggetti estesi. Per altre informazioni sugli elementi host e sui controlli host, vedere Panoramica degli elementi host e dei controlli host.

Informazioni sui metodi GetVstoObject e HasVstoObject

Per testare un oggetto Office nativo, usare i HasVstoObject metodi e GetVstoObject nel progetto:

  • Utilizzare il metodo HasVstoObject se desiderate determinare se l'oggetto nativo di Office dispone di un oggetto esteso nelle personalizzazioni. Questo metodo restituisce true se l'oggetto nativo di Office ha un oggetto esteso e false in caso contrario.

  • Utilizzare il GetVstoObject metodo se si desidera ottenere l'oggetto esteso per un oggetto Office nativo. Questo metodo restituisce un ListObjectoggetto , Workbook, Worksheeto Document se l'oggetto office nativo specificato ne ha uno. In caso contrario, GetVstoObject restituisce null. Ad esempio, il metodo GetVstoObject restituisce un Document se l'oggetto specificato Document è l'oggetto sottostante per il documento nel progetto di documento Word.

    Nei progetti a livello di documento, non è possibile usare il metodo GetVstoObject per creare un nuovo Workbook, Worksheet o Document elemento host durante l'esecuzione. È possibile usare questo metodo solo per accedere agli elementi host esistenti generati nel progetto in fase di progettazione. Se si desidera creare nuovi elementi host in fase di esecuzione, è necessario sviluppare un progetto di componente aggiuntivo VSTO. Per altre informazioni, vedere Limitazioni a livello di codice degli elementi host e dei controlli host e Estensione di documenti di Word e cartelle di lavoro di Excel nei componenti aggiuntivi VSTO in fase di esecuzione.

Usare i metodi GetVstoObject e HasVstoObject

Per chiamare i metodi HasVstoObject e GetVstoObject, utilizzare il metodo Globals.Factory.GetVstoObject o Globals.Factory.HasVstoObject e passare l'oggetto nativo di Word o Excel, ad esempio un Document o Worksheet, che si desidera testare.

Contenuti correlati

  • Last updated on