Smarttagarchitektur

  • Artikel

Die Office-Entwicklungstools in Visual Studio 2010 bieten ein flexibles Smarttagobjektmodell, mit dem Sie Microsoft Office Word-Dokumenten und Microsoft Office Excel-Arbeitsmappen rasch Smarttags hinzufügen können. Für erweiterte Szenarios können Sie auch eigene Smarttagerkennungen erstellen und auf Daten zugreifen, die in dem Smarttag gespeichert sind.

Weitere Informationen zu Smarttags finden Sie unter Übersicht über Smarttags.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Dokument- und auf Anwendungsebene für Excel 2007 und Word 2007. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Übersicht über das Objektmodell

Das Smarttagobjektmodell trennt Smarttags von den Aktionen, die Smarttags ausführen. In den folgenden Abschnitten werden die Hauptobjekte beschrieben, mit denen Sie Smarttags erstellen. Codebeispiele, in denen das Hinzufügen von Smarttags zu Dokumenten veranschaulicht wird, finden Sie unter Gewusst wie: Hinzufügen von Smarttags zu Word-Dokumenten und Gewusst wie: Hinzufügen von Smarttags zu Excel-Arbeitsmappen.

Smarttags

Im Code ist ein Smarttag ein Microsoft.Office.Tools.Word.SmartTag-Objekt oder ein Microsoft.Office.Tools.Excel.SmartTag-Objekt. Zu diesen Objekten gehören die folgenden Eigenschaften:

  • Terms und Expressions. Diese Eigenschaften enthalten die bekannten Ausdrücke für das Smarttag. Um eine einfache Zeichenfolge anzugeben, fügen Sie die Zeichenfolge der Terms-Eigenschaft hinzu. Um eine komplexe Zeichenfolge anzugeben, fügen Sie der Expressions-Eigenschaft einen regulären Ausdruck hinzu, der die Zeichenfolge beschreibt.

  • Actions. Diese Eigenschaft enthält die auszuführenden Aktionen, wenn der Benutzer das Smarttag auswählt.

  • Caption. Diese Eigenschaft gibt die Bezeichnung des Smarttags an.

Aktionen

Wenn der Benutzer das Smarttag auswählt, kann er eine oder mehrere Aktionen ausführen, die speziell für das Smarttag gelten. Jede Aktion wird durch ein Microsoft.Office.Tools.Word.Action-Objekt oder ein Microsoft.Office.Tools.Excel.Action-Objekt dargestellt. Diese Objekte stellen das BeforeCaptionShow-Ereignis und das Click-Ereignis bereit:

  • Das Auslösen des BeforeCaptionShow-Ereignisses erfolgt unmittelbar nach dem Klicken des Benutzers auf das Smarttagsymbol, jedoch vor dem Anzeigen des Smarttagmenüs. Behandeln Sie dieses Ereignis, wenn Sie den Aktionstitel im Smarttagmenü zur Laufzeit ändern möchten.

  • Das Click-Ereignis wird ausgelöst, wenn der Benutzer auf den Aktionstitel im Smarttagmenü klickt. Behandeln Sie dieses Ereignis, um Code auszuführen, wenn der Benutzer auf die Aktion klickt.

Die Ereignishandler für diese Ereignisse empfangen ein Microsoft.Office.Tools.Excel.ActionEventArgs-Objekt oder ein Microsoft.Office.Tools.Word.ActionEventArgs-Objekt, das den Zugriff auf den erkannten Text und die Position des Texts ermöglicht.

Erstellen von Smarttags

Die Art und Weise, wie Sie ein Smarttag erstellen, hängt davon ab, ob das Projekt auf .NET Framework 3.5 oder .NET Framework 4 abzielt.

Wenn Sie auf .NET Framework 3.5 abzielen, sind SmartTag und Action Klassen, die Sie direkt instanziieren können. Im folgenden Codebeispiel wird veranschaulicht, wie ein einfaches Smarttag in einem Word-Projekt erstellt wird, das auf .NET Framework 3.5 abzielt. Um dieses Beispiel zu verwenden, führen Sie den Code aus der ThisDocument-Klasse in einem Projekt auf Dokumentebene oder die ThisAddIn-Klasse in einem Projekt auf Anwendungsebene aus.

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

