共用方式為

智慧標籤架構

  • 發行項

Visual Studio 2010 中的 Office 開發工具提供彈性的智慧標籤物件模型，可以讓您快速將智慧標籤加入至 Microsoft Office Word 文件和 Microsoft Office Excel 活頁簿。 若要進一步應用，您還可以建立自己的智慧標籤辨識器，並存取智慧標籤中儲存的資料。

如需智慧標籤的詳細資訊，請參閱智慧標籤概觀。

**適用於：**本主題中的資訊適用於 Excel 2007 和 Word 2007 的文件層級專案和應用程式層級專案。如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

物件模型概觀

智慧標籤物件模型將智慧標籤與智慧標籤所執行的動作區隔開來。 下列各節說明用來建立智慧標籤的主要物件。 如需示範如何在文件中加入智慧標籤的程式碼範例，請參閱 HOW TO：將置智慧標籤加入至 Word 文件和 HOW TO：在 Excel 活頁簿中加入智慧標籤。

智慧標籤

在您的程式碼中，智慧標籤是 Microsoft.Office.Tools.Word.SmartTag 或 Microsoft.Office.Tools.Excel.SmartTag 物件。 這些物件包含下列屬性：

  • Terms 和 Expressions： 這些屬性包含智慧標籤可辨識的詞彙。 若要指定簡單字串，請將字串加入至 Terms 屬性。 若要指定複雜字串，請將描述該字串的規則運算式 (Regular Expression) 加入至 Expressions 屬性。

  • Actions. 這個屬性包含要在使用者選取智慧標籤時執行的動作。

  • Caption. 這個屬性指定智慧標籤 (Tag) 的標籤 (Label)。

動作

當使用者選取智慧標籤時，便可以執行該智慧標籤專屬的一個或多個動作。 每個動作都以 Microsoft.Office.Tools.Word.Action 或 Microsoft.Office.Tools.Excel.Action 物件表示。 這些物件提供 BeforeCaptionShow 和 Click 事件：

  • BeforeCaptionShow 事件會在使用者按一下智慧標籤圖示之後即引發，但這是在智慧標籤功能表顯示之前發生的。 如果您想要在執行階段修改智慧標籤功能表中的動作標題，請處理這個事件。

  • Click 事件會在使用者按一下智慧標籤功能表中的動作標題時引發。 若要在使用者按一下動作時執行程式碼，請處理這個事件。

這些事件的事件處理常式會接收 Microsoft.Office.Tools.Excel.ActionEventArgs 或 Microsoft.Office.Tools.Word.ActionEventArgs 物件，以提供所辨識文字及其位置的存取。

建立智慧標籤

您建立智慧標籤的方式取決於專案的目標是 .NET Framework 3.5 還是 .NET Framework 4。

當您的目標是 .NET Framework 3.5 時，SmartTag 和 Action 是您可以直接執行個體化的類別。 下列程式碼範例示範如何在目標為 .NET Framework 3.5 的 Word 專案中建立簡單的智慧標籤。 若要使用這個範例，請從 ThisDocument 類別 (如果是文件層級專案) 或 ThisAddIn 類別 (如果是應用程式層級專案) 執行程式碼。

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

當您的目標是 .NET Framework 4 時，SmartTag 和 Action 是您無法直接執行個體化的介面。 您必須在專案中改用 Globals 類別所提供的 CreateSmartTag 和 CreateAction 方法，來取得這些物件的執行個體。 如需 Globals 類別的詳細資訊，請參閱 全域存取 Office 專案中的物件。 下列程式碼範例示範如何在目標為 .NET Framework 4 的 Word 專案中建立簡單的智慧標籤。 若要使用這個範例，請從 ThisDocument 類別 (如果是文件層級專案) 或 ThisAddIn 類別 (如果是應用程式層級專案) 執行程式碼。

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

如需進一步指示和示範較複雜智慧標籤的程式碼範例，請參閱 HOW TO：將置智慧標籤加入至 Word 文件和 HOW TO：在 Excel 活頁簿中加入智慧標籤。

建立智慧標籤辨識器

如果您想要自訂預設智慧標籤辨識行為，可以建立您自己的智慧標籤辨識器。 做法取決於專案的目標是 .NET Framework 3.5 還是 .NET Framework 4。

預設文字辨識行為

當使用者在文件或活頁簿中輸入文字時，Word 和 Excel 就會從該文字建立一份語彙基元 (Token) 的清單。 預設智慧標籤辨識器會收到這份語彙基元清單，以及使用者輸入的完整文字。 如果符合下列其中一項條件，預設辨識器就會識別智慧標籤：

  • Terms 屬性的其中一個字串符合文件或活頁簿的其中一個語彙基元。

  • Expressions 屬性的其中一個規則運算式與使用者輸入的完整文字相符。

