吹き出しコントロールを使用してコンテンツを強調表示し、SharePoint ホスト型の SharePoint アドインの機能を強化するHighlight content and enhance the functionality of SharePoint-hosted SharePoint Add-ins with the callout control

SharePoint の吹き出しコントロールは、ユーザーの関心を引いたり、SharePoint ホスト型アドインの機能を紹介する柔軟な方法を提供します。The SharePoint callout control provides a flexible way to engage your user and showcase your SharePoint-hosted app's functionality. アドインの UI に合わせてさまざまな方法で構成できます。You can configure it in a variety of ways to suit your add-in's UI. このコントロールを構築してページに追加し、外観とビヘイビアーをカスタマイズできます。This article shows you how to construct this control, add it to your page, and customize its appearance and behavior.

SharePoint サイトで検索を行うと、検索結果の上にマウス ポインターを置くと常に表示されるため、実際の吹き出しコントロールの例を確認することができます。When you do searches in a SharePoint site, you'll see examples of the callout control in action because it appears whenever you hover over a search result.

以下の図は、1 つの検索結果に対する吹き出しを示しており、コンテンツ コントロールに典型的な内容をいくつか示しています。典型的な内容とは、タイトル、ページ上のアイテムについての情報、アイテムに対して行うアクション (ここでは [開く] と [送信]) のことです。The following figure shows the callout for a single search result and shows a few of the typical things in a content control: a title, some information about the item on the page, and actions (Open and Send) that you can take on the item.

この例では、情報とアクションは比較的簡単なものですが、吹き出しを使用する 2 つのメリットをすでにご理解いただけたと思います。In this case, the information and actions are relatively simple, but you can already see two advantages to using it. はじめに、吹き出しにより必要なときにページ上の要素についての追加情報を表示することができます。次に、ページに機能を追加するための洗練された方法を提供します。First, it lets you show additional information about elements on a page when that's needed, and second, it gives you an elegant way of adding functionality to the page.

SharePoint の検索結果ページに表示された吹き出しコントロールの例Example of the callout control on a SharePoint search results page

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

callout.js ファイルを含めることで HTML ページでコントロールを使用可能にするMake the control available to your HTML page by including the callout.js file

この例では、SP.SOD.executeFunc メソッドを使用して、スクリプト ファイルが、それに依存するコードを実行する前にロードすることを確認します。This example uses the SP.SOD.executeFunc method to ensure that the script file loads before you run any code that depends on it.

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

SP.SOD.executeFunc 関数に渡す関数には、callout.js ファイルがロードした後に実行するコードが含まれています。The function that you pass to the SP.SOD.executeFunc function contains the code that you want to run after the callout.js file loads. これらのファイルをロードしたら、CalloutManager オブジェクトを使用して、関連する吹き出しコントロールを必要とするページ要素ごとに Callout オブジェクトを作成します。After you load those files, you use the CalloutManager object to create a Callout object for each page element that needs to have a callout control associated with it.

CalloutManager は、連想配列内のページにあるすべての Callout オブジェクトへの参照を格納するシングルトンです。The CalloutManager is a singleton that stores references to every Callout object on a page inside an associative array.

Callout オブジェクトには、2 つの必須メンバー IDlaunchPoint だけが含まれています。The Callout object has only two required members: ID and launchPoint. ID メンバーは、CalloutManagerCallout オブジェクトにマッピングされるキーです (CalloutManager["value of the callout's ID member"])。The ID member is the key that is mapped to the Callout object in the CalloutManager: CalloutManager["value of the callout's ID member"]. launchPoint メンバーは、HTML ページ要素です。The launchPoint member is an HTML page element.

たとえば、ページで div 要素を作成または取得し、Callout オブジェクトのメンバーとして渡すことができます。You can, for example, create or get a div element on your page and pass it as a member of the Callout object. 既定では、吹き出しコントロールはユーザーが launchPoint 要素を選択するたびに表示されます。By default, the callout control appears whenever a user selects the launchPoint element.

この例では、2 つの必須メンバーと 1 つのタイトル文字列だけを使用して、可能な限り簡単な吹き出しコントロールを作成する方法を示します。This example shows you how to create the simplest possible callout control with only the two required members and a title string.

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

