扩展:模板样式

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:TemplateStyles and the translation is 63% complete.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Türkçe • ‎français • ‎polski • ‎中文 • ‎日本語
MediaWiki擴充功能手冊
OOjs UI icon advanced.svg
TemplateStyles
发布状态: 稳定版
实现 标签 , ContentHandler , 钩子
描述 允许模板加载已过滤的CSS样式表。
作者
最新版本 Continuous updates
兼容性方针 Snapshots releases along with MediaWiki. Master is not backwards compatible.
MediaWiki 1.31+
PHP 5.5+
许可协议 GNU通用公眾授權條款2.0或更新版本
下载
  • $wgTemplateStylesNamespaces
  • $wgTemplateStylesDisallowedProperties
  • $wgTemplateStylesDisallowedAtRules
  • $wgTemplateStylesUseCodeEditor
  • $wgTemplateStylesDisable
  • $wgTemplateStylesAutoParseContent
  • $wgTemplateStylesMaxStylesheetSize
  • $wgTemplateStylesAllowedUrls
<templatestyles src=... />
翻譯TemplateStyles擴充功能如在translatewiki.net可用

检查使用和版本矩阵。

问题 尚未完成的工作 · 回報錯誤

TemplateStyles扩展引入了一个<templatestyles>标签用于指定Wiki页面应该加载的一个样式表。 将此标签放入模板中可使该模板加载自定义的样式,而无需将样式放入MediaWiki:Common.css

关于编辑者如何在Wiki上使用该扩展,参见Help:模板樣式

用法

首先需要创建一个CSS页面。 默认设置下,Template名字空间下任何标题以".css"结尾且没有语法错误的子页面都将创建为“已过滤的CSS” content model

采用此模式的名字空间可用$wgTemplateStylesNamespaces调整,或者对任何页面使用Special:ChangeContentModel 。 然后,在模板的维基文本中添加<templatestyles src="..." />并且来加载该样式。

采用“已过滤的CSS”内容模型保存的CSS必须满足严格的有效性要求:无效CSS、无法识别的规则以及不支持的属性/属性值无法保存。 如果仍以某些方式保存了无效的CSS,当CSS输出到浏览器时,存在问题的部分将被移除。

标签上的src属性的值是页面标题,默认视作Template名字空间。 例如,<templatestyles src="Example/styles.css" />将加载“Template:Example/styles.css”页面。 如果该页面不存在或者不是“已过滤CSS”内容模型,则该操作失败。

可以使用可选参数wrapper将样式限定在页面的特定范围内,例如<templatestyles src="Example/styles.css" wrapper="div.example" />将加载的样式限制于主解析内容中的任何<div class="example">元素上。 wrapper参数可使用任何CSS简单选择器序列。 此功能是为允许比对模板的线上与沙盒版本而设计。

已过滤CSS的使用与模板的嵌入引用(transclusion)一样被追踪,并如嵌入引用一样显示于Special:WhatLinksHere

注意事项

  • 模板样式所加入的样式被限制于.mw-parser-output,以免篡改主解析内容以外的用户界面。
  • 样式应针对特定的CSS类(class)编写,并且生成使用这些类的元素的任何内容都应包含样式本身,而不要依赖其他模板来完成此目的。
    • 模板所包含的样式目前可能影响该模板所生成内容之外的页面内容,但未来或许会移除这种能力,因此不应对此有所依赖。
    • 模板所含样式影响了模板外的内容时,编辑特定章节且内容不含该模板时不会看到模板样式被应用。 举例来说,如果某个信息框上含有影响整个页面所有表格的样式,当编辑某个不含该信息框的章节时,预览章节不能在表格上看到这些样式。
  • 模板样式允许少数几个非标准化的CSS属性。 请求支持额外的属性应在Phabricator中的css-sanitizer与TemplateStyles项目中提交。
    • Requests should include links to standards-track documents (e.g. on w3.org) describing the syntax of the properties being requested, and an analysis of current browser support for the properties (e.g. a link to a caniuse.com page about the properties).
    • Vendor-prefixed properties (e.g. anything starting with -webkit-, -moz-, or -ms-) are likely to be declined if they're not needed for modern browsers.
  • @font-face规则必须使用前缀为"TemplateStyles"的font-family。 这应在很大程度上避免重新定义文档中其他位置上使用的字体。
  • To target styles based on skins, use a selector such as body.skin-vector .myClass; specification of the body element is required and must be followed by a descendant combinator (i.e. the space).

