CSS Linked Parameters Module Level 1（日本語訳）

◎要約

この仕様は、 ~CSS値を~link先の資源 — ~SVG画像など — の中へ渡す仕方を導入する — それらの値が行先~資源~内で~CSS`~custom環境~変数$用の値として利用できるよう。これは、 “~template化された” ~SVG画像の容易な再利用を許容する — それは、 ~source~SVGを改変する必要なく， ~siteの~theme色, 等々に容易に順応させれる。 ◎ This spec introduces a way to pass CSS values into linked resources, such as SVG images, so that they can be used as CSS custom environment variables in the destination resource. This allows easy reuse of "templated" SVG images, which can be adapted to a site’s theme color, etc. easily, without having to modify the source SVG.

~CSSisaLANG

1. 序論

~SVGは、 ~CSSで~style可能である — この能力は、 ~HTML内に~inlineに利用するときごく有用になり得る。例えば，~SVG~iconは、利用者がそれを~hoverしているか否かに基づいて，異なる色をとれる — それに `fill$p ~propを変更する `hover$ps 規則を適用するだけで。 ◎ SVG is stylable with CSS, and when used inline in HTML, this capability can be very useful. For example, an SVG icon can take on a different color based on whether the user is hovering it or not, just by applying a :hover rule to it that changes the fill property.

~SVG画像が［外縁~pageからの［ `選択子$／`継承$ ］を自身に適用することを許容しない仕方］で参照されるときには（ ~HTML内の［ `img$e ／ `iframe$e ］を介してそれを埋込むなど）、この機能性は失われる。そのような “外部” ~SVG画像の表示を変更するための仕方は、一連の画像を生産して，どの画像を参照するか変更する他にない。そのようにした場合、新たな資源が~downloadされるに伴い，当の~pageは遅延を被ることに加え、 ~CSS遷移の様な動的な効果は許容されない。 ◎ When the SVG is referenced in a way that doesn’t allow selectors or CSS inheritance from the outer page to apply to it (such as embedding it via img or iframe in HTML), though, this functionality is lost. The only way to change the display of such "external" SVG images is to produce several of them, and change which image you’re referencing. This incurs delay on the page as a new resource is downloaded, and disallows dynamic effects like CSS Transitions.

~CSS `~link~parameter@ は、 “外部” 資源に対し［ ~CSS~propにより／ ~URLの特別な素片~schemeを通して］~CSS`~custom環境~変数$を設定するための仕方を与える。これは、 “~inlineな” ~SVG画像が有する~custom化~能を成す — 制限されるが，強力な — 下位集合を “外部” ~SVG画像に与える。 ◎ CSS link parameters are a way to set CSS custom environment variables on an "external" resource, either by a CSS property or thru a special fragment scheme on the URL. This gives a limited, but powerful, subset of the customizability that "inline" SVG images have to "external" SVG images.

【 `~custom環境~変数@ は、参照~先が不明な未定義な用語 — おそらく， `CSS-MIXINS-1$r か `CSS-ENV-1$r にて定義されることになると思われる。】

各`~link~parameter$は、次が成す~pairである ⇒＃ `dashed-ident$t が成す名前, `declaration-value$t が成す任意な値, または空な値 ◎ A link parameter is a pair of a <dashed-ident> name, and an arbitrary (possibly empty) <declaration-value> value.

例えば，~SVG画像は、 `~link~parameter$を利用して，［その色が，その場で変更されることを許容する］よう書くこともできる — 次の様に： ◎ For example, an SVG image can be written to use link parameters, allowing it to have its colors changed on the fly, like:

<svg>
  <path fill="env(--color, black)" d="..." />
</svg>

それは，既定では［自身の図形を~fallback用に指定された色 `black^v で~fillする］ことになるが、 `~link~parameter$は，次に挙げる仕方でこの色を~custom化できる： ◎ By default, it will fill its shape with black, as that’s the fallback color specified. But link parameters can customize the color in several ways:

<img src="image.svg#param(--color,green)">

img {
  link-parameters: param(color, green);
}

.foo {
  background-image: url("image.svg", param(--color, green));
}

2. ~link~parameterの設定-法

