Architettura degli smart tag

Articolo
08/11/2011

Gli strumenti di sviluppo di Office in Visual Studio 2010 forniscono 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, vedere Cenni preliminari sugli smart tag.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento e di applicazione per Excel 2007 e Word 2007. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Cenni preliminari sul modello a oggetti

Il modello a oggetti per gli smart tag separa gli smart tag dalle azioni che questi ultimi eseguono. Nelle sezioni riportate di seguito vengono descritti gli oggetti principali utilizzati per creare gli smart tag. Per esempi di codice in cui viene illustrato come aggiungere smart tag 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

All'interno del codice uno smart tag è un oggetto Microsoft.Office.Tools.Word.SmartTag o Microsoft.Office.Tools.Excel.SmartTag. Tali oggetti comprendono le proprietà elencate di seguito:

Terms e Expressions. Queste proprietà contengono 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.
Actions. Questa proprietà contiene le azioni da eseguire quando l'utente seleziona lo smart tag.
Caption. Questa proprietà specifica l'etichetta dello smart tag.

Azioni

Quando seleziona lo smart tag, l'utente può eseguire una o più azioni specifiche dello smart tag. Ogni azione è rappresentata da un oggetto Microsoft.Office.Tools.Word.Action o Microsoft.Office.Tools.Excel.Action. Questi oggetti 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 o Microsoft.Office.Tools.Word.ActionEventArgs che fornisce accesso al testo riconosciuto e alla relativa posizione.

Creazione di smart tag

La modalità con cui si crea uno smart tag varia a seconda che il progetto sia destinato a .NET Framework 3.5 o a .NET Framework 4.

Nel caso in cui il progetto sia destinato a .NET Framework 3.5, SmartTag e Action sono classi per le quali è possibile creare direttamente un'istanza. Nell'esempio di codice riportato di seguito viene illustrato come creare un semplice smart tag in un progetto di Word destinato a .NET Framework 3.5. Per utilizzare questo esempio, eseguire il codice dalla classe ThisDocument in un progetto a livello di documento o dalla classe ThisAddIn in un progetto a livello di applicazione.

Dim simpleSmartTag As Microsoft.Office.Tools.Word.SmartTag =
        New Microsoft.Office.Tools.Word.SmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Test Smart Tag")
Dim simpleAction As Microsoft.Office.Tools.Word.Action = 
    New Microsoft.Office.Tools.Word.Action("Test Action")

simpleSmartTag.Terms.Add("blue")
simpleSmartTag.Actions = New Microsoft.Office.Tools.Word.Action() { _
    simpleAction}
Me.VstoSmartTags.Add(simpleSmartTag)

Microsoft.Office.Tools.Word.SmartTag simpleSmartTag =
    new Microsoft.Office.Tools.Word.SmartTag(
    "www.microsoft.com/Demo#DemoSmartTag",
    "Test Smart Tag");
Microsoft.Office.Tools.Word.Action simpleAction = 
    new Microsoft.Office.Tools.Word.Action("Test Action");

simpleSmartTag.Terms.Add("blue");
simpleSmartTag.Actions = new Microsoft.Office.Tools.Word.Action[] { 
    simpleAction };
this.VstoSmartTags.Add(simpleSmartTag);

Se il progetto è destinato a .NET Framework 4, SmartTag e Action sono interfacce per le quali non è possibile creare direttamente un'istanza. Al contrario, è necessario utilizzare i metodi CreateSmartTag e CreateAction forniti dalla classe Globals nel progetto per ottenere istanze di questi oggetti. Per ulteriori informazioni sulla classe Globals, vedere Accesso globale a oggetti nei progetti di Office. Nell'esempio di codice riportato di seguito viene illustrato come creare un semplice smart tag in un progetto di Word destinato a .NET Framework 4. Per utilizzare questo esempio, eseguire il codice dalla classe ThisDocument in un progetto a livello di documento o dalla classe ThisAddIn in un progetto a livello di applicazione.

Dim simpleSmartTag As Microsoft.Office.Tools.Word.SmartTag =
    Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Test Smart Tag")
Dim simpleAction As Microsoft.Office.Tools.Word.Action =
    Globals.Factory.CreateAction("Test Action")

