2024/11/25 時点の英語版に基づき更新

mdn · Dec 18, 2024 · c567923 · c567923
1 parent e87c369
commit c567923
Showing 1 changed file with 135 additions and 20 deletions.
diff --git a/files/ja/web/manifest/scope/index.md b/files/ja/web/manifest/scope/index.md
@@ -1,51 +1,166 @@
 ---
 title: scope
 slug: Web/Manifest/scope
+l10n:
+  sourceCommit: 1e660f71a4741c5fdf36bb7ac8dc7acfbc9cfb49
 ---
 
 {{QuickLinksWithSubpages("/ja/docs/Web/Manifest")}}
 
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">型</th>
-      <td><code>String</code></td>
-    </tr>
-    <tr>
-      <th scope="row">必須</th>
-      <td>いいえ</td>
-    </tr>
-  </tbody>
-</table>
+`scope` はマニフェストメンバーで、ウェブアプリケーションのページとサブディレクトリーを格納する最上位の URL パスを指定するために使用します。
+ユーザーがウェブアプリをインストールして使用すると、スコープ内のページがアプリのようなインターフェイスを提供します。
+ユーザーがアプリの対象外のページに移動した場合でも、アプリのようなインターフェイスはそのままですが、ブラウザーではコンテキストの変化を示すために、 URL バーなどの UI の要素が表示されます。
 
-`scope` メンバーは文字列型で、このウェブアプリケーションのアプリケーションコンテキストのナビゲーションスコープを定義します。これは、マニフェストが適用されている時に見ることができるウェブページを制限するものです。ユーザーがスコープ外へ移動した場合は、ブラウザータブやウィンドウの中の通常のウェブページに戻ります。
+## 構文
 
-`scope` が相対 URL である場合、ベース URL はマニフェストの URL になります。
+```json-nolint
+/* 絶対 URL */
+"scope": "https://example.com/myapp/"
+
+/* 相対 URL */
+"scope": "/myapp/"
+
+/* 特定のディレクトリーに制限されたスコープ */
+"scope": "/myapp/dashboard/"
+```
+
+### 値
+
+- `scope`
+
+  - : URL を表す文字列です。
+    これは絶対 URL にも相対 URL にもすることができます。
+    値が相対 URL の場合、マニフェストファイルの URL に対して解決されます。
+
+    マニフェストで `scope` が指定されていない場合、または値が不正な場合（文字列でない、無効なURLである、または `start_url` が指定された `scope` 内にない場合）、実効的なスコープは、ファイル名、クエリー、フラグメントが除去された後の `start_url` の値に設定されます。
+
+## 解説
+
+`scope` メンバーは、ウェブアプリのインストールされた環境の一部である URL を定義します。ブラウザーは `scope` を使用して、ページがウェブアプリの{{Glossary("Application_context", "アプリケーションコンテキスト")}}内にあるかどうかを判断します。
+
+### スコープ内及びスコープ外の動作
+
+URL が「スコープ内」とみなされるのは、その URL のパスが `scope` で定義された URL パスで始まる場合です。
+例えば、`scope` が `/app/` に設定されている場合、 `/app/`、`/app/page.html`、`/app/dashboard/index.html` の URL はすべてスコープ内とみなされますが、`/` や `/page.html` はスコープ外となります。
+
+ユーザーがインストールされたウェブアプリを開くと、アプリのようなユーザーインターフェイスが提供されます。
+スコープ内のページでは、ブラウザーはアプリケーションのコンテキストを維持し、アプリのような使い勝手を保ちます。
+ユーザーがアプリのスコープ外のページに移動した場合でも、概ねアプリのようなインターフェイスが提供されますが、これらのページでは、ブラウザーは URL バーなどの追加の UI 要素を表示します。
+これにより、ユーザーはアプリの定義されたスコープ外のページを表示していることを理解しやすくなります。
+
+> [!NOTE]
+> `scope` メンバーは、ユーザーが定義したスコープ外のアプリページに移動することを妨げるものではありません。
+> スコープ外のナビゲーションはブラウザーによってブロックされず、新しい最上位の閲覧コンテキストで開かれることもありません。
+
+次のディレクトリー構造をもつ、ハイキングコースを探索するためのウェブアプリを想定してみましょう。
+
+```plain
+web-app/
+├── manifest.json
+├── trails/
+│   ├── index.html
+│   ├── trail-list.html
+│   ├── settings/
+│   │   └── index.html
+│   └── saratoga-gap-trail.html
+├── blog/
+│   └── index.html
+```
+
+スコープを `/trails/` に設定すると、次のようになります。
+
+- `/trails/` 以下のページやサブディレクトリー（`trail-list.html` や `/trails/settings/index.html` など）を表示すると、ユーザーはブラウザーのコントロールのないアプリのようなインターフェイス（左の画像）が使えます。
+- `/blog/` などのサブディレクトリーのページに移動すると、アプリの範囲外であるにもかかわらず、アプリのようなインターフェイスはそのまま残りますが、ユーザーにはウェブサイトのアドレスや他にもブラウザーのコントロール（右の画像）が表示されます。
+
+| スコープ内ページ                                                                                  | スコープ外のページ                                                                                                                  |
+| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| ![ブラウザーのコントロールがないアプリのインターフェイスを示すトレイリストページ](trail-list.png) | ![アプリのようなインターフェイスを維持しながら、ウェブサイトアドレスとブラウザーのコントロールを表示しているブログページ](blog.png) |
+
+### 深いリンクが張られたページへの影響
+
+他のアプリケーションでも、ウェブアプリケーションの特定のページに直接深いリンクを張ることができます。
+`scope` メンバーは、リンク先のページがどのように表示されるかに影響しますが、深いリンクが動作しないわけではありません。
+
+先述の例の、 `scope` を `/trails/` に設定した、ハイキングコースを探索するためのウェブアプリについて考えてみましょう。
+
+- `https://trailnav.app/trails/saratoga-gap-trail.html` へのリンクがソーシャルメディアで共有された場合、 Trail Navigator アプリをインストールしたユーザーは、ブラウザーのコントロールなしに、アプリのインターフェイスでこのページを表示します。
+- `https://trailnav.app/blog/trail-safety.html` へのリンクが共有された場合、これらのユーザーはアプリのようなインターフェイスでブログページを表示しますが、ウェブサイトアドレスとブラウザーコントロールが表示されます。これは、アプリが定義する範囲外であるためです。
+
+この動作により、外部リンクからアプリページにアクセスした場合でも、ユーザーがアプリのスコープ内またはスコープ外のページを閲覧しているかを理解しやすくなります。
+
+### 代替の scope の動作
+
+`start_url` が `scope` URL のサブセットでない場合、`scope` は無効になります。
+
+- **有効**: `scope` が `/app/` で、 `start_url` が `/app/home.html` の場合
+- **無効**: `scope` が `/app/` で、 `start_url` が `/index.html` の場合
+
+`scope` が指定されていない場合、または不正な場合は、ファイル名、クエリー、フラグメントが除去された後の `start_url` の値が既定値となります。
+なお、 `start_url` も未定義（または不正な）場合は、マニフェストにリンクしているページが既定値となります。
+これにより、既定ではインストールを起動したページからスコープが開始されることが確保されます。
+
+例を挙げます。
+
+- `start_url` が `https://example.com/app/index.html?user=123#home` の場合、スコープは `https://example.com/app/` になります。
+- `start_url` が `/pages/welcome.html` の場合、スコープは同一オリジンの `/pages/` となります。
+- `start_url` が `/pages/` の場合（末尾のスラッシュが重要）、スコープは `/pages/` となります。
+
+`scope` のフォールバック動作に頼っている場合は、アプリ内のすべてのページの URL が、 `start_url` の親パスで始まるように確実に保持してください。
+この方法でスコープの決定に関する課題を避けるには、マニフェストファイルで `scope` を明示的に指定することをお勧めします。
+
+### スコープの照合の仕組み
+
+スコープ URL の文字列照合では、パス構造ではなく単純な接頭辞の一致を使用します。
+例えば、 `scope` が `/prefix` に設定されている場合、 `/prefix` で始まる URL、たとえば `/prefix-of/index.html` や `/prefix/index.html` を含めて一致します。 `/prefix-of/index.html` は、たとえ `prefix-of` がスコープ `/prefix` と完全に一致していなくても一致します。
+
+このため、`/`で終わるスコープを定義することが推奨されます。
+`scope` を `/prefix/` に設定すると、確実に `/prefix/` ディレクトリー内のページのみと一致するようになり、意図しない一致を防ぐことができます。
 
 ## 例
 
