共用方式為

逐步解說：在 Outlook 中的電子郵件訊息顯示自訂工作窗格

  • 發行項

更新：2007 年 11 月

適用於

本主題中的資訊只適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 應用程式。

專案類型

  • 應用程式層級專案

Microsoft Office 應用程式

  • Outlook 2007

如需詳細資訊，請參閱依應用程式和專案類型提供的功能。

此逐步解說會示範如何針對每個已建立或已開啟的電子郵件訊息顯示個別的自訂工作窗格執行個體。使用者可以使用每則電子郵件之功能區上的按鈕，顯示或隱藏自訂工作窗格。

若要顯示含有多個檔案總管或偵測器視窗的自訂工作窗格，您必須針對每一個開啟的視窗建立自訂工作窗格的執行個體。如需 Outlook 視窗中自訂工作窗格行為的詳細資訊，請參閱自訂工作窗格概觀。

注意事項：

此逐步解說會呈現少部分的增益集程式碼，以便輕易討論程式碼背後的邏輯。若要檢視您在本逐步解說中編輯之每個檔案的完整內容，請參閱 HOW TO：在 Outlook 中的電子郵件訊息顯示自訂工作窗格。

這個逐步解說將說明下列工作：

  • 設計自訂工作窗格的使用者介面 (UI)。

  • 建立自訂功能區 UI。

  • 顯示含有電子郵件訊息的自訂功能區 UI。

  • 建立類別以管理偵測器視窗和自訂工作窗格。

  • 初始化和清除增益集所用的資源。

  • 同步處理功能區切換按鈕和自訂工作窗格。

注意事項：

在下列指示的某些 Visual Studio 使用者介面項目中，您的電腦可能會顯示不同的名稱或位置。您所擁有的 Visual Studio 版和使用的設定，會決定這些項目。如需詳細資訊，請參閱 Visual Studio 設定。

必要條件

您需要下列元件才能完成此逐步解說：

  • Visual Studio Tools for Office (Visual Studio 2008 Professional 和 Visual Studio Team System 的選擇性元件)。

  • Microsoft Office Outlook 2007。

Visual Studio Tools for Office 預設會與列出的 Visual Studio 版本一起安裝。若要查看是否已安裝，請參閱安裝 Visual Studio Tools for Office。

建立專案

自訂工作窗格會在應用程式層級增益集中實作，請從建立 Outlook 2007 的增益集專案開始。

若要建立新的專案

  • 使用名稱 OutlookMailItemTaskPane 建立 [Outlook 增益集] 專案。使用 2007 Microsoft Office system 的 [Outlook 增益集] 專案範本。如需詳細資訊，請參閱 HOW TO：建立 Visual Studio Tools for Office 專案。

    Visual Studio 會開啟 ThisAddIn.cs 或 ThisAddIn.vb 程式碼檔，並將 OutlookMailItemTaskPane 專案加入至 [方案總管]。

設計自訂工作窗格的使用者介面

自訂工作窗格沒有視覺化設計工具，但是您可以根據需要設計使用者控制項的 UI。此增益集中的自訂工作窗格具有內含 TextBox 控制項的簡單 UI。在此逐步解說後面，您會在自訂工作窗格中加入使用者控制項。

若要設計自訂工作窗格的使用者介面

  1. 按一下 [方案總管] 中的 [OutlookMailItemTaskPane] 專案。

  2. 在 [專案] 功能表上，按一下 [加入使用者控制項]。

  3. 在 [加入新項目] 對話方塊中，將使用者控制項的名稱變更為 TaskPaneControl，然後按一下 [加入]。

    使用者控制項隨即在設計工具中開啟。

  4. 從 [工具箱] 的 [通用控制項] 索引標籤，將 [TextBox] 控制項拖曳至使用者控制項。

設計功能區的使用者介面

此增益集的其中一個目標就是讓使用者可以從每則電子郵件訊息的功能區，隱藏或顯示自訂工作窗格。若要提供使用者介面，請建立可顯示切換按鈕的自訂功能區 UI，使用者按一下該切換按鈕即可顯示或隱藏自訂工作窗格。

