Jump to content
MediaWiki

Extension:Gadgets(小工具)

本頁使用了標題或全文手工轉換
From mediawiki.org
This page is a translated version of the page Extension:Gadgets and the translation is 95% complete.
MediaWiki扩展手册
Gadgets
发行状态: 稳定版
实现 MyWiki , 特殊页面 , API
描述
可讓使用者在他們的偏好設定頁面中啟用基於JavaScript、由使用者提供的小工具
作者 Daniel Kinzler (Duesentrieb 留言 )
兼容性政策 快照跟随MediaWiki发布。 master分支不向后兼容。
MediaWiki 1.19+
许可协议 GNU通用公眾授權條款2.0或更新版本
下載
README
示例 維基共享資源:小工具總覽、使用者偏好設定(點擊「小工具」;您需要先登入)
  • $wgGadgetsDefinitionsUseCodeEditor
  • $wgGadgetsRepo
  • $wgGadgetsDefinitionsUseCodeMirror
前往translatewiki.net翻譯Gadgets扩展
問題 开启的任务 · 报告错误

小工具擴充功能讓使用者可以選擇其他wiki使用者所提供的基於JavaScript或CSS的小工具。

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

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

安装

此扩展随附于MediaWiki 1.18及更新版本,因此您無需下載它。 但其余的配置的指示仍须依循執行。
  • 下载文件,并解压Gadgets文件夹到extensions/目录中。
    开发者和代码贡献人员应改从Git安装此扩展,输入:
    cdextensions/
gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
  • 請新增下列代码到您的LocalSettings.php 文件的底部: 
    wfLoadExtension( 'Gadgets' );
  • Yes 完成 – 請导航至您的wiki上的Special:Version,以验证此扩展已成功安装。

配置

$wgGadgetsRepo 是否在MediaWiki:Gadgets-definition中定義小工具,或透過頁面如MediaWiki:Gadgets/你的小工具名稱.json來定義。 若為json,亦將建立內容模型 小工具定義。 "Json"模式目前仍在開發中,尚未準備就緒可供使用。
$wgSpecialGadgetUsageActiveUsers 設定是否在 Special:GadgetUsage 上顯示活躍使用者統計資料。 true

用法

在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-template.vue | 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":[],
"codexIcons":[],
"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)。 自從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
codexIcons Comma-separated codex icon names These Codex icons will be loaded with this gadget, see List of all icons. They will be available from an icons.json file generated in the package. 1.45 (gerrit:1108823)
supportsUrlLoad 无 | true | false 標記小工具可透過URL查詢參數載入。 1.38
Removed options
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


页面

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

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

 * frobinator[ResourceLoader]|frob.js|frob.css|pretty.css
 * l33t[ResourceLoader]|l33t.js
 * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json
 * foo[ResourceLoader|package|dependencies=vue,@wikimedia/codex]|codextest.js|codextest-main.vue|codextest-ChangeNameDialog.vue


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

另見

此扩展用于一个或多个维基媒体项目。 这可能意味着扩展足够稳定、运作足够良好,可以用在这样的高流量的网站上。 请在维基媒体的CommonSettings.php和InitialiseSettings.php配置文件中查找此扩展的名称以查看哪些网站安装了该扩展。 特定wiki上的已安装的扩展的完整列表位于Special:Version页面。
此扩展在以下wiki农场/托管网站和/或软件包中提供: 這不是一份權威名單。 即使某些wiki农场/托管网站和/或软件包未在这里列出,它们也可能提供此扩展。 请检查你的wiki农场/托管网站或软件包以确认提供情况。

AltStyle によって変換されたページ (->オリジナル) /