•  
    •  
Заказать разработку
Методы и функции API Р7-Офис
Углубленное изучение АПИ плагинов Р7-Офис
Занятие 1
Создание интерфейса плагинов. Часть 1.
Обработка базовых событий с помощью jQuery
Введение
При создании плагинов для редактора Р7, архитектура плагина обычно делится на две основные части: обработку данных и разработку графического интерфейса пользователя. Первая часть включает работу в виртуальной песочнице с использованием API редактора. Вторая часть - организация графического интерфейса, который использует стандартное front-end API HTML-страницы, обеспечивающее доступ к встроенным контролам с помощью JavaScript.

Хотя можно использовать любые библиотеки или фреймворки, такие как React или Angular, их применение может усложнить и замедлить работу плагина. В большинстве случаев, для задач, стоящих перед плагинами, нет необходимости в крупных фреймворках. Мы будем рассматривать использование легкой и быстрой библиотеки jQuery (версия 3.7).

Краткая справка о jQuery
jQuery — это бесплатная библиотека JavaScript, созданная Джоном Резигом в 2006 году, разработанная для упрощения работы с HTML на стороне клиента. jQuery делает такие вещи, как обход и обработка HTML-документов, обработка событий, анимации и AJAX, значительно проще благодаря простому API, совместимому с разными браузерами.

С помощью jQuery можно легко извлекать элементы из HTML-страниц и выполнять операции с ними. Знание селекторов CSS полезно при работе с jQuery, так как они помогают упрощать JavaScript-код.

Библиотека работает со всеми основными браузерами. Она может расширять свой функционал с помощью своих плагинов (будут рассмотрены вкратце в отдельном уроке).

Библиотека облегчает и обогащает возможности работы с GUI пользователя, такими как:
обработка событий действий пользователя
динамическое изменение внешнего вида, вплоть до добавления и удаления разделов интерфейса
простой и удобный поиск различных частей DOM модели, без необходимости организации циклов с проверками
работа сразу со многими элементами по одному шаблону действий
дополнительные сервисные функции
подключение дополнительных плагинов к jQuery для работы со сложными объектами (деревья, календари и т.д.)


Подключение jQuery в плагин
Чтобы подключить jQuery в плагине, добавьте следующий тег в раздел <head> HTML-документа:

<script src="scripts/jquery-3.7.0.min.js"></script>

Файл можно скачать и разместить в каталоге с кодом плагина, или использовать внешние ссылки на плагин через CDN (Content Delivery Network - сеть доставки контента):

<script src="//code.jquery.com/jquery-3.7.0.min.js"></script>

