逐步解說：在 Outlook 中使用電子郵件訊息顯示自定義工作窗格

發行項
01/13/2024

本逐步解說示範如何使用建立或開啟的每個電子郵件訊息，顯示自定義工作窗格的唯一實例。使用者可以使用每則電子郵件訊息功能區上的按鈕，顯示或隱藏自訂工作窗格。

適用於： 本主題中的資訊適用於 Outlook 的 VSTO 載入宏專案。如需詳細資訊，請參閱 Office 應用程式 lication 和項目類型所提供的功能。

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

注意

本逐步解說會呈現一小部分的 VSTO 增益集程式碼，以便更容易討論程式碼背後的邏輯。

本逐步解說將說明下列工作：

設計自訂工作窗格的使用者介面 (UI)。
建立自訂功能區 UI。
顯示具有電子郵件訊息的自定義功能區UI。
建立類別以管理偵測器視窗和自訂工作窗格。
初始化和清除 VSTO 增益集所使用的資源。
同步處理功能區切換按鈕和自訂工作窗格。

注意

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

必要條件

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

此版 Visual Studio 包含 Microsoft Office Developer Tools。如需詳細資訊，請參閱設定計算機來開發 Office 解決方案。
Microsoft Outlook 2013 或 Microsoft Outlook 2010。

建立專案

自定義工作窗格會在 VSTO 載入宏中實作。首先，建立 Outlook 的 VSTO 載入宏專案。

建立新的專案

建立名為 OutlookMailItemTaskPane 的 [Outlook 增益集] 專案。使用 [Outlook 增益集] 專案範本。如需詳細資訊，請參閱如何：在Visual Studio中建立 Office專案。

Visual Studio 會開啟 ThisAddIn.cs 或 ThisAddIn.vb 程式代碼檔案，並將 OutlookMailItemTaskPane 專案新增至 方案總管。

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

自訂工作窗格沒有視覺化設計工具，但您可以透過 UI 來設計所需的使用者控制項。這個 VSTO 增益集中的自訂工作窗格具有內含 TextBox 控制項的簡單 UI。稍後在本逐步解說中，您會將使用者控制項加入自訂工作窗格。

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

在 [方案總管] 中，按一下 [OutlookMailItemTaskPane] 專案。
在 [專案] 功能表上，按一下 [加入使用者控制項] 。
在 [加入新項目] 對話方塊中，將使用者控制項的名稱變更為 TaskPaneControl，然後按一下 [加入] 。

使用者控制項隨即在設計工具中開啟。
從 [工具箱] 的 [通用控制項] 索引標籤，將 TextBox 控制項拖曳至使用者控制項。

設計功能區的使用者介面

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

建立自訂功能區 UI

在 [專案] 功能表上，按一下 [加入新項目]。
選取 [ 加入新項目 ] 對話方塊中的 [ 功能區 (視覺化設計工具)]。
將新功能區的名稱變更為 ManageTaskPaneRibbon，然後按一下 [加入] 。

ManageTaskPaneRibbon.cs 或 ManageTaskPaneRibbon.vb 檔案會在功能區設計工具中開啟，並顯示預設的索引標籤和群組。
在功能區設計工具中，按一下 [group1] 。
在 [屬性] 視窗中，將 [標籤] 屬性設定為「工作窗格管理員」。
從 [工具箱] 的 [Office 功能區控制項] 索引標籤，將 ToggleButton 控制項拖曳至 [工作窗格管理員] 群組。
按一下 [toggleButton1] 。
在 [屬性] 視窗中，將 [標籤] 屬性設定為「顯示工作窗格」。

顯示具有電子郵件訊息的自定義功能區用戶介面

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

使用電子郵件訊息顯示自定義功能區UI

在功能區設計工具中，按一下 [ManageTaskPaneRibbon] 功能區。
在 [屬性] 視窗中，按一下 [RibbonType] 旁的下拉式清單，然後選取 [Microsoft.Outlook.Mail.Compose] 和 [Microsoft.Outlook.Mail.Read] 。

建立類別來管理偵測器視窗和自定義工作窗格

在某些情況下，VSTO 載入宏必須識別哪些自定義工作窗格與特定電子郵件訊息相關聯。這些情況包括：

當使用者關閉電子郵件訊息時。在這種情況下，VSTO 增益集必須移除對應的自訂工作窗格，以確保正確地清除 VSTO 增益集所使用的資源。
使用者關閉自訂工作窗格時。在此情況下，VSTO 載入宏必須更新電子郵件訊息功能區上切換按鈕的狀態。
當使用者按下功能區上的切換按鈕時。在這種情況下，VSTO 增益集必須隱藏或顯示對應的工作窗格。

若要讓 VSTO 載入宏追蹤哪些自定義工作窗格與每個開啟的電子郵件訊息相關聯，請建立包裝 Inspector 和 CustomTaskPane 物件的自定義類別。這個類別會為每個電子郵件訊息建立新的自定義工作窗格物件，並在對應的電子郵件訊息關閉時刪除自定義工作窗格。

