Programmare personalizzazioni a livello di documento

  • Articolo

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

  • Automazione dell'applicazione con il relativo modello a oggetti

  • Aggiunta di controlli all'area di un documento

  • Chiamata a codice Visual Basic, Applications Edition (VBA) contenuto nel documento dall'assembly di personalizzazione

  • Chiamata a codice contenuto nell'assembly di personalizzazione da VBA

  • Gestione di determinati aspetti di un documento anche se si trova in un server in cui non è stato installato Microsoft Office

  • Personalizzazione dell'interfaccia utente di un'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 app Office lication e tipo di progetto.

    Alcuni aspetti della scrittura del codice nei progetti a livello di documento presentano delle differenze rispetto ad altri tipi di progetti in Visual Studio. Molte di queste differenze sono causate dalla modalità di esposizione dei modelli a oggetti di Office 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, in Visual Studio viene generata automaticamente nel progetto una classe utilizzabile come base iniziale di scrittura del codice. Visual Studio genera classi differenti per Word ed Excel:

  • Per impostazione predefinita, nei progetti a livello di documento di Word la classe viene denominata ThisDocument .

  • Per i progetti a livello di documento di Excel vengono generate più classi: una per la cartella di lavoro e una per ogni foglio di lavoro. Per impostazione predefinita, queste classi vengono denominate come segue:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    La classe generata contiene gestori eventi che vengono chiamati quando il documento viene aperto o chiuso. Per eseguire il codice all'apertura del documento, aggiungerlo nel gestore dell'evento Startup . Per eseguire il codice subito prima della chiusura del documento, aggiungerlo al gestore dell'evento Shutdown . 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 nella Strumenti di Visual Studio per il runtime di Office sono interfacce, quindi le classi generate non possono derivarne l'implementazione. Al contrario, le classi generate derivano la maggior parte dei loro membri dalle classi base seguenti:

  • ThisDocument: deriva da DocumentBase.

  • ThisWorkbook: deriva da WorkbookBase.

  • Sheetn: deriva da WorksheetBase.

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

Accedere al modello a oggetti dell'applicazione host

Per accedere al modello a oggetti dell'applicazione host occorre usare i membri della classe generata nel progetto. Ognuna di queste classi corrisponde a un oggetto nel modello a oggetti di Excel o Word. In particolare, le classi sono quasi identiche in termini di proprietà, metodi ed eventi. Ad esempio, la classe ThisDocument di un progetto a livello di documento di Word fornisce la maggior parte dei membri disponibili nell'oggetto Document del modello a oggetti di Word.

L'esempio di codice seguente illustra come usare il modello a oggetti di Word per salvare il documento appartenente a una personalizzazione a livello di documento di Word. Questo esempio è destinato a essere eseguito dalla classe ThisDocument .

this.Save();

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

Globals.ThisDocument.Save();

Dal momento che la classe ThisDocument ottiene la maggior parte dei suoi membri dall'elemento host Document , il metodo Save chiamato in questo codice è di fatto il metodo Save dell'elemento host Document . Questo metodo corrisponde al metodo Save dell'oggetto Document del 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 di un documento è possibile aggiungere controlli Windows Form o controlli host all'area del documento. Con la combinazione di set di controlli diversi e con la scrittura di codice, è possibile associare i controlli ai dati, raccogliere le informazioni relative all'utente e rispondere alle azioni utente.

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

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

Combinare personalizzazioni a livello di documento e VBA

È possibile usare codice VBA in un documento appartenente a una personalizzazione a livello di documento. È possibile chiamare codice VBA nel documento dall'assembly di personalizzazione e anche configurare il progetto in modo da consentire al codice VBA nel documento di chiamare il codice nell'assembly di personalizzazione.

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

Gestire i documenti in un server

Diversi aspetti della personalizzazione a livello di documento possono essere gestiti anche nei server in cui non è stato installato Microsoft Office Word oppure Microsoft Office Excel. È ad esempio possibile accedere e apportare modifiche ai dati memorizzati nella cache dei dati di un documento. È anche possibile gestire l'assembly di personalizzazione associato al documento. Ad esempio, è possibile rimuovere a livello di codice l'assembly da un documento in modo che quest'ultimo non esegua più il codice.

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

Personalizzare l'interfaccia utente delle app Office licazioni Microsoft

È 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 degli eventi di Office ricevono un oggetto nativo di Office che rappresenta la cartella di lavoro, il foglio di lavoro o il documento che ha generato l'evento. In alcuni casi, è necessario eseguire il codice solo se l'evento è stato generato dalla cartella di lavoro o dal documento della personalizzazione a livello di documento. Ad esempio, in una personalizzazione a livello di documento per Excel, è necessario eseguire il codice quando l'utente attiva uno dei fogli di lavoro nella cartella di lavoro personalizzata, ma non quando l'utente attiva un foglio di lavoro in altre cartelle di lavoro che possono essere aperte contemporaneamente.

Quando è presente un oggetto nativo di Office, è possibile verificare se tale oggetto è stato esteso in un elemento host o in un controllo host di una personalizzazione a livello di documento. Gli elementi host e i controlli host sono tipi forniti dal runtime di Strumenti di Visual Studio 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 controlli host vengono definiti 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 eseguire il test di un oggetto nativo di Office, usare i metodi HasVstoObject e GetVstoObjectnel progetto:

  • Se si vuole determinare se l'oggetto nativo di Office ha un oggetto esteso nella personalizzazione, usare il metodo HasVstoObject. Questo metodo restituisce true se l'oggetto nativo di Office ha un oggetto esteso, altrimenti false .

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

    Nei progetti a livello di documento non è possibile usare il GetVstoObject metodo per creare un nuovo Workbookelemento host , Worksheeto in Document fase di esecuzione. Tale metodo può essere usato 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 il HasVstoObject metodo e GetVstoObject , utilizzare il Globals.Factory.GetVstoObject metodo o Globals.Factory.HasVstoObject e passare l'oggetto nativo di Word o Excel ,ad esempio o DocumentWorksheet, che si desidera testare.

Contenuto correlato