外部~資源には、 `~link~parameter$たちが成す~listを付随させれる。【！重複:, each entry composed of ... 】 ◎ An external resource can be accompanied by a list of link parameters, each entry composed of a <dashed-ident> as a key, and a (possibly empty) <declaration-value> as the value.

`~link~parameter$を指定する仕方には、次に挙げる 3 種がある： ◎ There are three ways to specify a link parameter:

`link-parameters$p ~propを介して — それは、次に挙げるものに適用される：
- 当の要素が外部~資源を表現するならば，それ
- 当の要素の~propに利用されるすべての外部~資源
◎ via the link-parameters property, which applies to the resource itself (if the element represents an external resource), and to all external resources used in CSS properties on the element
外部~資源の~URLを成す素片~部位における特別な構文を介して ◎ via a special syntax in the fragment portion of the URL of an external resource
`url$t【！`url^f】構文における `param^f 引数を介して ◎ via a param() argument in the url() syntax

これらのうち複数の仕方で指定された場合、 `~link~parameter$たちは，外部~資源~用には単独の~listの中へ次に挙げる順序で付加される： ◎ If specified in multiple of these ways, all of the link parameters are appended into a single list for the external resource, in the order:

当の要素の `link-parameters$p ~prop【！, if relevant】 ◎ the link-parameters property on the element, if relevant
`~SVG~parameter素片~識別子$ ◎ the param() URL fragment identifiers
`url$t【！`url^f】内の `url-modifier$t として与えられた `param$f ◎ the param() <url-modifier>s in url()

同じ名前を伴う複数個の`~link~parameter$が存在する場合、当の~list内の最後のものが利用される。 ◎ If multiple link parameters exist with the same name, the last one in the list is used.

~link先の資源~内で`~link~parameter$へ~accessする方法は、 `§ ~link~parameterの利用-法＠#using$ にて定義される。 ◎ How to access link parameters in the linked resource is defined in the next section, § 3 Using Link Parameters.

2.1. ~CSSを介した設定-法： `link-parameters$p ~prop

◎名 `link-parameters@p ◎値 `none$v | `param()$t# ◎初 `none$v ◎適すべての要素, すべての疑似要素 ◎継されない ◎百受容しない ◎算指定されたとおり ◎順文法に従う ◎ア離散的 ◎表終 ◎ Name: link-parameters Value: none | <link-param>+ Initial: none Applies to: all elements and pseudo-elements Inherited: no Percentages: n/a Computed value: as specified Canonical order: per grammar Animation type: discrete

`link-parameters$p ~propは、次に挙げるものに`~link~parameter$を設定する仕方を成す： ◎ The link-parameters property is one way to set link parameters＼

要素が外部~資源を表現しているならば（~HTML `img$e や `iframe$e など）、その資源。 ◎ on the element itself (if it is an element representing an external resource, such as an HTML img or iframe),＼
~CSSを介して要素に指定されたすべての外部~資源（背景~画像, 等々）。 ◎ and on all external CSS resources specified on the element (such as background images, etc).＼

各種~値の意味は： ◎ Its values are:

`none@v: 指定される`~link~parameter$は無い。 ◎ No link parameters specified.
`param()$t#: `~link~parameter$たちが成す空でない~list。 ◎ A list of one or more link parameters.

`param@f 関数は、ある`~link~parameter$を指定する — それは、 ~keyとして `dashed-ident$t, 値として `declaration-value$t （省略された場合は空な値）を伴う。その構文は： ◎ The param() function specifies a link parameter, with a key of the <dashed-ident>, and a value of the <declaration-value>?. (If the <declaration-value> is omitted, it represents an empty value.) It has the syntax:

`param()$t
	= param( `dashed-ident$t , `declaration-value$t? )

2.2. ~URLを介した設定-法

外部~資源を参照するために利用される~URLの`素片$urlにおいては、既存の`~SVG素片~識別子＠~SVGlinking#svg-fragment-identifier$【！SVG 1.1 ~SVG11/linking.html#LinksIntoSVG】に類似な，特別な “素片~識別子” として `~SVG~parameter素片~識別子@ を利用できる† — その構文は： ◎ A special "fragment identifier" can be used in the fragment of a URL used to reference an external resource. Several examples of existing "fragment identifiers" for SVG documents can be found in the SVG 1.1 specification. ◎ The syntax of an SVG parameter fragment identifier is:

