功能區 XML

  • 發行項

功能區 （XML） 專案可讓您使用 XML 自訂功能區。 如果您想要以功能區 （Visual Designer） 項目不支援的方式自定義功能區，請使用功能區 （XML） 專案。 如需每個專案可執行的比較，請參閱 功能區概觀。

適用於： 本主題中的資訊適用於下列應用程式的檔層級專案和 VSTO 載入宏專案：Excel;InfoPath 2013 和 InfoPath 2010;前景;幻燈片;專案;Visio;詞。 如需詳細資訊，請參閱 Office 應用程式 lication 和項目類型所提供的功能。

將功能區 （XML） 專案新增至專案

您可以從 [加入新項目] ribbon 對話方塊，將 [功能區 (XML)] GetCustomUI 項目加入至任何 Office 專案。 Visual Studio 會自動將下列檔案加入您的專案中：

  • 功能區 XML 檔。 這個檔案會定義功能區使用者介面 (UI)。 請使用這個檔案加入 UI 項目，例如索引標籤、群組和控制項。 如需詳細資訊，請參閱 本主題稍後的功能區 XML 檔案參考 。

  • 功能區程式碼檔案。 此檔案內含「功能區類別」 GetCustomUI(ribbon class)。 這個類別具有您在 [加入新項目] ribbon 對話方塊中為 [功能區 (XML)] GetCustomUI 項目所指定的名稱。 Microsoft Office 應用程式 lications 會使用這個類別的實例來載入自定義功能區。 如需詳細資訊，請參閱 本主題稍後的功能區類別參考 。

    根據預設，這些檔案會將自定義群組新增至 功能區中的 [載入宏] 索引 標籤。

在 Microsoft Office 應用程式 lication 中顯示自定義功能區

將功能區 （XML） 專案新增至項目之後，您必須將程式代碼新增至 ThisAddin、ThisWorkbook 或 ThisDocument 類別，以覆寫 CreateRibbonExtensibilityObject 方法，並將功能區 XML 類別傳回至 Office 應用程式 lication。

下列程式碼範例將覆寫 CreateRibbonExtensibilityObject 方法並傳回名為 MyRibbon 的功能區 XML 類別。

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

定義自定義功能區的行為

您可以建立 回呼方法，以回應用戶動作，例如按兩下功能區上的按鈕。 回呼方法和 Windows Forms 控制項中的事件非常類似，但回呼方法是由 UI 項目中 XML 的屬性所識別。 請在功能區類別中撰寫方法，接著控制項便會呼叫與屬性值名稱相同的方法。 例如，您可以建立當使用者按兩下功能區上的按鈕時所呼叫的回呼方法。 建立回呼方法需要執行兩個步驟：

  • 在程式碼中識別回呼方法的功能區 XML 檔案中，將屬性指派給控制項。

  • 在功能區類別中定義回呼方法。

注意

Outlook 還需要另一個步驟。 如需詳細資訊，請參閱 自定義 Outlook 的功能區。

如需示範如何從功能區自動化應用程式的逐步解說，請參閱 逐步解說：使用功能區 XML 建立自定義索引標籤。

將回呼方法指派給控件

若要將回呼方法指派給功能區 XML 檔中的控制項，請加入指定回呼方法類型及方法名稱的屬性。 例如，下列項目會定義擁有名為 ribbon 之 OnToggleButton1。

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

當使用者執行與特定控制項相關聯的主要工作時，便會呼叫GetCustomUI 。 例如，當使用者按一下切換按鈕時，便會呼叫該按鈕的 GetCustomUI 回呼方法。

您在屬性中指定的方法可以具有任何名稱。 但必須符合您在功能區程式碼檔案中定義之方法的名稱。

您可以將許多不同類型的回呼方法指定給功能區控制項。 如需每個控制項可用的回呼方法完整清單，請參閱針對開發人員自定義 Office （2007） 功能區使用者介面的技術文章 （第 3 部分 3） 。

