From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../mdn/structures/compatibility_tables/index.html | 476 +++++++++++++++++++++ 1 file changed, 476 insertions(+) create mode 100644 files/ja/mdn/structures/compatibility_tables/index.html (limited to 'files/ja/mdn/structures/compatibility_tables') diff --git a/files/ja/mdn/structures/compatibility_tables/index.html b/files/ja/mdn/structures/compatibility_tables/index.html new file mode 100644 index 0000000000..e93cfb04d2 --- /dev/null +++ b/files/ja/mdn/structures/compatibility_tables/index.html @@ -0,0 +1,476 @@ +--- +title: 互換性一覧表とブラウザー互換性データリポジトリ (BCD) +slug: MDN/Structures/Compatibility_tables +tags: + - MDN Meta + - ガイド + - ブラウザー互換性 + - 互換性テーブル + - 互換性一覧表 + - 構造 +translation_of: MDN/Structures/Compatibility_tables +--- +
{{MDNSidebar}}
+ +

MDN には、オープンなウェブ文書のための互換性一覧表の標準形式があります。これは、すべてのブラウザーにわたって共有される DOM, HTML, CSS, JavaScript, SVG などの技術の文書で使用されます。この記事は、作成した互換性一覧表をデータベースにどのように追加して維持するか、また、一覧表を記事に統合する方法についての「始め方」のガイドです。

+ +

より高度なドキュメントや、データを表現するために使用される手続きや JSON スキーマの最新の変更点については、データリポジトリの contributor guide や data guidelines guide をご覧ください。

+ +

質問がある場合や問題を発見した場合は、 MDN ディスカッションフォーラムで相談してください。

+ +

データリポジトリにアクセスする方法

+ +

データは GitHub リポジトリに保存されています - https://github.com/mdn/browser-compat-data を参照してください。アクセスするには GitHub アカウントを取得し、 browser-compat-data を自分のアカウントでフォーク (fork) し、フォークしたものをローカルマシンにクローン (クローン) する必要があります。

+ +

データを追加する準備

+ +

新しいデータを追加する前に、フォークがメインリポジトリの最新である (同じ内容を含む) ことを確認し、フォーク内に追加を格納するための新しいブランチ (ブランチ) を作成し、そのブランチをローカルのクローンにプルすれば、その中で作業を始めることができます。

+ +

フォークが最新であることを、次のように簡単な方法で確認してみましょう。

+ +

メインの browser-compat-data リポジトリをリモートとして追加

+ +

端末またはコマンドラインでフォークをローカルにクローンした場所へ行き、次のようにしてリモートにメイン (upstream) リポジトリを指すよう追加します (これを行う必要があるのは一度だけです)。

+ +
git remote add upstream https://github.com/mdn/browser-compat-data.git
+ +

もしこれをしたか不明確であれば、次のようにリポジトリがどのリモートを指しているかを確認することができます。

+ +
git remote -v
+ +

リモートのコンテンツでフォークを更新する

+ +

では、フォークを更新したいときは、次のようにできます。

+ +
    +
  1. +

    master ブランチにいることを確認します。

    + + 
    git checkout master
    +
    2. +
  2. +

    以下のように更新されたリポジトリのコンテンツをフェッチ (fetch) します。

    + + 
    git fetch upstream
    +
    3. +
  3. +

    ローカルの master の内容をメイン (upstream) リポジトリの master の内容にリベース (rebase) します。

    + + 
    git rebase upstream/master
    +
    4. +
  4. +

    以下のようにしてここまでの変更をあなたがフォークしたリモートへ反映します。

    + + 
    git push
    +
    5. +
+ +

作業用の新しいブランチの作成

+ +

