LLWiki:管理员技术手册

此頁面內容嚴重缺失，急需您幫忙補充！（點此編輯） 可參考同類條目添加所需內容，並從官方等可靠渠道搜集資料編寫，亦建議附上資料來源。

由於LLWiki使用的不是最新版本的MediaWiki系統以及MediaWiki的幫助頁面可能未得到及時和正確的更新，編輯這個頁面時請不要簡單地複製或翻譯來自MediaWiki的內容，應該在條件允許的情況下先實際測試。

全站CSS

這裡所說的全站CSS包含common.css、mobile.css和各CSS小工具，有時由於功能的相似性也會涉及用戶CSS（common.css、vector.css和minerva.css）。LLWiki暫時沒有建立針對不同用戶組的專門CSS頁面。

優先加載的CSS

一些CSS會以<link rel="stylesheet">的形式在首次渲染前完成加載，包括common.css和各純CSS小工具，這些CSS頁面適合處理靜態HTML元素就需要的樣式。注意純CSS小工具即使在定義時規定了targets=mobile也一定會在桌面版加載，因此手機版的專用CSS需要添加.skin-minerva選擇器。

由於common.css本身就會優先加載，桌面版專用的全站CSS寫入該頁面即可，與手機版通用的CSS寫入gadget-site-styles.css。某個小工具專用的CSS如果需要用於靜態HTML元素，請將CSS部分單獨定義為type=styles（可省略，但添加後方便區分）的純CSS小工具，然後以peers=<纯CSS小工具名称>的語法添加到對應的JS小工具上。參見#小工具定義。

滯後加載的CSS

一些CSS的加載需要依賴JS，加載時機可能晚於首次渲染，包括mobile.css和除純CSS小工具以外的CSS小工具，這些CSS頁面適合處理依賴JS動態加載的HTML元素。

由於mobile.css加載滯後，靜態HTML元素需要的手機版樣式請添加.skin-minerva選擇器後寫入gadget-site-styles.css。

CSS小工具分類

定義為type=styles的小工具應添加純CSS小工具分類，其他CSS小工具應添加CSS小工具分類。其他分類與JS小工具一致，參見#小工具分類。

Gadget（小工具）和全站JS

這裡所涉及的JS頁面包含common.js、mobile.js和各JS小工具，有時由於功能的相似性也會涉及用戶JS（common.js、vector.js和minerva.js）。LLWiki暫時沒有建立針對不同用戶組的專門JS頁面。

MediaWiki核心模塊介紹

本章節介紹LLWiki使用或曾經使用的MediaWiki核心模塊，更完整的列表參見MediaWiki和JSDuck。

mediawiki

mediawiki是任何頁面都會預加載的兩個環境模塊之一，包含不少功能。這裡只介紹LLWiki常使用的一些屬性和方法。

mw.config

這個屬性提供了大量重要的站點、頁面和用戶信息，一般常用mw.config.get()方法獲取對應的變量值。下表整理了LLWiki常用的一些變量：