當使用者輸入字串時，Word 和 Excel 便會將含有內嵌空格的字串或是結合字母、數字和符號的字串剖析成個別的語彙基元。 例如，如果使用者輸入 "sales report"，Word 和 Excel 就會建立語彙基元 "sales" 和 "report"。 同樣地，如果使用者輸入 "2005sales"，Word 和 Excel 就會建立語彙基元 "2005" 和 "sales"。

如果您想要讓智慧標籤辨認含有內嵌空格的字串或是結合字母、數字和符號的字串，請勿將該字串加入至 Terms 屬性。 請改將描述該字串的規則運算式加入至 Expressions 屬性，或是自行建立搜尋該字串的辨識器。

在目標為 .NET Framework 4 的專案中建立智慧標籤辨識器

若要建立您自己的智慧標籤辨識器，請定義實作了 Microsoft.Office.Tools.Word.ISmartTagExtension 或 Microsoft.Office.Tools.Excel.ISmartTagExtension 介面的類別。 實作 ISmartTagExtension.Recognize 方法時，請搜尋文字中的智慧標籤詞彙，並在找到智慧標籤詞彙時，於 Word 或 Excel 中註冊智慧標籤。 若要註冊智慧標籤，請呼叫 Recognize 方法中 context 參數的 PersistTag 方法。

下列程式碼範例示範如何在目標為 .NET Framework 4 的 Word 專案中，使用自訂辨識器來建立簡單的智慧標籤類別。

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

如需進一步指示，和示範使用自訂辨識器建立較複雜智慧標籤類別的程式碼範例，請參閱 HOW TO：使用 Word 中的自訂辨識器和 .NET Framework 4 建立智慧標籤和 HOW TO：使用 Excel 中的自訂辨識器和 .NET Framework 4 建立智慧標籤。

在目標為 .NET Framework 3.5 的專案中建立智慧標籤辨識器

若要建立您自己的智慧標籤辨識器，請從 Microsoft.Office.Tools.Word.SmartTag 或 Microsoft.Office.Tools.Excel.SmartTag 衍生類別，然後覆寫該類別中的 SmartTag.Recognize 方法。 請讓這個方法搜尋文字中的智慧標籤詞彙，並在找到智慧標籤詞彙時，於 Word 或 Excel 中註冊智慧標籤。 若要註冊智慧標籤，請呼叫由您的類別從 Microsoft.Office.Tools.Word.SmartTag 或 Microsoft.Office.Tools.Excel.SmartTag 衍生的 PersistTag 方法。

下列程式碼範例示範如何在目標為 .NET Framework 3.5 的 Word 專案中，使用自訂辨識器來建立簡單的智慧標籤類別。

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

如需進一步指示，和示範使用自訂辨識器建立較複雜智慧標籤類別的程式碼範例，請參閱 HOW TO：使用 Word 中的自訂辨識器和 .NET Framework 3.5 建立智慧標籤和 HOW TO：在 Excel 和 .NET Framework 3.5 中使用自訂辨識器建立智慧標籤。

在屬性包中儲存和擷取資料

智慧標籤可在索引鍵與值配對的集合 (稱為屬性包) 中儲存資料。 屬性包中的每個值與索引鍵都是字串。

有兩種方法可以存取屬性包：

  • 您可以處理 Microsoft.Office.Tools.Word.Action 或 Microsoft.Office.Tools.Excel.Action 物件的 Click 或 BeforeCaptionShow 事件，並使用事件引數參數的 Properties 屬性，以寫入和讀取智慧標籤的屬性包。 Properties 屬性會傳回 ISmartTagProperties 物件。 當您在專案中加入 Microsoft Smart Tags 2.0 Type Library 的參考時，即可使用 ISmartTagProperties 介面。

  • 您可以依照上面的指示來建立自訂智慧標籤辨識器。 實作或覆寫 Recognize 方法時，請使用 site 參數的 GetNewPropertyBag 方法取得 ISmartTagProperties 物件，這個物件可用來寫入和讀取智慧標籤屬性包。

如需如何寫入和讀取屬性包的範例，請參閱下列主題：

規則運算式和屬性包

當您將規則運算式指派給智慧標籤時，預設辨識器會針對每個從規則運算式擷取的群組，在智慧標籤屬性包中加入一對索引鍵值組。

如需示範這個行為的範例，請參閱逐步解說：使用文件層級自訂建立智慧標籤。 如需規則運算式中所擷取群組的詳細資訊，請參閱群組建構和規則運算式物件模型。

請參閱

工作

HOW TO：在 Word 和 Excel 中啟用智慧標籤

HOW TO：將置智慧標籤加入至 Word 文件

HOW TO：在 Excel 活頁簿中加入智慧標籤

HOW TO：使用 Word 中的自訂辨識器和 .NET Framework 3.5 建立智慧標籤

HOW TO：在 Excel 和 .NET Framework 3.5 中使用自訂辨識器建立智慧標籤

逐步解說：使用文件層級自訂建立智慧標籤

逐步解說：使用應用程式層級增益集建立智慧標籤

其他資源

智慧標籤概觀