次の方法で共有


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

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

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

このリボン オブジェクト モデルの主要な要素は、リボン クラスリボン イベント、およびリボン コントロール クラスです。

リボン クラス

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

このクラスは、リボン コード ファイルとリボン デザイナー コード ファイルを分割する部分クラスとして位置付けられます。

リボン イベント

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

イベント 説明
Load Office アプリケーションがリボンのカスタマイズを読み込んだときに発生します。 Load イベント ハンドラーがリボン コード ファイルに自動的に追加されます。 このイベント ハンドラーを使用して、リボンが読み込まれるときにカスタム コードを実行します。
LoadImage リボンが読み込まれたときに、リボンのカスタマイズ内のイメージをキャッシュできます。 これにより、リボンのイメージをこのイベント ハンドラーにキャッシュするコードを作成する場合に、パフォーマンスを多少向上させることができます。 詳細については、LoadImageを参照してください。
Close リボンのインスタンスを閉じたときに発生します。

リボン コントロール

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

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

コントロール名 クラス名
ボックス RibbonBox
Button RibbonButton
ButtonGroup RibbonButtonGroup
CheckBox RibbonCheckBox
ComboBox RibbonComboBox
DropDown RibbonDropDown
EditBox RibbonEditBox
ギャラリー RibbonGallery
グループ RibbonGroup
ラベル RibbonLabel
メニュー RibbonMenu
Separator RibbonSeparator
SplitButton RibbonSplitButton
Tab RibbonTab
ToggleButton RibbonToggleButton

Microsoft.Office.Tools.Ribbon 名前空間では、System.Windows.Forms 名前空間に属するコントロール クラスとの名前の衝突を回避するために、型名にプレフィックス "Ribbon" が追加されています。

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

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

Ribbon コントロールには、コントロールへのラベルの割り当てやコントロールの表示/非表示の切り替えなど、さまざまなタスクの実行に使用できるプロパティが含まれています。

リボンが読み込まれた後、またはコントロールが動的メニューに追加された後で、プロパティが読み取り専用になることがあります。 詳しくは、「読み取り専用になるプロパティの設定」をご覧ください。

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

タスク : これを行うには、次の手順を実行します。
コントロールの表示/非表示を切り替える。 Visible プロパティを使用します。
コントロールを有効または無効にします。 Enabled プロパティを使用します。
コントロールのサイズを設定する。 ControlSize プロパティを使用します。
コントロールに表示するイメージを取得する。 Image プロパティを使用します。
コントロールのラベルを変更する。 Label プロパティを使用します。
ユーザー定義のデータをコントロールに追加する。 Tag プロパティを使用します。
RibbonBoxRibbonDropDownRibbonGallery

RibbonSplitButton コントロール。
Items プロパティを使用します。
RibbonComboBoxRibbonDropDownRibbonGallery のいずれかのコントロールに項目を追加する。 Items プロパティを使用します。
RibbonMenu にコントロールを追加する。 Items プロパティを使用します。

リボンが Office アプリケーションに読み込まれた後で RibbonMenu にコントロールを追加する場合は、リボンが Office アプリケーションに読み込まれる前に Dynamic プロパティを true に設定する必要があります。 詳しくは、「読み取り専用になるプロパティの設定」をご覧ください。
RibbonComboBox 内の選択された項目を取得する。

RibbonDropDown または RibbonGallery
SelectedItem プロパティを使用します。 RibbonComboBox では、Text プロパティを使用します。
RibbonTab 上のグループを取得する。 Groups プロパティを使用します。
RibbonGallery に表示する行および列の数を指定する。 RowCount プロパティおよび ColumnCount プロパティを使用します。

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

リボンが読み込まれる前にのみ設定できるプロパティがあります。 それらのプロパティは次の 3 つの方法で設定できます。

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

  • リボン クラスのコンストラクター。

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

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

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

    詳しくは、「読み取り専用になるプロパティ」をご覧ください。

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

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

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

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

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

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

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

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

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

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

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

Note

動的メニューのコントロールのプロパティは、いつでも設定できます。 この場合、次の表の内容は該当しません。

プロパティ リボン コントロール クラス
BoxStyle RibbonBox
ButtonType RibbonSplitButton
ColumnCount RibbonGallery
ControlId RibbonTab
ダイアログ起動ツール RibbonGroup
動的 RibbonMenu
Global OfficeRibbon
グループ RibbonTab
ImageName RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton
ItemSize RibbonMenu

RibbonSplitButton
MaxLength RibbonComboBox

RibbonEditBox
名前 RibbonComponent
Position RibbonButton

RibbonCheckBox

RibbonGallery

RibbonGroup

RibbonMenu

RibbonSeparator

RibbonSplitButton

RibbonTab

RibbonToggleButton
RibbonType OfficeRibbon
行数 RibbonGallery
ShowItemImage RibbonComboBox

RibbonDropDown

RibbonGallery
ShowItemLabel RibbonDropDown

RibbonGallery
ShowItemSelection RibbonGallery
SizeString RibbonComboBox

RibbonDropDown

RibbonEditBox
StartFromScratch OfficeRibbon
タブ OfficeRibbon
Title RibbonSeparator

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

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

リボンの他のインスタンスが作成されたときにこれらのプロパティを別の値に設定する条件ロジックがある場合、そのコードは何の効果ももたらしません。

Note

Outlook リボンに追加した各コントロールで [Name] プロパティが設定されるようにしてください。 実行時にコントロールを Outlook リボンに追加する場合は、このプロパティをコードで設定する必要があります。 デザイン時にコントロールを Outlook リボンに追加する場合は、Name プロパティが自動的に設定されます。

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

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

イベント 説明
をクリックします。 コントロールがクリックされたときに発生します。
TextChanged 編集ボックスまたはコンボ ボックス内のテキストが変更されたときに発生します。
ItemsLoading コントロールの Items コレクションが Office から要求されたときに発生します。 Office は、コードがコントロールのプロパティを変更するか、InvalidateControl メソッドが呼び出されるまで、Items コレクションをキャッシュします。
ButtonClick RibbonGallery または RibbonDropDown 内のボタンがクリックされたときに発生します。
SelectionChanged RibbonDropDown または RibbonGallery 内の選択項目が変更されたときに発生します。
DialogLauncherClick グループの右下にあるダイアログ ランチャー アイコンがクリックされたときに発生します。

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

パラメーター 説明
送信者 イベントを発生させたコントロールを表す Object
e RibbonControlEventArgs を格納している IRibbonControl。 このコントロールを使用すると、Visual Studio Tools for Office ランタイムによって提供されるリボン オブジェクト モデルには用意されていないプロパティにアクセスできます。