Extension:PageImages（页面图片）

**MediaWiki扩展手册**
PageImages; 发行状态：稳定版
实现	API, 解析器扩展
描述	將代表著一個頁面的圖片的信息儲存下來
作者	Max Semenik (MaxSem留言)
最新版本	持續更新中
兼容性政策	快照跟随MediaWiki发布。 master分支不向后兼容。
MediaWiki	1.37+
PHP	7.3.19+
数据库更改	否
	参数 $wgPageImagesOpenGraphFallbackImage; $wgPageImagesExpandOpenSearchXml; $wgPageImagesDenylistExpiry; $wgPageImagesNamespaces; $wgPageImagesDenylist; $wgPageImagesScores; $wgPageImagesLeadSectionOnly; $wgPageImagesOpenGraph; $wgPageImagesAPIDefaultLicense;
	使用的函数钩 ApiOpenSearchSuggest; BeforePageDisplay; InfoAction; ParserAfterTidy; ParserModifyImageHTML; ParserTestGlobals; SearchResultProvideThumbnail; SpecialMobileEditWatchlist::images;
许可证	WTFPL 2.0
下載	下載扩展 ; Git [?]: 浏览存储库 (Phabricator · GitHub); Gerrit代码复核; Git提交日誌; 下載原始碼（tarball壓縮）;
	前往translatewiki.net翻譯PageImages扩展
問題	开启的任务 · 报告错误

This page is a translated version of the page Extension:PageImages and the translation is 96% complete.

此扩展处于代码监管权审核阶段，目前未积极维护。 (T252249) 这一阶段内不会考虑新特性的请求。

PageImages（页面图片）收集页面中的图片使用信息。

扩展目的为回传一张与条目相联系的最合适缩略图。

頁面圖片也為wiki上的條目提供OpenGraph協定的元資料，提供給例如Facebook等第三方軟體去提取。

安裝

此扩展随附于MediaWiki 1.34及更新版本，因此您無需下載它。但其余的配置的指示仍须依循執行。

下载文件，并解压PageImages文件夹到extensions/目录中。
开发者和代码贡献人员应改从Git安装此扩展，输入：
```
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageImages
```
請新增下列代码到您的LocalSettings.php 文件的底部：
```
wfLoadExtension( 'PageImages' );
```
按需求配置
若要將頁面圖片初始指定給頁面，請執行擴充功能的維護目錄中的initImageData.php腳本 (/path/to/extensions/PageImages/maintenance/)
完成 – 請导航至您的wiki上的Special:Version，以验证此扩展已成功安装。

配置

$wgPageImagesDenylist是一个图片拒絕列表的來源数组。被列出的文件永远不会被选为页面图片。例如：

$wgPageImagesDenylist = [
	// 本地wiki上的页面
	[
		'type' => 'db',
		'page' => 'MediaWiki:Pageimages-denylist',
		'db' => false,
	],
	// 维基共享资源上的页面，适用于可直接访问其数据库的其它维基媒体项目
	[
		'type' => 'db',
		'page' => 'MediaWiki:Pageimages-denylist',
		'db' => 'commonswiki',
	],
	// 维基共享上的页面，适用于采用网络访问的第三方网站
	[
		'type' => 'url',
		'url' => 'http://commons.wikimedia.org/w/index.php?title=somepage&action=raw',
	],
];

可以同時使用不止一個來源。

拒絕列表應該包含檔案的wiki链接。其餘的內容則無關緊要（可包含到其他頁面的連結）。例如：

* [[:File:First denylisted file.png]]
* [[:File:Second denylisted file.jpeg]]
...

请记住，使圖片添加至頁面的檔案連結不會起作用（这些文件會被拒绝是有原因的，对吧？），所以別把链接前的:忘记了。

名称	描述	預設
$wgPageImagesDenylistExpiry	决定列表保持被缓存的时长，单位为秒。	15 * 60 (15 minutes)
$wgPageImagesExpandOpenSearchXml	如果设置为`true`，PageImages将使用自己的、更准确的结果覆盖掉`opensearch` API模块中的图片检测。	`false`
$wgPageImagesNamespaces	PageImages起作用的的命名空间数组。變更之後，您必須執行refreshLinks.php 來產生這些命名空間的頁面圖片資訊（您最好可以使用`--namespace`參數來只處理受影響命名空間上的頁面，因為該腳本非常耗費資源）	`NS_MAIN`
$wgPageImagesOpenGraph	启用或停用OpenGraph元標籤（如果有其他擴充功能管理這些標籤，可能會很有用）（1.39+）。	`true`
$wgPageImagesOpenGraphFallbackImage	一個後備圖片的URL，當頁面上沒有圖片可以展示時會顯示該圖片。	`false`

