吹き出しコントロールを使用してコンテンツを強調表示し、SharePoint ホスト型の SharePoint アドインの機能を強化する

SharePoint の吹き出しコントロールを使用すると、柔軟な方法でユーザーに操作を促したり、SharePoint でホストされるアドインの機能を紹介したりできます。 これは、アドインの UI に合わせてさまざまな方法で設定できます。 このコントロールを構成してページに追加し、その外観と動作をカスタマイズすることができます。

SharePoint サイトで検索を行うときに、マウス カーソルを検索結果の上に置くたびに、機能している吹き出しコントロールの例を見ることができます。

次の図では、1 つの検索結果の吹き出しと、吹き出しコントロールの一般的な内容をいくつか示しています。タイトル、ページ上のアイテムに関するいくつかの情報、およびアイテムに対して実行できるアクション ([開く] および [送信]) を示しています。

この場合、情報やアクションは比較的単純ですが、これを使用する 2 つの利点が既に見えています。 第一に、必要に応じてページ上の要素に関する追加情報を表示し、第二に、ページに機能を追加する優れた方法を提供します。

SharePoint の検索結果ページに表示された吹き出しコントロールの例

callout.js ファイルを含めることにより HTML ページでコントロールを使用可能にする

この例では、SP.SOD.executeFunc メソッドを使用して、スクリプト ファイルが読み込まれてから、そのスクリプト ファイルに依存するコードが実行されるようにします。

SP.SOD.executeFunc("callout.js", "Callout", function () {
    });

SP.SOD.executeFunc 関数に渡す関数には、callout.js ファイルが読み込まれた後に実行するコードが含まれています。 それらのファイルを読み込んだ後、CalloutManager オブジェクトを使用して、関連する吹き出しコントロールが必要なページ要素ごとに Callout オブジェクトを作成します。

CalloutManager は、連想配列内のページ上のすべての Callout オブジェクトへの参照を格納するシングルトンです。

Callout オブジェクトには 2 つの必要なメンバー ID と launchPoint だけが含まれています。 ID メンバーは、CalloutManager の中の Callout オブジェクトにマップされるキーです: CalloutManager["value of the callout's ID member"]。 launchPoint メンバーは、HTML ページ要素です。

たとえば、ページ上で div 要素を作成または取得し、それを Callout オブジェクトのメンバーとして渡すことができます。 既定では、ユーザーが launchPoint 要素を選択するたびに吹き出しコントロールが表示されます。

この例では、必要な 2 つのメンバーとタイトル文字列のみを使用して、最も簡単な吹き出しコントロールを作成する方法を示します。

var calloutPageElement = document.createElement("div");
var callout = CalloutManager.createNew({
   ID: "unique identifier",
   launchPoint: calloutPageElement,
   title: "callout title"
});

この特定の吹き出しが表示され、ユーザーがページ要素を選択するたびにコントロールの上部にタイトルが表示されます。 オプションのメンバーを使用して、コントロールの外観、動作、配置、アクションをいくつかの非常に強力な方法でカスタマイズします。 吹き出しコントロールには、コントロールのインスタンスを作成した後に、任意のパラメーターの値を設定するために使用できる Set メソッドも含まれています。

callout.set({openOptions:{event: "hover"}});

また、CalloutOptions オブジェクトのすべての吹き出しメンバーの値を設定してから、そのオブジェクトを createNew メソッドに渡すこともできます。

var calloutPageElement = document.createElement("div");
var calloutOptions = new CalloutOptions();
calloutOptions.ID = unique identifier;
calloutOptions.launchPoint = calloutPageElement;
calloutOptions.title = callout title;
var callout = CalloutManager.createNew(calloutOptions);

吹き出しコントロールの外観をカスタマイズする

これらのメンバーを使用して、吹き出しの表示を制御できます。

