Extension:弹出窗口

关于這是由扩展所提供的功能，参见：Special:MyLanguage/Page Previews。

MediaWiki扩展手册

Popups 发行状态： 稳定版
实现	皮肤
描述	在用户悬停在条目的链接及腳註標記时显示弹出窗口
作者	Prateek Saxena (user:Prtksxna), Yair Rand, Sam Smith, Joaquín Oltra Hernández, Bahodir Mansurov, Jon Robson, Piotr Miazga, Jeff Hobson WMDE Engineering
MediaWiki	1.37+
PHP	5.6+
许可协议	GNU通用公眾授權條款2.0或更新版本
下載	下載扩展 Git [?]: 浏览存储库 (Phabricator · GitHub) Gerrit代码复核 Git提交日誌 下載原始碼(tarball壓縮)
示例	English Wikipedia
参数 $wgPopupsVirtualPageViews $wgPopupsTextExtractsIntroOnly $wgPopupsStatsvSamplingRate $wgPopupsRestGatewayEndpoint $wgPopupsHideOptInOnPreferencesPage $wgPopupsPageDisabled $wgPopupsGateway $wgPopupsConflictingNavPopupsGadgetName
使用的函数钩 BeforePageDisplay GetPreferences MakeGlobalVariablesScript ResourceLoaderGetConfigVars
季度下載量	211 (Ranked 12th)
正在使用的公开wiki数	947 (Ranked 282nd)
前往translatewiki.net翻譯Popups扩展
問題	开启的任务 · 报告错误

當將滑鼠懸停在文章或參考文獻的連結上時，弹出窗口（Popups，在Special:Version中稱為預覽）扩展會顯示頁面和參考資料的預覽。前者由條目內容的摘要所組成，後者顯示參考文獻的完整內容。

該擴充功能是設計團隊的一項創舉，靈感來自流行的導航弹出窗口小工具。目前這項功能在所有維基百科上都是預設提供給已登出的使用者。有關擴充功能的說明，以及在維基媒體專案上使用的更多資訊，請參考页面预览。

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

依存组件

當與預設的mwApiPlain网关一起使用时，本扩展硬性依赖于Extension:TextExtracts 和Extension:页面图片 。 测试功能 也有可选的依赖项（如果你想作为 Beta 功能启用参考预览），以及 Extension:EventLogging 和 扩展:WikimediaEvents （用于检测）。

安裝

• 安装依存组件。

• 下载文件，并将解压后的Popups文件夹移动到extensions/目录中。
  开发者和代码贡献人员应从Git安装扩展，输入：cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Popups
• 将下列代码放置在您的LocalSettings.php 的底部：

  wfLoadExtension( 'Popups' );
  

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

最终配置的示例

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

配置

选项	默认值	帮助文档
$wgPopupsVirtualPageViews	false	擴充功能是否應該記錄虛擬的頁面瀏覽。
$wgPopupsHideOptInOnPreferencesPage	false	是否应在首选项页面上隐藏启用/禁用页面预览的选项。
$wgPopupsOptInDefaultState	1	老账户的页面预览可见性默认值。必须是字符串，以便与beta功能设置兼容。 有关更多信息，请参阅T191888。 此值在內部轉換為布林類型。 因此，大於等於2的值其意義等於1。
$wgPopupsOptInStateForNewAccounts	1	針對新创建帐户，默认的页面预览的可见性（1.32~1.43版）。 有关更多信息，请参阅T191888。
$wgPopupsConflictingNavPopupsGadgetName	'Navigation_popups'	本地導覽弹出窗口小工具的名称用作在MediaWiki:Gadgets-definition 中的标识符。 此小工具与页面预览不兼容。 对于已启用了小工具的用户，该扩展将自行禁用。
$wgPopupsConflictingRefTooltipsGadgetName	ReferenceTooltips	本地参考文献提示工具 小工具名称用作在MediaWiki:Gadgets-definition 中的标识符。 此小工具与参考预览不兼容。 对于已启用了小工具的用户，参考预览将自行禁用。
$wgPopupsGateway	'mwApiPlain'	用于获取弹出窗口数据的网关。可用选项：mwApiPlain, restbasePlain, restbaseHTML。在src/gateway/page.js中提供了完整且始终最新的列表。
$wgPopupsRestGatewayEndpoint	'/api/rest_v1/page/summary/'	指定摘要来源的REST端点。 端点必须符合 Specs/Summary/1.2.0 的规格。
$wgPopupsReferencePreviews	true	在開發過程中停用參考預覽的臨時功能旗標。
$wgPopupsReferencePreviewsBetaFeature	true	参考预览是否应作为Beta功能提供。如果为false，则默认情况下为所有用户启用参考预览。
$wgPopupsStatsvSamplingRate	0	将性能数据记录到 statsv 的采样率。
$wgPopupsPageDisabled	Several special pages. See extension.json for the full list.	不应显示弹出窗口的页面列表。 包含子页面。 这些页面受 wiki 的 HTML 缓存策略的约束。 可能需要清除这些页面才能查看此配置变量的效果。 每个排除的页面都应由规范名称定义，例如：Special:Userlogin。

