帮助:小工具

本页内容来自滚动的天空Wiki https://rs.miraheze.org/wiki/Help:小工具

小工具（Gadgets）由mw:Extension:Gadgets提供，它能使用户使用其他用户提供的JavaScript/CSS。他们可以在参数设置中被已注册用户启用或禁用。

可以在Special:小工具获取本wiki所有小工具的名称和描述，并在Special:GadgetUsage查询小工具的使用情况。

定义小工具

MediaWiki:Gadgets-definition中每个以一个或一个以上星号*开头的行定义一个小工具，必须遵循以下格式

* 小工具内部名称 [可选参数] | JS/CSS页面名称

第一个字段是小工具内部名称，并引用一条使用wiki语法的系统消息（MediaWiki:Gadget-小工具内部名称）作为一个简短的小工具描述。注意：内部名称被用作表单字段名称的一部分，必须遵守NAME属性值定义的规则，也就是说它必须是以字母（[A-Za-z]）开头，由字母、数字（[0-9]）、连字符（-）、下划线（_）、半角冒号（:）和小数点（.）组成的字符串。

可选参数格式如下（空格可省略）：

[参数1 | 参数2 = 参数值 | ... 参数N]

每个可选参数可以只有参数名称（标志参数），如ResourceLoader、hidden，也可以包含以逗号隔开的值的列表：

参数 = 值1, 值2, 值3

例如：

* mygadget1[ResourceLoader]|mygadget1.js|mygadget1.css
* mygadget2[ResourceLoader|package]| mygadget2.js | mygadget2-Foo.js | mygadget2-data.json | mygadget2.css
* mygadget3[ ResourceLoader | rights=edit, purge ] | mygadget3.js | mygadget3.css

可选参数

名称	参数值	描述	加入版本
ResourceLoader		使小工具脚本与ResourceLoader相容。	?
dependencies	以逗号隔开的依赖模块名称	如果目前小工具没有包含相容于ResourceLoader的资源（即没有样式表或脚本标记为相容），则此选项无效。	?
rights	以逗号隔开的权限名称	使该小工具仅对有特定权限的用户可用且在参数设置中可见。	?
hidden		在参数设置中隐藏该小工具，可以用于以下两种情况： 默认启用一个小工具且不可禁用（Common.js的小工具替代方案）。注意小工具只有同时加入hidden | default才对所有用户加载。 小工具不是为终端用户使用，而是被其他小工具加载。例如允许两个小工具复用相同的内部代码，或对仅在特定页面加载的小工具注册“核心”部分。	1.28
skins	以逗号隔开的皮肤名称	使小工具仅对使用特定皮肤的用户可用。	?
actions	以逗号隔开的操作名称	使小工具仅对特定页面操作有效。例如actions = edit, history能使小工具仅在编辑和浏览编辑历史时加载。注意：指定edit操作时也会在action=submit载入。无效的操作将导致小工具停用，不会在任何地方执行。	1.38-wmf.16
default		使小工具默认对所有人（包括匿名用户）启用。已注册用户仍能在参数设置中禁用该小工具。（前提是没有hidden参数。）	1.18
package		标记小工具为包。在该模式下，只有第一个JavaScript页面会被执行，而其他页面会被用模板:Code导入，并且能启用在其他情况无法被使用的JSON页面。	1.38-wmf.16
targets	desktop（默认）、mobile或desktop,mobile	设定小工具的ResourceLoader目标（桌面版和移动版）。	gerrit:60954
type	styles或general	styles：小工具只修改页面已有元素的样式。它会导致小工具的CSS文件嵌入页面HTML而不是通过JavaScript加载。注意：这将不会加载任何指定的JavaScript文件。对于同时通过JS和CSS修改元素样式的小工具，需要设定两个独立小工具定义。	1.28
peers	以逗号隔开的ResourceLoader模块名称	需要仅有CSS的小工具（通常隐藏）。这些小工具比dependencies加载还要快，并且即使JavaScript被浏览器禁用也会被加载。	1.29.0-wmf.11 （预发布版本）
supportsUrlLoad	无 | true | false	使小工具可通过url查询参数withgadget加载。	1.38
requiresES6		允许ES6（ES2015）语法在小工具中的使用。启用此项意味着该小工具跳过服务端语法检查。任何需要ES6的小工具都在一个网络请求中加载，使得不正确或不支持的语法导致的错误只针对那些小工具，而不会影响别的小工具和MediaWiki软件特性。推荐使用类似于ESLint的工具来确保只有合法ES6语法被使用。	1.40.0-wmf.7

你可以为你的小工具指定附加的依赖，例如：

* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css

在这里，我们请求ResourceLoader把jquery.ui和jquery.effects.clip跟mygadget一同加载。注意小工具无法依赖于来自页面、静态文件或外部URL的脚本，只有已在ResourceLoader注册的模块可以使用。要想让某页面的脚本依赖于另一页面的脚本，两个脚本都必须先作为小工具在ResourceLoader上注册为模块，才能使用以下语法设定依赖关系：

* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js

可以用"default"将小工具设定为默认启用：

 * mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css

要使小工具只对有合适权限的用户可用，设定rights参数，例如：

* ImprovedDeletion [rights=delete] | ImprovedDeletion.js

使小工具只对真正能删除页面的用户可用。

注意此限制是基于权限，而非行政员之类的用户组。例如：

* modrollback[ResourceLoader|rights=rollback]|modrollback.js
* UTCLiveClock[ResourceLoader|rights=purge]|UTCLiveClock.js
* Ajax_sysop[ResourceLoader|rights=patrol,rollback,markbotedits,delete]|Ajax_sysop.js

页面

最后一个字段指代组成小工具的JavaScript、CSS或JSON代码，包含于系统消息中（在例子中的MediaWiki:Gadget-mygadget.js和MediaWiki:Gadget-mygadget.css），其标题必须以“.js”或“.css”结尾。

一个小工具可使用任意数量的消息页面。特别地，除了小工具自己的特定代码，共用代码可以放入一个由几个小工具使用的消息页面，例如：

* frobinator[ResourceLoader]|commonStuff.js|frob.js|frob.css|pretty.css
* l33t[ResourceLoader]|commonStuff.js|tools.js|l33t.js
* foobar[ResourceLoader|package]|foo.js|bar.js|foobar.json

在这个例子中，小工具frobinator和l33t都使用了MediaWiki:Gadget-commonStuff.js的代码。

请注意如果代码含有会被解析为wiki语法的字符串（如签名代码~~~~、分类等），应当将其用模板:Tag包裹并放入注释中以保证不会被解析。

章节

MediaWiki:Gadgets-definition中的小工具列表可以用二级及以下标题（行首的== ==）拆分为多个章节，包含一个定义该章节名称的系统消息，例如：

== interface-gadgets ==

这将会表示一个新章节，其标题会被定义为MediaWiki:Gadget-section-interface-gadgets。