升級至MediaWiki 1.37以上的注意事項

自MediaWiki 1.37起，$wgPageImagesBlacklist和$wgPageImagesBlacklistExpiry已分別更名為$wgPageImagesDenylist和$wgPageImagesDenylistExpiry。自MediaWiki 1.37起，$wgPageImagesDenylist的預設頁面的值已從MediaWiki:Pageimages-blacklist變為MediaWiki:Pageimages-denylist。

並沒有加入向後相容的程式碼來接受舊的名稱，所以您應該在升級時改變變數名稱、或是事先定義這兩個變數，為後續的升級預先準備。如果您已向您wiki上的MediaWiki:Pageimages-blacklist加入了內容，您應該將它重命名到新的名称。同時設定$wgPageImagesBlacklist（舊變數名稱）為新頁面名稱。升級時將使用預設值，該值應會符合您之前的變更。

API

PageImages擴充功能透過在properties API中加入一個prop=pageimages屬性來提供圖片資訊，來應對action=query。

prop=pageimages (pi)

(main | query | pageimages)

This module requires read rights.
Source: PageImages
License: WTFPL

Returns information about images on the page, such as thumbnail and presence of photos.

https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:PageImages#API

Specific parameters:

Other general parameters are available.

piprop

Which information to return:

thumbnail: URL and dimensions of thumbnail image associated with page, if any.
name: Image title.
original: URL and original dimensions of image associated with page, if any.

Values (separate with | or alternative): name, original, thumbnail

Default: thumbnail|name

pithumbsize

Maximum width in pixels of thumbnail images.

Type: integer

Default: 50

pilimit

Properties of how many pages to return.

Type: integer or max

The value must be between 1 and 50.

Default: 50

pilicense

Limit page images to a certain license type:

free: Only free images.
any: Best image, whether free or non-free.

One of the following values: any, free

Default: free

picontinue

When more results are available, use this to continue. More detailed information on how to continue queries can be found on mediawiki.org.

Type: integer

pilangcode

Code for the language the image is going to be rendered in if multiple languages are supported

Example:

Get name and 100-pixel thumbnail of an image on the Albert Einstein page.: api.php?action=query&prop=pageimages&titles=Albert%20Einstein&pithumbsize=100 [open in sandbox]

响应

{
  // piprop.name （且图像存在）
  pageimage?: string // 源图像文件名（original.source的基础名称）
  // piprop.thumbnail （且图像存在）
  thumbnail?: {
    source: string // 缩略图URL
    width: number // 缩略图宽度，单位为像素
    height: number // 缩略图高度，单位为像素
  }
  // piprop.original （且图像存在）
  original?: {
    source: string // 源图像URL
    width: number // 源图像宽度，单位为像素
    height: number // 源图像高度，单位为像素
  }
}

示例请求

请求某個條目的页面图片。

api.php?action=query&prop=pageimages&titles=Lightbox_demo [在Api沙盒中尝试]

结果

{
    "query": {
        "normalized": [
            {
                "from": "Lightbox_demo",
                "to": "Lightbox demo"
            }
        ],
        "pages": {
            "162510": {
                "pageid": 162510,
                "ns": 0,
                "title": "Lightbox demo",
                "thumbnail": {
                    "source": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e9/Crystal_Clear_app_korganizer.png/50px-Crystal_Clear_app_korganizer.png",
                    "width": 50,
                    "height": 50
                },
                "pageimage": "Crystal_Clear_app_korganizer.png"
            }
        }
    }
}

工作原理

當一個带有本地图片的頁面保存時，解析器會运行ParserMakeImageParams和LinksUpdate鉤子。 PageImages擴充功能會回應這些（以及其他鉤子），並在page_props 表中为頁面插入一个新屬性。屬性名稱為page_image和page_image_free，其值為圖片的名稱。如果一个页面同时有这两个属性，则它们的值不会相同。

擴充功能只會儲存選取的圖片名稱。其他功能可能會顯示圖片，例如頁面資訊、Hovercards，以及在輸入時進行的行動搜尋。

图片选择

如何检查与页面关联的图片是什么？

页面图片会显示与?action=info页面。

它用什么方式选择图片？

