Выделение контента и расширение функций надстроек SharePoint с размещением в SharePoint с помощью выноски

Элемент "Выноска" в SharePoint помогает привлечь внимание пользователя и продемонстрировать функции надстройки, размещенной в SharePoint. Вы можете адаптировать его под пользовательский интерфейс надстройки. Вы можете создать этот элемент управления, добавить его на страницу, а также настроить его внешний вид и поведение.

Вы можете увидеть выноску в действии, выполнив поиск на сайте SharePoint и наведя указатель на один из результатов.

На приведенном ниже рисунке показана выноска для одного результата поиска, а также представлено несколько типичных аспектов элемента управления контентом: заголовок, сведения об элементе на странице и действия (Открыть и Отправить), которые вы можете выполнить с этим элементом.

В этом случае информация и действия относительно простые, но преимущества использования выноски все равно заметны. Во-первых, она позволяет показывать дополнительную информацию об элементах на странице, когда это необходимо, а во-вторых, предоставляет элегантный способ добавления функций на страницу.

Пример выноски на странице результатов поиска в SharePoint

Предоставление HTML-странице доступа к элементу управления путем добавления файла callout.js

Используйте метод SP.SOD.executeFunc, чтобы файл сценария всегда загружался до выполнения зависящего от него кода.

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

Функция, которую вы передаете в функцию SP.SOD.executeFunc, содержит код, который нужно выполнить после загрузки файла callout.js. После загрузки этих файлов вы создаете объект Callout для каждого элемента страницы, с которым необходимо связать выноску, используя объект CalloutManager.

CalloutManager — это одноэлементный объект, хранящий ссылки на каждый объект Callout на странице в массиве ассоциативных элементов.

Объект Callout имеет всего два обязательных элемента: ID и launchPoint. Элемент ID — это ключ, сопоставленный с объектом Callout в CalloutManager (CalloutManager["value of the callout's ID member"]). Элемент launchPoint — это элемент HTML-страницы.

Например, вы можете создать или получить элемент div на своей странице и передать его в качестве элемента объекта Callout. По умолчанию выноска появляется, когда пользователь выбирает элемент launchPoint.

В этом примере показано, как создать простейшую выноску с двумя обязательными элементами и строкой заголовка.

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

Эта выноска появляется и показывает заголовок в верхней части элемента управления, когда пользователь выбирает элемент страницы. Для настройки внешнего вида, поведения, положения и действий элемента управления используются необязательные элементы. Выноска также имеет метод set, с помощью которого можно задать значение любого параметра после создания экземпляра элемента управления.

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

Вы также можете задать значения для всех элементов выноски в объекте CalloutOptions, а затем передать этот объект методу createNew.

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

Настройка внешнего вида выноски

Управлять внешним видом выноски можно с помощью указанных ниже элементов.

Элемент	Назначение	Допустимые значения (полужирным шрифтом выделено значение по умолчанию)
title	Отображение заголовка в верхней части элемента управления	строка, NULL, строка с HTML-кодом
содержимое	Отображение HTML-кода внутри элемента управления, когда нет значения для contentElement элемента.	строка с HTML-кодом, NULL, должен быть равен NULL, если contentElement имеет какое-либо значение.
contentElement	Отображение HTML-элемента внутри элемента управления, если для элемента нет значения content .	Любой элемент HTML, NULL, должен быть равен NULL, если для элемента content задано значение.
contentWidth	Указание ширины (в пикселях) контейнера основной части выноски. Этот контейнер также имеет границу шириной 1 пиксель и отбивку шириной 15 пикселей с каждой стороны, поэтому итоговый элемент управления на 32 пикселя шире указанной вами ширины. Свойство CSS overflow элемента управления имеет значение hidden, поэтому содержимое обрезается, если оно не помещается в указанную ширину. Если настроить этот элемент для открытой выноски, изменение вступит в силу немедленно. С другими элементами дело обстоит по-другому.	Любое число от 240 до 610, 350 (то есть по умолчанию элемент управления имеет ширину в 382 пикселя)
beakOrientation	Задает ориентацию стрелки или указателя выноски.	Ориентация topBottom Ориентация leftRight

Настройка поведения выноски

Вы можете настроить поведение выноски, используя указанные ниже элементы. Начните с элемента openOptions, так как он позволяет указать, как элемент управления открывается и закрывается, когда пользователь взаимодействует с ним на странице.