若要建立自訂功能區 UI

  1. 在 [專案] 功能表上按一下 [加入新項目]。

  2. 選取 [加入新項目] 對話方塊中的 [功能區 (視覺化設計工具)]。

  3. 將新功能區的名稱變更為 ManageTaskPaneRibbon，然後按一下 [加入]。

    ManageTaskPaneRibbon.cs 或 ManageTaskPaneRibbon.vb 檔案會在功能區設計工具中開啟，並顯示預設索引標籤和群組。

  4. 在功能區設計工具中，按一下 [group1]。

  5. 將 [屬性] 視窗中的 [Label] 屬性設定為 Task Pane Manager。

  6. 從 [工具箱 ] 的 [Office 功能區控制項] 索引標籤，將 ToggleButton 控制項拖曳到 [Task Pane Manager] 群組上。

  7. 按一下 [toggleButton1]。

  8. 將 [屬性] 視窗中的 [Label] 屬性設定為 Show Task Pane。

顯示含有電子郵件訊息的自訂功能區使用者介面

您在本逐步解說中建立的自訂工作窗格，會設計為僅與含有電子郵件訊息的偵測器視窗一起出現。因此，設定相關屬性，僅與這些視窗一起顯示您的自訂功能區 UI。

若要顯示含有電子郵件訊息的自訂功能區 UI

  1. 在功能區設計工具中，按一下 [ManageTaskPaneRibbon] 功能區。

  2. 在 [屬性] 視窗中，按一下 [RibbonType] 旁邊的下拉式清單，並選取 [Microsoft.Outlook.Mail.Compose] 和 [Microsoft.Outlook.Mail.Read]。

建立類別以管理偵測器視窗和自訂工作窗格

在數種情況下，增益集必須識別與特定電子郵件訊息相關聯的自訂工作窗格。這些情況包含下列：

  • 當使用者關閉電子郵件訊息時。在此情況下，增益集必須移除對應的自訂工作窗格，以確保增益集所用的資源已正確地清除。

  • 當使用者關閉自訂工作窗格時。在此情況下，增益集必須更新電子郵件訊息功能區上切換按鈕的狀態。

  • 當使用者按一下功能區上的切換按鈕時。在此情況下，增益集必須隱藏或顯示對應的工作窗格。

若要啟用增益集以追蹤與每則開啟之電子郵件訊息相關聯的自訂工作窗格，請建立包裝了好幾對 Inspector 和 CustomTaskPane 物件的自訂類別。這個類別會針對每則電子郵件訊息建立新的自訂作業窗格物件，並且在對應的電子郵件訊息已關閉時，刪除自訂工作窗格。

若要建立類別以管理偵測器視窗和自訂工作窗格

  1. 在 [方案總管] 中，以滑鼠右鍵按一下 ThisAddIn.cs 或 ThisAddIn.vb 檔，然後按一下 [檢視程式碼]。

  2. 將下列陳述式加入至檔案的最上方。

    Imports System.Collections.Generic