メンバー	用途	有効な値 (既定は太字)
title	コントロールの上部にタイトルを表示します。	文字列、 null 、HTML を含む文字列
content	メンバーの値がない場合は常に、コントロール内に HTML を contentElement 表示します。	HTML を含む文字列、 null 。 contentElement の値が存在する場合は null である必要があります。
contentElement	メンバーの値がない場合は、コントロール内に HTML 要素を content 表示します。	任意の HTML 要素、または null。content の値が存在する場合は null である必要があります。
contentWidth	吹き出しの本文のコンテナーのピクセル単位で幅を指定します。 このコンテナーには、各側に 1 ピクセルの境界線と各ピクセルの 15 ピクセルのパディングもあるため、コントロールは指定したボディ幅よりも 32 ピクセル広くなります。 コントロールの CSS overflow プロパティは に hidden設定されているため、指定した幅に収まらない場合はコンテンツがクリップされます。 このメンバーをオープンの吹き出しに設定すると、変更が直ちに反映にされます。 その他のメンバーの場合は、変更はすぐには反映されません。	240 から 610 の任意の数値、350 (既定では、コントロールの幅は 382 ピクセルになります)。
beakOrientation	吹き出しコントロールの突起またはポインターの方向を指定します。	topBottom の向き leftRight の向き

吹き出しコントロールの動作をカスタマイズする

次のメンバーを使用して、吹き出しの動作を制御することができます。 重要な openOptions メンバーから始めます。これは、ユーザーがページ上で操作するときにコントロールの開閉方法を指定できるためです。

以下に、吹き出しの動作を制御するために設定できる他のメンバーを示します。

吹き出しコントロール メソッドの使用

以下のメソッドを使用して、吹き出しコントロールの動作をカスタマイズできます。

吹き出しコントロールにアクションを追加する

吹き出しコントロールのインスタンスを作成した後に、アクションを追加します。 吹き出しアクションは、1 つのアクションまたはアクションのメニューのいずれかで構成できます。 吹き出しコントロールには、最大 3 つのアクションを追加できます。 吹き出しアクションを作成した後に、addAction メソッドを使用して CalloutControl オブジェクトにそれを追加します。 このサンプル アクションでは、ユーザーがテキストを選択した後に、ブラウザーに新しいウィンドウが開きます。

//Create CalloutAction
var calloutAction = new CalloutAction({
            text: "Open window"
            onClickCallback: function() {                
                window.open(url);
            }
        });

//Add Action to an instance of the CalloutControl        
        myCalloutControl.addAction(calloutAction);

また、CalloutActionOptions オブジェクトの CalloutAction メンバーの値を設定して、そのオブジェクトを CalloutAction コンストラクターに渡すこともできます。

//Create CalloutAction
var calloutActionOptions = new CalloutActionOptions();
calloutActionOptions.text = "Open window";
actionOptions.onClickCallback = function() {
    window.open(url);
};
var calloutAction = new CalloutAction(calloutActionOptions);

//Add Action to an instance of the CalloutControl        
        myCalloutControl.addAction(calloutAction);

以下のメンバーを使用して、吹き出しアクションの動作を定義できます。

次のセクションでは、CalloutActionMenuEntry を作成して CalloutAction オブジェクトに追加する方法について説明します。

吹き出しコントロールにアクション メニューを追加する

吹き出しアクションに単一のアクションではなくメニューが含まれる場合は、次の図のように、吹き出しアクションのテキストの横に下向き矢印が表示されます。

ユーザーがアクション ラベルの横の矢印を選択すると、吹き出しアクションによりメニューが表示される

メニュー エントリはいくつでも作成でき、CalloutAction オブジェクトの menuEntries メンバーの値として配列に指定することで吹き出しアクションに追加できます。

//Create two menu entries.
var menuEntry1 = new CalloutActionMenuEntry("Entry One", calloutActionCallbackFunction, "/_layouts/images/DOC16.GIF");
var menuEntry2 = new CalloutActionMenuEntry("Some Other Entry", calloutActionCallbackFunction, "/_layouts/images/XLS16.GIF");

//Add the menu entries to the callout action.
var calloutAction = new CalloutAction({
   text: "MENU W/ ICONS",
   menuEntries: [menuEntry1, menuEntry2]
})

//Add the callout action to the callout control.
callout.addAction(calloutAction);

