API リファレンスサイドバー

この記事は翻訳が完了していません。 この記事の翻訳にご協力ください

関連するインターフェイス、チュートリアル、およびその API に関連するその他のリソースへのリンクを表示できるように、API リファレンスページにカスタムサイドバーを含めることができます。この記事では、この方法について説明します。

サイドバーの作成

API サイドバーを作成するには、次の3つの手順を実行する必要があります。

  1. API リファレンスページを作成します
  2. 特定の API のエントリを KumaScript リポジトリGroupData.json データファイルに追加します
  3. APIRef マクロを使用して、表示したい各ページにサイドバーを挿入します

これらのステップを順番に実行しましょう。この記事で参照する例は、Fetch API です。

API リファレンスページの作成

サイドバーをページに追加する前に、ページ自体を作成する必要があります (詳細については、API リファレンスの必要なものガイドを参照してください)。

GroupData.json へのエントリの追加

GroupData.json ファイルには、API 参照サイドバーに表示されるリンクに関するすべてのデータが格納されます。呼び出されると、APIRef マクロはパラメータとして与えられた API 名を取り、GroupData.json でその名前を検索し、適切なサイドバーを作成してページに挿入します。

GroupData.json に項目を追加するには、以下を行う必要があります。

  1. GitHub アカウントを持っていることを確認します
  2. KumaScript リポジトリをフォークし、新しいブランチを作成して変更を保存し、リポジトリをローカルにクローンします
  3. 作業を開始する前に新しいブランチをチェックアウトし、作業が終わったら変更を押してください
  4. プルリクエストを作成して、MDN チームがあなたの作業をレビューし、必要に応じて変更を求めることができるようにします

GitHub の使用についてサポートが必要な場合は、互換性一覧表に詳細なガイドがあります。

GroupData.json ファイルは、KumaScript リポジトリの macros ディレクトリ内にあります。それを見ると、巨大な JSON 構造があり、それぞれの API に独自のメンバーがあります。名前は API 名で、値は作成するサイドバーリンクを定義するいくつかのサブメンバーを含むオブジェクトです。

たとえば、MDN の Fetch API ページを見てください。 GroupData.json の対応するエントリは次のようになります。

"Fetch API": {
    "overview":   [ "Fetch API"],
    "interfaces": [ "Body",
                    "Headers",
                    "Request",
                    "Response",
                    "FetchController",
                    "FetchObserver",
                    "FetchSignal",
                    "ObserverCallback" ],
    "methods":    [ "WindowOrWorkerGlobalScope.fetch()" ],
    "properties": [],
    "events":     []
},

ご覧のとおり、名前には "Fetch API" を使用し、オブジェクト値の内側には多数のサブメンバーを含めています。

GroupData エントリ内に含めるサブメンバ

このセクションでは、GroupData エントリに含めることができるすべてのサブメンバーを一覧表示します。

Note that most of the values included inside the listed sub-members equate to both the link text, and slugs appended to the end of the main API index page —  https://developer.mozilla.org/<language-code>/docs/Web/API — to create the final URL for the displayed link. So for example, "Body" will result in a link being created like so in the en-US locale:

<li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li>

There are a few exceptions. For example the "guides" sub-member contains one or more sets of link information (title and slug) that defines links to associated guides/tutorials. In this case the slugs are appended to the end of the MDN docs root — https://developer.mozilla.org/<language-code>/docs — allowing an article anywhere on MDN to be included.

Here are the available members. In each case, an example is included that assumes that the locale is en-US. These are all technically optional, but it is strongly encouraged that instead of omitting them, you include empty arrays.

  1. "overview" — the value is an array, inside of which you include the slug of the API overview page, if there is one. "Fetch API" results in a link being made to https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API.

  2. "interfaces" — the value is an array in which you should list all of the interfaces that form part of that API. "Body" results in a link being made to https://developer.mozilla.org/en-US/docs/Web/API/Body.

  3. "methods" — the value is an array that should contain any methods the spec adds to interfaces associated with other APIs, such as instantiation methods created on Navigator or Window. If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list. "WindowOrWorkerGlobalScope.fetch()" results in a link being made to https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch. Do not list methods that are members of interfaces that are members of interfaces that are owned by the same API.

  4. "properties" — the value is an array that should contain all of the properties associated with the API. This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces. If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list. "Headers.append" results in a link being made to https://developer.mozilla.org/en-US/docs/Web/API/Headers/append.

  5. "events" — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere. If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. "animationstart" results in a link being made to https://developer.mozilla.org/en-US/docs/Web/Events/animationstart.

  6. "guides" — the value is an array containing one or more objects that define links to guides explain how to use the API. Each object contains two sub-members — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link. As an example, the following object:

    { "url":   "/docs/Web/API/Detecting_device_orientation",
    "title": "Detecting device orientation" }

    Creates a link with the title "Detecting device orientation", which points to https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation.

  7. "dictionaries" — an array of strings listing all of the dictionaries which are part of the API. Generally, only dictionaries used by more than one property or method should be listed here, unless they are of special significance or are likely to require being referenced from multiple pages. "RTCConfiguration" results in a link to https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration.

  8. "types" — an array of typedefs and enumerated types defined by the API. You may choose to only list those that are of special importance or are referenced from multiple pages, in order to keep the list short. "RTCCodecType" creates a link to https://developer.mozilla.org/en-US/docs/Web/API/RTCCodecType.

  9. "callbacks" — the value is an array containing a list of all the defined callback types for the API. You may find it unnecessary to use this group at all, even on APIs that include callback types, as often they are not useful to document separately. An entry in this array containing the string "RTCSessionDescriptionCallback" results in a link being created to https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescriptionCallback.

サイドバーで使用されるタグ

一部のサブメンバーは、ページタグに基づいて子ページから自動的に検出されます。サイドバーがレンダリングされるたびにトップレベル API の下のページがクロールされ、メソッド ("メソッド" タグ)、プロパティ ("プロパティ" タグ)、およびコンストラクタ ("コンストラクタ" タグ) のエントリが自動的に作成されます。

サブメンバは、タグに基づいて警告アイコンで自動的に装飾されます。実験的 ("実験的" タグ)、非標準的 ("非標準" または "非標準" タグ)、廃止予定 ("非推奨" タグ)、廃止 ("廃止" タグ) のサブメンバー用に装飾が追加されます。

Further information about tag-based processing is available in the APIRef source.

サイドバーを挿入する

GroupData.json に API のエントリを追加してプルリクエストとして送信し、その変更をメインリポジトリに受け入れたら、APIRef マクロを使用して API リファレンスページに含めることができ、GroupData の API にパラメータとして使用されます。例として、WebVR API のサイドバーは、次のようにそのページに含まれています。

{{APIRef("WebVR API")}}