Архитектура смарт-тегов

  • Статья

Средства разработки Office в среде Visual Studio 2010 предоставляют гибкую объектную модель смарт-тегов, которая позволяет быстро добавлять смарт-теги в документы Microsoft Office Word и книги Microsoft Office Excel. В сложных скриптах можно также создать настраиваемый распознаватель смарт-тегов и получить доступ к данным смарт-тегов.

Дополнительные сведения о смарт-тегах см. в разделе Общие сведения о смарт-тегах.

Применение. Сведения этого раздела применяются к проектам уровня документа и уровня приложения для Excel 2007 и Word 2007. Дополнительные сведения см. в разделе Доступность функций по типам приложений Office и проектов.

Общие сведения об объектной модели

Объектная модель для смарт-тегов разделяет смарт-теги и действия, которые они выполняют. В следующих разделах описываются основные объекты, используемые для создания смарт-тегов. Примеры кода, которые демонстрируют способы добавления смарт-тегов в документ, см. в разделах Практическое руководство. Добавление смарт-тегов в документы Word и Практическое руководство. Добавление смарт-тегов в книги Excel.

Смарт-теги

В коде смарт-теги являются объектом Microsoft.Office.Tools.Word.SmartTag или Microsoft.Office.Tools.Excel.SmartTag. Эти объекты обладают следующими свойствами:

  • Terms и Expressions. Эти свойства содержат распознаваемые термины для смарт-тегов. Чтобы задать простую строку, добавьте ее в свойство Terms. Чтобы задать сложную строку, добавьте регулярное выражение, описывающее строку, в свойство Expressions.

  • Actions. Это свойство содержит действия, выполняемые при выборе смарт-тега пользователем.

  • Caption. Это свойство задает метку смарт-тега.

Действия

Когда пользователь выбирает смарт-тег, он может выполнить одно или несколько действий, специфичных для данного смарт-тега. Каждое действие представляется объектом 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 являются классами, допускающими непосредственное создание экземпляров. В следующем примере кода показано, как создать простой смарт-тег в проекте Word, предназначенном для платформы .NET Framework 3.5. Для использования этого примера запустите код из класса 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 являются интерфейсами и не допускают непосредственное создание экземпляров. Вместо этого для получения экземпляров этих объектов необходимо использовать в проекте методы CreateSmartTag и CreateAction, предоставляемые классом Globals. Дополнительные сведения о классе Globals см. в разделе Глобальный доступ к объектам в проектах Office. В следующем примере кода показано, как создать простой смарт-тег в проекте Word, предназначенном для платформы .NET Framework 4. Для использования этого примера запустите код из класса 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);

Дальнейшие инструкции и примеры кода, которые демонстрируют более сложные смарт-теги, см. в разделах Практическое руководство. Добавление смарт-тегов в документы Word и Практическое руководство. Добавление смарт-тегов в книги Excel.

Создание распознавателя смарт-тегов

Если требуется настроить используемое по умолчанию поведение распознавания смарт-тегов, можно создать свой собственный распознаватель смарт-тегов. Способ, которым это делается, зависит от платформы, для которой предназначен проект: .NET Framework 3.5 или .NET Framework 4.

Поведение по умолчанию при распознавании текста

Когда пользователь вводит текст в документе или рабочей книге, Word и Excel создают из текста список маркеров. Распознаватель смарт-тегов по умолчанию получает список токенов и полный введенный пользователем текст. Распознаватель по умолчанию определяет смарт-теги, если соблюдено одно из следующих условий:

  • Одна из строк в свойстве Terms точно совпадает с одним из маркеров в документе или рабочей книге.

  • Одно из регулярных выражений в свойстве Expressions совпадает с полным введенным пользователем текстом.

Во время набора текста пользователем приложения Word и Excel анализируют строки, содержащие внедренные пробелы, или строки, содержащие буквы, числа и символы, и разделяют их на отдельные маркеры. Например, если пользователь ввел "отчет по продажам", Word и Excel создадут маркеры "продажам" и "отчет". Аналогично, если пользователь ввел "продажи2005", Word и Excel создадут маркеры "продажи" и "2005".

Если требуется, чтобы смарт-тег распознавал строку, содержащую встроенные пробелы или строку с сочетанием букв, чисел и символов, не добавляйте строку в свойство Terms. Вместо этого добавьте регулярное выражение, которое описывает строку, в свойство Expressions или создайте собственный распознаватель, который будет выполнять поиск строки.

Создание распознавателей смарт-тегов в проектах, предназначенных для платформы .NET Framework версии 4

