Создание надстроек для отечественного офисного пакета «МойОфис». Часть первая, вводная
Поскольку это первая моя публикация на Хабре, хотя как читатель я присутствую здесь уже довольно много лет, я скажу пару слов о себе. Вообще мой стаж как программиста, если учитывать и студенческие годы, когда я под руководством моего руководителя практики начал изучать С и С++ еще в 1992 году (откидываем программирование на калькуляторах, это всё таки баловство), уже более 30 лет. Много чем занимался в этой сфере, и что перепробовал по работе и чисто из интереса. Несколько более «известным» я стал с 2016 года в кругу тех, кто активно использует станки ЧПУ, как разработчик средств автоматизации (макросов) под CorelDraw. Тем не менее, сегодня речь пойдет о другой автоматизации — офисной. В силу своей работы на гос службе, мне приходилось заниматься внедрением и поддержкой документооборота, а также автоматизацией разных рутинных задач. Поэтому тема не сказать что для меня незнакомая.
Кратко, если кому интересно как я пришёл в итоге к теме статьи
Но про автоматизацию в наших офисных пакетах (конкретно «МойОфис») можно сказать, что не знал почти ничего до нынешней зимы. На меня вышли рекрутёры одного из крупных банков, с предложением пособеседоваться на открывшуюся ставку в группу перевода большого пакета макросов из «MS Office», в закупленный в рамках импортозамещения пакет «МойОфис» от «Новые облачные технологии». Я дал добро, так как на тот момент, хотя и работал в аналогичном русле по автоматизации на ещё одном «чудесном» отечественном пакете «Lotsia PDM Plus», но обстановка была такова, что в скором времени я мог оказаться без работы. Чтобы не быть совсем «бледным» перед потенциальным работодателем, я скачал лежащие в открытом доступе материалы по автоматизации в «МойОфис», посмотрел пару роликов с вэбинаров, и так же нашёл несколько статей с корпоративного блога, от создателей оного. Если вкратце, то с формулировкой «слишком опытный претендент» мне в итоге отказали, но материалы и сам офисный пакет остались. Далее, я всё-таки был уволен, так как проект по автоматизации в организации закрыли, в связи с приходом новых хозяев, которым было проще оставаться на таблицах Exсel, чем внедрять полноценный документооборот с DocumentsWorkflow (для тех кто не в курсе — это раздел электронного документооборота, в котором организовано движение электронных документов по выстроенным бизнес-цепочкам пользователей). Так у меня появилось снова свободное время, и я решил более подробно изучить «МойОфис» в плане автоматизации.
Итак, что на текущий момент есть в плане автоматизации в пакете «МойОфис». На самом деле, если сравнивать с возможностями даже почти 20 летней давности автоматизации на VBA в «MS Office», то не много. Языком для автоматизации выбран неплохой, в общем-то, хотя и мало для этого полезный, скриптовый язык Lua. Есть два типа поддерживаемых скриптов (поддержка есть только для текстового и табличного редакторов):
Макросы. Это простые именованные скрипты для выполнения локальных операций в документе, без возможности использовать дополнительные формы взаимодействия с пользователем и сам скрипт, как правило, внедрен как правило в сам документ.
Надстройки. Более сложный формат скриптов, который ставится (инсталлируется) уже в сам программный пакет. Поддерживает в зачаточном состоянии возможность использование форм для взаимодействия с пользователем, с базовым набором контролов взаимодействия пользователя с надстройкой.
«Заметьте, не я это предложил!» ©
Данное описание взято непосредственно из руководства от самих разработчиков, поэтом про «зачаточную возможность использования форм» они написали сами! Но я полностью с ними согласен, так как с этим там и правда плохо, но если постараться, то кое что можно предпринимать даже с этим!
Имеется простой редактор для написания и отладки скрипта макроса с расстановкой точек отладки и просмотра локальных переменных, но при этом нет даже автодополнения кода для API «МойОфис». То есть писать макросы в нем приходится, особенно по началу, с открытым справочником и поиском по нему требуемых данных об используемых в API функциях, что как по мне, в 2023 году, как-то не особо правильно! Ещё недавно добавили «импорт» в виде закомментированного исходного кода VBA макросов, при открытии документов Word или Excel. Ну, в общем, для простых переносов простых же макросов, пусть «со скрипом», но терпимо!
Встроенный в «МойОфис Текст» Lua редактор для создания простых макросов.Как раз с примером «импортированного» для дальнейшей переделки под Lua исходного кода сохранённого внутри вордовского документа простого макроса.
А вот для надстроек, которые в общем то и являются более менее адекватной заменой макросам, даже и этого «не завезли»!
Немного «гневной лирики от себя
Ничего кроме чувства глубокого удивления и досады, когда я узнал об этом, это у меня не возникло! Не, ну как так то?! В наше время, когда многие офисные работники настолько привыкли к написанной автоматизации под майкрософтовским офисом, что при предложении о переходе на любой другой офис, очень часто вторым вопросом такого работника, после: «А похоже ли будет на офис от майкрософта?», обычно следует: «А мои панельки (макросов) там будут?». А с панельками в новом офисе — сложно! Нет ни то чтобы визуального редактора форм, как у старших конкурентов, а и даже просто редактирование и отладка для надстроек не предусмотрена! Вот как все мягко говоря непросто, для тех, кто будет заниматься переносом макросов. Но как и принято в нашей среде программистов, если очень хочется, то что нибудь получится! Не думаю, что я один такой, кто нашёл обходные пути, но информации на этот счёт я не нашёл даже у разработчиков (даже в переписке с техподдержкой мне сказали, что пока всё только в планах).
Итак, что я предлагаю для решения проблем с отсутствием встроенной среды разработки, и создания более комфортной среды для тех коллег, кому придётся всё-таки заниматься внедрением надстроек под «МойОфис»?
Для разработки надстройки использовать стороннюю среду разработки (IDE) предназначенная для программирования под Lua.
Удалённая отладка надстроек средствами того же IDE.
Создание в IDE простого визуального редактора для проектирования форм для новых надстроек (пока не пробовал, но шанс есть!)
Создания аддона для встроенного в Microsoft Office IDE VBA, который бы позволил существенно упростить перенос уже разработанных макросов из «MS Office» под «МойОфис», за счёт хотя бы частичной трансляции дизайна форм и бизнес-логики
Таков мой план на текущий момент, хотя пункт 4 из него, всё таки это более дальняя перспектива, так как задача сама по себе, мягко говоря — нетривиальная! И сразу оговорюсь — решение найденное мной на текущий момент рассматривается под Windows. Собственно, если речь именно о переносе, то в любом случае актуально сперва всё сделать в винде, и потом перенести под Linux готовые надстройки. Поэтому, может быть, этим вопросом я займусь позже. И если всё пройдет успешно, опишу особенности, если таковые возникнут, уже отдельной статьёй.
Выбор IDE для написания надстроек
Мой выбор для проведения экспериментов пал на LuaRT версии 1.4. Данная среда разработки является форком другой, наверное самого известной среди Lua программистов всего мира ZeroBrane Studio (автор Paul Kulchenko). При этом LuaRT является, наверное самый развивающийся в мире Lua IDE, в которой реализовано много новых своих интересных «фич», таких как компиляция в exe файл, работа со своими модулями, в том числе и GUI. К тому же под она лицензией MIT, а значит позволяет безбоязненно использовать её возможности под выбранные цели.
LuaRT версии 1.4
Очень удобным плюсом такого выбора оказалось и то, что в LuaRT внедрёна возможность удаленной отладки, через модуль «mobdebug», который используется и для отладки Lua скриптов и в самом «МойОфис». Ещё из выявившихся в ходе исследований плюсов является возможность самостоятельно создать систему автодополнений для API «МойОфис», а значит существенно упростить себе жизнь при написании кода! О том, как это сделать я обязательно так же расскажу в следующей части.
Пишем простейшую надстройку
Основным справочным материалом послужила открытая информация от разработчиков офиса, посвященная написанию надстроек. Настоятельно рекомендую ознакомится хотя бы с вводной частью руководства по созданию надстроек, так как это хорошо упростит понимание того, что я делаю.
Итак, следуя упомянутому руководству, для начала работы нужно создать где-нибудь на диске папку со следующим набором подпапок:
Дополнительные структуры
Так же могут быть ещё две подпапки:
bin, в котором размещаются библиотеки и иные сторонние модули
i18n, в котором размещаются файлы, необходимые для локализации надстройки
Но на текущий момент, можно на них не обращать внимание.
Сразу опишу папку META-INF, так как она второстепенная, но обязательная. В ней должен быть всего лишь файл LICENSE с лицензионным соглашением, демонстрируемым при инсталляции надстройки. Содержимое лицензии на ваш вкус.
В корневой папке должен присутствовать файл регистрации с обязательным именем Package.lua, содержащий пары ключ-значение для конфигурации надстройки в приложении редакторов «МойОфис». Какие именно ключи и для чего можно узнать в соответствующем разделе руководства. Пока же приведу листинг из пробного файла с пояснением самых важных на текущий момент пунктов:
extensionName — Название надстройки. Отображается в меню Надстройки командного меню приложения в том случае, если надстройка установлена и включена
applicationId — Идентификатор приложения, с которым может работать надстройка
commandsProvider — Наименование файла сценария надстройки. Допустимо указание пути относительно домашнего каталога надстройки. Файл сценария под названием entryform.lua расположен в каталоге cmd домашней папки надстройки.
Полное содержимое файла Package.lua
local Package = {
vendor = "МойОфис",
description = "Это пример расширения для МойОфис",
extensionID = "ru.starfair.test",
extensionName = "Тестовое Расширение 1",
extensionVersion = {
major = 1,
minor = 1,
patch = 0,
build = "" },
applicationId = "MyOffice Text",
apiVersion = {
major = 1,
minor = 0 },
commandsProvider = "cmd/entryform.lua",
fallbackLanguage = 'en',
onLoad = "cmd/entryform-prep.lua",
onUnload = "cmd/entryform-prep.lua"
}
return PackageОстальные пункты не столь критичны на текущий момент. Далее, в каталоге cmd следует создать новый файл, с именем entryform.lua соответствующим имени указанном в commandsProvider файла Package.lua. Поскольку я хочу немного сэкономить место для этой статьи, содержимое я выберу сразу с созданием простой формы и пока не буду углубляться в сам код. Его я поясню в следующих статьях, или же можно понять, немного полистав руководство:
Actions = {}
--[[Обязательная команда, по которой устанавливается
набор доступных для данной надстроки команд в меню--]]
function Actions.getCommands()
return {
{
id = "DlgForm.ShowDlg",
menuItem = "Показать форму",
command = Actions.ShowControls
}
}
end
--Создадим набор из двух кнопок Ок и Cancel
Actions.dialogButtons = ui:DialogButtons{}
Actions.dialogButtons:addButton("OK", Forms.DialogButtonRole_Accept)
Actions.dialogButtons:addButton("Cancel", Forms.DialogButtonRole_Reject)
--Создадим метку в середине формы
Actions.lblMenu = ui:Label{
Text="Поздравляю с первой надстройкой!",
Color=Forms.Color(255,0,0),
}
Actions.lblMenu:setColor(Forms.Color(255,0,0))
Actions.lblMenu:setAlignment(Forms.Alignment_MiddleCenter)
--Создадим форму используя созданные ранее контролы
Actions.dlgBegin = ui:Dialog {
Title = "Демонстрация мультиформенного расширения",
Size = Forms.Size(600,300),
Buttons = Actions.dialogButtons,
--Позиционирование метки строго по центру формы
ui:Column {
ui:Row {Actions.lblMenu},
}
}
--Функция выводящая созданую форму
function Actions.ShowControls(context)
context.showDialog(Actions.dlgBegin)
end
return ActionsНа этой стадии, нужно быть очень внимательным, и поскольку отладка надстроек ещё не внедрена (этому я посвящу следующую статью), то любые ошибки придётся исправлять «вслепую», опираясь на скупые сообщения об ошибке (причем по одной за раз!), при попытке запустить инсталлированное расширение!
Итак, вводим данный листинг, сохраняем файл под названием entryform.lua в подпапку cmd (не обязательно именно такую, можно вообще в корне записать, но лучше не сваливать всё в одну кучу!). Дальше из под Проводника Windows выделяем всё содержимое корневой папки (помним что в папке META-INF, обязательно надо разместить файл с лицензией, иначе надстройка не инсталируется) и сохраняем в zip файл (правая кнопка мышки, в контекстном меню выбрать: Отправить/Сжатая ZIP папка). Далее надо просто сменить расширение получившегося .zip архива на расширение .mox. Как инсталлировать расширение, так же проще прочесть в руководстве по созданию надстроек от разработчиков. Если все прошло удачно, то в меню Надстройки программы «МойОфис Текст» появится созданная нами надстройка:
Так запускается наша первая надстройка в «МойОфис Текст»
И собственно, вот что должно появится, когда вы выбираете пункт меню »Показать форму»:
Внешний вид надстройки с формой
В общем-то, пока я ничего особо нового не сказал, чего-бы не было в руководстве по созданию надстроек. Но как обычно принято, для самых упорных дочитавших до этого момента, теперь я начинаю делиться более ценной информацией!
Итак, допустим собрали надстройку, инсталлировали и запустили.Первый же вопрос любого нормального программиста: «Каким образом теперь вносить изменения, и желательно без необходимости каждый раз создавать архив, инсталлировать по новой надстройку и т.д.?» Так вот, чтобы продолжить более комфортно заниматься расширением функционала, нужно найти место на жестком диске, где располагается инсталлированное расширение.И расположение не такое и очевидное! А именно вот по такому пути:
C:\Users\Your_User_Name\AppData\Local\New Cloud Technologies Ltd\MyOffice\MyOffice Text\Extensions
Это для «МойОфис Текст». Для редактора таблиц, MyOffice Text сменится на MyOffice Spreadsheet. Далее, после Extensions, следует специфичный Код_Надстройки, который генерируется для каждой надстройки отдельно. Если их много, то чему что соответствует, можно найти в реестре по следующим путям:
Для текстового редактора:
HKEY_CURRENT_USER\Software\MyOffice Standard\MyOffice Text\Plugins\Код_Надстройки
Для табличного:
HKEY_CURRENT_USER\Software\MyOffice Standard\MyOffice
Spreadsheet\Plugins\ Код_Надстройки
Теперь, закрываем в LuaRT всё что мы уже написали ранее, и вот таким образом указываем путь для проекта по выясненному как показано выше, абсолютному пути к инсталлированной надстройке:
Задание в LuaRT папки для текущего проекта
Вот таким образом, мы теперь будем продолжать работу с исходным кодом, но уже инсталлированного расширения в достаточно удобной для работы IDE! А значит — без необходимости заново каждый раз при изменениях упаковывать в архив и инсталлировать надстройку!
Но не забывайте периодически делать самостоятельно вручную обратные копии файлов, так как если вы каким то образом по новой инсталлируете надстройку, прежняя папка будет удалена со всем содержимым, и «новое» содержимое будет распаковано в папку под новым кодом, хотя формально и для той же самой надстройки. И даже если вы сделаете обновление (такая возможность в диспетчере надстроек так же имеется), то всё равно, содержимое будет перезаписано, а значит в следующий раз у вас получится откат на более раннюю версию.
На сегодня всё! В следующей части я расскажу о подключении удалённой отладки и создании файла для автодополнения для API «МойОфис» в LuaRT.
