手册:使用自定义命名空间

本頁使用了標題或全文手工轉換
From mediawiki.org
This page is a translated version of the page Manual:Using custom namespaces and the translation is 70% complete.
Outdated translations are marked like this.

除了内置的命名空间外,也可以为MediaWiki的安装添加自定义命名空间,以进一步分离内容并允许更多的逻辑组织。

自定义命名空间可以使用 $wgExtraNamespaces 配置指令简单管理。 也可以使用 $wgNamespaceAliases 配置指令为自定义(以及预定义的)命名空间定义别名。 有些拓展会使创建自定义命名空间变得容易。 例如NamespaceManager BlueSpiceNamespaceManager

建议在操作命名空间之前确保作业队列中没有挂起的作业,以避免此类作业的目标页面所在的命名空间恰好是您将要删除或重命名的命名空间,从而导致失败。 使用runJobs.php 运行所有挂起的作业,并在操作命名空间配置之前清除作业队列。

创建自定义命名空间

"LocalSettings.php" 文件中加入$wgExtraNamespaces 全局变量以创建新的命名空间。 这个数组中,所有命名空间都需要一個獨一無二的数字索引。 一个简单的创建自定义命名空间的例子,将以下行代码添加到"LocalSettings.php" 文件会定义一个“Foo”命名空间(3000)及其“Foo_talk”命名空间。 需要注意的是自定义命名空间目前必须要有对应的讨论命名空间。

// 为我添加的命名空间定义常量。
define("NS_FOO", 3000); // 这必须是偶数。
define("NS_FOO_TALK", 3001); // 这必须是下一个奇整数。

// 添加命名空间。
$wgExtraNamespaces[NS_FOO] = "Foo";
$wgExtraNamespaces[NS_FOO_TALK] = "Foo_talk"; // 请注意命名空间名称中的下划线
挑选未使用的数字
作为惯例,数字100-199的命名空间是为保留的特定命名空间,尽管有的扩展不遵从这个惯例。 扩展编写者使用更高的数字,高达32767。 当选择索引时,你应该避免任何已在extension default namespaces里的任何数字,这是因为你有可能以后会安装那些插件。 从3000到4999的数字是为系统管理员保留的,以定义他们的自定义命名空间。 (并且,你也要避免任何命名空间的名称扩展默认命名空间内的冲突。)
偶数,然后奇数
注意在上面的例子中,命名空间的索引是3000。
同时创建讨论命名空间
您通常会为每个自定义命名空间创建一个讨论“Talk”命名空间。 这个例子中,如果你将页面移动到“Foo”命名空间,将被提示移动其关联的讨论页(如果有),如果你选择这样做,MediaWiki将会把讨论页放在“Foo talk”中。
无空格
注册命名空间时,使用下划线而不是空格。 “My Namespace”是无效的,请改用“My_Namespace”。
没有连字符

大写部分不允许使用连字符,但它们仍然可以安全地添加到前缀标题中。 例子:

$wgExtraNamespaces[NS_FOOFOO] = "Foo-Foo";
为您选择的数字命名
这个例子为命名空间ID定义了一些常量,这样一来你以后便可以在配置中引用这些命名空间,例如在$wgNamespaceProtection $wgNamespacesWithSubpages $wgExtraGenderNamespaces 中。

你可以继续为你的新命名空间配置额外的设定。

