Architecture des balises actives

Article
08/10/2011

Les outils de développement Office dans Visual Studio 2010 fournissent un modèle objet de balise active flexible qui vous permet d'ajouter rapidement des balises actives aux documents Microsoft Office Word et aux classeurs Microsoft Office Excel. Pour les scénarios avancés, vous pouvez également créer vos propres modules de reconnaissance des balises actives et accéder aux données qui sont stockées dans la balise active.

Pour plus d'informations sur les balises actives, consultez Vue d'ensemble des balises actives.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document et de niveau application pour Excel 2007 et Word 2007. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Vue d'ensemble du modèle objet

Le modèle objet de balise active sépare les balises actives des actions que les balises actives exécutent. Les sections suivantes décrivent les principaux objets que vous utilisez pour créer des balises actives. Pour obtenir des exemples de code montrant comment ajouter des balises actives à un document, consultez Comment : ajouter des balises actives à des documents Word et Comment : ajouter des balises actives aux classeurs Excel.

Balises actives

Dans votre code, une balise active est un objet Microsoft.Office.Tools.Word.SmartTag ou Microsoft.Office.Tools.Excel.SmartTag. Ces objets incluent les propriétés suivantes :

Terms et Expressions. Ces propriétés contiennent les termes reconnaissables pour la balise active. Pour spécifier une chaîne simple, ajoutez la chaîne à la propriété Terms. Pour spécifier une chaîne complexe, ajoutez une expression régulière décrivant la chaîne à la propriété Expressions.
Actions. Cette propriété contient les actions à exécuter lorsque l'utilisateur sélectionne la balise active.
Caption. Cette propriété spécifie l'étiquette de la balise active.

Actions

Lorsque l'utilisateur sélectionne votre balise active, il peut effectuer une ou plusieurs actions propres à celle-ci. Chaque action est représentée par un objet Microsoft.Office.Tools.Word.Action ou Microsoft.Office.Tools.Excel.Action. Ces objets fournissent les événements BeforeCaptionShow et Click :

L'événement BeforeCaptionShow est déclenché juste après que l'utilisateur a cliqué sur l'icône de balise active, mais avant que le menu Balise active ne s'affiche. Gérez cet événement si vous souhaitez modifier le titre de l'action dans le menu de balise active au moment de l'exécution.
L'événement Click est déclenché lorsque l'utilisateur clique sur le titre de l'action dans le menu Balise active. Gérez cet événement pour qu'il exécute du code lorsque l'utilisateur clique sur l'action.

Les gestionnaires d'événements de ces événements reçoivent un objet Microsoft.Office.Tools.Excel.ActionEventArgs ou Microsoft.Office.Tools.Word.ActionEventArgs qui permet d'accéder au texte reconnu et à l'emplacement du texte.

Création de balises actives

La façon dont vous créez une balise active dépend de la version ciblée pour votre projet : .NET Framework 3.5 ou .NET Framework 4.

Lorsque vous ciblez .NET Framework 3.5, SmartTag et Action sont des classes que vous pouvez instancier directement. L'exemple de code suivant montre comment créer une balise active simple dans un projet Word qui cible .NET Framework 3.5. Pour utiliser cet exemple, exécutez le code à partir de la classe ThisDocument dans un projet au niveau du document ou de la classe ThisAddIn dans un projet au niveau de l'application.

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

Lorsque vous ciblez .NET Framework 4, SmartTag et Action sont des interfaces que vous ne pouvez pas instancier directement. Au lieu de cela, vous devez utiliser les méthodes CreateSmartTag et CreateAction fournies par la classe Globals dans votre projet pour obtenir des instances de ces objets. Pour plus d'informations sur la classe Globals, consultez Accès global aux objets dans les projets Office. L'exemple de code suivant montre comment créer une balise active simple dans un projet Word qui cible .NET Framework 4. Pour utiliser cet exemple, exécutez le code à partir de la classe ThisDocument dans un projet au niveau du document ou de la classe ThisAddIn dans un projet au niveau de l'application.

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

Pour obtenir des instructions et des exemples de code supplémentaires montrant des balises actives plus complexes, consultez Comment : ajouter des balises actives à des documents Word et Comment : ajouter des balises actives aux classeurs Excel.

Création de module de reconnaissance des balises actives

Si vous souhaitez personnaliser le comportement par défaut de reconnaissance de la balise active, vous pouvez créer votre propre module de reconnaissance des balises actives. La façon dont vous le faites varie selon que votre projet cible .NET Framework 3.5 ou .NET Framework 4.

Comportement de la reconnaissance du texte par défaut

Lorsqu'un utilisateur tape du texte dans un document ou dans un classeur, Word et Excel créent une liste de jetons à partir de ce texte. Le module de reconnaissance des balises actives par défaut reçoit cette liste de jetons ainsi que le texte complet tapé par l'utilisateur. Le module de reconnaissance par défaut identifie une balise active si l'une des conditions suivantes est satisfaite :

Une des chaînes de la propriété Terms correspond exactement à l'un des jetons dans le document ou le classeur.
Une des expressions régulières dans la propriété Expressions a une correspondance dans le texte complet entré par l'utilisateur.