次に、自分のリモートフォーク (普通はhttps://github.com/自分のユーザー名/browser-compat-data) へ行き、以下の手順で新しいブランチを作成します。変更したい内容をここに追加していくことになります。

+ +
    +
  1. "Branch: Master" ボタンをクリックします。
    2. +
  2. 新しいブランチの名前を "Find or create a branch..." と書かれたところに入力します。
    3. +
  3. "Create branch ブランチ名 from Master" と書かれたボタンを押します。
    4. +
+ +

例えば、 WebVR API についてデータを追加したい場合 "webvr" という名前がブランチ名として考えられるでしょう。

+ +

新しいブランチへの切り替え

+ +

ここから先は作業が端末またはコマンドラインに戻ります。ローカルにクローンしたものを更新して新しく作成したブランチを使えるようにするには、下のコマンドを使います。

+ +
git pull
+ +

そして以下のように新しく作成したブランチに切り替えます。

+ +
git checkout name-of-branch
+ +

これでデータを追加するための準備が完了しました！

+ +

データの追加

+ +

データを追加するには、新たに互換性データを書いたファイルを作成する必要があります。作成する必要があるファイルは、どの技術分野について作業しようとするかによって異なります。

+ + + +

あなたが作成するファイルは、このリポジトリに含まれているスキーマで定義されている構造に従わなければなりません。詳細なスキーマの説明はこちらで見ることができます。

+ +

基本的な互換性データの構造

+ +

では例を見ていきましょう。例として CSS プロパティの JSON ファイルに求められる基本構造を次に示します。

+ +
{
+  "css": {
+    "properties": {
+      "border-width": {
+        "__compat": {
+          ...
+        }
+      }
+    }
+  }
+}
+ +

まず css オブジェクトがあります。その中に properties オブジェクトがあります。 properties オブジェクトの中には、互換性データとして定義したい特定の機能につき一つのメンバーが必要です。それぞれのメンバーは __compat をメンバーに持ち、この中に実際のデータを記述します。

+ +

上記のデータは border-width.json にあります。 MDN で表示された border-width の表と見比べてみてください。

+ +

他の種類の機能についても同様ですが、ただしオブエジェクトの名前が異なります。

+ + + +
+

HTML や CSS、 JavaScript のページにおいては、普通一つだけの機能について記述するでしょう。しかし API インターフェイスについては少し事情が異なります。なぜなら常に複数のサブ機能を持つからです (下の {{anch("Sub-features", "サブ機能")}} を参照してください)。

+ +

機能内の基本構造

+ +

機能の __compat メンバーの中には、以下のメンバーを記述する必要があります。

+ + + +

ブラウザーメンバーの名前はスキーマで定義されています (Browser identifiers を参照してください)。現在定義されている識別子の完全な一覧のもの使用してください。他のブラウザーを追加したい場合は、広範な影響があり、慎重に考えずに行うべきではありませんので、まず私たちに相談してください。

+ +

基本的なブラウザーの compat データファイルでは、ブラウザー識別子のメンバーの中に "version_added" を含めるだけでよいでしょう (後ほど {{anch("Adding_data_Advanced_cases", "データの追加: 高度な場合")}} で説明します)。記述することができる値は以下の通りです。

+ + + +

status メンバーの内容には、以下の3つのサブメンバーの記述してください。

+ + + +

border-width の機能データ (border-width.json も参照) を一例として以下に示します。

+ +
"__compat": {
+  "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width",
+  "support": {
+    "chrome": {
+      "version_added": "1"
+    },
+    "webview_android": {
+      "version_added": "2"
+    },
+    "edge": {
+      "version_added": true
+    },
+    "edge_mobile": {
+      "version_added": true
+    },
+    "firefox": {
+      "version_added": "1"
+    },
+    "firefox_android": {
+      "version_added": "1"
+    },
+    "ie": {
+      "version_added": "4"
+    },
+    "ie_mobile": {
+      "version_added": "6"
+    },
+    "opera": {
+      "version_added": "3.5"
+    },
+    "opera_android": {
+      "version_added": "11"
+    },
+    "safari": {
+      "version_added": "1"
+    },
+    "safari_ios": {
+      "version_added": "3"
+    }
+  },
+  "status": {
+    "experimental": false,
+    "standard_track": true,
+    "deprecated": false
+  }
+}
+ +

説明の追加

+ +

__compat メンバーには、4つ目のオプションのメンバである、descriptionがあります。これを使用することで、その機能に関する人間にとって読みやすい説明を含めることができます。これを含めるべきなのは、データを少し見ただけではその機能が何であるかがわかりにくい場合だけです。例えば、データ構造を見ただけではコンストラクタが何であるかわからないかもしれないので、次のような記述を含めることができます。

+ +
{
+  "api": {
+    "AbortController": {
+      "__compat": {
+        ...
+      },
+      "AbortController": {
+        "__compat": {
+          "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController",
+          "description": "<code>AbortController()</code> constructor",
+          "support": {
+            ...
+          }
+        }
+      }
+
+      ... etc.
+    }
+  }
+}
+ +

サブ機能

+ +

互換性一覧表が複数の行を持つページでは、各行の情報を定義するために、各機能の中に複数の副機能が必要になります。これは、例えば、ある機能の基本的なサポートが一つの行に格納されていても、そのしばらく後に、その機能が新しいプロパティや値の型を持つようになった場合などに起こります。

+ +

例として、background-colorプロパティの互換性データ と 対応するMDNページ を参照してください。基本的なサポートは上で説明したように __compat オブジェクトの中に存在しており、ブラウザの "16進数値のアルファチャンネル "のサポートするに関する追加の行は、それ自身の__compat オブジェクトを含んでいます。

+ +
{
+  "css": {
+    "properties": {
+      "background-color": {
+        "__compat": {
+          ...
+        },
+        "alpha_ch_for_hex": {
+          "__compat": {
+            ...
+          },
+        }
+      }
+    }
+  }
+}
+ +

API の場合、上位 2 つのレベルを api.name-of-the-interface として定義し、次に上位の __compat セクションでインターフェイスの全体的なブラウザ互換性を定義し、インターフェイス内に含まれるメソッド、プロパティ、およびコンストラクタのそれぞれのサブ機能を定義します。基本的な構造は以下のようになります。

+ +
{
+  "api": {
+    "VRDisplay": {
+      "__compat": {
+        ...
+      },
+      "cancelAnimationFrame": {
+        "__compat": {
+          ...
+        }
+      },
+      "capabilities": {
+        "__compat": {
+          ...
+        }
+      },
+
+      ... etc.
+
+    }
+  }
+}
+ +

完全な例は、VRDisplay.jsonを参照してください。

+
+ +

データの追加: 高度な場合

+ +

ブラウザの互換性データには、いくつかの高度な機能があります。このセクションの目的は、最も一般的なものをリストアップし、それぞれの例を提供して、あなた自身の互換性データにそれらを実装する方法を示すことです。

+ +

脚注を含める

+ +

しばしば互換性一覧表には、有益な詳細や、開発者にとって有用な奇妙な動作を説明する、特定のエントリに関連した脚注が含まれています。例として、{{domxref("VRDisplay.capabilities")}} (VRDisplay.jsonも参照) の Chrome Android エントリには、(執筆時点では)"現在はGoogle Daydreamのみでサポートされています "という脚注がありました。これを互換性データに含めるために、関連する "chrome_android "サブメンバーの中に "notes "サブメンバーを追加しました。これはこのようになります。

+ +
"chrome_android": {
+  "version_added": true,
+  "notes": "Currently supported only by Google Daydream."
+}
+ +

ベンダープレフィックスを含める

+ +

ある機能が、あるブラウザでベンダープレフィックス付きでサポートされている場合、ブラウザの互換性データでそのことを明確にしたいと思うでしょう。Firefoxにおいて、 -moz- プレフィックスによりサポートされている機能を想像してください。互換性データでこれを指定するには、該当する "firefox" サブメンバーの中に "prefix" サブメンバーを追加する必要があります。これは次のようになります。

+ +
"firefox": {
+  "version_added": true,
+  "prefix": "-moz-"
+}
+ +

ブラウザーの設定やフラグを含める

+ +

いくつかの機能はブラウザでサポートされているかもしれませんが、それらは実験的なものであり、デフォルトではオフになっています。ユーザがこの機能を使いたい場合は、環境設定/フラグを使ってオンにする必要があります。

+ +

互換性データでこれを表現するには、関連するブラウザ識別子サブメンバーの中に "flags" サブメンバーを追加する必要があります。flags" の値は、3つのメンバを含むオブジェクトの配列です。

+ + + +

つまり、ある機能のChromeのサポートに環境設定/フラグを追加するには、次のようにします。

+ +
"chrome": {
+  "version_added": "50",
+  "flags": [
+    {
+      "type": "preference",
+      "name": "Enable Experimental Web Platform Features",
+      "value_to_set": "true"
+    }
+  ]
+},
+ +

もしその機能が2つ以上のフラグの元にある場合、この例のように "flags"配列にオブジェクトを追加することができます。

+ +
"firefox": {
+  "version_added": "57",
+  "flags": [
+    {
+      "type": "preference",
+      "name": "dom.streams.enabled",
+      "value_to_set": "true"
+    },
+    {
+      "type": "preference",
+      "name": "javascript.options.streams",
+      "value_to_set": "true"
+    }
+  ]
+},
+ +

対応が削除されたバージョンを含める

+ +

あるブラウザのバージョンで追加された機能が、非推奨となったために再び削除されることがあります。これは、削除されたバージョン番号を表す文字列を値として受けとる、"version_removed" サブメンバーを使えば簡単に表現できます。例えば、以下のようになります。

+ +
"firefox": {
+  "version_added": "35",
+  "version_removed": "47",
+},
+ +

同じブラウザーの項目に複数の対応ポイントを含む

+ +

同じブラウザの複数のサポートデータポイントを、同じ機能の中に追加したい場合もあるでしょう。

+ +

例えば、 {{cssxref("text-align-last")}} プロパティ（text-align-last.jsonも参照）は、バージョン35でChromeに追加され、プレフィックス付きでサポートされました。

+ +

上記のサポートはバージョン 47 で削除されましたが、バージョン 47 でもデフォルトで text-align-last が有効になるようにサポートが追加されました。

+ +

これらのデータポイントの両方を含めるために、"chrome "サブメンバーの値を、単一のサポート情報オブジェクトではなく、2つのサポート情報オブジェクトを含む配列にすることができます。

+ +
"chrome": [
+  {
+    "version_added": "47"
+  },
+  {
+    "version_added": "35",
+    "version_removed": "47",
+    "flags": [
+      {
+        "type": "preference",
+        "name": "Enable Experimental Web Platform Features",
+        "value_to_set": "true"
+      }
+    ]
+  }
+],
+ +
+

注: ​​​​配列の中には、最新または重要なサポートポイントを最初に配置するべきです。こうすることで、単に最新の情報を取得したい人にとって読みやすいデータとなります。

+
+ +

別名を含める

+ +

時々、ブラウザが仕様とは異なる名前で機能をサポートすることがあります。これは例えば、あるブラウザがある機能の実験的なサポートを早くから追加していて、仕様が安定する前に名前が変わってしまったというような場合が考えられます。

+ +

このようなケースをブラウザの互換性データに含めるには、"alternative_name"メンバの中に代替名を指定するサポート情報ポイントを含めます。

+ +
+

注: 代替名は正確なエイリアスではないかもしれません。標準バージョンとは異なる動作をするかもしれません。

+
+ +

では例を見てみましょう。{{cssxref("border-top-right-radius")}} プロパティ（border-top-right-radius.jsonも参照）のFirefoxでのサポートは以下の通りです。

+ + + +

これをデータで表現するために、以下のJSONを使用しました。

+ +
"firefox": [
+  {
+    "version_added": "4",
+    "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0."
+  },
+  {
+    "prefix": "-webkit-",
+    "version_added": "49",
+    "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>."
+  },
+  {
+    "alternative_name": "-moz-border-radius-topright",
+    "version_added": "1",
+    "version_removed": "12"
+  }
+],
+ +

変更のメインリポジトリへの反映

+ +

互換性データの追加が終わったら、まず以下のコマンドを使ってテストしてみてください。

+ + + +

問題がなさそうであれば、コミットして、GitHub上のあなたのリモートフォークにプッシュする必要があります。これは、以下のようなターミナルコマンドで簡単に行うことができます。

+ +
git add .
+git commit -m 'adding compat data for name-of-feature'
+git push
+ +

リモートフォーク (URLの例: https://github.com/your-username/browser-compat-data) に行くと、ファイルリストの一番上 (「最近プッシュしたブランチ」の下) にあなたのプッシュに関する情報が表示されているはずです。プルリクエスト（あなたのリモートフォークをメインリポジトリに取り込むための、最初の過程のことです）を作成するには、"Compare & pull request" ボタンを押して、続く画面の簡単なプロンプトに従ってください。

+ +

これが終われば、ただ待つのみです。レビュアーがあなたのプルリクエストをレビューし、メインリポジトリにマージします。そうでない場合は、変更を依頼します。変更が必要な場合は、変更を加えて、プルリクエストが受理されるまで再度投稿してください。

+ +

MDN ページへのデータの挿入

+ +

一度あなたの新しいデータがメインリポジトリに含められたら、{{TemplateLink("Compat")}} マクロを使って、MDNページ上でそのデータに基づいてブラウザの互換性一覧表を動的に生成することができます。これは、JSONデータを探索して、互換性一覧表を生成したい機能を表すオブジェクトを見つけるために必要なドット記法を唯一のパラメータとして受け取ります。

+ +


+ マクロ呼び出しの上に、他のコントリビューターにとって使いやすくするために、編集モードのMDNでコントリビューターにのみ表示される隠しテキストを追加します。

+ +
<div class="hidden">
+The compatibility table on this page is generated from structured data.
+If you'd like to contribute to the data, please check out
+<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>
+and send us a pull request.
+</div>
+ +

例として、HTTPヘッダーに関するページである {{HTTPHeader("Accept-Charset")}} では、マクロの呼び出しは次のようになっています。 \{{Compat("http.headers.Accept-Charset")}}リポジトリ内のaccept-charset.jsonファイルを見ると、これが JSON データにどのように反映されているかがわかると思います。

+ +

別の例として、{{domxref("VRDisplay.capabilities")}} プロパティの互換性一覧表は、 \{{Compat("api.VRDisplay.capabilities")}}を使用して生成されます。マクロ呼び出しにより、以下の表（および対応する一連の注釈）が生成されます。

+ +
+ + +

{{Compat("api.VRDisplay.capabilities")}}

+ +
+

注: ファイル名は、JSON 構造体内のインターフェイスに与えられたラベルと一致することがよくありますが、必ずしもそうとは限りません。マクロ呼び出しがテーブルを生成するときには、使用する JSON を見つけるまですべてのファイルを探索するので、ファイル名はそれほど重要ではありません。そうは言っても、常に可能な限り直感的な名前を付けるべきです。

+
-- cgit v1.2.3-54-g00ecf