收集页面中的所有图片，并计算每个图片的分数。其中得分最高的图片将被选为页面图片。如果该图片包含了wiki已配置的无自由许可的元数据，则会选择分数最高且自由许可的图片。如果没有找到合适的图片或所有图片分数都很差（即分数为负），页面将没有任何图片。

如果$wgPageImagesLeadSectionOnly为true，则只有导言段落中的图片会作为备选。只在Wikipedia中该选项为true；所有其他项目都可以从导言段落外提取图片。

图片分数如何计算？

Wikimedia上预估最好的页面图片是文章中前四个图片之一，其宽或高为400~600px之間，且宽或高的一项为另一项的二倍。

该计算方法可进行配置。
分数由以下因素组合计算：
- 宽度被定义为 $wgPageImagesScores['width']
  - 在Wikimedia中，小于119像素的图片会扣很多分。宽400px~600px的图片更被偏爱，它有一个下限分数。
  - 圖庫中的图片使用$wgPageImagesScores['galleryImageWidth']单独评分
    - 在Wikimedia中的圖庫中，小于100px的图片将被忽略。
- 在文档中的位置也参照$wgPageImagesScores['position']中定义的值进行计算
  - 在Wikimedia中，只有文档中的前四张图片会入选。
- 图片的最佳宽高比被定义在$wgPageImagesScores['ratio']
  - 在Wikimedia中，允许的比例为0.4至3.1，更优的比例为0.6至2.1
  - The default value is $wgPageImagesScores['ratio'] = ["3" => -100, "5" => 0, "20" => 5, "30"=> 0, "31"=> -100]; with the key representing the width divided by height, rounded to the tenths place, and the decimal shifted one position to the right. An image 400px wide by 300px high would have a value of 13. The key's value is the scoring multiple associated with that ratio. Keys are selected and increase from zero, with a new scoring multiple not taking effect until the key has met or exceeded its value but not exceeded the next key. 任何其他图片都将得分为负并被弃选。

页面图片如何被更新？

每當LinksUpdate 钩子在运行时页面图片就會填充图片，例如在页面被编辑时。

我可以排除某些页面图片吗？

可以！

对于整个wiki而言，有一个允许管理员编辑的配置页面MediaWiki:Pageimages-denylist(示例) 定义在这其中的图片不会被作为任何主题的页面图片。

对于特定页面，将|class=notpageimage添加到要排除的每个图片中。例如，[[File:Example.png|class=notpageimage]]。更多详情请访问phab:T301588。

If you need to exclude an image in the infobox please refer to the template's documentation. Most templates support a image_class parameter that can be used to disable the image.

e.g.

{{Infobox type
  image=InappropriateImage.png
  image_class=notpageimage
}}

我可以要求明確的頁面圖片嗎？

從MediaWiki 1.44.0開始，您可以透過在圖片中加入|class=pageimage來標記圖片，此圖片符合在它用什么方式选择图片？段落中所述條件。一般而言，這是最後非不得己的手段了，因為這會覆寫掉圖片評分演算法，這意味著圖片可能被顯示在不適合它的地方 (例如解析度、授權條款、或位置)。

在可能的前提下，最好是加入首選的縮圖使之成為條目中的第一張圖片。

我如何檢視頁面的圖片？

使用侧边栏中的页面信息链接（或將?action=info添加到URL），您将能够看到当前选择的图片。

如何清除不合适的图片？

仅当文章中的链接更改时，页面图片才会更改。对于紧急情况，请在页面中添加/删除链接，必要时进行恢复。刷新缓存将不起作用。对于较大的紧急情况，请提交Phabricator工单。

为什么我的页面图片是空白框？

这可能与您文章中的视频内容有关。如果视频文件以空白屏幕开头，则它将成为视频的默认缩略图，并且如果用作页面图片，它将成为页面图片。我们目前正在对此进行修复，使您可以更改视频的默认缩略图。有关更多信息，请参见：phab:T92457和phab:T22647。

參見

Extension:Popups（弹出窗口）

此扩展用于一个或多个维基媒体项目。这可能意味着扩展足够稳定、运作足够良好，可以用在这样的高流量的网站上。请在维基媒体的CommonSettings.php和InitialiseSettings.php配置文件中查找此扩展的名称以查看哪些网站安装了该扩展。特定wiki上的已安装的扩展的完整列表位于Special:Version页面。

此扩展在以下wiki农场/托管网站和/或软件包中提供：