使用标注控件突出显示内容并改进 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.

下图显示了单个搜索结果的标注,还显示了内容控件中的几个典型部分:标题、关于页面上项目的一些信息以及可以对项目执行的操作(“打开”**** 和“发送”****)。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.

在本例中,信息和操作相对简单,但你已看到使用它的两个优点。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 对象只有两个必需的成员:IDlaunchPointThe 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.

本示例演示如何仅使用两个必需的成员和一个标题字符串,创建尽可能简单的标注控件。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. 标注控件还有一种设置方法,在创建控件的实例后,可以使用此方法设置任意参数的值。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);

自定义标注控件的外观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 的字符串, null ,如果 contentElement 具有值则必须为空。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 元素,null,如果 content 具有值,则必须为 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 orientation

标注控件的尖角按上下方向显示Where the callout control's beak appears with the topbottom orientation

左右方向leftRight orientation

标注控件的尖角按左右方向显示Where the callout control's beak appears with the leftright orientation

自定义标注控件的行为Customize the behavior of the callout control

可以使用以下成员控制标注的行为。You can use the following members to control the behavior of the callout. 从重要的 openOptions 成员开始,因为当用户在页面上与控件交互时,可使用它指定控件的打开和关闭方式。Begin with the important openOptions member because it lets you specify how the control opens and closes 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 selects the launchPoint element with a mouse, and close whenever a user moves the mouse away from the launchPoint element.

由于 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 selects an X button in the upper-right corner of the control.

由于 event 的值为 hovercloseCalloutOnBlur 的值不适用且无法设置。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 selects an X button in the upper-right corner of the control.

由于 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 对象作为参数传递给你提供的函数,在呈现控件之前,可以使用此成员设置任意控件属性的值。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.
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.

只能为此成员设置一次值。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.
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.
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.

此对象有四个 Boolean 成员:updownleftrightThis object has four Boolean members: up, down, left, and right.

控件打开时,其中两个值将为 true ,另外两个为 false(例如,upright)。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(字符串 eventName,CalloutCallback 回调addEventCallback(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 参数必须为以下值之一:openingopenclosingclosedThe eventName parameter must be one of these values: opening, open, closing, closed.

callback 参数必须是一个将标注控件的实例作为其第一个参数的函数。The callback parameter must be a function that takes an instance of the callout control as its first parameter.
open()open() 显示控件。Display the control.

如果该控件已打开或正在打开,此方法返回 false 且不执行任何操作。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 且不执行任何操作。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.
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.

控件的操作不能超过三个,如果尝试添加更多操作,会发生异常。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.
无参数No parameters

向标注控件添加操作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. 可以向标注控件添加最多三个操作。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 (required)text (required) 为操作显示文本标签。Display a text label for the action. 字符串,nullstring, null
onClickCallbackonClickCallback 定义用户选择标注操作标签时执行的操作。Define the action that occurs when the user selects 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 定义操作菜单,而不是单一操作。Define a menu of actions instead of a single action. [ CalloutActionMenuEntry, ...]

nullnull

下一节介绍如何创建 CalloutActionMenuEntry 并将它添加到 CalloutAction 对象。The next section explains how to create a CalloutActionMenuEntry and add it to a CalloutAction object.

向标注控件添加操作菜单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 the following figure.

用户选择操作标签旁的箭头时,标注操作将显示菜单A callout action displays a menu when a user selects 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 构造函数采用三个参数。The CalloutActionMenuEntry 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.

  • 传递一个函数作为第二个参数以定义当用户单击菜单项文本时发生的操作。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 来创建和管理标注控件的实例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 值是键。It stores each instance of the callout control in an associative array where the ID value of each control is the key. 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 Callout object.

执行此操作时,CalloutManager 在其关联数组中添加该控件的条目,并使用所需成员 ID 的值作为关键字。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.

需要 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.

需要 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.

如果没有为 launchPoint 分配 Callout 对象,此对象会引发异常。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.

如果没有为 launchPoint 分配 Callout 对象,此方法会返回 null。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.

如果至少关闭一个标注,则此方法返回 true。This method returns true if it closes at least one callout.
无参数No parameters
isAtLeastOneCalloutOpen()isAtLeastOneCalloutOpen() 检查是否还有 callout 是打开的。Check to see if at least one callout is open. 无参数No parameters

定位页面上的标注控件Position the callout control on the page

使用此成员Use this member 用途Purpose 有效值(默认以粗体显示)Valid values (default in bold)
boundingBoxboundingBox 指定 HTML 元素,它将作为标注控件的 offsetParent 的等效项。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 对象编写标注控件的定位算法。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 元素的下方和右侧显示控件,需要编写如下定位算法。For example, if you want the control to appear below and to the right of the launchPoint element all 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() 返回 Boolean 类型的值。Returns Boolean.
isCalloutTooFarRight()isCalloutTooFarRight() 返回 Boolean 类型的值。Returns Boolean.
isCalloutTooFarBottom()isCalloutTooFarBottom() 返回 Boolean 类型的值。Returns Boolean.
isCalloutTooFarLeft()isCalloutTooFarLeft() 返回 Boolean 类型的值。Returns Boolean.
isCalloutLeftOfHardBoundingBox()isCalloutLeftOfHardBoundingBox() 返回 Boolean 类型的值。Returns Boolean.

如果为 true,控件的左侧会位于容器元素的外部。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.
isCalloutRightOfHardBoundingBox()isCalloutRightOfHardBoundingBox() 返回 Boolean 类型的值。Returns Boolean.

如果为 true,控件的右侧会位于容器元素的外部。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() 返回 Boolean 类型的值。Returns Boolean.

如果为 true,控件的顶部会位于容器元素的外部。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() 返回 Boolean 类型的值。Returns Boolean.

如果为 true,控件的底部会位于容器元素的外部。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() 返回 Boolean 类型的值。Returns Boolean.
isOrientedDown()isOrientedDown() 返回 Boolean 类型的值。Returns Boolean.
isOrientedLeft()isOrientedLeft() 返回 Boolean 类型的值。Returns Boolean.
isOrientedRight()isOrientedRight() 返回 Boolean 类型的值。Returns Boolean.
moveUpAndRight()moveUpAndRight() 不返回任何值。Returns nothing.

改变控件的方向。Changes the direction of the control.
moveUpAndLeft()moveUpAndLeft() 不返回任何值。Returns nothing.

改变控件的方向。Changes the direction of the control.
moveDownAndRight()moveDownAndRight() 不返回任何值。Returns nothing.

改变控件的方向。Changes the direction of the control.
moveDownAndLeft()moveDownAndLeft() 不返回任何值。Returns nothing.

改变控件的方向。Changes the direction of the control.
moveTowardsOppositeQuadrant()moveTowardsOppositeQuadrant() 不返回任何值。Returns nothing.

改变控件的方向。Changes the direction of the control.
flipHorizontal()flipHorizontal() 不返回任何值。Returns nothing.

改变控件的方向。Changes the direction of the control.
flipVertical()flipVertical() 不返回任何值。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.

例如,如果在调用 moveUpAndRight() 方法后,控件的顶端被文档正文的顶端截断,则 numberOfEdgesCollidingWithBoundingBox() 方法返回一个大于 1 的数字。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});

这种定位算法将控件的默认方向更改为 downAndRight 而不是 upAndRight,但如果有任何冲突,它将使用默认算法。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