Чтобы создать свой собственный распознаватель смарт-тегов, определите класс, реализующий интерфейс Microsoft.Office.Tools.Word.ISmartTagExtension или Microsoft.Office.Tools.Excel.ISmartTagExtension. В реализации метода ISmartTagExtension.Recognize необходимо выполнить поиск терминов смарт-тега в тексте и зарегистрировать смарт-тег в Word или Excel, если термин смарт-тега будет найден. Чтобы зарегистрировать смарт-тег, вызовите метод PersistTag параметра context метода Recognize.

В следующем примере кода показано, как создать простой класс смарт-тега с пользовательским распознавателем в проекте Word, предназначенном для платформы .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; }
    }
}

Дальнейшие инструкции и примеры кода, которые демонстрируют более сложные классы смарт-тегов с пользовательскими распознавателями, см. в разделах Практическое руководство. Создание смарт-тегов с настраиваемыми распознавателями в Word и .NET Framework 4 и Практическое руководство. Создание смарт-тегов с настраиваемыми распознавателями в Excel и .NET Framework 4.

Создание распознавателей смарт-тегов в проектах, предназначенных для платформы .NET Framework версии 3.5

Чтобы создать свой собственный распознаватель смарт-тегов, создайте класс, производный от класса Microsoft.Office.Tools.Word.SmartTag или Microsoft.Office.Tools.Excel.SmartTag, затем переопределите метод SmartTag.Recognize этого класса. В своем методе выполните поиск терминов смарт-тега в тексте и зарегистрируйте смарт-тег в Word или Excel, если термин смарт-тега будет найден. Чтобы зарегистрировать смарт-тег, вызовите метод PersistTag, унаследованный вашим классом от класса Microsoft.Office.Tools.Word.SmartTag или Microsoft.Office.Tools.Excel.SmartTag.

В следующем примере кода показано, как создать простой класс смарт-тега с пользовательским распознавателем в проекте Word, предназначенном для платформы .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);
        }
    }
}

Дальнейшие инструкции и примеры кода, которые демонстрируют более сложные классы смарт-тегов с пользовательскими распознавателями, см. в разделах Практическое руководство. Создание смарт-тегов с настраиваемыми распознавателями в Word и .NET Framework 3.5 и Практическое руководство. Создание смарт-тегов с настраиваемыми распознавателями в Excel и .NET Framework 3.5.

Сохранение данных в контейнер свойств и извлечение данных из него

Смарт-теги могут хранить данные в коллекции пар "ключ-значение", которые известны под названием "контейнер свойств". Каждое значение и ключ в контейнере свойств является строкой.

Существует два способа доступа к контейнеру свойств.

  • Можно обрабатывать события Click или BeforeCaptionShow объекта Microsoft.Office.Tools.Word.Action или Microsoft.Office.Tools.Excel.Action и использовать свойство Properties параметра аргумента события для записи или чтения из контейнера свойств смарт-тега. Свойство Properties возвращает объект ISmartTagProperties. Интерфейс ISmartTagProperties доступен после добавления ссылки на библиотеку типов Microsoft Smart Tags 2.0 в проект.

  • Пользовательский распознаватель смарт-тегов можно создать в соответствии с приведенными выше инструкциями. В своей реализации или переопределении метода Recognize используйте метод GetNewPropertyBag параметра site для получения объекта ISmartTagProperties, который можно использовать для записи в контейнер свойств смарт-тега или чтения из него.

Примеры записи в контейнер свойств и считывания из него см. в указанных ниже разделах.

Регулярные выражения и контейнер свойств

После назначения регулярного выражения смарт-тегу, распознаватель по умолчанию добавляет пару "код-значение" для каждой захваченной группы регулярного выражения в контейнер свойств смарт-тега.

Пример, демонстрирующий это, см. в разделе Пошаговое руководство. Создание смарт-тега с помощью настройки уровня документа. Дополнительные сведения о захваченных группах в регулярных выражениях, см. в разделах Конструкции группирования и Объектная модель регулярных выражений.

См. также

Задачи

Практическое руководство. Разрешение смарт-тегов в Word и Excel

Практическое руководство. Добавление смарт-тегов в документы Word

Практическое руководство. Добавление смарт-тегов в книги Excel

Практическое руководство. Создание смарт-тегов с настраиваемыми распознавателями в Word и .NET Framework 3.5

Практическое руководство. Создание смарт-тегов с настраиваемыми распознавателями в Excel и .NET Framework 3.5

Пошаговое руководство. Создание смарт-тега с помощью настройки уровня документа

Пошаговое руководство. Создание смарт-тега с помощью надстройки уровня приложения

Другие ресурсы

Общие сведения о смарт-тегах