Cenni preliminari sul modello a oggetti di Word

Aggiornamento: Luglio 2008

Si applica a
Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati. Tipo di progetto Progetti a livello di documento Progetti a livello di applicazione Versione Microsoft Office Word 2003 Word 2007 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Per sviluppare soluzioni Visual Studio Tools per Office per Microsoft Office Word è possibile interagire con il modello a oggetti di Word. Questo modello a oggetti è costituito da classi e interfacce fornite nell'assembly di interoperabilità primario per Word ed è definito nello spazio dei nomi Microsoft.Office.Interop.Word.

In questo argomento vengono descritti gli aspetti seguenti dell'utilizzo del modello a oggetti di Word:

• Informazioni sul modello a oggetti di Word

• Oggetti estesi nei progetti di Visual Studio Tools per Office

• Utilizzo della documentazione sul modello a oggetti di Word

Per informazioni sull'utilizzo del modello a oggetti di Word per eseguire attività nei progetti Visual Studio Tools per Office, vedere gli argomenti seguenti:

• Utilizzo dei documenti

• Utilizzo del testo nei documenti

• Utilizzo delle tabelle

Informazioni sul modello a oggetti di Word

In Word sono disponibili centinaia di oggetti con cui interagire. Questi oggetti sono organizzati in una gerarchia che corrisponde strettamente all'interfaccia utente. All'inizio della gerarchia vi è l'oggetto Application. Questo oggetto rappresenta l'istanza corrente di Word. L'oggetto Application contiene gli oggetti Document, Selection, Bookmark e Range. Ciascuno di questi oggetti dispone di numerosi metodi e proprietà a cui è possibile accedere per modificarli e interagire con essi.

Nell'illustrazione seguente viene mostrata una visualizzazione di questi oggetti nella gerarchia del modello a oggetti di Word.

Riepilogo del modello a oggetti di Word

A prima vista sembra che vi siano molte sovrapposizioni. Ad esempio, gli oggetti Document e Selection sono entrambi membri dell'oggetto Application, ma l'oggetto Document è anche membro dell'oggetto Selection. Entrambi gli oggetti Document e Selection contengono oggetti Bookmark e Range. La sovrapposizione esiste in quanto sono disponibili numerosi metodi per accedere allo stesso tipo di oggetto. Ad esempio, si applica la formattazione a un oggetto Range, ma è possibile accedere all'intervallo della selezione corrente, di un particolare paragrafo, di una sezione o dell'intero documento.

Nelle sezioni riportate di seguito viene fornita una breve descrizione degli oggetti di livello superiore e della loro reciproca interazione. Tali oggetti sono i seguenti cinque:

• Oggetto applicazione

• Oggetto Document

• Oggetto Selection

• Oggetto Range

• Oggetto Bookmark

Visual Studio Tools per Office estende inoltre molti di questi oggetti in elementi host e controlli host. Questi oggetti estesi possono essere utilizzati nei progetti a livello di documento o, a partire da Visual Studio 2008 Service Pack 1 (SP1), nei progetti a livello di applicazione per Word 2007. Gli elementi e i controlli host dispongono di funzionalità aggiuntive, ad esempio funzionalità di associazione dati ed eventi. Per ulteriori informazioni sui controlli host, vedere Oggetti estesi nei progetti di Visual Studio Tools per Office.

Oggetto Application

L'oggetto Application rappresenta l'applicazione Word e costituisce l'elemento padre di tutti gli altri oggetti. I membri vengono in genere applicati complessivamente a Word. Le proprietà e i metodi di questo oggetto consentono di controllare l'ambiente Word.

Nei progetti di componenti aggiuntivi a livello di applicazione è possibile accedere all'oggetto Application utilizzando il campo Application della classe ThisAddIn. Per ulteriori informazioni, vedere Programmazione di componenti aggiuntivi a livello di applicazione.

Nei progetti a livello di documento è possibile accedere all'oggetto Application utilizzando la proprietà Application della classe ThisDocument.

Oggetto Document

