Как написать скрипт для 1hebrew

Обычный юзерскрипт становится «своим» в менеджере «1hebrew Скрипты»: его настройки появляются в общей панели рядом с нашими, у него есть кнопка ⚙ и своя панель в окошке менеджера, он умеет показывать всплывашки и панели в стиле менеджера. Для этого хватает нескольких строк в шапке — ничего не нужно согласовывать с нами.

В Tampermonkey и обычном Violentmonkey такие строки ничего не ломают: их там просто никто не читает, и скрипт работает как раньше.

Скачать шаблон Файл настроек шаблона Файл панели шаблона

1. Шапка

// ==UserScript==
// @name         Мой скрипт
// @namespace    https://example.com/my-scripts
// @version      1.0.0
// @match        https://example.com/*
// @icon         https://example.com/icon.png
// @resource     settings https://example.com/my.settings.json
// @resource     panel https://example.com/my.panel.json
// @hebrew-settings               settings
// @hebrew-settings-command       Настройки
// @hebrew-full-settings-command  Все настройки
// @hebrew-panel                  panel
// @grant        GM_getValue
// @grant        GM_addValueChangeListener
// @grant        GM_registerMenuCommand
// @grant        hebrew.ui
// @grant        hebrew.panel
// ==/UserScript==

Если что-то написано не так, менеджер покажет это при установке скрипта («Ключи 1hebrew: есть ошибки») и в редакторе над кодом. Скрипт при этом всё равно ставится и работает — просто без формы настроек.

2. Файл настроек

Тот же формат, что у наших скриптов. Скрипт читает значения обычным GM_getValue(ключ, по_умолчанию); когда человек меняет настройку в панели, срабатывает GM_addValueChangeListener — перезагружать страницу не нужно.

{
  "settings": [
    { "key": "enabled", "type": "bool", "label": "Включено", "default": true },
    { "key": "size", "type": "number", "label": "Размер", "default": 3,
      "min": 1, "max": 10, "step": 1, "help": "Подсказка под названием" },
    { "key": "mode", "type": "select", "label": "Режим", "default": "fast",
      "options": [ { "value": "fast", "label": "быстро" },
                   { "value": "slow", "label": "медленно" } ] },
    { "key": "greeting", "type": "text", "label": "Текст", "default": "" },
    { "key": "openKey", "type": "hotkey", "label": "Открыть панель", "default": "Alt+Shift+H" }
  ],
  "groups": [
    { "title": "Дополнительно", "keys": ["size", "openKey"], "collapsed": true }
  ]
}

У каждой настройки обязательны key (латиница, цифры, . _ -), type и label; help — по желанию. Группы необязательны: настройки без группы идут первыми.

Синхронизация. Если человек включил облачную синхронизацию, значения настроек из этого файла едут вместе со скриптом на его другие устройства — и только они: остальное, что скрипт хранит через GM_setValue (данные, кэш, размер окна), остаётся на устройстве. Поля password не синхронизируются никогда. Настройку, которая имеет смысл только на этом устройстве (адрес своего сервера, токен устройства), пометьте "sync": false — другое значение, кроме false, считается ошибкой. Пришедшее значение менеджер проверяет по вашему файлу настроек на принимающем устройстве: неизвестный ключ или значение не того типа отбрасываются.

Строгие правила. Файл до 64 КБ, до 40 настроек, до 10 групп. Лишних полей быть не должно, тексты — до 120 символов (help — до 300), без служебных символов. Если хоть что-то не так, менеджер не показывает форму вовсе и пишет причину на карточке скрипта: половина формы хуже, чем никакой.

Клавиши. Скрипт сам слушает клавиатуру и сам сравнивает нажатие со значением из настроек. Менеджер следит, чтобы ваша клавиша не совпала с его собственными, с клавишами наших скриптов и расширений и с клавишами скриптов, установленных раньше вашего. При совпадении менеджер записывает в настройку пустую строку и пишет на карточке «Клавиша … занята — выключена». Поэтому пустая строка должна значить «клавиша выключена».

3. Интерфейс на странице: hebrew.ui

С @grant hebrew.ui в скрипте появляется объект hebrew.ui. Всё, что он рисует, живёт в закрытом теневом DOM: сайт не может перекрасить или прочитать этот интерфейс. Тексты выводятся как текст — HTML, ссылки и картинки туда не передать. На каждой всплывашке и панели менеджер сам подписывает имя скрипта.

const ui = typeof hebrew === 'object' && hebrew?.ui ? hebrew.ui : null;

ui?.toast('Сохранено', { kind: 'ok', timeout: 3000 });   // kind: info | ok | error

