扩展:模板样式

This page is a translated version of the page Extension:TemplateStyles and the translation is 90% complete.
Outdated translations are marked like this.
MediaWiki擴充功能手冊
OOjs UI icon advanced-invert.svg
TemplateStyles
发布状态: 稳定版
实现 标签 , ContentHandler , 钩子
描述 允许模板加载已过滤的CSS样式表。
作者
最新版本 Continuous updates
兼容性方针 Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki >= 1.36.0
PHP 7.3+
许可协议 GNU通用公眾授權條款2.0或更新版本
下载
  • $wgTemplateStylesUseCodeEditor
  • $wgTemplateStylesDisable
  • $wgTemplateStylesDefaultNamespace
  • $wgTemplateStylesDisallowedAtRules
  • $wgTemplateStylesDisallowedProperties
  • $wgTemplateStylesAllowedUrls
  • $wgTemplateStylesAutoParseContent
  • $wgTemplateStylesMaxStylesheetSize
  • $wgTemplateStylesNamespaces
<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名字空间。 (This default can be changed via $wgTemplateStylesDefaultNamespace.) 例如,<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

注意事项

  • 由TemplateStyles加入的样式被在.mw-parser-output中,以免篡改主解析内容以外的用户界面。
    • 如要使TemplateStyles在像w:MediaWiki:Protectedpagetext这样的内容中生效,需将这个消息内容用<div class="mw-parser-output">...</div>包围。
  • 样式应针对特定的CSS类(class)编写,并且生成使用这些类的元素的任何内容都应包含样式本身,而不要依赖其他模板来完成此目的。
    • 模板所包含的样式目前可能影响页面中该模板生成的内容之外的内容,但未来或许会移除这种能力,因此不应对此有所依赖。
    • 模板所含样式影响了模板外的内容时,编辑特定章节且内容不含该模板时不会看到模板样式被应用。 举例来说,如果某个信息框上含有影响整个页面所有表格的样式,当编辑某个不含该信息框的章节时,预览章节不能在表格上看到这些样式。
  • 模板样式允许少数几个非标准化的CSS属性。 请求支持额外的属性应在Phabricator中的css-sanitizer与TemplateStyles项目中提交。
    • 请求应当包含链接到描述需要请求使用的属性的语法的标准文档(例如w3.org)的链接,以及对这个属性的浏览器兼容性分析(例如到caniuse.com中的关于该属性的页面)。
    • 带有特定浏览器名称前缀的属性(例如以-webkit--moz--ms-开头的属性)可能会被拒绝,如果现代浏览器不需要的话。
  • @font-face规则必须使用前缀为"TemplateStyles"的font-family。 这应在很大程度上避免重新定义文档中其他位置上使用的字体。
  • 如需基于皮肤来应用样式,应使用像body.skin-vector .myClass这样的选择器,其中必须指定body元素,其后接一个descendant combinator(例如空格)。 bodyhtml元素的其他类也应该以相同的方式指定。 1.32+

安装

  • 如果使用Vagrant ,请通过vagrant roles enable templatestyles --provision安装
手动安装
  • 下载文件,并将其放置在您extensions/文件夹中的TemplateStyles目录内。
  • 只有從git安裝才运行Composer来安装PHP依赖,通过发行composer install --no-dev至扩展目录。 (参见任务T173141了解潜在问题。)
  • 将下列代码放置在您的LocalSettings.php的底部:
    wfLoadExtension( 'TemplateStyles' );
    
  • 根据需要配置。
  •   完成 – 在您的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正则表达式,用于匹配允许的各种类型的外部引用。

键是外部引用类型,值为正则表达式(包括分隔符)的数组以匹配允许的URL。当前的外部引用类型有:

audio
声音文件,用于CSS声音模块cue属性。
image
图像文件,用于像background这样的属性。
svg
SVG文件,用于蒙版滤镜
font
用于@font-facesrc
namespace
用于@namespace.
css
用于@import
$wgTemplateStylesNamespaces
[ NS_TEMPLATE => true ]
将此名字空间内以.css结尾的标题的内容模型设为“已过滤的CSS”。

不要启用2(用户)或8(MediaWiki),因为与这些名字空间中的正常CSS页面冲突。

$wgTemplateStylesPropertyBlacklist
[]
CSS样式规则中需要屏蔽的选项。

TemplateStylesPropertySanitizer 钩子允许更加精细的控制。

$wgTemplateStylesAtRuleBlacklist
[]
样式表中需要屏蔽的at-规则。

TemplateStylesStylesheetSanitizer 钩子允许更加精细的控制。

$wgTemplateStylesUseCodeEditor
true
是否为“已过滤的CSS”内容类型启用扩展:代码编辑器
$wgTemplateStylesAutoParseContent
true
若为true,如果CSS内容模型已经在该数组中,则“已过滤的CSS”内容模型会被添加到$wgTextModelsToParse

若为false,如果需要分类等内容解析在CSS页面之外,则手动将'sanitized-css'添加到该数组。

$wgTemplateStylesMaxStylesheetSize
102400
样式表的最大大小(字节)。null表示无限制。
$wgTemplateStylesDefaultNamespace
NS_TEMPLATE
The default namespace for the src attribute of the ‎<templatestyles> tag.

其他依赖性

$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.

可能的错误

如果从其他wiki导入页面时发生错误,则对于下列几种错误,你可以尝试在你的LocalSettings.php中启用$wgShowExceptionDetails 来解决问题。

  • Class 'Wikimedia\CSS\Parser\Parser' not found
    该错误可能会在尝试导入一个wiki CSS页面或将页面的内容模型改变为“已过滤的CSS”时出现。 对于2020年8月16日,扩展分发器中有个开放漏洞,需要composer install --no-dev在“扩展子目录内”运行,即使扩展不是从Git安装的。 详情请见Topic:Ukv6pdo96a8qfur2
  • Import failed: The content model 'sanitized-css' is not registered on this wiki.
    某些人在wiki上导入页面时可能看到此错误。 该扩展提供有该内容模型。 安装TemplateStyles来解决导入问题。

参见