ユーザーがページ要素を選択するたびに、この固有の吹き出しが表示され、コントロールの上部にタイトルを表示します。This particular callout appears and displays a title at the top of the control whenever a user selects the page element. コントロールの外観、動作、配置、アクションを非常に効果的な方法でカスタマイズするには、オプションのメンバーを使用します。You use the optional members to customize the control's appearance, behavior, positioning, and actions in some very powerful ways. 吹き出しコントロールには、コントロールのインスタンスを作成した後にパラメーターの値を設定するのに使用できる set メソッドもあります。The callout control also has a set method that you can use to set a value for any parameter after you create an instance of the control.

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

また、CalloutOptions オブジェクトのすべての吹き出しメンバーに値を設定し、そのオブジェクトを createNew メソッドに渡すこともできます。You can also set values for all of the callout members in a CalloutOptions object and then pass that object to the createNew method.

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

吹き出しコントロールの外観をカスタマイズするHow to customize the appearance of the callout control

これらのメンバーを使用して、吹き出しの表示を制御することができます。You can use these members to control the display of callout.

メンバーMember 用途Purpose 有効な値 (既定は太字)Valid values (default in bold)
titletitle コントロールの上部にタイトルを表示します。Display a title at the top of the control. 文字列、 null 、HTML を含む文字列string, null, string containing HTML
contentcontent メンバーの値がない場合に、コントロールの内部に HTML を表示します。contentElementDisplay HTML inside the control whenever there is no value for the contentElement member. HTML を含む文字列、 nullcontentElement の値が存在する場合は null である必要があります。string containing HTML, null, must be null if contentElement has a value
contentElementcontentElement content メンバーへの値がない場合に、コントロール内に HTML 要素を表示します。Display an HTML element inside the control when there is no value for the content member. すべての HTML 要素、nullcontent に値がある場合は null である必要があります。any HTML element, null, must be null if content has a value
contentWidthcontentWidth 吹き出し本体コンテナーの幅をピクセル単位で指定します。Specify the width in pixels of the callout body container.

このコンテナーには四辺に 1 ピクセルの境界と 15 ピクセルのパディングがあるため、コントロールは指定する本体幅よりも 32 ピクセル分幅が広くなります。This container also has a 1-pixel border and 15-pixel padding on each side, so the control is 32 pixels wider than the body width that you specify.

コントロールの CSS overflow プロパティは hidden に設定されるので、指定する幅の内側に収めることができない場合、コンテンツがクリップされます。The control's CSS overflow property is set to hidden, so your content is clipped if it does not fit inside the width that you specify.

開いている状態の吹き出し上でこのメンバーを設定すると、変更が直ちに反映されます。If you set this member on an open callout, the change takes effect immediately.

これは、他のメンバーには適用されません。This is not true of the other members.
240 ~ 610 の任意の数値、 350 (既定では、コントロールの幅は 382 ピクセルになります)Any number between 240 and 610, 350 (making the control 382 pixels wide by default)
beakOrientationbeakOrientation 吹き出しコントロールの突起またはポインターの向きを指定します。Specify the orientation of the beak or pointer of the callout control. topBottom の向きtopBottom orientation

吹き出しコントロールの突起が上下方向に表示される場合Where the callout control's beak appears with the topbottom orientation

leftRight の向きleftRight orientation

吹き出しコントロールの突起が左右方向に表示される場合Where the callout control's beak appears with the leftright orientation

吹き出しコントロールのビヘイビアーをカスタマイズするHow to customize the behavior of the callout control

以下のメンバーを使用して、吹き出しのビヘイビアーを制御できます。You can use the following members to control the behavior of the callout. ページ上でアクションをしたときにコントロールが開いたり閉じたりする方法を指定できるため、重要度の高い openOptions メンバーから開始してください。You can use the following members to control the behavior of the callout. Begin with the important openOptions member because it lets you specify how the control will open and close when the user interacts with it on the page.

openOptions メンバーにこれらの値を使用するUse these values for the openOptions member 用途Purpose
{event: "click", closeCalloutOnBlur: true} 吹き出しコントロールが、ユーザーがマウスを使用して launchPoint 要素を選択した場合には表示されるように、また、ユーザーがマウスを launchPoint 要素から離した場合には常に閉じるようにしてください。Make the callout control appear when the user clicks on the launchPoint element with a mouse and close whenever a user moves the mouse away from the launchPoint element. Because the value of is , the value of the option is true by default and can't be changed. This is the default combination of values.

