吹き出しコントロールを使用してコンテンツを強調表示し、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 add-in's functionality. これは、アドインの UI に合わせてさまざまな方法で設定できます。You can configure it in a variety of ways to suit your add-in's UI. このコントロールを構成してページに追加し、その外観と動作をカスタマイズすることができます。You can 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 メンバーは、CalloutManager の中の Callout オブジェクトにマップされるキーです: 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 つのメンバーとタイトル文字列のみを使用して、最も簡単な吹き出しコントロールを作成する方法を示します。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 contentElement メンバーに値がない場合に、コントロール内に HTML を表示します。Display 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*/) {...}

nullNull
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*/) {...}

nullNull
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*/) {...}

nullNull
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*/) {...}

nullNull

吹き出しコントロール メソッドの使用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.

このオブジェクトには updownleftright の 4 つのブール値メンバーがあります。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) CalloutAction オブジェクトの吹き出しコントロールの配列に新しい CalloutAction を追加します。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. 吹き出しアクションは、1 つのアクションまたはアクションのメニューのいずれかで構成できます。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*/) {...}

nullNull
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*/) {...}

nullNull
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*/) {...}

nullNull
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 1 つのアクションではなく、アクションのメニューを定義します。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, ...]

nullNull

次のセクションでは、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 user object.

その際、CalloutManager によってコントロールのエントリが連想配列に追加され、必須のメンバー ID の値が連想配列のキーとなります。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 members 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 members 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.

割り当てられた Callout オブジェクトが launchPoint にない場合、このメソッドは例外をスローします。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.

割り当てられた Callout オブジェクトが launchPoint にない場合、このメソッドは 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() 何も返しません。Excel 2003: Returns nothing.

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

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

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

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

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

コントロールの方向を変更します。Returns nothing. Changes the direction of the control.
flipVertical()flipVertical() 何も返しません。Excel 2003: 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