Extension:小工具

此扩展随附于MediaWiki 1.18及更高版本。 因此您无需另外下载。 但是，您仍需遵循此页面提供的其他使用说明。

MediaWiki扩展手册

Gadgets 发行状态： 稳定版
实现	MyWiki , 特殊页面 , API
描述	允許使用者在他們的偏好設定頁面中啟用基於JS、由使用者提供的小工具
作者	Daniel Kinzler (Duesentrieb留言)
兼容性政策	快照跟随MediaWiki发布。 master分支不向后兼容。
MediaWiki	1.19+
许可协议	GNU通用公眾授權條款2.0或更新版本
下載	下載扩展 Git [?]: 下载Git master 浏览存储库 (Phabricator · GitHub) 提交历史 存储库貢獻者 (GitHub) 代码复核 README
示例	維基共享資源：小工具總覽、使用者偏好設定（點擊「小工具」；您需要先登入）
参数 $wgGadgetsRepo $wgSpecialGadgetUsageActiveUsers
使用的函数钩 BeforePageDisplay CodeEditorGetPageLanguage ContentHandlerDefaultModelFor DeleteUnknownPreferences EditFilterMergedContent GetPreferences PageDeleteComplete PageSaveComplete PreferencesGetIcon PreferencesGetLegend ResourceLoaderRegisterModules UserGetDefaultOptions getUserPermissionsErrors wgQueryPages
季度下載量	114 (Ranked 58th)
正在使用的公开wiki数	4,529 (Ranked 177th)
前往translatewiki.net翻譯Gadgets扩展
問題	开启的任务 · 报告错误

小工具擴充功能提供了一種方式，能讓使用者選擇其他wiki使用者提供基於JavaScript和CSS的小工具。

小工具由位於MediaWiki命名空間頁面中的JavaScript和CSS片段 組成。 每個小工具由MediaWiki:Gadgets-definition中的一行所定義，並提供了小工具的名稱及描述，以及JS和CSS程式碼片段的列表（參見底下的用法段落）。

由於小工具位於MediaWiki命名空間（定義小工具的列表和實際的程式碼判斷皆是），因此只有管理員（自1.32起為介面管理員）能編輯程式碼。 這是因為：只有受到wiki社群高度信任的使用者才能編輯JavaScript程式碼，因為它被其他使用者所用，且JavaScript能輕鬆地劫持帳號和監視他人。

安裝

• 下载文件，并将其放置在您extensions/文件夹中的Gadgets目录内。
  开发者和代码贡献人员应从Git安装扩展，输入：cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
• 将下列代码放置在您的LocalSettings.php 的底部：

  wfLoadExtension( 'Gadgets' );
  

•  完成 – 在您的wiki上导航至Special:Version，以验证已成功安装扩展。

用法

在de.wikipedia的使用者偏好設定中選擇的一些小工具

一旦用至少一个有效的小工具创建了 MediaWiki:Gadgets-definition，一个新的「小工具」部分将在 Special:Preferences 上显示给所有用户。用户可以在那里启用他们想使用的小工具。 当前由 MediaWiki:Gadgets-definition 定义的小工具的概述也在 Special:Gadgets 上显示，并带上指向相关系统消息和脚本/样式页的有用链接，以便于创建或编辑。 小工具选项的统计在 Special:GadgetUsage。

定义格式

在MediaWiki:Gadgets-definition中每個以一個以上「*」（星號）字符開頭的行定义一个小工具。行必須是以下的格式：

* mygadget [选项] | 頁面名稱

第一個欄位（範例中的「mygadget」）是小工具的內部名稱，选项页面的标签来自界面消息页面（MediaWiki:Gadget-mygadget），可以在其中写入名称和简短描述，也允许使用wikitext语法。

内部名称必须以基本的拉丁字母（[A-Za-z]）開頭，並可跟隨任何數量的字母、數字（[0-9]）、連字號（-）、底線（_）和句號（.）。 此限制的原因是内部名称必须在作为HTML表单名称、MediaWiki界面消息键和 ResourceLoader 模块名称时有效。

選項格式：

[ResourceLoader | 選項1 | 選項2 | ... 選項N]

ResourceLoader标签是必须的，除非小工具仅包含样式。 标签选项只需要将其名称写上去就可以启用。 需要值的选项后跟一个等号和一个逗号分隔的值列表。 所有空格都是可选的，可以被省略。

