本页内容来自与本站著作权协议兼容的滚动的天空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
|
在参数设置中隐藏该小工具,可以用于以下两种情况:
|
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。