Procedura: creare smart tag con sistemi di riconoscimento personalizzati in Excel

Articolo
04/28/2010

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. 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.

È possibile controllare il riconoscimento degli smart tag nelle cartelle di lavoro in Microsoft Office Excel derivando i dati dalla classe Microsoft.Office.Tools.Excel.SmartTag ed eseguendo l'override del metodo Recognize.

Per eseguire uno smart tag gli utenti finali devono avere gli smart tag attivati in Word o Excel. Per ulteriori informazioni, vedere la classe Procedura: attivare gli smart tag in Word ed Excel.

Per aggiungere uno smart tag con un sistema di riconoscimento personalizzato a una cartella di lavoro di Excel

Creare un nuovo progetto a livello di documento o di applicazione per Excel. Per ulteriori informazioni, vedere Procedura: creare progetti Visual Studio Tools per Office.

Nota:

Per utilizzare un progetto a livello di applicazione è necessario aver installato nel proprio sistema Visual Studio 2008 Service Pack 1 (SP1).
Aggiungere un riferimento a Libreria dei tipi Microsoft Smart Tags 2.0 dalla scheda COM della finestra di dialogo Aggiungi riferimento.
Aggiungere un file di classe al progetto e creare una classe che eredita da Microsoft.Office.Tools.Excel.SmartTag.
Nella nuova classe, creare le azioni per gli smart tag. Le azioni sono le voci che appariranno nel menu degli smart tag. Creare azioni aggiungendo istanze del tipo Action all'insieme Actions della classe.
Eseguire l'override del metodo Recognize per implementare il comportamento di riconoscimento personalizzato. L'implementazione del metodo Recognize deve chiamare il metodo PersistTag affinché lo smart tag venga riconosciuto in Excel.
Creare gestori eventi per rispondere all'evento Click, e facoltativamente anche all'evento BeforeCaptionShow, delle azioni create.

Nota:
Per utilizzare un progetto a livello di applicazione è necessario aver installato nel proprio sistema Visual Studio 2008 Service Pack 1 (SP1).

Nel file di codice della cartella di lavoro del progetto, aggiungere l'istanza dello smart tag alla proprietà VstoSmartTags della classe ThisWorkbook (per un progetto a livello di documento) o alla proprietà VstoSmartTags della classe ThisAddIn (per un progetto a livello di applicazione).

Nota:
Se si utilizza un progetto a livello di applicazione creato prima di installare SP1, è necessario modificare il progetto affinché generi la proprietà VstoSmartTags. Per ulteriori informazioni, vedere la classe Procedura: aggiungere smart tag a livello di applicazione in progetti creati prima di SP1.

Esempio

Nell'esempio di codice riportato di seguito viene illustrato come creare uno smart tag personalizzato in una cartella di lavoro di Excel. Viene eseguito l'override del metodo Recognize per riconoscere i termini sales e organization in una cella del foglio di lavoro. Il metodo Recognize aggiunge una coppia chiave-valore all'insieme delle proprietà con chiave per lo smart tag. Chiama quindi il metodo PersistTag per riconoscere lo smart tag e salvare la proprietà del nuovo smart tag. Per testare l'esempio, digitare le parole sales e organization in celle diverse della cartella di lavoro, quindi provare a utilizzare le azioni dello smart tag. Un'azione consentirà di visualizzare il valore di proprietà corrispondente per il termine riconosciuto, mentre l'altra lo spazio dei nomi e il titolo dello smart tag.

Imports Microsoft.Office.Tools.Excel
Imports Microsoft.Office.Interop.SmartTag

Public Class CustomSmartTag
    Inherits SmartTag

    ' Declare Actions for this SmartTag
    WithEvents Action1 As New Action("Display property value")
    WithEvents Action2 As New Action("Display smart tag details")

    Public Sub New()
        MyBase.New("https://www.contoso.com/Demo#DemoSmartTag", _
            "Custom Smart Tag")
        Me.Terms.AddRange(New String() {"sales", "organization"})
        Actions = New Action() {Action1, Action2}
    End Sub

    Protected Overrides Sub Recognize(ByVal text As String, _
        ByVal site As ISmartTagRecognizerSite, _
        ByVal tokenList As ISmartTagTokenList)

        ' Determine whether each smart tag term exists in 
        ' the document text.
        Dim Term As String
        For Each Term In Me.Terms

            ' Search the cell text for the first instance of 
            ' the current smart tag term.
            Dim index As Integer = Me.CellText.IndexOf(Term, 0)

            If (index >= 0) Then

                ' Create a smart tag token and a property bag for the 
                ' recognized term.
                Dim propertyBag As ISmartTagProperties = _
                    site.GetNewPropertyBag()

                ' Write a new property value.
                Dim key As String = "Key1"
                propertyBag.Write(key, DateTime.Now)

                ' Attach the smart tag to the term in the document
                Me.PersistTag(propertyBag)

                ' This implementation only finds the first instance
                ' of a smart tag term in the cell. 
                Exit For
            End If
        Next
    End Sub

    ' This action displays the property value for the term.
    Private Sub Action1_Click(ByVal sender As Object, _
        ByVal e As ActionEventArgs) Handles Action1.Click

        Dim propertyBag As ISmartTagProperties = e.Properties
        Dim key As String = "Key1"
        MsgBox("The corresponding value of " & _
            key & " is: " & propertyBag.Read(key))
    End Sub

    ' This action displays smart tag details.
    Private Sub Action2_Click(ByVal sender As Object, _
        ByVal e As ActionEventArgs) Handles Action2.Click

        MsgBox("The current smart tag caption is '" & _
            Me.Caption & "'. The current smart tag type is '" & _
            Me.SmartTagType & "'.")
    End Sub