[ResourceLoader | myflag | mykey = value1, value2, value3 ]

範例：

* mygadget[ResourceLoader]|mygadget.js|mygadget.css

或

* mygadget[ResourceLoader|package]| mygadget.js | mygadget-Foo.js | mygadget-data.json | mygadget.css

或

* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css

使用小工具定義命名空間

基於$wgGadgetsRepoClass，有兩種方式可以定義小工具。 如果設定為'MediaWikiGadgetsDefinitionRepo'（預設值），則可用小工具的列表定義在MediaWiki:Gadgets-definition。 替代方式是當$wgGadgetsRepoClass設定為'GadgetDefinitionNamespaceRepo'時，小工具定義在Gadget definition命名空間中的頁面。

遷移已存在的小工具定義尚未被支援，所以您將會在改變此選項後遺失先前定義的小工具。

建立Gadget definition:mygadget頁面並放入以下的JSON程式碼與mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css有相同的效果。

{
	"settings": {
		"rights": [ "foo", "bar" ],
		"default": false,
		"package": false,
		"hidden": false,
		"skins": [],
		"actions": [],
		"category": ""
	},
	"module": {
		"scripts": [ "mygadget.js" ],
		"styles": [ "mygadget.css" ],
		"datas": [],
		"peers": [],
		"dependencies": [],
		"messages": [],
		"type": ""
	}
}

在以上範例中，使用了Gadget:Mygadget.js和Gadget:mygadget.css。

选项

名称	参数	描述	自从
ResourceLoader	无	標記小工具腳本與资源加载器 相容。	1.17 (r76527)
dependencies	逗點隔開的模組名稱	这些模块将在该小工具的脚本执行前加载。 參見預設模組列表。	1.17 (r76639)
rights	逗點隔開的權限名稱	標記小工具僅對擁有特定權限的使用者有效且在偏好設定中可見。	1.18 (r85268)
hidden	无	從偏好設定頁面中隱藏小工具。 這可以使用在兩個地方： 預設啟用小工具並不允許關閉（Common.js的模組化替代方案）。 注意您需要同時加入：hidden | default以對所有使用者載入此模組。 小工具不是給終端使用者所用，而是讓其他小工具載入。 例如允許兩個小工具重用相同的內部程式碼，或對僅在特定頁面載入的小工具註冊「核心」部分。	1.28
skins	逗點隔開的外觀名稱	標記小工具僅對使用特定外觀的使用者有效且在偏好設定中可見。 在MediaWiki 1.32之前它採用使用者在偏好設定中設定的外觀，而不是目前顯示的外觀（例如在URL中加入?useskin=monobook，工單T199478）。 Since 1.39, the ResourceLoader module is not registered on skins the gadget is unavailable on, so the gadget cannot be loaded on those skins as a dependency or using mw.loader.load() either (工單T236603). 使用skins应是不得已而为之，应仅限于依赖 DOM 操作的专门代码，这些代码在没有非标准化API的情况下使用，而资源加载器/核心模块 上列出的方法无法提供这些 API。 For example code which relies on DOM manipulation in the absence of standardized APIs and that cannot be implemented using Core modules.	1.19 (r100509)
actions	逗點隔開的操作名稱	標記小工具僅在特定頁面操作時有效。 例如使用actions = edit, history讓小工具僅在編輯頁面時和歷史頁面上載入。 指定edit操作時也會在action=submit載入。 無效的操作將導致小工具停用，不會在任何地方執行。	1.38 (gerrit:747112)
categories	Comma-separated category names	Make the gadget available only on the specified categories. E.g. categories = Archived, Maintenance to load a gadget only on pages in the Category:Archived or Category:Maintenance.	1.42 (gerrit:1005092)
namespaces	以逗号分隔的命名空间编号	使小工具只能在指定的命名空间中使用。 例如，namespaces = 0, 2只在主空间和用户命名空间內加载小工具。	1.41 (gerrit:624517)
contentModels	逗号分隔的内容模型	在具有给定内容模型的页面上提供小工具。 例如，contentModels = wikitext只在wikitext页面加载小工具。	1.41 (gerrit:922062)
default	无	預設對所有人（包含IP）啟用小工具。 已註冊使用者仍然可以在他們的偏好設定中停用它。	1.18 (r85902)
package	无	標記小工具為packaged。 在此模式中，僅有第一個JavaScript會被執行，其他頁面可透過使用require()函數來引入。 此模式也允許使用JSON頁面，在其他情況無法被引用。	1.38
targets	desktop、mobile、或desktop,mobile(預設)	（在版本1.42.0-wmf.16移除） 對小工具設定资源加载器 目標。 Do not use targets, instead use skins where absolutely necessary.	1.21 (gerrit:60954)
type	styles (default for CSS-only gadgets) or general (default otherwise)	模組僅會修改頁面上已存在元素的樣式（自訂外觀、排版或條目內容），可使用styles。 這讓模組的CSS檔案直接包含在頁面的HTML中，而非透過JavaScript載入。 詳細資訊請見ResourceLoader/Migration guide (users)#Gadget type。 使用styles將不會載入任何指定的JavaScript檔案。 對於同時透過JavaScript和CSS修改元素樣式的小工具，需要使用兩個單獨的小工具定義。	1.28
peers	逗點隔開的小工具名稱	这些仅使用CSS的小工具将与此小工具一起加载。 這些小工具將會比使用dependencies還快載入，且就算JavaScript被停用也會載入。 詳細資訊請見ResourceLoader/Migration guide (users)#Gadget peers。	1.29.0
supportsUrlLoad	无 | true | false	標記小工具可透過URL查詢參數載入。	1.38
requiresES6	None	（在版本1.42.0-wmf.13移除） Allow use of ES6 syntax (ES2015) in the gadget. Enabling this means server-side syntax validation is skipped for the gadget. Any ES6-requiring gadgets are loaded together in a single web request, which isolates failures due to invalid or unsupported syntax to those gadgets only, without affecting other gadgets and MediaWiki software features. It is recommended to use a tool like ESLint to ensure only valid ES6 syntax is used. Conflicts with default.	1.40.0-wmf.7 (gerrit:758086)
top	无	（在版本1.29移除） 標記小工具最早載入。 應該謹慎使用，可能需要初始化一些東西，例如註冊可視化編輯器的插件。	1.22 (gerrit:75506)

