Help:TemplateStyles

This page is a translated version of the page Help:TemplateStyles and the translation is 86% complete.

注意: このページを編集すると、編集内容が CC0 のもとで公開されることに同意したと見なされます。詳細はパブリック・ドメインのヘルプページを参照してください。

TemplateStyles enables the complex behavioral and aesthetic styling of templates through the use of referenced external CSS files that are wiki pages themselves. Notably, the ability to create/modify the CSS files is included in the default permissions for autoconfirmed users and so doesn't require involving someone with interface administrator privileges.

動作の仕組み

編集者は、ページに <templatestyles src="[ページ名]" /> を追加できます。参照されるページの内容は CSS として構文解析され、無害化されて、‎<templatestyles> タグが使用されているページ (直接使用されている場合、またはそのページで使用されているテンプレートによって展開されている場合) に読み込まれます。

[some page] には、sanitized-css (サニタイズCSS) コンテントモデルが必要です。このコンテントモデルは、.css で終わるテンプレート名前空間の下位ページにおいて既定です。推奨される使用パターンは、Template:Foo のスタイルを、それが最も影響を及ぼすテンプレートの下位ページ、例えば Template:Foo/styles.css に格納する方法です。 [some page] に名前空間の接頭辞が付かない場合、既定でテンプレート名前空間を読み込みます。従って例えば、<templatestyles src="Foo/styles.css" /> と書かれた場合、読み込まれるのは Template:Foo/styles.css です。

‎<templatestyles>タグは、装飾される本文の前に、理想的にはテンプレートの最上部またはそれにできるだけ近い位置に置くことで、ページが部分的にしかレンダリングされていない状態で最初に表示される場合に、装飾されていないページが出力される可能性を避ける必要があります。

解決される問題

TemplateStyles の利用で利用者は装飾規則を特定のページに割り当てることができ、CSSスタイルシートを十分に機能させつつ危険な構築を除外して、さらに本来の機能としてプレビューやデバッグのツールと共存できます (例: TemplateSandbox )。

アクセスと管理維持の障壁を下げることで、テンプレートの視覚的な設計における新たな発想の促進、保守作業の軽減、そして表示画面への適応性の向上が期待されます (特に、3月 2016 時点でもなおウィキペディアのページ閲覧の過半数を占めているモバイル機器への対応)。

従来、MediaWiki ページ上でテンプレート (やその他のコンテンツ) を装飾する方法は 2 通りありましたが、いずれも以下のいずれにも特にうまく対応できていませんでした:

Using inline styles (that is, raw HTML code with added attributes like style="margin: 10px;")
Using certain special system messages such as MediaWiki:Common.css

インラインスタイルの場合

本文と体裁が分離されません。コンテントがテンプレート（記事の表など）に含まれている場合を除き、記事内にウィキテキストが表示され、ほとんどの編集者には理解できません。
装飾とウィキテキストの混在が原因で、構文強調その他のCSSによる編集支援が困難または不可能になります。
対象となるHTML要素一つひとつに装飾処理をする必要があり、結果として大量のコピー&ペーストやコードが記述されるせいで、読みにくくメンテナンスが困難になります。
style属性は、CSSのサブセットに限定されています。最重要点は、レスポンシブデザインに必要な @media 規則が機能せず、多様な画面幅に対応するテンプレートの作成が不可能なことです。さらにインラインスタイルは、CSSスタイルシートの装飾より優先されるため、利用者固有・外装固有・機器固有のカスタマイズが、より困難になっています。

システムページ向け (MediaWiki:*.css)

編集がインターフェイス管理者に限定されることは、参加の大きな障壁です。
使用できる CSS 規則を制限する方法がないため、編集制限は解除できません。また、一部の古いブラウザーでは、読者の IP アドレスを追跡したり、スクリプトを実行したりするために悪用されるおそれがあります。
まず保存することが前提で、事前に変更のテストができません。 T112474
全てのスタイルシートを（そのページを利用者が使うかどうかを問わず）あらゆるページに読み込む必要があり、帯域幅を無駄遣いし、装飾規則のデバックをより困難にしています。

安全性

安全です! TemplateStyles は本格的な CSS 解析器を含んでおり、CSS の読み込み、再シリアル化、全てのコードのエスケープ、認識しない CSS 規則の除去ができます。この解析器の精度は、外部リソース (例えば背景画像) を拒否し、ローカルリソースは許可するのに十分です。CSS セレクタは、記事コンテンツ外の要素を参照できないように書き換えられます (絶対配置などを利用して記事の一部を移動させ、内容外の領域の視覚的な変更を行う方法は現時点では防止していません。これは、ウィキテキストやインラインスタイルでも既に可能だったため、現状と同じです)。

Allowed CSS properties and rules