Wenn Sie auf .NET Framework 4 abzielen, sind SmartTag und Action Schnittstellen, die Sie nicht direkt instanziieren können. Stattdessen müssen Sie die CreateSmartTag-Methode und die CreateAction-Methode verwenden, die von der Globals-Klasse in Ihrem Projekt bereitgestellt werden, um Instanzen dieser Objekte abzurufen. Weitere Informationen über die Globals-Klasse finden Sie unter Globaler Zugriff auf Objekte in Office-Projekten. Im folgenden Codebeispiel wird veranschaulicht, wie ein einfaches Smarttag in einem Word-Projekt erstellt wird, das auf .NET Framework 4 abzielt. Um dieses Beispiel zu verwenden, führen Sie den Code aus der ThisDocument-Klasse in einem Projekt auf Dokumentebene oder die ThisAddIn-Klasse in einem Projekt auf Anwendungsebene aus.

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

‪Weitere Anweisungen und Codebeispiele, in denen komplexere Smarttags zu veranschaulicht werden, finden Sie unter Gewusst wie: Hinzufügen von Smarttags zu Word-Dokumenten und Gewusst wie: Hinzufügen von Smarttags zu Excel-Arbeitsmappen.

Erstellen von Smarttagerkennungen

Wenn Sie das Standardverhalten für die Smarttagerkennung anpassen möchten, können Sie eine eigene Smarttagerkennung erstellen. Die Art und Weise, wie Sie hierfür vorgehen, hängt davon ab, ob das Projekt auf .NET Framework 3.5 und .NET Framework 4 abzielt.

Standard-Texterkennungsverhalten

Wenn ein Benutzer Text in ein Dokument oder eine Arbeitsmappe eingibt, wird in Word und Excel aus dem Text eine Liste von Token erstellt. Die Smarttag-Standarderkennung nimmt diese Tokenliste und den vollständigen, vom Benutzer eingegebenen Text entgegen. Damit die Standarderkennung ein Smarttag identifiziert, muss eine der folgenden Bedingungen erfüllt sein:

  • Eine der Zeichenfolgen in der Terms-Eigenschaft stimmt mit einem der Token im Dokument bzw. in der Arbeitsmappe überein.

  • Einer der regulären Ausdrücke in der Expressions-Eigenschaft stimmt mit eine Passage im vollständigen, vom Benutzer eingegebenen Text überein.

Word und Excel analysieren während der Benutzereingabe Zeichenfolgen mit Leerzeichen oder Zeichenfolgen, in denen Buchstaben, Zahlen und Symbole kombiniert sind, und erstellen daraus einzelne Token. Wenn der Benutzer z. B. "Verkaufsbericht Januar" eingibt, erstellen Word und Excel die Token "Verkaufsbericht" und "Januar". Entsprechend werden bei der Eingabe von "2005sales" von Word und Excel die Token "2005" und "sales" erstellt.

Wenn mit dem Smarttag eine Zeichenfolge mit Leerzeichen oder mit einer Kombination aus Buchstaben, Zahlen und Symbolen erkannt werden soll, fügen Sie die entsprechende Zeichenfolge nicht der Terms-Eigenschaft hinzu. Fügen Sie stattdessen der Expressions-Eigenschaft einen regulären Ausdruck hinzu, der die Zeichenfolge beschreibt, oder erstellen Sie eine eigene Erkennung, mit der nach der Zeichenfolge gesucht wird.

Erstellen von Smarttagerkennungen in Projekten, die auf .NET Framework 4 abzielen

Um eine eigene Smarttagerkennung zu erstellen, definieren Sie eine Klasse, die die Microsoft.Office.Tools.Word.ISmartTagExtension-Schnittstelle oder die Microsoft.Office.Tools.Excel.ISmartTagExtension-Schnittstelle implementiert. In der Implementierung der ISmartTagExtension.Recognize-Methode müssen Sie den Text für Smarttagbegriffe suchen und das Smarttag in Word oder Excel registrieren, falls ein Smarttagbegriff gefunden wird. Um ein Smarttag zu registrieren rufen Sie die PersistTag-Methode des context-Parameters der Recognize-Methode auf.

Im folgenden Codebeispiel wird veranschaulicht, wie eine einfache Smarttagklasse mit einer benutzerdefinierten Erkennung in einem Word-Projekt erstellt wird, das auf .NET Framework 4 abzielt.

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

Weitere Anweisungen und Codebeispiele, in denen komplexere Smarttagklassen mit benutzerdefinierten Erkennungen veranschaulicht werden, finden Sie unter Gewusst wie: Erstellen von Smarttags mit benutzerdefinierten Erkennungen in Word und .NET Framework 4 und Gewusst wie: Erstellen von Smarttags mit benutzerdefinierten Erkennungen in Excel und .NET Framework 4

Erstellen von Smarttagerkennungen in Projekten, die auf .NET Framework 3.5 abzielen

