【この訳に特有な表記規約】
◎表記記号この仕様に現れる`~URL$は、 いくつかの箇所で,それを`直列化した結果@~URL1#concept-url-serializer$と暗黙的に同一視されている。
他所を集約するため、
次も定義する
⇒
ある特能が
`~risk下@
にあるとは、
`W3C Process^cite
にて定義される`~risk下@https://www.w3.org/2020/Process-20200915/#at-risk$を意味する
⇒
当の特能は、
勧告案へ進む前に,除去してもヨイ
— 新たな勧告候補を公表する要件を満たすことなく。
◎
[The feature] may be removed before advancement to Proposed Recommendation without a requirement to publish a new Candidate Recommendation.
1. ~web~app~manifest
`~app~manifest@ ( `application manifest^en, 略して “~manifest” ) は、 ~web~appが立上げられるときの[ 開始-時の~parameter, ~appの既定 ]を包含する~JSON `JSON$r 文書である。 ◎ An application manifest is a [JSON] document that contains startup parameters and application defaults for when a web application is launched.
各`~manifest$には、 それが~fetchされた`~URL$ `URL$r として `~manifest~URL@ が結付けられる。 【この用語は、この仕様~内ではどこからも参照されていないが,~algoの引数~名として現れている。】 ◎ A manifest has an associated manifest URL, which is the [URL] from which the manifest was fetched.
`~manifest$の根は、 次に挙げる~memberを有し得る。 これらの~memberは、 どれも省略可能であり,どの順序でも現れ得る: ◎ A manifest can have any of the following members at its root, all of which are optional. The members can appear in any order.
- `background_color$mM
- `dir$mM
- `display$mM
- `icons$mM
- `id$mM【!`識別情報$】
- `lang$mM
- `name$mM
- `orientation$mM
- `prefer_related_applications$mM
- `related_applications$mM
- `scope$mM
- `short_name$mM
- `shortcuts$mM
- `start_url$mM
- `theme_color$mM
注記: ~manifestを成す どの~memberも省略可能であるが、 うち一部は,[ 一部の~UAにおいて、 この仕様が与する能力の利点を全部的にとるために要求される ]かもしれない。 ◎ Note Although it is optional for any member to appear in a manifest, some user agents might require one or more to be present to take full advantage of the capabilities afforded by this specification.
1.1. 例
◎非規範的こので節は、 開発者がこの仕様の様々な特能をどう用立てれるかを示す。 ◎ This section shows how developers can make use of the various features of this specification.
1.1.1. 典型的な構造
◎非規範的以下に典型的な`~manifest$を示す: ◎ The following shows a typical manifest.
典型的な`~manifest$: ◎ Example 1: Typical manifest
{ "lang": "en", "dir": "ltr", "name": "Super Racer 3000", "short_name": "Racer3K", "icons": [{ "src": "icon/lowres.webp", "sizes": "64x64", "type": "image/webp" }, { "src": "icon/lowres.png", "sizes": "64x64" }, { "src": "icon/hd_hi", "sizes": "128x128" }], "scope": "/", "id": "superracer", "start_url": "/start.html", "display": "fullscreen", "orientation": "landscape", "theme_color": "aliceblue", "background_color": "red" }
1.1.2. `link^e 要素を利用して~manifestへ~linkする
◎非規範的この例は、 ~link型 `manifest$v, および他の[ `link$e, `meta$e ]要素を利用して,~fallback用の[ 名前, ~iconたちが成す集合 ]を~web~appに与える方法も示す: ◎ The example also shows how to use the link type "manifest" and how to use other meta and link elements to give the web application a fallback name and set of icons.
~manifestへの~link法 ◎ Example 2: Linking to a manifest
<!doctype> <html> <title>Racer 3K</title> <!-- 開始-時の環境設定 ◎ Startup configuration --> <link rel="manifest" href="manifest.webmanifest"> <!-- 旧来の~browser用の~fallback~app~metadata ◎ Fallback application metadata for legacy browsers --> <meta name="application-name" content="Racer3K"> <link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico"> <link rel="icon" sizes="512x512" href="hi_def.png">
注記: ~manifest用の~file拡張子は、 `.webmanifest^c であり,~IANAに登録された ( `§ ~IANA考慮点@#iana-considerations$ )。 一部の~web~serverは、 この拡張子を認識して,当の~fileを[ 標準~化された`~app~manifest~MIME型$ ( `application/manifest+json^c ) ]を利用して転送する。 開発者は, 異なる拡張子(例:`.json^c ), あるいは何もなし(例: `/api/GetManifest^c ) も選べるが、[ `~MIME型$ `application/manifest+json$c を利用して~manifestを転送する ]ことが奨励される — 他の`~JSON~MIME型$でもかまわないが。 ◎ Note: File extension: .webmanifest or .json? The IANA registered file extension for the manifest is .webmanifest. Some web servers recognize this extension and transfer the file using the standardized application manifest media type (application/manifest+json). Developers can also choose a different extension (e.g. .json) or none at all (e.g. /api/GetManifest), but are encouraged to transfer the manifest using the application/manifest+json MIME type, although any JSON MIME type is ok.
1.1.3. 複数の~iconの宣言-法
◎非規範的次の例では、 開発者は,~web~appに結付けられる~iconを次のように選んでいる: ◎ In the following example, the developer has made the following choices about the icons associated with the web application:
- まず、 同じ~size, 異なる形式の 2 つの~iconを含ませた。 うち 1 つは、 `type^mI ~memberを通して明示的に~WebPとして~markされている。 ~UAが~WebPを~supportしない場合、 同じ~sizeのもう 1 つの~iconに~fall-backする。 この~iconの`~MIME型$は、 ~HTTP~headerを介して決定されるか, ~UAが~iconを成す最初の少数の~byteを受信したとき`~sniff@~MIMESNIFF#computed-mime-type$され得る。 ◎ The developer has included two icons at the same size, but in two different formats. One is explicitly marked as WebP through the type member. If the user agent doesn't support WebP, it falls back to the second icon of the same size. The MIME type of this icon can then be either determined via a HTTP header, or can be sniffed by the user agent once the first few bytes of the icon are received.
- 開発者は 257×257 px 以上には~SVGを利用したかったが、 その~SVG~fileは,小さな~sizeでは高密度な~screenでも ぼやけ過ぎに見えたため、 寸法が 257px 以上の所に限り利用されるよう,~SVG~iconを含めた。 他の場合、 ~UAは~ICO~file( `hd_hi.ico^c )を利用する — それは、 何段階かの小さな表示~sizeごとに個別に誂えられた,何個かの~raster~iconからなる。 ◎ The developer wants to use an SVG for greater than or equal to 257x257px. They've found that the SVG file looks too blurry at small sizes, even on high-density screens. To deal with this problem, the developer includes an SVG icon that is only used when the dimensions are at least 257px. Otherwise, the user agent uses the ICO file (hd_hi.ico), which includes a gamut of raster icons individually tailored for small display sizes. ◎ Example 3: Multiple icons
{ "icons": [ { "src": "icon/lowres.webp", "sizes": "48x48", "type": "image/webp" },{ "src": "icon/lowres", "sizes": "48x48" },{ "src": "icon/hd_hi.ico", "sizes": "72x72 96x96 128x128 256x256" },{ "src": "icon/hd_hi.svg", "sizes": "257x257" }] }
1.1.4. ~shortcutの作成-法
◎非規範的次の例では、 開発者は 2 個の~shortcutを含めている。 ~manifestの~URLは `https://example.com/manifest.webmanifest^samp と見做すなら: ◎ In the following example, the developer has included two shortcuts. Assuming the manifest's URL is https://example.com/manifest.webmanifest:
- 1 個目の~shortcutは、 ~text "Play Later" を伴って表示されることになる。 ~OSが[ 文脈~menu~item用の~iconを~supportしていて, その目的~用に~SVG画像も~supportする ]場合、 ~UAは~textの傍に `https://example.com/icons/play-later.svg^samp にある~SVG画像を呈示することになる。 ~appが立上げられたとき,~UAは、 新たな`~top-level閲覧~文脈$を~instance化して, `https://example.com/play-later^samp へ~navigateすることになる。 ◎ The first shortcut would be displayed with the text "Play Later". If the operating system supports icons for context menu items and it also supports SVG images for that purpose, the user agent would present https://example.com/icons/play-later.svg next to the text. When launched, the user agent would instantiate a new top-level browsing context and navigate to https://example.com/play-later.
- 2 個目の~shortcutは、 ~text "Subscriptions" を伴って表示されることになる。 ~appが立上げられたとき,~UAは、 新たな`~top-level閲覧~文脈$を~instance化して, `https://example.com/subscriptions?sort=desc^samp へ~navigateすることになる。 ◎ The second shortcut would be displayed with the text "Subscriptions". When launched, the user agent would instantiate a new top-level browsing context and navigate to https://example.com/subscriptions?sort=desc. ◎ Example 4: Adding shortcuts
{ "shortcuts": [ { "name": "Play Later", "description": "View the list of podcasts you saved for later", "url": "/play-later", "icons": [ { "src": "/icons/play-later.svg", "type": "image/svg+xml" } ] }, { "name": "Subscriptions", "description": "View the list of podcasts you listen to", "url": "/subscriptions?sort=desc" } ] }
1.1.5. “~scope” の理解
◎非規範的`scope$mM ~memberは、 どの文書が~web~appの一部を成し,どれがそうでないか — よって、 利用者が ある~web~site周りで~navigateするとき, 当の~manifestが`適用-$される~web~pageたちが成す集合 — を~browserに伝える。 ◎ The scope member tells the browser which documents are part of a web application, and which are not - and hence, to which set of web pages the manifest is "applied" when the user navigates around a web site.
例えば, `{"scope": "/"}^c は、 当の~manifestは,ある生成元~内のあらゆる文書に適用されることを意味する。 他方, `{"scope": "/racer/"}^c は、[ ~path `/racer/^l の中の文書に限り,`~scopeの中$にある ]ことを意味する — なので、[ `/racer/race1.html^l, `/racer/race2.html^l, 等々 ]は,どれも`~scopeの中$にあるが、 それら以外の[ `/elsewhere/^l や `/^l の中にあるもの ]は “~scopeの外” にあり,[ 当の~manifestは,それらの~path内の文書には適用されない ]ことになる。 ~supportされる~scope~pathは 1 個に限られる。 技術的な詳細は、 `§ ~navi~scope@#nav-scope$を見よ。 ◎ For example, {"scope": "/"} means that the manifest applies to every document in an origin. On the other hand, {"scope": "/racer/"} means that only documents within the path "/racer/" are within scope: so "/racer/race1.html", "/racer/race2.html", etc. would all be within scope, but "/elsewhere/" and anything at the root "/" would be "out of scope" and the manifest wouldn't apply to documents in those paths. Only one scope path is supported. See 6. Navigation scope for the technical details.
`~manifestを適用する$ことは、[ 当の~manifest内に見出された~memberのうち,呈示に影響するもの ]は,どれも効果を発揮することを意味する — “~fullscreen” 表示や,特定0の~screen方位を適用するなど。 ~appが`~scopeの中$にある~URLへ~navigateされる限り、 ~browserは当の~manifestを適用し続けることになる。 しかしながら,~web~appが “~scopeの外” へ~navigateされた場合、 当の~manifestは もはや適用されなくなり,~browserは自前の既定を適用することになる。 その結果,~appは、 例えば,~fullscreenでは もはや表示されず, ~browser~UItab内の定例の~web~pageとして表示されるようになる。 ~scopeの[ 内へ/外へ ]~navigateされている~web~pageをどう処するかは、 実装者の裁定に委ねられる。 技術的な詳細は、 `§ ~manifestの適用-法@#applying$を見よ。 ◎ Applying a manifest means that any members that affect presentation found in the manifest will come into effect, such as display "fullscreen", or applying a particular screen orientation. As long as the application is navigated to URLs that are within scope, the browser will continue to apply the manifest. However, navigating the web applications "out of scope" will cause the manifest to no longer be applied, and the browser will apply its own defaults. This will cause, for example, the application to no longer be displayed in fullscreen, and instead be displayed as a regular web page in a browser tab. It's left up to implementers to decide how to deal with web pages being navigated in and out of scope. See 1.17.5 Applying the manifest for the technical details.
最後に,利用者は[ ある生成元に属する どの文書からも,~web~appを~installできる場合もある ]ので、 ~manifest内に `scope$mM ~memberを常に宣言することは, 良い実施になる。 ~manifest に `scope$mM ~memberが欠落な場合、 `start_url$mM ~memberの~pathが~fallbackとして利用される。 それも欠落な場合、 当の~web~appが~installされた文書の~URLが, ~scopeとして利用される結果になる。 ~naviにおいて期待されない挙動が生じ得ないようにしたいなら、 常に, `scope$mM ~memberを含めた上で `/^l を設定するのが好ましい。 ◎ Finally, as it's possible that a user can install a web application from any document within an origin, it's good practice to always declare a scope member in a manifest. If the scope member is missing from the manifest, then the path of the start_url member is used as a fallback. And if the start_url member is also missing, then the document URL from which the web application is installed gets used as the scope. To be sure you don't get any unexpected navigation behavior, always include a scope member preferably set to "/".
1.2. `dir^m ~member
`~manifest$の `dir@mM ~memberは、 `~manifest$の`地域化-可能な~member$用の既定の文字列~方向を指定する。 この~memberの値は、 ある`~text方向$に設定できる。 ◎ The manifest's dir member specifies the default string direction for the localizable members of the manifest. The dir member's value can be set to a text-direction.
`地域化-可能な~member@ ( `localizable member^en )は: ◎ The localizable members are:
- `~manifest$の ⇒# `name$mM, `short_name$mM ◎ name member. short_name member.
- `~shortcut~item$の ⇒# `name$mH, `short_name$mH, `description$mH ◎ Shortcut item's name member. Shortcut item's short_name member. Shortcut item's description member.
`~text方向@ は、 次に挙げる値をとり得る。 それは、 `地域化-可能な~member$の値に対し,既定で含意される方向性を与える: ◎ The text-directions are the following, implying that the value of the localizable members is by default:
- `ltr@l ◎ ltr
- 左横書き~text。 ◎ Left-to-right text.
- `rtl@l ◎ rtl
- 右横書き~text。 ◎ Right-to-left text.
- `auto@l ◎ auto
- ~text方向は未知。 ~UAは、 ~textの表示を見積もるための経験則 — 例えば, `UAX9$r にて述べられる `first-strong^en ~algo† — を利用するべきである。 ◎ Text direction is unknown. The user agent should use heuristics to estimate the display of the text, for example the first-strong algorithm as described in [UAX9].
- 【† ~text方向は、 当の~textを成す最初の[ 強い方向性を伴う文字 ] — `双方向-文字~種別@~UTR/tr9/#Bidirectional_Character_Types$が `Strong^i に分類される文字 — により決定される (~HTMLの`文字列の方向性を算出する~algo@~HTMLdom#_compute-string-directionality$と同様に)。 】
`~text方向~list@ は、 次で与えられる`~list$である ⇒ « `ltr$l, `rtl$l, `auto$l » ◎ The text-direction list is the list « "ltr", "rtl", "auto" ».
`_dir~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest ) に対し: ◎ To process the dir member, given ordered map json and ordered map manifest:
- %~manifest[ `dir^l ] ~SET `auto^l ◎ Set manifest["dir"] to "auto".
- %dir ~LET %~JSON[ `dir^l ] ◎ ↓
- ~IF[ %dir は`文字列$でない ] ⇒ ~RET ◎ If json["dir"] doesn't exist or if json["dir"] is not a string, return.
- %dir ~SET `前後の~ASCII空白~列を剥ぐ$( %dir ) ◎ Strip leading and trailing ASCII whitespace from json["dir"].
- ~IF[ %dir ~NIN `~text方向~list$ ] ⇒ ~RET ◎ If text-direction list doesn't contain json["dir"], return.
- %~manifest[ `dir^l ] ~SET %dir ◎ Set manifest["dir"] to json["dir"].
1.3. `lang^m ~member
`~manifest$の `lang@mM ~memberは、 `文字列$の形をとる`言語~tag$であり,[ ~manifestの`地域化-可能な~member$ ]の値~用の言語を指定する。 `lang$mM ~memberが指定されなかった場合、 言語は未知であるものと扱われる。 ◎ The manifest's lang member is a string in the form of a language tag that specifies the language for the values of the manifest's localizable members. If the lang member is not specified, the language is treated as unknown.
注記: 言語を指定すれば、 ~UAが~accessibility用に最も適切な処理-法や資源 (~font, ~style付け, ~hyphen化, ~text発話~用の~voiceなど) を選定する助けになり,利用者~体験は改善される。 ◎ Note Specifying the language improves the user experience by helping user agents select the most appropriate processing or resources, such as fonts, styling, hyphenation, or text-to-speech voices for accessibility.
`言語~tag@ は、 `BCP47$r にて定義される[ 整形式な~tag【`参照@~RFCx/rfc5646#section-2.2.9$】用の `Language-Tag$P 生成規則 ]に合致する`文字列$である。 ◎ A language tag is a string that matches the production of a well-formed Language-Tag defined in [BCP47].
注記: 言語~tagは、 文字大小無視である。 言語~tagの例として,次が挙げられる ⇒# `fr^l (~French), `en-AU^l (~Australiaで話される~English), `zh-Hans-CN^l (簡体字~用字系で書かれ, ~Chinaで話される~Chinese)。 ◎ Note Language tags are case-insensitive. Examples of language tags include 'fr' (French), 'en-AU' (English as spoken in Australia), or 'zh-Hans-CN' (Chinese as written in the Simplified Han script as spoken in China).
`_lang~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest ) に対し: ◎ To process the lang member, given ordered map json and ordered map manifest:
- %lang ~LET %~JSON[ `lang^l ] ◎ ↓
- ~IF[ %lang は`文字列$でない ] ⇒ ~RET ◎ If json["lang"] doesn't exist or if json["lang"] is not a string, return.
- %lang ~SET `前後の~ASCII空白~列を剥ぐ$( %lang ) ◎ Strip leading and trailing ASCII whitespace from json["lang"].
- ~IF[ `IsStructurallyValidLanguageTag$jA( %lang ) の結果 ~EQ ~F ] ⇒ ~RET ◎ If calling IsStructurallyValidLanguageTag with json["lang"] returns false, return.
- %~manifest[ `lang^l ] ~SET `CanonicalizeUnicodeLocaleId$jA( %lang ) ◎ Set manifest["lang"] to the result of calling the CanonicalizeUnicodeLocaleId abstract operation with json["lang"].
1.4. `name^m ~member
`~manifest$の `name@mM ~memberは、[ 利用者~向けに通例的に表示される,~web~appの名前 ]を表現する`文字列$である (例:他の~appたちが成す~listの中での名前や,~icon用の~labelとして)。 ◎ The manifest's name member is a string that represents the name of the web application as it is usually displayed to the user (e.g., amongst a list of other applications, or as a label for an icon).
`name$mM ~memberは、 `~installした~web~app$の`~access可能な名前$として~serveする。 ◎ The name member serves as the accessible name of an installed web application.
注記: `name$mM ~memberは、 `~manifestを処理する$ときに,`~text~memberを処理する$~algoを利用して処理される。 ◎ Note: Processing the `name` member When processing a manifest, the process a text member algorithm is used to process the name member.
1.5. `short_name^m ~member
`~manifest$の `short_name@mM ~memberは、[ ~web~appの名前の短い~version ]を表現する`文字列$であり、 ~web~appの全部的な名前を表示するには空間が足らない所での利用が意図される。 ◎ The manifest's short_name member is a string that represents a short version of the name of the web application. It is intended to be used where there is insufficient space to display the full name of the web application.
注記: `short_name$mM ~memberは、 `~manifestを処理する$ときに,`~text~memberを処理する$~algoを利用して処理される。 ◎ Note: Processing the `short_name` member When processing a manifest, the process a text member algorithm is used to process the short_name member.
1.6. `scope^m ~member
`~manifest$の `scope@mM ~memberは、[ ~web~appの`~app文脈$における`~navi~scope$ ]を表現する`文字列$である。 ◎ The manifest's scope member is a string that represents the navigation scope of this web application's application context.
注記: “既定の~scope” ( `scope$mM ~memberは,欠落であるか 妥当な~URLでない【!empty, or failure】とき)は、 `開始~URL$から[ ~filename, ~query, 素片 ]を除去したものになる。 ◎ Note: Default scope The "default scope" (when scope member is missing, empty, or failure) is the start URL, but with its filename, query, and fragment removed.
`_scope~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest【, `~URL$ %~manifest~URL】 ) に対し: ◎ To process the scope member, given ordered map json and ordered map manifest:
- %~manifest[ `scope^l ] ~SET `~URL構文解析する$( `.^l, %~manifest[ `start_url^l ] ) ◎ Set manifest["scope"] to the result of parsing "." with manifest["start_url"] as the base URL.
- ~IF[ %~JSON[ `scope^l ] ~EQ 空~文字列 ] ⇒ ~RET ◎ If json["scope"] is the empty string, then return.
- %~scope ~LET `~URL構文解析する$( %~JSON[ `scope^l ], %~manifest~URL ) ◎ Let scope be the result of parsing json["scope"] with manifest URL as the base URL.
- ~IF[ %~scope ~EQ `失敗^i ] ⇒ ~RET ◎ If scope is failure, return.
- %~scope の ⇒# `~query$url ~SET ~NULL, `素片$url ~SET ~NULL ◎ Set scope's query and fragment to null.
- ~IF[ `~targetは~scopeの中にある$( %~manifest[ `start_url^l ], %~scope ) ~EQ ~F ] ⇒ ~RET ◎ If manifest["start_url"] is not within scope of scope, return.
- %~manifest[ `scope^l ] ~SET %~scope ◎ Otherwise, set manifest["scope"] to scope.
1.7. `icons^m ~member
`~manifest$の `icons@mM ~memberは、 様々な文脈において,~web~appの~icon的な表現として~serveし得る画像たちを与える。 例えば,次に利用できるような ⇒# 他の~appたちが成す~listの中で当の~web~appを表現する/ ~OSの~task切替器や~system選好に~web~appを統合する ◎ The manifest's icons member are images that serve as iconic representations of the web application in various contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS's task switcher and/or system preferences.
注記: `icons$mM ~memberは、 `~manifestを処理する$ときに,`画像~資源を処理する$~algoを利用して処理される。 ◎ Note When processing a manifest, the process image resources algorithm is used to process the icons member.
1.8. `display^m ~member
`~manifest$の `display@mM ~memberは、[ ~web~app用に開発者が選好する`表示~mode$ ]を与える。 ◎ The manifest's display member represents the developer's preferred display mode for the web application. Its value is a display mode.
`_display~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest ) に対し: ◎ To process the display member, given ordered map json and ordered map manifest:
- %~manifest[ `display^l ] ~SET `browser$l ◎ Set manifest["display"] to "browser".
- %display ~LET %~JSON[ `display^l ] ◎ ↓
- ~IF[ %display は`文字列$でない ] ⇒ ~RET ◎ If json["display"] doesn't exist or json["display"] is not a a string, return.
- %display ~SET `前後の~ASCII空白~列を剥ぐ$( %display ) ◎ Strip leading and trailing ASCII whitespace from json["display"].
- ~IF[ %display ~NIN `表示~mode~list$ ] ⇒ ~RET ◎ If display modes list doesn't contain json["display"], return.
- %~manifest[ `display^l ] ~SET %display ◎ Set manifest["display"] to json["display"].
1.9. `orientation^m ~member
`~manifest$の `orientation@mM ~memberは`文字列$であり、[ ~web~appを成す すべての`~top-level閲覧~文脈$用の`既定の~screen方位$ ]として~serveする。 アリな値は、 `OrientationLockType$I ~enumと同じであり,この仕様においては `方位~値@ と称される (すなわち: `any^l, `natural^l, `landscape^l, `portrait^l, `portrait-primary^l, `portrait-secondary^l, `landscape-primary^l, `landscape-secondary^l ) ◎ The manifest's orientation member is a string that serves as the default screen orientation for all top-level browsing contexts of the web application. The possible values are those of the OrientationLockType enum, which in this specification are referred to as the orientation values (i.e., "any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", or "landscape-secondary").
~UAは `orientation$mM ~memberの値を`既定の~screen方位$として~supportする場合、 それが,~web~app用の一生にわたる`既定の~screen方位$として~serveする (何らかの他の手段により稼働時に上書きされない限り)。 これは、 ~UAは,どの時点でも`既定の~screen方位$を指す方位を返す`モノトスル^EMことを意味する — 方位が~unlockされるか `SCREEN-ORIENTATION$r, `~top-level閲覧~文脈$が`~navigate$されない限り。 ◎ If the user agent supports the value of the orientation member as the default screen orientation, then that serves as the default screen orientation for the life of the web application (unless overridden by some other means at runtime). This means that the user agent MUST return the orientation to the default screen orientation any time the orientation is unlocked [SCREEN-ORIENTATION] or the top-level browsing context is navigated.
注記: この仕様は, `SCREEN-ORIENTATION$r の `OrientationLockType$I に依拠するが、 その仕様の~APIの実装は — もちろん,~supportすることは奨励されるが — ~UAにとって任意選択~である。 ◎ Note Although the specification relies on the [SCREEN-ORIENTATION]'s OrientationLockType, it is OPTIONAL for a user agent to implement the [SCREEN-ORIENTATION] API. Supporting the [SCREEN-ORIENTATION] API is, of course, encouraged.
[[ ~UI/~UX ]上の ある種の~~都合/ ~platform規約 ]により、 一部の[ ~screen方位, 表示~mode ]は `一緒に利用できない@ こともある。 どの[ ~screen方位, 表示~mode ]が一緒に利用できないかは、 実装者の裁量に委ねられる。 例えば,~UAによっては、 `browser$l `表示~mode$の間に~appの`既定の~screen方位$を変更しても, イミを成さないかもしれない。 ◎ Certain UI/UX concerns and/or platform conventions will mean that some screen orientations and cannot be used together. Which orientations and display modes cannot be used together is left to the discretion of implementers. For example, for some user agents, it might not make sense to change the default screen orientation of an application while in browser display mode.
注記: `~top-level閲覧~文脈$の方位は、 ~web~appが稼働している間も,他の手段 ( `SCREEN-ORIENTATION$r ~APIなど) により変更され得る。 ◎ Note Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [SCREEN-ORIENTATION] API).
`_orientation~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest ) に対し: ◎ To process the orientation member, given ordered map json and ordered map manifest:
- %orientation ~LET %~JSON[ `orientation^l ] ◎ ↓
- ~IF[ %orientation は`文字列$でない ] ⇒ ~RET ◎ If json["orientation"] doesn't exist or json["orientation"] is not a string, return.
- %orientation ~SET `前後の~ASCII空白~列を剥ぐ$( %orientation ) ◎ Strip leading and trailing ASCII whitespace from json["orientation"].
- ~IF[ %orientation は`方位~値$でない ] ⇒ ~RET ◎ If json["orientation"] doesn't contain any of the orientation values, return.
- %~manifest[ `orientation^l ] ~SET %orientation ◎ Set manifest["orientation"] to json["orientation"].
1.10. `start_url^m ~member
`~manifest$の `start_url@mM ~memberは、 `開始~URL@ を表現する`文字列$である。 それは、[ 利用者が~web~appを立上げたとき (例:利用者が機器の~app~menuや~homescreenから~web~appの~iconを~clickしたとき), ~UAが読込むもの ]として,開発者が選好する`~URL$である。 ◎ The manifest's start_url member is a string that represents the start URL , which is URL that the developer would prefer the user agent load when the user launches the web application (e.g., when the user clicks on the icon of the web application from a device's application menu or homescreen).
`start_url$mM ~memberは、 純粋に助言的である — ~UAは、 次をしても`ヨイ^EM: ◎ The start_url member is purely advisory, and\
- それを`無視する$ ◎ a user agent MAY ignore it or\
- それを用立てない~choiceを末端利用者に供する ◎ provide the end-user the choice not to make use of it.\
- 末端利用者が~URLを改変することを許容する — 一例として、 ~web~app用の~bookmarkが作成されたとき/それ以降のいつでも。 ◎ A user agent MAY also allow the end-user to modify the URL when, for instance, a bookmark for the web application is being created or any time thereafter.
`_start_url~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest, `~URL$ %~manifest~URL, `~URL$ %文書~URL ) に対し:
- %開始~URL ~LET %文書~URL
- %start_url ~LET %~JSON[ `start_url^l ]
-
~IF[ %start_url は`文字列$である ]~AND[ %start_url ~NEQ 空~文字列 ]:
- %~URL ~LET `~URL構文解析する$( %start_url, %~manifest~URL )
- ~IF[ %~URL ~NEQ `失敗^i ]~AND[ ( %~URL, %文書~URL ) は`同一-生成元$である ] ⇒ %開始~URL ~SET %~URL
- %~manifest[ `start_url^l ] ~SET %開始~URL
例えば, %start_url に `../start_point.html^l, %~manifest~URL に `https://example.com/resources/manifest.webmanifest^l が与えられた場合、 結果の %開始~URL は, `https://example.com/start_point.html^l になる。 ◎ Example 5 For example, if the value of start_url is ../start_point.html, and the manifest's URL is https://example.com/resources/manifest.webmanifest, then the result of parsing would be https://example.com/start_point.html.
1.10.1. ~privacyの考慮点: `start_url^mM による追跡
`start_url$mM は、[ ~appが~browserの外側から立上げられたこと ]を指示するよう,細工される~~可能性も~~考えられる (例: `"start_url": "index.html?launcher=homescreen"^c )。 これは、 解析~用に — 場合によっては他の~custom化にも — 有用になり得る。 しかしながら,その一方、 開発者が `start_url^mM の中に[ 利用者を一意に識別する文字列 ]を符号化する~~可能性も~~考えられる (例:~serverがアテガった識別子 — `?user=123^l, `/user/123/^l, `https://user123.foo.bar^l など)。 これは、 利用者が自覚しないであろう[ 指紋収集/~privacyに敏感な情報 ]になる。 ◎ It's conceivable that the start_url could be crafted to indicate that the application was launched from outside the browser (e.g., "start_url": "index.html?launcher=homescreen"). This can be useful for analytics and possibly other customizations. However, it is also conceivable that developers could encode strings into the start_url that uniquely identify the user (e.g., a server-assigned identifier, such as "?user=123", "/user/123/", or "https://user123.foo.bar"). This is fingerprinting/privacy sensitive information that the user might not be aware of.
注記: 開発者が`開始~URL$を[ 利用者を一意に識別する情報を含める ]ために利用することは、 不良な実施である — それは、 利用者が~site~dataを~clearしても~clearされない指紋を表現することになるので。 しかしながら、 この仕様には,開発者がこれを行うことを実用的に防止するものは何も無い。 ◎ Note: Don't add identifiers to start URLs It is bad practice for a developer to use the start URL to include information that uniquely identifies a user, as it would represent a fingerprint that is not cleared when the user clears site data. However, nothing in this specification can practically prevent developers from doing this.
よって,~UAには、 ~installして以降は,いつでも次を利用者に許容することが`推奨される^EM ⇒# ~appの`開始~URL$を検分すること, 必要yなら それを改変すること ◎ Given the above, it is RECOMMENDED that, upon installation, or any time thereafter, a user agent allows the user to inspect and, if necessary, modify the start URL of an application.
~UAは、 この指紋収集に抗する他の保護を提供してもヨイ。 例えば,利用者がある生成元からの~dataを~clearした場合には、 当の生成元~用の~manifestの`~navi~scopeの中$にある~appを~uninstallする — したがって,~appの`開始~URL$から潜在的な指紋を除去する — 【ような~option】を提供するなど。 ◎ A user agent MAY offer other protections against this form of fingerprinting. For example, if a user clears data from an origin, the user agent MAY offer to uninstall applications that are within scope of that origin, thus removing the potential fingerprint from the application's start URL.
1.11. `id^c ~member
`~manifest$の `id@mM ~memberは、 当の~app用の `識別情報@ ( `identity^en )を表現する`文字列$である。 `識別情報$は、 ~URLの形をとり,`開始~URL$と同一-生成元に属する。 ◎ The manifest's id member is a string that represents the identity for the application. The identity takes the form of a URL, which is same origin as the start URL.
~UAは、 `識別情報$を利用して,~appを普遍的かつ一意に識別する。 ~UAは、 自身が出くわした ある`~manifest$ %~manifest が ◎ The identity is used by user agents to uniquely identify the application universally.\
- すでに~install済みな~appに対応しない`識別情報$を伴う場合、 %~manifest が別の~appと同じ~URLから~serveされていようが, %~manifest を それらとは別個な~appの記述として扱う`ベキ^emである。 ◎ When the user agent sees a manifest with an identity that does not correspond to an already-installed application, it SHOULD treat that manifest as a description of a distinct application, even if it is served from the same URL as that of another application.\
- %~manifest[ `id^l ] が, すでに~install済みな~appの`識別情報$と (任意選択で, `素片を除外する^i下で) `同等な~URL$である場合、 次が通達されたものとして, %~manifest を利用する`ベキ^emである ⇒ %~manifest は, すでに~install済みな~appの~manifest用の置換であり、 以前とは異なる~URLから~serveされていようが,別個な~appではない ◎ When the user agent sees a manifest where manifest["id"] is equal (with exclude fragments OPTIONALLY set to true) to the identity of an already-installed application, it SHOULD be used as a signal that this manifest is a replacement for the already-installed application's manifest, and not a distinct application, even if it is served from a different URL than the one seen previously.
注記: `id$mM ~memberの`素片$urlは,`_id~memberを処理する$pMときに除去されるので、 どの~appに合致するか検査するときには, `素片は除外する^i 下で比較することは厳密には必要yでない。 しかしながら,この仕様の旧い~version(および,場合によっては旧い~UA)は、 構文解析-時点で`~URL$から`素片$urlを除去する代わりに, `素片は除外する^i 下で比較することにしか依拠していなかったので、 歴史的な【~UAに格納-済みな】~app~dataは, `id$mM 内に`素片$urlを包含することもある。 したがって,~UAは、 素片を有するべきでない 2 個の`~URL$を比較するときでも, `素片は除外する^i 下で比較することが最善な実施になる。 ◎ Note: Excluding fragments is best practice Since the processing algorithm removes the fragment from the id member, it is not strictly necessary to exclude fragments when checking for a matching application. However, since old versions of this spec (and, possibly, old user agents) did not remove the fragment from the URL at parse time, and relied only on excluding fragments during comparisons, historical app data could contain fragments in the id. Therefore, it is best practice for user agents to exclude fragments even when comparing two URLs that ought not to have fragments.
注記: `識別情報$は、 ~web~appたちが成す~listを収集する~serviceにより, 各~appを一意に識別するために利用され得る。 ◎ Note The identity can be used by a service that collects lists of web applications to uniquely identify applications.
注記: `識別情報$は、 ~URLと同じ様に処理されるが、 ~navigateできる資源を指すわけではないので, `~scopeの中$にあることは要求されない。 ◎ Note The identity is processed like a URL but it doesn't point to a resource that can be navigated to, so it's not required to be within scope.
`_id~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest ) に対し: ◎ To process the id member, given ordered map json, ordered map manifest:
- %~manifest[ `id^l ] ~SET %~manifest[ `start_url^l ] ◎ Set manifest["id"] to manifest["start_url"].
- ~IF[ %~JSON[ `id^l ] は`文字列$でない ] ⇒ ~RET ◎ If the type of json["id"] is not string, return.
- ~IF[ %~JSON[ `id^l ] ~EQ 空~文字列 ] ⇒ ~RET ◎ If json["id"] is the empty string, return.
- %基底~生成元 ~LET %~manifest[ `start_url^l ] の`生成元$url ◎ Let base origin be manifest["start_url"]'s origin.
- %~ID ~LET `~URL構文解析する$( %~JSON[ `id^l ], %基底~生成元 ) ◎ Let id be the result of parsing json["id"] with base origin as the base URL.
- ~IF[ %~ID ~EQ `失敗^i ] ⇒ ~RET ◎ If id is failure, return.
- ~IF[ ( %~ID, %~manifest[ `start_url^l ] ) は`同一-生成元$でない ] ⇒ ~RET ◎ If id is not same origin as manifest["start_url"], return.
- %~ID の`素片$url ~SET ~NULL ◎ Set id's fragment to null.
- %~manifest[ `id^l ] ~SET %~ID ◎ Set manifest["id"] to id.
下の表tに, `_id~memberを処理する$pM手続きによる結果の `id^c の例を示す: ◎ Example 6: Resulting ids The table below shows some example ids resulting from the process the id member steps.
%~JSON[ `id^l ] (入力) | %~manifest[ `start_url^l ] (基底) | %~manifest[ `id^l ] (結果) |
---|---|---|
ε【!undefined】 | `https://example.com/my-app/start^l | `https://example.com/my-app/start^l |
ε【!undefined】 | `https://example.com/my-app/#here^l | `https://example.com/my-app/^l |
空~文字列 | `https://example.com/my-app/start^l | `https://example.com/my-app/start^l |
`/^l | `https://example.com/my-app/start^l | `https://example.com/^l |
`foo^l | `https://example.com/my-app/start^l | `https://example.com/foo^l |
`foo?x=y^l | `https://example.com/my-app/start^l | `https://example.com/foo?x=y^l |
`foo#heading^l | `https://example.com/my-app/start^l | `https://example.com/foo^l |
`./foo^l | `https://example.com/my-app/start^l | `https://example.com/foo^l |
`https://example.com/foo^l | `https://example.com/my-app/start^l | `https://example.com/foo^l |
`https://anothersite.com/foo^l | `https://example.com/my-app/start^l | `https://example.com/my-app/start^l |
`😀^l | `https://example.com/my-app/start^l | `https://example.com/%F0%9F%98%80^l |
`id$mM は `start_url$mM の`生成元$urlを基準に解決されるので、[ `../foo^l, `foo^l, `/foo^l, `./foo^l ]どれを供しても,同じ識別子に解決される。 そのようなわけで、 `id^c が根に相対的な~URL~pathになるよう, 明示的に先頭に `/^l を利用することが最善な実施になる。 また, `id^c を処理する~algoには、 `~URL標準^cite `URL$r による[ 符号化する/復号する ]ための標準な規則が適用される。 ◎ Since id is resolved against start_url's origin, providing "../foo", "foo", "/foo", "./foo" all resolves to the same identifier. As such, best practice is to use a leading "/" to be explicit that the id is a root-relative URL path. Also, standard encoding/decoding rules apply to the id processing algorithm, as per the URL Standard.
1.12. `theme_color^m ~member
`~manifest$の `theme_color@mM ~memberは、 ~app文脈~用の `既定の~theme色@ として~serveする。 何が `~theme色@ を成すかは、 `HTML$r に定義される。 ◎ The manifest's theme_color member serves as the default theme color for an application context. What constitutes a theme color is defined in [HTML].
~UAが, `theme_color^c ~memberの値を`既定の~theme色$として尊守する場合、 当の~manifestが`適用-$されるどの閲覧~文脈においても, その色が`~theme色$として~serveする。 しかしながら,文書が[ `name$a 属性の値が `theme-color$v にされた妥当な `meta$e 要素 `HTML$r ]を含む場合、 `既定の~theme色$は上書きされ得る。 ◎ If the user agent honors the value of the theme_color member as the default theme color, then that color serves as the theme color for all browsing contexts to which the manifest is applied. However, a document may override the default theme color through the inclusion of a valid [HTML] meta element whose name attribute value is "theme-color".
~UAは、 文脈に基づいて`~theme色$の`~alpha成分$を無視しても`ヨイ^EM — 例えば、 ほとんどの環境においては,`~theme色$は透明になり得ない。 ◎ The user agent MAY ignore the theme color's alpha component based on the context. For example, in most environments, the theme color cannot be transparent.
実装者は、 `prefers-color-scheme$d を~supportするためとして, `theme_color$mM ~memberに定義された値を上書きしても`ヨイ^EM。 ◎ Implementors MAY override the value defined by the theme_color member to support prefers-color-scheme.
注記: `theme_color$mM ~memberは、 `~manifestを処理する$ときに,`色~memberを処理する$~algoを利用して処理される。 ◎ Note When processing a manifest, the process a color member algorithm is used to process the theme_color member.
1.15. `background_color^m ~member
`~manifest$の `background_color@mM ~memberは、[ ~web~appが期待する背景~色 ]を述べる。 それは,当の~appの~stylesheet内で すでに可用であるものを繰返すが、 ~UAは,[ ~networkから~fetchされるか~diskから検索取得されるかを問わず、 ~fileが実際に可用になる前に,~manifestが既知であるとき ]に~web~appの背景~色を描くために利用できる。 ◎ The manifest's background_color member describes the expected background color of the web application. It repeats what is already available in the application stylesheet but can be used by the user agent to draw the background color of a web application for which the manifest is known before the files are actually available, whether they are fetched from the network or retrieved from disk.
`background_color$mM ~memberが意味されるのは、 ~web~appを読込んでいる間,利用者~体験を改善するために限られる — ~UAは、 ~web~appの~stylesheetが可用なときは, 背景~色として利用しない`モノトスル^EM。 ◎ The background_color member is only meant to improve the user experience while a web application is loading and MUST NOT be used by the user agent as the background color when the web application's stylesheet is available.
実装者は、 `prefers-color-scheme$d を~supportするためとして, `background_color$mM ~memberに定義された値を上書きしても`ヨイ^EM。 ◎ Implementors MAY override the value defined by the background_color member to support prefers-color-scheme.
注記: `background_color$mM ~memberは、 `~manifestを処理する$ときに,`色~memberを処理する$~algoを利用して処理される。 ◎ Note When processing a manifest, the process a color member algorithm is used to process background_color member.
1.16. `shortcuts^mM ~member
`~manifest$の `shortcuts@mM ~memberは、 `~shortcut~item$たちが成す`~list$であり、 ~web~appの中で主要taskへの~accessを供する。 ◎ The manifest's shortcuts member is an list of shortcut items that provide access to key tasks within a web application.
注記: ~shortcutは、 一例として — ~social~media~appの中での/電子商取引の文脈における近過去の注文への — 利用者の時列線へ直に~linkするためにも利用できる。 ◎ Note Shortcuts could, for instance, be used to link directly to a user's timeline within a social media application or to their recent orders in an e-commerce context.
注記: 開発者には、 それらの~shortcutを — 最も~criticalな~shortcutが~list内で最初に現れるよう — 優先度順にすることが奨励される。 ◎ Developers are encouraged to order their shortcuts by priority, with the most critical shortcuts appearing first in the list.
注記: ~shortcutが どう呈示され,どれだけ多くが利用者に示されるかは、[ ~UA/~OS ]の裁量に委ねられる。 ◎ How shortcuts are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system.
`_shortcuts~memberを処理する@pM ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~manifest【!不要, `~URL$ %~manifest~URL】 ) に対し: ◎ To process the shortcuts member, given ordered map json, ordered map manifest, and URL manifest URL:
- %処理-済み~shortcut~list ~LET 新たな`~list$ ◎ Let processedShortcuts be a new list.
- %~manifest[ `shortcuts^l ] ~SET %処理-済み~shortcut~list ◎ Set manifest["shortcuts"] to processedShortcuts.
- %shortcuts ~LET %~JSON[ `shortcuts^l ] ◎ ↓
- ~IF[ %shortcuts は`~list$でない ] ⇒ ~RET ◎ If json["shortcuts"] doesn't exist or json["shortcuts"] is not a list, return.
-
%shortcuts を成す ~EACH( %~entry ) に対し: ◎ For each entry of json["shortcuts"]:
- %~shortcut ~LET `~shortcutを処理する$( %~entry, %~manifest[ `scope^l ] ) ◎ Let shortcut be process a shortcut with entry and manifest["scope"].
- ~IF[ %~shortcut ~EQ `失敗^i ] ⇒ ~CONTINUE ◎ If shortcut is failure, continue.
- %処理-済み~shortcut~list に %~shortcut を`付加する$ ◎ Append shortcut to processedShortcuts.
~UAは、 ~shortcutたちを: ◎ ↓
- [ ~host~OSにおける~app~iconの文脈~menuの公開 ]と一貫したヤリトリを介して,公開する`ベキ^EMである (例:右~click, 長押し)。 ◎ A user agent SHOULD expose shortcuts via interactions that are consistent with exposure of an application icon's context menu in the host operating system (e.g., right click, long press).\
- ~manifestに供された順序で,具現化する`ベキ^EMである。 ◎ A user agent SHOULD render the shortcuts in the same order as they are provided in the manifest.\
- [ ~host~OSにおける~app~iconの文脈~menuの公開 ]と一貫した方式で,表現する`ベキ^EMである。 ◎ A user agent SHOULD represent the shortcuts in a manner consistent with exposure of an application icon's context menu in the host operating system.\
~UAは、 ~host~OSの[ 規約や制限 ]と一貫させるために必要なら, 呈示される~shortcutたちが成す~listを切落しても`ヨイ^EM。 ◎ A user agent MAY truncate the list of shortcuts presented in order to remain consistent with the conventions or limitations of the host operating system.
1.17. ~manifestの~life-cycle
この節では、[ `~manifestを処理する$/`~manifestを適用する$ ]ための~algoを定義する。 ◎ This section defines algorithms for processing a manifest, and applying a manifest.
~UAは~link型 `manifest$v, および それに結付けられた[ ~linkされた資源を~fetchして処理する方法を成す手続き ]を~supportするモノトスル。 ◎ A user agent MUST support the link type "manifest" and the associated steps for how to fetch and process the linked resource.
1.17.1. ~manifestの処理
`無視する@ ものとされる所では、 ~UAは,その条件を生じさせた[ ~manifest/~member/値 ]が何であれ,それが無かったかのように動作する`モノトスル^EM。 ◎ When instructed to ignore, the user agent MUST act as if whatever manifest, member, or value caused the condition is absent.
次の~algo【および他の一部の~algo】は、 `処理~拡張~地点@ を供する。 ~manifestに新たな~memberを追加する他の仕様は、 当の~algo内の,その地点に~hookすることが奨励される — ~manifest~obj( %~manifest )内にある既存の値を改変する`ベキ^EMではない。 ◎ The following algorithm provides an processing extension-point: other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm. They SHOULD NOT modify the existing values already in the manifest object.
注記: `処理~拡張~地点$は、 `~monkey~patch$することに関係する課題を避け易くすることが意味されている。 ◎ Note The processing extension-point is meant to help avoid issues related to monkey patching.
`~manifestを処理する@ ときは、所与の ( `~URL$ %文書~URL, `~URL$ %~manifest~URL, `~byte列$ %本体~byte列 ) に対し,次の手続きを走らす: ◎ The steps for processing a manifest are given by the following algorithm. The algorithm takes a URL document URL, a URL manifest URL, and a byte sequence bodyBytes.
- %~JSON ~LET `~JSON~byte列を~Infra値に構文解析する$( %本体~byte列 ) — 例外が投出されたときは、 ~catchして ⇒ %~JSON ~SET ε ◎ Let json be the result of parse JSON bytes to an Infra value passing bodyBytes. ◎ If the json is a parsing exception,\
- ~IF[ %~JSON は`有順序~map$でない ] ⇒ %~JSON ~SET 新たな`有順序~map$ ◎ or json is not an ordered map: • Set json to an empty ordered map.
- %~manifest ~LET 新たな`有順序~map$ ◎ Let manifest be an empty ordered map.
- `_dir~memberを処理する$pM( %~JSON, %~manifest ) ◎ Process the dir member passing json and manifest.
- `_lang~memberを処理する$pM( %~JSON, %~manifest ) ◎ Process the lang member passing json and manifest.
- `~text~memberを処理する$( %~JSON, %~manifest, `name^l ) ◎ Process a text member passing json, manifest, and "name".
- `~text~memberを処理する$( %~JSON, %~manifest, `short_name^l ) ◎ Process a text member passing json, manifest, and "short_name".
- `_start_url~memberを処理する$pM( %~JSON, %~manifest, %~manifest~URL, %文書~URL ) ◎ Process the start_url member passing json, manifest, manifest URL, and document URL.
- `_id~memberを処理する$pM( %~JSON, %~manifest ) ◎ Process the id member passing json and manifest.
-
%文書 ~LET 当の`文書$
【 %文書 は、 原文では `the document^en としか記されていない。 それは,通例的には %文書~URL を供したそれを指すが (すなわち, %文書~URL ~EQ %文書 の`~URL$doc )、 この時点では,~instance化されてない場合もあり得る ( %文書 は未来に~instance化される`文書$を指すことになる) — `§ 文書を伴わない~manifestの処理-法@#processing-the-manifest-without-a-document$を見よ。 】
◎ ↓ - ~IF[ %文書 の`処理-済み~manifest$ ~NEQ ~NULL ]~AND[ ( %文書 の`処理-済み~manifest$[ `id^l ], %~manifest[ `id^l ] ) は、 `同等な~URL$でない ] ⇒ ~RET ◎ If the document's processed manifest is not null, and document's processed manifest's id is not equal to manifest["id"], return.
- `_scope~memberを処理する$pM( %~JSON, %~manifest, %~manifest~URL ) ◎ Process the scope member passing json, manifest, and manifest URL.
- `色~memberを処理する$( %~JSON, %~manifest, `theme_color^l ) ◎ Process a color member passing json, manifest, and "theme_color".
- `色~memberを処理する$( %~JSON, %~manifest, `background_color^l ) ◎ Process a color member passing json, manifest, and "background_color".
- `_display~memberを処理する$pM( %~JSON, %~manifest ) ◎ Process the display member passing json and manifest.
- `画像~資源を処理する$( %~JSON[ `icons^l ] , %~manifest, %~manifest~URL, `icons^l ) ◎ Process image resources passing json["icons"], manifest, manifest URL, and "icons".
- `_orientation~memberを処理する$pM( %~JSON, %~manifest ) ◎ Process the orientation member passing json, manifest.
- `_related_applications~memberを処理する$pM( %~JSON, %~manifest ) ◎ Process the related_applications member passing json and manifest.
- `_shortcuts~memberを処理する$pM( %~JSON, %~manifest【!不要, %~manifest~URL】 ) ◎ Process the shortcuts member passing json, manifest, and manifest URL.
- `処理~拡張~地点$ ⇒ [ ~proprietaryな~member/他の~supportする~member ]が在れば、 この地点で処理する ◎ Processing extension-point: process any proprietary and/or other supported members at this point in the algorithm.
- %文書 の `処理-済み~manifest@ 【!~LET】~SET %~manifest ◎ Let document's processed manifest be manifest.
1.17.2. 色~memberの処理
注記: ~supportされる色は、[ `~sRGB$に属する色/ ~UAが~~外部~知識なしに~sRGBに変換できる色 (例:`有名~色$【!aliceblue】 ) ]に限られる。 例えば、[ `lab(…)^v / `color(display-p3, …)^v ]は,~~外部~知識なしに~sRGBに変換できるが、 `color(--custom-profile, …)^v は, `--custom-profile^v に合致している `color-profile$at 規則を見出すことが要求され, それは~manifest内には指定し得ないので変換できない。 ◎ Note: Supported colors Only sRGB colors, and colors the user agent can convert to sRGB without any outside knowledge (e.g., "AliceBlue"), are supported. For example, lab(…) or color(display-p3, …) can be converted to sRGB without outside knowledge, but color(--custom-profile, …) would require finding a matching "@color-profile" rule which cannot be specified in the manifest.
`色~memberを処理する@ ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~map, `文字列$ %~member ) に対し: ◎ To process a color member, using ordered map json, ordered map map, and string member:
- %色~member ~LET %~JSON[ %~member ] ◎ ↓
- ~IF[ %色~member は`文字列$でない ] ⇒ ~RET ◎ If json[member] doesn't exist or json[member] is not a string, return.
- %色~member ~SET `前後の~ASCII空白~列を剥ぐ$( %色~member ) ◎ Strip leading and trailing ASCII whitespace from json[member].
- %色 ~LET `~CSS文法に則って構文解析する$( %色~member, `color$t ) ◎ Let color be the result of parsing the value of json[member] as a CSS color.
- ~IF[ %色 ~EQ `失敗^i ] ⇒ ~RET ◎ If color is failure, return.
- ~IF[ ~UAは 内来的に知る情報のみを利用して %色 を`~sRGB$に変換できる ] ⇒ %~map[ %~member ] ~SET %色 を~sRGBへ変換した結果 ◎ If color can be converted to sRGB using solely information the user agent inherently knows, then convert color to sRGB. ◎ If color is not sRGB color, return. ◎ Set map[member] to color.
1.17.3. ~text~memberの処理
`~text~memberを処理する@ ときは、所与の ( `有順序~map$ %~JSON, `有順序~map$ %~map, `文字列$ %~member ) に対し: ◎ To process a text member, given ordered map json, ordered map map, and string member:
- %~text~member ~LET %~JSON[ %~member ] ◎ ↓
- ~IF[ %~text~member は`文字列$である ] ⇒ %~map[ %~member ] ~SET `前後の~ASCII空白~列を剥ぐ$( %~text~member ) ◎ If json[member] doesn't exists or json[member] is not a string, return. ◎ Strip leading and trailing ASCII whitespace from json[member]. ◎ Set map[member] to the value of json[member].
1.17.4. 文書を伴わない~manifestの処理-法
`~manifestを処理する$手続きは, `HTML$r における `link$e 要素~用の処理~手続き【 § `manifest$v を見よ】から呼出されるが、 ~UAは,`文書$を伴わない~manifestを処理するために呼出しても`ヨイ^EM。 ◎ The processing a manifest steps are invoked by [HTML]'s processing steps for the link element, but MAY also be invoked by the user agent to process a manifest without an associated document.
この事例では、 `HTML$r 内の対応する手続きにより為される保証に合致するためには,~UAは — 少なくとも,過去の ある時点で — 次を確保する`ベキ^EMである: ◎ In this case, to match the guarantees made by the corresponding steps in [HTML], the user agent SHOULD ensure that at least at some point in the past:
- 次を満たす`文書$が,少なくとも 1 つ以上は在った ⇒ [ %文書~URL と`同一-生成元$に属する ]~AND[ 次を満たす `link$e 要素を有する ] ⇒ [ `rel$a 属性を有していて, その値は `manifest$v【!`~app~manifest$】 を与えている ]~AND[ `href$a 有していて, その値は %~manifest~URL に解決される ] ◎ there was at least one document that is same origin as document URL that has a link element linkElement with a rel of manifest and a href that resolves to manifest URL, and that
- ( %~manifest~URL, %文書~URL ) は`同一-生成元$でない場合、 %本体~byte列 を成す~dataは, 次を満たす`~CORS要請$で`~fetch$された ⇒ [ その `Origin$h ~headerは、 %文書~URL の`生成元$urlを値にとる ]~AND[ その`資格証~mode$rq ~EQ [ 前項の `link$e 要素の `crossorigin$a 属性 ]用の`~CORS設定群~属性の資格証~mode$ ] ◎ if manifest URL is not same origin as document URL, the bodyBytes data was fetched with a CORS Request whose Origin is document URL's origin, and whose credentials mode is set to the CORS settings attribute credentials mode for linkElement's crossorigin attribute.
注記(これらの検査の根拠): この規程は、[ 当の~manifest %~manifest へ~linkしている文書を最初に読込むことなく、 %~manifest を利用して,~appの~installationを遂行する ]ことを~UAに許容するが (例:ある同期c~serviceを介して,利用者の機器に~app~installするとき)、 上で推奨した検査は,~UAに対し次を検証yするよう依頼する ⇒ ある~appが生成元 %A を~scopeに入れていて, %~manifest が属する生成元 %B は %A と異なるとき、 %A, %B の間に双方向な関係性がある。 ◎ Note: The rationale for these checks This provision allows user agents to perform app installations using a manifest without having to first load a document that links to the manifest (e.g. when installing an app onto the user's device via a sync service). But the above recommendations ask the user agent to verify that, when an application scope is on origin A and the manifest is on a different origin B, there is a bidirectional relationship between the two origins.
1 個目の検査は、 次を確保する ⇒ 少なくとも、 %A に属する何らかの~pageが, %~manifest へ~linkしている (さもなければ、 %~manifest が[ %A に属する未提携な~app用の~metadata ]を制御することがアリになろう)。 ◎ The first check ensures that at least some page on origin A links to the manifest on origin B\ (otherwise, it would be possible for a manifest on origin B to control the metadata for an unaffiliated app on origin A).
2 個目の検査は、 次を確保する: ◎ The second check ensures that\
- %B は[ %~manifest が %A により適用される ]ことを(`~CORS~protocol$を介して)許容する。 ◎ origin B allows (via the CORS protocol) its manifest to be applied by origin A,\
- %~manifest は、 %A, %B 両~生成元により合意されるとおり,資格証を[ 伴って/伴わずに ]~fetchされる — 文書を通して直に行う場合と同じく。 ◎ and also that the manifest is fetched with or without credentials, as agreed by both origins, as it would if going directly through the document.
1.17.5. ~manifestの適用-法
`処理-済み~manifest$は、 `~top-level閲覧~文脈$に `適用-@ される。 それは、 `処理-済み~manifest$を成す~memberたちが,閲覧~文脈の呈示や挙動に影響することを意味する。 ◎ A processed manifest is applied to a top-level browsing context, meaning that the members of the processed manifest are affecting the presentation or behavior of a browsing context.
`~top-level閲覧~文脈$のうち,ある`~manifest$が適用されているものは、 `~app文脈@ と称される。 ◎ A top-level browsing context that has a manifest applied to it is referred to as an application context.
`~app文脈$ %~app を作成したときは、 ~UAは,即時に次を走らす`モノトスル^EM:
- %~URL ~LET [ `深い~link$へ`~navigate$するよう依頼された場合は それ / ~ELSE_ `開始~URL$ ]
- %~app を %~URL へ`~navigate$する — 次を与える下で ⇒ `履歴~取扱い$i ~SET `replace$hH
注記: `開始~URL$は、 `start_url$mM ~memberの値になるとは限らない — 利用者/~UAは、 ~appが`~install$されたとき,開始~URLを変更し得るので。 ◎ Note The start URL is not necessarily the value of the start_url member: the user or user agent could have changed it when the application was installed.
~manifestを`適用-$する適切な時機は、 `~app文脈$を作成した後, かつ`開始~URL$への`~navi$が始まる前とする。 ◎ The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.
1.17.6. ~manifestの更新-法
`~manifest$は、 `manifest$v ~link関係~用に指定されるとおり, 読込まれる~pageごとに~fetchされ処理される。 ~UAは,成功裡に`~manifestを処理-$したときは、 更新された~manifestを[ 当の~appに結付けられた — 現在の, または未来の — `~app文脈$ ]に適用してもヨイ。 ◎ As specified for manifest link relation, the manifest is fetched and processed on every page load. When the processing a manifest is successful, user agents MAY apply updated manifest to any current and future application contexts associated with the application.
更新する目的においては、 次に挙げる~memberは, `~securityに敏感な~member@ とされる — それらは、[ ~installationの間に立上n用~UI ]に呈示されるので ⇒# `short_name$mM, `icons$mM, `name$mM ◎ For the purpose of updating, the following member are security-sensitive members, as they are presented during installation and on launch surfaces: • short_name, • icons • name,
~UAは、 `~securityに敏感な~member$に対する変更を: ◎ ↓
- 利用者が`許可を表出する$ことを経ずに,自動的に適用するベキでない。 ◎ User agents SHOULD NOT automatically apply changes to security-sensitive members without express permission from the user.
- 代わりに,適切な管理~optionと伴に呈示するベキである — 当の~web~appを更新することについて,利用者が情報を得た上で裁定を下せるよう。 ◎ Instead, user agents SHOULD present changes to security-sensitive members with appropriate management options, so the user can make an informed decision about updating the web application.
~UAは、 当の更新が`~securityに敏感な~member$に対する変更を包含しない場合には, 当の変更を自動的に適用してもヨイ。 ◎ The user agent MAY automatically apply the changes if the update does not contain changes to security-sensitive members.
注記: 当の更新が[ `~securityに敏感な~member$, 他の~member ]どちらに対する変更も包含するときは、 ~UAは,自動的に[ 部分的に更新する ]ことはないことになる。 例えば、 ~UAは,利用者に次の~optionを呈示することもできる ⇒# 当の更新を受容する/ 当の~web~appを~uninstallする ◎ Note: A user agent will not apply a partial update When the update contains changes both to security-sensitive members and other members, a user agent won't automatically partially update. For example, the user agent could present options to the user: • Accept the update • Uninstall the web app
2. ~manifest画像~資源
各 `~manifest画像~資源@ は、 概念的には,~web~appの一部を成す画像~資源 — この~objを利用している~memberの意味論に依存して,様々な文脈で利用するのに相応しいそれ — を与える (例:~app~menuの一部を成す~icon, 等々)。 ◎ Each manifest image resource is an image resource that is conceptually part of a web application, suitable to use in various contexts depending on the semantics of the member that is using the object (e.g., an icon that is part of an application menu, etc.).
`~manifest画像~資源$は、 追加的な `purpose$mI ~memberを有し得る~~点で`画像~資源$から相違する。 ◎ A manifest image resource differs from a image resource in that it can have an additional purpose member.
~UAは、 `~manifest画像~資源$に結付けられた画像を,利用者に表示する前に改変しても`ヨイ^EM — ~platformの視覚的な~styleにより良く合致するよう、 例えば、[ 隅を丸める/特定の色で塗る ]ことにより。 色の変更や隅が切取られるなどにより,重要な情報が失われるのを避けるため、 開発者には,画像~資源をそのような局面~用に準備することが推奨される。 ◎ User agents MAY modify the images associated with an manifest image resource to better match the platform’s visual style before displaying it to the user, for example by rounding the corners or painting it in a specific color. It is recommended that developers prepare their image resources for such scenarios to avoid losing important information through, e.g., change of color or clipped corners.
2.1. `purpose^mI ~member
`purpose@mI ~memberは、 `~space等で分離された~token集合$(一意)である。 許容される値は,いずれかの`~icon目的$である。 ◎ The purpose member is an unordered set of unique space-separated tokens. The allowed values are the icon purposes.
`~manifest画像~資源$が,ある `~icon@ として利用される所では、 開発者は,[ 画像は、 ~host~OSの文脈~内で何らかの特別な目的を~serveするため (すなわち,~web~appをより良く~OSに統合するため) に意図される ]ことを~hintできる。 ~UAは、 ~iconを[ この~memberにて言明された`~icon目的$ ]以外に利用する`ベキ^EMでない。 ◎ When a manifest image resource is used as an icon, a developer can hint that the image is intended to serve some special purpose in the context of the host OS (i.e., for better integration). User agents SHOULD NOT use an icon other than for its stated icon purpose.
注記: 例えば,目的 `monochrome$l を伴う~iconは、 ~appの全彩色な立上n~iconとは視覚的に別個な,~solid-fillを伴う[ ~badge/~pinned ]~iconとして利用することもできる。 ~UAは、[ ~icon画像【!an `purpose$mI 】をどこにどう表示するか決定するための~hint ]として `purpose$mI ~memberの値を利用する。 開発者により他が宣言されない限り、 ~UAは,~iconを どの目的にも( `any$l 目的に)利用できる。 ◎ Note For example, an icon with purpose "monochrome" could be used as a badge or pinned icon with a solid fill, visually distinct from an application's full color launch icon. The user agent uses the value of the purpose member as a hint to determine where and how an purpose is displayed. Unless declared otherwise by the developer, a user agent can use an icon for any purpose.
`~icon目的@ には、 次に挙げるものがある: ◎ The icon purposes are as follows:
- `monochrome@l (単彩色) ◎ monochrome
- ~UAは、 この~iconを`~solid-fillを伴う単彩色~icon@#monochrome-icons-and-solid-fills$が必要な所で呈示できる。 ~icon内の色~情報は破棄され、 ~alpha~dataのみが利用される。 ~UAは、 この~iconを~solid-fill用の~maskなどに利用できる。 ◎ A user agent can present this icon where a monochrome icon with a solid fill is needed. The color information in the icon is discarded and only the alpha data is used. The icon can then be used by the user agent like a mask over any solid fill.
- `maskable@l (~mask可能) ◎ maskable
- 画像は、 `~icon~mask/安全~zone@#icon-masks$を伴うことを念頭に設計されている — すなわち、 画像を成す`安全~zone$の外側にあるどの部分も, ~UAは安全に[ 無視できる/~maskして消せる ]。 ◎ The image is designed with icon masks and safe zone in mind, such that any part of the image that is outside the safe zone can safely be ignored and masked away by the user agent.
- `any@l (任意)(既定) ◎ any (default)
- ~UAは、 他の`~icon目的$【!`purpose$mI】が要求されない所であれば, 当の~iconをどこで表示してもかまわない。 例えば,この`~icon目的$を伴う`~manifest画像~資源$は、 `monochrome$l が要求される文脈においては,利用されなくなる。 ◎ The user agent is free to display the icon where no purpose is required. For example, a manifest image resource with a "any" purpose wouldn't be used in a context where "monochrome" is required.
`~icon目的~list@ は、 次で与えられる`~list$である ⇒ « `monochrome$l, `maskable$l, `any$l » ◎ The icon purposes list is the list « "monochrome", "maskable", "any" ».
注記: ~iconが複数の目的を包含する場合、 どの目的にも利用できる。 言明されたどの目的も認識されない場合、 ~iconは,まるごと無視される。 例えば、 ~icon目的が `monochrome fizzbuzz^l ならば, `monochrome$l が妥当な目的なので単彩色~iconとして利用することもできるが、 目的が `fizzbuzz^l だけならば, ~iconは無視されることになる。 ◎ Note If an icon contains multiple purposes, it could be used for any of those purposes. If none of the stated purposes are recognized, the icon is totally ignored. For example, if an icon has purpose "monochrome fizzbuzz", then it could be used as a monochrome icon, as "monochrome" is a valid purpose. However, if an icon just has the purpose "fizzbuzz", then it will be ignored.
`画像の目的を決定する@ ときは、所与の ( `有順序~map$ %~JSON ) に対し: ◎ To determine the purpose of an image, given ordered map json:
- %purpose ~LET %~JSON[ `purpose^l ] ◎ ↓
- ~IF[ %purpose は`文字列$でない ] ⇒ ~RET `集合$ « `any^l » ◎ If json["purpose"] doesn't exist or if json["purpose"] is not a string: • Return set « "any" ».
- %~keyword群 ~LET `~ASCII空白で分割する$( %purpose ) ◎ Let keywords be the result of split on ASCII whitespace json["purpose"].
- %目的~群 ~LET 新たな`集合$ ◎ Let purposes be new set.
-
%~keyword群 を成す ~EACH( %~keyword ) に対し ⇒ ~IF[ %~keyword ~NIN `~icon目的~list$ ] ⇒ %目的~群 に %~keyword を`付加する$set ◎ For each keyword of keywords: • If icon purposes list doesn't contain keyword, then continue. • Otherwise, append keyword to purposes.
- ~IF[ %目的~群 は`空$である ] ⇒ ~RET `失敗^i ◎ If purposes is empty, then return failure.
- ~RET %目的~群 ◎ Return purposes.
2.2. 画像~資源の~CSP
~manifestの所有者~文書に結付けられた `img-src$dir 指令 `CSP3$r は、 ~UAは~icon画像を~fetchできるかどうかを統治する~security施策である。 ◎ The security policy that governs whether a user agent can fetch an icon image is governed by the img-src directive [CSP3] associated with the manifest's owner Document.
例えば次のように,[ ~manifestの所有者~文書【が得られた`応答$】の `Content-Security-Policy$h ~HTTP~header ]内に `img-src$dir 指令が与えられたとする: ◎ Example 7: Content security policy of icons For example, given the following img-src directive in the Content-Security-Policy HTTP header of the manifest's owner Document:
HTTP/1.1 200 OK Content-Type: text/html Content-Security-Policy: img-src icons.example.com <!doctype> <html> <link rel="manifest" href="manifest.webmanifest">
次の `manifest.webmanifest^c が与えられたとするとき: ◎ And given the following manifest.webmanifest:
{ "name": "custom manifest", "start_url": "https://boo", "icons": [ { "src": "//icons.example.com/lowres" }, { "src": "//other.com/hi-res" } ] }
~icon資源の~fetchingは、 `icons.example.com/lowres^c からは成功することになる一方で, `other.com/hi-res^c からは失敗することになる。 ◎ The fetching of icon resources from icons.example.com/lowres would succeed, while fetching from other.com/hi-res would fail.
2.3. ~icon~maskと安全~zone
一部の~platformには,自前の選好される~icon形状があるが、 ~web~appは複数の~platformにまたがって働くべきであり、[ 目的として `maskable$l を追加する ]ことにより,[ ~UAが指定された~maskを~iconに適用できることを指示する ]こともアリである。 これは、 次を~platformに許容する ⇒# ~iconが~platformに統合されても,きちんと見えることを確保する / ~platform全体を通して,場所ごとに異なる~maskや背景~色を適用する ◎ Some platforms have their own preferred icon shape, but as web applications should work across multiple platforms, it is possible to indicate that an icon can have a user-agent-specified mask applied by adding the maskable purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different masks and background colors in different places throughout the platform.
`安全~zone@ は、 ~UAの選好に関わらず,`~mask可能$な~iconの中の[ 常に可視になると保証される区画 ]である。 それは、 次のような真円として定義される ⇒ [ 中心は~iconの中心に一致する ]~AND[ 半径は~icon~size — ~iconの横幅, 縦幅のうち小さい方 — の 40% ] ◎ The safe zone is the area within a maskable icon which is guaranteed to always be visible, regardless of user agent preferences. It is defined as a circle with center point in the center of the icon and with a radius of 2/5 (40%) of the icon size, which means the smaller of the icon width and height, in case the icon is not square.
注記: `~mask可能$な~iconの設計者は、 重要な部分はすべて`安全~zone$の中に必ず入るよう求めることになる。 ◎ Note Designers of maskable icons will want to make sure that all important parts are within the safe zone.
この~zone内の画素は、 ~mask内に見えることが保証される。 安全~zoneの外側にある画素は、 可視になることは保証されない (適用される~maskに依存して,可視になり得るが)。 ◎ All pixels in this zone are guaranteed to be seen in all masks. Pixels outside the safe zone are not guaranteed to (but can) be visible depending on the applied mask.
~UAは、 任意~sizeの~maskを適用して,`安全~zone$ (中心から画像~size(正方形でないならば横幅, 縦幅の最小)の 0.4 倍~以内) の外にある画素を透明にしても`ヨイ^EM。 ◎ The user agent MAY apply a mask of any size, making any pixels that are more than 2/5ths of the image size (minimum of width and height if non-square) away from the center (the safe zone) transparent.
~UAは、 安全~zoneの中の画素は透明にしない`モノトスル^EM。 ◎ The user agent MUST NOT make any pixel within the safe zone transparent.
~UAは、 ~paddingをさらに追加して~iconを大きくしても`ヨイ^EM。 ◎ The user agent MAY enlarge the icon by adding additional padding.
~iconが透明な画素を包含する場合、 ~UAは, ~iconを自身が選んだ~solid-fill(例:~white)上に組成する`モノトスル^EM。 ◎ If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid fill (e.g., white) of the user agent's choice.
注記: ~iconの設計者には、 ~mask可能な~icon内で透明な画素を利用するのは避けることが示唆される。 ◎ Note It is suggested that designers avoid using transparent pixels in maskable icons.
2.3.1. ~maskの例
注記: `安全~zone$の内側に~~収めることにより、 ほとんどの~iconは,その上下左右端に[ 無~内容な, あるいは本質的でない内容(~icon背景など)を伴う ] 10% の~paddingを備えるようになる。 開発者には、[ 安全~zone以外のすべてが~maskで消された~icon ]を検査することが示唆される。 ◎ Note By staying inside the safe zone, most icons will have around 10% padding on the top, bottom, right and left with no content or non-essential content, such as an icon background. It is suggested that developers check their icon when all but the safe zone is masked out.
目的 `maskable$l を伴う~icon ◎ 2.3.1.1 Icons with "maskable" purpose
~mask例 ◎ 2.3.1.2 Mask examples
2.4. 単彩色~iconと~solid-fill
一部の~platformは、 ~iconを単-色など, `~solid-fill@ ( `solid fill^en )で表示するよう施行する。 そこでは、 `~manifest$内で宣言し得るのは,~iconの透明度に限られる。 ~web~appは,複数の~platformにまたがって働く必要があるので、 `monochrome$l 目的を追加することにより,[ ~iconには、 ~UAが指定した色を適用できる ]ことを指示することはアリである。 これは、 次を確保することを~platformに許容する ⇒ ~iconの見かけは — ~platform全体を通して,場所に応じて異なる色や~paddingを適用することまで含め — ~platformにきちんと統合される。 ◎ Some platforms enforce that icons be displayed with a solid fill such as a single color, where only the transparency of the icon can be declared in a manifest. As web applications need to work across multiple platforms, it is possible to indicate that an icon can have an user-agent-specified color applied by adding the monochrome purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different colors and padding in different places throughout the platform.
~UAは、 `monochrome$l ~iconを呈示するときは,画素の[ ~red, ~green, ~blue ]成分を独立に表示しない`モノトスル^EM — 各~画素を元の~alpha値で, かつ すべての画素に自身が選んだ同じ[ ~red, ~green, ~blue ]値を利用して表示する`ベキ^EMである。 ◎ When presenting a monochrome icon, the user agent MUST NOT independently display the red component, green component, or blue component of a pixel. The user agent SHOULD display each pixel with its original alpha value, but with a red, green, and blue value of the user agent's choosing. It is RECOMMENDED that the user agent use the same color value for all pixels.
注記: `monochrome$l ~iconの設計者は、 すべての画素を~blackに設定して, 透明度のみを利用して ~iconの~silhouetteを作成することもできる。 ◎ Note Designers of monochrome icons could set all pixels to black and only use transparency to create a silhouette of their icon.
~UAは、 ~paddingをさらに追加して~iconを大きくしても`ヨイ^EM。 【!重複】 ◎ The user agent MAY enlarge the icon by adding additional padding.
~UAは、 透明な画素の背後に どの色の背景を追加しても`ヨイ^EMが、 背景と~iconの~contrastは,~~十分に確保する`ベキ^EMである。 ◎ The user agent MAY add a background of any color behind transparent pixels, and SHOULD ensure that the background has sufficient contrast with the icon.
2.4.1. 単彩色~iconの用法~例
目的 `monochrome$l を伴う~icon ◎ 2.4.1.1 Usage examples
2.5. 画像~資源の処理
`画像~資源を処理する@ ときは、所与の ( `~list$ %画像~群, `有順序~map$ %~map, %~manifest~URL, `文字列$ %~member ) に対し: ◎ To process image resources, given list images, ordered map map, manifest URL and string member:
- %画像~資源~list ~LET 新たな`~list$ ◎ Let imageResources be a new list.
- %~map[ %~member ] ~SET %画像~資源~list ◎ Set map[member] to imageResources.
- ~IF[ %画像~群 は`~list$でない ] ⇒ ~RET ◎ If images is not list, return.
-
%画像~群 を成す ~EACH( %画像かも ) に対し: ◎ For each potential image of images:
- %画像 ~LET `~JSONから画像~資源を処理する$( %画像かも, %~manifest~URL ) ◎ Let image be the result of running process an image resource from JSON given potential image and manifest URL.
- ~IF[ %画像 ~EQ `失敗^i ] ⇒ ~CONTINUE ◎ If image is failure, continue.
- %目的~群 ~LET `画像の目的を決定する$( %画像かも ) ◎ Let purposes be determine the purpose of an image passing potential image.
- ~IF[ %目的~群 ~EQ `失敗^i ] ⇒ ~CONTINUE ◎ If purposes is failure, continue.
- %画像[ `purpose^l ] ~SET %目的~群 ◎ Set image["purpose"] to purposes.
- %画像~資源~list に %画像 を`付加する$ ◎ Append image to imageResources.
3. ~shortcut~item
各 `~shortcut~item@ は、 ~web~appの中の[ 主要task/~page ]への~linkを表現する`有順序~map$である。 それは、 次に挙げる~memberを有する ⇒# `name$mH, `short_name$mH, `description$mH, `url$mH, `icons$mH ◎ Each shortcut item is an ordered map that represents a link to a key task or page within a web app. It has the following members: • name • short_name • description • url • icons
利用者が ~web~appの~iconを~~起動したとき,~UAは、 これらの~memberを[ ~OSにより表示される文脈~menuを組立てる ]ために利用できる。 利用者が~OS~menuから~shortcutを呼出したとき,~UAは、 次を走らす`ベキ^EMである ⇒ `~shortcutを立上げる$( その~shortcutを与えている`~shortcut~item$ ) ◎ A user agent can use these members to assemble a context menu to be displayed by the operating system when a user engages with the web app's icon. When the user invokes a shortcut from the operating system menu, the user agent SHOULD run launching a shortcut.
- `name@mH ◎ 3.1 name member
- `文字列$ ◎ The shortcut item's name member is a string\
- 文脈~menuにおいて通例的に利用者に表示される,この~shortcutの名前を表現する。 ◎ that represents the name of the shortcut as it is usually displayed to the user in a context menu.
- `short_name@mH ◎ 3.2 short_name member
- `文字列$ ◎ The shortcut item's short_name member is a string\
- 短い~versionの,この~shortcutの名前を表現する — この~shortcutの全部的な名前を表示するには空間が足らない所での利用が意図される。 ◎ that represents a short version of the name of the shortcut. It is intended to be used where there is insufficient space to display the full name of the shortcut.
- `description@mH ◎ 3.3 description member
- `文字列$ ◎ The shortcut item's description member is a string\
- この~shortcutの目的を述べることを開発者に許容する — ~UAは、 この情報を支援技術に公開しても`ヨイ^EM。 ◎ that allows the developer to describe the purpose of the shortcut. User agents MAY expose this information to assistive technology.
- `url@mH ◎ 3.4 url member
- `文字列$ ◎ The shortcut item's url member is\
- `~app文脈$の`処理-済み~manifest$の`~navi~scopeの中$にあり, この~shortcutが作動化されたとき開くことになる~URL。 ◎ a URL within scope of a processed manifest that opens when the associated shortcut is activated.
- `icons@mH ◎ 3.5 icons member
- ~list ◎ The shortcut item's icons member lists\
- 様々な文脈において,この~shortcutの~icon的な表現として~serveする画像【を表現する【~JSON~obj】たちからなる。 ◎ images that serve as iconic representations of the shortcut in various contexts.
`~shortcutを立上げる@ ときは、 所与の ( %~manifest, `~shortcut~item$ %~shortcut ) に対し ⇒ `~web~appを立上げる$( %~manifest, %~shortcut[ `url^l ]【!shortcut.url】 ) ◎ 3.6 Launching a shortcut ◎ When shortcut item shortcut having manifest is invoked, run the steps to launch a web application with manifest and shortcut.url.
3.1. 【!3.7.】~shortcut~itemの処理
`~shortcutを処理する@ ときは、所与の ( `有順序~map$ %~item, `~URL$ %~scope ) に対し: ◎ To process a shortcut, given ordered map item and scope,:
-
~IF[ ~OR↓ ]…
- %~item は `有順序~map$でない
- %~item[ `name^l ] は`文字列$でない
- %~item[ `name^l ] ~EQ 空~文字列
- %~item[ `url^l ] は`文字列$でない
…ならば ⇒ ~RET `失敗^i
◎ Return failure if it's the case that: • item is not ordered map. • item["name"] doesn't exist. • item["name"] is the empty string. • item["url"] doesn't exist. • item["url"] is not a string. - %~URL ~SET `~URL構文解析する$( %~item[ `url^l ], %~manifest~URL ) ◎ Let url be the result of parsing item["url"] with manifest URL as the base URL.
- ~IF[ %~URL ~EQ `失敗^i ] ⇒ ~RET `失敗^i ◎ If url is failure, return failure.
- ~IF[ `~targetは~scopeの中にある$( %~URL, %~scope ) ~EQ ~F 【!原文は`~navi~scopeの中$を参照しているが、それだと引数が合わない】 ] ⇒ ~RET `失敗^i ◎ If url is not within scope of scope, return failure.
- %~shortcut ~LET 新たな`有順序~map$ «[ `url^l → %~URL, `name^l → %~item[ `name^l ] ]» ◎ Let shortcut be ordered map «[ "url" → url, "name" → item["name"] ]».
- `画像~資源を処理する$( %~item[ `icons^l ], %~shortcut, %~manifest~URL, `icons^l ) ◎ Process image resources passing item["icons"], shortcut, manifest URL, and "icons".
- ~RET %~shortcut ◎ Return shortcut.
4. 外部~app資源
`956$issue: この仕様の `related_applications^c ~memberは、 現時点で,その実装は一つしかないため、 `~risk下$にある。 Web Apps ~WGは、 この特能を仕様~内に保つため,もう一つの実装を探している。 ◎ (Feature at Risk) Issue 956: related_applications is single engine feature ◎ The related_applications member of this specification currently only has a single implementation. As such, it has been marked "at risk" as per the W3C Process, meaning that: • [The feature] may be removed before advancement to Proposed Recommendation without a requirement to publish a new Candidate Recommendation. ◎ The Web Apps Working Group is seeking a second implementation in order to keep this feature in the specification.
各 `外部~app資源@ は、 当の~web~appに関係する~appを表現する。 それは、 次に挙げる~memberを有し得る — それらのうち一部は、 `妥当な外部~app資源$になるために要求される ⇒# `fingerprints$mA, `id$mA, `min_version$mA, `platform$mA, `url$mA ◎ Each external application resource represents an application related to the web application. ◎ An external application resource can have the following members, some of which are required to be a valid external application resource: • fingerprints member • id member • min_version member • platform member • url member
`妥当な外部~app資源@ は、 ~memberとして次を有していなければナラナイ ⇒ `platform$mA, および [ `url$mA, `id$mA ]のうちどちらか(両方あってもよい) ◎ A valid external application resource MUST have platform member, and either an url or an id member (or both).
次の例では、 ~web~appは[ 関係する~appとして,異なる 2 つ ]を~listしている。 1 つは `Google Play Store^en にあるもの, もう 1 つは `iTunes Store^en にあるものを指す。 `Google Play Store^en にある方は、 `Google Play Store^en に特有な方式で[ ~Android~package名, 最小~version指定子, 検証y用に利用される暗号上の指紋 ]を有する。 ◎ Example 8 In the following example, the web application is listing two different related applications, one on Google Play Store and the other one on the iTunes Store. The one on the Google Play Store has an Android package name, a minimum version specifier, and cryptographic fingerprints used for verification, in a Play-Store-specific manner.
{ "related_applications": [ { "platform": "play", "url": "https://play.google.com/store/apps/details?id=com.example.app1", "id": "com.example.app1", "min_version": "2", "fingerprints": [ { "type": "sha256_cert", "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2" } ] }, { "platform": "itunes", "url": "https://itunes.apple.com/app/example-app1/id123456789" } ] }
`外部~app資源$が有し得る~memberは: ◎ ↓
- `platform@mA ◎ 4.1. platform member
- 当の`外部~app資源$に結付けられた`~platform$を表現する。 ◎ The platform member represents the platform this external application resource is associated with.\
- `~platform@ は、[ ~software頒布~ecosystem/場合によっては~OS ]を表現する。 この仕様は、 この~member用に特定0の値を定義しない。 ◎ A platform represents a software distribution ecosystem or possibly an operating system. This specification does not define the particular values for the platform member.
- 【 この仕様の他の節に現れる “~platform” には、 この~platformを意味するものもあるかもしれない。 】
- 当~WGは、 `既知な~platform値たちが成す~list@https://github.com/w3c/manifest/wiki/Platforms$を保守する。 ◎ The working group maintains a registry of known platform values.
- `url@mA ◎ 4.2. url member
- 当の~appが見出された~URLを与える。 ◎ An external application resource's url member is the URL where the application can be found.
-
`~appの~URLを処理する@ ときは、 所与の ( %~app~URL ) に対し: ◎ To process the url member of an application:
- ~RET [ 次の結果 ~NEQ `失敗^i ならば その結果/ ~ELSE_ ~NULL ] ⇒ `~URL構文解析する$( %~app~URL ) ◎ (この段は不要) If application URL is missing, return null. ◎ Otherwise, parse application URL and if the result is not failure, return the result. Otherwise return null.
- `id@mA ◎ 4.3. id member
- 当の`~platform$で~appを表現するために利用される~IDを表現する。 ◎ An external application resource's id member represents the id which is used to represent the application on the platform.
- `min_version@mA ◎ 4.4. min_version member
- この~appが当の~web~appに関係すると見なされるための,最小~versionを表現する。 この~versionは,`文字列$であり、 その構文と意味論は,当の`~platform$に特有である。 ◎ An external application resource's min_version member represents the minimum version of the application that is considered related to this web app. This version is a string with platform-specific syntax and semantics.
- `fingerprints@mA ◎ 4.5. fingerprints member
- `指紋$たちが成す`~list$を表現する。 ◎ An external application resource's fingerprints member represents an list of fingerprints.
- `指紋@ は、 ~appを検証yするために利用される暗号上の指紋たちが成す集合を表現する。 各~指紋は、 2 つの~member `type@mP, `value@mP からなる。 どちらも`文字列$であり、 その構文と意味論は,当の`~platform$が定義する。 ◎ A fingerprint represents a set of cryptographic fingerprints used for verifying the application. A fingerprint has the following two members: type and value. Each of these are strings, but their syntax and semantics are platform-defined.
5. ~install可能な~web~app
~UA用の~manifestの共通的な利用事例は、 ~web~appを `~install@ することにある。 それにより,~UAは、 `~top-level閲覧~文脈$を, ~manifestを成す~memberたちを`適用-$した上で — すなわち,[ ~manifestの各~member, それらの既定の値 ]の効果が発揮されるように — ~instance化する手段を末端利用者に供する。 `~install$された~web~appは、 `~installした~web~app@ と称される。 このように~installされる~web~appが,伝統的な~bookmarkから~~際立つのは、 後者から~web~pageを開いても,~manifestを成す~prop群は`適用-$されないことにある。 ◎ A common use case of a manifest is for a user agent to install a web application; whereby the user agent provides the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. A web application that is installed is known as a installed web application. That is, the manifest's members, or their defaults, are in effect on the top-level browsing context. This distinguishes an installed web application from a traditional bookmark, as opening a web page from a traditional bookmark will not have the manifest's properties applied to it.
例えば,~installationを~supportする~UA上では、[ 末端利用者からは~native~appと判別-不能な仕方 ]で~web~appを呈示して立上げることもできる —[ `home screen^en / `launcher^en / `start menu^en ]にて,~label付き~iconとして現れるなど。 `~web~appを立上げる$とき,~manifestは — その`開始~URL$が読込まれるに先立って — ~UAにより`~top-level閲覧~文脈$に`適用-$される。 これは、[ ~manifestに関連な値を適用する機会 ]を~UAに与える — ~web~appの[ `表示~mode$/~screen方位 ]を場合によっては変更するなど。 あるいは別の例として、 ~UAは,[ 自身の~bookmarkたちが成す~listの中に,~web~appを`~install$する ]こともできる。 ◎ Note For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu. When launching a web application, the manifest is applied by the user agent to the top-level browsing context prior to the start URL being loaded. This gives the user agent an opportunity to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application. Alternatively, and again as an example, the user agent could install the web application into a list of bookmarks within the user agent itself.
5.1. ~appの名前
`~appの名前@ は、 ~manifest内の[ `name$mM, `short_name$mM ]~memberから導出される: ◎ The application's name is derived from either the name member or short_name member.
- 片方の~memberだけ[ 欠落である/空~文字列をとる【!空】/間違った型である ]場合 ⇒ ~UAは、 その~fallbackとして,もう片方を利用しても`ヨイ^EM。 ◎ When either the name member or the short_name member is missing, empty, or the wrong type, a user agent MAY use the name member as a fallback for the short_name member or short_name member as the fallback for the name member.
-
両~memberとも[ 欠落である/空~文字列をとる【!空】/間違った型である ]場合 ⇒ ~UAは、[ 欠落~member用に相応しい置換を`文書$【内の~metadata】から見出す ]よう~fallbackしても`ヨイ^EM (例: `short_name$mM に代えて `application-name$v を利用する) — そうしない場合、 代替として:
- ~platform規約に従う既定の名前 (例: `Untitled^l 【 “~titleなし” 】 ) をアテガう`ベキ^EMである。
- 末端利用者に次を許容しても`ヨイ^EM ⇒ `~appの名前$として~serveできる何らかの~textを入力する
- 他の場合【!両~memberとも在る場合】 ⇒ 可用な空間に どちらの~memberがより適するかは、 実装の裁定に委ねられる (例:~iconの~~下側に可用な空間~用には, `short_name$mM ~memberの方が適するかもしれない)。 ◎ When both the name and short_name members are present, it is left up to implementations to decide which member is best suited for the space available (e.g., the short_name member might be better suited for the space available underneath an icon).
5.2 ~web~appの立上n法
[ ~OS/~UA ]の裁量で,次を走らす ⇒ `~web~appを立上げる$( `処理-済み~manifest$ ) ◎ At the discretion of the operating system or user agent, run the steps to launch a web application with a processed manifest.
注記: これは概して、 利用者が`~installした~web~app$を~app立上n用~UI — 例: `home screen^en/ `launcher^en / `start menu^en — から選定したとき,場を占めることになる。 ◎ Note This would typically take place when the user selects an installed web app from an app launching UI surface e.g., a home screen, launcher or start menu.
`~web~appを立上げる@ 手続きは、 所与の ⇒# `処理-済み~manifest$ %~manifest, `~URL$ %~target~URL(省略時は ε ), `~POST資源$ %~POST資源(省略時は ~NULL ) ◎終 に対し,`~app文脈$を返す: ◎ The steps to launch a web application is given by the following algorithm. The algorithm takes a processed manifest manifest, an optional URL target URL, an optional POST resource POST resource and returns an application context.
- ~Assert: %~target~URL は、 ε でないならば, %~manifest の`~navi~scopeの中$にある。 ◎ target URL, if given, MUST be within scope of manifest.
- ~RET `新たな~app文脈を作成する$( %~manifest, %~target~URL, %~POST資源 ) ◎ ↓
他の仕様は、 この~algoの手続きを自前の手続きで置換してもヨイ。 この置換は、 `~web~appを立上げる$すべての呼出nに効果を発揮することになる。 ◎ Other specifications MAY replace this algorithm's steps with their own steps. This replacement will take effect for all invocations of launch a web application.
注記: この~algoが置換-可能なのは、[ 試験的な~manifest~field `launch_handler@https://github.com/WICG/web-app-launch$c で,すべての~web~app立上nの挙動を環境設定する ]ことを許容するためである。 置換~algoは、 既定では`新たな~app文脈を作成する$を呼出すが,ある種の条件の下では挙動が異なる。 ◎ Note This algorithm is replaceable to allow an experimental launch_handler manifest field to configure the behavior of all web application launches. The replacement algorithm invokes create a new application context by default but under certain conditions behaves differently. ◎ ↑↑Return the result of running the steps to create a new application context passing manifest, target URL and POST resource.
`新たな~app文脈を作成する@ 手続きは、 所与の ⇒# `処理-済み~manifest$ %~manifest, `~URL$ %~target~URL(省略時は ε ), `~POST資源$ %~POST資源(省略時は ~NULL ) ◎終 に対し,`~app文脈$を返す: ◎ The steps to create a new application context is given by the following algorithm. The algorithm takes a processed manifest manifest, an optional URL target URL, an optional POST resource POST resource and returns an application context.
- ~IF[ %~target~URL ~EQ ε ] ⇒ %~target~URL ~SET `開始~URL$ ◎ If target URL was not given, set target URL to start URL.
- %辿可能 ~LET `新鮮な~top-level辿可能を作成する$( %~target~URL, %~POST資源 ) ◎ Let traversable be the result of running the steps to create a fresh top-level traversable with target URL and POST resource.
- %閲覧~文脈 ~LET %辿可能 にて`作動中な閲覧~文脈$nav ◎ Let browsing context be the traversable's active browsing context.
- `~manifestを適用する$( %~manifest, %閲覧~文脈 ) ◎ Apply manifest to browsing context.
- ~RET %閲覧~文脈 ◎ Return browsing context.
5.3. ~privacyと~securityの考慮点
~web~appを`~install$する能を末端利用者に~~供する~UIは、 ~web~appに係る[ ~icon, 名前, `開始~URL$, 生成元, 等々 ]を検分することも,末端利用者に許容することが`推奨される^EM。 これは、 末端利用者が意識的に裁定を下す機会を与える — ~web~appを~installする前に,それに係る情報を[ 認可する/場合によっては改変する ]ような。 これはまた、 ~web~appが — 例えば,期待されない~iconや名前を利用することにより — 別の~web~appを偽装している場合に,末端利用者がそれを見分ける機会を与える。 ◎ It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.
~UAには、[ 他の~appが,どの~appが~system上に~installされたか決定すること ] (例:~UAの~cacheに対する計時~攻撃を介して) を防止することが`推奨される^EM。 これは、 例えば,次のいずれかにより行い得る: ◎ It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example,\
- ~web~appが`~install$された後に, ~UAの~cache内の[ ~manifestから~linkされた資源 ](例えば,~icon)を無効~化する。 ◎ invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or\
- 定例の~web閲覧~用に利用される~cacheとは まったく別の~cacheを利用する。 ◎ by using an entirely different cache from that used for regular web browsing.
5.4. ~uninstallation
~UAは、 `~installした~web~app$を除去するための仕組みを利用者に供する`ベキ^EMである。 ◎ User agents SHOULD provide a mechanism for the user to remove an installed web application application.
~UAはまた、 除去の時点で,当の~appに結付けられていた他の持続的な[ ~data/設定群 ] — 許可や持続的な~storageなど — を~revokeするための機会を利用者に呈示することが`推奨される^EM。 ◎ It is RECOMMENDED that at the time of removal, the user agent also present the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.
7. 表示~mode
`表示~mode@ は、 ~web~appが~OSの文脈の中にどう呈示されるかを表現する (例:~fullscreen内に, 等)。 表示~modeは、 所与の~platform上で利用-中にある~UI~metaphorと機能性に対応する。 表示~modeの~UI規約は、 純粋に助言的である — 実装者は、 それを最もよく収まるものに解釈してもかまわない。 ◎ A display mode represents how the web application is being presented within the context of an OS (e.g., in fullscreen, etc.). Display modes correspond to user interface (UI) metaphors and functionality in use on a given platform. The UI conventions of the display modes are purely advisory and implementers are free to interpret them how they best see fit.
この仕様は、 次に挙げる`表示~mode$を定義する: ◎ This specification defines the following display modes:
- `fullscreen@l
- ~web~appは、 ~browserの~UI要素は隠される下で開かれ,可用な表示-区画~全体を占める。 ◎ Opens the web application with browser UI elements hidden and takes up the entirety of the available display area.
- `standalone@l
- ~web~appは、[ 自立的な~native~appの様な見かけと感触 ]を備えるように開かれる。 これには、 ~appが[ 異なる~window, ~app `launcher^en 内に自前の~icon, 等々 ]を備えることも含まれ得る。 ~UAは,この~modeにおいては、 標準な~browser~UI要素 — ~URL~barなど — を除外することになるが, 他の~system~UI要素 — 状態s~bar, ~systemの “戻る” ~buttonなど — を含めれる。 ◎ Opens the web application to look and feel like a standalone native application. This can include the application having a different window, its own icon in the application launcher, etc. In this mode, the user agent will exclude standard browser UI elements such as an URL bar, but can include other system UI elements such as a status bar and/or system back button.
- `minimal-ui@l
- この~modeは, `standalone$l に類似するが、 ~naviの制御~用に[ 必要最小限な~UI要素~一式 (すなわち、[ 戻る, 進む, 読み込み直す ]に加えて,たぶん文書の~addressを~viewするための何らかの仕方) へ~accessするための何らかの手段 ]を末端利用者に供する。 ~UAは、~platformに特有な他の~UI要素も含めれる — “共有する”, “印刷する” ~buttonや,[ ~platform/~UA ]上で恒例な何であれ。 ◎ This mode is similar to standalone, but provides the end-user with some means to access a minimal set of UI elements for controlling navigation (i.e., back, forward, reload, and perhaps some way of viewing the document's address). A user agent can include other platform specific UI elements, such as "share" and "print" buttons or whatever is customary on the platform and user agent.
- `browser@l (既定)
- ~UA内で~hyperlinkを開くための~platformに特有な規約を利用して,~web~appを開く (例:~browser~UItabや新たな~window内に)。 ◎ Opens the web application using the platform-specific convention for opening hyperlinks in the user agent (e.g., in a browser tab or a new window).
注記: `fullscreen$l `表示~mode$は、 `FULLSCREEN$r ~APIとは【!直交的かつ】独立に働く。 `fullscreen$l は,~browser~windowの~fullscreen状態に影響する一方で、 `FULLSCREEN^r ~APIは,表示域の中に包含される要素に対し演算する。 そのようなわけで、 ~web~appの`表示~mode$は `fullscreen$l に設定される一方で,当の文書の[ `fullscreenElement@~FULLSCREEN#dom-document-fullscreenelement$m は ~NULL を返す 【!fullScreenElement】/ `fullscreenEnabled@~FULLSCREEN#dom-document-fullscreenenabled$m は ~F を返す ]こともある。 ◎ Note The fullscreen display mode is orthogonal to, and works independently of, the Fullscreen API Standard. The fullscreen display mode affects the fullscreen state of the browser window, while the [FULLSCREEN] API operates on an element contained within the viewport. As such, a web application can have its display mode set to fullscreen, while document.fullScreenElement returns null, and fullscreenEnabled returns false.
~UAが`~app文脈$に特定0の`表示~mode$を適用したなら、 それは,`~top-level閲覧~文脈$用の `既定の表示~mode@ になる (すなわち、 ~windowが`~navigate$されたときに表示~modeとして利用される)。 ~UAは、 ~securityの理由があれば,`既定の表示~mode$を上書きしても`ヨイ^EM (例:`~top-level閲覧~文脈$が別の生成元へ`~navigate$されたとき)。 ~UAはまた、 別の`表示~mode$へ切替える手段を利用者に供しても`ヨイ^EM。 ◎ Once a user agent applies a particular display mode to an application context, it becomes the default display mode for the top-level browsing context (i.e., it is used as the display mode when the window is navigated). The user agent MAY override the default display mode for security reasons (e.g., the top-level browsing context is navigated to another origin) and/or the user agent MAY provide the user with a means of switching to another display mode.
`display$mM ~memberが欠落であるか,その値が妥当でないときは、 ~UAは,`既定の表示~mode$として `browser$l `表示~mode$を利用する。 そのようなわけで、 ~UAは,`表示~mode$として `browser$l を~supportする`モノトスル^EM。 ◎ When the display member is missing, or if there is no valid display member, the user agent uses the browser display mode as the default display mode. As such, the user agent MUST support the browser display mode.
どの`表示~mode$にも `~fallback連鎖@ がある — それは、 `表示~mode$たちが成す`~list$であり,次の表tで与えられる:
`表示~mode$ | `~fallback連鎖$ |
---|---|
`browser$l | « » |
`minimal-ui$l | « `browser$l » |
`standalone$l | « `minimal-ui$l, `browser$l » |
`fullscreen$l | « `standalone$l, `minimal-ui$l, `browser$l » |
`~web~appが選んだ表示~modeを決定する手続き@ は、所与の ( `処理-済み~manifest$ %~manifest ) に対し,ある`表示~mode$を返す: ◎ The steps for determining the web app's chosen display mode is given by the following algorithm. The algorithm takes a processed manifest manifest and returns a display mode.
- `処理~拡張~地点$ ⇒ [ ~proprietaryな/他の~supportされる ]表示~modeが在れば,この地点で処理する ◎ processing extension-point: process any proprietary and/or other supported display modes at this point in the algorithm.
- %表示~mode ~LET %~manifest[ "`display$mM" ] ◎ ↓
- ~IF[ ~UAは %表示~mode を~supportする ] ⇒ ~RET %表示~mode ◎ If the user agent supports manifest["display"], then return manifest["display"].
- %表示~mode の`~fallback連鎖$を成す ~EACH( %~fallback~mode ) に対し ⇒ ~IF[ ~UAは %~fallback~mode を~supportする ] ⇒ ~RET %~fallback~mode ◎ For each fallback_mode of the fallback chain of manifest["display"]: • If the user agent supports the fallback_mode, then return fallback_mode.
- ~Assert: この段に達することはない — `browser$l 以外の どの`表示~mode$にも,その`~fallback連鎖$内には `browser$l があり、 すべての~UAは,`表示~mode$として `browser$l を~supportする要件があるので。 ◎ Note The above loop is guaranteed to return a value before the assertion, due to the fact that browser is in every mode's fallback chain, and the requirement that all user agents support the browser display mode.
ある架空の~browser SuperSecure Browser は,表示~modeとして[ `minimal-ui$l, `browser$l ]のみを~supportしている一方で、 開発者は `fullscreen$l を求めていて,~manifest内で `display$mM ~propを利用してそれを宣言したとする。 この事例では、 ~UAは,まず `fullscreen$l を~supportするかどうかを検査することになる… が、 ~supportしないので, `standalone$l に~fall-backする… が、 それも~supportしないので,最終的に `minimal-ui$l に~fall-backすることになる。 ◎ Example 9 SuperSecure Browser (a fictitious browser) only supports the minimal-ui and browser display modes, but a developer declares that they wants fullscreen in the manifest by using the display property. In this case, the user agent will first check if it supports fullscreen (it doesn't), so it falls back to standalone (which it also doesn't support), and ultimately falls back to minimal-ui.
`表示~mode~list@ は、 次で与えられる`~list$である ⇒ « `fullscreen$l, `standalone$l, `minimal-ui$l, `browser$l » ◎ The display modes list is the list « "fullscreen", "standalone", "minimal-ui", "browser" ».
~UAは、 適用される[ ~web~appの`表示~mode$ ] 【すなわち、上の~algoで決定されたそれ】 を `display-mode$d 媒体~特能 `MEDIAQUERIES-5$r 内に反映する`モノトスル^EM。 ◎ A user agent MUST reflect the applied display mode of the web application in the display-mode media feature [MEDIAQUERIES-5].
注記: ~UAは、 適用されている実際の表示~modeを — [ ~CSS/~JS ]を通して~access可能な `display-mode$d 媒体~特能を介して — 公開することになる — それは、 ~manifest内に宣言されたものになるとは限らない。 この媒体~特能は、 ~web~page用の~manifestが適用されていないときは, 他の表示~modeも反映するようになることに注意。 例えば,末端利用者が~pageを~fullscreenの中へ置いた場合、 ~UAは,その変化を `display-mode$d 媒体~特能を介して[ ~CSS/~script ]へ反映することになる。 ◎ Note A user agent will expose the actual display mode being applied — not necessarily the one declared in the manifest — via the display-mode media feature, accessible through CSS or JavaScript. Note that this media feature will also reflect other display modes for a web page when a manifest is not being applied. For example, if the end-user puts the page into fullscreen, then the user agent would reflect this change to CSS and scripts via the display-mode media feature.
8. ~privacyと~securityの考慮点
この仕様は、 高価値な~dataに対し,直に対処することはない。 しかしながら,[ `~installした~web~app$, その~data ]は、 “高価値なもの” としても見れる (特に,~privacyの観点からは)。 ◎ This specification does not directly deal with high-value data. However, installed web applications and their data could be seen as "high value" (particularly from a privacy perspective).
~manifest形式は~JSONであり, `UNICODE$r を利用して符号化されるので、 `JSON$r, `UNICODE-SECURITY$r に述べられる~security考慮点が適用される。 加えて,[ 開発者が[ ~customな/拘束されない ]~dataを`~manifest$内に含めること ]を防止する仕方は無いので、 実装者は,[ 他から制約されない~member型の値 ]に対し[ 実装に特有な自前の制限sを課す ]必要がある — 例 ⇒# ~DoS攻撃を防止するため/ ~memoryの使い切りに抗して防護するため/ ~platformに特有な制限を回避するため ◎ As the manifest format is JSON and will be encoded using [UNICODE], the security considerations described in [JSON] and [UNICODE-SECURITY] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest, implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
~web~appは、 一般に[ ~JS, ~HTML, ~CSS~file, その他の~media ]を包含し, それらは~sandbox化された環境~内で実行されることになる。 そのようなわけで,実装者は、 ~supportする型による~securityへの含意を自覚する必要がある。 特定的には、 実装者は,[ 少なくとも,次に挙げる仕様 ]に要旨された~securityへの含意を考慮する必要がある ⇒ `CSS-MIME$r, `ECMAScript-MIME$r, `HTML$r ◎ Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [CSS-MIME], [ECMAScript-MIME], [HTML].
~web~appは[ 局所的な機器, ~remote~host ]の両者と同時的にヤリトリ-可能な内容を包含し得るので、 実装者は[ 私的~情報を~remote~hostへ公開することによる,~privacyへの含意 ]を考慮する必要がある。 その軽減と防衛策の掘り下げは、 実装の責務であり,この仕様には規定されない。 しかしながら,防衛策を設計する際には、 実装者には次を勧める ⇒# 情報~共有についての利用者の自覚を可能化すること/ 許可の~revocationを可能化する~UIへの容易な~accessを供すること ◎ As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.
この仕様は,~manifestの一定の~memberの中で~URLの宣言を許容するので、 実装者は[ `URL$r 仕様にて論じられた~security考慮点 ]を考慮する必要がある。 ~manifest内に見出された[ ~IRI/~IDNA ]~addressを表示しようと意図している実装には、[ `UNICODE-SECURITY$r 内に与えられた~security助言 ]に従うことが強く奨励される。 ◎ As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [URL] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [UNICODE-SECURITY].
開発者は[ `CSP3$r 仕様~全体を通して論じられた~security考慮点 ]を自覚する必要がある。 特に、[ ~manifestを “~inline化” する目的で, `data:^c ~URLを妥当な~sourceにする ]ことに関して。 そうすることは、 文書~自身が~manifestを直に含むことを許容するので,~XSS攻撃を可能化し得る — これは完全に避けるのが最善である。 ◎ Developers need to be aware of the security considerations discussed throughout the [CSP3] specification, particularly in relation to making data: a valid source for the purpose of "inlining" a manifest. Doing so can enable XSS attacks by allowing a manifest to be included directly in the document itself; this is best avoided completely.
~web~appを`~install$する能を末端利用者に~~供する~UIは… 【以下,`~install可能な~web~app: § ~privacyと~securityの考慮点@#installation-sec$と同じ(なので,和訳は省略する)。】 ◎ It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name. ◎ It is RECOMMENDED that user agents prevent other applications from determining which applications are installed on the system (e.g., via a timing attack on the user agent's cache). This could be done by, for example, invalidating from the user agent's cache the resources linked to from the manifest (for example, icons) after a web application is installed - or by using an entirely different cache from that used for regular web browsing.
~shortcut用の `url$mH は、[ ~appは~browserの外側から立上げられた ]ものと指示するよう細工されたり (例: `"url": "/task/?from=homescreen"^c ), 開発者が[ 利用者を一意に識別する文字列 ]を その中に符号化する~~可能性も~~考えられる (例:~serverがアテガった識別子【!~UUID】)。 これは、 利用者が自覚しないかもしれない[ 指紋収集/~privacyに敏感な情報 ]になる。 ◎ It's conceivable that a shortcut url could be crafted to indicate that the application was launched from outside the browser (e.g., "url": "/task/?from=homescreen"). It is also conceivable that developers could encode strings into the url that uniquely identify the user (e.g., a server assigned UUID). This is fingerprinting/privacy sensitive information that the user might not be aware of.
~web~appが稼働している間は、 ~UAには, ~web~appについての共通な情報 — [ 生成元, 開始~URLや現在の~URL, 是認された許可, 結付けられた~icon ]など — に~accessする手段を末端利用者に供することが`推奨される^EM。 そのような情報が末端利用者にどう公開されるかは、 実装者に委ねられる。 ◎ When the web application is running, it is RECOMMENDED that the user agent provides the end-user a means to access common information about the web application, such as the origin, start and/or current URL, granted permissions, and associated icon. How such information is exposed to end-users is left up to implementers.
加えて,~UAには、[ `表示~mode$を `browser$l 以外の何かに設定する~manifest ]を適用するときは,[ ~web~browserの通常の閲覧~文脈から去っていることを,末端利用者に明瞭に指示する ]ことが`推奨される^EM — 例えば[ 長く~animateされる明白な遷移 / “~app X を立上げています” と発話する ]など。 また,~web~app[ を立上げる/に切替える ]のは、 ~host~platform内の他の~app[ を立上げる/に切替える ]ときと一貫した方式で遂行されるのが理想である。 ◎ Additionally, when applying a manifest that sets the display mode to anything except "browser", it is RECOMMENDED that the user agent clearly indicate to the end-user that their are leaving the normal browsing context of a web browser. Ideally, launching or switching to a web application is performed in a manner that is consistent with launching or switching to other applications in the host platform. For example, a long and obvious animated transition, or speaking the text "Launching application X".
`display$mM ~memberは、 ~UAの~native~UIに対する ある程度の制御を生成元に許容する。 それは、 ~fullscreenを占めた後には, 別の~appの~UIを真似るよう試みることもできる。 また,このことは、 `display-mode$d 媒体~特能 `MEDIAQUERIES-5$r により手助けされる — ~scriptは、 それを通して~web~appの表示~modeを知れるので。 ◎ The display member allows an origin some measure of control over a user agent’s native UI. After taking over the full screen, it could attempt to mimic the user interface of another application. This is also facilitated by the 'display-mode' media feature [MEDIAQUERIES-5], through which a script can know the display mode of a web application.
A. ~IANA考慮点
`~app~manifest~MIME型@ は、 ~MIME型 `application/manifest+json@c である。 ~MIME型に加え,~file拡張子 `.webmanifest^c も `~IANAに登録された@~IANA-a/media-types/application/manifest+json$。 ◎ The mime type application/manifest+json is the application manifest media type. Both the mime type and the .webmanifest file extension are registered with the Internet Assigned Numbers Authority (IANA).
A.1. ~MIME型~登録
~manifestが[ `MIME-TYPES$r 仕様を~supportする~protocol(例: ~HTTP) ]越しに転送される場合、 `~app~manifest~MIME型$で~labelすることが`推奨される^EM。 ◎ If the protocol over which the manifest is transferred supports the [MIME-TYPES] specification (e.g. HTTP), it is RECOMMENDED that the manifest be labeled with the application manifest media type.
- 型~名 ⇒ `application^c ◎ Type name: • application
- 下位型~名 ⇒ `manifest+json^c ◎ Subtype name: • manifest+json
- 要求される~parameter ⇒ N/A ◎ Required parameters: • N/A
- 省略可能な~parameter ⇒ N/A ◎ Optional parameters: • N/A
- 符号化法~考慮点 ⇒ `application/json^c 用のそれと同じ ( `RFC7159$r § 8.1 ) ◎ Encoding considerations: • Same as for application/json ([RFC7159] section 8.1)
- ~privacyと~securityの考慮点 ⇒ `§ ~privacyと~securityの考慮点@#priv-sec$を見よ ◎ Privacy and security considerations: • See § 8. Privacy and security considerations.
- この~MIME型を利用する~app ⇒ ~web~browser ◎ Applications that use this MIME type: • Web browsers
-
追加的な情報:
- `Magic number(s)^en ⇒ N/A
- ~file拡張子 ⇒ `.webmanifest^c
- `Macintosh file type code(s)^en ⇒ `TEXT^c
- `Person & email address to contact for further information^en ⇒ `Web Applications ~WG@https://www.w3.org/groups/wg/webapps$ への窓口は public-webapps@w3.org にて。 ◎ Person & email address to contact for further information: • The Web Applications Working Group can be contacted at public-webapps@w3.org.
- 意図される用法 ⇒ COMMON ◎ Intended usage: • COMMON
- 用法に対する制約 ⇒ なし ◎ Restrictions on usage: • none
- 著作者 ⇒ ~W3C の Web Applications ~WG ◎ Author: • W3C's Web Applications Working Group.
- 変更~制御者 ⇒ ~W3C ◎ Change controller: • W3C
A.2. ~link関係~型~登録
- 関係~名 ⇒ `manifest^v ◎ Relation Name: • manifest
- 記述 ⇒ `~manifest$への~link。 ~manifestは、 ~web~appに結付けられる~metadataを一極に集中する場を開発者に供する。 ◎ Description: • Links to a manifest. A manifest provides developers with a centralized place to put metadata associated with a web application.
- 参照 ⇒ `~TR/appmanifest/@~TR/appmanifest/$ ◎ Reference: • https://www.w3.org/TR/appmanifest/
- 注記 ⇒ ~web~manifestが どう[ `~fetch$される/ `処理される@#dfn-processing-a-manifest$ ]かの詳細は、 ~link型 `manifest$v を見よ。 ◎ Notes: • See link type "manifest" for details about how a web manifest is fetched processed.
B. 適合性
【 この節の他の内容は、 `~W3C日本語訳 共通~page@~W3Ccommon#conformance$ に移譲。 】 ◎ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. ◎ The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
この仕様への適合性を主張し得るのは【!class of product】、 ~UAに限られる。 ◎ There is only one class of product that can claim conformance to this specification: a user agent.
注記: この仕様は,首に~web~browserを~targetにしているが、 他の~softwareも,適合する方式でこの仕様を実装できると見込まれる。 例として,探索~engineや~crawlerは、 ~manifestを見出して処理して,[ ~install可能な~web~appとしても働き得る~site ]たちが成す目録を築き上げることもできる。 ◎ Note Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, could find and process manifests to build up catalogs of sites that potentially work as installable web applications.
B.1. 拡張能
◎非規範的この仕様は、 拡張-可能になるよう設計されている。 他の仕様は、 ~manifest用に新たな~memberを定義することが奨励される。 しかしながら,そうするときには、 この仕様~内に利用される規約に従うように。 特に,`~manifestを処理する$ための手続きの中に~hookする`処理~拡張~地点$を利用すること。 また、 特定0の~memberを,この仕様にて定めた方式で処理する手続きを指定すること。 これにより、 ~web~platformを成すこの部分を,一貫したものに保ち易くなる。 ◎ This specification is designed to be extensible. Other specifications are encouraged to define new members for the manifest. However, in doing so, please follow the conventions used in this specification. In particular, use the processing extension-point to hook into the steps for processing a manifest. Also, be sure to specify the steps for processing your particular member in the manner set forth in this specification. This will help keep this part of the platform consistent.
拡張は、 ~communityが容易に見出せるよう, `拡張~registry@https://github.com/w3c/manifest/wiki/Extensions-Registry$に追加されたし。 ◎ To allow the community to easily find extensions, please add your extensions to the Extensions Registry.
新たな~memberを指定するときは、 この仕様~内に定義されるものを上書きしたり`~monkey~patch$しないこと。 また、 新たな~memberが他の~member[ より前/より後 ]に処理されるものと見做さないこと。 新たな~memberとその処理は、 不可分かつ自己完結的になるよう保つこと。 実装には、 それらどの~memberも[ 認識する/~supportする ]ことなく無視してかまわないことに注意。 ◎ When specifying a new member, don't override or monkey patch anything defined in this specification. Also, don't assume your member will be processed before or after any other member. Keep your new member, and its processing, atomic and self contained. Note also that implementations are free to ignore any member they do not recognize or support.
拡張の策定者は、 実装し易くなるよう,この仕様を一時的に~patchしたいと求める場合、 何をしようとしているか~communityに伝わるよう, `~bugを申請-@https://github.com/w3c/manifest/issues$されたし。 ◎ If you are writing a specification and temporarily want to patch this specification to help implementations along, file a bug so the community is informed of what you are trying to do.
B.1.1. ~proprietaryな~manifest~member
◎非規範的~proprietaryな拡張は,望ましくないが、 現実的には避けれない。 ~UAは,[ ~manifest~JSON内の,この文書~内に指定されない~member ]を解釈することも選べるが、 【以下に述べるように】~careすること。 ◎ Although proprietary extensions are undesirable, they can't realistically be avoided. If a user agent chooses to interpret a member in the manifest JSON that is not specified in this document, it can do so, but with care.
~proprietaryな拡張を追加している実装者には、 それが標準にもなり得るかどうか (すなわち、 異なる~platform上の他の~UAが — 今は,関心を表出していないとしても — 当の~memberを用立てることは,イミを成すかどうか) について考慮することが奨励される。 そうならば、 策定者には,当の~APIを[ ~vendor中立な仕方で設計して,標準として提案する ]ことが依頼される ( `§ ~incubation@#incubations$ を見よ)。 新たな~memberが真に~proprietaryである場合 (すなわち、 イミを成し得るのは,ある~proprietaryな~ecosystemの文脈に限られる)、 この過程を利用すること — 加えて、 名前の衝突を避けるよう,当の~memberには[ 当の~proprietaryな~ecosystemの短い名前 ]を接頭すること。 ◎ We encourage implementors adding proprietary extensions to consider whether they could become a standard (i.e. if it would make sense for a second user agent on a different platform to make use of that member, even if no other user agent has expressed interest right now). If so, we ask authors to design the API in a vendor-neutral way, and propose it as a standard (see C. Incubations). If the new member is truly proprietary (i.e. will only ever make sense in the context of a proprietary ecosystem), use this process, and prefix it with the short name of that proprietary ecosystem to avoid name collisions.
後で標準になったとき除去するものと意図する場合、 ~vendor接頭辞を利用しないこと (それらは、永劫に まとわりつく傾向にある)。 接頭辞を利用するのは、 今および将来にわたってイミを成すものに限ること。 ◎ Do not use vendor prefixes that you intend to later remove once it becomes a standard (those tend to stick around forever). Only use prefixes that will make sense now and into the future.
実装者には、 ~proprietaryな拡張を`拡張~registry@https://github.com/w3c/manifest/wiki/Extensions-Registry$に追加することが奨励される。 これにより,~communityは、[ どの[ 拡張~vendor/~web~community ]がそれを定義して文書化したか ]を追跡できるようになる。 それらの拡張は、 ~WGにより,定期的に標準~化に向けて考慮されることになる。 ◎ We encourage implementors to add proprietary extensions to our Extensions Registry. This allows the community to track what extensions vendors and/or the web community have defined and documented. Periodically, we will consider those extensions for standardization.
3 つの~proprietaryな拡張の例(仮): ◎ The following is an example of three hypothetical proprietary extensions. ◎ Example 10: Proprietary extensions
{ ... "kpl_fancy_feature": "some/url/img", "gmpc_awesome_thing": { ... }, "blitzly_site_verification": "KEY_9864D0966935" ... }
注記: この例では、 故意に,[ 外部~siteや外部~serviceにもなり得るもの ]の名前にしてある — ~browserや~browser~vendorの名前`ではなく^em。 これらは、 それらを考案した~browserに属する~vendor接頭辞ではなく, ~proprietaryな~serviceの接頭辞である。 ◎ Note In this example, we have deliberately chosen (made-up) names of things that could be external sites or services, not names of browsers or browser vendors. These are not vendor prefixes belonging to the browser that invented them; they are prefixes of proprietary services.
C. ~incubation
◎非規範的この仕様に対する拡張は、 ~Web~communityにより,並行に~incubateされて( “練り上げられて” )おり、 うち一部は,複数の~browserに出荷されている。 ~incubateされた特能を複数の~browser~engineが~supportするようになった場合、 当の特能は,~Web~platformを成す標準として この仕様の一部を成すことになろう: ◎ Extensions to this specification are being incubated in parallel by the Web Community, some of which are shipping in multiple browsers. If two or more browser engines end up supporting an incubated feature, then those features will become part of this specification in the future - allowing them to become a standard the Web Platform:
- `beforeinstallprompt^et【!BeforeInstallPrompt】 ~event型, および対応する `window.onappinstalled^m ~event~handler~IDL属性 ◎ BeforeInstallPrompt and window.onappinstalled event
- これらは、 元々は,この仕様の一部を成していた。 しかしながら,複数の実装者から~supportを得られなかったので、 この仕様から除去された ( `836$pull )。 それらは今や、 `~WICG$の `beforeinstallprompt^et ~event, `window.onappinstalled^c ~repository にて見出せる。 ◎ The BeforeInstallPrompt event and window.onappinstalled event were originally part of this specification. However, they were removed from the specification because they did not have support from two or more implementers. You can now find them in the BeforeInstallPrompt event and window.onappinstalled repository at the WICG.
- `share_target^c ~member ◎ share_target member
- `share_target^c ~memberは、 ~web~appを[ 何かを共有する動作~用の “~target” ]として登録する (例:~text/~URL/~fileを共有するため)。 `share_target^c ~memberは、 `Web Share Target@https://wicg.github.io/web-share-target/$cite 仕様の一部を成し, `~WICG$にて~incubateされている。 ◎ The share_target member registers a web application as "target" for share actions (e.g., for sharing a text, a URL, or a file). The share_target member is part of the Web Share Target specification, being incubated at the WICG.
D. ~app情報
◎非規範的`~manifest$【!Web Application Manifest】を成す~memberには、 追加的な~metadataを供するものも,いくつかある。 それらは、 ~web~appが販売されたり頒布され得る文脈 — `digital storefront^en 【 “Play ストア” 等の “売り場” 】や~installation~dialogなど — において,~web~appがどう呈示され得るかに関係する。 次に挙げる,そのような~member【の定義】は、 これらの利用事例をより良く~supportする労の一環として, `manifest-app-info$r に移動された ⇒# `categories^c, `description^c, `iarc_rating_id^c, `screenshots^c ◎ Several members of the Web Application Manifest provide additional metadata related to how the web application may be presented in the context of a digital storefront, installation dialog, or other surfaces where the web application may be marketed or distributed. In an effort to support these use cases better, the following members have been moved into Web App Manifest - Application Information: • categories • description • iarc_rating_id • screenshots
E. ~HTMLの `link^e, `meta^e 要素との関係性
◎非規範的この仕様~用に[ ~HTML[ `meta$e / `link$e ]~tag†ではなく,~JSON ]を利用することを選んだ~~理由についての,多方面な論点は、 `97$issue, および `www-tag ~list@https://lists.w3.org/Archives/Public/www-tag/2014Jan/0139.html$ にある。 以下に,それらの論点から提起された要点の短い要約を与える。 ◎ An extensive discussion of why we chose to use JSON instead of HTML meta/link tags for this specification is available on GitHub and on the www-tag list. Below is a short summary of the key points raised in those discussions.
【† この節の文脈における “~tag” とは、 挙げられた要素に特有な各種~内容~属性 (および,それらに指定される値) (すなわち,要素~tagの中に記されるもの) の総称を意味する。 】
この仕様にて定義される文書~形式は、[ ~proprietaryな, および `HTML$r に定義される ][ `meta^e / `link^e ]~tagに伴う既存の陥穽を避けることを希望して, それを避ける仕方で[ ~Web~appについての~metadataを~capsule化する ]ための統一的な手段を供する。 そのような陥穽として、 次が挙げられる: ◎ The document format defined in this specification provides a unified means of encapsulating metadata about a Web application in a way that we hope will avoid existing pitfalls with both proprietary and [HTML]'s meta/link tags. Those pitfalls include:
- 開発者は、 ~iconや~app名を~web~siteの各~pageごとに重複する必要があり, 何~pageかにまたがる有意な冗長性へ導く。 これは、 その情報を~UAが利用しない限り (例:利用者は~web~appを~bookmarkしていない), 無駄でしかなくなる。 【!?never/compounded】 ◎ Developers have to duplicate the icons and application name in each page of a web site, leading to significant redundancy across pages. This is compounded if that information never gets used by the user agent (e.g., the user never bookmarks the web application).
- ~metadataが複数の文書に散らばると、 ~dataの同期cがとれなくなり易い。 ◎ Spreading metadata across multiple documents can cause data to fall out of sync.
- ~web~app用の~metadataが~HTML文書~内に住まう場合、 ~UA(および利用者)が~siteの~metadataに対する更新を検査する~costは,有意に増える。 ~HTML~fileは,幾度も変更されると見込まれるので、 ~UAは,[ 関連な `meta^e ~tagが一つでも変更されたかどうか検査するために, ~HTML~file全体を幾度も~downloadする ]はめになる。 この資源が[ JS, 画像, ~stylesheet ]の様な資源を~inlineに包含する場合、 この~downloadも自明でなくなり得る。 ◎ If the metadata for a web application lives in a HTML document, that significantly increases the cost to user agents (and users) of checking for updates to the metadata of a site. Since the HTML file is likely to change often, it means that a user agent will often have to download the whole HTML file in order to check if any of the relevant meta tags have changed. If this resource contains inlined resources like JavaScript, images, or stylesheets, this could be a non-trivial download.
この仕様が自前の問題を持ち込まないと~~考えるのは,早計であろうが、 この~dataを~manifestの形で外部-化することは,上で述べた問題を解消する。 これらの問題は、 次により解消される: ◎ Although it would be unrealistic to think that this specification won't bring its own set of problems, externalizing this data in the form of a manifest solves the problems described above. These problems are solved by:
- ~manifestを外部に~link可能にする: 外部~manifest~fileは、 外部~資源として~cacheでき,~markupに~~費やす~byteも冗長性も節約する。 ◎ Making the manifest externally linkable: External manifest files can be cached as external resources, saving both bytes and redundancy in the markup.
- 柔軟な値~型: ~HTMLの属性と違って,~manifestの~memberは、 文字列のみならず~objや配列などの複階的な型を利用して~dataを表現できる。 これは、 ~proprietaryな `meta^e ~tagの値が現在~利用している — とりわけ~tagの値がいくつかの下位~値を包含するときの — バラバラで面倒な形式の問題を解消する。 ◎ Flexible value types: unlike HTML attributes, members of the manifest can represent data using complex types, such as objects and arrays, rather than just strings. This solves the problem of the awkward and highly inconsistent formats the values of proprietary meta tags are currently using, especially when a tag's value contains several sub-values.
加えて、 現在,[ 様々な `meta^e ~tagに基づく解決策により供されている機能性 ]を~manifestの中で標準~化することは、 どれも同じものを達成する多数の[ 【!tproprietary = to declare large number of proprietary】 ~proprietaryな/標準な ] `HTML$r ~tagを宣言する必要がある問題を解消する。 もちろんこれは、 ~browserがこの標準を実際に実装し,利用者に広く配備されていくかどうかにかかっている: これが起きた場合、 ~Web~communityは,[ これを書いている時点で~Webにはびこっている~proprietaryな `meta^e ~tag ]の多くは,退役-可能になるであろう。 ~proprietaryな~tagについてのさらなる情報は、 `~install可能な~web~app用の利用事例と要件$cite ( `Use Cases and Requirements for Installable Web Apps^en ) に見出せる。 ◎ In addition, standardizing the functionality currently provided by the various meta tag-based solutions within the manifest solves the problem of having tproprietary and standard [HTML] tags that all achieve the same thing. Of course, this hinges on the standard actually getting implemented by browsers and those browsers getting widely deployed to users: if this happens, the Web community might be able to retire many of the proprietary meta tags plaguing the Web at the time of writing. More information about the proprietary tags can be found in the Use Cases and Requirements for Installable Web Apps .
最後に,この仕様は、 `HTML$r にて見出される標準~化された解決策を冗長なものにしない。 `name$mM や `icons$mM の様な~memberが~manifestから欠落なときは、 ~UAは,~iconや~app名などを~manifestの所有者~文書から探索できる (あるいは,~UAは、 文書~内に~proprietaryな[ ~tag/~metadata ]が在る場合には,それらに~fallbackすることもあるかもしれない)。 ◎ Lastly, this specification does not make the standardized solutions found in [HTML] redundant. When members like the name or icons is missing from the manifest, user agents can search in a manifest's owner [HTML] document for things like icons and the application name (or a user agent might even fallback to proprietary tags/metadata, if they are present in a document).
F. ~JSON~schema
◎非規範的`~manifest$文書を検証することに関心がある開発者は、 `schemastore.org@https://schemastore.org/json/$ にある公式的でない `~manifest形式~用の~JSON~schema@https://json.schemastore.org/web-manifest$ に見出せる。 それは, `Apache 2.0@https://www.apache.org/licenses/LICENSE-2.0.html$ の下で許諾されており、 `Mads Kristensen@https://github.com/madskristensen$en 氏が保守してくださっている。 この~JSON~schemaに課題を見出したなら、 ~GitHub `SchemaStore repository@https://github.com/SchemaStore/schemastore$ にて `~bugを申請-@https://github.com/SchemaStore/schemastore/issues/$されたし。 ◎ Developers interested in validating manifest documents can find an unofficial JSON schema for the manifest format at schemastore.org. It is licensed under Apache 2.0. It is kindly maintained by Mads Kristensen. If you find any issues with the JSON schema, please file a bug at the SchemaStore repository on GitHub.
注記: 【…以下略(上述した “~manifest形式~用の~JSON~schema” を成す~JSON~code)。】 ◎ Note: Web Manifest JSON Schema Click to view schema. ...
G. 国際-化
◎非規範的作者には~manifestの内容を地域化するときには、 次に挙げるいずれかの~optionを利用することが期待される: ◎ It is expected that authors will localize the content of a manifest by using one of the following options:
- 言語を動的に設定する: ◎ Dynamically setting the language:
- 一例として、 末端利用者に,どの言語を選好するか尋ねて、 その選好に基づいて,文書に動的に~manifest~link関係性を[ 追加する/置換する ]よう依頼することが挙げられる (例: `manifest.php?lang=fr^l の様な~URLを利用して)。 ◎ This can include, for instance, asking the end-user what their preferred language is and dynamically adding or replacing the manifest link relationship to the document based on that language preference (e.g., using a URL like "manifest.php?lang=fr").
- ~server上での[ 内容~折衝, `geotargeting^en【利用者の地理的所在に呼応する何らかの動作(例:広告)】, 等々 ]を利用して: ◎ Using content-negotiation, or geotargeting, etc. on the server:
- ~web~appを~hostする~serverは、 次を利用して,末端利用者の言語を予め決定するよう試みることもできる: `geotargeting@https://en.wikipedia.org/wiki/Geotargeting$en / 内容~折衝 (例: ~HTTP `Accept-Language$h ~header `RFC9110$r を利用して,あるいは~custom~HTTP~headerも) ◎ The server that hosts the web application could attempt to predetermine the end-user's language by using geotargeting or by using content negotiation (e.g., using an HTTP "Accept-Language" header [RFC9110], or even a custom HTTP header).
開発者は、 上の~optionが与えられた下で,[ 末端利用者が選好する言語に関する末端利用者の~privacy ]に思慮深くある必要がある: 末端利用者が,そのような言語~選好を~web~appに明示的に指示したとき (すなわち,単に~UAの既定の言語~設定群を利用していない)、 末端利用者が選好する言語を伝送路~越しに~~平文で送信してかまわないことには,一般にならない。 そうすると、 末端利用者についての個人-情報を露呈することになる。 そのようなわけで,開発者には、 `TLS$r を利用して,~Web~appに対する `pervasive monitoring^en【(諜報機関などによる)大規模な監視網】 `RFC7258$r の機会cを抑制することが奨励される。 ◎ Given the options above, developers need to be mindful of the end-user's privacy with respect to their preferred language: When the end-user has explicitly indicated their language preference to a web application (i.e., when not just using the user-agent default language settings), sending the end-user's preferred language in the clear over the wire is generally not OK. Doing so would reveal personal information about an end-user. As such, developers are encouraged to use [TLS] to reduce the chances of pervasive monitoring of their Web applications [RFC7258].
H. 利用事例と要件
この文書は、 `~install可能な~web~app用の利用事例と要件$citeに取組むことを試みる。 ◎ This document attempts to address the Use Cases and Requirements for Installable Web Apps.
I. 課題~要約
【この節の内容(原文内に挙げられた各 課題への~link一覧)は、省略する。】 ◎ Issue 956: related_applications is single engine feature\ Issue 957: prefer_related_applications is single engine feature\ Issue 446: Specify how updates work\ Issue 905: badge purpose "monochrome" is only supported by Firefox\ Issue 956: related_applications is single engine feature\
J. 変更~log
◎非規範的最初の公な作業草案からの有意な変更点は: ◎ The following are some significant changes that were made since First Public Working Draft:
【 以下、原文は~commitの~titleそのものなので,訳さないことにする。 】
- Remove problematic icon matching algorithm ( `2f54efe$commit, `1120$pull )
- Processing steps for id now removes the fragment ( `bceb2ee$commit, `1122$pull )
- Rewrite privacy considerations on fingerprinting in start_url ( `2a8fc0a$commit, `1114$pull )
- Change "A" to "An" ( `662cc34$commit, `1103$pull )
- Allow manifest processing to be invoked without going through an HTML… ( `22a0b1e$commit )
- Ran tidy. ( `7d41b99$commit, `1067$pull )
- Describe manifest update behavior ( `54acb9e$commit, `1011$pull )
- Link to manifest-app-info in the README ( `8d0663e$commit, `1030$pull )
- Address privacy issue with start_url ( `5d2ac4b$commit, `1029$pull )
- Transfer display-mode to mediaqueries-5 ( `874996c$commit, `1022$pull )
- Add id member to manifest ( `8102fc5$commit, `988$pull )
- Use docURL as start_url ( `a8284f3$commit, `991$pull )
- Add missing shortcut icon ( `100cd9a$commit, `979$pull )
- Remove query & fragment from scope ( `04b2157$commit, `961$pull )
- Remove WebIDL + rewrite all the things ( `32b497c$commit )
- Revert "Editorial: Move some members to App Information Note ( `10c255d$commit, `900$pull )
- Moving to data-cite for the accessible name ( `72ba21c$commit, `920$pull )
- BREAKING CHANGE: remove `platform` from ManifestImageResource ( `4ab46a2$commit, `913$pull )
- Adding in some accessibility-related language ( `d1699ec$commit, `898$pull )
- Add privacy section for shortcuts member ( `1860fe4$commit,`896$pull )
- BREAKING CHANGE: Replace "badge" with "monochrome" ( `2c55d86$commit, `833$pull )
- Update links to the WG ( `f704809$commit, `871$pull )
- Remove beforeinstallprompt and appinstalled events. ( `8c7fd7b$commit, `836$pull )
- Set the manifest request's . ( `9888403$commit, `829$pull )
- Rewrite processing shortcuts algorithm to be more precise ( `83fd72b$commit, `832$pull )
- BREAKING CHANGE: remove serviceworker member ( `8923ba4$commit, `825$pull )
- Make Service Worker registration work properly (don't use outdated st… ( `6708bc8$commit )
- Add shortcuts feature to the explainer and spec ( `4c24e73$commit, `768$pull )
- Make BeforeInstallPrompt optional ( `32ce484$commit, `797$pull )
- Various fixes to ImageResource processing algorithms: ( `c3e18c8$commit, `811$pull )
- Rewrite installation process and install prompting logic ( `f8f227e$commit, `790$pull )
K. 謝辞
◎非規範的この文書は、 `HTML$r 仕様から~textを再利用する — その仕様の許諾により許可される下で。 ◎ This document reuses text from the [HTML] specification, as permitted by the license of that specification.
`HTML5Apps project^en を介してこの仕様に貢献された `Dave Raggett and Dominique Hazael-Massieux^en 氏に。 ◎ Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.
~icon例の画像を寄せられた `Claudio Gomboli^en 氏に。 ◎ Claudio Gomboli for icon example images.
事実調査から[ ~scope外の~URLへの~naviに関係する潜在的な~risk ]を報告して,この仕様に貢献された `Indiana University Bloomington^en の方々に。 ◎ Indiana University Bloomington security researchers have contributed to this specification by reporting potential risks related to out-of-scope navigation.