-スコープが相対 URL の場合は、マニフェストの URL がベース URL として使用されます。
+### 絶対 URL でのスコープの指定
+
+ウェブアプリのマニフェストファイルが `https://hikingapp.com/index.html` からリンクされており、すべてのサブディレクトリーをスコープに含めることを希望しているとします。下記に表示されているように、マニフェストファイルの URL と同じオリジンである絶対 URL を使用して、このスコープを指定することができます。これにより、 `https://hikingapp.com/store` や `https://hikingapp.com/company` のようなページがウェブアプリの一部であることを確保することができます。
 
 ```json
-"scope": "/app/"
+{
+  "scope": "https://hikingapp.com/"
+}
 ```
 
-以下のスコープは、ナビゲーションを現在のサイトに制限します。
+### 相対 URL でのスコープの指定
+
+マニフェストファイルの URL が `https://hikingapp.com/resources/manifest.json` で、スコープを `https://hikingapp.com/app/` にしたい場合、相対 URL として次のように定義することができます。
 
 ```json
-"scope": "https://example.com/"
+{
+  "scope": "../app/"
+}
 ```
 
-最後に、以下の例はナビゲーションを現在のサイトのサブディレクトリーに制限します。
+### ウェブアプリをサイトの特定の部分向けに定義
+
+ウェブサイトには複数の部分があるものの、ウェブアプリでは特定の部分に焦点を当てたい場合、`scope` を以下のように定義することができます。
 
 ```json
-"scope": "https://example.com/subdirectory/"
+{
+  "name": "My Hiking Web App",
+  "start_url": "https://hikingapp.com/store/",
+  "scope": "https://hikingapp.com/store/"
+}
 ```
 
+この設定では、 `https://hikingapp.com/store/products` のようなページはウェブアプリの一部ですが、 `https://hikingapp.com/company/` はウェブアプリの対象外となります。対象外の URL の場合、ブラウザーはさまざまな UI の要素を表示して、ユーザーにアプリの対象外に移動したことを知らせます。
+
 ## 仕様書
 
 {{Specifications}}
 
 ## ブラウザーの互換性
 
 {{Compat}}
+
+## 関連情報
+
+- [`start_url`](/ja/docs/Web/Manifest/start_url) マニフェストメンバー
+- {{Glossary("Application_context", "アプリケーションコンテキスト")}}