帮助:小工具

来自吾萌百科

本页内容来自与本站著作权协议兼容的滚动的天空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]

每个可选参数可以只有参数名称(标志参数),如ResourceLoaderhidden,也可以包含以逗号隔开的值的列表:

参数 = 值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(默认)、mobiledesktop,mobile 设定小工具的ResourceLoader目标(桌面版和移动版)。 gerrit:60954
type stylesgeneral 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.uijquery.effects.clipmygadget一同加载。注意小工具无法依赖于来自页面、静态文件或外部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