Help:TemplateStyles

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Help:TemplateStyles and the translation is 61% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎français • ‎română • ‎中文 • ‎日本語 • ‎한국어

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

動作の仕組み

ページに<templatestyles src="[some page]" />というウィキテキストを挿入すると、[some page] の記述がCSSとして解析され、置換した特殊文字を<templatestyles> タグの位置に読み込みます(ページ上で直接、もしくはそのページで使用されるテンプレート内で)。

[some page] には必ずコンテントモデルsanitized-css (Sanitized 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スタイルシートを十分に機能させつつ危険な構築を除外して、さらに本来の機能としてプリビューやデバッグのツールと共存できます(例=テンプレートのサンドボックス)。

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

安全性

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

認識するCSS規則

現在、TemplateStyles は主流を含む複数のブラウザが推奨するCSS3プロパティ(2017年前期時点)のほとんどを受け付けます。単純な規則に加えて@規則のうち@media@page@supports@keyframe及び@font-face@font-feature-valuesも推奨します(セキュリティ上の理由からフォントフェースは名称がTemplateStylesで始まるものに限定)。

現在、標準外のプロパティ(ベンダー接頭辞を含む)は非推奨です。今後の計画についてはT162379をご覧下さい。

How can I target mobile/desktop resolutions?

Media queries allow you to target elements at mobile resolution and desktop resolution. Some advise making your styles mobile friendly by default and wrapping desktop styles within the media query. Note, MediaWiki has standardised on 720px and 1000px breakpoints to represent tablet and desktop.

How can I target specific skins?

MediaWiki provides various classes on the html and body elements, including one that indicates which skin is in use. These can be targeted by including a simple selector for the html or body element including the needed classes, followed by a space (or in CSS terms, the descendant combinator).

Generally, this technique should be used for design consistency, rather than targeting mobile and desktop as all skins can be used in both mobile and desktop resolutions. See also #How can I target mobile/desktop resolutions?.

/* 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; }

In which order do CSS styles override?

Which CSS rule takes effect is controlled by specificity (roughly, the complexity of the selector - e.g. div.foo { margin: 10px } is more specific than .foo { margin: 5px }). In case of equal specificity, CSS styles that come later in the document override earlier styles.

Mediawiki:Commons.css, other site scripts, user scripts and gadgets are loaded in the <head> section of the page. TemplateStyles stylesheets are loaded in the <body>, so they override site/user script and gadget rules with equal specificity, and in the case of two TemplateStyles rules, the second overrides the first. (Note though that TemplateStyles rules are deduplicated: if the same stylesheet is referenced multiple times on the page, it is only inserted the first time. Note also that "later" has to do with document position, not load order. Gadgets add their CSS after the page has fully loaded, by manipulating the page with Javascript; some add it on-demand when the user does some action such as clicking a button. Nevertheless, they add it to the head, so equally-specific CSS rules in the body get precedence over it.)

不正行為対策機能の提供

CSSを別個のページに保存するというデザインの決定には、標準的な不正行為防止ツールセットとの融合を簡単に実現する目的もあります。TemplateStyles CSSページ固有の記述モデル(sanitized-css)に変更を加えると、不正行為フィルターで行う検知と管理に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 (開発者)、Chris Koerner (コミュニティ連絡員)、Dan Garry (製品マネージャー)、Gergő Tisza (開発者)、Grace Gellerman (製品マネージャー)。

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

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

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

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

以下のウィキメディアのサイトはこの機能を有効にしてます(2018年3月付け)。

Calling from a Lua module

TemplateStyles can be called from a Lua module using frame:extensionTag.

Example code is the following:

local p = {};

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

return p;

関連ページ