Help:TemplateStyles - MediaWiki

Help:TemplateStyles - MediaWiki
Jump to content
From mediawiki.org
This page is a
translated version
of the page
Help:TemplateStyles
and the translation is 58% complete.
Languages:
Bahasa Indonesia
Nederlands
bosanski
català
interlingua
polski
português
português do Brasil
română
svenska
čeština
русский
العربية
سنڌي
ไทย
中文
한국어
注意:
このページを編集すると、編集内容が
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
)。
アクセスと管理維持の障壁を下げることで、テンプレートの視覚的な設計における新たな発想の促進、保守作業の軽減、そして表示画面への適応性の向上が期待されます (特に、
2016年3月30日
時点でもなおウィキペディアのページ閲覧の
過半数
を占めているモバイル機器への対応)。
従来、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).
The CSS
var
()
function is permitted only in properties taking a single color value and inside
calc
()
functions.
Setting custom properties is not permitted.
CSS property declarations permitted by css-sanitizer
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.
align-*
align-content
align-items
align-self
animation
animation-delay
animation-direction
animation-duration
animation-fill-mode
animation-iteration-count
animation-name
animation-play-state
animation-timing-function
appearance
aspect-ratio
background
background-attachment
background-blend-mode
background-clip
background-color
background-image
background-origin
background-position
background-repeat
background-size
block-*
block-overflow
block-size
border
border-block
border-block-color
border-block-end
border-block-end-color
border-block-end-style
border-block-end-width
border-block-start
border-block-start-color
border-block-start-style
border-block-start-width
border-block-style
border-block-width
border-bottom
border-bottom-color
border-bottom-left-radius
border-bottom-right-radius
border-bottom-style
border-bottom-width
border-collapse
border-color
border-end-end-radius
border-end-start-radius
border-image
border-image-outset
border-image-repeat
border-image-slice
border-image-source
border-image-width
border-inline
border-inline-color
border-inline-end
border-inline-end-color
border-inline-end-style
border-inline-end-width
border-inline-start
border-inline-start-color
border-inline-start-style
border-inline-start-width
border-inline-style
border-inline-width
border-left
border-left-color
border-left-style
border-left-width
border-radius
border-right
border-right-color
border-right-style
border-right-width
border-spacing
border-start-end-radius
border-start-start-radius
border-style
border-top
border-top-color
border-top-left-radius
border-top-right-radius
border-top-style
border-top-width
border-width
bottom
box-*
box-decoration-break
box-shadow
box-sizing
break-*
break-after
break-before
break-inside
caption-side
caret
caret-color
caret-shape
clear
clip
clip-path
clip-rule
color
color-interpolation-filters
columns
column-count
column-width
column-*
column-fill
column-gap
column-rule
column-rule-color
column-rule-style
column-rule-width
column-span
contain-*
contain-intrinsic-block-size
contain-intrinsic-height
contain-intrinsic-inline-size
contain-intrinsic-size
contain-intrinsic-width
content
continue
counter-*
counter-increment
counter-reset
cursor
direction
display
empty-cells
filter
flex
flex-basis
flex-direction
flex-flow
flex-grow
flex-shrink
flex-wrap
float
flood-*
flood-color
flood-opacity
font
font-family
font-feature-settings
font-kerning
font-size
font-size-adjust
font-stretch
font-style
font-synthesis
font-variant
font-variant-caps
font-variant-east-asian
font-variant-ligatures
font-variant-numeric
font-variant-position
font-weight
gap
grid
grid-area
grid-auto-columns
grid-auto-flow
grid-auto-rows
grid-column
grid-column-end
grid-column-start
grid-row
grid-row-end
grid-row-start
grid-template
grid-template-areas
grid-template-columns
grid-template-rows
hanging-punctuation
height
hyphens
image-*
image-orientation
image-rendering
inline-size
inset
inset-block
inset-block-end
inset-block-start
inset-inline
inset-inline-end
inset-inline-start
isolation
justify-*
justify-content
justify-items
justify-self
left
letter-spacing
lighting-color
line-*
line-break
line-clamp
line-height
list-style
list-style-image
list-style-position
list-style-type
margin
margin-block
margin-block-end
margin-block-start
margin-bottom
margin-inline
margin-inline-end
margin-inline-start
margin-left
margin-right
margin-top
mask
mask-border
mask-border-mode
mask-border-outset
mask-border-repeat
mask-border-slice
mask-border-source
mask-border-width
mask-clip
mask-composite
mask-image
mask-mode
mask-origin
mask-position
mask-repeat
mask-size
mask-type
max-*
max-block-size
max-height
max-inline-size
max-width
max-lines
min-*
min-block-size
min-height
min-inline-size
min-width
min-intrinsic-sizing
mix-blend-mode
nav-*
nav-down
nav-left
nav-right
nav-up
object-*
object-fit
object-position
offset-*
offset-anchor
offset-position
offset-path
offset-distance
offset-rotate
offset-after
offset-before
offset-end
offset-start
opacity
order
orphans
outline
outline-color
outline-offset
outline-style
outline-width
overflow
overflow-block
overflow-inline
overflow-wrap
overflow-x
overflow-y
padding
padding-block
padding-block-end
padding-block-start
padding-bottom
padding-inline
padding-inline-end
padding-inline-start
padding-left
padding-right
padding-top
page-break-*
page-break-after
page-break-before
page-break-inside
place-*
place-content
place-items
place-self
position
quotes
resize
right
row-gap
shape-*
shape-image-threshold
shape-margin
shape-outside
tab-size
table-layout
text-*
text-align
text-align-all
text-align-last
text-combine-upright
text-decoration
text-decoration-color
text-decoration-line
text-decoration-style
text-emphasis
text-emphasis-color
text-emphasis-position
text-emphasis-style
text-indent
text-justify
text-orientation
text-overflow
text-shadow
text-transform
text-underline-position
top
transform
transform-box
transform-origin
transition
transition-delay
transition-duration
transition-property
transition-timing-function
unicode-bidi
user-select
-moz-user-select
-ms-user-select
-webkit-user-select
vertical-align
visibility
white-space
widows
width
word-break
word-spacing
writing-mode
z-index
注記:
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
2024年1月2日
; see
phab: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
StylePropertySanitizer.php
).
Though the property was
renamed during drafting by the
W3C-CSSWG
in
2018年8月24日
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
2018年9月15日
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
2018年7月22日
, 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
StylePropertySanitizer.php
).
Though the original name was
deprecated by the
W3C-CSSWG
in
2024年1月23日
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.
11.0
11.1
The
offset-*
properties were
renamed
inset-
in
2025年3月11日
by the
W3C-CSSWG
in the CSS Position 3 module, which supersedes and replaces CSS Logical 1.
The
'flow-relative offsets' are now renamed in concordance
inset-block-start
、​
inset-block-end
、​
inset-inline-start
、​
inset-inline-end
properties and
inset-block
、​
inset-inline
および
inset
shorthands.
The deprecated
offset-*
properties
should be distinguished from the still existant
offset-
shorthands
offset-anchor
、​
offset-position
、​
offset-path
、​
offset-distance
および
offset-rotate
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.
14.0
14.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
2018年12月6日
, supporting implementations did not begin
appearing until 2025
and, as of the most recent official guidance on
2025年3月24日
, 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
px
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
10
px
foo
margin
px
よりも詳細です。)
特異性が同等であれば、文書に後から出現するCSSスタイルを採用します。
MediaWiki:Common.css
やその他のサイトスクリプト、利用者スクリプトやガジェットの読み込み先は、ページの
‎<
head
節です。
TemplateStyles のスタイルシートは
‎<
body
に読み込まれ、サイトまたは利用者スクリプトあるいはガジェットの規則と同等の重さを与えられるため、TemplateStyles 2件を充当すると2番目の指定が優先されます。
（注意事項として、TemplateStyles 規則は不転写です。同一のスタイルシートを特定のページで複数回指定されても、最初の位置にしか追加されません。
また「後から」とは文中の位置であり、読み込みの順位ではありません。
ガジェットがすべて読み込まれるとJavaScriptを使ってページを操作し、固有のCSSを追加します。場合により、例えばボタンを押すなど利用者の特定の操作を待ってオンデマンドで追加します。
しかしながら追加する位置が先頭の節であるため、特異性が同等の規則を本文に置いてあると、そちらが優先されます。）
Luaモジュールはどうすればスタイルと相互作用できますか？
TemplateStyles を Lua モジュールから呼び出すには
frame:extensionTag
を使います。
コードのサンプルは以下の通りです。
local
{};
function
templateStyle
frame
src
return
frame
extensionTag
'templatestyles'
''
src
src
);
end
return
不正行為対策機能の提供
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を選び、
タスクを提出
してください。
実際に使われる場所を見るには
あらかじめ選別したサンプル
を閲覧できます。
この機能はウィキメディアの全サイトで有効です。
Help with errors
background-image
If you receive the following error when trying to publish the changes to your CSS file:
$1
行目
$2
文字目のプロパティ
background-image
に、無効またはサポートされていない値が指定されています。
It could be that the
url('...');
attribute given to
background-image
is not pointing to a local resource.
The parser only allows local resources (and rejects remote ones).
Only URLs which point to resources at
//upload.wikimedia.org/
are permitted, for example
//upload.wikimedia.org/wikipedia/commons/8/83/MediaWiki-2023-button-proposal.svg
for the file at
File:MediaWiki-2023-button-proposal.svg
These URLs can be obtained by using the URL address that links point to on
ウィキメディア・コモンズ
file pages.
These links include those to "Original file" or any of the links to the file's "Other resolutions:" such as
1,024 × 1,024 pixels
関連ページ
Extension:TemplateStyles
– 特に
#Caveats
節。
Wikipedia:TemplateStyles
guideline page on English Wikipedia.
Retrieved from "
Category
Help/ja
Help:TemplateStyles
Add topic