Настройки плагина

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

Способ	Когда
Поля в манифесте	Несколько параметров кнопки: текст, число, список, переключатель, цвет
Страница кнопки на HTML	Своя вёрстка, статус, подсказки, нестандартные элементы
Окно плагина на HTML	Настройки всего плагина: подключение, аккаунт, журнал

Поля в манифесте

Приложение рисует форму само, в своём оформлении. Плагину не нужно ни строчки HTML.

[[actions]]
id = "com.example.weather.now"
name = "Погода"
settings = { city = "Москва", units = "metric", refresh = 10 }

[[actions.fields]]
id = "city"
label = "Город"
type = "text"
placeholder = "Название города"

[[actions.fields]]
id = "units"
label = "Единицы"
type = "select"
options = [{ value = "metric", label = "Цельсий" }, { value = "imperial", label = "Фаренгейт" }]

[[actions.fields]]
id = "refresh"
label = "Обновлять, минут"
type = "number"
min = 1
max = 120

Типы полей: text, textarea, number, select, toggle, color. Значение сохраняется в настройках кнопки под ключом id, а плагин получает событие settings. Числа приходят числами, переключатели логическими значениями.

Страница кнопки

Если у действия есть inspector (или у плагина ui.inspector), вместо формы показывается своя страница:

<!doctype html>
<meta charset="utf-8">
<link rel="stylesheet" href="/_opensd/inspector.css">
<script src="/_opensd/inspector.js"></script>

<label>Город <input data-setting="city"></label>
<label>Показывать влажность <input type="checkbox" data-setting="humidity"></label>
<button class="primary" id="test">Проверить</button>

<script>
  document.getElementById("test").onclick = () => opensd.send({ check: true });
  opensd.on("message", (result) => console.log(result));
</script>

/_opensd/inspector.js подключает страницу к приложению и создаёт глобальный opensd.
/_opensd/inspector.css даёт базовое оформление в стиле приложения, со светлой и тёмной темой.
Элементы с data-setting="ключ" связываются с настройками кнопки сами: значение подставляется при открытии и сохраняется при изменении. data-global="ключ" делает то же с общими настройками плагина.

API моста:

Член	Что делает
`opensd.ready`	Промис с контекстом: `kind`, `plugin`, `action`, `context`, `settings`, `globals`, `theme`, `language`
`opensd.settings`, `opensd.saveSettings(s)`	Настройки кнопки
`opensd.globals`, `opensd.saveGlobals(s)`	Общие настройки плагина
`opensd.send(payload)`	Сообщение плагину: событие `inspectorMessage`
`opensd.on("message" \| "settings" \| "globals" \| "theme", fn)`	Подписка
`opensd.openSettings()`	Открыть окно настроек плагина
`opensd.openUrl(url)`	Открыть ссылку `https://` в браузере
`opensd.bind(root)`	Связать поля, добавленные после загрузки

Плагин отвечает странице командой toInspector: key.toInspector(payload) в JavaScript, host.key(&context).to_inspector(&payload) в Rust.

Окно плагина

ui.settings открывается отдельным окном из «Настройки», «Плагины» и со страницы кнопки через opensd.openSettings(). Мост тот же, только без кнопки: kind равен "settings", settings пустой, работа идёт с globals. Сообщения приходят плагину событием settingsPageMessage, плагин отвечает командой toSettingsPage. Пока окно открыто, плагин получает settingsPageOpen, при закрытии settingsPageClose.

Ограничения страниц

Страница открывается в iframe с sandbox="allow-scripts" и политикой default-src 'none':

скрипты, стили, картинки, шрифты и медиа только из пакета или data:;
нет сети: всё, что нужно из внешнего мира, страница просит у плагина;
нет форм с отправкой, всплывающих окон, вложенных фреймов, localStorage и cookies;
переход на другой адрес разрывает связь с приложением.

Сохраняйте настройки кнопками и событиями input или change, а не отправкой формы.