event の値は click のため、showCloseButton オプションの値は既定では true であり、変更することはできません。Because the value of event is click, the value of the showCloseButton option is true by default and can't be changed.

この値の組み合わせは既定です。This is the default combination of values.
{event: "hover", showCloseButton: true} 吹き出しコントロールが、ユーザーがマウスを使用して launchPoint 要素の上にポインターを置いた場合には表示されるように、また、ユーザーがコントロールの右上隅にある X ボタンを選択した場合には常に閉じるようにしてください。Make the callout control appear when the user hovers over the launchPoint element with a mouse and close whenever the user clicks on an X button in the upper right corner of the control. Because the value of is , the value of is not applicable and can't be set.

event の値は hover のため、closeCalloutOnBlur の値は適用不可で、設定できません。Because the value of event is hover, the value of closeCalloutOnBlur is not applicable and can't be set.
{event: "click", closeCalloutOnBlur: false} 吹き出しコントロールが、ユーザーがマウスを使用して launchPoint 要素の上にポインターを置いた場合には表示されるように、また、ユーザーがコントロールの右上隅にある X ボタンを選択した場合には常に閉じるようにしてください。Make the callout control appear when the user hovers over the launchPoint element with a mouse and close only whenever the user clicks on an X button in the upper right corner of the control. Since the value of is , the value of the option is true by default and can't be changed.

event の値は click のため、showClosebutton オプションの値は既定では true であり、変更することはできません。Because the value of event is click, the value of the showClosebutton option is true by default and can't be changed.


以下に、吹き出しのビヘイビアーを制御するために設定できる他のメンバーを示します。These are the other members that you can set to control the callout's behavior.

使用するメンバーUse this member 用途Purpose 有効な値 (既定は太字)Valid values (default in bold)
onOpeningCallbackonOpeningCallback 吹き出しコントロールがページにレンダリングされる前に必要となるアクションを実行します。Perform actions that must happen before the callout control is rendered on the page.

Callout オブジェクトは、指定する関数に対するパラメーターとして渡す必要があるため、このメンバーを使用して、コントロールがレンダリングされる前にコントロールのプロパティに値を設定することができます。Perform actions that must happen before the callout control is rendered on the page. Because the Callout object must be passed as a parameter to the function that you supply, you can use this member to set values for any of the control's properties before the control is rendered. You can also use this member to begin asynchronous actions that add or change the content of the control. You can set a value for this member only once.

また、このメンバーを使用して、コントロールのコンテンツを追加または変更する非同期アクションを開始することができます。You can also use this member to begin asynchronous actions that add or change the content of the control.

このメンバーへは、値を 1 度だけ設定することができます。You can set a value for this member only once.
function(callout /*=Callout*/) {...}

null#NULL!
onOpenedCallbackonOpenedCallback 吹き出しコントロールがページにレンダリングされて完全にアニメーション化した後に必要となるアクションを実行します。Perform actions that must happen after the callout control is rendered on the page and fully animated.

このメンバーを使用して、コントロールのドキュメント オブジェクト モデル (DOM) を操作することもできます。You might use this member to manipulate the Document Object Model (DOM) of the control.

このメンバーへは、値を 1 度だけ設定することができます。You can set a value for this member only once.
function(callout /*=Callout*/) {...}

null#NULL!
onClosingCallbackonClosingCallback 吹き出しコントロールを閉じている間、ただしページから完全に削除される前に必要となるアクションを実行します。Perform actions that must happen while the callout control is closing but before it has fully been removed from the page. You can set a value for this member only once.

このメンバーへは、値を 1 度だけ設定することができます。You can set a value for this member only once.
function(callout /*=Callout*/) {...}

null#NULL!
onClosedCallbackonClosedCallback 吹き出しコントロールが閉じて、ページから削除された後に必要となるアクションを実行します。Perform actions that must happen after the callout control has closed and been removed from the page. You can set a value for this member only once.

このメンバーへは、値を 1 度だけ設定することができます。You can set a value for this member only once.
function(callout /*=Callout*/) {...}

null#NULL!

吹き出しコントロールのメソッドを使用するUse the callout control methods

以下のメソッドを使用して、吹き出しコントロールの動作をカスタマイズできます。You can use these methods to customize the behavior of the callout control.

