Extension:Popups(弹出窗口)

Popups(弹出窗口,在Special:Version中稱為預覽)扩展會顯示頁面以及參考資料的預覽,當將滑鼠懸停在某個條目或參考文獻的連結上時。前者是由條目內容的摘要所組成、而後者會顯示參考文獻的完整內容。

此擴充功能由設計團隊發起,靈感源自廣受歡迎的导航弹出窗口小工具。目前此功能預設啟用於所有維基百科,適用於未登入使用者。有關擴充功能運作方式的說明,以及在維基媒體專案中使用的更多資訊,請參閱頁面預覽。

引用预览功能最终被加入,目的在于实现德语社群的技術愿望。更詳細的說明和更多使用資訊,請參考参考文献预览 。

當與預設的mwApiPlain网关一起使用时,本扩展硬性依赖于Extension:TextExtracts 和Extension:PageImages(页面图片) 。 此外,還存在對 Extension:EventLogging 和 扩展:WikimediaEvents (用於儀器化)的可選依赖關係。

• 安装依存组件。

• 下载文件,并解压Popups文件夹到extensions/目录中。
  开发者和代码贡献人员应改从Git安装此扩展,输入:

  cdextensions/
  gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/Popups
  

• 請新增下列代码到您的LocalSettings.php 文件的底部:

  wfLoadExtension( 'Popups' );
  

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

最终配置的示例

wfLoadExtensions( [
 'TextExtracts',
 'PageImages',
 'Popups'
] );
$wgPopupsHideOptInOnPreferencesPage = true;

页面预览弹出窗口会显示一张图像(如果有的话)和一小段文字摘要。

图片来源于Extension:PageImages(页面图片) ,该图片返回与文章相关的单个最合适的缩略图。 它忽略维护模板,小作品,旗帜图标等。

可以使用$wgPopupsRestGatewayEndpoint透過任何與頁面內容服務摘要端點相容的API來設定頁面預覽。 对于第三方,我们鼓励使用页面内容服务来在您本地的wiki使用弹出窗口。

您也可以使用Extension:TextExtracts 扩展。 这个扩展有各种警告,我们不积极支持使用这个API。

此擴充功能目前只有一個渲染器,用於一般頁面。

您可以針對不同類型的頁面或參考輕鬆新增新的呈現器。

我們需要使用下列方法建立一個新物件:

• init
• createPopup
• getOffset
• getClasses
• processPopup

您可以在ext.popups.renderer.article.js或在這個新增引用渲染器的補丁中看到這些方法的詳細資訊。

每個專案都不同,預覽中顯示的內容也高度取決於您wiki中的內容。

弹出窗口擴充功能已針對類似維基百科的內容(例如wikitext)進行最佳化。

如果您的wiki使用不同種類的內容處理器(例如像Wikibase 的情況),它將需要提供自己的API。

API可以用任何語言撰寫,但API的回應必須符合Specs/Summary/1.2.0 中定義的規格。

定義新的API並不在弹出窗口擴充功能的範圍內。

定義完成後,您可以使用$wgPopupsRestGatewayEndpoint的組態選項來設定頁面預覽以便指向您的API。

• 使用Translate 擴充功能的使用者請注意,頁面預覽要求以頁面內容語言進行預覽。如果預覽包含完整的可翻譯區塊,則會進行翻譯。但是,如果預覽包含不完整的可翻譯區塊--例如說,因為句子被切掉了--則不會被翻譯,並會以頁面的內容語言顯示。如果您觀察到這種行為,那麼您應該考慮在您的引導部份標記個別的句子。 T167852 針對技術讀者,但有更多關於基本問題的資訊。
• 較長的數學公式在預覽中被截斷--較長的數學或化學公式(公式寬度大於預覽寬度)在預覽中顯示為截短。我們無法加入漸層以顯示公式是在文章本身上繼續的。
• 小檔案可能會出現在「頁面資訊」(action=info)中,但不會出現在「彈出式視窗」中。 這裡設定了一些要求 - 對於肖像圖像:精確(最小)高度為250px,最大寬度為203px;對於橫向圖像:精確(最小)寬度為320px且最大高度為200px。^[1] 若要顯示,影像必須能夠成為較大或等於這些「確切」尺寸的縮圖。 (如果您要裁剪大型圖片來做文章的主圖,請確定您所建立的圖片不小於指定的尺寸)。
• 某些頁面的預覽彈出式視窗可能僅顯示以下文字:There was an issue displaying this preview。 其中一個原因在於 TextExtracts 擴充功能未能為該頁面找到任何「引言」文字,這種情況可能發生於條目的開頭包含有特定實體時,例如有使用 PortableInfobox 擴充功能所建立的資訊框。 解決此問題的替代方案是設定 $wgPopupsTextExtractsIntroOnly = false;,儘管此舉可能導致預覽中出現不需要的實體,例如非引言部分的標題。 TextExtracts組態變數 $wgExtractsRemoveClasses 可用於從預覽中清除這些不需要的實體,但此操作也會對所有其他TextExtracts API的使用者將它們隱藏。