變量名	說明	手機版可用性
skin	皮膚	桌面版為「vector」，手機版為「minerva」，這也是區分桌面版和手機版的主要依據
wgFormattedNamespaces	儲存了所有名字空間本地化譯名的數組，不過目前除了「模塊」都是英文	可用
wgNamespaceIds	儲存了所有可接受的中英文名字空間名稱對應的編號，注意英文名稱中的空格都顯示為下劃線	可用
wgScript	/mediawiki/index.php，在LLWiki也可簡化為/zh，主要用於不同MediaWiki站點間的代碼通用，非必需	可用
wgAction	index.php的action參數	相比於桌面版，手機版由於添加了Special:歷史而少了「history」這個可能值
wgArticleId	內容頁面編號，不存在時值為0，可以用於判斷是否是內容頁面且頁面是否已建立	需要注意查看歷史和差異時值為0
wgCanonicalSpecialPageName	標準化的特殊頁面名，也可被wgPageName取代，主要用於不同MediaWiki站點間的代碼通用，非必需	可用，而且多了「History」和"MobileDiff"等可能的取值
wgCategories	當前閱讀的歷史版本所屬的分類，不含名字空間，下劃線顯示為空格，且總是包含隱藏分類。繁簡規則一般遵從實際分類頁面，但似乎偶有例外	除非已執行MobileCategories小工具，否則不可用。另外桌面版的空值為[]，手機版的空值為null，注意可能的bug
wgCurRevisionId	頁面最新的版本編號，不存在時值為0	在歷史和差異頁面不可用
wgIsArticle	是否是內容頁面（包含由某個頁面的Wikitext原始碼解析生成的HTML，可能是歷史頁面和差異下方的歷史頁面）	由於差異頁面不可同時顯示歷史頁面，此時不可用
wgIsRedirect	最新版本是否是重定向頁面	在歷史和差異頁面不可用
wgIsProbablyEditable	是否可能可以編輯	在歷史和差異頁面不可用
wgNamespaceNumber	名字空間編號	在歷史和差異頁面會顯示為-1
wgPageContentModel	頁面內容模型，特殊頁面為「wikitext」	由於歷史和差異是特殊頁面，會錯誤地顯示為「wikitext」
wgPageName	頁面名稱，空格顯示為下劃線	在歷史和差異頁面不可用
wgRedirectFrom	跳轉自重定向時為對應的重定向頁，空格顯示為下劃線	可用
wgRelevantPageName	關聯的頁面名稱，空格顯示為下劃線	可以用於歷史和差異頁面，此時效果與桌面版一致
wgRelevantArticleId	關聯的內容頁面編號，不存在時值為0	可以用於歷史和差異頁面，此時效果與桌面版一致
wgRelevantUserName	關聯的用戶名	使用者貢獻頁面不可用
wgRelevantPageIsProbablyEditable	關聯的頁面是否可能可以編輯	可以用於歷史和差異頁面，此時效果與桌面版一致
wgRestrictionEdit	編輯保護，不存在的頁面（含受保護的標題）或特殊頁面為null，存在的內容頁面受全保護時為["sysop"]，受半保護時為["autoconfirmed"]，未保護為[]；不包含名字空間保護和級聯保護	在歷史和差異頁面不可用，另外未保護的內容頁面為["*"]
wgRestrictionMove	移動保護，不存在的頁面或特殊頁面為null，存在的內容頁面受全保護時為["sysop"]，受半保護時為["autoconfirmed"]，未保護為[]；不包含名字空間保護和級聯保護	在歷史和差異頁面不可用
wgRevisionId	當前顯示的頁面版本的編號，不存在時值為0。注意和index.php的oldid參數可能不同	由於差異頁面不可同時顯示歷史頁面，此時不可用
wgTitle	不含名字空間的頁面名稱	在歷史和差異頁面不可用
wgUserEditCount	當前用戶的編輯次數	可用
wgUserGroups	當前用戶所屬的用戶組，未登入時為["*"]	可用
wgUserLanguage	當前用戶使用的界面語言	可用
wgUserName	當前用戶的用戶名	可用
wgUserRegistration	當前用戶的註冊時間，顯示為毫秒數；可以使用mw.user.getRegistration()方法替代，該方法會生成Date對象	可用
wgUserVariant	當前用戶閱讀頁面時的內容語言，在不可更改內容語言的頁面總是為該用戶的默認內容語言	可用
wgDiffOldId	差異頁面位於左側的版本的編號	不可用
wgDiffNewId	差異頁面位於右側的版本的編號	不可用

mw.hook()

這個方法是LLWiki建立異步JS框架的重要一環。常用以下兩個方法：

• mw.hook(hook).fire(data): 用於喚起一個Hook事件，其中data為傳遞給事件處理程序的可選參數。
• mw.hook(hook).add(handler): 用於處理一個Hook事件，handler為該事件處理函數，參數傳遞自mw.hook().fire()方法。

這個方法應與jQuery的event delegation和各Promise對象結合使用，以在恰當的時機執行恰當的函數。以下列舉LLWiki常用的Hook事件。