このメソッドを使用するUse this method 用途Purpose 有効なパラメーター値Valid parameter values
set({member:value})set({member:value}) コントロールのインスタンスの作成後にメンバーの値を設定します。Set values for members after you have constructed an instance of the control. 吹き出しコントロールのメンバーの値を定義する名前/値のペア。A name/value pair that defines a value for any callout control member.

var callout = new Callout({openOptions:{event: "click"}});callout.set({openOptions:{event: "hover"}});
getOrientation()getOrientation() 吹き出しコントロールが指している向きを表示する CalloutOrientation オブジェクトを返します。Return a CalloutOrientation object that indicates which way the callout control is pointing.

このオブジェクトには 4 つのブール型メンバー、updownleftright があります。This object has four Boolean members: up, down, left, and right.

コントロールが開いている間、これら値のうち 2 つが true となり、その他の 2 つは false となります (たとえば、upright)。Return a object that indicates which way the callout control is pointing. This object has four Boolean members: , , , and . While the control is open, two of these values will be true and two will be false ( up and right, for example).
パラメーターなしNo parameters
addEventCallback(string eventName, CalloutCallback callbackaddEventCallback(string eventName, CalloutCallback callback 吹き出しコントロールが eventName パラメーターで指定された状態に変更されるときに常に呼び出されるコールバック関数を登録します。Register a callback function that is called whenever the callout control changes to the state specified by the eventName parameter. eventName パラメーターは、openingopenclosingclosed のいずれかの値になる必要があります。The eventName parameter must be one of these values: opening, open, closing, closed.

callback パラメーターは、最初のパラメーターとして呼び出しコントロールのインスタンスを受け取る関数である必要があります。The callback parameter must be one of these values: , , , . The parameter must be a function that takes an instance of the callout control as its first parameter.
open()open() コントロールを表示します。Display of the Footer.ascx control

コントロールがすでに開いているか、開いている途中である場合には、このメソッドは false を返し、何の処理も行いません。Display the control. If the control is already open or opening, this method returns false and does nothing.
パラメーターなしNo parameters
close(bool useAnimation)close(bool useAnimation) コントロールを非表示にします。Hide the control.

コントロールがすでに閉じているか、閉じている途中である場合には、このメソッドは false を返し、何の処理も行いません。Hide the control. If the control is closed or already closing, this method returns false and does nothing.
アニメーションでコントロールを閉じるかどうかを指定するブール値です。A Boolean value that specifies whether the control closes with animation. Animation is off by default.

アニメーションは既定ではオフです。Animation is off by default.
toggle()toggle() コントロールのオープン/クローズ状態を切り替えます。Toggle the control's open/close state. パラメーターなしNo parameters
addAction(CallOutAction calloutAction)addAction(CallOutAction calloutAction) 新しい CalloutActionCalloutAction オブジェクトの吹き出しコントロールの配列に追加します。Add a new CalloutAction to the callout control's array of CalloutAction objects.

これらのオブジェクトは、コントロールのフッターに表示するアクションを定義します。These objects define the actions to show in the footer of the control.

[吹き出しコントロールをアクションに追加する] セクションで、これらのオブジェクトを構築する方法について説明します。The Add actions to the callout control section explains how to construct these objects.

アクションを追加することができるのは、コントロールのインスタンスを作成した後のみです。You can add actions only after creating an instance of the control.

コントロールに含めることができるアクションは 3 つまでで、それ以上追加する場合は例外を取得します。The control can have no more than three actions, and if you try to add more you'll get an exception.
CalloutAction オブジェクト。A CalloutAction object.
refreshActions()refreshActions() コントロールに追加されたすべてのアクションを再読み込みします。Reload all of the actions that have been added to the control. You can use this method to change, enable, or disable actions while the control is open.

このメソッドを使用して、コントロールが開いている間にアクションを変更、有効化、または無効化できます。Reload all of the actions that have been added to the control. You can use this method to change, enable, or disable actions while the control is open.
パラメーターなしNo parameters

吹き出しコントロールにアクションを追加するHow to add actions to the callout control

吹き出しコントロールのインスタンスを作成した後に、アクションを追加します。You add actions after you've created an instance of the callout control. 吹き出しアクションは、単一のアクションまたはアクションのメニューのいずれかで構成できます。A callout action can consist of either a single action or a menu of actions. 吹き出しコントロールには、最大 3 つのアクションを追加できます。You can add up to three actions to a callout control. 吹き出しアクションを作成したら、addAction メソッドを使用して CalloutControl オブジェクトに追加します。After you have created a callout action, you add it to the CalloutControl object with its addAction method. このアクションのサンプルでは、ユーザーがテキストを選択した後にブラウザで新しいウィンドウを開きます。This sample action opens a new window in your browser after the user selects the text.

//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 コンストラクタに渡すこともできます。You can also set values for all of the CalloutAction members in a CalloutActionOptions object and pass that object to the CalloutAction constructor.

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


以下のメンバーを使用して、吹き出しアクションのビヘイビアーを定義できます。You can use these members to define the behavior of a callout action.

使用するメンバーUse this member 用途Purpose 有効な値 (既定は太字)Valid values (default in bold)
text (必須)text (required) アクションのテキスト ラベルを表示します。Display a text label for the action. 文字列、 nullstring, null
onClickCallbackonClickCallback ユーザーが吹き出しアクションのラベルを選択するときに行われるアクションを定義します。Define the action that occurs when the user clicks on the callout action label. function(calloutAction /*=CalloutAction*/) {...}

null#NULL!
isEnabledCallbackisEnabledCallback 吹き出しを表示する前に実行され、アクションが有効化されているかどうかを特定するコールバック関数を定義します。Define a callback function that runs before the callout displays, and determines whether the action is enabled.

この関数が true を返した場合には、吹き出しは有効化されたアクションを表示します。If this function returns true, the callout displays the enabled action.

false を返した場合には、吹き出しはアクション テキストを表示しますが、アクションを無効化します。If it returns false, the callout displays the action text, but disables the action.
function(calloutAction /*=CalloutAction*/) {...}

null#NULL!
isVisibleCallbackisVisibleCallback 吹き出しを表示する前に実行され、アクション テキストを表示するかどうかを決定するコールバック関数を定義します。Define a callback function that runs before the callout displays and determines whether the action text displays.

この関数が true を返した場合には、吹き出しはアクション テキストを表示します。If this function returns true, the callout displays the action text.

*False* を返した場合には、吹き出しはアクション テキストを非表示にします。If it returns false, the callout hides the action text.

追加のアクションは、非表示のアクションと入れ替わる形で左に移動します。Additional actions move left to take the place of the hidden action.
function(calloutAction /*=CalloutAction*/) {...}

null#NULL!
tooltiptooltip ユーザーが吹き出しアクションのテキストをポイントしたときに表示されます。Display text when the user hovers over the callout action text. 文字列、 nullstring, null
disabledTooltipdisabledTooltip ユーザーが吹き出しアクション テキストの上にマウスポインターを置き、吹き出しアクションが無効化された (isEnabledCallback 関数が false を返した) 場合に、テキストを表示します。Display text when the user hovers over the callout action text and the callout action has been disabled (when the isEnabledCallback function returns false ). 文字列、 nullstring, null
menuEntriesmenuEntries 単一のアクションではなくアクションのメニューを定義します。Define a menu of actions instead of a single action. The next section explains how to create a and add it to a object. [ CalloutActionMenuEntry, ...]

null#NULL!

次のセクションでは、CalloutActionMenuEntry を作成して CalloutAction オブジェクトに追加する方法について説明します。Define a menu of actions instead of a single action. The next section explains how to create a CalloutActionMenuEntry and add it to a CalloutAction object.

吹き出しコントロールにアクションメニューを追加するHow to add action menus to the callout control

吹き出しアクションに単一のアクションではなくメニューが含まれる場合には、ユーザーに対して、以下の図のように吹き出しアクションテキストの横に下向きの矢印が表示されます。When a callout action contains a menu instead of a single action, the user sees a down arrow next to the callout action text, as in Figure 4.

ユーザーがアクション ラベルの横の矢印を選択すると、吹き出しアクションにメニューが表示されます。A callout action displays a menu when a user clicks on the arrow next to the action label.

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

メニューのエントリはいくつでも作成でき、CalloutAction オブジェクトの menuEntries メンバーの値として配列に渡すことで、吹き出しアクションに追加することができます。You can create as many menu entries as you want and add them to the callout action by passing them in an array, as the value of the menuEntries member of the CalloutAction object.

//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 つのパラメーターを取ります。The CalloutActionMenuEntry constructor takes three parameters. 最初の 2 つのパラメーターは必須です。The first two parameters are required. 3 番目のパラメーターはオプションですが、アイコンをテキストと一緒に表示できるので役に立ちます。The constructor takes three parameters. The first two parameters are required. The third is optional, but it can be helpful because it lets you display an icon with the text.

  • 各メニュー エントリのテキスト ラベルを表示する最初のパラメーターとして文字列を渡します。Pass a string as the first parameter to display a text label for each menu entry.

  • 2 番目のパラメーターとして、ユーザーがメニュー エントリのテキストをクリックしたときに発生するアクションを定義するための関数を渡します。Pass a function as the second parameter to define the action that occurs when the user clicks on the menu entry text.

  • テキスト ラベルの左側に表示するアイコンの URL を含む文字列を渡します。Pass a string that contains the URL for the icon that you want to display to the left of the text label.

CalloutManager を使用して吹き出しコントロールのインスタンスを作成して管理するHow to use the CalloutManager to create and manage instances of the callout control

CalloutManager シングルトン オブジェクトは、ページ上のすべての Callout オブジェクトへの参照を格納します。The CalloutManager singleton object stores references to every Callout object on a page. 吹き出しコントロールの各インスタンスを、各コントロールの ID 値がキーとなる連想配列に格納します。The singleton object stores references to every object on a page. It stores each instance of the callout control in an associative array where the ID value of each control is the key. The contains methods that help you create and manage the objects that it stores. CalloutManager には、格納する Callout オブジェクトを作成して管理するのに役立つメソッドが含まれます。The CalloutManager contains methods that help you create and manage the Callout objects that it stores.

このメソッドを使用するUse this method 用途Purpose 有効なパラメーター値Valid parameter values
createNew(members)createNew(members) 新しい Callout オブジェクトを作成します。Create a new object.

これを行うと、必須メンバー ID の値をキーとして、CalloutManager が連想配列にコントロールへのエントリを追加します。Create a new object. When you do this, the CalloutManager adds an entry for the control in its associative array, with the value of the required member ID as the key.
使用する各メンバーに値を割り当てる連想配列。An associative array that assigns values to each member that you want to use. The and members are required.

IDlaunchPoint メンバーは必須です。The ID, , , and launchPoint properties are required.
createNewIfNecessary (members)createNewIfNecessary (members) パラメーターとして渡す launchPoint に割り当てられた吹き出しコントロールがまだない場合には、Callout オブジェクトを作成します。Create a Callout object if the launchPoint that you pass as a parameter doesn't have a callout control assigned to it already. 使用する各メンバーに値を割り当てる連想配列。An associative array that assigns values to each member that you want to use. The and members are required.

IDlaunchPoint メンバーは必須です。The ID, , , and launchPoint properties are required.
getFromLaunchPoint: function (/@type(HTMLElement)/launchPoint)getFromLaunchPoint: function (/@type(HTMLElement)/launchPoint) 関数で指定された launchPoint に関連する Callout オブジェクトを取得します。Get the Callout object associated with the launchPoint provided in the function. This method returns null if the doesn't have a object assigned to it.

このメソッドは launchPoint に割り当てられた Callout がない場合には、例外をスローします。Get the object associated with the provided in the function. This method throws an exception if the launchPoint doesn't have a Callout object assigned to it.
パラメーターなしNo parameters
getFromLaunchPointIfExists: function (/@type(HTMLElement)/launchPoint)getFromLaunchPointIfExists: function (/@type(HTMLElement)/launchPoint) 関数で指定された launchPoint に関連する Callout オブジェクトを取得します。Get the Callout object associated with the launchPoint provided in the function. This method returns null if the doesn't have a object assigned to it.

このメソッドは、launchPoint に割り当てられた Callout オブジェクトがない場合、null を返します。Get the object associated with the provided in the function. This method returns null if the launchPoint doesn't have a Callout object assigned to it.
パラメーターなしNo parameters
getFromCalloutDescendant: function (/@type(HTMLElement)/descendant)getFromCalloutDescendant: function (/@type(HTMLElement)/descendant) 要素が与えた関数で指定された HTML 要素に関連する Callout オブジェクトを取得します。Get the Callout object associated with the HTML element provided in the function given element.

この要素は、吹き出し要素の子孫のいずれかになることができます。This element can be any descendent of the callout element.

たとえば、Callout オブジェクトを作成したときに割り当てた contentElement メンバーの値を渡すことができます。For example, you could pass the value of the contentElement member that you assigned when you created the Callout object.

子孫に関連する Callout オブジェクトがない場合、このメソッドは例外をスローします。This method throws an exception if the descendant doesn't have a Callout object associated with it.
パラメーターなしNo parameters
closeAll()closeAll() 開いているすべての Callout オブジェクトを閉じます。Closes all open Callout objects.

少なくとも 1 つの吹き出しを閉じると、このメソッドは true を返します。Closes all open objects. This method returns true if it closes at least one callout.
パラメーターなしNo parameters
isAtLeastOneCalloutOpen()isAtLeastOneCalloutOpen() 1 つ以上の吹き出しが開いているかどうかを調べます。Check to see if at least one callout is open. パラメーターなしNo parameters

ページ上に吹き出しコントロールを配置する。How to position the callout control on the page

このメンバーを使用するUse this member 用途Purpose 有効な値 (既定は太字)Valid values (default in bold)
boundingBoxboundingBox 吹き出しコントロールの offsetParent と同等の役割を果たす HTML 要素を指定します。Specify the HTML element that will serve as the equivalent of the offsetParent of the callout control.

既定では、これに対する既定値は吹き出しコントロールの offsetParent ですが、このメンバーを使用してコントロールが適切に配置されているかを確認することができます。By default, the default value for this is the callout control's offsetParent, but you can use this member to make sure that the control is positioned correctly.

吹き出しコントロールは、このボックス内で表示されるように自らを配置しようとします。The callout control attempts to position itself so that it's visible within this box. ボックス内で表示されたままになるように向きを変えます (突起の向きに応じて、上から下へ、または左から右へ)。It changes direction (from top to bottom or from left to right, depending on the beak orientation) to remain visible within it.
任意の HTML 要素、吹き出しコントロールを含む HTML 要素の offsetParentany HTML element, the offsetParent of the HTML element that contains the callout control
positionAlgorithmpositionAlgorithm 吹き出しコントロールの既定の配置アルゴリズムを上書きします。Override the default positioning algorithm for the callout control. CalloutOptions.prototype.defaultPositionAlgorithmCalloutOptions.prototype.defaultPositionAlgorithm,

function(calloutPositioningProxy) { ... }

以下のセクションで、calloutPositioningProxy オブジェクトを使用して吹き出しコントロールの配置アルゴリズムを記述する方法について説明します。Override the default positioning algorithm for the callout control. The following section describes how to use the calloutPositioningProxy object to write positioning algorithms for the callout control.

CalloutPositioningProxy で配置アルゴリズムを記述するWrite positioning algorithms with calloutPositioningProxy

calloutPositioningProxy オブジェクトは、吹き出しコントロールが既定で使用する配置ロジックを上書きするのに使用できるメソッドとプロパティを含みます。The calloutPositioningProxy object contains methods and properties that you can use to override the positioning logic that the callout control uses by default. たとえば、コントロールを常に launchPoint 要素の下の右側に表示したい場合には、以下のような配置アルゴリズムを記述します。The object contains methods and properties that you can use to override the positioning logic that the callout control uses by default. For example, if you want the control to appear below and to the right of the launchPoint element all of the time, you write a positioning algorithm that looks like the following.

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

次に、この関数を Callout オブジェクトの positionAlgorithm メンバーの値として渡します。これは Callout の作成時に行うことも、後から値を設定して行うこともできます。You would then pass that function as the value of the Callout object's positionAlgorithm member. You can do that when you create the Callout, or later by setting the value.

callout.set({positionAlgorithm: alwaysGoDownAndRight});

既定の位置設定ロジックは、ブラウザーの JavaScript コンソール (たとえば Internet Explorer の F12 開発者ツール) を起動することでいつでも確認できます。You can always take a look at the default positioning logic by launching your browser's JavaScript console (the Internet Explorer F12 Developer Tools, for example).

CalloutOptions.prototype.positionAlgorithm.toString()

これらのメソッドを CalloutPositioningProxy オブジェクトで使用して、独自の位置指定ロジックを作成できます。You can use these methods in the CalloutPositioningProxy object to write your own positioning logic.

メソッドMethod 説明Description
isCalloutTooFarTop()isCalloutTooFarTop() ブール値を返します。Returns Boolean.
isCalloutTooFarRight()isCalloutTooFarRight() ブール値を返します。Returns Boolean.
isCalloutTooFarBottom()isCalloutTooFarBottom() ブール値を返します。Returns Boolean.
isCalloutTooFarLeft()isCalloutTooFarLeft() ブール値を返します。Returns Boolean.
isCalloutLeftOfHardBoundingBox()isCalloutLeftOfHardBoundingBox() ブール値を返します。Returns Boolean.

true の場合には、コントロールの左側面がコンテナー要素の外側に配置されます。Returns Boolean. If true, the left side of the control sits outside its container element. It's not visible and the user can't scroll to it. 表示はされず、ユーザーはスクロールできません。Returns Boolean. If true, the bottom of the control sits outside its container element. It's not visible and the user can't scroll to it.
isCalloutRightOfHardBoundingBox()isCalloutRightOfHardBoundingBox() ブール値を返します。Returns Boolean.

true の場合には、コントロールの右側面がコンテナー要素の外側に配置されます。Returns Boolean. If true, the right side of the control sits outside its container element. It is not visible and the user can't scroll to it. 表示はされず、ユーザーはスクロールできません。Returns Boolean. If true, the right side of the control sits outside its container element. It is not visible and the user can't scroll to it.
isCalloutAboveHardBoundingBox()isCalloutAboveHardBoundingBox() ブール値を返します。Returns Boolean.

true の場合には、コントロールの上面がコンテナー要素の外側に配置されます。Returns Boolean. If true, the top of the control sits outside its container element. It's not visible and the user can't scroll to it. 表示はされず、ユーザーはスクロールできません。Returns Boolean. If true, the top of the control sits outside its container element. It's not visible and the user can't scroll to it.
isCalloutBelowHardBoundingBox()isCalloutBelowHardBoundingBox() ブール値を返します。Returns Boolean.

true の場合には、コントロールの下面がコンテナー要素の外側に配置されます。Returns Boolean. If true, the bottom of the control sits outside its container element. It's not visible and the user can't scroll to it. 表示はされず、ユーザーはスクロールできません。Returns Boolean. If true, the bottom of the control sits outside its container element. It's not visible and the user can't scroll to it.
isOrientedUp()isOrientedUp() ブール値を返します。Returns Boolean.
isOrientedDown()isOrientedDown() ブール値を返します。Returns Boolean.
isOrientedLeft()isOrientedLeft() ブール値を返します。Returns Boolean.
isOrientedRight()isOrientedRight() ブール値を返します。Returns Boolean.
moveUpAndRight()moveUpAndRight() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
moveUpAndLeft()moveUpAndLeft() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
moveDownAndRight()moveDownAndRight() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
moveDownAndLeft()moveDownAndLeft() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
moveTowardsOppositeQuadrant()moveTowardsOppositeQuadrant() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
flipHorizontal()flipHorizontal() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
flipVertical()flipVertical() 何も返しません。Returns nothing.

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
numberOfEdgesCollidingWithBoundingBox()numberOfEdgesCollidingWithBoundingBox() 表示された境界ボックスと吹き出しが接する端部の数を表す 0 から 4 の間の整数を返します。Returns an integer between 0 and 4 that represents the number of edges where the callout collides with the visible bounding box. For example, if the top of the control is clipped by the top of the document body after you call the method, the method returns a number greater than 1.

たとえば、moveUpAndRight() メソッドを呼び出した後にコントロールの上面がドキュメント本文の上面にクリップされている場合には、numberOfEdgesCollidingWithBoundingBox() は 1 より大きい数値を返します。Returns an integer between 0 and 4 that represents the number of edges where the callout collides with the visible bounding box. For example, if the top of the control is clipped by the top of the document body after you call the moveUpAndRight() method, the numberOfEdgesCollidingWithBoundingBox() method returns a number greater than 1.

次の位置設定アルゴリズムは、コントロールをテキストの上または下に移動します。 CalloutPositioningProxyisRTL プロパティは、テキストが右から左の言語を表示しているかどうかを示します。コントロールの位置がページ上のテキストに対して常に正しく設定されていることを確認するために、このプロパティをチェックします。This positioning algorithm makes the control go above or below the text. The isRTL property of the CalloutPositioningProxy tells you whether the text is displaying a right-to-left language. You check for this property to ensure that the control is always positioned correctly in relation to the text on the page.

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 に変更しますが、接している面がない場合には既定のアルゴリズムを使用します。This positioning algorithm changes the default direction of the control to downAndRight instead of upAndRight, but it uses the default algorithm if there are any collisions.

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

関連項目See also