Extension:TemplateStyles/zh
TemplateStyles是一个解析器扩展，可讓用户在wiki页面存放自定义的CSS并通过<templatestyles>标签将这些样式嵌入进条目中。 此扩展只允许在可嵌入样式页面中儲存一個安全的CSS语法子集。这是由css-sanitizer函式庫驅動的。
我们鼓励编辑者通过TemplateStyles包含用于模板的样式，因为这允许能编辑模板的用户也能编辑样式，而且如此一来样式只会在需要的时候加载（相对于加入全站的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>包围。
- 如要使TemplateStyles在像w:MediaWiki:Protectedpagetext这样的内容中生效，需将这个消息内容用
- 样式应针对特定的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（例如空格）。body或html元素的其他类也应该以相同的方式指定。 See phab:T197617. 1.32+
安裝
- 下载，并将解压后的
TemplateStyles移动到extensions/目录中。
开发者和代码贡献人员应从Git安装扩展，输入：cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateStyles
- 只有是從Git安裝的才需Composer来安装PHP，发行
composer install --no-dev至的目录。 （参见T173141了解潜在问题。）Category:Extensions requiring Composer with git/zh - 将下列放置在您的LocalSettings.php的底部：
wfLoadExtension( 'TemplateStyles' );
完成 – 在您的wiki上至Special:Version，以验证已成功安装。
- 如果使用Vagrant，请
vagrant roles enable templatestyles --provision安装
- :
- [[Special:MyLanguage/Extension:SyntaxHighlight|:Category:Pages using Lc zh with unknown or deprecated arguments#zh]]
- :
| 備註 | ||
|---|---|---|
$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。当前的外部引用类型有： |
$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页面之外，则手动将 |
$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；应该不会再发生了。
- Running Composer for the extension would usually be the fix for this issue.
Import failed: The content model 'sanitized-css' is not registered on this wiki.- 尝试导入一个由TemlateStyles创建的wiki页面，但TemplateStyles在你的wiki上没有安装时，就会出现这个错误。
参见
- Help:模板樣式
- css-sanitizer - 用于过滤CSS。
- phab:T483 "RfC: Allow styling in templates"（关于在维基媒体的wiki上部署此扩展的讨论）
- phab:T56864 “ResourceLoader：更少地在wiki模块（用户和站点）内实现支持，更少支持例如MediaWiki:Common等页面”
- phab:T155813 “决定TemplateStyles CSS存储和分发方法”
- It’s now easier to craft content for mobile devices: Responsive web design at the Wikipedia scale（英文页面，标题大意：现在在移动设备做内容更加容易：维基百科尺度下的响应式网页设计），位于维基媒体博客。
- 扩展:TemplateStylesExtender
 | 此用于一个或多个维基媒体项目。 这可能意味着足够稳定、运作足够良好，可以用在这样的高流量的网站上。 请在维基媒体的CommonSettings.php和InitialiseSettings.php中查找此的名称以查看哪些网站安装了该。 特定wiki上的已安装的的完整列表位于Special:Version页面。 |
