Arquitectura de las etiquetas inteligentes

Artículo
08/10/2011

Las herramientas de desarrollo de Office en Visual Studio 2010 proporcionan un modelo de objetos de etiquetas inteligentes flexible que permite agregar rápidamente etiquetas inteligentes a los documentos de Microsoft Office Word y los libros de Microsoft Office Excel. Para los escenarios avanzados, también puede crear sus propios reconocedores de etiquetas inteligentes y datos de acceso que se almacenan en la etiqueta inteligente.

Para obtener más información sobre las etiquetas inteligentes, vea Información general sobre etiquetas inteligentes.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento y los proyectos de nivel de aplicación para Excel 2007 y Word 2007. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Información general sobre el modelo de objetos

El modelo de objetos de etiquetas inteligentes separa las etiquetas inteligentes de las acciones que estas realizan. En las siguientes secciones se describen los objetos principales que se usan para crear etiquetas inteligentes. Para obtener ejemplos de código que muestren cómo agregar etiquetas inteligentes a un documento, vea Cómo: Agregar etiquetas inteligentes a documentos de Word y Cómo: Agregar etiquetas inteligentes a libros de Excel.

Etiquetas inteligentes

En el código, una etiqueta inteligente es un objeto Microsoft.Office.Tools.Excel.SmartTag o Microsoft.Office.Tools.Word.SmartTag. Estos objetos incluyen las siguientes propiedades:

Terms y Expressions. Estas propiedades contienen los términos reconocibles de la etiqueta inteligente. Para especificar una cadena simple, agregue la cadena a la propiedad Terms. Para especificar una cadena compleja, agregue una expresión regular que describa la cadena a la propiedad Expressions.
Actions. Esta propiedad contiene las acciones que se realizarán cuando el usuario seleccione la etiqueta inteligente.
Caption. Esta propiedad especifica la etiqueta de la etiqueta inteligente.

Acciones

Cuando el usuario selecciona su etiqueta inteligente, puede realizar una o más acciones que son específicas de la etiqueta inteligente. Cada acción se representa mediante un objeto Microsoft.Office.Tools.Word.Action o Microsoft.Office.Tools.Excel.Action. Estos objetos proporcionan los eventos BeforeCaptionShow y Click:

Se provoca el evento BeforeCaptionShow inmediatamente después de que el usuario haga clic en el icono de la etiqueta inteligente, pero antes de que se muestre el menú de etiquetas inteligentes. Controle este evento si desea modificar en tiempo de ejecución el título de la acción en el menú de etiquetas inteligentes.
Se provoca el evento Click cuando el usuario hace clic en el título de la acción en el menú de etiquetas inteligentes. Controle este evento para ejecutar código cuando el usuario haga clic en la acción.

Los controladores de estos eventos reciben un objeto Microsoft.Office.Tools.Excel.ActionEventArgs o Microsoft.Office.Tools.Word.ActionEventArgs que proporciona acceso al texto reconocido e indica su ubicación.

Crear etiquetas inteligentes

La manera de crear una etiqueta inteligente depende de si el proyecto se destina a .NET Framework 3.5 o .NET Framework 4.

Si está destinado a .NET Framework 3.5, SmartTag y Action son clases de las que se pueden crear instancias directamente. En el siguiente ejemplo de código se muestra cómo crear una etiqueta inteligente simple en un proyecto de Word destinado a .NET Framework 3.5. Para usar este ejemplo, ejecute el código desde la clase ThisDocument en un proyecto de nivel de documento o la clase ThisAddIn en un proyecto de nivel de aplicación.

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);

Cuando la versión de destino es .NET Framework 4, SmartTag y Action son interfaces de las que no se pueden crear instancias directamente. En su lugar, se deben usar los métodos CreateAction y CreateSmartTag proporcionados por la clase Globals en el proyecto para obtener instancias de estos objetos. Para obtener más información sobre la clase Globals, vea Acceso global a objetos en los proyectos de Office. En el siguiente ejemplo de código se muestra cómo crear una etiqueta inteligente simple en un proyecto de Word destinado a .NET Framework 4. Para usar este ejemplo, ejecute el código desde la clase ThisDocument en un proyecto de nivel de documento o la clase ThisAddIn en un proyecto de nivel de aplicación.

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);

Para obtener más instrucciones y ejemplos de código con etiquetas inteligentes más complejas, vea Cómo: Agregar etiquetas inteligentes a documentos de Word y Cómo: Agregar etiquetas inteligentes a libros de Excel.

Crear reconocedores de etiquetas inteligentes

Si desea personalizar el comportamiento predeterminado para reconocer etiquetas inteligentes, puede crear su propio reconocedor de etiquetas inteligentes. La manera de hacerlo depende de si su proyecto está destinado a .NET Framework 3.5 y .NET Framework 4.

Comportamiento predeterminado del reconocimiento de texto

Cuando un usuario escribe texto en un documento o en un libro, Word y Excel crean una lista de tokens a partir del texto. El reconocedor de etiquetas inteligentes predeterminado recibe esta lista de tokens y el texto completo escrito por el usuario. El reconocedor predeterminado identifica una etiqueta inteligente si se cumple una de las condiciones siguientes:

