Extending a Form Region with an Add-in

  • Статья

Хотя вы можете создавать и запускать формы с областями форм без надстройки COM, использование надстройки COM позволит регионам форм включать настраиваемую бизнес-логику или расширенные функции. В отличие от настройки страниц форм в стандартной форме, VBScript не используется для написания кода за формой; Вместо этого вы программ будете программ для областей форм с помощью надстройки COM. Надстройка реализует новый интерфейс FormRegionStartup. Надстройки смогут использовать элементы управления Microsoft Forms 2.0 и Элементы управления Microsoft Outlook в области формы. В этом разделе описывается реализация FormRegionStartup и доступ к элементам управления Outlook в области формы.

Указание использования надстройки

При регистрации области формы для класса сообщений создайте раздел в реестре Windows для этого класса сообщений (если ключ еще не существует) и укажите в качестве данных знак равенства (=), за которым следует ProgID надстройки. Дополнительные сведения о регистрации области формы в реестре Windows см. в разделе Указание областей форм в реестре Windows.

Реализация FormRegionStartup

В том же классе, который реализует интерфейс IDTExtensibility2 надстройки COM, реализуйте интерфейс Outlook.FormRegionStartup , определенный в библиотеке типов Outlook. Outlook вызовет четыре метода в этом интерфейсе:

GetFormRegionStorage

Когда Outlook будет отображать область формы, которая управляется надстройкой, Outlook вызовет метод GetFormRegionStorage . Когда надстройка получает вызов из Outlook в GetFormRegionStorage с указанием сведений для области формы, надстройка вернет сведения для макета. Эти сведения могут быть локальным путем к файлу макета (. OFS-файл), объект Microsoft Windows IStorage или массив байтов с содержимым файла OFS, который позволяет надстройке хранить OFS в качестве ресурса. Outlook будет использовать возвращаемые сведения для создания экземпляров элементов управления и вычисления макета для области формы. Outlook также создаст экземпляр объекта FormRegion для области формы. Прототип метода для GetFormRegionStorage в Microsoft Visual Basic и Microsoft C# показан ниже.

В Visual Basic:

Public Function GetFormRegionStorage(ByVal FormRegionName As String,
    ByVal Item As Object, 
    ByVal LCID As Integer, 
    _ ByVal FormRegionMode As Outlook.OlFormRegionMode, 
    ByVal FormRegionSize As Outlook.OlFormRegionSize) _ 
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionStorage

В C#:

public object GetFormRegionStorage(string FormRegionName, 
    object Item, 
    int LCID,
    Outlook.OlFormRegionMode FormRegionMode, 
    Outlook.OlFormRegionSize FormRegionSize)

BeforeFormRegionShow

Если getFormRegionStorage успешно выполняется, непосредственно перед отображением области формы в окне инспектора или в области чтения Outlook вызовет Метод BeforeFormRegionShow, передав объект FormRegion надстройке. Надстройка будет использовать этот шанс перед отображением области формы для обновления чего-либо в пользовательском интерфейсе, например изменения подписей меток, как описано в разделе Доступ к элементам управления Outlook ниже, и подавления ненужного содержимого. Ниже показаны прототипы методов Visual Basic и C# для BeforeFormRegionShow .

В Visual Basic:

Public Sub BeforeFormRegionShow(ByVal Item As Object, 
    ByVal FormRegion As Microsoft.Office.Interop.Outlook.FormRegion) _ 
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.BeforeFormRegionShow

В C#:

public void BeforeFormRegionShow(object Item, Outlook.FormRegion FormRegion)

Доступ к элементам управления Outlook

При использовании надстройки COM для расширения области формы вы часто прослушиваете события элемента управления, вызываете методы управления, а также считываете и задаете свойства элемента управления. Чтобы получить доступ к Microsoft Forms элементам управления версии 2.0, элементам управления Outlook или объекту canvas формы в надстройке, необходимо добавить ссылку на библиотеку объектов Microsoft Forms 2.0. Добавление этой ссылки даст доступ к пространству имен Microsoft.Vbe.Interop.Forms в проекте надстройки.

После добавления ссылки можно при необходимости создать псевдоним в пространстве имен библиотеки типов, чтобы упростить использование включенных типов. Чтобы создать псевдоним, вставьте следующий код в начало файла кода. Ниже приведены примеры того, как это сделать при написании надстройки в Visual Basic или C#. Эти псевдонимы также будут использоваться в приведенных ниже примерах кода.

В Visual Basic:

Imports Outlook = Microsoft.Office.Interop.Outlook 
Imports Office = Microsoft.Office.Core  
Imports MSForms = Microsoft.Vbe.Interop.Forms

В C#:

using Outlook = Microsoft.Office.Interop.Outlook; 
using Office = Microsoft.Office.Core; 
using MSForms = Microsoft.Vbe.Interop.Forms;