您可以對您的小工具指定額外的依賴項，例如：

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

在這裡，我們要求ResourceLoader和mygadget一起載入模組jquery.ui和jquery.effects.clip。 注意小工具無法依賴於來自頁面、靜態文件或外部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

User rights

This extension adds two new user rights, gadgets-edit and gadgets-definition-edit, which by default aren't given to any group.

您可以在您的LocalSettings.php 加入以下內容，以提供適當的權限給interface-admin群組中的使用者。 編輯小工具命名空間中的頁面需要gadgets-edit權限，編輯小工具定義命名空間中的頁面需要gadgets-definition-edit權限。

$wgGroupPermissions['interface-admin']['gadgets-edit'] = true;
$wgGroupPermissions['interface-admin']['gadgets-definition-edit'] = true;

页面

定義行剩餘的欄位指向構成小工具模組的JavaScript、CSS或JSON源碼頁面。 它們作為系統訊息儲存在MediaWiki命名空間內（此範例中的MediaWiki:Gadget-mygadget.js和MediaWiki:Gadget-mygadget.css）。 這些頁面的名稱必須分別以「.css」、「.js」或「.json」結尾。

一個小工具可以使用任意數量的源代码页面，例如：

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

請注意如果您的程式碼包含可被解析為wiki語法的字串（例如，簽名代碼~~~~），您可能想要將您的程式碼包含在‎<nowiki>...‎</nowiki>內，將這些標籤放在JavaScript或CSS註解中，它們才不會在實際使用中被解析。

範例可參考MediaWiki:Gadget-externalsearch-bar.js的第一行和最後一行。

章節

MediaWiki:Gadgets-definition中的小工具列表可以透過以兩個以上的「=」（等號）字元開頭及結尾的行來分隔成多個段落，其中包含定義該段落的系統訊息名稱，例如：

 == interface-gadgets ==

這定義了新段落，其中標題定義在MediaWiki:Gadget-section-interface-gadgets頁面中。

Popular gadgets

See meta:Gadgets for gadgets which are popular in Wikimedia communities.

參閱

• Special:Gadgets – lists all the gadgets and a brief description of each
• Extension:Gadgets/Roadmap
• 小工具管理工具
• Extension:微件
• 片段