吹き出しコントロールを使用してコンテンツを強調表示し、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 メンバーから始めます。これは、ユーザーがページ上で操作するときにコントロールの開閉方法を指定できるためです。
openOptions メンバーに使用する値 |
用途 |
|---|---|
{event: "click", closeCalloutOnBlur: true} |
ユーザーがマウスで launchPoint 要素を選択したときには吹き出しコントロールを表示させ、ユーザーが launchPoint 要素からマウスを離したときは閉じるようにします。event の値が click なので、showCloseButton オプションの値は既定で true であり、変更することはできません。これは、値の既定の組み合わせです。 |
{event: "hover", showCloseButton: true} |
ユーザーが launchPoint 要素をマウスでポイントしたときに吹き出しコントロールを表示し、コントロールの右上隅の X ボタンを選択したときに閉じます。event の値が hover なので、closeCalloutOnBlur の値は適用されず、設定できません。 |
{event: "click", closeCalloutOnBlur: false} |
ユーザーが launchPoint 要素をマウスでポイントしたときに吹き出しコントロールを表示し、コントロールの右上隅の X ボタンを選択したときにのみ閉じます。event の値が click なので、showClosebutton オプションの値は既定で true であり、変更することはできません。 |
以下に、吹き出しの動作を制御するために設定できる他のメンバーを示します。
| 使用するメンバー | 用途 | 有効な値 (既定は太字) |
|---|---|---|
| onOpeningCallback | ページで吹き出しコントロールがレンダリングされる前に発生する必要のあるアクションを実行します。 オブジェクトは Callout 指定した関数にパラメーターとして渡す必要があるため、このメンバーを使用して、コントロールがレンダリングされる前にコントロールのプロパティの値を設定できます。このメンバーを使用して、コントロールの内容を追加または変更する非同期アクションを開始することもできます。 このメンバーの値は 1 回だけ設定することができます。 |
function(callout /*=Callout*/) {...}null |
| onOpenedCallback | ページで吹き出しコントロールがレンダリングされ、アニメーションが表示された後に発生する必要のあるアクションを実行します。 このメンバーを使用して、コントロールのドキュメント オブジェクト モデル (DOM) を操作することができます。 このメンバーの値は 1 回だけ設定することができます。 |
function(callout /*=Callout*/) {...}null |
| onClosingCallback | 吹き出しコントロールを閉じる際、コントロールが完全にページから削除されるまでに発生する必要のあるアクションを実行します。 このメンバーの値は 1 回だけ設定することができます。 |
function(callout /*=Callout*/) {...} null |
| onClosedCallback | 吹き出しコントロールを閉じる際、コントロールが完全にページから削除された後に発生する必要のあるアクションを実行します。 このメンバーの値は 1 回だけ設定することができます。 |
function(callout /*=Callout*/) {...}null |
吹き出しコントロール メソッドの使用
以下のメソッドを使用して、吹き出しコントロールの動作をカスタマイズできます。
| 使用するメソッド | 用途 | 有効なパラメーター値 |
|---|---|---|
| set({member:value}) | コントロールのインスタンスを作成した後に、メンバーの値を設定します。 | 吹き出しコントロールのメンバーの値を定義する名前/値のペア。var callout = new Callout({openOptions:{event: "click"}});callout.set({openOptions:{event: "hover"}}); |
| getOrientation() | CalloutOrientation吹き出しコントロールが指している方法を示す オブジェクトを返します。このオブジェクトには、、 down、left、および rightの up4 つのブールメンバーがあります。コントロールが開いている間、これらの値のうち 2 つは true、もう 2 つは false (たとえば up と right) になります。 |
パラメーターなし |
| addEventCallback(string eventName, CalloutCallback callback | 吹き出しコントロールが パラメーターで指定された状態に変更されるたびに呼び出されるコールバック関数を eventName 登録します。 |
パラメーターはeventName、 のいずれかの値closingopeningopenclosedである必要があります。パラメーターは callback 、吹き出しコントロールのインスタンスを最初のパラメーターとして受け取る関数である必要があります。 |
| open() | コントロールを表示します。 コントロールが既に開いているか、開いている途中である場合、このメソッドは false を返し、何も処理を行いません。 |
パラメーターなし |
| close(bool useAnimation) | コントロールを非表示にします。 コントロールが既に閉じているか、閉じている途中である場合、このメソッドは false を返し、何も処理を行いません。 |
アニメーションでコントロールを閉じるかどうかを指定するブール値。 アニメーションは既定でオフです。 |
| toggle() | コントロールのオープン/クローズ状態を切り替えます。 | パラメーターなし |
| addAction(CallOutAction calloutAction) | 吹き出しコントロールのオブジェクト配列CalloutActionに新しい CalloutAction を追加します。これらのオブジェクトは、コントロールのフッターに表示されるアクションを定義します。 「吹き出しコントロールにアクションを追加する」セクションには、これらのオブジェクトを構築する方法が説明されています。 アクションの追加は、コントロールのインスタンスを作成した後にのみ行うことができます。 コントロールは最大 3 つのアクションを持つことができ、それ以上追加しようとすると例外が発生します。 |
CalloutAction オブジェクト。 |
| refreshActions() | コントロールに追加されたすべてのアクションを再読み込みします。 このメソッドを使用して、コントロールが開いている間にアクションを変更、有効、または無効にすることができます。 |
パラメーターなし |
吹き出しコントロールにアクションを追加する
吹き出しコントロールのインスタンスを作成した後に、アクションを追加します。 吹き出しアクションは、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);
以下のメンバーを使用して、吹き出しアクションの動作を定義できます。
| 使用するメンバー | 用途 | 有効な値 (既定は太字) |
|---|---|---|
| text (必須) | アクションのテキスト ラベルを表示します。 | 文字列、null |
| onClickCallback | ユーザーが吹き出しアクションのラベルを選択すると発生するアクションを定義します。 | function(calloutAction /*=CalloutAction*/) {...}null |
| isEnabledCallback | 吹き出しが表示される前に実行されるコールバック関数を定義し、アクションが有効かどうかを判断します。 この関数が true を返した場合、吹き出しには有効なアクションが表示されます。 この関数が false を返した場合、吹き出しにはアクション テキストが表示されますが、アクションは無効になります。 |
function(calloutAction /*=CalloutAction*/) {...} null |
| isVisibleCallback | 吹き出しが表示される前に実行され、アクション テキストが表示されるかどうかを決定するコールバック関数を定義します。 この関数が true を返した場合、吹き出しにはアクション テキストが表示されます。 この関数が false を返した場合、吹き出しにはアクション テキストは表示されません。 追加のアクションは左に移動し、非表示になっているアクションに取って代わります。 |
function(calloutAction /*=CalloutAction*/) {...}null |
| tooltip | ユーザーが吹き出しアクションのテキストの上にカーソルを置いたときにテキストを表示します。 | 文字列、null |
| disabledTooltip | ユーザーが吹き出しアクションのテキストの上にカーソルを置き、吹き出しアクションが無効にされている (isEnabledCallback 関数が false を返す) 場合にテキストを表示します。 |
文字列、null |
| menuEntries | 1 つのアクションではなく、アクションのメニューを定義します。 | [ CalloutActionMenuEntry, ...]null |
次のセクションでは、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 オブジェクトを作成および管理するのに役立つメソッドが含まれています。
| 使用するメソッド | 用途 | 有効なパラメーター値 |
|---|---|---|
| createNew(members) | 新しい Callout オブジェクトを作成します。その際、 CalloutManager によってコントロールのエントリが連想配列に追加され、必須のメンバー ID の値が連想配列のキーとなります。 |
使用する各メンバーに値を割り当てる連想配列。 メンバー ID と launchPoint メンバーが必要です。 |
| createNewIfNecessary (members) | Calloutパラメーターとして渡す オブジェクトlaunchPointに吹き出しコントロールがまだ割り当てされていない場合は、オブジェクトを作成します。 |
使用する各メンバーに値を割り当てる連想配列。 メンバー ID と launchPoint メンバーが必要です。 |
| getFromLaunchPoint: function (/@type(HTMLElement)/launchPoint) | 関数で提供されている launchPoint に関連付けられた Callout オブジェクトを取得します。割り当てられた Callout オブジェクトが launchPoint にない場合、このメソッドは例外をスローします。 |
パラメーターなし |
| getFromLaunchPointIfExists: function (/@type(HTMLElement)/launchPoint) | 関数で提供されている launchPoint に関連付けられた Callout オブジェクトを取得します。割り当てられた Callout オブジェクトが launchPoint にない場合、このメソッドは null 値を返します。 |
パラメーターなし |
| getFromCalloutDescendant: function (/@type(HTMLElement)/descendant) | 関数指定の要素で提供されている HTML 要素に関連付けられた Callout オブジェクトを取得します。この要素には、吹き出し要素の任意の子孫を指定することができます。 たとえば、 Callout オブジェクトの作成時に割り当てた contentElement メンバーの値を渡すことができます。関連付けられた Callout オブジェクトが子孫にない場合、このメソッドは例外をスローします。 |
パラメーターなし |
| closeAll() | 開 Callout いているすべてのオブジェクトを閉じます。このメソッドは、少なくとも 1 つの吹き出しを閉じる場合は true を返します。 |
パラメーターなし |
| isAtLeastOneCalloutOpen() | 1 つ以上の吹き出しが開いているかどうかを調べます。 | パラメーターなし |
ページ上に吹き出しコントロールを配置する
| 使用するメンバー | 用途 | 有効な値 (既定は太字) |
|---|---|---|
| boundingBox | 吹き出しコントロールの と同等 offsetParent の機能を果たす HTML 要素を指定します。既定では、この既定値は吹き出しコントロールの offsetParent ですが、このメンバーを使用してコントロールが正しく配置されていることを確認できます。吹き出しコントロールは、このボックス内に表示されるように位置設定を試みます。 ボックス内に表示されるように、方向は変化します (突起の方向に応じて、上から下、または左から右へ)。 |
任意の HTML 要素、または吹き出しコントロールを含んだ HTML 要素の offsetParent |
| positionAlgorithm | 吹き出しコントロールの既定の位置設定アルゴリズムを上書きします。 | CalloutOptions.prototype.defaultPositionAlgorithmfunction(calloutPositioningProxy) { ... } |
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 配置ロジックを記述できます。
| メソッド | 説明 |
|---|---|
| isCalloutTooFarTop() | ブール値を返します。 |
| isCalloutTooFarRight() | ブール値を返します。 |
| isCalloutTooFarBottom() | ブール値を返します。 |
| isCalloutTooFarLeft() | ブール値を返します。 |
| isCalloutLeftOfHardBoundingBox() | ブール値を返します。 true の場合、コントロールの左側はコンテナー要素の外側に配置されます。 これは表示されず、ユーザーはそこにスクロールできません。 |
| isCalloutRightOfHardBoundingBox() | ブール値を返します。 true の場合、コントロールの右側はコンテナー要素の外側に配置されます。 これは表示されず、ユーザーはそこにスクロールできません。 |
| isCalloutAboveHardBoundingBox() | ブール値を返します。 true の場合、コントロールの上部はコンテナー要素の外側に配置されます。 これは表示されず、ユーザーはそこにスクロールできません。 |
| isCalloutBelowHardBoundingBox() | ブール値を返します。 true の場合、コントロールの下部はコンテナー要素の外側に配置されます。 これは表示されず、ユーザーはそこにスクロールできません。 |
| isOrientedUp() | ブール値を返します。 |
| isOrientedDown() | ブール値を返します。 |
| isOrientedLeft() | ブール値を返します。 |
| isOrientedRight() | ブール値を返します。 |
| moveUpAndRight() | 何も返しません。 コントロールの方向を変更します。 |
| moveUpAndLeft() | 何も返しません。 コントロールの方向を変更します。 |
| moveDownAndRight() | 何も返しません。 コントロールの方向を変更します。 |
| moveDownAndLeft() | 何も返しません。 コントロールの方向を変更します。 |
| moveTowardsOppositeQuadrant() | 何も返しません。 コントロールの方向を変更します。 |
| flipHorizontal() | 何も返しません。 コントロールの方向を変更します。 |
| flipVertical() | 何も返しません。 コントロールの方向を変更します。 |
| numberOfEdgesCollidingWithBoundingBox() | 表示されている境界ボックスと吹き出しが競合するエッジの数を表す 0 から 4 の整数を返します。 たとえば、 moveUpAndRight() メソッドを呼び出した後にコントロールの上部が文書の先頭で切り取られた場合、numberOfEdgesCollidingWithBoundingBox() メソッドは 1 より大きい数値を返します。 |
次の位置設定アルゴリズムは、コントロールをテキストの上または下に移動します。 の 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});