リボン オブジェクト モデルの概要

Visual Studio Tools for Office ランタイムは、実行時にリボン コントロールのプロパティを取得および設定するために使用できる、厳密に型指定されたオブジェクト モデルを公開します。 たとえば、メニュー コントロールを動的に設定したり、コンテキストに応じてコントロールの表示と非表示を切り替えたりすることができます。 タブ、グループ、およびコントロールをリボンに追加することもできますが、Office アプリケーションによってリボンが読み込まれる前に限られます。 詳細については、「 読み取り専用になるプロパティを設定する」を参照してください。

適用対象: このトピックの情報は、次のアプリケーションのドキュメント レベルのプロジェクトと VSTO アドイン プロジェクトに適用されます: Excel、InfoPath 2013 および InfoPath 2010、Outlook、PowerPoint、Project、Visio、Word。 詳細については、「 Office アプリケーションとプロジェクトの種類で使用できる機能」を参照してください。

このリボン オブジェクト モデルは、主に リボン クラス、 リボン イベント、 リボン コントロール クラスで構成されます。

リボン クラス

新しい リボン (ビジュアル デザイナー) 項目をプロジェクトに追加すると、Visual Studio によって リボン クラスがプロジェクトに追加されます。 リボン クラスは、RibbonBase クラスから継承します。

このクラスは、リボン コード ファイルとリボン デザイナー コード ファイルの間で分割される部分クラスとして表示されます。

リボン イベント

リボン クラスには、次の 3 つのイベントが含まれています。

リボン コントロール

Microsoft.Office.Tools.Ribbon名前空間には、ツールボックスの Office リボン コントロール グループに表示される各コントロールの型が含まれています。

次の表に、各 Ribbon コントロールの型を示します。 各コントロールの説明については、「リボンの 概要」を参照してください。

Microsoft.Office.Tools.Ribbon名前空間では、これらの型の "リボン" プレフィックスを使用して、System.Windows.Forms名前空間内のコントロール クラスの名前との名前の競合を回避します。

リボン デザイナーにコントロールを追加すると、リボン デザイナーはそのコントロールのクラスをリボン デザイナーのコード ファイルのフィールドとして宣言します。

リボン コントロールのプロパティを使用する一般的なタスク

各 Ribbon コントロールには、コントロールにラベルを割り当てる、コントロールを非表示にして表示するなど、さまざまなタスクを実行するために使用できるプロパティが含まれています。

場合によっては、リボンの読み込み後、またはコントロールが動的メニューに追加された後に、プロパティが読み取り専用になります。 詳細については、「 読み取り専用になるプロパティを設定する」を参照してください。

次の表では、 Ribbon コントロール プロパティを使用して実行できるタスクの一部について説明します。

読み取り専用になるプロパティを設定する

一部のプロパティは、リボンが読み込まれる前にのみ設定できます。 これらのプロパティを設定するには、次の 3 つの場所があります。

• Visual Studio の [プロパティ] ウィンドウ。

• Ribbon クラスのコンストラクター内。

• プロジェクトのThisAddin、ThisWorkbook、またはThisDocument クラスのCreateRibbonExtensibilityObject メソッド。

  動的メニューには、いくつかの例外があります。 メニューを含むリボンが読み込まれた後でも、実行時に新しいコントロールの作成、プロパティの設定、および動的メニューへの追加を行うことができます。

  動的メニューに追加するコントロールのプロパティは、いつでも設定できます。

  詳細については、「 読み取り専用になるプロパティ」を参照してください。

リボンのコンストラクターでプロパティを設定する

Ribbon クラスのコンストラクターで、 コントロールのプロパティを設定できます。 このコードは、 InitializeComponent メソッドの呼び出しの後に表示する必要があります。 次の例では、現在の時刻が太平洋標準時 (UTC-8) 17:00 以降の場合に、新しいボタンをグループに追加します。

次のコードを追加します。

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

Visual Studio 2008 からアップグレードした Visual C# プロジェクトでは、リボン コード ファイルにコンストラクターが表示されます。

Visual Basic プロジェクトまたは Visual Studio 2013 で作成した Visual C# プロジェクトでは、コンストラクターがリボン デザイナーのコード ファイルに表示されます。 このファイルの名前は YourRibbonItem です。Designer.csまたは YourRibbonItem。Designer.vb。 Visual Basic プロジェクトでこのファイルを表示するには、まずソリューション エクスプローラーで [ すべてのファイルを表示 ] ボタンをクリックする必要があります。

CreateRibbonExtensibilityObject メソッドでプロパティを設定する

プロジェクトのRibbon、CreateRibbonExtensibilityObject、またはThisAddin クラスのThisWorkbook メソッドをオーバーライドするときに、ThisDocument コントロールのプロパティを設定できます。 CreateRibbonExtensibilityObjectメソッドの詳細については、「リボンの概要」を参照してください。

次の使用例は、Excel ブック プロジェクトのCreateRibbonExtensibilityObject クラスのThisWorkbook メソッドでリボン プロパティを設定します。

次のコードを追加します。

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

読み取り専用になるプロパティ

次の表は、リボンが読み込まれる前にのみ設定できるプロパティを示しています。

Outlook インスペクターに表示されるリボンのプロパティを設定する

リボンが表示されるインスペクターをユーザーが開くたびに、リボンの新しいインスタンスが作成されます。 ただし、リボンの最初のインスタンスが作成される前にのみ、上記の表に一覧表示されているプロパティを設定できます。 最初のインスタンスが作成されると、Outlook がリボンの読み込みに使用する XML ファイルが最初のインスタンスによって定義されるため、これらのプロパティは読み取り専用になります。

リボンの他のインスタンスの作成時にこれらのプロパティのいずれかを別の値に設定する条件付きロジックがある場合、このコードは無効になります。

リボン コントロール イベント

各コントロール クラスには、1 つ以上のイベントが含まれています。 次の表では、これらのイベントについて説明します。

これらのイベントのイベント ハンドラーには、次の 2 つのパラメーターがあります。

関連コンテンツ

• 実行時にリボンにアクセスする
• リボンの概要
• 方法: リボンのカスタマイズを開始する
• リボン デザイナー
• チュートリアル: リボン デザイナーを使用してカスタム タブを作成する
• チュートリアル: 実行時にリボンのコントロールを更新する
• Outlook のリボンをカスタマイズする
• 方法: 組み込みタブをカスタマイズする
• 方法: Backstage ビューにコントロールを追加する
• 方法: リボン デザイナーからリボン XML にリボンをエクスポートする
• 方法: アドイン のユーザー インターフェイス エラーを表示する