Manual:Skin autodiscovery/zh

From MediaWiki.org
Jump to navigation Jump to search

Skin autodiscovery was a legacy skin installation mechanism used by MediaWiki since very early versions (around 2004) which will be removed in MediaWiki 1.25, after being superseded by an explicit installation method in MediaWiki 1.12 and after being officially deprecated in MediaWiki 1.23.

MediaWiki 1.23 and 1.24 will emit warnings in production if a skin using the deprecated mechanism is found:

A skin using autodiscovery mechanism, $aSkin, was found in your skins/ directory.
The mechanism will be removed in MediaWiki 1.25 and the skin will no longer be recognized.
See https://www.mediawiki.org/wiki/Manual:Skin_autodiscovery for information how to fix this.

Skins using autodiscovery will continue working in the 1.23 LTS release (with the aforementioned warnings). If you upgrade from one LTS version to the next, you will have time until 1.27 LTS is released, giving you plenty of time to migrate.

autodiscovery 是如何工作的?[edit]

It used to be possible to just put a <name>.php file in MediaWiki's skins/ directory, which would be loaded and expected to contain the Skin<name> class. It has been discouraged for a long time because of the limitations of this method (inability to add localisation messages, ResourceLoader modules, etc. without cluttering LocalSettings.php) and awkwardness in managing such skins ($wgSkipSkins had to be introduced to make it possible to disable an installed skin).

Since MediaWiki 1.23 this mechanism is officially deprecated.

我该如何更新?[edit]

The recommended way to create a skin is detailed on Manual:Skinning.

In short, you would create a subdirectory under skins/ containing your skin's PHP code and assets, define certain skin properties in the <name>.php file, which now is located inside that subdirectory, and require_once it like you do when installing extensions.

This has already been supported, with minor modifications, since MediaWiki 1.12.

我应该去哪里找到新版本的皮肤?[edit]

The bundled skins which come with MediaWiki (like Vector or MonoBook) will continue to be updated with the MediaWiki Core. When you upgrade your installation to MediaWiki 1.24 or newer, you will also get a new version of these skins. (You should then remove the old copies from the skins/ folder, see Manual:Upgrading#Files remaining that may cause errors.)

If the skin you use was written by someone else (and you don't maintain it yourself), first try to find out if its maintainer has updated it already. Most of the skins that have description pages here on mediawiki.org (Category:All skins) use the new mechanism already or will be updated to use it soon (before 1.25 is released).

If you maintain the skin yourself, or if you want to help its maintainer migrating it, go ahead with the next section.

迁移指南[edit]

将皮肤迁移到新的机制所需要的步骤,如下:

  1. 移动 MySkin.php 文件和皮肤资源(如不存在则创建)到 MySkin 目录。在此之前,皮肤常常使用 camel-case for the PHP 文件名和 lower-case 目录。你现在应该让这两个名字完全相同——最好是 camel-case 版本。
    • Optionally, split the classes defined by your skin (SkinMySkin, MySkinTemplate) to separate files and register them in $wgAutoloadClasses like so: $wgAutoloadClasses['SkinMySkin'] = __DIR__ . '/SkinMySkin.php';. This will make the structure of the main file clearer, especially if you have a lot of code or used additional features (see below).
  2. Adjust paths in the PHP files if they were relative to file's directory, rather than $IP or $wgStyleDirectory.
  3. Add the skin to $wgValidSkinNames in the MySkin.php file, like so: $wgValidSkinNames['myskin'] = 'MySkin';. Note the capitalisation: The key is lower-case, the value is camel-case as in the class name "SkinMySkin" of the skin.
  4. If you used additional MediaWiki features:
    • If you have somehow defined ResourceLoader modules for your skin (like $wgResourceModules['skins.myskin.styles'] = ), put them in the MySkin.php file as well. Remember to adjust paths if necessary. (No other changes are needed.)
    • If you have somehow defined localization messages for your skin (using $wgMessagesDirs or $wgExtensionMessagesFiles), move the messages file/directory into the MySkin directory, and place the definition (which looks like $wgMessagesDirs['MySkin'] = __DIR__ . '/i18n'; or $wgExtensionMessagesFiles['MySkin'] = __DIR__ . '/MySkin.i18n.php';, respectively) in the MySkin.php file.
  5. Add a require_once( "$IP/skins/MySkin/MySkin.php" ); to your LocalSettings.php file (similarly to how it's done for extensions).

As mentioned above, the "migrated" skins will work with your MediaWiki 1.23 installation, as well as many versions back.

Example[edit]

This patch set exemplarily shows how this migration works: https://gerrit.wikimedia.org/r/#/c/138795/

See also[edit]