Leiten Sie zum Erstellen einer eigenen Smarttagerkennung eine Klasse von Microsoft.Office.Tools.Word.SmartTag oder Microsoft.Office.Tools.Excel.SmartTag ab, und überschreiben Sie dann die SmartTag.Recognize-Methode in der Klasse. In der Methode müssen Sie den Text für Smarttagbegriffe suchen und das Smarttag in Word oder Excel registrieren, falls ein Smarttagbegriff gefunden wird. Um ein Smarttag zu registrieren, rufen Sie die PersistTag-Methode auf, die die Klasse aus Microsoft.Office.Tools.Word.SmartTag oder Microsoft.Office.Tools.Excel.SmartTag ableitet.

Im folgenden Codebeispiel wird veranschaulicht, wie eine einfache Smarttagklasse mit einer benutzerdefinierten Erkennung in einem Word-Projekt erstellt wird, das auf .NET Framework 3.5 abzielt.

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

Weitere Anweisungen und Codebeispiele, in denen komplexere Smarttagklassen mit benutzerdefinierten Erkennungen veranschaulicht werden, finden Sie unter Gewusst wie: Erstellen von Smarttags mit benutzerdefinierten Erkennungen in Word und .NET Framework 3.5 und Gewusst wie: Erstellen von Smarttags mit benutzerdefinierten Erkennungen in Excel und .NET Framework 3.5

Speichern und Abrufen von Daten in der Eigenschaftensammlung

Smarttags können Daten in einer Auflistung von Schlüssel-Wert-Paaren speichern, die als Eigenschaftensammlung bezeichnet wird. Jeder Wert und jeder Schlüssel in der Eigenschaftensammlung ist eine Zeichenfolge.

Es gibt zwei Möglichkeiten, um auf die Eigenschaftensammlung zuzugreifen:

  • Sie können das Click-Ereignis oder das BeforeCaptionShow-Ereignis eines Microsoft.Office.Tools.Word.Action-Objekts oder Microsoft.Office.Tools.Excel.Action-Objekts behandeln und die Properties-Eigenschaft des Ereignisargumentparameters verwenden, um in der Eigenschaftensammlung des Smarttags zu lesen und zu schreiben. Die Properties-Eigenschaft gibt ein ISmartTagProperties -Objekt zurück. Die ISmartTagProperties-Schnittstelle steht Ihnen zu Verfügung, wenn Sie dem Projekt einen Verweis auf die Microsoft Smart Tags 2.0-Typbibliothek hinzufügen.

  • Sie können eine benutzerdefinierte Smarttagerkennung erstellen, indem Sie den Anweisungen oben folgen. Verwenden Sie in der Implementierung oder Überschreibung der Recognize-Methode die GetNewPropertyBag-Methode des site-Parameters, um ein ISmartTagProperties-Objekt abzurufen, das Sie zum Schreiben und Lesen der Eigenschaftensammlung des Smarttags verwenden können.

Beispiele für das Schreiben und Lesen in der Eigenschaftensammlung finden Sie in den folgenden Themen:

Reguläre Ausdrücke und die Eigenschaftensammlung

Wenn Sie einem Smarttag einen regulären Ausdruck zuweisen, fügt die Standarderkennung der Eigenschaftensammlung des Smarttags für jede erfasste Gruppe des regulären Ausdrucks ein Schlüssel-Wert-Paar hinzu.

Ein Beispiel, in dem dieses Verhalten veranschaulicht wird, finden Sie unter Exemplarische Vorgehensweise: Erstellen eines Smarttags mit einer Anpassung auf Dokumentebene. Weitere Informationen über erfasste Gruppen in regulären Ausdrücken finden Sie unter Gruppierungskonstrukte und unter Das Objektmodell für reguläre Ausdrücke.

Siehe auch

Aufgaben

Gewusst wie: Aktivieren von Smarttags in Word und Excel

Gewusst wie: Hinzufügen von Smarttags zu Word-Dokumenten

Gewusst wie: Hinzufügen von Smarttags zu Excel-Arbeitsmappen

Gewusst wie: Erstellen von Smarttags mit benutzerdefinierten Erkennungen in Word und .NET Framework 3.5

Gewusst wie: Erstellen von Smarttags mit benutzerdefinierten Erkennungen in Excel und .NET Framework 3.5

Exemplarische Vorgehensweise: Erstellen eines Smarttags mit einer Anpassung auf Dokumentebene

Exemplarische Vorgehensweise: Erstellen eines Smarttags mit einem Add-In auf Anwendungsebene

Weitere Ressourcen

Übersicht über Smarttags