L'oggetto Microsoft.Office.Interop.Word.Document svolge un ruolo centrale nell'ambito della programmazione di Word. Rappresenta un documento e tutto il relativo contenuto. Quando si apre un documento o se ne crea uno nuovo, viene creato un nuovo oggetto Microsoft.Office.Interop.Word.Document, che viene aggiunto all'insieme Documents dell'oggetto Application. Il documento con lo stato attivo è detto documento attivo. È rappresentato dalla proprietà ActiveDocument dell'oggetto Application.

Visual Studio Tools per Office estende l'oggetto Microsoft.Office.Interop.Word.Document fornendo la classe Microsoft.Office.Tools.Word.Document. Questa classe è un elemento host che consente di accedere a tutti i membri della classe Microsoft.Office.Interop.Word.Document nativa e che, oltre a introdurre eventi aggiuntivi, offre la possibilità di aggiungere controlli e smart tag gestiti. Per ulteriori informazioni, vedere Cenni preliminari sugli elementi e sui controlli host.

Quando si crea un progetto a livello di documento, Visual Studio Tools per Office genera una classe denominata ThisDocument, che deriva dalla classe Microsoft.Office.Tools.Word.Document. È possibile accedere ai membri della classe Microsoft.Office.Tools.Word.Document utilizzando le parole chiave Me o this del codice della classe ThisDocument oppure utilizzando l'oggetto Globals.ThisDocument del codice esterno alla classe ThisDocument. Per selezionare il primo paragrafo del documento, ad esempio, utilizzare il codice seguente.

Me.Paragraphs(1).Range.Select()

this.Paragraphs[1].Range.Select();

A partire da SP1 è possibile generare in fase di esecuzione elementi host Microsoft.Office.Tools.Word.Document tramite componenti aggiuntivi a livello di applicazione per Word 2007. È possibile utilizzare l'elemento host generato per aggiungere controlli e smart tag al documento associato. Per ulteriori informazioni, vedere la classe Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Oggetto Selection

L'oggetto Selection rappresenta l'area correntemente selezionata. Quando si esegue un'operazione nell'interfaccia utente di Word, impostando ad esempio il testo in grassetto, si seleziona, ovvero si evidenzia, il testo e quindi si applica la formattazione. L'oggetto Selection è sempre presente in un documento. Se non è selezionato alcun elemento, rappresenta il punto di inserimento. Inoltre, una selezione può includere più blocchi di testo non contigui.

Oggetto Range

L'oggetto Range rappresenta un'area contigua in un documento e viene definito mediante una posizione di carattere iniziale e una posizione di carattere finale. Non sono presenti limiti che impongono l'utilizzo di un singolo oggetto Range. È possibile definire più oggetti Range nello stesso documento. Un oggetto Range presenta le caratteristiche descritte di seguito:

• Può essere costituito dal solo punto di inserimento, da un intervallo di testo o dall'intero documento.

• Comprende caratteri non stampabili come spazi, caratteri di tabulazione e segni di paragrafo.

• Può corrispondere all'area rappresentata dalla selezione corrente oppure a un'area diversa dalla selezione corrente.

• Non è visibile in un documento, a differenza di una selezione, che è sempre visibile.

• Non viene salvato con un documento ed è disponibile solo durante l'esecuzione del codice.

In caso di inserimento di testo alla fine dell'intervallo, l'intervallo viene automaticamente espanso in modo da includere il testo inserito.

Oggetti di controllo del contenuto

Un oggetto Microsoft.Office.Interop.Word.ContentControl fornisce una modalità per controllare l'input e la presentazione del testo nonché di altri tipi di contenuto nei documenti di Word 2007. Un oggetto Microsoft.Office.Interop.Word.ContentControl può visualizzare vari tipi diversi di interfaccia utente ottimizzati per l'utilizzo nei documenti di Word, ad esempio un controllo RTF, una selezione data o una casella combinata. Inoltre è possibile utilizzare un oggetto Microsoft.Office.Interop.Word.ContentControl per impedire agli utenti di modificare le sezioni del documento o del modello.