const panel = ui.panel({
  title: 'Мой скрипт',
  content: [
    'Обычная строка — это текст',
    ui.switch({ label: 'Подсветка', checked: true, onChange: on => toggle(on) }),
    ui.button({ label: 'Сделать', primary: true, onClick: () => run() }),
  ],
  onClose: () => console.log('панель закрыли'),
});
panel.update([ 'Новое содержимое' ]);   // перерисовать
panel.close();

ui.onThemeChange(theme => {
  // theme.name: 'light' | 'dark'; theme.tokens: { '--hb-bg': '#0c0b10', ... }
  for (const [name, value] of Object.entries(theme.tokens)) {
    myRoot.style.setProperty(name, value);
  }
});

Полей ввода в панели нет специально: так чужая панель не может выдать себя за менеджер и попросить пароль. Ввод текста — через настройки (тип text) или поле input в панели окошка (раздел 4).

В других менеджерах объекта hebrew нет. Проверяйте его, как в примере, и показывайте что-то своё — шаблон так и делает.

4. Панель в окошке: @hebrew-panel

У скрипта может быть своя панель в окошке менеджера (кнопка расширения на панели браузера). Код скрипта там не выполняется: скрипт описывает панель данными, а менеджер рисует её своими кнопками и полями. Панели других авторов идут отдельным блоком «Панели других авторов» — всегда после наших скриптов; в шапке каждой менеджер сам пишет имя и иконку скрипта и пометку «другой автор».

{
  "title": "Мой скрипт",
  "elements": [
    { "type": "text", "text": "Нажато: 0" },
    { "type": "button", "id": "press", "label": "Нажать", "primary": true },
    { "type": "switch", "id": "on", "label": "Включено", "value": true },
    { "type": "select", "id": "mode", "label": "Режим", "value": "fast",
      "options": [ { "value": "fast", "label": "быстро" }, { "value": "slow", "label": "медленно" } ] },
    { "type": "number", "id": "size", "label": "Размер", "value": 3, "min": 1, "max": 10, "step": 1 },
    { "type": "input", "id": "note", "label": "Заметка", "placeholder": "Текст",
      "multiline": false, "maxLength": 200, "submit": "Добавить" },
    { "type": "list", "id": "notes", "label": "Заметки",
      "items": [ { "id": "n1", "text": "Первая", "action": "Удалить" } ] },
    { "type": "divider" }
  ]
}

Скрипт слушает нажатия и присылает новое содержимое панели — целиком, в том же формате:

const popupPanel = typeof hebrew === 'object' && hebrew?.panel ? hebrew.panel : null;

popupPanel?.onAction(action => {
  // action: { type, id, value?, item? }
  //   button — { type: 'button', id }
  //   switch / select / number — value: новое значение
  //   input — value: текст, когда человек нажал кнопку под полем (или Enter)
  //   list — item: id строки, у которой нажали кнопку action
  if (action.id === 'press') clicks += 1;
  popupPanel.update(buildPanel()).catch(error => console.warn(error.message));
});

Строгие правила. Файл (и каждое обновление) — до 32 КБ, до 40 элементов, title до 60 символов, подписи до 120. Лишних полей быть не должно, id не повторяются. Никакого HTML, картинок и ссылок: строки с адресами (https://…, www.…) не принимаются — панель никуда не ведёт. Поле ввода не может быть паролем и не может спрашивать пароль, токен, логин или номер карты; под каждым полем менеджер сам пишет «Текст уйдёт в скрипт «…»». Название панели не может повторять наши блоки («Перевод», «Курсы», «Вставки», «Клавиши», «Настройки»…). Если что-то не так, панель не показывается, а причина видна на карточке скрипта, при установке и в редакторе; неверное обновление отклоняется — update вернёт ошибку с причиной. Обновлять можно не чаще 10 раз за 2 секунды.

Нажатия приходят только тому экземпляру скрипта, который работает в открытой вкладке (во встроенных окнах страницы панели нет), и только этому скрипту — другие скрипты на той же странице их не получают. Пока скрипт на странице не вызвал hebrew.panel, вместо панели написано «Скрипт не работает на этой странице».

5. Что менеджер гарантирует

• Значения настроек хранятся в хранилище вашего скрипта (как GM_setValue) и видны только ему.
• Ключи @hebrew-* не дают скрипту никаких новых прав: ни сети, ни чужих данных. Сеть — только по @connect, как обычно.
• Новый адрес в @resource и новый @grant в обновлении менеджер считает расширением прав: такое обновление ждёт подтверждения человека.
• Скрипты из нашего каталога описаны в каталоге, и для них шапка не читается — каталог главнее.
• Код скрипта никогда не выполняется в окошке менеджера: панель — только данные, нарисованные менеджером.

Как это выглядит