Hook名稱	說明
MediaWiki預定義的Hook
postEdit	一次非空編輯提交成功，一般發生在自動重載頁面後，可以搭配mw.config.get( 'wgPostEdit' )。需要注意各類編輯小工具提交編輯後的頁面重載均未適配這個事件
structuredChangeFilters.ui.initialized	近期變更、相關變更和監視清單頁面的過濾器加載完成，一般至多發生一次
wikipage.categories	頁面下方的div#catlinks加載完成。特殊頁面或沒有添加任何分類時也能觸發，因為此時#catlinks仍然存在只是隱藏起來
wikipage.collapsibleContent	某個或某組mw-collapsible類的元素添加摺疊JS完成
wikipage.content	最常用的Hook，表示頁面內容（一般即div#mw-content-text）加載完成，幾乎無處不在，與$.ready最大的區別在於這個事件可能多次觸發
wikipage.diff	差異（一般即table.diff）加載完成
wikipage.editform	編輯區加載完成，需要注意此時WikiEditor的工具欄可能尚未加載完成
codeEditor.configure	切換至CodeEditor
LLWiki定義的Hook
code.prettify	代碼高亮完成
codemirror.config	CodeMirror擴展的設置下載完成
hotcat.ready	HotCat小工具加載完成
local.comments	簽名時間替換為本地時區
mobile.menu	手機版的左側主菜單加載完成
to.bottom	添加滾動至底部的按鈕
transclusion.preview	用於預覽潛入頁面的編輯區加載完成
wikiplus.dialog	打開Wikiplus小工具的對話框

mw.loader

mw.loader包含了很多用於ResourceLoader的方法。

• mw.loader.addStyleTag()，用於在header的末尾插入一個<style>。由於返回的是一個HTML元素，後續操作不如mw.util.addCSS()返回的StyleSheet對象方便，但在不需要後續操作的場合可以不用加載mediawiki.util模塊。由於mediawiki.util在LLWiki的廣泛使用，這個方法幾乎沒有任何優點。
• mw.loader.getScript()，用於加載外部JS腳本，相比mw.loader.load()方法優點在於會返回一個Promise對象。
• mw.loader.getState()，用於獲取模塊的當前狀態，不可用的模塊返回null，可用但未加載的模塊返回'registered'，可用且正在加載的模塊可能返回'loaded'或'loading'，已加載完成的模塊返回'ready'。注意加載完成的模塊未必已經執行完。
• mw.loader.load()，用於加載模塊、其他JS或其他CSS，加載模塊時參數為模塊名或一個模塊名構成的數組，加載JS或CSS時填寫url，加載CSS還需要額外填寫第二參數'text/css'。缺點在於不會返回一個Promise對象。
• mw.loader.using()，用於加載模塊，相比mw.loader.load()方法優點在於會返回一個Promise對象，任一模塊加載失敗即返回rejected。

mw.notify()

調用這個方法可以在桌面版的右上角、手機版的上方顯示一個泡泡通知。LLWiki一般使用這個方法取代window.alert()或OO.ui.alert()。

方法mw.notify(message, options)接受兩個參數。第一個必需參數message指定通知內容，可以是字符串、HTML元素對象或元素對象數組、jQuery對象或mw.message對象；第二個可選參數options則指定自定義選項，是一個JS對象。

options中可自定義的選項有：

• autoHide：布爾值，決定通知是否會自行消失。默認為true。
• autoHideSeconds：如果啟用了autoHide（如默認情形），則指定通知自行消失的時間。默認為'short'（5秒），可以指定為'long'（30秒）。
• tag：字符串，指定通知的標籤，類似於HTML的ID。如果發送多個擁有同一個tag的通知，會導致之前的通知被後來的在原位覆蓋。
• title：標題。如果指定，則會於內容上方加粗顯示。
• type：字符串，指定通知的種類。除默認效果外其他可選類型為'success'、'warn'和'error'。

mw.now()

這個方法理論上和Date.now()差不多，但實際測試表明和Date.now()的取值不同，因此請勿混合使用。非必需，基本可以完全被Date.now()替換。

jquery

jquery是任何頁面都會預加載的兩個環境模塊之一，尤其在DOM操作和Ajax請求方面功能強大，非常推薦在JS編程之前預先熟悉API文檔。考慮到mw.loader已經集成了不少的常用Ajax方法，這裡主要推薦熟練掌握DOM相關的內容，包括事件、DOM操作、選擇器和遍歷。特別需要提醒的是濫用htmlString有造成XSS的風險，因此請儘量使用如$('<p>', {html: $('<a>', {text: '文字', href: 'https://llwiki.org'})})或$('<p>').append( $('<a>').text('文字').attr('href', 'https://llwiki.org') )等語法進行規避。