【† ~SVGを名前に含んでいるが、 ~SVGに限られるものと定義されてはいない。】

param( `dashed-ident$t , `declaration-value$t )

【 `param()$t と違って， `declaration-value^t は省略可能でない。】

（これは、【~SVGの `SVGFragmentIdentifier＠~SVGlinking#_SVGFragmentIdentifier$c 用の構文ではなく，】 ~CSSの`値~定義の構文$を利用する。） ◎ (using the CSS value definition syntax;＼

この構文~用に，実際の構文解析器を定義する。 ◎ TODO define an actual parser for it).

例えば、次の様な~URLで~SVG画像を参照すれば，当の画像の`~custom環境~変数$ `env(--text-color)^v を `blue$v に設定できる ⇒ `http://example.com/image.svg#param(--text-color,blue)^l ◎ For example, to set the env(--text-color) custom environment variable of an SVG image to blue, one can reference the image with a url like “http://example.com/image.svg#param(--text-color,blue)”.

画像には複数個の`~link~parameter$を渡せる — 当の~URLに複数個の`~SVG~parameter素片~識別子$を付加することにより。 ◎ Multiple link parameters can be passed to an image by appending multiple param() fragment identifiers to the URL.

例えば，前の例の画像が `env(--bg-color)^v も利用していた場合、次の様な~URLで参照すれば，［ `env(--text-color)^v, `env(--bg-color)^v ］どちらも設定できる ⇒ `http://example.com/image.svg#param(--text-color,blue)param(--bg-color,white)^l ◎ For example, if the image from the previous example also used env(--bg-color), it could be referenced with a url like “http://example.com/image.svg#param(--text-color,blue)param(--bg-color,white)” to set both env(--text-color) and env(--bg-color).

注記： ~spaceその他のある種の【！some】文字は、 ~CSS構文においては妥当であっても， ~URLにおいては【！technically】妥当でないかもしれない。一部の文脈においては、［妥当な~URLを形成するよう，それらの文字を~escapeする必要がある］かもしれない。ほとんどの事例 — ~HTMLの `a$e 要素【の `href^a 属性】や ~CSSの `url$f 関数など — では、 ~spaceは受容され，~escapeする必要はないが。【~commaを利用するよう構文が更新されたため、この注記は，いくぶん関連しなくなった。】 ◎ Note: Spaces, and some other characters that might be valid in CSS syntax, are not technically valid in URLs. In some contexts, you might need to escape those characters to form a valid URL. In most cases, though, such as HTML’s a element or CSS’s url() function, spaces are accepted and do not need to be escaped.

2.3. `url^f 関数を介した設定-法

外部~資源を `url$f 関数などの~CSSを介して参照するとき，共通的に求まれる利用事例は、当の~pageの自前の`~custom~prop$の値を当の資源へ — 例えば、その値を~SVG画像の呈示に反映させるために — 渡すことだが， ~custom~propの値を `url^f 関数へ渡す~URLの中へ統合する仕方は無い。 ◎ When referencing an external resource via CSS, the param() function can be used in the url() function. But a common use-case is passing in values of the page’s own custom properties; for example, a page might use a --primary-color custom property, and want to make an SVG image match. There’s no way, however, to integrate the value of a custom property in CSS into the URL passed to the url() function.

そのような利用事例を収容するため、 `param$f を `url$t を成す妥当な `url-modifier$t として利用できる。 `url-modifier$t として指定され各 `param$f は、 `link-parameters$p 用のそれらと同じく， `~link~parameter$を定義する。 ◎ To accommodate this, param() is a valid <url-modifier>. All the param()s specified as a <url-modifier> define link parameters, as for link-parameters.

例えば、ある~siteが `--primary-color^p ~custom~propを~pageの~theme色に利用していて，それを `env(--color)^v を利用している~SVG背景に反映させるよう求める場合、次のように書くこともできる： ◎ For example, if the site is using a --primary-color custom property to theme its elements with, and wanted an SVG background using env(--color) to reflect it, it could write:

.foo {
  background-image: url(
    "http://example.com/image.svg"
    param(--color, var(--primary-color))
  );
}

3. ~link~parameterの利用-法

