Extension:TemplateStyles

MediaWiki扩展手册

TemplateStyles 发行状态： 稳定版
实现	标签 , ContentHandler , 函数钩
描述	允许模板加载已过滤的CSS样式表。
作者	Brad Jorsch Marc A. Pelletier
最新版本	持续更新
兼容性政策	快照跟随MediaWiki发布。 master分支不向后兼容。
MediaWiki	1.30+
PHP	7.3+
许可协议	GNU通用公眾授權條款2.0或更新版本
下載	下載扩展 Git [?]: 下载Git master 浏览存储库 (Phabricator · GitHub) 提交历史 存储库貢獻者 (GitHub) 代码复核
参数 $wgTemplateStylesUseCodeEditor $wgTemplateStylesDisable $wgTemplateStylesDefaultNamespace $wgTemplateStylesDisallowedAtRules $wgTemplateStylesDisallowedProperties $wgTemplateStylesAllowedUrls $wgTemplateStylesAutoParseContent $wgTemplateStylesMaxStylesheetSize $wgTemplateStylesNamespaces
标签 <templatestyles src=... />
使用的函数钩 CodeEditorGetPageLanguage ContentHandlerDefaultModelFor ParserClearState ParserFirstCallInit
提供的函数钩 TemplateStylesPropertySanitizer TemplateStylesStylesheetSanitizer
季度下載量	1,129 (Ranked 1st)
正在使用的公开wiki数	1,977 (Ranked 199th)
前往translatewiki.net翻譯TemplateStyles扩展
問題	开启的任务 · 报告错误

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>包围。
• 样式应针对特定的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了解潜在问题。）
• 将下列代码放置在您的LocalSettings.php 的底部：

  wfLoadExtension( 'TemplateStyles' );
  

• 按需求配置。
•  完成 – 在您的wiki上导航至Special:Version，以验证已成功安装扩展。

使用Vagrant安装：

• 如果使用Vagrant ，请通过vagrant roles enable templatestyles --provision安装

为能使用有语法高亮和自动缩进的代码编辑器，提供更舒适的用户界面，请安装下列扩展：

• Extension:WikiEditor
• Extension:SyntaxHighlight
• Extension:代码编辑器

配置

配置设置

参数	默认	備註
$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-face的src。 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；应该不会再发生了。
  There is a generally method is update composer under the extension's directory.

• 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上部署此扩展的讨论）
  • Requests for comment/Allow styling in templates
• 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