Cómo: Crear etiquetas inteligentes con reconocedores personalizados en Excel

Actualización: Julio de 2008

Puede controlar cómo Microsoft Office Excel reconoce las etiquetas inteligentes en los libros derivando de la clase Microsoft.Office.Tools.Excel.SmartTag e invalidando el método Recognize.

Para ejecutar una etiqueta inteligente, los usuarios finales deben tener las etiquetas inteligentes habilitadas en Word o en Excel. Para obtener más información, vea Cómo: Habilitar las etiquetas inteligentes en Word y en Excel.

Para agregar una etiqueta inteligente con un reconocedor personalizado a un libro de Excel

1. Cree un nuevo proyecto en el nivel del documento o en el nivel de la aplicación para Excel. Para obtener más información, consulte Cómo: Crear proyectos de Visual Studio para Office.

   Nota:
   Para utilizar un proyecto en el nivel de la aplicación, debe tener Visual Studio 2008 Service Pack 1 (SP1) instalado.

2. Agregue una referencia a la opción Biblioteca de tipos de Etiquetas inteligentes de Microsoft 2.0 de la ficha COM del cuadro de diálogo Agregar referencia.

3. Agregue un archivo de clases al proyecto y cree una clase que herede de Microsoft.Office.Tools.Excel.SmartTag.

4. En la nueva clase, cree las acciones para las etiquetas inteligentes. Las acciones son elementos que aparecen en el menú de etiquetas inteligentes. Cree acciones agregando instancias del tipo Action a la colección Actions de su clase.

5. Reemplace el método Recognize para implementar su propio comportamiento de reconocimiento personalizado. Su implementación de Recognize debe llamar al método PersistTag para que Excel reconozca la etiqueta inteligente.

6. Cree controladores de eventos para responder al evento Click y, opcionalmente, al evento BeforeCaptionShow, de las acciones creadas.

7. En el archivo de código del documento del libro, agregue la instancia de etiqueta inteligente a la propiedad VstoSmartTags de la clase ThisWorkbook (para un proyecto en el nivel del documento) o la propiedad VstoSmartTags de la clase ThisAddIn (para un proyecto en el nivel de la aplicación).

   Nota:
   Si utiliza un proyecto en el nivel de la aplicación creado antes de instalar SP1, debe modificar el proyecto para que genere la propiedad VstoSmartTags. Para obtener más información, vea Cómo: Agregar etiquetas inteligentes en el nivel de la aplicación a proyectos creados con anterioridad al SP1.

Ejemplo

En el ejemplo de código siguiente se muestra cómo crear una etiqueta inteligente personalizada en un libro de Excel. En el ejemplo se reemplaza el método Recognize para reconocer los términos sales y organization de una celda de hoja de cálculo. El método Recognize agrega un par de clave y valor a la colección de propiedades principales de la etiqueta inteligente. El método llama, a continuación, al método PersistTag para reconocer la etiqueta inteligente y guardar la nueva propiedad de etiqueta inteligente. Para probar el ejemplo, escriba las palabras sales y organization en celdas diferentes del libro y, a continuación, pruebe las acciones de la etiqueta inteligente. Una acción muestra el valor de la propiedad correspondiente para el término reconocido y la otra, muestra el espacio de nombres de la etiqueta inteligente y el título.

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 + "'.");
        }
    }
}

Compilar el código

• En el proyecto, agregue una referencia a la Biblioteca de tipos de Etiquetas inteligentes de Microsoft 2.0 de la ficha COM del cuadro de diálogo Agregar referencia. Compruebe que la propiedad Copy Local de la referencia es false. Si es true, la referencia no se aplica al ensamblado de interoperabilidad primario correcto y se debe instalar el ensamblado de los discos de instalación de Microsoft Office. Para obtener más información, vea Cómo: Instalar ensamblados de interoperabilidad primario de Office.

• Coloque el código de ejemplo en un nuevo archivo de clase denominado CustomSmartTag.

• En C#, cambie el espacio de nombres para que coincida con el nombre del proyecto.

• Agregue Imports (en Visual Basic) o instrucciones using (en C#) para los espacios de nombres Microsoft.Office.Tools.Excel y Microsoft.Office.Interop.SmartTag en la parte superior del archivo de clases.

• Agregue el código siguiente al controlador de eventos ThisAddIn_Startup o ThisWorkbook_Startup en su proyecto. Este código agrega la etiqueta inteligente personalizada al libro.

  Me.VstoSmartTags.Add(New CustomSmartTag())
  

  this.VstoSmartTags.Add(new CustomSmartTag());
  

Seguridad

Debe habilitar las etiquetas inteligentes en Excel. No están habilitadas de manera predeterminada. Para obtener más información, vea Cómo: Habilitar las etiquetas inteligentes en Word y en Excel.

Vea también

Tareas

Cómo: Habilitar las etiquetas inteligentes en Word y en Excel

Cómo: Agregar etiquetas inteligentes a documentos de Word

Cómo: Agregar etiquetas inteligentes a libros de Excel

Cómo: Crear etiquetas inteligentes con reconocedores personalizados en Word

Tutorial: Crear una etiqueta inteligente usando una personalización en el nivel del documento.

Tutorial: Crear una etiqueta inteligente usando un complemento en el nivel de la aplicación

Conceptos

Información general sobre etiquetas inteligentes

Arquitectura de las etiquetas inteligentes

Personalización de la interfaz de usuario de Office

Historial de cambios