页面预览内容

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

图片

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

文本

页面预览可以通过配置$wgPopupsRestGatewayEndpoint使用API，该API需要符合页面内容服务摘要端点规范。对于第三方，我们鼓励使用页面内容服务来在您本地的wiki使用弹出窗口。

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

渲染器

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

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

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

• init
• createPopup
• getOffset
• getClasses
• processPopup

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

頁面預覽 API

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

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

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

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

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

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

已知問題

• 使用Translate 擴充功能的使用者請注意，頁面預覽要求以頁面內容語言進行預覽。如果預覽包含完整的可翻譯區塊，則會進行翻譯。但是，如果預覽包含不完整的可翻譯區塊--例如說，因為句子被切掉了--則不會被翻譯，並會以頁面的內容語言顯示。如果您觀察到這種行為，那麼您應該考慮在您的引導部份標記個別的句子。 T167852 針對技術讀者，但有更多關於基本問題的資訊。
• 較長的數學公式在預覽中被截斷--較長的數學或化學公式（公式寬度大於預覽寬度）在預覽中顯示為截短。我們無法加入漸層以顯示公式是在文章本身上繼續的。
• 小檔案可能會出現在「頁面資訊」（action=info）中，但不會出現在「彈出式視窗」中。 這裡設定了一些要求 - 對於肖像圖像：精確（最小）高度為250px，最大寬度為203px；對於橫向圖像：精確（最小）寬度為320px且最大高度為200px。. 若要顯示，影像必須能夠成為較大或等於這些「確切」尺寸的縮圖。 (如果您要裁剪大型圖片來做文章的主圖，請確定您所建立的圖片不小於指定的尺寸)。
• The preview popup for some pages may contain only the text: There was an issue displaying this preview. One of the reasons for this is the TextExtracts extension failing to find any "intro" text for the page, which can happen if the article begins with certain entities, such as an infobox created with the PortableInfobox extension. A work-around for this is to set $wgPopupsTextExtractsIntroOnly = false; although this can cause the preview to contain unwanted entities, such as the titles for non-intro sections. The TextExtracts configuration variable $wgExtractsRemoveClasses may then be used to clean up those unwanted entities from the preview, though this will also hide them from all other users of the TextExtracts API.

可擴展性

在MediaWiki 1.40中，擴充功能與皮肤可以使用自己的自訂預覽類型來擴充頁面預覽的機能。

它的做法是在 extension.json 或 skin.json 檔案中註冊 PluginModules 屬性，指向可註冊預覽類型的 ResourceLoaderModule。

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

外掛模組應匯出何時顯示預覽（透過選擇器）、以及如何擷取預覽資料（透過閘道庫）的相關資訊。 The selector should match an element which has a data-title attribute. The data-title attribute will be passed to the fetchPreviewForTitle function.

module.exports = {
        // 一個獨一無二的ID，代表您的預覽類型。
        type,
        // 符合自訂預覽類型的CSS選擇器
        selector: '.mycustomselector',
        // 閘道器
        gateway: {
                fetchPreviewForTitle:  ( title, el ) => {
                	const deferred = $.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
                	} );
                	return deferred;
                }
        }
};

For real world examples, Extension:數學 provide smath tooltips and Extension:引述 provides reference previews.

常见问题

為什麼我不能從預覽中複製和貼上文字？

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

我要如何變更預覽時看到的影像？

請參閱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上的參考預覽的帮助頁面和中央反馈頁面。
• 元維基上的參考預覽的主專案頁面
• 相關研究：維基媒體效能團隊/撰寫彈出式視窗：最佳實踐