Architettura degli smart tag

Articolo
04/28/2010

Aggiornamento: novembre 2007

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. Progetti a livello di documento Excel 2003 Excel 2007 Word 2003 Word 2007 Progetti a livello di applicazione Excel 2007 Word 2007 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati.

Progetti a livello di documento

Excel 2003
Excel 2007
Word 2003
Word 2007

Progetti a livello di applicazione

Excel 2007
Word 2007

Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Visual Studio Tools per Office fornisce un modello a oggetti flessibile per smart tag che consente di aggiungere rapidamente smart tag ai documenti di Microsoft Office Word e alle cartelle di lavoro di Microsoft Office Excel. Per gli scenari avanzati è inoltre possibile creare sistemi di riconoscimento di smart tag personalizzati e accedere a dati archiviati nello smart tag.

Per ulteriori informazioni sugli smart tag di Visual Studio Tools per Office, vedere Cenni preliminari sugli smart tag.

Cenni preliminari sul modello a oggetti

Il modello a oggetti per gli smart tag di Visual Studio Tools per Office fornisce classi distinte per gli smart tag e per le azioni eseguite dagli smart tag. Per esempi di codice in cui viene illustrato come aggiungere smart tag di Visual Studio Tools per Office a un documento, vedere Procedura: aggiungere smart tag ai documenti di Word e Procedura: aggiungere smart tag a cartelle di lavoro di Excel.

Smart tag

Uno smart tag di Visual Studio Tools per Office è un'istanza di una qualsiasi classe derivante dalla classe astratta SmartTagBase. Visual Studio Tools per Office comprende due classi che implementano la classe astratta SmartTagBase: Microsoft.Office.Tools.Word.SmartTag e Microsoft.Office.Tools.Excel.SmartTag. A meno che non sia necessario creare un sistema personalizzato di riconoscimento degli smart tag, quando si aggiungono smart tag a un documento è possibile utilizzare istanze di queste classi.

La classe SmartTagBase fornisce le funzionalità seguenti:

Le proprietà Terms e Expressions, contenenti i termini riconoscibili per lo smart tag. Per specificare una stringa semplice, aggiungere la stringa alla proprietà Terms. Per specificare una stringa complessa, aggiungere un'espressione regolare che descrive la stringa alla proprietà Expressions.
La proprietà Actions, contenente le azioni da eseguire quando l'utente seleziona lo smart tag.
Il sistema di riconoscimento degli smart tag predefinito che confronta l'input dell'utente con il contenuto delle proprietà Terms e Expressions.

Azioni

Quando seleziona lo smart tag, l'utente può eseguire una o più azioni specifiche dello smart tag. Ogni azione è rappresentata da un'istanza della classe Microsoft.Office.Tools.Word.Action o della classe Microsoft.Office.Tools.Excel.Action. Queste classi forniscono gli eventi BeforeCaptionShow e Click:

L'evento BeforeCaptionShow viene generato subito dopo che l'utente ha fatto clic sull'icona di smart tag, ma prima che venga visualizzato il menu Smart tag. Gestire questo evento se si desidera modificare in fase di esecuzione il titolo dell'azione visualizzato nel menu dello smart tag.
L'evento Click viene generato quando l'utente seleziona il titolo dell'azione nel menu Smart tag. Gestire questo evento per eseguire codice quando l'utente fa clic sull'azione.

I gestori di questi eventi ricevono un oggetto Microsoft.Office.Tools.Excel.ActionEventArgs (per Excel) o un oggetto Microsoft.Office.Tools.Word.ActionEventArgs (per Word) che fornisce accesso al testo riconosciuto e alla relativa posizione.

Comportamento predefinito del riconoscimento del testo

Quando un utente digita testo in un documento o in una cartella di lavoro, Word ed Excel creano un elenco di token a partire da tale testo. Il sistema di riconoscimento degli smart tag predefinito della classe SmartTagBase riceve tale elenco di token e il testo completo digitato dall'utente. Il sistema di riconoscimento degli smart tag predefinito identifica uno smart tag se si verifica una delle seguenti condizioni:

Una delle stringhe della proprietà Terms corrisponde esattamente a uno dei token presenti nel documento o nella cartella di lavoro.
Una delle espressioni regolari nella proprietà Expressions presenta una corrispondenza con il testo completo digitato dall'utente.

Le stringhe contenenti spazi incorporati, o le stringhe che combinano lettere, numeri e simboli, vengono analizzate da Word ed Excel in token separati quando vengono digitate dall'utente. Ad esempio, se l'utente digita "sales report", Word ed Excel creano i token "sales" e "report". Analogamente, se l'utente digita "2005sales", Word ed Excel creano i token "2005" e "sales".

