Extension:小工具

This page is a translated version of the page Extension:Gadgets and the translation is 88% complete.
Outdated translations are marked like this.
此扩展已绑定在MediaWiki 1.18及以上版本。 因此您不需要再次下载。 然而,您仍需要跟随提供的其他指示。
MediaWiki扩展手冊
OOjs UI icon advanced-invert.svg
Gadgets
發布狀態: 穩定版本
Screenshot-gadgets-tab-vector-skin.png
实现 我的wiki , 特殊页面 , API
描述 允許使用者在他們的偏好設定頁面中啟用基於JS、由使用者提供的小工具
作者 Daniel Kinzler (Duesentrieb讨论)
兼容性政策 快照跟随MediaWiki发布。 master分支不向後兼容。
MediaWiki 1.19+
许可协议 GNU通用公眾授權條款2.0或更新版本
下載
README
示例 維基共享資源:小工具總覽使用者偏好設定(點擊「小工具」;您需要先登入)
  • $wgGadgetsRepoClass
  • $wgSpecialGadgetUsageActiveUsers
Quarterly downloads 195 (Ranked 51st)
Public wikis using 6,111 (Ranked 13th)
翻譯Gadgets扩展,若在translatewiki.net可用
問題 尚未完成的工作 · 报告錯誤

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

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

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

安裝

  • 下载文件,并将其放置在您extensions/文件夹中的Gadgets目录内。
  • 将下列代码放置在您的LocalSettings.php 的底部:
    wfLoadExtension( 'Gadgets' );
    
  •   完成 – 在您的wiki上导航至Special:Version,以验证已成功安装扩展。

用法

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

一旦建立至少一個有效的小工具,所定義的小工具將在Special:Preferences的「小工具」章節顯示,使用者將能選擇他們想要使用的小工具。 由MediaWiki:Gadgets-definition定義的小工具總覽也顯示在Special:Gadgets,並附上指向對應系統訊息的連結以方便編輯。 非預設小工具的使用情況統計可在Special:GadgetUsage檢視。

格式

在MediaWiki:Gadgets-definition中每個以一個以上「*」(星號)字元開頭的行定義為小工具;它必須是以下的格式:

* mygadget [選項(可以省略)] | 頁面名稱

第一個欄位(範例中的「mygadget」)是小工具的內部名稱,並引用一條系統訊息(此範例為MediaWiki:Gadget-mygadget),其包含小工具的簡短描述,可使用wiki語法。

這表示它必須以基本的拉丁字母([A-Za-z])開頭,並跟隨任何數量的字母、數字([0-9])、連字號(-)、底線(_)、冒號($5)和句號(.)。 內部名稱被用作表單欄位名稱的一部分,必須遵守NAME屬性值定義的規則

選項格式:

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

The ResourceLoader flag is required unless the gadget contains only styles. Options that are "flags" only need to have their name written to be turned on. 每個選項可以是僅有選項名稱(在這種情況為flag選項)或包含以逗點隔開的值列表: 可以省略空格。

[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.jsGadget:mygadget.css

选项

名称 參數 描述 以来
ResourceLoader 標記小工具腳本與ResourceLoader 相容。 ?
dependencies 逗點隔開的模組名稱 參見預設模組列表。 如果目前小工具沒有包含相同於ResourceLoader的資源(即沒有樣式表或腳本標記為相同),則此選項無效。 ?
rights 逗點隔開的權限名稱 標記小工具僅對擁有特定權限的使用者有效且在偏好設定中可見。 ?
hidden 偏好設定頁面中隱藏小工具。 這可以使用在兩個地方:
  • 預設啟用小工具並不允許關閉(Common.js的模組化替代方案)。 注意您需要同時加入:hidden | default以對所有使用者載入此模組。
  • 小工具不是給終端使用者所用,而是讓其他小工具載入。 例如允許兩個小工具重用相同的內部程式碼,或對僅在特定頁面載入的小工具註冊「核心」部分。
1.28
skins 逗點隔開的外觀名稱 標記小工具僅對使用特定外觀的使用者有效且在偏好設定中可見。 在MediaWiki 1.32之前它採用使用者在偏好設定中設定的外觀,而不是目前顯示的外觀(例如在URL中加入?useskin=monobook任务T199478)。 ?
actions 逗點隔開的操作名稱 標記小工具僅在特定頁面操作時有效。 例如使用actions = edit, history讓小工具僅在編輯頁面時和歷史頁面上載入。
指定edit操作時也會在action=submit載入。 無效的操作將導致小工具停用,不會在任何地方執行。
1.38-wmf.16
default 預設對所有人(包含IP)啟用小工具。 已註冊使用者仍然可以在他們的偏好設定中停用它。 1.18
package 標記小工具為packaged。 在此模式中,僅有第一個JavaScript會被執行,其他頁面可透過使用require()函數來引入。 此模式也允許使用JSON頁面,在其他情況無法被引用。 1.38-wmf.16
targets desktop(預設)、mobiledesktop,mobile 對小工具設定ResourceLoader 目標。 gerrit:60954
type stylesgeneral 模組僅會修改頁面上已存在元素的樣式(自訂外觀、排版或條目內容),可使用styles。 這讓模組的CSS檔案直接包含在頁面的HTML中,而非透過JavaScript載入。 詳細資訊請見ResourceLoader/Migration guide (users)#Gadget type
使用styles不會載入任何指定的JavaScript檔案。 對於同時透過JavaScriptCSS修改元素樣式的小工具,需要使用兩個單獨的小工具定義。
1.28
peers 逗點隔開的模組名稱 需要僅CSS的小工具(通常被隱藏)。 這些小工具將會比使用dependencies還快載入,且就算JavaScript被停用也會載入。 詳細資訊請見ResourceLoader/Migration guide (users)#Gadget peers 1.29.0-wmf.11
(預發布)
supportsUrlLoad | true | false 標記小工具可透過URL查詢參數載入。 1.38
requiresES6 None 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. 1.40.0-wmf.7
top (在版本1.29移除) 標記小工具最早載入。 應該謹慎使用,可能需要初始化一些東西,例如註冊可視化編輯器的插件。 gerrit:75506

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

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

在這裡,我們要求ResourceLoader和mygadget一起載入模組jquery.uijquery.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:Gadget-mygadget.jsMediaWiki: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

請注意如果您的程式碼包含可被解析為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.

參見