$wgNamespaceProtection[NS_FOO] = [ 'editfoo' ]; // 需要“editfoo”权限才能编辑foo命名空间
$wgNamespacesWithSubpages[NS_FOO] = true;            // 为foo命名空间启用子页面
$wgGroupPermissions['sysop']['editfoo'] = true;      // 向“sysop”用户组授予“editfoo”权限
尽早进行
$wgExtraNamespaces的操作必须要在MediaWiki初始化期间完成,即,以防一个拓展之类的东西需要用新增的自定义命名空间,请确保你在调用对应拓展之前就定义并命名好这些命名空间。
小心URL协议碰撞
MediaWiki的链接代码认识一些URL协议,它们都定义在$wgUrlProtocols 变量里。 如果你的命名空间名字与其中一个协议相同,在创建[[维基链接]]指向自定义命名空间的页面时会有麻烦。 这种情况最常出现于试图创建“News”命名空间的场面,因为news:是一个为NNTP新闻组使用的URL协议。
为避免这个问题,你可以向“LocalSettings.php”文件添加以下代码,以注销相关的URL协议(把news改成你想移除的协议的小写名称):
$wgUrlProtocols = array_diff( $wgUrlProtocols, array( 'news:' ) );

在扩展中

拓展通常都会添加它们自己的命名空间,比如Flow 拓展的“Topic”命名空间。 一个拓展可以无条件地向$wgExtraNamespaces添加命名空间,如前文所述;或者如果命名空间注册是有条件的(例如EventLogging 只会在有纲要的维基上定义“Schema”命名空间),拓展会为CanonicalNamespaces 钩子添加一个处理函数以决定该做什么。