Значения элемента openOptions	Назначение
{event: "click", closeCalloutOnBlur: true}	Выноска появляется, когда пользователь наводит указатель на элемент launchPoint, и закрывается, когда пользователь убирает указатель с элемента launchPoint. Так как свойству event присвоено значение click, параметр showCloseButton имеет значение true, его нельзя изменить. Это сочетание значений используется по умолчанию.
{event: "hover", showCloseButton: true}	Выноска появляется, когда пользователь наводит указатель на элемент launchPoint, и закрывается, когда пользователь нажимает кнопку X в верхнем правом углу элемента управления. Так как свойству event присвоено значение hover, значение closeCalloutOnBlur не применимо, его нельзя задать.
{event: "click", closeCalloutOnBlur: false}	Выноска появляется, когда пользователь наводит указатель на элемент launchPoint, и закрывается, только когда пользователь нажимает кнопку X в верхнем правом углу элемента управления. Так как свойству event присвоено значение click, параметр showClosebutton имеет значение true, его нельзя изменить.

Ниже показаны другие элементы, с помощью которых можно управлять поведением выноски.

Элемент	Назначение	Допустимые значения (полужирным шрифтом выделено значение по умолчанию)
onOpeningCallback	Выполнение действий, которые должны произойти до отрисовки выноски на странице. Callout Так как объект должен быть передан в качестве параметра функции, которую вы предоставляете, этот элемент можно использовать для задания значений для любого из свойств элемента управления перед отрисовкой элемента управления. Вы также можете использовать этот член для запуска асинхронных действий, которые добавляют или изменяют содержимое этого элемента управления. Задать значение для этого элемента можно только один раз.	function(callout /*=Callout*/) {...} null
onOpenedCallback	Выполнение действий, которые должны произойти после отрисовки выноски на странице и ее полной анимации. Вы можете использовать этот член для работы с моделью DOM элемента управления. Задать значение для этого элемента можно только один раз.	function(callout /*=Callout*/) {...} null
onClosingCallback	Выполнение действий, которые должны произойти во время закрытия выноски, но до ее полного удаления со страницы. Задать значение для этого элемента можно только один раз.	function(callout /*=Callout*/) {...} null
onClosedCallback	Выполнение действий, которые должны произойти после закрытия выноски и ее удаления со страницы. Задать значение для этого элемента можно только один раз.	function(callout /*=Callout*/) {...} null

Использование методов выноски

Вы можете настраивать поведение выноски, используя указанные ниже методы.

