Extension:TemplateStyles

This page is a translated version of the page Extension:TemplateStyles and the translation is 96% complete.
Outdated translations are marked like this.
MediaWiki扩展手册
TemplateStyles
发行状态: 稳定版
实现 标签 , ContentHandler , 函数钩
描述
允许模板加载已过滤的CSS样式表。
作者
最新版本 持续更新
兼容性政策 快照跟随MediaWiki发布。 master分支不向后兼容。
MediaWiki 1.30+
PHP 7.3+
许可协议 GNU通用公眾授權條款2.0或更新版本
下載
  • $wgTemplateStylesUseCodeEditor
  • $wgTemplateStylesDisable
  • $wgTemplateStylesDefaultNamespace
  • $wgTemplateStylesDisallowedAtRules
  • $wgTemplateStylesDisallowedProperties
  • $wgTemplateStylesAllowedUrls
  • $wgTemplateStylesAutoParseContent
  • $wgTemplateStylesMaxStylesheetSize
  • $wgTemplateStylesNamespaces
<templatestyles src=... />
季度下載量 1,289 (Ranked 1st)
正在使用的公开wiki数 1,977 (Ranked 199th)
前往translatewiki.net翻譯TemplateStyles扩展
問題 开启的任务 · 报告错误

TemplateStyles扩展引入了一个‎<templatestyles>标签,用于指定wiki页面应该加载的一个样式表。 The extension allows only a safe subset of CSS syntax to be stored in embeddable style pages. This is powered by the css-sanitizer library.

将此标签放入模板中可使该模板加载自定义的样式,而无需将样式放入MediaWiki:Common.css

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

用法

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

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

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

标签上的src属性的值是页面标题,默认视作Template命名空间。 (默认值可以通过$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)编写,并且生成使用这些类的元素的任何内容都应包含样式本身,而不要依赖其他模板来完成此目的。
    • 模板所包含的样式目前可能影响页面中该模板生成的内容之外的内容,但未来或许会移除这种能力,因此不应对此有所依赖。 (See discussion from phab:T155813#2996589 and in phab:T176272.)
    • 模板所含样式影响了模板外的内容时,编辑特定章节且内容不含该模板时不会看到模板样式被应用。 例如:如果某个信息框上含有影响整个页面所有表格的样式,当编辑某个不含该信息框的章节时,预览章节不能在表格上看到这些样式。
  • TemplateStyles不支持CSS变量,参见phab:T320322
  • 模板样式允许少数几个非标准化的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元素的其他类也应该以相同的方式指定。 See phab:T197617. 1.32+

安裝

  • 下载文件,并将其放置在您extensions/文件夹中的TemplateStyles目录内。
    开发者和代码贡献人员应从Git安装扩展,输入:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateStyles
  • 只有從git安裝才运行Composer来安装PHP依赖,通过发行composer install --no-dev至扩展目录。 (参见任务T173141了解潜在问题。)
  • 将下列代码放置在您的LocalSettings.php 的底部:
    wfLoadExtension( 'TemplateStyles' );
    
  • 按需求配置。
  •   完成 – 在您的wiki上导航至Special:Version,以验证已成功安装扩展。


使用Vagrant安装:

  • 如果使用Vagrant ,请通过vagrant roles enable templatestyles --provision安装
为能使用有语法高亮和自动缩进的代码编辑器,提供更舒适的用户界面,请安装下列扩展:

配置

配置设置
参数 默认 備註
$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" => [
        "<.>"
    ],
]
PCRE正则表达式,用于匹配允许的各种类型的外部引用。

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

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

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

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

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

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

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

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

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

$wgTemplateStylesMaxStylesheetSize 102400 样式表的最大大小(字节)。null表示无限制。
$wgTemplateStylesDefaultNamespace NS_TEMPLATE ‎<templatestyles>标签的src属性的默认命名空间。

其他依赖

$wgTidyConfig 应配置为 no tidying 或者 RemexHtml。 如果与任何 Raggett 驱动程序一起使用,则段落中间的 ‎<templatestyles /> 标记(包括在内联模板中)将导致 tidy 在此处断开段落。 其他驱动程序尚未针对此问题进行测试。

可能的错误

你可以尝试在你的LocalSettings.php中启用$wgShowExceptionDetails 来解决问题。

  • Class 'Wikimedia\CSS\Parser\Parser' not found
    这意味着必需的库没有安装。 该错误可能会在尝试导入一个wiki CSS页面或将页面的内容模型改变为“sanitized-css”时出现。 这在过去很常见,因为扩展分发过程中的bug;应该不会再发生了。
  • Import failed: The content model 'sanitized-css' is not registered on this wiki.
    尝试导入一个由TemlateStyles创建的wiki页面,但TemplateStyles在你的wiki上没有安装时,就会出现这个错误。

参见