As of 2025年3月5日 (水), TemplateStyles accepts no fewer than 331 CSS properties and aliases, including the vast majority of those most often used on the modern internet with official support by one or more major web browser. Beyond simple rules, @media, @page, @supports, @keyframe, @font-face/@font-feature-values at-rules are also supported (with font-face restricted to fonts whose name starts with TemplateStyles, for security reasons).

CSS property declarations permitted by css-sanitizer ^[a]^[b]^[c]

Note: Each property is linked to a source of documentation on its usage, however the typical external link icons have been suppressed to prevent the obscuring of any links to footnotes that similarly appear in superscript.

注記:

↑ This list is current as of changeset ffe10a21512f to the css-sanitizer source code repository, authored at 2025年3月5日 (水) 20:34.
↑ The authoritative reference for these properties will always be the source code for the css-sanitizer library, specifically the src/Sanitizer/StylePropertySanitizer.php file. When reviewing it, a simple method for bringing them into greater focus is to perform a full text search of the contents for the string $props.
↑ Non-standard properties—including those with vendor prefixes, except for the vendor-prefixed -*-user-select group—have never been recognized by this extension and continue to be automatically rejected, as of 1月 2024; see T162379: Decide which non-standard CSS properties to support in TemplateStyles for notice of any progress on a resolution to this issue.
↑ The modern block-ellipsis property is present in the extension source code only by its original name, block-overflow (Line 676 at changeset ffe10a21512f). Though the property was renamed during drafting by the W3C-CSSWG in 8月 2018 and is now only a legacy alias, until the extension is updated only the original property name is accepted as valid.
↑ ^5.0 ^5.1 ^5.2 ^5.3 ^5.4 ^5.5 ^5.6 ^5.7 The page-break-* properties from CSS2 were deprecated by the W3C-CSSWG in 9月 2018 and persist only as legacy shorthands for the break-* replacement properties from the CSS3 Fragmentation module. They are subject to removal in the future and users are strenuously encouraged to replace all uses of the older properties explicitly, paying attention to the fact that not all values have a 1:1 equivalent mapping with the replacements' values. Several popular user agents have already demonstrated flawed and inconsistent behavior when the legacy shorthands are present on a page.
↑ The clip property was deprecated by the W3C-CSSWG in 7月 2018, and official guidance was added to use the clip-path property in its place; it is subject to removal at any time due to definition conflicts with other properties.
↑ The legacy name alias grid-column-gap is also accepted as valid by this extension and is evaluated exactly as if its modern replacement property name, column-gap, had been used.
↑ The modern continue property, which is accepted by this extension, must always be used in place of the older region-fragment property, which it never accepted as valid. The W3C-CSSWG describes 'continue' as generalizing the older property ahead of replacing it altogether, but care must be taken during the conversion as different values must be defined to achieve identical behaviors between the two.
↑ The modern font-width property is present in the extension source code only by its original name, font-stretch (Line 543 at changeset ffe10a21512f). Though the original name was deprecated by the W3C-CSSWG in 1月 2024 and remains only as a legacy alias, until the extension is updated only the original property name is accepted as valid.
↑ The legacy name alias grid-gap is also accepted as valid by this extension and is evaluated exactly as if its modern replacement property name, gap, had been used.
↑ The non-standard property, word-wrap, is also accepted as valid by this extension and is directly aliased to the official property overflow-wrap.
↑ The legacy name alias grid-row-gap is also accepted as valid by this extension and is evaluated exactly as if its modern replacement property name, row-gap, had been used.
↑ ^13.0 ^13.1 Though the creation of the text-align-all property as a constituent value of the text-align shorthand by the W3C-CSSWG took place in 12月 2018, supporting implementations did not begin appearing until 2025 and, as of the most recent official guidance on 3月 24, 2025, the recommendation to eschew the new property and continue to use the shorthand remains in effect.

モバイル版・デスクトップ版の解像度の設定は?

メディアクエリではモバイル版とデスクトップ版で、解像度の要素を指定できます。装飾の仕様はモバイル版に適合させるのが既定で、メディアクエリでデスクトップ向けにラッピングすればよいと教える人がいます。しかしながらMediaWikiではタブレット版とデスクトップ版の表示を640px と 1120px のブレークポイントを標準としている点にご留意ください。

特定の外装限定仕様を作るには？

MediaWikiではhtmlならびにbody要素に多種のクラスを提供し、どの外装を使用しているか示すものもこれに含まれます。. これらをターゲット設定するには、必要なクラスを含むhtmlまたはbody要素に空白スペース（またはCSS用語では子孫コンビネータ）を続けて簡略なセレクタを指定します。

通常はモバイル版やデスクトップ版を区別して考慮するのではなく、この技術を用いてデザイン面の一貫性を保つべきです。どちらの版でもすべての外装を使用できるため、採用する解像度も適合させる必要があります。 #モバイル版・デスクトップ版の解像度の設定は？も合わせて参照してください。

