Заставьте веб-сайты работать немного лучше, как вы хотите.

Начните здесь

How @grant работает

Для новых сценариев объявляйте каждый используемый вами привилегированный API. Social Browser запускает сценарии с явными разрешениями в изолированном мире User Script и объединяет только запрошенные возможности. Скрипт с @grant none работает без возможностей GM.

// ==UserScript==// @name Remember display mode// @namespace https://example.com/my-scripts// @match https://example.com/*// @grant GM_getValue// @grant GM_setValue// ==/UserScript== const mode = GM_getValue('displayMode', 'compact');console.log('Saved mode:', mode); GM_setValue('displayMode', 'comfortable');

Классический GM_* или современный GM.*?

Social Browser поддерживает знакомые классические имена и их современные. GM.* формы для основного набора возможностей GM. Современная форма поддерживает Promise, поэтому используйте await. Выберите один стиль для каждого сценария и будьте последовательны.

const theme = GM_getValue('theme', 'dark');GM_setValue('theme', 'light');

const theme = await GM.getValue('theme', 'dark');await GM.setValue('theme', 'light');

GM_info / GM.info

Используйте информацию о сценарии, когда вам нужно проверить текущий сценарий, версию, разрешения, совпадения или информацию о времени выполнения Social Browser. Не жестко закодируйте поведение строк версии, если вам действительно не нужна логика совместимости.

// @grant GM_info console.log('Script:', GM_info.script.name);console.log('Version:', GM_info.version);console.log('Handler:', GM_info.scriptHandler);console.log('Grants:', GM_info.scriptGrants);console.log('Matches:', GM_info.scriptMatches);

Хранение

Запомните небольшие данные скрипта

Хранилище GM ограничено User Script, а не обычным страничным хранилищем. Он идеально подходит для безобидных настроек, счетчиков и состояния сценария. Не используйте его в качестве обычного хранилища для паролей, секретов 2FA, файлов cookie или материалов сеанса.

// @grant GM_getValue// @grant GM_setValue// @grant GM_deleteValue const settings = GM_getValue('settings', { compact: true, rowsPerPage: 25}); settings.rowsPerPage = 50;GM_setValue('settings', settings); // Reset later if the user asks for defaults.// GM_deleteValue('settings');

Наблюдайте за изменением значения

GM_addValueChangeListener полезно, когда один и тот же сценарий открыт более чем в одном фрейме или вкладке. Обратный вызов получает (name, oldValue, newValue, remote). В Social Browser события изменения значений могут синхронизироваться между фреймами/вкладками в одном Profile/сеансе.

// @grant GM_addValueChangeListener// @grant GM_removeValueChangeListener const listenerId = GM_addValueChangeListener( 'displayMode', (name, oldValue, newValue, remote) => { console.log({ name, oldValue, newValue, remote }); }); // Remove it when you no longer need it.// GM_removeValueChangeListener(listenerId);

Помощники страницы

Добавьте стили или небольшие элементы

GM_addStyle(css) / GM.addStyle(css)

Используйте это, когда настройка страницы в основном визуальная. Это чище, чем установка множества отдельных element.style свойства.

// @grant GM_addStyle GM_addStyle(` .important-total { font-weight: 700; outline: 2px solid currentColor; padding: 4px 8px; }`);

GM_addElement(...) / GM.addElement(...)

Создайте небольшой элемент DOM и безопасно добавьте его. Вы можете сначала передать родительский элемент или опустить его, чтобы использовать тело страницы.

// @grant GM_addElement const panel = document.querySelector('#account-panel');if (panel) { GM_addElement(panel, 'button', { type: 'button', textContent: 'Copy account ID', className: 'my-copy-button', onclick() { const id = panel.querySelector('.account-id')?.textContent?.trim(); if (id) navigator.clipboard.writeText(id); } });}

Сеть

Делайте привилегированные запросы с помощью GM_xmlhttpRequest

Обычная страница fetch() контролируется обычными правилами браузера/CORS страницы. Запрос GM Social Browser API использует выделенный канал запроса процесса браузера. Перед отправкой запроса его пункт назначения сверяется с указанным в скрипте. @connect правила.

// ==UserScript==// @match https://app.example.com/*// @connect api.example.com// @grant GM_xmlhttpRequest// ==/UserScript== const response = await GM_xmlhttpRequest({ method: 'GET', url: 'https://api.example.com/status', responseType: 'json', timeout: 10000, headers: { Accept: 'application/json' }}); console.log(response.status, response.response);

Обратные вызовы и прерывание

Запрос API поддерживает общие обратные вызовы запроса и возвращает дескриптор, который можно прервать. Используйте тайм-аут, даже если вы также поддерживаете прерывание.

// @connect api.example.com// @grant GM_xmlhttpRequest const request = GM_xmlhttpRequest({ url: 'https://api.example.com/slow-report', timeout: 15000, onload(response) { console.log('Loaded:', response.status); }, onerror(error) { console.error('Request failed:', error); }, ontimeout() { console.warn('Request timed out'); }, onabort() { console.log('Request aborted'); }}); // Cancel only if your script no longer needs the result.// request.abort();

