Extension:小工具
 发行状态： 稳定版 |
|
|---|---|
 |
|
| 实现 | MyWiki, 特殊页面, API |
| 描述 | |
| 作者 | Daniel Kinzler (Duesentrieb留言) |
| 兼容性政策 | 快照跟随MediaWiki发布。 master分支不向后兼容。 |
| MediaWiki | 1.19+ |
| 许可协议 | GNU通用公眾授權條款2.0或更新版本 |
| 下載 | README |
| 示例 | 維基共享資源：小工具總覽、使用者偏好設定（點擊「小工具」；您需要先登入） |
|
|
| 季度下載量 | 132 (Ranked 46th) |
| 正在使用的公开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能輕鬆地劫持帳號和監視他人。
安裝
- 下载文件，并将解压后的
Gadgets文件夹移动到extensions/目录中。
开发者和代码贡献人员应从Git安装扩展，输入：cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets - 将下列代码放置在您的LocalSettings.php的底部：
wfLoadExtension( 'Gadgets' );
完成 – 在您的wiki上导航至Special:Version，以验证已成功安装扩展。
用法
一旦用至少一个有效的小工具创建了 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
使用小工具定義命名空間
| MediaWiki版本： | ≤ 1.41 |
視$wgGadgetsRepoClass的不同，有兩種方式可以定義小工具。
如果它是'MediaWikiGadgetsDefinitionRepo'（預設值），則可用小工具的列表定義在MediaWiki:Gadgets-definition之內。
在另一種方式中，當$wgGadgetsRepoClass設定為'GadgetDefinitionNamespaceRepo'時，小工具的定義會在小工具定義命名空間中的頁面上被定義。
(在MediaWiki 1.39版以上，所使用的值是'\\MediaWiki\\Extension\\Gadgets\\GadgetDefinitionNamespaceRepo'。)
建立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) |
skins
|
逗點隔開的皮肤名稱 | 標記小工具僅對使用特定皮肤的使用者有效且在偏好設定中可見。 在MediaWiki 1.32之前它採用使用者在偏好設定中設定的皮肤，而不是目前顯示的皮肤（例如在URL中加入?useskin=monobook，T199478）。 自從1.39版起，因為ResourceLoader模組不會在小工具無法使用的皮肤上註冊，因此小工具無法在這些皮肤上作為依賴而被載入，或是在使用mw.loader.load()時也會有相同的情形(T236603)。
使用
skins是不得已而为之，应仅限于依赖DOM操作的专门代码。 例如这些代码在没有非标准化API的情况下使用，而核心模块上列出的方法无法提供这些API。 |
1.19 (r100509) |
actions
|
逗點隔開的操作名稱 | 標記小工具僅在特定頁面操作時有效。 例如使用actions = edit, history讓小工具僅在編輯頁面時和歷史頁面上載入。
指定
edit操作時也會在action=submit載入。 無效的操作將導致小工具停用，不會在任何地方執行。 |
1.38 (gerrit:747112) |
categories
|
以逗号分隔的類別名稱 | 讓小工具只能在指定的類別上使用。 例如：categories = Archived, Maintenance只會在Category:Archived或Category:Maintenance的頁面上載入小工具。 另见：Template gadgets
|
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 |
type
|
styles (針對CSS小工具的預設值) 或general (其他情況下的預設值)
|
模組僅會修改頁面上已存在元素的樣式（自訂外觀、排版或條目內容），可使用styles。 這讓模組的CSS檔案直接包含在頁面的HTML中，而非透過JavaScript載入。 詳細資訊請見ResourceLoader/迁移指导（用户）#Gadget type。
使用
styles將不會載入任何指定的JavaScript檔案。 對於同時透過JavaScript和CSS修改元素樣式的小工具，需要使用兩個單獨的小工具定義。 |
1.28 |
peers
|
逗點隔開的小工具名稱 | 这些仅使用CSS的小工具将与此小工具一起加载。 這些小工具將會比使用dependencies還快載入，且就算JavaScript被停用也會載入。 詳細資訊請見ResourceLoader/Migration guide (users)#Gadget peers。
|
1.29 |
supportsUrlLoad
|
无 | true | false | 標記小工具可透過URL查詢參數載入。 | 1.38 |
| Name | Parameters | Description | Since | Removed |
|---|---|---|---|---|
top
|
无 | 標記小工具最早載入。 應該謹慎使用，可能需要初始化一些東西，例如註冊可視化編輯器的插件。 | 1.22 (gerrit:75506) | 1.29 |
requiresES6
|
「無」 | 允許在小工具中使用ES6語法 (ES2015)。 啟用此功能表示小工具會跳過伺服器端的語法驗證。 任何需要ES6的小工具都會在單一網頁請求中一併載入，這可將因無效或不支援的語法所導致的故障隔離，只影響這些小工具，而不會影響其他小工具和MediaWiki軟體功能。 建議使用ESLint之類的工具，以確保只會使用有效的ES6語法。 與default衝突。
|
1.40 (gerrit:758086) | 1.42 |
targets
|
desktop、mobile、或desktop, mobile(預設)
|
對小工具設定资源加载器目標。
請勿使用
targets，而在絕對必要的情況下使用skins。 |
1.21 (gerrit:60954) | 1.42 |
您可以對您的小工具指定額外的依賴項，例如：
* 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 * geonotice [ResourceLoader |default |rights=viewmywatchlist] |geonotice.js * Ajax_sysop [ResourceLoader |rights=patrol, rollback, markbotedits, delete]|Ajax_sysop.js
使用者權限
gadgets-edit和gadgets-definition-edit，預設情況下不會給予任何群組。
您可以在您的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-formWizard-core.js的第一行和最後一行。
章節
MediaWiki:Gadgets-definition中的小工具列表可以透過以兩個以上的「=」（等號）字元開頭及結尾的行來分隔成多個段落，其中包含定義該段落的系統訊息名稱，例如：
== interface-gadgets == ... == editing-gadgets == ...
這會定義二個新段落，其標題定義在MediaWiki:Gadget-section-interface-gadgets頁面和MediaWiki:Gadget-section-editing-gadgets頁面中。
熱門的小工具
在維基媒體社群中很受歡迎的小工具，請參見meta:Gadgets。
另見
- Special:Gadgets – 列出所有的小工具，以及每個小工具的簡要說明
- Extension:Gadgets/Roadmap
- 小工具管理工具
- Extension:微件
- 片段
| 此扩展用于一个或多个维基媒体项目。 这可能意味着扩展足够稳定、运作足够良好，可以用在这样的高流量的网站上。 请在维基媒体的CommonSettings.php和InitialiseSettings.php配置文件中查找此扩展的名称以查看哪些网站安装了该扩展。 特定wiki上的已安装的扩展的完整列表位于Special:Version页面。 |
| 此扩展在以下wiki农场/托管网站和/或软件包中提供： 這不是一份權威名單。 即使某些wiki农场/托管网站和/或软件包未在这里列出，它们也可能提供此扩展。 请检查你的wiki农场/托管网站或软件包以确认提供情况。 |