simpleSmartTag.Terms.Add("blue")
simpleSmartTag.Actions = New Microsoft.Office.Tools.Word.Action() { _
    simpleAction}
Me.VstoSmartTags.Add(simpleSmartTag)

Microsoft.Office.Tools.Word.SmartTag simpleSmartTag =
    Globals.Factory.CreateSmartTag(
    "www.microsoft.com/Demo#DemoSmartTag",
    "Test Smart Tag");
Microsoft.Office.Tools.Word.Action simpleAction =
    Globals.Factory.CreateAction("Test Action");

simpleSmartTag.Terms.Add("blue");
simpleSmartTag.Actions = new Microsoft.Office.Tools.Word.Action[] { 
    simpleAction };
this.VstoSmartTags.Add(simpleSmartTag);

Per ulteriori istruzioni ed esempi di codice che illustrino smart tag più complessi, vedere Procedura: aggiungere smart tag ai documenti di Word e Procedura: aggiungere smart tag a cartelle di lavoro di Excel.

Creazione di sistemi di riconoscimento degli smart tag

Se si desidera personalizzare il comportamento di riconoscimento predefinito degli smart tag, è possibile creare un sistema di riconoscimento degli smart tag personalizzato. La modalità con cui si esegue questa operazione varia a seconda che il progetto sia destinato a .NET Framework 3.5 o a .NET Framework 4.

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 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 in progetti destinati a .NET Framework 4

Per creare un sistema di riconoscimento degli smart tag personalizzato, definire una classe che implementa l'interfaccia Microsoft.Office.Tools.Word.ISmartTagExtension o Microsoft.Office.Tools.Excel.ISmartTagExtension. Nell'implementazione del metodo ISmartTagExtension.Recognize, cercare i termini dello smart tag all'interno del testo e, quando viene trovato un termine, registrare lo smart tag con Word o Excel. Per registrare uno smart tag, chiamare il metodo PersistTag del parametro context del metodo Recognize.

Nell'esempio di codice riportato di seguito viene illustrato come creare una classe di smart tag semplice con un sistema di riconoscimento personalizzato in un progetto di Word destinato a .NET Framework 4.

Public Class SmartTagWithCustomRecognizer
    Implements Microsoft.Office.Tools.Word.ISmartTagExtension

    Private theSmartTag As Microsoft.Office.Tools.Word.SmartTag

    Public Sub New()
        theSmartTag = Globals.Factory.CreateSmartTag("www.microsoft.com/Demo#DemoSmartTag",
            "Test Smart Tag", Me)
        Dim simpleAction As Microsoft.Office.Tools.Word.Action = Globals.Factory.CreateAction("Test Action")
        theSmartTag.Actions = New Microsoft.Office.Tools.Word.Action() {simpleAction}
    End Sub

    Private Sub Recognize(ByVal text As String,
        ByVal site As Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite,
        ByVal tokenList As Microsoft.Office.Interop.SmartTag.ISmartTagTokenList,
        ByVal context As Microsoft.Office.Tools.Word.SmartTagRecognizeContext) _
        Implements Microsoft.Office.Tools.Word.ISmartTagExtension.Recognize

        Dim index As Integer = text.IndexOf("blue")
        If index >= 0 Then
            context.PersistTag(index, 4, Nothing)
        End If
    End Sub

    Public ReadOnly Property ExtensionBase() As Object _
        Implements Microsoft.Office.Tools.Word.ISmartTagExtension.ExtensionBase
        Get
            Return theSmartTag
        End Get
    End Property
End Class

public class SmartTagWithCustomRecognizer : Microsoft.Office.Tools.Word.ISmartTagExtension
{
    private Microsoft.Office.Tools.Word.SmartTag theSmartTag;

    public SmartTagWithCustomRecognizer()
    {
        theSmartTag = Globals.Factory.CreateSmartTag("www.microsoft.com/Demo#DemoSmartTag", 
            "Test Smart Tag", this);
        Microsoft.Office.Tools.Word.Action simpleAction = Globals.Factory.CreateAction("Test Action");
        theSmartTag.Actions = new Microsoft.Office.Tools.Word.Action[] { simpleAction };
    }

    public void Recognize(string text, Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite site, 
        Microsoft.Office.Interop.SmartTag.ISmartTagTokenList tokenList,
        Microsoft.Office.Tools.Word.SmartTagRecognizeContext context)
    {
        int index = text.IndexOf("blue");
        if (index >= 0)
        {
            context.PersistTag(index, 4, null);
        }
    }