Word et Excel analysent les chaînes contenant des espaces incorporés, ou les chaînes qui associent des lettres, des chiffres et des symboles, dans des jetons séparés lorsqu'un utilisateur les entre. Par exemple, si l'utilisateur entre « rapport de ventes », Word et Excel créent les jetons « ventes » et « rapport ». De la même façon, si l'utilisateur entre "ventes 2005", Word et Excel créent les jetons "2005" et "ventes".

Pour que la balise active reconnaisse une chaîne contenant des espaces incorporés ou une chaîne associant des lettres, des chiffres et des symboles, n'ajoutez pas la chaîne à la propriété Terms. Ajoutez plutôt une expression régulière décrivant la chaîne à la propriété Expressions ou créez votre propre module de reconnaissance qui recherche la chaîne.

Création de modules de reconnaissance des balises actives dans les projets qui ciblent .NET Framework 4

Pour créer votre propre module de reconnaissance des balises actives, définissez une classe qui implémente l'interface Microsoft.Office.Tools.Word.ISmartTagExtension ou Microsoft.Office.Tools.Excel.ISmartTagExtension. Dans votre implémentation de la méthode ISmartTagExtension.Recognize, recherchez les termes des balises actives dans le texte et inscrivez la balise active auprès de Word ou Excel si vous trouvez un terme de balise active. Pour inscrire une balise active, appelez la méthode PersistTag du paramètre context de la méthode Recognize.

L'exemple de code suivant montre comment créer une classe de balise active simple avec un module de reconnaissance personnalisé dans un projet Word qui cible .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; }
    }
}

Pour obtenir des instructions et des exemples de code supplémentaires qui montrent des classes de balise active plus complexes avec des modules de reconnaissance personnalisés, consultez Comment : créer des balises actives avec des modules de reconnaissance personnalisés dans Word et dans .NET Framework 4 et Comment : créer des balises actives avec des modules de reconnaissance personnalisés dans Excel et dans .NET Framework 4.

Création de modules de reconnaissance des balises actives dans les projets qui ciblent .NET Framework 3.5

Pour créer votre propre module de reconnaissance des balises actives, dérivez une classe de Microsoft.Office.Tools.Word.SmartTag ou de Microsoft.Office.Tools.Excel.SmartTag, puis substituez la méthode SmartTag.Recognize dans la classe. Dans votre méthode, recherchez les termes de balise active dans le texte et inscrivez la balise active auprès de Word ou Excel lorsque vous trouvez un terme. Pour inscrire une balise active, appelez la méthode PersistTag que votre classe dérive de Microsoft.Office.Tools.Word.SmartTag ou Microsoft.Office.Tools.Excel.SmartTag.

L'exemple de code suivant montre comment créer une classe de balise active simple avec un module de reconnaissance personnalisé dans un projet Word qui cible .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);
        }
    }
}

Pour obtenir des instructions et des exemples de code supplémentaires qui montrent des classes de balise active plus complexes avec des modules de reconnaissance personnalisés, consultez Comment : créer des balises actives avec des modules de reconnaissance personnalisés dans Word et dans .NET Framework 3.5 et Comment : créer des balises actives avec des modules de reconnaissance personnalisés dans Excel et dans .NET Framework 3.5.

Stockage et récupération de données dans le sac de propriétés

Les balises actives peuvent stocker des données dans une collection de paires clé/valeur, désignée par le terme « sac de propriétés ». Chaque valeur et chaque clé du sac de propriétés sont une chaîne.

Il existe deux façons d'accéder au conteneur des propriétés :

Vous pouvez gérer les événements Click ou BeforeCaptionShow d'un objet Microsoft.Office.Tools.Word.Action ou Microsoft.Office.Tools.Excel.Action et utiliser la propriété Properties du paramètre d'argument d'événement pour écrire dans le conteneur des propriétés de la balise active et y lire des informations. La propriété Properties retourne un objet ISmartTagProperties. L'interface ISmartTagProperties est disponible lorsque vous ajoutez à votre projet une référence à la Bibliothèque de types Microsoft Smart Tags 2.0.
Vous pouvez créer un module de reconnaissance des balises actives personnalisé en suivant les instructions ci-dessus. Dans votre implemention ou substitution de la méthode Recognize, utilisez la méthode GetNewPropertyBag du paramètre site pour obtenir un objet ISmartTagProperties que vous pouvez utiliser pour écrire dans le conteneur des propriétés de la balise active et pour y lire des informations.

Pour obtenir des exemples de lecture et d'écriture dans le conteneur des propriétés, consultez les rubriques suivantes :

Expressions régulières et sac de propriétés

Lorsque vous assignez une expression régulière à une balise active, le module de reconnaissance par défaut ajoute une paire clé-valeur pour chaque groupe capturé par l'expression régulière au conteneur des propriétés de la balise active.

Pour obtenir un exemple qui illustre ce comportement, consultez Procédure pas à pas : création d'une balise active à l'aide d'une personnalisation au niveau du document. Pour obtenir plus d'informations sur les groupes capturés dans des expressions régulières, consultez Constructions de regroupement et Modèle objet d'expression régulière.