/* Elements with class 'foo' will have red text in all skins. */
.foo { color: red; }

/* Override that element's color to green for the Vector skin only. */
body.skin-vector .foo { color: green; }

/* Add a red border if the browser doesn't have JavaScript enabled. */
html.client-nojs .foo { border: 1px solid red; }

/* Declare that same border as green for the Vector skin. */
html.client-nojs body.skin-vector .foo { border-color: green; }

/* This does not work; the 'body' element must be selected! */
.skin-vector .foo { background: orange; }

/* These do not work, either; the descendant combinator must be used. */
body.skin-vector > .foo { background: orange; }
body.skin-vector ~ .foo { background: orange; }
html.client-nojs > body.skin-vector .foo { background: orange; }

MediaWikiメッセージでスタイルを使用するにはどうすればよいですか？

悪意のある利用者が文書のメインコンテンツ領域以外の部分をいじれないように、すべての CSS 規則の前に自動的に mw-parser-output の CSS クラスが付けられます。 TemplateStyles をベースにしたテンプレートをコンテンツ領域外で使用する場合 (例: sitenotice )、<div class="mw-parser-output">…</div> などでテンプレートを包んで、自分でそのクラスを提供する必要があります。

CSS装飾はどの順で上書きされるか？

どの CSS 規則が効果を発揮するかは詳細度で決まります。(大ざっぱに説明するとセレクターの複雑さです。例えば div.foo { margin: 10px } は .foo { margin: 5px } よりも詳細です。) 特異性が同等であれば、文書に後から出現するCSSスタイルを採用します。

MediaWiki:Common.css やその他のサイトスクリプト、利用者スクリプトやガジェットの読み込み先は、ページの ‎<head> 節です。 TemplateStyles のスタイルシートは ‎<body> に読み込まれ、サイトまたは利用者スクリプトあるいはガジェットの規則と同等の重さを与えられるため、TemplateStyles 2件を充当すると2番目の指定が優先されます。（注意事項として、TemplateStyles 規則は不転写です。同一のスタイルシートを特定のページで複数回指定されても、最初の位置にしか追加されません。

また「後から」とは文中の位置であり、読み込みの順位ではありません。ガジェットがすべて読み込まれるとJavaScriptを使ってページを操作し、固有のCSSを追加します。場合により、例えばボタンを押すなど利用者の特定の操作を待ってオンデマンドで追加します。しかしながら追加する位置が先頭の節であるため、特異性が同等の規則を本文に置いてあると、そちらが優先されます。）

Luaモジュールはどうすればスタイルと相互作用できますか？

TemplateStyles を Lua モジュールから呼び出すにはframe:extensionTagを使います。

コードのサンプルは以下の通りです。

local p = {};

function p.templateStyle( frame, src )
    return frame:extensionTag( 'templatestyles', '', { src = src } );
end

return p;

不正行為対策機能の提供

CSSを別個のページに保存するというデザインの決定には、標準的な不正行為防止ツールセットとの融合を簡単に実現する目的もあります。TemplateStyles CSSページ固有の記述モデル（sanitized-css）に変更を加えると、Extension:AbuseFilter で行う検知と管理にnew_content_model変数を利用できます。

CSS の添付はテンプレート参照読み込みの場合と同様に監視が可能で、「リンク元」オプションで特定のスタイルシートが使われたページを、「ページ情報」で（エディタによっては編集画面でも）どのスタイルシートが使われたかを、「関連ページの更新状況」でページに影響を与えそうな最近の更新を、それぞれ把握できます。

テンプレートスタイルは HTML コードで識別できる情報を残します。特定の規則の出どころ、ページのソースの閲覧、閉じる ‎<style> タグがあると例えば変数 data-mw-deduplicate="TemplateStyles:r123456" を取り、123456 の部分がスタイルシートの版番号を示します (例えば差分表示を使用した場合)。

TemplateStyles を制作する上での意思決定の方法

CSS をテンプレートに含める発想は、コメント募集で提案され、承認されました。技術的な詳細は 2 度目の RfC で決定され、ワークフローの詳細はユーザとの協議を通じて拡充されました。

TemplateStyles の製作者

TemplateStyles はもともと、Wikimedia Reading Infrastructure team (それ以前にCorenがボランティアとして実験) のプロジェクトでした。当時、Brad Jorsch (開発者)、Bryan Davis (マネージャー)、Gergő Tisza (開発者)。担当と責任は移動しました。現在の所有者については、メンテナーのページを参照してください。

エラーの報告や要望の提案

PhabricatorのコンポーネントでTemplateStylesを選び、タスクを提出してください。

実際に使われる場所を見るには

あらかじめ選別したサンプルを閲覧できます。

この機能はウィキメディアの全サイトで有効です。