因未被mw.loader包含而可能用到的Ajax方法主要為$.getJSON()，需要注意在MW的默認設置下調用jQuery的Ajax方法必須手動設置{cache: true}。

另外jQuery也提供了一些工具方法，可以用於緩解ResourceLoader的JS模塊不允許使用ES6語法的問題，或是方便鍵值對相關的語句的書寫，或是方便連鎖。比如用$.extend()方法代替...算符、用$.each(obj, (key, val) => {})方法代替for (const key in obj) {}等。

應用jQuery時可能出現的一些常見錯誤列舉如下：

• 混淆.attr()方法和.prop()方法。
• 混淆jQuery對象的.data()方法和HTML元素的.dataset屬性。
• 使用.toggle()、.fadeToggle()等方法時不慎破壞較複雜的CSS布局。
• 錯誤使用.remove()、.clone()等方法造成丟失數據和事件處理程序。
• 混淆event.target、event.currentTarget、event.delegateTarget和this關鍵字。
• 混淆$.when()方法和Promise.all()方法的參數格式和回調函數。

mediawiki.api

這個模塊提供了一系列方法用於簡化API請求。使用這一模塊時，需要首先建立一個mw.Api對象，常用語法為const api = new mw.Api();。以下列舉這個mw.Api對象常用的方法，沒有出現在以下列表中的方法可能不僅是不推薦使用，而是因為未適配中文的繁簡轉換而不應在LLWiki使用。

• api.get()，這是最基礎的兩個方法之一，用於提交類型為GET的Ajax請求，參數基本與api.php的參數一致，區別在於返回的格式已經限定為JSON對象，即可省略{format: "json"}這一參數。API請求的參數列表詳見API文檔，這裡特別推薦一下generator參數的強大功能和{formatversion: 2}這個參數。
• api.post()，這是最基礎的兩個方法之一，用於提交類型為POST的Ajax請求，用法與api.get()方法高度相似。一般情形下，{action: 'query'}的請求應該使用api.get()方法以充分利用瀏覽器緩存等優點；但如果請求的數據量過大，可能不得不使用api.post()方法代替。
• api.postWithToken()，提交改動時一般使用這個快捷方法而非傳統的api.post()，但在很多情形下都可以替換為下述更為方便的方法，只有用於{action: 'patrol'}時難以替代。
• api.postWithEditToken()，相當於api.postWithToken('csrf', params)，主要用於提交編輯。大部分情況下不推薦使用api.edit()方法替代，因為api.edit()在大多數應用場合會造成重複而不必要的{action: 'query', prop: 'revisions'}請求。為了避免編輯衝突，在LLWiki請儘可能使用mw.safeEdit()方法。另外在建立新頁面（{createonly: 1}或直接應用api.create()方法）時，請務必先檢查對應的繁簡中文標題是否已經存在。
• api.newSection()，這個方法相比api.postWithEditToken()可以進一步簡化添加新章節的代碼。
• api.rollback()，相當於api.postWithToken('rollback', params)，用於回退。
• api.watch()，相當於api.postWithToken('watch', params)，用於監視。
• api.unwatch()，相當於api.postWithToken('watch', params)，用於取消監視。
• api.upload()，相當於api.postWithEditToken()的{action: 'upload'}。注意這個方法只能上傳本地文件，需要通過url上傳的請使用api.postWithEditToken()方法。
• api.parse()，用於解析HTML的快捷方法，常用於生成預覽。如果要獲得現存頁面的HTML，還需要加載mediawiki.Title，此時建議可以直接使用標準的api.get()方法代替。

mediawiki.util

mediawiki.util提供了很多非常方便的方法，可以用於滿足形形色色的需要。