在MediaWiki 1.40中,擴充功能與皮肤可以使用自己的自訂預覽類型來擴充頁面預覽的機能。 它的做法是在 extension.json 或 skin.json 檔案中註冊 PluginModules 屬性,指向可註冊預覽類型的 ResourceLoaderModule。

{
"attributes":{
"Popups":{
"PluginModules":[
"skins.skinjson.popup"
]
}
}
}

外掛模組應匯出何時顯示預覽(透過選擇器)、以及如何擷取預覽資料(透過閘道庫)的相關資訊。 選擇器應匹配某個具有data-title屬性的元素。 data-title 屬性將被傳遞至 fetchPreviewForTitle 函式。

module.exports={
// 一個獨一無二的ID,代表您的預覽類型。
type,
// 符合自訂預覽類型的CSS選擇器
selector:'.mycustomselector',
// 閘道器
gateway:{
fetchPreviewForTitle:(title,el)=>{
constdeferred=$.Deferred();
deferred.resolve({
title:'Hello world',
extract:[
`Hi`
],
url:'https://www.mediawiki.org/wiki/Extension:Popups',
type,
languageCode:'en',
languageDirection:'ltr',
thumbnail:undefined,
pageId:-1
});
returndeferred;
}
}
};

以實際應用範例而言,Extension:Math(数学) 提供smath工具提示,而 Extension:Cite(引用) 則提供參考預覽功能。

在撰寫本文時,這樣做是弊大於利。基本上,這可以歸結為減少觸摸區域以便閱讀完整文章。一旦頁面預覽部署在英文和德文維基百科上了,請隨時重新開啟此任務、然後重新啟動討論,但在目前我們並無此計劃。

請參閱Extension:页面图片#图像选择。

任何標示為noexcerpt類別的元素都會從摘要中剔除。

任何標示為noexcerpt、mw-ref、reference、noprint、nomobile、或sortkey類別的HTML元素都會從摘要中移除。 如果要在摘要中顯示文字,在任何情況下都不應該在文章開頭部分使用的任何範本中使用這些類別。

這些是由摘要REST API(維基媒體製作的wiki)或TextExtracts API(如果您的wiki是使用預設的mwApiPlain閘道)提供的。

在Phabricator中的T91344有一個很好的討論。如果您對此有任何意見,或看到任何與此相關的問題,請在那裡告訴我們。

彈出式視窗只會出現在內容命名空間中的頁面連結。 這是彈出式視窗的限制;而TextExtracts可從其他命名空間看得到。 您可以將更多命名空間追加到$wgContentNamespaces 中來解決這個問題。

• MediaWiki.org上的頁面預覽的帮助頁面和中央反馈頁面。
• MediaWiki.org上的參考預覽的帮助頁面和中央反馈頁面。
• 元維基上的參考預覽的主專案頁面
• 相關研究:維基媒體效能團隊/撰寫彈出式視窗:最佳實踐

The quickest way (last updated March 2026) to set up Popups is to install Extension:MobileFrontendContentProvider and to add the following code to LocalSettings.php

Visiting localhost/wiki/Paris should render Paris from English Wikipedia with working page previews.

wfLoadExtension( 'MobileFrontendContentProvider' );
wfLoadExtension( 'Popups' );
$wgThumbnailStepsRatio = 1;
$wgThumbnailSteps = [ 20, 40, 60, 120, 250, 330, 500, 960, 1280, 1920, 3840 ];
$wgPopupsRestGatewayEndpoint = 'https://en.wikipedia.org/api/rest_v1/page/summary/';
$wgPopupsGateway = 'restbaseHTML';

• Extensions maintained by Reader Teams/zh
• Extensions maintained by Reader Growth/zh
• Extensions maintained by Reader Teams - Level Pending/zh
• Stable extensions/zh
• Skin extensions/zh
• BeforePageDisplay extensions/zh
• GetPreferences extensions/zh
• MakeGlobalVariablesScript extensions/zh
• ResourceLoaderGetConfigVars extensions/zh
• GPL licensed extensions/zh
• Extensions in Wikimedia version control/zh
• All extensions/zh
• Pages using deprecated NoteTA template
• Extensions used on Wikimedia/zh
• Extensions included in BlueSpice/zh
• Extensions included in Canasta/zh
• Extensions included in Fandom/zh
• Extensions included in Miraheze/zh
• Extensions included in MyWikis/zh
• Extensions included in ProWiki/zh
• Extensions included in Telepedia/zh
• Extensions included in Weird Gloop/zh
• Extensions included in wiki.gg/zh
• Popup extensions/zh

• Extensions with manual MediaWiki version/zh