Una de las cadenas en la propiedad Terms coincide exactamente con uno de los símbolos en el documento o el libro.
Una de las expresiones regulares en la propiedad Expressions se corresponde con el texto completo escrito por el usuario.

Word y Excel analizan cadenas que contienen espacios incrustados, o cadenas que combinan letras, números y símbolos, en token separados cuando un usuario las escribe. Por ejemplo, si el usuario escribe "sales report", Word y Excel crean los símbolos (token) "sales" y "report". Del mismo modo, si el usuario escribe "2005sales", Word y Excel crean los tokens "2005" y "sales".

Si desea que su etiqueta inteligente reconozca una cadena que contiene espacios incrustados o una cadena que combina letras, números y símbolos, no agregue la cadena a la propiedad Terms. En lugar de ello, agregue una expresión regular que describa la cadena a la propiedad Expressions o cree su propio reconocedor para buscar la cadena.

Crear reconocedores de etiquetas inteligentes en proyectos destinados a .NET Framework 4

Para crear su propio reconocedor de etiquetas inteligentes, defina una clase que implemente la interfaz Microsoft.Office.Tools.Excel.ISmartTagExtension o Microsoft.Office.Tools.Word.ISmartTagExtension. En la implementación del método ISmartTagExtension.Recognize, busque términos de etiquetas inteligentes en el texto y registre la etiqueta inteligente con Word o Excel si encuentra alguno. Para registrar una etiqueta inteligente, llame al método PersistTag del parámetro context del método Recognize.

En el siguiente ejemplo de código se muestra cómo crear una clase de etiqueta inteligente simple con un reconocedor personalizado en un proyecto de Word destinado 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; }
    }
}

Para obtener más instrucciones y ejemplos de código con clases de etiquetas inteligentes más complejas con reconocedores personalizados, vea Cómo: Crear etiquetas inteligentes con reconocedores personalizados en Word y .NET Framework 4 y Cómo: Crear etiquetas inteligentes con reconocedores personalizados en Excel y .NET Framework 4.

Crear reconocedores de etiquetas inteligentes en proyectos destinados a .NET Framework 3.5

Para crear su propio reconocedor de etiquetas inteligentes, derive una clase de Microsoft.Office.Tools.Word.SmartTag o Microsoft.Office.Tools.Excel.SmartTag y, a continuación, invalide el método SmartTag.Recognize en la clase. En el método , busque términos de etiquetas inteligentes en el texto y registre la etiqueta inteligente con Word o Excel si encuentra alguno. Para registrar una etiqueta inteligente, llame al método PersistTag que su clase deriva de Microsoft.Office.Tools.Word.SmartTag o Microsoft.Office.Tools.Excel.SmartTag.

En el siguiente ejemplo de código se muestra cómo crear una clase de etiqueta inteligente simple con un reconocedor personalizado en un proyecto de Word destinado a .NET Framework 3.5.

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);
        }
    }
}

Para obtener más instrucciones y ejemplos de código con clases de etiquetas inteligentes más complejas con reconocedores personalizados, vea Cómo: Crear etiquetas inteligentes con reconocedores personalizados en Word y .NET Framework 3.5 y Cómo: Crear etiquetas inteligentes con reconocedores personalizados en Excel y .NET Framework 3.5.

Almacenar y recuperar datos de la bolsa de propiedades

Las etiquetas inteligentes pueden almacenar los datos en una colección de pares de clave y valor, conocida como bolsa de propiedades. Cada valor y clave de la bolsa de propiedades es una cadena.

Hay dos maneras de tener acceso al contenedor de propiedades:

Puede controlar los eventos BeforeCaptionShow o Click de un objeto Microsoft.Office.Tools.Excel.Action o Microsoft.Office.Tools.Word.Action y usar la propiedad Properties del parámetro de argumento de evento para escribir y leer en el contenedor de propiedades de la etiqueta inteligente. La propiedad Properties devuelve un objeto ISmartTagProperties. La interfaz ISmartTagProperties está disponible cuando se agrega al proyecto una referencia a Microsoft Smart Tags 2.0 Type Library.
Para crear un reconocedor de etiquetas inteligentes, siga las instrucciones anteriores. En su implementación o invalidación del método Recognize, use el método GetNewPropertyBag del parámetro site para obtener un objeto ISmartTagProperties que se pueda usar para escribir y leer en el contenedor de propiedades de la etiqueta inteligente.

Para obtener ejemplos de cómo escribir y leer en el contenedor de propiedades, vea los temas siguientes.

Expresiones regulares y la bolsa de propiedades

Cuando se asigna una expresión regular a una etiqueta inteligente, el reconocedor predeterminado agrega un par de clave y valor por cada grupo capturado en la expresión regular al contenedor de propiedades de la etiqueta inteligente.

Para obtener un ejemplo que muestre este comportamiento, vea Tutorial: Crear una etiqueta inteligente usando una personalización de nivel de documento.. Para obtener más información sobre grupos capturados en expresiones regulares, vea Construcciones de agrupamiento y El modelo de objetos de expresión regular.