Imports Microsoft.Office.Tools
Imports Office = Microsoft.Office.Core
Imports Outlook = Microsoft.Office.Interop.Outlook

    using Microsoft.Office.Tools;

  3. 將下列程式碼加入至 ThisAddIn 類別之外的 ThisAddIn.cs 或 ThisAddIn.vb 檔 (若為 Visual C#，將此程式碼加入到 OutlookMailItemTaskPane 命名空間)。InspectorWrapper 類別會管理一對 Inspector 和 CustomTaskPane 物件。您會在下列步驟中完成這個類別的定義。

    Public Class InspectorWrapper
    Private inspector As Outlook.Inspector
    Private WithEvents inspectorEvents As Outlook.InspectorEvents_Event
    Private WithEvents taskPane As CustomTaskPane

    public class InspectorWrapper
{
    private Outlook.Inspector inspector;
    private CustomTaskPane taskPane;

  4. 將下列建構函式加入至您在上一個步驟中加入的程式碼之後。這個建構函式會建立和初始化新的自訂工作窗格，而該工作窗格會與傳入的 Inspector 物件相關聯。在 C# 中，此建構函式也會將事件處理常式附加至 Inspector 物件的 Close 事件以及 CustomTaskPane 物件的 VisibleChanged 事件。

    Public Sub New(ByVal Inspector As Outlook.Inspector)
    Me.inspector = Inspector
    inspectorEvents = TryCast(Me.inspector, Outlook.InspectorEvents_Event)
    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(New TaskPaneControl(), _
        "My task pane", Inspector)
End Sub

    public InspectorWrapper(Outlook.Inspector Inspector)
{
    inspector = Inspector;
    ((Outlook.InspectorEvents_Event)inspector).Close +=
        new Outlook.InspectorEvents_CloseEventHandler(InspectorWrapper_Close);

    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(
        new TaskPaneControl(), "My task pane", inspector);
    taskPane.VisibleChanged += new EventHandler(TaskPane_VisibleChanged);
}

  5. 將下列方法加入至您在上一個步驟中加入的程式碼之後。對於 InspectorWrapper 類別內含之 CustomTaskPane 物件的 VisibleChanged 事件而言，這個方法為其事件處理常式。每當使用者開啟或關閉自訂工作窗格時，這個程式碼就會更新切換按鈕的狀態。

    Private Sub TaskPane_VisibleChanged(ByVal sender As Object, ByVal e As EventArgs) _
    Handles taskPane.VisibleChanged
    Globals.Ribbons(inspector).ManageTaskPaneRibbon.ToggleButton1.Checked = taskPane.Visible
End Sub

    void TaskPane_VisibleChanged(object sender, EventArgs e)
{
    Globals.Ribbons[inspector].ManageTaskPaneRibbon.toggleButton1.Checked = 
        taskPane.Visible;
}

  6. 將下列方法加入至您在上一個步驟中加入的程式碼之後。對於含有目前電子郵件訊息之 Inspector 物件的 Close 事件而言，這個方法為其事件處理常式。關閉電子郵件訊息後，事件處理常式就會釋放資源。該事件處理常式也會從 CustomTaskPanes 集合中移除目前的自訂工作窗格。這有助於在開啟下一則電子郵件訊息時，防止自訂工作窗格有多個執行個體。

    Sub InspectorWrapper_Close() Handles inspectorEvents.Close
    If Not (taskPane Is Nothing) Then
        Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane)
    End If

    taskPane = Nothing
    Globals.ThisAddIn.InspectorWrappers.Remove(inspector)
    RemoveHandler inspectorEvents.Close, AddressOf InspectorWrapper_Close
    inspector = Nothing
End Sub

    void InspectorWrapper_Close()
{
    if (taskPane != null)
    {
        Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane);
    }

    taskPane = null;
    Globals.ThisAddIn.InspectorWrappers.Remove(inspector);
    ((Outlook.InspectorEvents_Event)inspector).Close -=
        new Outlook.InspectorEvents_CloseEventHandler(InspectorWrapper_Close);
    inspector = null;
}

  7. 將下列程式碼加入至您在上一個步驟中加入的程式碼之後。稍後在本逐步解說中，您會在自訂功能區 UI 中從某個方法呼叫此屬性，以顯示或隱藏自訂工作窗格。

        Public ReadOnly Property CustomTaskPane() As CustomTaskPane
        Get
            Return taskPane
        End Get
    End Property
End Class

        public CustomTaskPane CustomTaskPane
    {
        get
        {
            return taskPane;
        }
    }
}

初始化和清除增益集所用的資源

將程式碼加入至 ThisAddIn 類別以便在載入時初始化增益集，以及在卸載時清除增益集所用的資源。您可以設定 NewInspector 事件的事件處理常式，並將所有現有電子郵件訊息傳遞至此事件處理常式，即可初始化增益集。卸載增益集後，卸下事件處理常式並清除增益集所用的物件。

若要初始化和清除增益集所用的資源

  1. 在 ThisAddIn.cs 或 ThisAddIn.vb 檔案中，找出 ThisAddIn 類別的定義。

  2. 將下列宣告加入至 ThisAddIn 類別：

    • inspectorWrappersValue 欄位包含增益集所管理的全部 Inspector 和 InspectorWrapper 物件。

    • inspectors 欄位會維護目前 Outlook 執行個體中偵測器視窗集合的參考。此參考可以讓記憶體回收行程不會釋放包含 NewInspector 事件之事件處理常式的記憶體，而您將在下一個步驟中宣告該事件。

    Private inspectorWrappersValue As New Dictionary(Of Outlook.Inspector, InspectorWrapper)
