Simple Tampermonkey script config library
此腳本不應該直接安裝，它是一個供其他腳本使用的函式庫。欲使用本函式庫，請在腳本 metadata 寫上： // @require https://update.greasyfork.org/scripts/470224/1501712/Tampermonkey%20Config.js
GM_configEnglish | 简体中文
Simple config lib for Tampermonkey scripts. (Greasy Fork) (GitHub)
prop.input)prop.processor)prop.formatter)This library needs the following permissions to work:
GM_setValue: Save your configGM_getValue: Get your configGM_deleteValue: Automatically delete your config (Optional. If granted, this lib will delete user config that is equal to default value)GM_registerMenuCommand: Register menuGM_unregisterMenuCommand: Update menuGM_addValueChangeListener: Listen for config changesTo include this library in your script, you can choose one of the following methods:
| Source | Original | Minified |
|---|---|---|
| GitHub Release | 🟢 | 🟢 |
| GitHub Raw | 🟢 | 🔴 |
| GreasyFork | 🔴 | 🟡* |
GitHub Release (Minified) is the recommended source. Take that for example, you can include it in your script like this:
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_deleteValue
// @grant GM_registerMenuCommand
// @grant GM_unregisterMenuCommand
// @grant GM_addValueChangeListener
// @require https://github.com/PRO-2684/GM_config/releases/download/<version>/config.min.js
Where <version> is the version you want to include (like v1.2.0). If only for testing, you can directly @require the latest version.
If your script is to be posted to GreasyFork, you may need to add Subresource Integrity checks. Simply append #md5=<md5> after the @required URL, where <md5> is the MD5 hash of the file. You can find the calculated hash at individual release pages.
To begin with, you'll need an Object to describe how your config is structured. This is termed "config description". Here's an example of a simple config description:
const configDesc = {
price: { // Config item id, sometimes called "prop"
name: "Price", // Display name
type: "int", // Type of the config item
value: 100 // Default value
},
name: {
name: "Name",
type: "str",
value: "John Doe"
}
};
You might want to restrict the range of the integer value. No problem, you can use min and max to do so. Here's an example:
const configDesc = {
price: {
name: "Price",
type: "int",
value: 100,
min: 1, // There's no such thing as a free lunch
max: 1000 // I can't afford it!
},
// ...
}
In this way, you've restricted the value in range $[1, 1000]$. Also, you might want a boolean value or a switch. No worries, we've got you covered - simply use "bool" as the type. For a complete list of supported types and their usage, kindly refer to the documentation.
After defining your config description, it's time to register it. Here's how you can do it:
const config = new GM_config(configDesc); // Register menu
Quite simple, right? Now you can start using your config. Normally, you want to query your config values, modify them programmatically under certain conditions, and listen for changes for dynamic updates. Here's how you can do it:
console.log(config.get("price")); // Query config
config.set("price", 100); // Modify config (The displayed menu will be updated automatically)
config.addEventListener("set", (e) => {
const { prop, before, after } = e.detail;
console.log(`Config ${prop} is modified from ${before} to ${after}`);
});
Now that you've successfully set up a simple config menu for your script, it's time to dive deeper into the documentation to explore more advanced features.
console.log(GM_config.version); // *Print version*
The first step is to define your config description, which is a dictionary and each of its key (apart from possible $default) represents the id of a config item. Note that no . is allowed in the id.
$defaultBy using $default, you can easily create a lot of config items of the same type. If $default is not specified in config description, following values will be used to fill unspecified fields in a config item:
{ // Priority: Lowest
type: "string",
input: "prompt",
processor: "same",
formatter: "normal"
}
If you'd like to modify the default value, you may provide $default in your config description to override the above default values. Note that specifying prop.type doesn't work here, and subfolders will inherit $default. e.g.:
const configDesc = {
"$default": { // Priority: Low
value: true,
input: "current",
processor: "not",
formatter: "boolean"
},
switch_true: {
name: "Switch true"
},
switch_false: {
name: "Switch false",
value: false // Priority: Highest
}
}
Usually, however, the following prop.type is the best choice to quickly set up similar config items, and $default is solely used for setting autoClose to false:
const configDesc = {
"$default": {
autoClose: false
},
// ...
}
prop.typeThe type of the config item, used for quickly setting up common properties. Currently supported types are:
str: String, defaulting to ""
bool: Boolean, defaulting to false
int: Integer, defaulting to 0
prop.min is provided, it will check if the value is greater than or equal to itprop.max is provided, it will check if the value is less than or equal to itfloat: Float, defaulting to 0.0
prop.min is provided, it will check if the value is greater than or equal to itprop.max is provided, it will check if the value is less than or equal to itenum: Enumerate
prop.options: An array of strings, each representing an option for display, defaulting to ["A", "B", "C"]
prop.options is only from the user's perspective, and the value actually used is the index of the option (cycles from 0 to prop.options.length - 1)prop.options.length to prop.value, defaulting to 0 if not specifiedaction: Calls function(s) when clicked
prop.input and prop.processor for this typeget events using config.addEventListener to set up callback(s)folder: A folder that contains other config items
prop.items to create config items in this folder, which should be in the same format as the top-level config description configDesc
$default in a folderprop.folderDisplay to customize how a folder is displayed
prefix: Prefix of subfolder names. Default value is empty string.suffix: Suffix of subfolder names. Default value is >.parentText: The text indicating going up a level. Default value is < Back.parentTitle: The title of going up a level. Default value is Return to parent folder.config.get("folder1.folder2.item")config.proxy["folder1.folder2.item"]config.proxy.folder1.folder2.itemconfig.proxy["folder1.folder2"].itemYou may use it like this:
const configDesc = {
switch_true: {
name: "Switch true",
type: "bool" // Priority: High
},
switch_false: {
name: "Switch false",
type: "bool", // Priority: High
value: false // Priority: Highest
}
}
prop.nameThe display name of the config item. Expected type: string.
prop.valueThe default value of the config item, can be of any type. Note that you should consider its validity, because this lib will not check default value's validity for you.
prop.input
(prop, orig, desc) => input
How to get user input. Expected a string (built-in input method) or a function (invoked when user clicks the menu item). If not specified by both prop.input and $default.input, prompt will be used, i.e. ask for user input using prompt(). Note that "user input value" does not necessarily have to be actually input by user, it can be provided by script. (e.g. built-in input method current).
Arguments of the function:
prop: The id of the config itemorig: Current valuedesc: Config description of current config item (desc. conveys the same meaning as prop.)Built-in input functions:
prompt: Ask for user input using prompt() (default value)current: Current value will be used as user input (Usually used with prop.processor=not so as to create a switch, or with custom processor to create a generator)action: Dispatches a get event and returns the original value. Will autoClose the menu to indicate that the click is successful. (Used internally by action type)folder: Goes down the given folder specified by the config item's id. After this, dispatches a get event and returns the original value. Will not autoClose the menu. (Used internally by folder type)prop.processor
(prop, input, desc) => stored
Process user input and return the value to be stored. Expected a string (built-in processor) or a function. Throw error if user input is invalid. If not specified by both prop.formatter and $default.formatter, same will be used, i.e. return user input directly. A common use case is to convert user input to integers or floats.
Arguments of the function:
prop: The id of the config iteminput: User inputdesc: Config description of current config itemBuilt-in processors:
same: Return user input directlynot: Invert boolean value (Usually used with prop.input=current so as to create a switch)int: Convert to integer in given range (if specified)
prop.min is provided, it will check if the value is greater than or equal to itprop.max is provided, it will check if the value is less than or equal to itfloat: Convert to float in given range (if specified)
prop.min is provided, it will check if the value is greater than or equal to itprop.max is provided, it will check if the value is less than or equal to itenum: Adds $1$ to the input and mods prop.options.length (Used internally by enum type)prop.formatter
(prop, value, desc) => string
Controls the text to be displayed on the menu. Expected a string (built-in formatter) or a function. If not specified by both prop.formatter and $default.formatter, normal will be used.
Arguments of the function:
prop: The id of the config itemvalue: The value of the config itemdesc: Config description of current config itemBuilt-in formatters:
normal: Display in the format of name: value
boolean: Display method for boolean values - true will be displayed as name: ✔, false will be displayed as name: ✘.enum: Display in the format of name: option, where option is prop.options[value] (Used internally by enum type)name_only: Only show the name of the config item (Used internally by action type)folder: Wrap the name with prop.folderDisplay.prefix and prop.folderDisplay.suffix. (Used internally by folder type)prop.hidden
boolean
Whether to hide the config item. If set to true, the config item will not be displayed in the menu, but you can still access or modify it using config.get and config.set.
Supports prop.accessKey, prop.autoClose, prop.title (Require TM >=4.20.0). If a function is provided, it will be called with argument prop, value and desc, just like custom prop.formatters. The returned value will be passed to Tampermonkey. See Tampermonkey docs for details.
The priority of the properties is as follows (from highest to lowest):
type of the config item$default in this folder$default for parent folder$default
After defining your config description, you can register the menu item by constructing a GM_config instance. The constructor accepts the following two arguments:
configDesc: Your config descriptionoptions: Options (optional)
immediate: Whether to register the menu items immediately.
true, the menu item will be registered immediately. (default value)false, the user need to click "Show configuration" to register it.debug: Whether to enable debug mode. If set to true, debug information will be printed to console. Default value is false. (Can be modified by config.debug at any time)const config = new GM_config(configDesc, { immediate: false }); // *Register menu*
console.log(config.get("price")); // *You may now start using the config 🎉*
After registering the menu, you can get/set/list config by calling .get(prop), .set(prop, value) and .list(path) on the instance respectively. e.g:
console.log(config.get("price")); // *Get config*
config.set("price", 100); // *Modify config* (The menu will be updated automatically)
console.log(config.list("someFolder.folder")); // *List config items in someFolder.folder*
Alternatively, operate on config.proxy to get/set/list config. e.g:
console.log(config.proxy.price); // *Get config*
config.proxy.price = 100; // *Modify config* (The menu will be updated automatically)
// *List config items in someFolder.folder*
for (const [prop, value] of Object.entries(config.proxy.someFolder.folder)) {
console.log(prop, value);
}
console.log(Object.keys(config.proxy.someFolder.folder));
Since no . is allowed in the id, you could also do this:
console.assert(config.proxy["someFolder.folder"].nothing === config.proxy.someFolder.folder.nothing);
You can listen for config get/set by calling config.addEventListener(type, listener, options?):
config.addEventListener("set", (e) => {
console.log(e.detail); // *Config is modified*
});
config.addEventListener("get", (e) => {
console.log(e.detail); // *Config is accessed*
});
e.detail is a dictionary with the following properties:
prop: The id of the config item accessed/modified. Use dots to represent nested config items.before: The value of the config item before the operation.after: The value of the config item after the operation.remote: Indicating whether this modification is caused by other script instances. Always false for get event (cannot detect other instances' accesses).It should be noted that:
get event is only triggered when the config is accessed by current script instanceset event is triggered when the config is modified from any sources, making multi-tab synchronization possibleAs you might have expected, you can remove the listener by calling config.removeEventListener(type, listener, options?). These two methods are identical to EventTarget.addEventListener and EventTarget.removeEventListener.
This feature is often used to update your script dynamically when config is modified. In this lib, auto-updating menu is implemented by this feature.
You can call config.up() and config.down(name) to navigate up and down the folder hierarchy, and config.currentPath to check the current path. To be specific:
config.up(): Go up one level. If already at the top level, simply re-register. Returns a string indicating the parent folder, or null if already at the root.config.down(name): Go down to the folder specified by name. If name is not a folder, do nothing. Returns true if successfully navigated, false otherwise.config.currentPath: A list of string, each representing a folder, in the order from the root to the current folder. Note that this property is read-only.prop.name and current value to prop.input to get user inputprop.processor to get processed valueconfig.proxy vs config
| Operation | config |
config.proxy |
|---|---|---|
| Get config | config.get("price") |
config.proxy.price |
| Set config | config.set("price", 100) |
config.proxy.price = 100 |
| List config | config.list("someFolder.folder") |
Object.keys(config.proxy.someFolder.folder) |
Internally, all operations on config.proxy are mapped to operations on config.
Install this test code, and see how does it work; Or you can try out this lib in action with Greasy Fork Enhance.
This project is in early development, and the API may change in the future. If you have any suggestions or find any bugs, please feel free to open an issue or pull request.