ある外部~資源~linkに 1 個以上の`~link~parameter$が指定されたとき， ~link先の資源が~CSSを解するならば（~SVG文書や~HTML文書など）、それら各`~link~parameter$は，当の資源~用に`~custom環境~変数$ — 各自の［名前, 値］を伴う, 大域的な, ~stylesheet内で `env$f 関数†により~access可能な変数 — を確立する。 ◎ When an external resource link has one or more link parameters specified, if the linked resource understands CSS (such as an SVG or HTML document), then those link parameters establish global custom environment variables for the resource with their name and value, accessible with the env() function in stylesheets.

【† この仕様に現れる `env$f は、 `CSS-ENV-1$r にて定義されるが，実際には［ `~custom環境~変数$用に定義されるものと見込まれる，それ］を指す。】

例えば，ある~SVG画像が `--color^p ~parameterを公開するよう求めていた場合、それを次の様に利用することもできる： ◎ For example, if an SVG image wanted to expose a --color parameter, it could use it like:

<svg>
  <g style="fill: env(--color);">
    <path d="..." />
  </g>
</svg>

注記： ~parameterが与えられなかった場合でも，~SVG画像を — 各`~custom~prop$用に “既定の値” を供することにより — 利用-可能にすることは、通例的に良い案になる。これを行う仕方は，いくつかある： ◎ It’s usually a good idea to make your SVG image usable even if no parameters are given, by providing "default values" for each of the custom properties. There are several ways to do this.

各 `env$f 関数に~fallback値を供する — `fill$p: `env(--color, blue)^v の様に。 ◎ On each env() function, provide a fallback value, like fill: env(--color, blue).
前項の仕方では面倒事になるまでに， `env$f が何度も利用される場合、当の`~custom環境~変数$を［名前が異なり, 既定の値を伴う`視野~付き環境~変数$ ］内に格納する — 次の様に： ◎ If the env() is going to be used a lot, such that providing a fallback for each individual env() is troublesome, store the custom environment variable in a scoped environment variable of a different name, with the default specified, like:
```
@env --color2: env(--color, blue);
```
あるいは、代替として，それをある`~custom~prop$内に格納する： ◎ /* Alternately, store it in a custom property: */
```
:root {
  --color: env(--color, blue);
}
```
この例においては、 `env(--color2)^v は、［ `--color^css が`~link~parameter$を介して供されたならばその値／他の場合は既定の値 `blue$v ］を包含することになる。どちらの事例でも、 `env(--color2)^css は，~stylesheetにおいて無条件に — すなわち，常に値を有することを知った上で — 利用できる。 ◎ In this example, if --color is provided via a linked parameter, env(--color2) will contain its value. If not, it will contain the default blue value. In either case, env(--color2) can be used in the stylesheet unconditionally, secure in the knowledge that it will always have a value.

注記： `env(parent --color)^v が定義されたなら、視野~levelを違えるために改称する必要はなくなり， @env --color: `env(parent --color)^v; だけで申し分なく働くことになる。 ◎ Note: When we define env(parent --color) to jump up a scope level, you won’t need to do the rename; @env --color: env(parent --color); will work just fine.

~privacyの考慮点

この仕様が導入する新たな~privacyの考慮点は無い。 ◎ This specification introduces no new privacy considerations.

~securityの考慮点

この仕様は、［敵対的な~sourceから~link先の資源へ情報を渡す新たな仕方］を導入するものになり得る。 ◎ This specification introduces a new way to pass information to a linked resource, potentially from a hostile source.

この~channel用に確立される明示的な~handshakeは無いが、当の情報を利用するための `env$f の利用は， ~link先の資源が当の情報により`意に沿わなく^emなり得る機会cを最小~化する。 ~pageにとって脆弱になる唯一の仕方は，自身の~styleに`未知^emな `env$f を利用することだが、それは，既定では［無効な~propになるだけであり，開発~toolにおいて開発者から可視になる］。 ◎ While no explicit handshake is established for this channel, the use of env() to use the information minimizes the chance that the linked resource can be surprised by the information. The only way for the page to be vulnerable is to somehow be using an unknown env() in their styles, which will just result in invalid properties by default, and be visible in the developer’s Dev Tools.

敵対的な情報は、当の資源が明示的に任意選択した個々の~CSS~propにしか【！also only】影響し得ない。 ◎ Any hostile information can also only affect individual CSS properties that the resource explicitly opts itself into.