    public object ExtensionBase
    {
        get { return theSmartTag; }
    }
}

Per ulteriori istruzioni ed esempi di codice che illustrino classi di smart tag più complesse con sistemi di riconoscimento personalizzati, vedere Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Word e .NET Framework 4 e Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Excel e .NET Framework 4.

Creazione di sistemi di riconoscimento degli smart tag in progetti destinati a .NET Framework 3.5

Per creare un sistema di riconoscimento degli smart tag personalizzato, derivare una classe da Microsoft.Office.Tools.Word.SmartTag o Microsoft.Office.Tools.Excel.SmartTag e ignorare il metodo SmartTag.Recognize nella classe. Nel metodo cercare i termini dello smart tag all'interno del testo e, quando viene trovato un termine, registrare lo smart tag con Word o Excel. Per registrare uno smart tag, chiamare il metodo PersistTag che la classe deriva da Microsoft.Office.Tools.Word.SmartTag o Microsoft.Office.Tools.Excel.SmartTag.

Public Class SmartTagWithCustomRecognizer 
    Inherits Microsoft.Office.Tools.Word.SmartTag

    Public Sub New()
    MyBase.New("https://www.contoso.com/Demo#DemoSmartTag", _
        "Test Smart Tag")
        Dim simpleAction As Microsoft.Office.Tools.Word.Action = _
            New Microsoft.Office.Tools.Word.Action("TestAction")
        Me.Actions = new Microsoft.Office.Tools.Word.Action() { simpleAction }
    End Sub

    Protected Overrides Sub Recognize(ByVal text As String, _
        ByVal site As Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite, _
        ByVal tokenList As Microsoft.Office.Interop.SmartTag.ISmartTagTokenList)

        Dim index As Integer = text.IndexOf("blue")
        If index >= 0 Then
            Me.PersistTag(index, 4, Nothing)
        End If
    End Sub
End Class

public class SmartTagWithCustomRecognizer : Microsoft.Office.Tools.Word.SmartTag
{
    public SmartTagWithCustomRecognizer() : base(
        "https://www.contoso.com/Demo#DemoSmartTag", 
        "Test Smart Tag")
    {
        Microsoft.Office.Tools.Word.Action simpleAction = 
            new Microsoft.Office.Tools.Word.Action("TestAction");
        this.Actions = new Microsoft.Office.Tools.Word.Action[] { simpleAction };
    }

    protected override void Recognize(string text, 
        Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite site, 
        Microsoft.Office.Interop.SmartTag.ISmartTagTokenList tokenList)
    {
        int index = text.IndexOf("blue");
        if (index >= 0)
        {
            this.PersistTag(index, 4, null);
        }
    }
}

Per ulteriori istruzioni ed esempi di codice che illustrino classi di smart tag più complesse con sistemi di riconoscimento personalizzati, vedere Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Word e .NET Framework 3.5 e Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Excel e .NET Framework 3.5.

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.

Esistono due modi per accedere all'elenco delle proprietà:

È possibile gestire l'evento Click o BeforeCaptionShow di un oggetto Microsoft.Office.Tools.Word.Action o 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 delle proprietà dello smart tag. La proprietà Properties restituisce un oggetto ISmartTagProperties. L'interfaccia ISmartTagProperties è disponibile quando si aggiunge al progetto un riferimento alla Libreria dei tipi Microsoft Smart Tags 2.0.
È possibile creare un sistema di riconoscimento degli smart tag personalizzato seguendo le istruzioni precedenti. Nell'implementazione o nell'override del metodo Recognize, utilizzare il metodo GetNewPropertyBag del parametro site per ottenere un oggetto ISmartTagProperties che può essere utilizzato per eseguire operazioni di scrittura o lettura nell'elenco delle proprietà dello smart tag.

Per esempi di operazioni di scrittura e lettura nell'elenco delle proprietà, vedere i seguenti argomenti:

Espressioni regolari ed elenco proprietà

Quando si assegna un'espressione regolare a uno smart tag, il sistema di riconoscimento predefinito aggiunge all'elenco delle 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 Modello a oggetti delle espressioni regolari.