Se si desidera che lo smart tag riconosca una stringa contenente spazi incorporati o una stringa che combina lettere, numeri e simboli, non aggiungerla alla proprietà Terms. Aggiungere invece un'espressione regolare che descrive la stringa alla proprietà Expressions oppure creare un sistema di riconoscimento personalizzato che esegua la ricerca della stringa.

Creazione di sistemi di riconoscimento degli smart tag

Per creare un sistema di riconoscimento personalizzato degli smart tag, derivare una nuova classe dall'oggetto SmartTagBase, Microsoft.Office.Tools.Word.SmartTag o Microsoft.Office.Tools.Excel.SmartTag ed eseguire l'override del metodo Recognize.

Nell'implementazione del metodo Recognize è necessario cercare i termini dello smart tag all'interno del testo e, quando viene trovato un termine, registrare manualmente lo smart tag con Word o Excel. Per esempi relativi alle procedure di creazione di sistemi di riconoscimento degli smart tag di Visual Studio Tools per Office, vedere Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Word e Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Excel.

Il processo di registrazione manuale di uno smart tag dipende dalla classe di derivazione dello smart tag. Nella tabella che segue vengono elencati le diverse opzioni disponibili per la registrazione di uno smart tag.

Classe di derivazione	Registrazione dello smart tag
Microsoft.Office.Tools.Word.SmartTag	Chiamare il metodo SmartTag.PersistTag.
Microsoft.Office.Tools.Excel.SmartTag	Chiamare il metodo SmartTag.PersistTag.
SmartTagBase	Chiamare il metodo CommitSmartTag del parametro site del metodo Recognize. Il parametro site è un oggetto che implementa l'interfaccia ISmartTagRecognizerSite. Questa interfaccia è disponibile quando si aggiunge al progetto un riferimento alla Libreria dei tipi Microsoft Smart Tags 2.0. Per ulteriori informazioni, vedere la documentazione relativa a Smart Tag SDK in MSDN Library.

Microsoft.Office.Tools.Word.SmartTag

Chiamare il metodo SmartTag.PersistTag.

Microsoft.Office.Tools.Excel.SmartTag

Chiamare il metodo SmartTag.PersistTag.

SmartTagBase

Chiamare il metodo CommitSmartTag del parametro site del metodo Recognize.

Il parametro site è un oggetto che implementa l'interfaccia ISmartTagRecognizerSite. Questa interfaccia è disponibile quando si aggiunge al progetto un riferimento alla Libreria dei tipi Microsoft Smart Tags 2.0. Per ulteriori informazioni, vedere la documentazione relativa a Smart Tag SDK in MSDN Library.

Archiviazione e recupero di dati dall'elenco proprietà

È possibile utilizzare gli smart tag per archiviare i dati in un insieme di coppie chiave/valore, noto come elenco proprietà. Ciascuna coppia chiave/valore nell'elenco proprietà rappresenta una stringa.

Gli smart tag di Visual Studio Tools per Office offrono due modi per accedere all'elenco proprietà:

È possibile gestire l'evento Click o l'evento BeforeCaptionShow della classe Microsoft.Office.Tools.Word.Action o della classe Microsoft.Office.Tools.Excel.Action nonché utilizzare la proprietà Properties del parametro dell'argomento di evento per eseguire operazioni di scrittura o lettura nell'elenco proprietà dello smart tag. La proprietà Properties restituisce un oggetto che implementa l'interfaccia ISmartTagProperties. L'interfaccia ISmartTagProperties è disponibile quando si aggiunge al progetto un riferimento alla Libreria dei tipi Microsoft Smart Tags 2.0.
È possibile implementare il metodo Recognize in una classe che deriva dalla classe SmartTagBase, dalla classe Microsoft.Office.Tools.Word.SmartTag o dalla classe Microsoft.Office.Tools.Excel.SmartTag. Il parametro site di questo metodo fornisce un metodo GetNewPropertyBag che restituisce un oggetto ISmartTagProperties utilizzabile per eseguire operazioni di scrittura o lettura nell'elenco proprietà dello smart tag.

Per esempi di operazioni di scrittura e lettura nell'elenco proprietà, vedere Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Word e Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Excel.

Espressioni regolari ed elenco proprietà

Quando si assegna un'espressione regolare a uno smart tag di Visual Studio Tools per Office, il sistema di riconoscimento predefinito aggiunge all'elenco proprietà dello smart tag una coppia chiave/valore per ogni gruppo acquisito dall'espressione regolare.

Per un esempio di codice che illustri questo comportamento, vedere Procedura dettagliata: creazione di uno smart tag tramite una personalizzazione a livello di documento. Per ulteriori informazioni sui gruppi acquisiti in espressioni regolari, vedere Costrutti di raggruppamento e Classi di espressioni regolari.