Private WithEvents inspectors As Outlook.Inspectors

    private Dictionary<Outlook.Inspector, InspectorWrapper> inspectorWrappersValue =
    new Dictionary<Outlook.Inspector, InspectorWrapper>();
private Outlook.Inspectors inspectors;

  3. 以下列程式碼取代 ThisAddIn_Startup 方法。此程式碼會將事件處理常式附加至 NewInspector 事件，並將每個現有 Inspector 物件傳遞至事件處理常式。如果使用者在 Outlook 已經執行以後載入增益集，則增益集會使用這項資訊替所有已經開啟的電子郵件訊息建立自訂工作窗格。

    Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    inspectors = Me.Application.Inspectors
    Dim inspector As Outlook.Inspector
    For Each inspector In inspectors
        Inspectors_NewInspector(inspector)
    Next inspector
End Sub

    private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    inspectors = this.Application.Inspectors;
    inspectors.NewInspector +=
        new Outlook.InspectorsEvents_NewInspectorEventHandler(
        Inspectors_NewInspector);

    foreach (Outlook.Inspector inspector in inspectors)
    {
        Inspectors_NewInspector(inspector);
    }
}

  4. 以下列程式碼取代 ThisAddIn_ShutDown 方法。此程式碼會卸下 NewInspector 事件處理常式並清除增益集所用的物件。

    Private Sub ThisAddIn_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Shutdown

    RemoveHandler inspectors.NewInspector, AddressOf Inspectors_NewInspector
    inspectors = Nothing
    inspectorWrappersValue = Nothing
End Sub

    private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
{
    inspectors.NewInspector -=
        new Outlook.InspectorsEvents_NewInspectorEventHandler(
        Inspectors_NewInspector);
    inspectors = null;
    inspectorWrappersValue = null;
}

  5. 將下列 NewInspector 事件處理常式加入至 ThisAddIn 類別。如果新的 Inspector 包含電子郵件訊息，此方法則建立新 InspectorWrapper 物件的執行個體，以管理電子郵件訊息與對應工作窗格之間的關係。

    Sub Inspectors_NewInspector(ByVal Inspector As Outlook.Inspector) _
    Handles inspectors.NewInspector

    If TypeOf Inspector.CurrentItem Is Outlook.MailItem Then
        inspectorWrappersValue.Add(Inspector, New InspectorWrapper(Inspector))
    End If
End Sub

    void Inspectors_NewInspector(Outlook.Inspector Inspector)
{
    if (Inspector.CurrentItem is Outlook.MailItem)
    {
        inspectorWrappersValue.Add(Inspector, new InspectorWrapper(Inspector));
    }
}

  6. 將下列屬性加入至 ThisAddIn 類別。這個屬性會將私用 inspectorWrappersValue 欄位公開至 ThisAddIn 類別外的程式碼。

    Public ReadOnly Property InspectorWrappers() As Dictionary(Of Outlook.Inspector, InspectorWrapper)
    Get
        Return inspectorWrappersValue
    End Get
End Property

    public Dictionary<Outlook.Inspector, InspectorWrapper> InspectorWrappers
{
    get
    {
        return inspectorWrappersValue;
    }
}

檢查點

建置您的專案，並確定專案在編譯時未發生任何錯誤。

若要建置您的專案

  • 在 [方案總管] 中，以滑鼠右鍵按一下 [OutlookMailItemTaskPane] 專案，然後按一下 [建置]。接著驗證專案編譯無誤。

同步處理功能區切換按鈕和自訂工作窗格

當看得見工作窗格時，切換按鈕會呈現已按下狀態，而當工作窗格隱藏起來時，切換按鈕則會呈現未按下狀態。若要同步處理按鈕的狀態和自訂工作窗格，請修改切換按鈕的 Click 事件處理常式。

