Office 專案中的事件Events in Office projects

每個 Office 專案範本會自動產生數個事件處理常式。Each Office project template automatically generates several event handlers. 文件層級自訂的事件處理常式與 VSTO 增益集的事件處理常式有些許不同。The event handlers for document-level customizations are slightly different from event handlers for VSTO Add-ins.

適用于: 本主題中的資訊適用于檔 - 層級專案和專案中的 VSTO 加入 - 。Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects. 請參閱 依 Office 應用程式和專案類型提供的功能See Features available by Office application and project type.

檔層級專案Document-level projects

Visual Studio 會在文件層級自訂中為新的或現有的文件或工作表,提供產生的後置程式碼。Visual Studio provides generated code behind new or existing documents or worksheets in document-level customizations. 這個程式碼會引發兩個不同的事件: StartupShutdownThis code raises two different events: Startup and Shutdown.

Startup 事件Startup event

在執行文件且組件中的所有初始設定程式碼都已執行之後,每個主項目 (文件、活頁簿或工作表) 都會引發 Startup 事件。The Startup event is raised for each of the host items (document, workbook or worksheet) after the document is running and all the initialization code in the assembly has been run. 這是在程式碼執行的類別建構函式中,所執行的最後動作。It is the last thing to run in the constructor of the class that your code is running in. 如需主專案的詳細資訊,請參閱 主專案和主控制項總覽For more information about host items, see Host items and host controls overview.

當您建立文件層級專案時,Visual Studio 會在產生的程式碼檔案中建立 Startup 事件的事件處理常式:When you create a document-level project, Visual Studio creates event handlers for the Startup event in the generated code files:

  • 如果是 Microsoft Office Word 專案,則事件處理常式的名稱為 ThisDocument_StartupFor Microsoft Office Word projects, the event handler is named ThisDocument_Startup.

  • 如果是 Microsoft Office Excel 專案,則事件處理常式有下列名稱:For Microsoft Office Excel projects, the event handlers have the following names:

    • Sheet1_Startup

    • Sheet2_Startup

    • Sheet3_Startup

    • ThisWorkbook_Startup

Shutdown 事件Shutdown event

當已載入您程式碼的應用程式定義域即將卸載時,每個主項目 (文件或工作表) 都會引發 Shutdown 事件。The Shutdown event is raised for each of the host items (document or worksheet) when the application domain that your code is loaded in is about to unload. 在卸載時,於類別中呼叫它是最後要執行的動作。It is the last thing to be called in the class as it unloads.

當您建立文件層級專案時,Visual Studio 會在產生的程式碼檔案中建立 Shutdown 事件的事件處理常式:When you create a document-level project, Visual Studio creates event handlers for the Shutdown event in the generated code files:

  • 如果是 Microsoft Office Word 專案,則事件處理常式的名稱為 ThisDocument_ShutdownFor Microsoft Office Word projects, the event handler is named ThisDocument_Shutdown.

  • 如果是 Microsoft Office Excel 專案,則事件處理常式有下列名稱:For Microsoft Office Excel projects, the event handlers have the following names:

    • Sheet1_Shutdown

    • Sheet2_Shutdown

    • Sheet3_Shutdown

    • ThisWorkbook_Shutdown

注意

在文件的 Shutdown 事件處理常式執行期間,請勿以程式設計方式移除控制項。Do not programmatically remove controls during the Shutdown event handler of the document. Shutdown 事件發生時,文件的 UI 項目便無法再使用。The UI elements of the document are no longer available when the Shutdown event occurs. 如果您想要在應用程式關閉之前移除控制項,請將程式碼加入其他事件處理常式,例如 BeforeCloseBeforeSaveIf you want to remove controls before the application closes, add your code to another event handler, such as BeforeClose or BeforeSave.

事件處理常式方法宣告Event handler method declarations

每個事件處理常式方法宣告都具有傳遞給它的相同引數: sendereEvery event handler method declaration has the same arguments passed to it: sender and e. 在 Excel 中, sender 引數會參考工作表,例如 Sheet1Sheet2;在 Word 中, sender 引數會參考文件。In Excel, the sender argument refers to the sheet, such as Sheet1 or Sheet2; in Word, the sender argument refers to the document. e 引數會參考事件的標準引數 (在此情況下不會使用)。The e argument refers to the standard arguments for an event, which are not used in this case.

下列程式碼範例會顯示 Word 文件層級專案中的預設事件處理常式。The following code example shows the default event handlers in document-level projects for Word.

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

End Sub

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

End Sub
private void ThisDocument_Startup(object sender, System.EventArgs e)
{
}

private void ThisDocument_Shutdown(object sender, System.EventArgs e)
{
}

下列程式碼範例會顯示 Excel 文件層級專案中的預設事件處理常式。The following code example shows the default event handlers in document-level projects for Excel.

注意

下列程式碼範例顯示 Sheet1 類別中的事件處理常式。The following code example shows the event handlers in the Sheet1 class. 其他主項目類別中的事件處理常式名稱會對應至這個類別名稱。The names of the event handlers in other host item classes correspond to the class name. 例如,在 Sheet2 類別中, Startup 事件處理常式的名稱為 Sheet2_StartupFor example, in the Sheet2 class, the Startup event handler is named Sheet2_Startup. ThisWorkbook 類別中, Startup 事件處理常式的名稱為 ThisWorkbook_StartupIn the ThisWorkbook class, the Startup event handler is named ThisWorkbook_Startup.

