模板:文档

From Valve Developer Community
Jump to: navigation, search
English Deutsch Español 简体中文 ქართული ენა

本模板由大康翻译。本模板的功能文本翻译于2021年9月19日 (日) 14:03‎(中国标准时间),描述文本翻译于2022年1月15日。部分内容由机器翻译。




这是几乎每个模板页面上使用的 {{Documentation}} 模板,以包含该模板的文档说明和信息。

该模板显示一个灰色的文档框,就像您现在看到的那样,并自动从 /doc 子页面加载内容。如果有指示,它还可以从其他地方加载内容。

此模板用于记录模板和嵌入到其他页面的其他页面。它可以在模板命名空间和大多数其他命名空间中使用。

使用此模板可以在必要时保护模板,同时允许任何人编辑文档和类别。

用法

通常这个模板在没有任何参数的情况下使用,放置在模板或页面的底部,在一个 <noinclude>...</noinclude> 容器中:

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn}}
<!-- 将类别添加到 /doc 子页面,不在此处 -->
</noinclude>

然后此模板会自动从使用它的模板的 /doc 子页面加载内容。

此模板还可以从任何其他页面加载内容。像这样:

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn |Template:(其他页面名称)/doc}}
</noinclude>

请注意,当从本地 /doc 页面以外的页面加载文档时,处理类别变得很棘手。

内容也可以直接作为文本提供。像这样:

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn
 | content =
(一些文本)
}}</noinclude>

使用 |content= 参数时,文档框通常不会在右上角显示 [edit] [purge] 链接。请注意,如果 /doc 页面存在,指向它的链接仍会显示在 doc 框下方的链接框中。

参数 |1=|content= 参数也可以组合,如下所示:

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn |1=Template:Any page/doc
| content =
{{Template:(任一页面)/doc |parameters}}
}}</noinclude>

然后作为参数 1 提供的页面名称用于 [edit] [purge] 链接和文档框下方链接框中的 /doc 链接。但是 content 参数用于文档框中显示的内容。上述代码表示内容被嵌入为{{Template:(任一页面)/doc|parameters}}。在这个例子中,一个参数也被提供给正在加载的 /doc 页面。

小技巧

要自动插入 noinclude 标记、模板调用和指导性注释,请使用以下代替代码:

{{subst:doc-code}}

最佳做法

代码应该添加在模板代码的底部,<noinclude> 之前没有空格(这会导致使用模板的页面上有额外的空间)。

适用于模板本身的类别应添加到 /doc 子页面底部的 <includeonly>...</includeonly> 标签内。

如果文档页面包含 <includeonly><noinclude> 标记作为可见文档文本的一部分,请将“<”替换为“ <" 或使用 Template:tag

标题

在模板命名空间中,此模板显示以下标题:

Curly brackets white.png 模板文档

在大多数其他名称空间中,例如“Wikipedia:”,它显示以下标题:

文档

但是当在文件(图像)页面上时,它会显示这个标题:

摘要

heading 参数可用于将标题设置为其他内容。像这样:

{{Documentation:zh-cn |heading=信息框文档}}

如果 heading 参数为空但已定义,则不显示标题并且不显示 [edit] [purge] 链接。像这样:

{{Documentation:zh-cn |heading=}}

heading-style 参数可以提供可选的 CSS 值。不带引号 " " 但带有结尾分号 ;。例如:

heading-style=font-size:150%;color:red;

链接框

大文档框下方是一个小链接框,显示有关文档的一些元数据。链接框根据提供给该模板的参数以及在哪个名称空间中使用它来显示不同的内容。在某些情况下,链接框根本不显示。

要隐藏链接框,请添加参数

|link box=off.

您还可以通过设置 |link box= 参数将自定义文本插入到链接框中。例如:

  |link box=本文档由 [[Template:Country showdata]] 自动生成

自动功能

如果文档页面不存在,[create] 链接会包含一个 preload 页面,以便单击它将使用基本文档页面格式预先填写编辑表单。预加载文本也用于 /sandbox 和 /testcases [create] 链接。

当此模板位于 /sandbox 子页面时,它会自动添加 {{Template sandbox notice}}。

Subject 命名空间与 Talk 命名空间

术语:“Subject 名称空间”与“Talk 名称空间”相反。例如“Template:”是“Template talk:”的主题空间。

此模板通常放置在 Subject 名称空间中,位于 <noinclude> 标记内。但在某些情况下,此模板需要出现在讨论页上:

  • 在 Mediawiki 命名空间中,因为 <noinclude> 通常在系统消息中不起作用,并且出于性能原因需要保持 Mediawiki 命名空间的清洁。

当放置在讨论页面上时,此模板通常放置在页面顶部附近并且没有 <noinclude>...</noinclude> 标签。

/doc、/sandbox 和 /testcases 页面通常应位于主题命名空间中,但未启用 MediaWiki 子页面功能的命名空间除外:Main、File、Mediawiki和类别。 (但目前我们只显示来自 User、User talk、Template 和 Template talk 命名空间的 /sandbox 和 /testcases 链接。)还有一大堆其他技术原因,为什么 /doc 页面必须存储在讨论页面下(但只有那些)命名空间。

该模板自动将其 /doc、/sandbox 和 /testcases 的 [create] 链接指向正确的命名空间。

测试

您可以使用 |page= 参数模拟给定页面的输出。例如,如果您使用代码 |page=Template:Quote,模板的行为将与页面 Template:Quote 完全相同,包括显示来自 Template:Quote/doc 的文档,链接到 Template:Quote/sandbox 等。此参数对测试很有用。

技术细节

该模板调用 {{documentation/start box2:zh-cn}} 和 {{documentation/end box2:zh-cn}} 依次调用 {{documentation/start box:zh-cn}} 和 {{documentation/end box:zh-cn}}。 /start 框(和 /end 框)包含大部分代码,而此模板和 /start box2(和 /end box2)进行参数预处理。

/doc [create] 链接的预加载页面是 Template:Documentation:zh-cn/preload。 /sandbox 和 /testcases [create] 链接的预加载页面是 Template:Documentation:zh-cn/preload-sandboxTemplate:Documentation:zh-cn/preload-testcases。 /sandbox [mirror] 链接的预加载页面是 Template:Documentation:zh-cn/mirror

完整语法

{{Documentation:zh-cn}}

{{Documentation
 | content =
}}

{{Documentation:zh-cn
| [path to documentation page]
| heading-style = 
| heading = 
| link box = 
}}

另请参阅

  • {{Documentation subpage:zh-cn}},放置在 /doc 子页面顶部的通知,解释其角色并包括指向它记录的页面的链接。