注册拓展的时机十分微妙。 拓展用$wgExtensionFunctions 注册的函数执行得太晚,以至于来不及注册额外的命名空间。(任务T47031所以拓展应该以文件作用域绑定CanonicalNamespaces(在MyExtension.php中)并在那里检查维基是否应该启用额外的命名空间。 拓展能以文件作用域无条件地配置命名空间权限和内容处理函数,因为它们并不要求命名空间真正地被创建。

MediaWiki版本:
1.25
Gerrit change 166705

extension.json的注册系统有个namespaces键,为拓展罗列出应该一直存在的命名空间。 来自Gadgets 扩展:

"namespaces": [
		{
			"id": 2300,
			"constant": "NS_GADGET",
			"name": "Gadget",
			"protection": "gadgets-edit"
		},
		{
			"id": 2301,
			"constant": "NS_GADGET_TALK",
			"name": "Gadget_talk"
		},
]

它也支持CanonicalNamespaces钩子。 Extensions should prefer extension registration over CanonicalNamespaces. Note that adding an extension to LocalSettings.php does not necessarily make relevant namespace constants available as globals for other extensions.

内容命名空间

在构建网站统计页面(参见Special:Statistics),MediaWiki使用值存储在数据库来计算总数。 一个典型的总数便是“文章数量”或者叫“内容页面数量”。

一个页面要被认作一篇文章或真内容,必须符合如下条件:

创建自定义命名空间以保存其他内容时,最好在配置中指明这一点。 通过$wgContentNamespaces 设定一个自定名字空间为内容名字空间。

例如在"LocalSettings.php"文件中加入如下内容:

$wgContentNamespaces[] = 3000;
$wgContentNamespaces[] = NS_FOO;

MediaWiki现在在会将“Foo”命名空间中的页面视为文章(如果这些页面也满足其余标准),并将在更新站点统计计数器时包括这些页面。

运行维护脚本

  • When adjusting the value of configuration parameter $wgContentNamespaces, it is a good idea to run either the "path/to/maintenance/updateArticleCount.php or "path/to/maintenance/initSiteStats.php" script to update the internal statistics cache (see 手册:维护脚本 ).

为什么要自定义命名空间

主要有以下原因:

  • A custom namespace can be used to hold content that should not be shown on the search results page, for example pages that are used only for transclusion.
  • 特定名字空间需要额外编辑特权。
  • You want certain namespaces not to be subjected to certain limitations or default settings ($wgNoFollowNsExceptions for example)
  • A uniform prefix for specific content(s), which is searchable for that namespace only

处理已存在的页面

在存储页面记录时,MediaWiki 使用命名空间的数字索引以及剩余的标题文本。 如果在不存在的命名空间中建立了一个页面,例如“Bar:Some page”,它将被视为主命名空间中名称为“Bar:Some page”的页面。

如果之后建立了“Bar”命名空间则会出现问题:查找“Bar:Some page”页面时,会因为在“Bar”命名空间中不存在“Some page”页面而失败。

有三种方法修正这样的错误:

移动冲突页面

当受影响的页面数量很少时(例如在网站配置中将“Bar”定义为名字空间前,其涉及5个已创建的页面),那么以下途径会比较合适:

  1. 将出现错误的命名空间从配置文件中注释掉
  2. 依次将每个错误页面从先前的命名空间中移出,如“Bar:Some page”移动为“Bar2:Some page”。
  3. 将配制文件恢复原样
  4. 最后将移动的页面移回正确的名字空间

使用维护脚本

“maintenance”目录中有一个叫“NamespaceDupes.php ”的脚本,用它可以对大量页面更有效地执行上述操作, 其使用方法很简单,请用“--help”选项调用脚本来显示其使用说明。

使用数据库查询

通过下面的数据库查询操作,可以将所有在主名字空间的“Bar:某页面”页面移动到编号为“3000”的名字空间:

UPDATE page SET
page_title = REPLACE(page_title, 'Bar:', ''),
page_namespace = 3000
WHERE page_title LIKE 'Bar:%' AND page_namespace=0

处理对应的讨论页面:

UPDATE page SET
page_title = REPLACE(page_title, 'Bar_talk:', ''),
page_namespace = 3001
WHERE page_title LIKE 'Bar_talk:%' AND page_namespace=1

After such fiddling, run the refreshLinks.php script and the updateSearchIndex.php script to update internal links and search results in your wiki. Note that external search engines like Google will take some time to update their index.

移除自定义命名空间

The problem addressed above also occurs when a custom namespace definition is removed; MediaWiki is no longer aware of the numerical index for the namespace, and attempts to search the main namespace for the desired pages, leading to inaccessible content. This is a rare occurrence, since most sites will not need namespaces removed, but it is a problem. (参见邮件列表讨论)。

Example on how to remove Flow and the Topic namespace:

  • 卸载Flow
  • 临时添加$wgExtraNamespaces[2600] = 'Topic';至配置
  • 使用deleteBatch.php删除所有Topic名字空间中的页面
  • 移除$wgExtraNamespaces配置

重命名自定义命名空间

Suppose that you need to rename custom namespace "Foo" to "New" without performing a mass move of pages. The easiest way to achieve this is to preserve the namespace ID (here "3000") as well as the namespace constant (here "NS_FOO"), modify the (visible) namespace title and add the old one as an alias.

define("NS_FOO", 3000);
$wgExtraNamespaces[NS_FOO] = "Foo";

更改为

define("NS_FOO", 3000);
$wgExtraNamespaces[NS_FOO] = "New";
$wgNamespaceAliases['Foo'] = NS_FOO;

避免命名空间冲突

In order for you to avoid namespace conflicts e.g. your namespace has the same number as a namespace defined by an extension, the extension namespace list shows you which numbers to avoid to prevent conflicts.

Defining $wgNamespacesToBeSearchedDefault , $wgNamespacesWithSubpages , $wgContentNamespaces or $wgNamespaceAliases for an ID not associated to any existing namespace in $wgExtraNamespaces doesn't break the wiki; MediaWiki gracefully ignores such configurations.

为命名空间设置样式

For example, to set the background color of pages in a particular namespace (and its associated talk namespace) you can add the following code to your common.css:

.ns-3000 #content, .ns-3001 #content { background-color: #f3f3ff; }
.ns-3000 div.thumb, .ns-3001 div.thumb { border-color: #f3f3ff; }

where 3000 is the namespace's index and #f3f3ff is the color you want as its background color.

You might also want to change the name of the tab from its default (the namespace's name). This is located in your system messages at MediaWiki:nstab-namespace.

参见

Site administration

Extensions

For extension developers