查看“帮助:小工具”的源代码

 本页内容来自与本站著作权协议兼容的滚动的天空Wiki： https://rs.miraheze.org/wiki/Help:小工具

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

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

== 定义小工具 ==
[[MediaWiki:Gadgets-definition]]中每个以一个或一个以上星号<code>*</code>开头的行定义一个小工具，必须遵循以下格式
<pre>
* 小工具内部名称 [可选参数] | JS/CSS页面名称
</pre>

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

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

<pre>
[参数1 | 参数2 = 参数值 | ... 参数N]
</pre>

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

<pre>
参数 = 值1, 值2, 值3
</pre>

例如：
<pre>
* 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
</pre>

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

你可以为你的小工具指定附加的依赖，例如：
<pre>
* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css
</pre>

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

<pre>
* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js
</pre>

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

<pre>
 * mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css
</pre>

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

<pre>
* ImprovedDeletion [rights=delete] | ImprovedDeletion.js
</pre>

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

注意此限制是基于权限，而非行政员之类的用户组。例如：
<pre>
* modrollback[ResourceLoader|rights=rollback]|modrollback.js
* UTCLiveClock[ResourceLoader|rights=purge]|UTCLiveClock.js
* Ajax_sysop[ResourceLoader|rights=patrol,rollback,markbotedits,delete]|Ajax_sysop.js
</pre>

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

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

<pre>
* 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
</pre>

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

请注意如果代码含有会被解析为wiki语法的字符串（如签名代码<code>~~<noinclude>~</noinclude>~</code>、分类等），应当将其用{{tag|nowiki}}包裹并放入注释中以保证不会被解析。

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

<pre>== interface-gadgets ==</pre>

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