若要建立類別來管理偵測器視窗和自定義工作窗格

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

在檔案最上方加入下列陳述式。

using Microsoft.Office.Tools;

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

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

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

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

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

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

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

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

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

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

將下列方法加入您在上一個步驟中加入的程式碼之後。這個方法是包含目前電子郵件訊息之物件的事件Inspector事件處理程式Close。事件處理程式會在電子郵件訊息關閉時釋放資源。這個事件處理常式也會從 CustomTaskPanes 集合中移除目前的自訂工作窗格。這有助於防止開啟下一封電子郵件訊息時，自定義工作窗格的多個實例。

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

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

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

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

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

初始化和清除載入宏所使用的資源

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

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

在 ThisAddIn.cs 或 ThisAddIn.vb 檔案中，找出 ThisAddIn 類別的定義。
將下列宣告加入至 ThisAddIn 類別：
- inspectorWrappersValue 欄位包含 VSTO 增益集所管理的全部 Inspector 和 InspectorWrapper 物件。
- inspectors 欄位會維護目前 Outlook 執行個體中偵測器視窗的集合參考。這個參考可以防止記憶體回收行程釋放包含 NewInspector 事件之事件處理常式的記憶體，您將在下一個步驟中宣告該事件。
  - C#
  - VB
```
private Dictionary<Outlook.Inspector, InspectorWrapper> inspectorWrappersValue =
    new Dictionary<Outlook.Inspector, InspectorWrapper>();
private Outlook.Inspectors inspectors;
```
```
Private inspectorWrappersValue As New Dictionary(Of Outlook.Inspector, InspectorWrapper)
Private WithEvents inspectors As Outlook.Inspectors
```

以下列程式碼取代 ThisAddIn_Startup 方法。這個程式碼會將事件處理常式附加至 NewInspector 事件，而該事件會將每一個現有的 Inspector 物件傳遞至事件處理常式。如果使用者在執行 Outlook 之後載入 VSTO 載入宏，VSTO 載入宏會使用此資訊來建立已開啟之所有電子郵件訊息的自定義工作窗格。

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

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

以下列程式碼取代 ThisAddIn_ShutDown 方法。這個程式碼會中斷連結 NewInspector 事件處理常式，並清除 VSTO 增益集所使用的物件。

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

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

將下列 NewInspector 事件處理常式加入 ThisAddIn 類別。如果新的 Inspector 包含電子郵件訊息，則方法會建立新 InspectorWrapper 對象的實例，以管理電子郵件訊息與對應工作窗格之間的關聯性。

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

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

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

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

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

Checkpoint

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

建置您的專案

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

將功能區切換按鈕與自定義工作窗格同步處理

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

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

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

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

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

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

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

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

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

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

測試專案

當您開始偵錯專案時，會開啟 Outlook 並載入 VSTO 增益集。 VSTO 載入宏會顯示自定義工作窗格的唯一實例，並顯示每個已開啟的電子郵件訊息。建立數個新的電子郵件訊息來測試程序代碼。

測試 VSTO 增益集

請按 F5。
在 Outlook 中，按兩下 [ 新增 ] 以建立新的電子郵件訊息。
在電子郵件訊息的功能區上，按兩下 [載入宏] 索引 卷標，然後按兩下 [ 顯示工作窗格] 按鈕。

確認標題為 [我的工作] 窗格的工作窗格 會顯示電子郵件訊息。
在工作窗格的文字方塊中，輸入「第一個工作窗格」。
關閉工作窗格。

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

確認工作窗格會開啟，而且文字方塊仍含有「第一個工作窗格」字串。
在 Outlook 中，按兩下 [ 新增 ] 以建立第二封電子郵件。
在電子郵件訊息的功能區上，按兩下 [載入宏] 索引 卷標，然後按兩下 [ 顯示工作窗格] 按鈕。

確認標題為 [我的工作] 窗格的工作窗格 會顯示電子郵件訊息，且此工作窗格中的文本框是空的。
在工作窗格的文字方塊中，輸入「第二個工作窗格」。
將焦點變更為第一封電子郵件。

確認與此電子郵件訊息相關聯的工作窗格仍會在文字框中顯示 [第一個工作] 窗格 。

這個 VSTO 增益集也會處理您可以嘗試的更進階案例。例如，您可以使用 [下一個專案] 和 [上一個專案] 按鈕來檢視電子郵件時，測試行為。您也可以在卸除 VSTO 載入宏、開啟數封電子郵件，然後重載 VSTO 載入宏時測試行為。

下一步

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

針對不同的應用程式，在 VSTO 載入宏中建立自定義工作窗格。如需支援自定義工作窗格之應用程式的詳細資訊，請參閱自定義工作窗格。
使用自訂工作窗格自動化 Microsoft Office 應用程式。如需詳細資訊，請參閱逐步解說：從自定義工作窗格自動執行應用程式。
在 Excel 中，建立可用來隱藏或顯示自訂工作窗格的功能區按鈕。如需詳細資訊，請參閱逐步解說：使用功能區按鈕同步處理自定義工作窗格。