Занятие 7:
Создание плагина
На занятии вы узнаете:
Отличия плагинов от макросов
Отличиями плагинов от макросов в составе редакторов Р7 являются:
- Независимость плагина от документа.
- Возможность иметь интерфейс с пользователем в виде встроенного или внешнего окна плагина (в том числе и несколько).
- Возможность подключать большое количество внешних скриптов .
- Более широкие возможности решаемых задач, не ограниченные только редактированием документа, но и разными расширениями исходных возможностей редакторов.
- Разработка возможна только во внешних редакторах кода.
Состав плагина
На момент инсталляции в редактор, файл плагина должен представлять собой zip архив, с расширением plugin. Минимальный состав такого архива должен включать следующие файлы:
- 1. Конфигурационный файл config.json (обязательно с таким названием!), который содержит полное описание инсталлируемого плагина. В нем в специальном формате (json), описываются в установленных по спецификации разработчика параметры плагина, такие как название, способ эксплуатации и т.д. Более подробную информацию можно найти на сайте разработчика. Пример такого файла будет показан ниже, в разделе написания простого плагина.
- 2. Файл html, который служит либо для описания интерфейса плагина, либо для загрузки скрипта с описанием javascript кода. Наименование данного файла должно соответствовать тому, что указано в параметре «url» файла config.json Обычно, это index.html Пример такого файла будет показан ниже, в разделе написания простого плагина.
- 3. Теоретически без файла about.html можно обойтись, но на практике лучше сделать отдельный файл, содержащий javascript код. В таком случае, путь к этому файлу должен быть включён в разделе <header> html файла, указанного в пункте 2. Код должен быть отформатирован определённым образом, и содержать функцию «точки инициализации плагина» window.Asc.plugin.init (), которую ищет редактор в момент запуска плагина. Можно обойтись и без неё, но в таком случае редактор при каждом запуске будет выдавать ошибку в консоли отладки.
- 4. Так же желательно иметь специальную папку «/translations», содержащую минимум два файла с переводами интерфейса плагина на разные языки. Сам список языков расположен в файле langs.json, а сами переводы интерфейсов в соответствующих файлах с расширением языка (например, для русского: ru-RU.json). Его отсутствие так же приводит к записям отладки в консоли отладки. В рамках учебного плагина, обойдёмся без перевода и этой папки!
- 5. Прочие файлы можно располагать в любую из вложенных папок с неограниченным числом вложений. Это могут быть другие скриптовые файлы, файлы ресурсов и т.п.
Основные этапы разработки плагина:
- Создать папки с перечисленными выше файлами.
- Заполнить требуемые параметры будущего плагина.
- В файле config.json, в переменной "guid", следует любыми доступными методами (например, с помощью онлайн генератора) сгенерировать статистически уникальный 128-битный идентификатор GUID (Globally Unique Identifier), по которому плагины будут различаться между собой.
- В переменной "name", следует указать имя плагина, под которым он будет показываться после инсталляции в рибонбаре редактора.
- Описание других переменных можно найти на сайте.
- В html файле можно указать минимальный набор разделов для файла разметки. А именно разделы:
<head>
<body>
В разделе head (тэг <script>) перечислить пути к файлам с расширением js, содержащим скрипты. Можно сами скрипты создать там же без создания внешних файлов. Если в плагине нет внешнего оформления, то в разделе body можно больше ничего не делать. - Создать файл со скриптом (например, code.js), и в нем записать минимальный скрипт:
(function (window, undefined) {
window.Asc.plugin.init = function () {
}, true);
};
window.Asc.plugin.button = function (id) {
};
})(window, undefined); - Запаковать все файлы в один zip архив и сменить его расширение с .zip на .plugin.
- Проинсталлировать данный плагин, согласно процедуре описанной в руководстве к редакторам (OnlyOffice) или здесь (к Р7 на русском).
- После инсталляции в папке ОС Windows C:\Users\User_Name\AppData\Local\R7-Office\Editors\data\sdkjs-plugins\[guid_number] (в ОС Linux: /home/user/.local/share/r7-office/editors/sdkjs-plugins/[guid_number]) будут располагаться файлы, созданные и упакованные ранее в архив. Эти файлы можно редактировать и изменять во внешнем редакторе, при этом не потребуется последующая замена файлов или переинсталляция плагина.
Создание простого плагина по шагам.
На сайте разработчиков имеется небольшой раздел, который показывает примеры разработки плагинов. Более информативным для разработчиков является раздел с плагинами на GitHub. В нем путем разбора можно посмотреть разные примеры создания плагинов. Поскольку данные примеры обычно являются довольно сложными, сделаем свой простой рабочий проект. Создадим плагин, который встроим в редактор Р7. Он будет делать простое действие - по нажатию на кнопку изменит цвет в ячейке, которую выбрал пользователь.
Шаг 1. Создадим конфигурационный файл config.json.
Пример файла:
{
"name" : "Плагин окрашивания ячейки",
"guid" : "asc.{6401CE6B-3E19-45E1-9352-BFCF41989AA5}",
"version": "0.0.1",
"variations" : [
{
"description" : "Учебный плагин",
"url" : "index.html",
"icons": [ "logo(64х64).png" ],
"isViewer" : true,
"EditorsSupport" : ["cell"],
"isVisual" : true,
"isModal" : false,
"isInsideMode" : true,
"initDataType" : "",
"initData" : "",
"isUpdateOleOnResize" : false,
"buttons" : []
}
]
}
Шаг 2. Сгенерируем GUID.
Любым удобным способом сгенерируем GUID и запишем его в переменную "guid", например "6401CE6B-3E19-45E1-9352-BFCF41989AA5".
Формат записи должен быть как в примере выше: "asc.{6401CE6B-3E19-45E1-9352-BFCF41989AA5}".
Сайт для онлайн-создания GUID: https://www.guidgenerator.com/
Формат записи должен быть как в примере выше: "asc.{6401CE6B-3E19-45E1-9352-BFCF41989AA5}".
Сайт для онлайн-создания GUID: https://www.guidgenerator.com/
Шаг 3. Создадим файл разметки index.html.
В файле разместим только одну кнопку с id="btn-1", помещенную в таблицу для простоты позиционирования.
Пример файла:
Пример файла:
<!DOCTYPE html>
<html lang="ru">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<style type="text/css">
html, body {
margin: 0px;
padding: 0px;
/* overflow: hidden; */
width:100%;
height:100%;
}
</style>
<script type="text/javascript" src="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.js"></script>
<script type="text/javascript" src="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins-ui.js"></script>
<link rel="stylesheet" href="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.css">
<script type="text/javascript" src="code.js"></script>
</head>
<body>
<table style="width: 100%;">
<tr><td>
<label class="header">Сменить цвет ячейки</label>
</td></tr>
<tr><td>
<button id="btn-1" style="width:75px;">Сменить цвет</button>
</td></tr>
</table>
</body>
</html>
Шаг 4. Создадим файл скрипта.
Создадим любым удобным способом здесь же в папке файл «code.js» и внесём в него следующий код:
(function(window, undefined){
//Функция API вызываемая редактором при инициализации плагина пользователем
window.Asc.plugin.init = function()
{
//Средствами DOM назначим функцию changeColor на обработку нажатия на кнопку
document.getElementById('btn-1').addEventListener('click', changeColor);
};
window.Asc.plugin.button = function(id)
{
this.executeCommand("close", "");
};
//Сменить цвет ячейки (ячеек), которую перед вызовом функции выделил пользователь
function changeColor(){
//Создание "песочницы" js, в поторой происходит работа с документом
window.Asc.plugin.callCommand(function() {
let oWorksheet =Api.GetActiveSheet();//Получить активный лист
let newColor=Api.CreateColorFromRGB(240, 240, 240);//Создать серый цвет
if(oWorksheet!=undefined){
let oActiveCell = oWorksheet.GetActiveCell();//Получить активную ячейку
if(oActiveCell!=undefined){//Залить активную ячейку, если она существует
oActiveCell.SetFillColor(newColor);
}
}
}, undefined,true); //true нужно чтобы редактор перерисовал лист!
};
})(window, undefined);
Шаг 5. Добавим файл иконки плагина.
Создадим или найдём в сети файл логотипа, по которому пользователь будет искать плагин в меню редактора. Относительный путь к этому файлу, его имя и расширение (тип) должны совпадать с тем, что указаны в переменной «icons» (например, "logo(64х64).png") в файле конфигурации config.json.
Папка с нашими файлами в Проводнике Windows должна выглядеть вот так:
Шаг 6. Сжимаем файлы плагина в zip-файл и изменяем расширение.
Выделим все файлы в папке с плагином, и с помощью контекстного меню Проводника упакуем эти файлы в zip-архив. Название файла с архивом можно сделать любым:
Сменим расширение архива с .zip на .plugin. Поместим получившийся файл в любую папку.
Шаг 7. Установим плагин. Произведем тестовый запуск.
Процедура инсталляции описана в руководстве на сайте разработчиков по ссылке. Если всё сделано правильно, то в редакторе Р7-Офис на вкладке «Плагины» появится созданный плагин.
Произведем тестовый запуск, нажав на кнопку плагина. В левой части редактора должна появиться форма нашего плагина с единственной кнопкой «Сменить цвет»:
Произведем тестовый запуск, нажав на кнопку плагина. В левой части редактора должна появиться форма нашего плагина с единственной кнопкой «Сменить цвет»:
По нажатию на кнопку «Сменить цвет» активная ячейка (на рисунке D6) окрашивается в серый цвет:
Шаг 8. Запуск консоли отладки редактора Р7.
Отладке было посвящено занятие 3. Повторим вкратце о включении и просмотре плагинов в этом режиме.
Чтобы получить возможность запуска с консолью отладки, редактор Р7 нужно запускать со специальным ключом «--ascdesktop-support-debug-info». В этом случае после запуска плагина, щелкнув по любому свободному месту в области плагина правой кнопкой мышки, можно из контекстного меню вызвать отладочную консоль Chromium (либо нажать клавишу F1):
Чтобы получить возможность запуска с консолью отладки, редактор Р7 нужно запускать со специальным ключом «--ascdesktop-support-debug-info». В этом случае после запуска плагина, щелкнув по любому свободному месту в области плагина правой кнопкой мышки, можно из контекстного меню вызвать отладочную консоль Chromium (либо нажать клавишу F1):
Чтобы посмотреть код, и расставить точки отладки, нужно перейти во вкладку «Sources».
В левой части дерева web приложения Р7 найдем ветку «frameEditor(…)» редактора, в которую загружен наш плагин. Далее найдем подветку «pluginFrameEditor(…)» в которую загружен html файл, отвечающий за внешний вид плагина. В нём в ветке «file:» найдем подгружаемый через <script> наш скриптовый файл «code.js». После его выбора он подгружается в консоль отладки. В этом окне мы можем уже работать над отладкой. При остановках кода, можем посмотреть значения различных переменных.
Во вкладке «Console»отладчика можно посмотреть сообщения об ошибках и различные предупреждения, которые появляются при работе плагина и самого редактора .
Для тех, кто ведёт разработку и отладку в Linux, более подробно о процессе отладки можно прочитать на сайте разработчика.
Шаг 9. Дальнейшая работа над плагином без переустановки.
Дальнейшая работа над плагином может продолжаться и в исходной папке проекта, но мы рекомендуем вносить изменения уже в установленные в редактор файлы плагина. В Windows путь к такой папке будет такой:
C:\Users\User_Name\AppData\Local\R7-Office\Editors\data\sdkjs-plugins\GUID_PLUGIN
Отмеченные серым участки (имя пользователя, под которым происходила инсталляция, и GUID плагина, использовавшийся на шаге 2), надо заменить на свои. В указанной папке будут располагаться все инсталлированные файлы плагина. Можно выбрать эту папку при работе в вашем редакторе, и вносимые изменения в код после сохранения файла сразу оказываются в плагине без необходимости повторной упаковки и установки его (с предварительным удалением!) в редакторе Р7.
C:\Users\User_Name\AppData\Local\R7-Office\Editors\data\sdkjs-plugins\GUID_PLUGIN
Отмеченные серым участки (имя пользователя, под которым происходила инсталляция, и GUID плагина, использовавшийся на шаге 2), надо заменить на свои. В указанной папке будут располагаться все инсталлированные файлы плагина. Можно выбрать эту папку при работе в вашем редакторе, и вносимые изменения в код после сохранения файла сразу оказываются в плагине без необходимости повторной упаковки и установки его (с предварительным удалением!) в редакторе Р7.
Внимание: при внесении изменений в базовую троицу файлов плагина (их может быть и большее число - зависит от проекта), для применения этих изменений обязательно понадобится выход из плагина и его повторная загрузка!
Выводы
В этом курсе не предусматривается глубокое изучение API редактора и плагинов в Р7, а лишь знакомство с основами автоматизации работы в Р7-Офис. Сама по себе процедура создания и запуска плагинов не столь уж и сложна.
Намного сложнее миграция кода из макросов MS Office в плагины Р7! Это довольно трудный и кропотливый процесс, требующий хорошего знания, как языка VBA для MS Office и объектной модели документов, так и хорошего опыта во frontend разработке на языке JavaScript и глубокого погружения в объектную модель Р7. Это возможно, так как типовые алгоритмы работы с документом в Р7 могут быть чаще всего перенесены из имеющихся макросов в MS Office.
В рамках данного курса эти различия не рассматриваются и требуют либо более серьёзной самостоятельной проработки, либо изучения этих особенностей в рамках углублённого курса по написанию плагинов Р7 при миграции из макросов MS Office.
Намного сложнее миграция кода из макросов MS Office в плагины Р7! Это довольно трудный и кропотливый процесс, требующий хорошего знания, как языка VBA для MS Office и объектной модели документов, так и хорошего опыта во frontend разработке на языке JavaScript и глубокого погружения в объектную модель Р7. Это возможно, так как типовые алгоритмы работы с документом в Р7 могут быть чаще всего перенесены из имеющихся макросов в MS Office.
В рамках данного курса эти различия не рассматриваются и требуют либо более серьёзной самостоятельной проработки, либо изучения этих особенностей в рамках углублённого курса по написанию плагинов Р7 при миграции из макросов MS Office.