• mw.util.addCSS()，相比mw.loader.addStyleTag()方法，因為返回值是一個StyleSheet對象而更便於後續動態操作。
• mw.util.addPortletLink()，實際上並不如直接使用jQuery自由度更大，但這個方法可能會出現在一些從其他維基導入的小工具里，不推薦使用。
• mw.util.debounce()，這個方法用於降低一個函數被調用的頻率，常見的比如scroll事件。
• mw.util.escapeRegExp()，mw.util還有其他的轉義方法，但應用較少，不再贅述。
• mw.util.getParamValue()，提取php參數，能夠滿足可能存在的各種奇怪情形，不建議使用自己寫的正則匹配替代。
• mw.util.getUrl()，獲取頁面對應的相對網址，一般來說使用mw.config.get('wgScript') + '/' + pageName即可。但如果頁面名稱中含需要轉義的字符（如/、?和&），使用這個方法還是挺方便的。
• mw.util.wikiUrlencode()，非常好用的方法，相比encodeURIComponent不會轉義/，相比encodeURI則增加了對?和&的轉義，是轉義頁面名稱的最佳選擇，同時在用做url時也比mw.util.getUrl()方法有更大的自由度。

LLWiki添加的全局變量和方法

window.wgULS()和window.wgUCS()

mw.gadgets

mw.request

mw.widget

mw.windowManager

mw.standardQuery()

mw.apiFailure()

mw.safeEdit()

mw.resizeLyrics()

ESLint

CodeEditor使用ESLint標註可能存在的語法問題。LLWiki並未在後台預先規定太多規則，目前比較常用的僅是在"use strict";的基礎上添加/*global mw, $, OO, wgULS*/或類似語句註明全局變量。特別要注意ESLint並不會對大多數JS模塊不允許使用的ES6語法（async/await語法是已知的唯一例外）作出警告（詳見#ResourceLoader和JS模塊），因此請勿過度依賴這一功能來除錯。

手機版

手機版CSS

手機版LLWiki使用Minerva Neue皮膚，與桌面版的Vector皮膚相比，不僅界面有很大差異，眾多基礎HTML元素也都添加了不同的CSS樣式。為了適配窄屏設備，Minerva皮膚還添加了大量基於@media的規則，一般以設備寬度720px為分界使用不同的樣式。以下著重介紹<table>和<img>這兩種需要CSS修正的重災區。

手機版CSS很多時候依賴外層容器的content類來生效，與此同時#mw-content-text .mw-parser-output的外層結構也同樣有效，設計各種基於API的快速編輯工具（如Wikiplus等）的預覽界面時需要考慮。

表格

對於<table>元素及其子節點，手機版已知會自動添加以下樣式：

table, caption, tbody, tfoot, thead, tr, th, td {
	font-size: 100%;
}
table {
	border-collapse: collapse;
}
.content table {
	margin: 1em 0;
	overflow: auto;
	overflow-y: hidden;
	overflow-x: auto;
}
@media only screen and (max-width: 720px) {
	.content table {
		display: block;
		width: 100% !important;
	}
}

這裡重點說明一下第二和第四條規則造成的影響。第二條規則使得表格的外層邊框、行邊框和單元格邊框合併，可能造成一系列關於邊框的CSS規則出現不符合預期的表現，尤其是<table>的cellspacing屬性會無法生效。因此一般建議避免使用cellspacing這一HTML屬性，改為使用CSS中的border-spacing。另外，在需要border-spacing或border-radius等樣式時，請同時指定border-collapse: separate;以使手機版生效。

第四條規則的本意是在窄屏上<table>元素不會將頁面撐得過寬，但這同時會造成外層的<table>和內層的<tbody>分離。特別是如果外層<table>規定了邊框或背景色時，很容易看出樣式的錯誤。為此一般需要主動指定display: table;以修復這一問題，LLWiki有很多預定義的表格CSS類也都添加了這一規則。但這樣修改的話又會重新面臨過寬的表格將整個頁面撐大的問題。LLWiki現定義了table-wrapper類，用於套在寬表格外：<div class="table-wrapper">，這個外層容器會在窄屏上通過overflow-x: auto;限制裡面的表格寬度。

測試帳戶

如果管理員需要一個沒有自確權限的測試帳戶用於濫用過濾器測試、小工具測試等，可以臨時啟用6號濫用過濾器來移除某個測試帳戶的自確權限。這個濫用過濾器的使用語法非常簡單，請根據樣例修改為對應的用戶名即可，這裡不再贅述。