После загрузки страницы HTML, библиотека jQuery становится доступной через объект jQuery или префикс $.
Селекторы
Одним из главных преимуществ jQuery является возможность легко получать доступ к элементам DOM. Селекторы могут быть идентификаторами (#), классами (.) или атрибутами. Например, $("#id_button") находит элемент с id id_button.
Основные элементы управления и работа с ними
jQuery позволяет работать с различными элементами управления, такими как кнопки, текстовые поля, флажки, переключатели, списки и т.д.

Ниже приведена таблица элементов управления (контролов) с соответствующими тегами HTML и стандартными параметрами.
Контролы в документе HTML
Поле ввода input
Input - элемент управления html-формы, который отображает объект, указанный в атрибуте type, например: button (кнопка), checkbox (флажок), color (палитра), date (календарь), text (текстовое поле) и другие. По умолчанию отображается текстовое поле.

Основные типы (атрибут type=””) для input рассмотрены в разделе Типы элемента <input>.

Примеры использования


text
<label>Элемент input по умолчанию:</label> <input><br><br>
<label>Элемент input с type="text":</label> <input type="text"><br><br>

Результат:
submit
<input type="submit" value="Отправить">

Результат:
radio
<p>Каким браузером в основном пользуетесь:<Br>
  <input type="radio" name="browser" value="ie"> Internet Explorer<Br>
<input type="radio" name="browser" value="opera"> Opera<Br>
<input type="radio" name="browser" value="firefox" checked> Firefox<Br>
</p>

Результат:
reset
<p><input type="reset" value="Очистить"></p>

Результат:
Многострочное поле ввода TextArea
Textarea - это элемент управления html-формы, представляющий из себя многострочное текстовое поле. Атрибуты rows и cols задают размеры поля (высоту и ширину) в символах.

Пример:
<textarea rows="7" cols="40">Материал из Википедии: «Дарвинизм — по имени английского натуралиста Чарльза Дарвина — в узком смысле — направление эволюционной мысли, приверженцы которого согласны с основными идеями Дарвина в вопросе эволюции (современная их форма, порой с существенным переосмыслением некоторых аспектов представлена в синтетической теории эволюции), согласно которым главным (хотя и не единственным) фактором эволюции является естественный отбор.»</textarea>

Результат:
Кнопка Button
Button появился в html позже элемента <input> и его синтаксис отличается от кнопки input — название кнопки пишется между открывающим и закрывающим тегами <button>Имя кнопки</button>. Чтобы в элементе <button> работал атрибут onclick необходимо указать атрибут type="button".

Пример:
<label>Элемент button:</label> <button type="button" >Нажмите меня!</button>

Результат:

Селектор Radio
Radio – тип тега Input для выбора одного варианта из предложенных. Все элементы одного переключателя должны иметь единый атрибут name.

Пример:
<label><B>Выберите слово из списка:</B></label>
<p><input type="radio" name="rad1" value="Бокал"> Бокал<p>
<p><input type="radio" name="rad1" value="Ведро"> Ведро<p>
<p><input type="radio" name="rad1" value="Кубик"> Кубик<p>
<p><input type="radio" name="rad1" value="Лунка" checked> Лунка<p>
<p><input type="radio" name="rad1" value="Ступа"> Ступа<p>

С помощью атрибута checked элементом блока переключателей по умолчанию выбран элемент с value «Лунка».

Результат:
Селектор Checkbox
Checkbox – тип тега Input для выбора нескольких элементов из предложенных.

Пример:
<p>В какие годы произошли Революции в России?</p>
<p><input type="checkbox" name="a" value="1417"> 1417</p>
<p><input type="checkbox" name="a" value="1917" checked>1917</p>
<p><input type="checkbox" name="a" value="1905" checked>1905</p>
<p><input type="checkbox" name="a" value="1934"> 1934</p>
<p><input type="checkbox" name="a" value="2024"> 2024</p>
<p><input type="submit" value="Отправить"></p>

Результат:
Раскрывающийся список Drop Down List
Select - тег элемента управления html-формы раскрывающегося списка.
Элементы списка перечисляются внутри тэгов <option>, располагающихся внутри тега <select>.


Пример 1:
<label>Выберите фрукт:</label>
<select>
<option>Апельсин</option>
<option>Гранат</option>
<option>Груша</option>
<option>Мандарин</option>
<option>Яблоко</option>
</select>

Результат:

Пример 2:
С помощью атрибута selected элементом блока переключателей по умолчанию выбран элемент Мандарин.
<label>Выберите фрукт:</label>
<select>
<option>Апельсин</option>
<option>Гранат</option>
<option>Груша</option>
<option selected>Мандарин</option>
<option>Яблоко</option>
</select>

Результат:
Работа с базовыми контролами в jQuery
Базовые понятия о событиях в модели DOM HTML страниц
Основой взаимодействия визуальных компонентов на странице (контролов и элементов разметки, таких как заголовки и ссылки) с пользователем является модель событий. Каждый элемент может получать от браузера оповещения (события). Основные события взаимодействия и ссылки на их документацию приведены в приложении в разделе "События".

Подключая к этим событиям свои обработчики, можно программировать динамическую реакцию на них. Например, изменять оформление страницы, выполнять вычисления, рисовать на канвасе (canvas) и так далее, без необходимости обращения к серверу и перезагрузки всей страницы или её части (в случае использования iframe). Именно потребность в такой локальной обработке привела к появлению языка JavaScript.
Исторический способ подключения обработчиков
Ранее обработчики событий внедрялись прямо в HTML-код, например:

<button onclick="createParagraph()">Нажми на меня!</button>

Здесь createParagraph() — это функция на JavaScript, описанная внутри тегов <script>. Такой подход загрязняет HTML-код, усложняет его поддержку и масштабирование, особенно при работе с большим числом однотипных элементов.
Современный подход
Современный подход предполагает разделение HTML+CSS и JavaScript-кода. Обработчики событий добавляются через JavaScript, например:

const buttons = document.querySelectorAll("button");
for (let i = 0; i < buttons.length; i++) {
buttons[i].addEventListener("click", createParagraph);
}
Использование jQuery для упрощения работы с событиями
jQuery упрощает этот процесс, позволяя значительно сократить код:

$("button").on("click", createParagraph);
Или даже так:

$("button").click(createParagraph);

Благодаря удобству использования и читаемости, мы будем использовать jQuery для взаимодействия пользователя с плагином в Р7. Мы рассмотрим не все возможные события, а только те, которые скорее всего понадобятся при разработке простых плагинов.
Событие «click».
Нажатие мышкой (или клавиатурное сочетание) на элементе управления (контроле).
Данное событие происходит, когда пользователь нажимает на контрол, используя мышь или клавиатурные сочетания (шорткаты). Для поиска контрола в DOM можно использовать различные методы:

По типу элемента: Возвращает массив элементов указанного типа.
По классу: Также возвращает массив элементов с указанным классом.
По идентификатору или фильтру: Возвращает либо массив, либо одиночное значение, в зависимости от результата поиска.

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

В чистом JavaScript имеются три способа добавления:

1.
var button = document. getElementById(("#id_button");//Найти элемент по его id
button.addEventListener("click", myFunction);//Добавить обработчик myFunction() на событие click

2.
button.addEventListener("click", function(){/*здесь тело inline встраиваемой функцииобработчика*/});

3.
button.onclick= function(){/*здесь тело inline встраиваемой функции обработчика*/ };
В JQuery четыре способа решают ту же задачу:

1.
$("#id_button").on(“click”, myFunction);

2.
$("#id_button").click(myFunction);

3. $("#id_button").click(function(){/*здесь тело inline встраиваемой функции обработчика*/});

4.Для Checkbox можно использовать такой способ.
$("#id_chbx").dblclick(function(){
let check=$(this).prop("checked");||true – если чекбокс выбран
});


Событие «dblclick».
Двойное нажатие мышкой на контрол.
Обычно в этом случае не предполагается клавиатурное сочетание, а только реакция на двойной щелчок левой кнопкой мышки.
Способы добавления обработчика «dblclick».

В чистом JavaScript имеются три способа добавления:

1.
button.addEventListener("dblclick", myFunction);//Добавить обработчик myFunction() на событие dblclick

2.
button.addEventListener("dblclick", function(){/*здесь тело inline встраиваемой функции обработчика*/});

3.
button.ondblclick= function(){/*здесь тело inline встраиваемой функции обработчика*/ };
В JQuery три способа решают ту же задачу:

1.
$("#id_button").on(“dblclick”, myFunction);

2.
$("#id_button").dblclick(myFunction);

3.
$("#id_button").dblclick(function(){/*здесь тело inline встраиваемой функции обработчика*/});
Событие «change».
Изменение значения контрола.
Событие изменения вызывается для элементов <input>, <select>, <textarea>, когда пользователь изменяет значение элемента. В отличие от события ввода, событие изменения не обязательно вызывается при каждом изменении значения элемента.

В зависимости от типа изменяемого элемента и способа взаимодействия пользователя событие изменения срабатывает в разные моменты:

Когда элемент <input type="checkbox"> устанавливается или снимается с флажка (по щелку мышью или по клавиатурной команде);

Когда элемент <input type="radio"> устанавливается (но не когда флажок снимается);

Когда пользователь явно фиксирует изменение (например, выбирая значение из раскрывающегося списка <select> щелчком мыши;

Когда пользователь выбирает дату в средстве выбора даты для <input type="date"> или когда выбирает файл в средстве выбора файла для <input type="file">;

Когда элемент теряет фокус после изменения его значения. Это актуально для элементов, в которых пользователь вводит текст, а не выбирает его, например <textarea> или элемента <input> типа текст, поиск, URL-адрес, телефон, электронная почта, пароль.
Способы добавления обработчика события «change»

В чистом JavaScript имеются три способа добавления:

1.
var select = document. getElementById(("#id_select");//Найти элемент по его id
select.addEventListener("change", myFunction);//Добавить обработчик myFunction() на событие change

2.
var select = document. getElementById(("#id_select");//Найти элемент по его id
select.addEventListener("change ", function(event){/*здесь тело inline встраиваемой функции обработчика*/
log.textContent = event.target.value;
});

3.
var select = document. getElementById(("#id_select");//Найти элемент по его id
select.onchange= function(event){/*здесь тело inline функции обработчика*/ };
В JQuery три способа решают ту же задачу:

1.
$("# id_select ").on(“change”, myFunction);

2.
$("# id_select "). change (myFunction);

3.
$("# id_select "). change (function(event){/*здесь тело inline встраиваемой функции обработчика*/
let value = $(this).val();//Узнать значение выбора в селекторе
});
Повышение надёжности отслеживания ввода для текстовых полей
Для отслеживания изменения значения в текстовых полях более надежным подходом будет использование обработчиков сразу по нескольким событиям:
let changeValue;
$("# id_select ").on("change input selectionchange", function() {
changeValue=$(this).val();
});
Другие полезные события
Работа с другими событиями осуществляется аналогично рассмотренным выше примерам. Найти описание событий несложно, главное — понять принцип их работы. У всех событий могут быть свои нюансы. Некоторые события не передают данных внутрь обработчиков, а некоторые могут это делать. Не всегда очевидно, какие действия вызываются в каком случае и т.д. Поэтому только с опытом использования DOM модели приходит интуитивное понимание того, как использовать те или иные события и в каких случаях.

К примеру, часто могут оказаться полезными события получения или потери контролом «фокуса» ввода (focus и blur). Иногда использование этих событий мало что дает, так как они иной раз происходят неочевидным образом. Необходимые нам изменения могут не отслеживаться, потому что находятся в последовательности вызовов внутренних событий после или до ожидаемых нами, и тогда приходится использовать предшествующие им события: например, использование пользователем мышки (mouseleave, mouseenter) или клавиатуры (keyup, keypress).

Почти всегда можно найти требуемое событие, но необходимо глубокое понимание механизмов событий в документе DOM, иногда долгая и упорная отладка для выяснения причин «странного» поведения, отличного от ожидаемого. Опыт постепенно расставляет всё по своим местам, и дальнейшее программирование становится более простым.
Приложение 1
Типы элемента <input> в html
Приложение 2
Основные атрибуты элемента управления <input> в html
Приложение 3
События
События работы с буфером обмена
События клавиатуры
Общий список событий для элементов