Visual Studio Tools per Office estende l'oggetto Microsoft.Office.Interop.Word.ContentControl in vari controlli host diversi fra loro. Mentre l'oggetto Microsoft.Office.Interop.Word.ContentControl è in grado di visualizzare qualsiasi tipo di interfaccia utente disponibile per i controlli del contenuto, Visual Studio Tools per Office fornisce una classe diversa per ogni tipo di interfaccia utente. Ad esempio, è possibile utilizzare un oggetto RichTextContentControl per creare un controllo RTF oppure un oggetto DatePickerContentControl per creare una selezione data. Questi controlli host funzionano come oggetti Microsoft.Office.Interop.Word.ContentControl nativi, ma sono dotati di eventi e funzionalità di associazione dati aggiuntive.

Per ulteriori informazioni, vedere Controlli contenuto.

Oggetto Bookmark

L'oggetto Microsoft.Office.Interop.Word.Bookmark rappresenta un'area contigua in un documento, con una posizione di carattere iniziale e una posizione di carattere finale. I segnalibri possono essere utilizzati per contrassegnare una posizione in un documento o come contenitori di testo in un documento. Un oggetto Microsoft.Office.Interop.Word.Bookmark può essere costituito dal punto di inserimento o avere le stesse dimensioni dell'intero documento. Un oggetto Microsoft.Office.Interop.Word.Bookmark presenta le seguenti caratteristiche distintive rispetto all'oggetto Range:

• È possibile assegnare un nome al segnalibro in fase di progettazione.

• Gli oggetti Microsoft.Office.Interop.Word.Bookmark vengono salvati con il documento e vengono quindi conservati al termine dell'esecuzione del codice o dopo la chiusura del documento.

• È possibile nascondere o rendere visibili i segnalibri, impostando la proprietà su false o true la proprietà ShowBookmarks dell'oggetto View.

Visual Studio Tools per Office estende l'oggetto Microsoft.Office.Interop.Word.Bookmark in un controllo host. Il controllo Microsoft.Office.Tools.Word.Bookmark si comporta come un Microsoft.Office.Interop.Word.Bookmark nativo, ma è dotato di eventi aggiuntivi e funzionalità di associazione dati. È possibile associare dati a un controllo Bookmark contenuto in un documento nello stesso modo in cui si associano dati a un controllo casella di testo di un Windows Form.

Per ulteriori informazioni, vedere la classe Controllo Bookmark.

Oggetti estesi nei progetti di Visual Studio Tools per Office

È importante comprendere le differenze tra gli oggetti nativi forniti dal modello a oggetti di Word e gli oggetti estesi (elementi host e controlli host) forniti da Visual Studio Tools per Office. Entrambi i tipi di oggetto sono disponibili sia nei progetti a livello di documento sia in quelli a livello di applicazione per Word 2007. Per ulteriori informazioni, vedere Cenni preliminari sugli elementi e sui controlli host.

Le differenze sono raggruppabili nelle seguenti quattro categorie:

• Fase di progettazione. Quando in fase di progettazione si aggiunge un controllo esteso di Word in una personalizzazione a livello di documento, tale controllo viene creato automaticamente come controllo host. Se, ad esempio, si aggiunge un segnalibro a un documento nella finestra di progettazione, il codice viene generato automaticamente per estendere il segnalibro in un controllo Microsoft.Office.Tools.Word.Bookmark.

• Fase di esecuzione. Gli elementi host non vengono creati automaticamente in fase di esecuzione. Se si aggiungono documenti in fase di esecuzione tramite il metodo Add, si tratta di oggetti Microsoft.Office.Interop.Word.Document che non hanno funzionalità aggiuntive fornite dagli elementi host Microsoft.Office.Tools.Word.Document. I controlli host possono essere aggiunti a livello di codice nei documenti mediante i metodi di supporto forniti in Visual Studio Tools per Office. Per ulteriori informazioni, vedere la classe Limitazioni a livello di codice degli elementi e dei controlli host.

  Nota:
  A partire da SP1 è possibile creare in fase di esecuzione elementi host Microsoft.Office.Tools.Word.Document mediante componenti aggiuntivi a livello di applicazione per Word 2007. Per ulteriori informazioni, vedere Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