End Class

using System;
using System.Windows.Forms;
using Microsoft.Office.Tools.Excel;
using Microsoft.Office.Interop.SmartTag;

namespace Trin_ExcelDerivedSmartTags
{
    public class CustomSmartTag : SmartTag {

        // Declare Actions for this SmartTag
        Microsoft.Office.Tools.Excel.Action Action1 =
            new Microsoft.Office.Tools.Excel.Action("Display property value");
        Microsoft.Office.Tools.Excel.Action Action2 =
            new Microsoft.Office.Tools.Excel.Action("Display smart tag details");

        public CustomSmartTag() : base(
            "https://www.contoso.com/Demo#DemoSmartTag", 
            "Custom Smart Tag")
        {
            this.Terms.AddRange(new string[] { 
                "sales", "organization" });
            Actions = new Microsoft.Office.Tools.Excel.Action[] { Action1, Action2 };
            Action1.Click +=
                new ActionClickEventHandler(Action1_Click);
            Action2.Click += 
                new ActionClickEventHandler(Action2_Click);
        }

        protected override void Recognize(string text, 
            ISmartTagRecognizerSite site, ISmartTagTokenList tokenList)
        {
            // Determine whether each smart tag term exists in 
            // the document text.
            foreach (string term in this.Terms)
            {
                // Search the cell text for the first instance of 
                // the current smart tag term.
                int index = this.CellText.IndexOf(term, 0);

                if (index >= 0)
                {
                    // Create a smart tag token and a property bag for the 
                    // recognized term.
                    ISmartTagProperties propertyBag = 
                        site.GetNewPropertyBag();

                    // Write a new property value.                 
                    string key = "Key1";
                    propertyBag.Write(key, DateTime.Now.ToString());

                    // Attach the smart tag to the term in the document
                    this.PersistTag(propertyBag);

                    // This implementation only finds the first instance
                    // of a smart tag term in the cell. 
                    break;
                }
            }
        }

        // This action displays the property value for the term.
        private void Action1_Click(object sender, ActionEventArgs e)
        {
            ISmartTagProperties propertyBag = e.Properties;
            string key = "Key1";
            MessageBox.Show("The corresponding value of " + key +
                " is: " + propertyBag.get_Read(key));
        }

        // This action displays smart tag details.
        private void Action2_Click(object sender, ActionEventArgs e)
        {
            MessageBox.Show("The current smart tag caption is '" + 
                this.Caption + "'. The current smart tag type is '" + 
                this.SmartTagType + "'.");
        }
    }
}

Compilazione del codice

Aggiungere un riferimento nel progetto a Libreria dei tipi Microsoft Smart Tags 2.0 dalla scheda COM della finestra di dialogo Aggiungi riferimento. Accertarsi che la proprietà Copia localmente del riferimento sia false. Se è true, il riferimento non è all'assembly di interoperabilità primario corretto e sarà necessario installare l'assembly dal supporto di installazione di Microsoft Office. Per ulteriori informazioni, vedere Procedura: installare assembly di interoperabilità primari di Office.
Copiare il codice di esempio in un nuovo file di classe denominato CustomSmartTag.
In C# modificare lo spazio dei nomi in modo che corrisponda al nome del progetto.
Aggiungere le istruzioni Imports (in Visual Basic) oppure using (in C#) per gli spazi dei nomi Microsoft.Office.Tools.Excel e Microsoft.Office.Interop.SmartTag all'inizio del file della classe.
Aggiungere il codice seguente al gestore eventi ThisWorkbook_Startup o ThisAddIn_Startup contenuto nel progetto. Questo codice consente di aggiungere lo smart tag personalizzato alla cartella di lavoro.
```
Me.VstoSmartTags.Add(New CustomSmartTag())
```
```
this.VstoSmartTags.Add(new CustomSmartTag());
```

Sicurezza

In Excel gli smart tag devono essere attivati esplicitamente, in quanto per impostazione predefinita non sono attivati. Per ulteriori informazioni, vedere la classe Procedura: attivare gli smart tag in Word ed Excel.