同步處理自訂工作窗格和切換按鈕

  1. 在功能區設計工具中，按兩下 [顯示工作窗格] 切換按鈕。

    Visual Studio Tools for Office 會自動產生名稱為 toggleButton1_Click 的事件處理常式，該事件處理常式會處理切換按鈕的 Click 事件。Visual Studio Tools for Office 也會在程式碼編輯器中開啟 ManageTaskPaneRibbon.cs 或 ManageTaskPaneRibbon.vb 檔案。

  2. 將下列陳述式加入至 ManageTaskPaneRibbon.cs 或 ManageTaskPaneRibbon.vb 檔案的頂端。

    Imports Microsoft.Office.Tools.Ribbon
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Microsoft.Office.Tools

    using Outlook = Microsoft.Office.Interop.Outlook;
using Microsoft.Office.Tools;

  3. 以下列程式碼取代 toggleButton1_Click 事件處理常式。當使用者按一下切換按鈕時，這個方法會隱藏或顯示與目前偵測器視窗相關聯的自訂工作窗格。

    Private Sub ToggleButton1_Click(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
    Handles ToggleButton1.Click

    Dim inspector As Outlook.Inspector = e.Control.Context
    Dim inspectorWrapper As InspectorWrapper = Globals.ThisAddIn.InspectorWrappers(inspector)
    Dim taskPane As CustomTaskPane = inspectorWrapper.CustomTaskPane
    If Not (taskPane Is Nothing) Then
        taskPane.Visible = TryCast(sender, RibbonToggleButton).Checked
    End If
End Sub

    private void toggleButton1_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Inspector inspector = (Outlook.Inspector)e.Control.Context;
    InspectorWrapper inspectorWrapper = Globals.ThisAddIn.InspectorWrappers[inspector];
    CustomTaskPane taskPane = inspectorWrapper.CustomTaskPane;
    if (taskPane != null)
    {
        taskPane.Visible = ((RibbonToggleButton)sender).Checked;
    }
}

測試專案

當您開始進行專案偵錯時，會開啟 Outlook 且載入增益集。增益集會對每個已開啟的電子郵件訊息顯示自訂個別的工作窗格執行個體。建立數則新電子郵件訊息以測試程式碼。

若要測試增益集

  1. 按下 F5 鍵。

  2. 在 Outlook 中，按一下 [新增] 以建立新電子郵件訊息。

  3. 在電子郵件訊息的功能區上，按一下 [增益集] 索引標籤，然後按一下 [顯示工作窗格] 按鈕。

    確認已顯示內含電子郵件訊息之標題為 [我的工作窗格] 的工作窗格。

  4. 在工作窗格的文字方塊中輸入 First task pane。

  5. 關閉工作窗格。

    確認 [顯示工作窗格] 按鈕的狀態會變更，而不再是已按下的狀態。

  6. 再次按一下 [顯示工作窗格] 按鈕。

    確認工作窗格會開啟，而且文字方塊仍含有 First task pane 字串。

  7. 在 Outlook 中，按一下 [新增] 以建立第二則電子郵件訊息。

  8. 在電子郵件訊息的功能區上，按一下 [增益集] 索引標籤，然後按一下 [顯示工作窗格] 按鈕。

    確認已顯示內含電子郵件訊息之標題為 [我的工作窗格] 的工作窗格，而且此工作窗格中的文字方塊是空的。

  9. 在工作窗格的文字方塊中輸入 Second task pane。

  10. 將焦點變更至第一則電子郵件訊息。

    確認與這則電子郵件訊息相關聯的工作窗格仍在文字方塊中顯示 First task pane。

此增益集也會處理您可以嘗試的更進階案例。例如，您可以使用 [下一項目] 和 [前一項目] 按鈕，在檢視電子郵件時測試行為。也可以在您卸載增益集、開啟數則電子郵件訊息，然後重新載入增益集時測試行為。

後續步驟

您可以在下列主題中，進一步了解如何建立自訂工作窗格：

請參閱

工作

HOW TO：在應用程式中加入自訂工作窗格

逐步解說：運用自訂工作窗格自動化應用程式

逐步解說：使用功能區按鈕同步處理自訂工作窗格

HOW TO：在 Outlook 中的電子郵件訊息顯示自訂工作窗格

概念

自訂工作窗格概觀

管理多個應用程式視窗中的自訂工作窗格

功能區概觀

Outlook 物件模型概觀

在執行階段存取功能區