• Nuove funzionalità. Gli elementi e i controlli host sono dotati di funzionalità non disponibili per gli oggetti nativi. Gli elementi host possono essere utilizzati come contenitore di controlli gestiti e dispongono di eventi aggiuntivi. I controlli host possono essere associati ai dati e dispongono di eventi aggiuntivi.

• Tipi. Gli oggetti nativi di Word utilizzano i tipi definiti in nello spazio dei nomi Microsoft.Office.Interop.Word dell'assembly di interoperabilità primario di Word, mentre gli elementi e i controlli host utilizzano i tipi definiti nello spazio dei nomi Microsoft.Office.Tools.Word del runtime di Visual Studio Tools per Office.

Utilizzo della documentazione sul modello a oggetti di Word

Per informazioni sulle classi utilizzabili nel modello a oggetti di Word, vedere i seguenti argomenti della documentazione:

• Riferimenti all'assembly di interoperabilità primario di Microsoft Office Word

• Riferimenti dello sviluppatore per Microsoft Office Word 2007

• Riferimenti del linguaggio VBA di Microsoft Office Word 2003

Il primo collegamento fornisce informazioni sulle classi e sulle interfacce nell'assembly di interoperabilità primario per Word. L'altro collegamento fornisce informazioni sul modello a oggetti di Word esposto al codice Visual Basic, Applications Edition (VBA). Ogni argomento della documentazione presenta vantaggi e svantaggi per gli sviluppatori che utilizzano Visual Studio Tools per Office.

Riferimento all'assembly di interoperabilità primario

In questa documentazione vengono descritti tutti i tipi nell'assembly di interoperabilità primario di Word che è possibile utilizzare nei progetti Visual Studio Tools per Office. Tuttavia, questa documentazione presenta gli svantaggi seguenti:

• Sono descritti solo i tipi nell'assembly di interoperabilità primario per Word 2003. Per le descrizioni di tipi e dei membri nuovi nell'assembly di interoperabilità primario per Word 2007, è necessario utilizzare il riferimento a VBA per Word 2007.

• Al momento non viene fornito alcun esempio di codice.

Riferimento a VBA

Tutti gli oggetti e i membri nel riferimento a VBA corrispondono a classi e membri nell'assembly di interoperabilità primario utilizzato nei progetti Visual Studio Tools per Office. Ad esempio, l'oggetto Document nella documentazione di VBA per Word corrisponde alla classe Microsoft.Office.Interop.Word.Document nell'assembly di interoperabilità primario.

Il riferimento a VBA presenta i vantaggi seguenti:

• Documenta i modelli a oggetti di Word 2007 e Word 2003.

• Fornisce esempi di codice per la maggior parte dei membri.

Il riferimento a VBA presenta gli svantaggi seguenti:

• Fornisce sintassi ed esempi di codice unicamente per VBA. Per utilizzare gli esempi di codice in un progetto Visual Studio Tools per Office, è necessario convertire il codice VBA in Visual Basic o Visual C#.

Tipi aggiuntivi negli assembly di interoperabilità primari

Gli assembly di interoperabilità primari contengono molti tipi non disponibili per VBA. Questi tipi aggiuntivi, che consentono di convertire gli oggetti del modello a oggetti COM di Word nel codice gestito, non possono essere utilizzati direttamente nel codice.

Per ulteriori informazioni, vedere Overview of Classes and Interfaces in the Office Primary Interop Assemblies.

Vedere anche

Concetti

Utilizzo dei documenti

Utilizzo del testo nei documenti

Utilizzo delle tabelle

Cenni preliminari sul modello a oggetti di Excel

Cenni preliminari sugli elementi e sui controlli host

Limitazioni a livello di codice degli elementi e dei controlli host

Informazioni sui parametri facoltativi nelle soluzioni Office

Riferimenti

Assembly di interoperabilità primari di Office

Altre risorse

Controlli host di Word

Cronologia delle modifiche

Date	History	Motivo
Luglio 2008	Aggiunte informazioni sulla creazione di elementi host Document in componenti aggiuntivi a livello di applicazione.	Modifica di funzionalità in SP1.