Документация

Разработка модулей

Расширяйте IWE Code внешними модулями. Упакуйте программу, опишите панель в JSON и установите модуль из файла.

Внешний модуль — отдельная программа, которую IWE Code запускает и с которой общается по простому JSON-протоколу. Напишите её на любом языке, приложите бинарники для нужных платформ и установите пакет без пересборки приложения.

Как это работает

  • Модуль работает отдельным процессом. IWE Code запускает его при включении модуля и останавливает при отключении или удалении.
  • Приложение и модуль обмениваются JSON-документами по одному на строку через стандартные потоки процесса.
  • Модуль описывает панель декларативным деревом виджетов. IWE Code рисует панель собственными нативными компонентами.
  • Модуль сам локализует текст своей панели. Язык интерфейса приложение передаёт при запуске.

Манифест

В каждом пакете есть файл manifest.json с описанием модуля.

id
Уникальный идентификатор в нижнем регистре через дефис, например hello-module.
name, description
Локализованные тексты. Английский обязателен; русский и испанский необязательны.
version
Семантическая версия модуля. Обновления должны её увеличивать.
api
Версия протокола. Текущая версия — 1.
minAppVersion
Минимальная версия приложения, которую поддерживает модуль.
entry
Имя исполняемого файла для каждой платформы, например macos-aarch64.
permissions
Объявленный доступ: filesystem-read, filesystem-write, network, process.
placement
Зона рабочей области для панели: header, top, left, right или bottom.
{
  "id": "hello-module",
  "name": { "en": "Hello module", "ru": "Модуль приветствия" },
  "description": { "en": "Shows a friendly panel." },
  "version": "1.0.0",
  "api": 1,
  "minAppVersion": "1.0.8",
  "entry": { "macos-aarch64": "hello-module", "linux-x86_64": "hello-module" },
  "permissions": [],
  "placement": "bottom"
}

Структура пакета

Пакет — tar-архив с gzip-сжатием и расширением .iwe-module.

hello-module/
├── manifest.json
├── manifest.sig
└── binaries/
    ├── macos-aarch64/hello-module
    └── linux-x86_64/hello-module

Сообщения протокола

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

{"type":"initialize","api":1,"appVersion":"1.0.8","language":"en","installPath":"/…/modules/hello-module/1.0.0"}
{"type":"panel","content":{"type":"column","children":[{"type":"text","content":"Hello!"}]}}
{"type":"event","id":"click","action":{"type":"click"}}
{"type":"notify","level":"info","message":"Done"}
{"type":"shutdown"}

От IWE Code к модулю

initialize
Отправляется один раз при запуске. Сообщает версию протокола, версию приложения, язык интерфейса и путь установки.
event
Сообщает о действии в виджете: нажатие, переключение или изменение текста.
shutdown
Просит модуль завершить работу.

От модуля к IWE Code

panel
Заменяет содержимое панели новым деревом виджетов.
notify
Показывает короткое сообщение уровня info, warning или error.

Виджеты панели

Панель — дерево простых узлов. У каждого узла есть тип и собственные поля.

column, row
Располагают дочерние узлы по вертикали или горизонтали с настраиваемым отступом.
text
Текст со стилем body, heading, caption, muted или danger.
button
Кнопка с подписью, сообщающая о нажатии. Стили: primary, secondary, danger.
text-input
Однострочное поле, сообщающее об изменении значения.
checkbox, toggle
Переключатели, сообщающие новое состояние.
progress
Индикатор прогресса от 0 до 1.
separator, scroll, spacer
Вспомогательные узлы: разделитель, прокрутка и заполнитель.

Права доступа

Манифест объявляет нужный модулю доступ. IWE Code показывает список перед установкой и просит подтверждение. Модули работают с правами вашего пользователя; IWE Code их не изолирует. Устанавливайте только те модули, которым доверяете.

filesystem-read
Читать файлы на компьютере.
filesystem-write
Изменять файлы на компьютере.
network
Работать с сетью.
process
Запускать другие программы.

Сборка пакета

Соберите референсный модуль, подготовьте каталог пакета и сожмите его. Пример — полный модуль на Rust, который можно скопировать.

cargo build --release --example hello-module
mkdir -p hello-module/binaries/macos-aarch64
cp target/release/examples/hello-module hello-module/binaries/macos-aarch64/
cp manifest.json hello-module/
tar -czf hello-module.iwe-module -C hello-module manifest.json binaries

Подпись пакета

IWE Code проверяет подпись пакета и контрольные суммы файлов. Приложение отклоняет пакеты без подписи или с изменениями.

Скрипту подписи нужен ключ Ed25519 сопровождающего проекта. Подробности есть в справочнике по пакетам.

python3 .github/scripts/sign-module.py hello-module.iwe-module

Установка

Откройте «Настройки → Модули» в IWE Code, выберите «Установить из файла…», проверьте запрошенный доступ и подтвердите. Обновления ставятся так же с более высокой версией.

Референсный модуль

В репозитории есть рабочий пример в каталоге examples/hello-module.

Подробный справочник