private void Sheet1_Startup(object sender, System.EventArgs e)
{
}

private void Sheet1_Shutdown(object sender, System.EventArgs e)
{
}
Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

End Sub

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

End Sub

檔層級 Excel 專案中的事件順序Order of events in document-level Excel projects

呼叫 Excel 專案中 Startup 事件處理常式的順序如下:The Startup event handlers in Excel projects are called in this order:

  1. ThisWorkbook_Startup.ThisWorkbook_Startup.

  2. Sheet1_Startup.Sheet1_Startup.

  3. Sheet2_Startup.Sheet2_Startup.

  4. Sheet3_Startup.Sheet3_Startup.

  5. 順序中的其他工作表。Other sheets in order.

    呼叫活頁簿方案中 Shutdown 事件處理常式的順序如下:The Shutdown event handlers in a workbook solution are called in this order:

  6. ThisWorkbook_Shutdown.ThisWorkbook_Shutdown.

  7. Sheet1_Shutdown.Sheet1_Shutdown.

  8. Sheet2_Shutdown.Sheet2_Shutdown.

  9. Sheet3_Shutdown.Sheet3_Shutdown.

  10. 順序中的其他工作表。Other sheets in order.

    此順序是在編譯專案時決定。The order is determined when the project is compiled. 如果使用者在執行階段重新排列工作表,則下次開啟或關閉活頁簿時,引發事件的順序並不會因而變更。If the user rearranges the sheets at run time, it does not change the order that the events are raised the next time the workbook is opened or closed.

VSTO 增益集專案VSTO Add-in projects

Visual Studio 提供 VSTO 增益集產生的程式碼。此程式碼會引發兩個不同的事件: StartupShutdownVisual Studio provides generated code in VSTO Add-ins. This code raises two different events: Startup and Shutdown.

Startup 事件Startup event

VSTO 增益集載入並執行組件中的所有初始化程式碼之後,會引發 Startup 事件。The Startup event is raised after the VSTO Add-in is loaded and all the initialization code in the assembly has been run. 這個事件是由所產生程式碼檔中的 ThisAddIn_Startup 方法處理。This event is handled by the ThisAddIn_Startup method in the generated code file.

ThisAddIn_Startup 事件處理常式中的程式碼是第一個執行的使用者程式碼,除非您的增益集會覆寫 RequestComAddInAutomationService 方法。Code in the ThisAddIn_Startup event handler is the first user code to run, unless your VSTO Add-in overrides the RequestComAddInAutomationService method. 在這個情況下, ThisAddIn_Startup 事件處理常式會在 RequestComAddInAutomationService之後呼叫。In this case, the ThisAddIn_Startup event handler is called after RequestComAddInAutomationService.

ThisAdd-In_Startup如果程式碼需要開啟檔,請勿在事件處理常式中加入程式碼。Don't add code in the ThisAdd-In_Startup event handler if the code requires a document to be open. 相反地,請將程式碼加入 Office 應用程式在使用者建立或開啟文件時所引發的事件。Instead, add that code to an event that the Office application raises when a user creates or opens a document. 如需詳細資訊,請參閱 Office 應用程式啟動時存取檔For more information, see Access a document when the Office application starts.

如需 VSTO 增益集啟動順序的詳細資訊,請參閱 Vsto 增益集的架構For more information about the startup sequence of VSTO Add-ins, see Architecture of VSTO Add-ins.

Shutdown 事件Shutdown event

當已載入您程式碼的應用程式定義域即將卸載時,會引發 Shutdown 事件。The Shutdown event is raised when the application domain that your code is loaded in is about to be unloaded. 這個事件是由所產生程式碼檔中的 ThisAddIn_Shutdown 方法處理。This event is handled by the ThisAddIn_Shutdown method in the generated code file. 卸載 VSTO 增益集時,這個事件處理常式會是最後一個執行的使用者程式碼。This event handler is the last user code to run when the VSTO Add-in is unloaded.

Outlook VSTO 增益集的關機事件Shutdown event in Outlook VSTO Add-ins

只有當使用者藉由使用 Outlook 的 [COM 增益集] 對話方塊停用 VSTO 增益集時,才會引發 Shutdown 事件。The Shutdown event is raised only when the user disables the VSTO Add-in by using the COM Add-ins dialog box in Outlook. Outlook 結束時不會引發此事件。It is not raised when Outlook exits. 如果您有必須在 Outlook 結束時執行的程式碼,請處理下列任一事件:If you have code that must run when Outlook exits, handle either of the following events:

注意

您可以修改登錄,強制 Outlook 在結束時引發 Shutdown 事件。You can force Outlook to raise the Shutdown event when it exits by modifying the registry. 不過,如果系統管理員還原此設定,則 Outlook 結束時,便不會再執行任何您加入至 ThisAddIn_Shutdown 方法的程式碼。However, if an administrator reverts this setting, any code that you add to the ThisAddIn_Shutdown method no longer runs when Outlook exits. 如需詳細資訊,請參閱 Outlook 2010 的關機變更For more information, see Shutdown changes for Outlook 2010.

另請參閱See also