Help:TemplateStyles

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

TemplateStyles は、インターフェイス管理者権限がなくてもテンプレートにおける複雑な装飾（スタイリング）を実行するツールです。

動作の仕組み

ページに <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>タグはテンプレートの最上部など装飾される本文の前に置くことで、ページの読み込み時に一部がレンダリングされ、装飾されていないページが出力される可能性を避ける必要があります。

解決される問題

今まで、テンプレート（やその他のコンテンツ）を装飾する方法は2通りありました。インライン・スタイル（style="margin: 10px" などHTMLコードを書いて直接、属性を追加）か、MediaWiki:Common.css など特別なシステムメッセージを用いるかでした。どちらの方法も完全には機能していません。

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

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

MediaWiki:*.css システムページを使った場合:

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

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

アクセスと管理維持の障壁を下げた効果として、将来的にテンプレートの視覚効果に新発想が増えたり、多種の表示画面（中でもウィキペディアのページ閲覧の過半数を占めるモバイル機器）に対応できることを期待しています。

安全性

安全です！ TemplateStyles は本格的なCSS解析器を含んでおり、CSSの読み込み、再シリアル化、全てのコードのエスケープ、ホワイトリストに合致しないCSS規則の除去ができます。この解析器の精度はローカルリソースのみ許可し、外部リソース（例えば背景画像）を拒否するには十分です。CSSセレクタは、記事コンテンツ外の要素を参照できないように書き直されます（絶対配置などを利用した記事の一部の配列改変によって、内容以外の領域の見え方を改変する手法は見送りました。ウィキテキストやインライン装飾でも既に同じ結果が出せるため、究極の解決策とはならないからです。）

認識するCSS規則

現在、TemplateStyles は主流を含む複数のブラウザが推奨するCSS3プロパティ（2017年前期時点）のほとんどを受け付けます。単純な規則に加えて@規則のうち@mediaと@page、@supportsと@keyframe及び@font-faceと@font-feature-valuesも推奨します（セキュリティ上の理由からフォントフェースは名称がTemplateStylesで始まるものに限定）。 許可されたプロパティの包括的なリストについては、css-sanitizer のStylePropertySanitizerコードの$propsの部分を参照してください。

現在、標準外のプロパティ (ベンダー接頭辞を含む) は非推奨です。 今後の計画については タスク T162379 を参照してください。

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

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

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

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

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

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

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

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

/* Make that border green in Vector */
html.client-nojs body.skin-vector .foo { border-color: green; }

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

/* These do not work! 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:Commons.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をテンプレートに含める発想は、コメント募集（RfC）で受けた提案が承認されて始まりました。技術面の詳細は2度目のRfCで詰め、ワークフローは ユーザとの協議で固めたものです。

TemplateStyles の製作者

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

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

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

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

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

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

関連ページ

• Extension:TemplateStyles - 特に#Caveats節。
• Wikipedia:TemplateStyles — guideline page on English Wikipedia.