Современная форма: GM.xmlHttpRequest(...) and GM.xmlhttpRequest(...) сопоставить одну и ту же возможность запроса.

Ресурсы

Объедините повторно используемый текст, CSS или другие ресурсы.

Объявить актив с помощью @resource, затем прочитайте его по имени. GM_getResourceText returns decoded text. GM_getResourceURL возвращает data URL, сохраняющий MIME-тип ответа.

// ==UserScript==// @resource helperCss https://example.com/assets/helper.css// @grant GM_getResourceText// @grant GM_getResourceURL// ==/UserScript== const css = await GM_getResourceText('helperCss');console.log(css); const dataUrl = await GM_getResourceURL('helperCss');console.log(dataUrl);

Если имя ресурса не существует, API возвращает undefined. Имена ресурсов должны быть короткими и информативными.

Помощники браузера

Вкладки, уведомления и буфер обмена

GM_openInTab(url, options)

Откройте URL на вкладке Social Browser. Использование active: false когда новая вкладка должна открыться без фокуса.

// @grant GM_openInTab GM_openInTab('https://example.com/report', { active: false});

Состояние сценария для каждой вкладки: GM_getTab, GM_saveTab, GM_getTabs

Эти API хранят небольшое состояние User Script, связанное с вкладками. Они полезны, когда скрипту необходимо запомнить, какой шаг или представление принадлежит определенной вкладке, не смешивая его с глобальными настройками скрипта.

// @grant GM_getTab// @grant GM_saveTab// @grant GM_getTabs const tabState = await GM_getTab();await GM_saveTab({ ...tabState, lastPanel: 'orders'}); const allScriptTabs = await GM_getTabs();console.log(allScriptTabs);

GM_notification

Покажите уведомление браузера о чем-то, что пользователь действительно должен заметить. Избегайте спама-уведомлений о рутинных действиях сценариев.

// @grant GM_notification await GM_notification({ title: 'Report ready', text: 'The page data is ready to review.'});

GM_setClipboard(data, type)

Скопируйте текст (или HTML по запросу) в буфер обмена. Используйте его, когда это возможно, после четкого действия пользователя, чтобы пользователь понимал, почему его буфер обмена изменился.

// @grant GM_setClipboard const orderId = document.querySelector('.order-id')?.textContent?.trim();if (orderId) { GM_setClipboard(orderId, 'text');}

Меню и загрузки

Добавьте преднамеренные действия пользователя

GM_registerMenuCommand / GM_unregisterMenuCommand

Зарегистрируйте команду в меню User Script. Это хороший шаблон для действий, которые должны выполняться только тогда, когда пользователь явно просит об этом.

// @grant GM_registerMenuCommand// @grant GM_unregisterMenuCommand const commandId = GM_registerMenuCommand( 'Highlight overdue rows', () => { document.querySelectorAll('.row.overdue').forEach((row) => { row.style.fontWeight = '700'; }); }); // Remove the menu item later if the script no longer needs it.// GM_unregisterMenuCommand(commandId);

GM_download

Запустите загрузку через Social Browser. Дайте файлу понятное имя и используйте его только в том случае, если загрузка является частью видимой цели сценария.

// @grant GM_download await GM_download({ url: 'https://example.com/reports/today.csv', name: 'today-report.csv'});

Расширенный

unsafeWindow: мост к глобальным переменным страницы только при необходимости

Явное разрешение User Scripts обычно выполняется в изолированном мире. unsafeWindow — это дополнительный мост к глобальным переменным в главном мире страницы. Используйте его только тогда, когда веб-сайт предоставляет переменную страницы или функцию, к которой обычный доступ к изолированному сценарию не может получить доступ.

// @grant unsafeWindow const appVersion = unsafeWindow.appConfig?.version;if (appVersion) { console.log('Page app version:', appVersion);}

Правило мира казни

Полный пример

Небольшой скрипт, объединяющий хранилище, стили, команды меню и буфер обмена.

Этот пример намеренно остается небольшим. Он запоминает, включено ли выделение, добавляет одно правило стиля, позволяет пользователю переключать его из меню User Script и копирует видимое значение страницы только по запросу.

// ==UserScript==// @name Helpful order-page tools// @namespace https://example.com/my-scripts// @version 1.0.0// @match https://example.com/orders/*// @grant GM_getValue// @grant GM_setValue// @grant GM_addStyle// @grant GM_registerMenuCommand// @grant GM_setClipboard// ==/UserScript== (() => { 'use strict';  GM_addStyle(` .sb-order-highlight { outline: 2px solid currentColor; font-weight: 700; } `);  const applyHighlight = () => { const enabled = GM_getValue('highlightEnabled', true); document.querySelectorAll('.order-total').forEach((element) => { element.classList.toggle('sb-order-highlight', enabled); }); };  GM_registerMenuCommand('Toggle order highlighting', () => { const current = GM_getValue('highlightEnabled', true); GM_setValue('highlightEnabled', !current); applyHighlight(); });  GM_registerMenuCommand('Copy current order ID', () => { const orderId = document.querySelector('.order-id')?.textContent?.trim(); if (orderId) { GM_setClipboard(orderId, 'text'); } });  applyHighlight();})();