定義回呼方法

請在功能區程式碼檔案的功能區類別中定義回呼方法。 回呼方法具有幾項需求：

  • 必須將其宣告為公用。

  • 其名稱必須符合您指派給功能區 XML 檔中控制項之回呼方法的名稱。

  • 其簽章必須符合相關功能區項目適用之回呼方法類型的簽章。

    如需功能區控制項回呼方法簽章的完整清單，請參閱針對開發人員自定義 Office （2007） 功能區使用者介面的技術文章 （第 3 部分 3） 。 Visual Studio 不會針對您在功能區程式碼檔案中建立的回呼方法提供 IntelliSense 支援。 如果您建立的回呼方法不符合有效的簽章，雖然程式碼會進行編譯，但是當使用者按一下控制項時，並不會產生任何反應。

    所有的回呼方法都有 IRibbonControl 參數，代表呼叫該方法的控制項。 您可以使用這個參數，對多個控制項重複使用相同的回呼方法。 下列程式碼範例示範的 GetCustomUI 回呼方法會根據使用者所按下的控制項，執行不同的工作。

    public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
{
    if (control.Id == "checkBox1")
    {
        MessageBox.Show("You clicked " + control.Id);
    }
    else
    {
        MessageBox.Show("You clicked a different control.");
    }
}

功能區 XML 檔案參考

您可以將元素和屬性新增至功能區 XML 檔案，以定義自定義功能區。 根據預設，功能區 XML 檔包含下列 XML。

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

下表描述功能區 XML 檔中的預設項目。

元素 描述
customUI 表示 VSTO 載入宏專案中的自定義功能區。
ribbon 表示功能區。
標籤 代表一組功能區索引標籤。
索引標籤 代表單一功能區索引標籤。
群組 代表功能區索引標籤上的控制項群組。

這些元素具有屬性，可指定自定義功能區的外觀和行為。 下表描述功能區 XML 檔中的預設屬性。

屬性 父元素 描述
onLoad customUI 識別應用程式載入功能區時所呼叫的方法。
idMso 索引標籤 識別要顯示在功能區中的內建索引標籤。
id 群組 識別群組。
label 群組 指定出現在群組上的文字。

功能區 XML 檔案中的預設項目和屬性是可用項目和屬性的小型子集。 如需可用元素和屬性的完整清單，請參閱針對開發人員自定義 Office （2007） 功能區使用者介面的技術文章（第 2 部分 3）。

功能區類別參考

Visual Studio 會在功能區程式碼檔中產生功能區類別。 將功能區上控件的回呼方法新增至這個類別。 這個類別會實作 IRibbonExtensibility 介面。

下表描述此類別中的預設方法。

方法 描述
GetCustomUI 傳回功能區 XML 檔案的內容。 Microsoft Office 應用程式 lications 會呼叫此方法，以取得定義自定義功能區使用者介面的 XML 字串。 這個方法會實作 GetCustomUI 方法。 注意：GetCustomUI 應該只實作以傳回功能區 XML 檔案的內容;它不應該用來初始化 VSTO 載入宏。 具體而言，您不應嘗試在 GetCustomUI 實作中顯示對話方塊或其他視窗。 否則，自定義功能區的行為可能不正確。 如果需要執行初始化 VSTO 增益集的程式碼，請將該程式碼加入至 ThisAddIn_Startup 事件處理常式。
OnLoad 將 IRibbonControl 參數指派給 Ribbon 欄位。 Microsoft Office 應用程式 lication 會在載入自定義功能區時呼叫此方法。 您可以使用此欄位來動態更新自訂功能區。 如需詳細資訊，請參閱針對開發人員自定義 Office （2007） 功能區使用者介面的技術文章（第 1 部分為 3）。
GetResourceText 由 GetCustomUI 方法呼叫以取得功能區 XML 檔案的內容。

相關內容