CalloutActionMenuEntry コンストラクターは、次の 3 つのパラメーターを取ります。 最初の 2 つのパラメーターは必須です。 3 番目のパラメーターはオプションですが、テキストを伴うアイコンを表示できるので便利です。

• 各メニュー項目のテキスト ラベルを表示する最初のパラメーターとして文字列を渡します。

• 2 番目のパラメーターとして、ユーザーがメニュー エントリのテキストをクリックしたときに発生するアクションを定義するための関数を渡します。

• テキスト ラベルの左側に表示するアイコンの URL を含んだ文字列を渡します。

CalloutManager を使用して吹き出しコントロールのインスタンスを作成および管理する

CalloutManager シングルトン オブジェクトは、ページ上のすべての Callout オブジェクトへの参照を格納します。 吹き出しコントロールの各インスタンスは、各コントロールの ID 値がキーである連想配列に格納されます。 CalloutManager には、それが格納する Callout オブジェクトを作成および管理するのに役立つメソッドが含まれています。

ページ上に吹き出しコントロールを配置する

calloutPositioningProxy オブジェクトを使用して吹き出しコントロールの位置設定アルゴリズムを記述する方法については、次のセクションで説明します。

calloutPositioningProxy が含まれる位置指定アルゴリズムを作成する

calloutPositioningProxy オブジェクトには、吹き出しコントロールが既定で使用する位置指定ロジックを上書きするために使用できるメソッドとプロパティが含まれています。 たとえば、コントロールが常に launchPoint 要素の下および右に表示されるようにするには、次のような位置指定アルゴリズムを記述します。

function alwaysGoDownAndRight(calloutPositioningProxy)  {
    calloutPositioningProxy.moveDownAndRight();
} 

その後、その関数をオブジェクトpositionAlgorithmのメンバーのCallout値として渡します。 これを行うには、値を Callout設定して 、 以降を作成します。

callout.set({positionAlgorithm: alwaysGoDownAndRight});

既定の位置設定ロジックは、ブラウザーの JavaScript コンソール (たとえば Internet Explorer の F12 開発者ツール) を起動することでいつでも確認できます。

CalloutOptions.prototype.positionAlgorithm.toString()

オブジェクトでこれらのメソッドを使用して、独自の CalloutPositioningProxy 配置ロジックを記述できます。

次の位置設定アルゴリズムは、コントロールをテキストの上または下に移動します。 の CalloutPositioningProxy プロパティはisRTL、テキストが右から左の言語を表示しているかどうかを示します。 コントロールの位置がページ上のテキストに対して常に正しく設定されていることを確認するために、このプロパティをチェックします。

function examplePositionAlgorithm(calloutPositioningProxy) {
    if (!calloutPositioningProxy.isRTL) {
        calloutPositioningProxy.moveDownAndRight();
        if (calloutPositioningProxy.isCalloutTooFarBottom()) {
            calloutPositioningProxy.moveUpAndRight();
        }
    }
    else {
        calloutPositioningProxy.moveDownAndLeft();
        if (calloutPositioningProxy.isCalloutTooFarBottom()) {
            calloutPositioningProxy.moveUpAndLeft();
        }
    }
}
callout.set({positionAlgorithm: examplePositionAlgorithm});

次の位置設定アルゴリズムは、コントロールの既定の方向を upAndRight から downAndRight に変更しますが、競合がない場合は既定のアルゴリズムを使用します。

function tryDownAndRightThenGoDefault(calloutPositioningProxy) {
    if (!calloutPositioningProxy.isRTL)
        calloutPositioningProxy.moveDownAndRight();
    else
        calloutPositioningProxy.moveDownAndLeft();
    
    if (calloutPositioningProxy.numberOfEdgesCollidingWithBoundingBox() > 0)
        return CalloutOptions.prototype.positionAlgorithm.apply(this, arguments);
};
callout.set({positionAlgorithm: tryDownAndRightThenGoDefault});

関連項目

• SharePoint で UX コンポーネントを作成する
• コード サンプル: SharePoint ホスト型アドインでリスト ビュー、吹き出し、およびダイアログを使用する
• SharePoint ホスト型の SharePoint アドインの作成を始める