Plugin settings pages (settingsPages)
Plugins often need their own configuration UI (toggles, API keys, default behavior). Instead of scattering Settings buttons across plugin pages, put the settings UI inside the Launcher: in Settings → Plugins → Plugin settings (Settings → Plugins → Plugin Settings) the left side lists one vertical tab per plugin and the right side shows the settings UI that plugin provides. Users can find it and do not get lost.Quick start
Step 1: Declare a Plugin settings page (Plugin Settings) incontributes.settingsPages of manifest.json (the relative path of an HTML file inside the .qplugin package):
dist/settings.html inside the package. It is a plain HTML page running in exactly the same Sandbox environment as the plugin’s main page (iframe Sandbox + full __PLUGIN_API__ Bridge + injected theme variables); use getSettings / setSettings to read and write the plugin’s own configuration:
.qplugin, install it, and enable the plugin. Settings → Plugins → Plugin settings now shows a tab named after the plugin, and opening it shows the UI you wrote.
Runtime environment
- iframe Sandbox:
<iframe sandbox="allow-scripts">rendered through srcdoc, isolated from the main interface DOM/CSS; every__PLUGIN_API__method is available (same Permission checks as plugin pages) - Theme following: the Launcher injects the theme CSS variables (
--foreground/--background/--primary/--border, and so on) and.p-*Component styles, and light and dark themes switch automatically; you do not need to handle it yourself - Container size: the content area on the right is about 560px high and adapts in width; when the page overflows it scrolls internally, so just lay out your root element at 100% height
- Configuration persistence:
getSettings/setSettingsread and writeplugins/{plugin id}/settings.json, andsetSettingsmerges by key (concurrency-safe), so you never write the whole object at once
Jump straight to the settings page
When you provide a Settings button on a plugin page or inside an Overlay window, jump withopenPluginSettings; the Launcher opens Plugin settings and selects your plugin:
- Permission:
config:read - If the target plugin declares no
settingsPages, the plugin settings area still opens (at its default position) - If one plugin declares several settings pages, the first one is selected
Rules and Lifecycle (lifecycle)
Consumers of plugin configuration (widgets, Overlay windows) should also call
getSettings at runtime and apply the latest values; the settings page only writes, and it does not broadcast changes automatically.