Вы можете получить доступ к элементам управления с помощью объекта FormRegion, полученного из BeforeFormRegionShow. Свойство FormRegion.Form возвращает объект, представляющий форму; Этот объект можно привести к классу MSForms.UserForm (который предоставляется в библиотеке объектов Microsoft Forms 2.0), чтобы получить доступ к холсту формы для области формы.

Каждый экземпляр объекта UserForm имеет коллекцию Controls , которую можно использовать для доступа к отдельным элементам управления в UserForm по имени элемента управления. Многие элементы управления Microsoft Forms 2.0 имеют тематические аналоги, которые являются элементами управления Outlook. В области формы Outlook заменяет те элементы управления Forms 2.0, которые имеют аналогичные элементы управления Outlook, соответствующими тематическими аналогами. Получив ссылку на тематический элемент управления из коллекции Controls , вы можете привести его к нужному типу в библиотеке типов Outlook. Затем вы сможете получить доступ ко всем свойствам, методам и событиям, предоставляемым для этих элементов управления в библиотеке типов Outlook. В отличие от настройки форм с помощью VBScript, вы сможете прослушивать все события элемента управления, а не только событие Click . Дополнительные сведения об элементах управления см. в разделе Элементы управления в пользовательской форме.

В следующих примерах кода показано, как метод BeforeFormRegionShow использует входной параметрFormRegion из Outlook для получения объекта формы, а затем приводит его к классу MSForms.UserForm и обращается к коллекции элементов управления в объекте UserForm . Холст формы, представленный этим объектом UserForm , содержит два элемента управления Outlook: текстовое поле с именем OlkTextBox1 и флажок с именем OlkCheckBox1. Он приводит их к соответствующим типам элементов управления Outlook и задает значения по умолчанию для этих элементов управления следующим образом.

В Visual Basic:

Dim UserForm As MSForms.UserForm 
Dim FormControls As MSForms.Controls 
Dim TextBox1 As Outlook.OlkTextBox 
Dim CheckBox1 As Outlook.OlkCheckBox 
 
UserForm = FormRegion.Form 
FormControls = UserForm.Controls 
 
TextBox1 = FormControls.Item("OlkTextBox1") 
TextBox1.Text = "Sample Form Region" 
CheckBox1 = FormControls.Item("OlkCheckBox1") 
CheckBox1.Value = True

В C#:

MSForms.UserForm userForm = (MSForms.UserForm)FormRegion.Form; 
MSForms.Controls formControls = userForm.Controls; 
 
Outlook.OlkTextBox textBox1 =  
   (Outlook.OlkTextBox)formControls.Item("OlkTextBox1"); 
textBox1.Text = "Sample Form Region"; 
 
Outlook.OlkCheckBox checkBox1 =  
   (Outlook.OlkCheckBox)formControls.Item("OlkCheckBox1"); 
checkBox1.Value = true;

GetFormRegionManifest

При запуске Outlook считывает список областей форм из реестра Windows и кэширует данные. На основе этих данных, если Outlook заметит, что надстройка предоставляет XML-манифест для области формы, Outlook будет использовать Идентификатор ProgID, указанный в кэшированных данных, и вызовет метод GetFormRegionManifest , реализованный этой надстройкой, чтобы получить XML-код, необходимый для отображения области формы. Если XML-манифест недопустим и не соответствует XML-схеме области формы, Outlook не сможет загрузить область формы.

Дополнительные сведения об указании ProgID при регистрации области формы см. в разделе Указание областей формы в реестре Windows.

Ниже показаны прототипы методов Visual Basic и C# для GetFormRegionManifest .

В Visual Basic:

Public Function GetFormRegionManifest(ByVal FormRegionName As String, 
    ByVal LCID As Integer) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest

В C#:

public object GetFormRegionManifest(string FormRegionName, int LCID)

GetFormRegionIcon

При запуске Outlook считывает список областей форм из реестра Windows и кэширует данные, связанные с областями формы. Если область формы зарегистрирована с помощью ProgID, Outlook прибегнет к соответствующей надстройке, вызвав ее реализацию GetFormRegionIcon для любого значка в XML-манифесте, имеющего addin значение дочернего элемента элемента icon . Дополнительные сведения об использовании надстройки для указания значков см. в разделе Практическое руководство. Использование надстройки для указания значков для области формы.

Ниже показаны прототипы методов Visual Basic и C# для GetFormRegionIcon .

В Visual Basic:

Public Function GetFormRegionIcon(ByVal FormRegionName As String, 
    ByVal LCID As Integer, _ 
    ByVal Icon As Outlook.OlFormRegionIcon) _ 
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest

В C#:

public object GetFormRegionIcon(string FormRegionName, int LCID, Outlook.OlFormRegionIcon Icon)

Поддержка и обратная связь

Есть вопросы или отзывы, касающиеся Office VBA или этой статьи? Руководство по другим способам получения поддержки и отправки отзывов см. в статье Поддержка Office VBA и обратная связь.