Other classes on the body or html elements may be targeted in the same manner. 1.32+

安装

  • 如果使用Vagrant ,请通过vagrant roles enable templatestyles --provision安装
手动安装
  • 下载文件,并将其放置在您extensions/文件夹中的TemplateStyles目录内。
  • 只有從git安裝才运行Composer来安装PHP依赖,通过发行composer install --no-dev至扩展目录。 (参见任务T173141了解潜在问题。)
  • 将下列代码放置在您的LocalSettings.php的底部:
    wfLoadExtension( 'TemplateStyles' );
    
  • 根据需要配置。
  • Yes 完成 – 在您的wiki上导航至Special:Version,以验证扩展已成功安装。
为能使用有语法高亮和自动缩进的代码编辑器,提供更舒适的用户界面,请安装下列扩展:

配置

配置设置
参数 默认 備註
$wgTemplateStylesAllowedUrls
[
    "audio" => [
        "<^https://upload\\.wikimedia\\.org/wikipedia/commons/>"
    ],
    "image" => [
        "<^https://upload\\.wikimedia\\.org/wikipedia/commons/>"
    ],
    "svg" => [
        "<^https://upload\\.wikimedia\\.org/wikipedia/commons/[^?#]*\\.svg(?:[?#]|$)>"
    ],
    "font" => [],
    "namespace" => [
        "<.>"
    ],
    "css" => []
]
PCRE正则表达式,用于匹配允许的各种类型的外部引用。

Keys are external reference types, values are arrays of regular expressions (including delimiters) to match allowed URLs. Current external reference types are:

audio
Sound file, for cue properties of the CSS Speech Module.
image
Image file, for properties such as background.
svg
SVG file, for Masking and Filters.
font
For @font-face's src.
namespace
For @namespace.
css
For @import.
$wgTemplateStylesNamespaces
[ NS_TEMPLATE => true ]
Namespaces in which to set the "Sanitized CSS" content model for titles ending in ".css".

Enabling this for 2 (User) or 8 (MediaWiki) is a bad idea, as it will conflict with the normal CSS files in those namespaces.

$wgTemplateStylesPropertyBlacklist
[]
Properties to blacklist in CSS style rules.

The TemplateStylesPropertySanitizer hook allows for finer-grained control.

$wgTemplateStylesAtRuleBlacklist
[]
At-rules to blacklist in stylesheets.

The TemplateStylesStylesheetSanitizer hook allows for finer-grained control.

$wgTemplateStylesUseCodeEditor
true
Whether to enable 扩展:代码编辑器 for the "Sanitized CSS" content type.
$wgTemplateStylesAutoParseContent
true
If true, the "Sanitized CSS" content model will be added to $wgTextModelsToParse if the CSS content model is already present in that array.

If false, add 'sanitized-css' to that array manually if you want categories and such parsed out of the CSS page.

$wgTemplateStylesMaxStylesheetSize
102400
Maximum size (in bytes) of a stylesheet. null for no limit.

其他依赖性

$wgTidyConfig 应配置为no tidying或者RemexHtmlIf used with any of the Raggett drivers, a <templatestyles /> tag in the middle of a paragraph (including in an inline template) will cause tidy to break the paragraph at that point. The other drivers have not been tested for this issue.

可能的错误

If you experience an error when importing pages from another wiki, for example, it may help to enable $wgShowExceptionDetails in your LocalSettings.php to determine if you are experiencing any of the errors below.

  • Class 'Wikimedia\CSS\Parser\Parser' not found
    This error may come up when attempting to import a wiki CSS page or when changing the content model of a page to "santized-css". There is, as of April 16, 2020, an open bug in the extension distributor which requires composer install --no-dev to be run in the extension subdirectory even when the extension is not installed from Git. 详情请见Topic:Ukv6pdo96a8qfur2
  • Import failed: The content model 'sanitized-css' is not registered on this wiki.
    某些人在wiki上导入页面时可能看到此错误。 该扩展提供有该内容模型。 安装TemplateStyles来解决导入问题。

参见