Метод	Назначение	Допустимые значения параметров
set({member:value})	Задание значений для членов после создания экземпляра элемента управления	Пара имя-значение, которая определяет значение любого члена элемента управления выносками var callout = new Callout({openOptions:{event: "click"}});callout.set({openOptions:{event: "hover"}});
getOrientation()	CalloutOrientation Возвращает объект , указывающий, на какой путь указывает элемент управления выноской. Этот объект содержит четыре логических элемента: up, down, leftи right. Пока элемент управления открыт, для двух из этих значений задано значение true, а для двух других — false (например, up и right).	Нет параметров
addEventCallback(string eventName, CalloutCallback callback	Зарегистрируйте функцию обратного вызова, которая вызывается каждый раз, когда элемент управления выноской переходит в состояние, указанное параметром eventName .	Параметр eventName должен иметь одно из следующих значений: opening, open, closing, , closed. Параметр callback должен быть функцией, которая принимает экземпляр элемента управления выноской в качестве первого параметра.
open()	Отображение элемента управления. Если элемент управления уже открыт или находится в процессе открытия, этот метод возвращает значение false и не выполняется никаких действий.	Нет параметров
close(bool useAnimation)	Скрытие элемента управления. Если элемент управления уже закрыт или находится в процессе закрытия, этот метод возвращает значение false, не выполняется никаких действий.	Логическое значение, указывающее, сопровождается ли закрытие элемента управления анимацией. По умолчанию анимация выключена.
toggle()	Переключение открытого/закрытого состояния элемента управления	Нет параметров
addAction(CallOutAction calloutAction)	Добавьте новый CalloutAction объект в массив CalloutAction объектов элемента управления выноской. Эти объекты определяют действия, отображаемые в нижнем колонтитуле элемента управления. Инструкции по созданию этих объектов см. в разделе Добавление действий в выноску. Вы можете добавлять действия только после создания экземпляра элемента управления. В элемент управления нельзя добавить больше трех действий, иначе возникнет исключение.	Объект CalloutAction.
refreshActions()	Перезагрузка всех действий, добавленных в элемент управления. Вы можете использовать этот метод для изменения, включения или отключения действий при открытом элементе управления.	Нет параметров

Добавление действий в выноску

Действия добавляются после создания экземпляра выноски. Действие выноски может представлять собой одно действие или меню действий. В выноску можно добавить не более трех действий. Действие выноски добавляется в объект CalloutControl с помощью метода addAction. Показанное ниже действие открывает новое окно в браузере, когда пользователь выбирает текст.

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

Вы также можете задать значения для всех элементов CalloutAction в объекте CalloutActionOptions и передать этот объект конструктору CalloutAction.

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

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

Вы можете управлять поведением действия выноски, используя указанные ниже элементы.

Элемент	Назначение	Допустимые значения (полужирным шрифтом выделено значение по умолчанию)
text (обязательный)	Отображение текстовой метки для действия	строка, NULL
onClickCallback	Определение действия, выполняемого, когда пользователь выбирает подпись действия выноски.	function(calloutAction /*=CalloutAction*/) {...} null
isEnabledCallback	Определение функции обратного вызова, которая выполняется до отображения выноски и определяет, включено ли действие. Если эта функция возвращает значение true, на выноске отображается активное действие. Если она возвращает значение false, на выноске отображается текст действия, но само действие отключается.	function(calloutAction /*=CalloutAction*/) {...} null
isVisibleCallback	Определение функции обратного вызова, которая выполняется до отображения выноски и определяет, отображается ли текст действия. Если функция возвращает значение true, на выноске отображается текст действия. Если она возвращает значение false, текст действия скрывается. Другие действия смещаются влево, занимая место скрытого действия.	function(calloutAction /*=CalloutAction*/) {...} null
tooltip	Отображение текста, когда пользователь наводит указатель на текст действия выноски.	строка, NULL
disabledTooltip	Отображение текста при наведении указателя на текст отключенного действия выноски (если функция isEnabledCallback возвращает значение false).	string, null
menuEntries	Определение меню действий вместо отдельного действия.	[ CalloutActionMenuEntry, ...] null

В следующем разделе описано, как создать класс CalloutActionMenuEntry и добавить его в объект CalloutAction.

Добавление меню действий в выноску

Когда действие выноски содержит не одно действие, а меню, пользователь видит рядом с текстом действия выноски стрелку вниз, как показано ниже.

Меню, отображаемое в действии выноски, когда пользователь нажимает стрелку возле подписи действия

Вы можете создать любое число элементов меню и добавить их в действие выноски, передав их в массиве в виде значения элемента menuEntries объекта CalloutAction.

//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 принимает три параметра. Первые два из них являются обязательными. Третий необязателен, но может оказаться полезным, так как позволяет отобразить значок рядом с текстом.

• Передайте строку в качестве первого параметра, чтобы отобразить текстовую метку для каждого элемента меню.

• Передайте функцию в качестве второго параметра, чтобы определить действие, которое выполняется при щелчке пользователем текста элемента меню.

• Передайте строку, содержащую URL-адрес для значка, который вы хотите отобразить слева от текстовой метки.

Создание экземпляров выноски и управление ими с помощью CalloutManager

Одноэлементный объект CalloutManager хранит ссылки на все объекты Callout на странице. Он хранит все экземпляры выноски в массиве ассоциативных элементов, где значение ID каждого элемента управления — это ключ. Объект CalloutManager содержит методы, помогающие создавать хранимые им объекты Callout и управлять ими.

Метод	Назначение	Допустимые значения параметров
createNew()	Создание нового объекта Callout. Когда вы делаете это, CalloutManager добавляет запись для элемента управления в свой массив ассоциативных элементов, используя значение обязательного элемента ID в качестве ключа.	Массив ассоциативных элементов, назначающий значения каждому элементу. ID Члены и launchPoint являются обязательными.
createNewIfNecessary (members)	Создайте объект , Callout если объекту launchPoint , передаваемому в качестве параметра, еще не назначен элемент управления выноской.	Массив ассоциативных элементов, который назначает значения каждому используемому члену. ID Члены и launchPoint являются обязательными.
getFromLaunchPoint: function (/@type(HTMLElement)/launchPoint)	Получение объекта Callout, связанного с элементом launchPoint, указанным в функции. Этот метод выдает исключение, если с элементом launchPoint не связан объект Callout.	Нет параметров
getFromLaunchPointIfExists: function (/@type(HTMLElement)/launchPoint)	Получение объекта Callout, связанного с элементом launchPoint, указанным в функции. Этот метод возвращает значение NULL, если с элементом launchPoint не связан объект Callout.	Нет параметров
getFromCalloutDescendant: function (/@type(HTMLElement)/descendant)	Получение объекта Callout, связанного с HTML-элементом, указанным в функции. Этим элементом может быть любой потомок элемента выноски. Например, вы можете передать значение элемента contentElement, назначенное при создании объекта Callout. Этот метод выдает исключение, если с потомком не связан объект Callout.	Нет параметров
closeAll()	Закрывает все открытые Callout объекты. Этот метод возвращает значение true, если закрывает хотя бы одну выноску.	Нет параметров
isAtLeastOneCalloutOpen()	Проверяет наличие хотя бы одной открытой выноски.	Нет параметров

Размещение выноски на странице

Элемент	Назначение	Допустимые значения (полужирным шрифтом выделено значение по умолчанию)
boundingBox	Укажите ЭЛЕМЕНТ HTML, который будет служить эквивалентом offsetParent элемента управления выноски. По умолчанию используется offsetParent выноски, но вы можете использовать этот элемент для правильного расположения элемента управления. Выноска пытается расположиться так, чтобы находиться внутри этой рамки. Она изменяет направление, чтобы оставаться в этой рамке. (Вниз вместо вверх, а также вправо вместо влево в зависимости от ориентации указателя.)	Любой HTML-элемент, offsetParent HTML-элемента, содержащего выноску
positionAlgorithm	Переопределение стандартного алгоритма размещения выноски.	CalloutOptions.prototype.defaultPositionAlgorithm function(calloutPositioningProxy) { ... }

В следующем разделе описано, как использовать объект calloutPositioningProxy для создания алгоритма размещения выноски.

Создание алгоритмов размещения с помощью calloutPositioningProxy

Объект calloutPositioningProxy содержит методы и свойства, которые можно использовать для переопределения стандартной логики размещения выноски. Например, чтобы этот элемент все время отображался ниже и правее элемента launchPoint, напишите алгоритм размещения, похожий на такой:

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

Затем вы передаете эту функцию в качестве значения Callout члена объекта positionAlgorithm . Это можно сделать при создании Calloutили более поздней версии, задав значение .

callout.set({positionAlgorithm: alwaysGoDownAndRight});

Вы всегда можете взглянуть на логическую схему размещения по умолчанию, запустив консоль JavaScript браузера (например, инструменты разработчика по F12 в Internet Explorer).

CalloutOptions.prototype.positionAlgorithm.toString()

Эти методы можно использовать в объекте CalloutPositioningProxy для написания собственной логики позиционирования.

Метод	Описание
isCalloutTooFarTop()	Возвращает логическое значение.
isCalloutTooFarRight()	Возвращает логическое значение.
isCalloutTooFarBottom()	Возвращает логическое значение.
isCalloutTooFarLeft()	Возвращает логическое значение.
isCalloutLeftOfHardBoundingBox()	Возвращает логическое значение. Если значение — true, левая часть элемента управления выходит за границы элемента контейнера. Она не видна, и пользователь не может получить к ней доступ с помощью прокрутки.
isCalloutRightOfHardBoundingBox()	Возвращает логическое значение. Если значение — true, правая часть элемента управления выходит за границы элемента контейнера. Она не видна, и пользователь не может получить к ней доступ с помощью прокрутки.
isCalloutAboveHardBoundingBox()	Возвращает логическое значение. Если значение — true, верхняя часть элемента управления выходит за границы элемента контейнера. Она не видна, и пользователь не может получить к ней доступ с помощью прокрутки.
isCalloutBelowHardBoundingBox()	Возвращает логическое значение. Если значение — true, нижняя часть элемента управления выходит за границы элемента контейнера. Она не видна, и пользователь не может получить к ней доступ с помощью прокрутки.
isOrientedUp()	Возвращает логическое значение.
isOrientedDown()	Возвращает логическое значение.
isOrientedLeft()	Возвращает логическое значение.
isOrientedRight()	Возвращает логическое значение.
moveUpAndRight()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
moveUpAndLeft()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
moveDownAndRight()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
moveDownAndLeft()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
moveTowardsOppositeQuadrant()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
flipHorizontal()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
flipVertical()	Ничего не возвращает. Изменяет направление ориентации элемента управления.
numberOfEdgesCollidingWithBoundingBox()	Возвращает целое число от 0 до 4, обозначающее число краев, которыми выноска соприкасается с видимым ограничивающим прямоугольником. Например, если верхняя часть элемента управления обрезается верхним краем основной части документа после вызова метода moveUpAndRight(), метод numberOfEdgesCollidingWithBoundingBox() возвращает число, которое больше 1.

Этот алгоритм размещения вынуждает элемент управления располагаться над текстом или под ним. Свойство isRTLCalloutPositioningProxy объекта указывает, отображается ли в тексте язык справа налево. Проверяйте значение этого свойства, чтобы обеспечить правильное размещение элемента управления относительно текста на странице.

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, но при наличии конфликтов он использует стандартный алгоритм.

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

См. также

• Создание компонентов взаимодействия с пользователем в SharePoint
• Пример кода: использование представлений списков, выносок и диалоговых окон в надстройках с размещением в SharePoint
• Создание надстроек SharePoint с размещением в SharePoint