カスタムリスティング：アイテムスキーマ、制限、および例

カスタムリスティングは、小さなフィールドスキーマを共有する繰り返し可能なアイテムのコレクションです。各アイテムは、タイトル、簡潔なサマリー、1つまたは2つのメタデータ値、および宛先リンクを持つことができます。この構造により、箇条書きリスト よりも多くのコンテキストを読者に提供しつつ、すべてのアイテムを独立したプロダクトカード のように扱うことはありません。

例 — サポートされているエクスポート形式

• CSV — スプレッドシート分析用の表形式行。フラットレコードに最適。利用可否： 全プラン。アクション： CSVエクスポート設定を表示。
• JSON — アプリケーションおよびデータパイプライン向けのネストされたレコード。フィールド関係の保持に最適。利用可否： ProおよびEnterprise。アクション： JSONリファレンスを読む。
• Google Sheets — コードなしでデータをレビューするチーム向けの同期ワークシート。利用可否： ProおよびEnterprise。アクション： Google Sheetsに接続。

レンダリングされた要素は、これらの箇条書きの装飾的なバージョンであってはなりません。3つのアイテムを含む1つのコレクションを公開し、各アイテムが同じtitle、summary、bestFor、availability、およびurlフィールドを保持する必要があります。リスティングをカスタムにしているのは、フィールドモデルであり、境界線、アイコン、または列数ではありません。

この要素が重要な理由

通常の散文は繰り返しを隠します。6つの統合が6つの段落で説明されている場合、読者は各段落にシステム名、サポートされるアクション、アカウント要件、およびセットアップリンクが含まれていることを発見しなければなりません。カスタムリスティングは、1つのアイテムスキーマ（すべてのアイテムで使用される定義済みフィールドセット）を通じてこれらの繰り返し部分に名前を付けます。読者は最初のエントリの後にパターンを学習し、以降のエントリを予測可能にスキャンできます。

その一貫性は再利用性も向上させます。コンテンツ管理システムは必須フィールドを検証でき、テンプレートはページ固有のマークアップなしですべてのアイテムをレンダリングでき、下流のアプリケーションは同じソースをコンパクトなモバイルリストや検索可能なディレクトリに変換できます。検索エンジンやAIシステムは、あるエンティティがどこで終わり別のエンティティが始まるかを推測する必要なく、個別のアイテム境界を受け取ります。

この要素が重要なのは、2つの有効な構造の間に共通のギャップがあるためです。箇条書きは各アイテムが1つのコンパクトなステートメントである場合に機能します。カードは各アイテムに独立した画像、複数の商業的属性、顕著なアクション、または単独で成立するのに十分な視覚的な重みが必要な場合に機能します。多くのコレクションはどちらの極端も必要としません。統合リストには、名前、2文の機能サマリー、ステータス、およびリンクが必要な場合があります。それを箇条書きに平坦化するとフィールドが失われ、カードに拡張するとスペースを浪費し、リファレンスコレクションがプロモーション的に感じられます。

構造化は、すべてのコレクションを特注品にするための言い訳にはなりません。一回限りのデザインは、一貫性のないフィールド、順序、アクセシビリティ、およびレスポンシブ動作を生み出します。したがって、要素の記述ルール が最初に適用されます。繰り返される情報ニーズを特定し、それを満たす最小のスキーマを登録し、コンテンツをレンダラー間で移植可能に保ちます。

使用すべきタイミング

すべてのアイテムが同じ読者の質問に答え、各アイテムに2〜5つの可視フィールドが必要で、主なタスクがすべての値を横並びで比較するよりも検査またはナビゲートである場合に、カスタムリスティングを使用します。適切なコレクションには、統合、サービスエリア、サポートされている形式、リソースダウンロード、パートナータイプ、チーム責任、ディレクトリプレビュー、およびグループ化された機能が含まれます。

選択する前に4つのテストを実行します：

1. 繰り返し可能性： すべてのアイテムが例外を発明することなく同じ必須フィールドを使用できますか？
2. 独立性： 読者は前のアイテムを読まなくても1つのアイテムを理解できますか？
3. スキャン可能性： タイトルとサマリーのパターンは、比較可能な値のグリッドよりも有用ですか？
4. アクション： 各アイテムに必要なプライマリ宛先は1つだけですか？

答えが「はい」の場合、カスタムリスティングが適切である可能性が高いです。コレクションがこれらのテストのいずれかに不合格の場合、別の要素を使用します：

• アイテムに1つの並列文のみが必要で、個別のメタデータがない場合は箇条書きリストを使用します。
• 読者が代替案間で同じ基準を縦または横にスキャンする必要がある場合は、比較表 を使用します。
• 画像、価格、オファー、評価、利用可否、および購入アクションにより各アイテムが実質的な商業ユニットになる場合は、プロダクトカードを使用します。
• 位置が編集上の順序付けではなく順序を表現する場合は、ステップリストを使用します。
• 各エントリが基本的に用語と定義のペアである場合は、用語集または定義パターンを使用します。
• アイテムに異なるフィールドが必要な場合、またはそれぞれ約100語以上の説明が必要な場合は、見出しと散文を使用します。

デザインが繰り返しボックスを求めているという理由だけでカスタムリスティングを選択しないでください。まず安定したコンテンツモデルが存在することを証明してください。アイテム1に価格があり、アイテム2に著者経歴があり、アイテム3にダウンロードサイズがある場合、CSSで整列できたとしても、それらは1つのコレクションではありません。

配置場所

ページがコレクションとその包含ルールを定義した後にリスティングを配置します。「サポートされている統合」はラベルです。「これらの統合は、監査済みページを所有するレポートワークスペースに送信できます」は、メンバーシップの意味を読者に伝えます。選択またはテストがセットを作成した場合は、最初のアイテムの前にその方法を説明し、リスティングがサポートされていない完全性やランキングを暗示しないようにします。

コレクションを、それが提供する決定またはナビゲーションタスクの近くに配置します。統合ページは、サポートされているワークフローをリストする前に、接続とその結果を紹介する必要があります。ディレクトリは、エントリを表示する前にスコープとフィルターを説明する必要があります。リスティクルは、選択したアイテムを提示する前に評価方法を明記する必要があります。

リスティングを散文、広告、コールトゥアクション、または無関係なスクリーンショットで中断してはいけません。アイテム境界は連続している必要があります。条件は、影響を受けるアイテムの定義されたメタデータ内に配置するか、リスト全体の前または後にコレクション全体の条件を説明します。12個を超えるアイテムが必要な場合は、意味のある小見出しの下にグループ化するか、フィルタリングを追加するか、読者をディレクトリインデックス に誘導します。無限に続く視覚的なスタックを作成しないでください。

構成

完全なカスタムリスティングには以下の領域があります：

1. コレクションタイトル： コンポーネントの内部名ではなく、読者の言語でセットに名前を付けます。
2. スコープステートメント： 何が含まれる資格があるか、およびコレクションが完全か、選択済みか、例示的かを定義します。
3. リストコンテナ： 1つのセマンティックコレクションを確立し、アイテム数を管理します。
4. アイテムタイトル： エンティティ、リソース、機能、またはオプションを一意に識別します。
5. アイテムサマリー： 1〜2文でアイテムの関連する違いや使用法を説明します。
6. メタデータグループ： 登録されたスキーマから0〜3個のラベル付きの事実を公開します。
7. プライマリアクション： 説明的なアンカーテキストを使用して1つの明確な宛先にリンクします。
8. アイテム境界： アイテムをコレクションから切り離すことなく、間隔、区切り線、または控えめなサーフェス処理を使用します。

スコープステートメントは、一般的な正確性の失敗を防ぎます。「利用可能な統合」は完全性を暗示します。「一般的なレポート統合」は選択を宣言します。作成者はソースデータがサポートできる文言を選択する必要があります。

デザイン例

レンダラーは密度を変えても構いませんが、フィールド順序、セマンティックリスト構造、および予測可能な読み取り順序を維持する必要があります。

積み重ねられた編集用リスティング

サマリーがほとんどの価値を提供する場合は、デフォルトの積み重ねデザインを使用します。タイトルを最初に、サマリーを2番目に、メタデータを3番目に、アクションを最後に配置します。控えめな区切り線で十分です。各アイテムに浮き上がったカードは必要ありません。

コンパクトなディレクトリプレビュー

タイトルと1つのメタデータ値で読者が宛先を選択できる場合は、コンパクトバリアントを使用します。サマリーは短くても構いませんが、ラベルは表示されたままにしておく必要があります。説明のない色付きドットで意味のあるステータスを置き換えてはいけません。

グループ化されたリスティング

1つの安定した分類で8〜24個のアイテムのコレクションをセクションに減らせる場合は、グループを使用します。グループ見出しは、エクスポートタイプやサービス地域などの真の分類法を記述する必要があります。単に等しい列を達成するためにグループ化してはいけません。

狭いビューポート

狭い幅では、ソース順序を維持し、メタデータをサマリーの下に積み重ねます。関連性を保つフィールドを非表示にしたり、列を維持するためにテキストを縮小したり、アクションをアイテムから移動したりしてはいけません。

パラメータ

以下のスキーマは意図的に制約されています。フィールドは、1つのアイテムにたまたまデータがあるからではなく、コレクション全体で有用な場合にのみコンポーネントの一部になります。

3アイテムが最小なのは、ペアは通常、散文、2列比較、または2つの実質的なカードとしてより明確だからです。12が通常の最大値なのは、長いフィルタリングされていないスタックのスキャンが非効率になるからです。グループ化された場合の上限24はガードレールであり、目標ではありません。より大きな、または頻繁に変更されるセットには、ディレクトリ、検索、ページネーション、またはデータ駆動型アプリケーションが必要です。

ordered=trueは、表示順序が宣言されたランキングを表現する場合にのみ選択します。編集上の都合、アルファベット順、またはデータソースの順序はランクを作成しません。ランキングが実際にある場合は、方法論を明記し、表示出力と構造化データの両方で位置を保持します。

構文とコード例

ポータブルディレクティブは、作成者の契約を定義します。プラットフォームアダプターはデータを異なる方法で保存しても構いませんが、同じフィールド名、アイテム順序、オプション性、および表示出力を維持する必要があります。

ポータブルマークダウンディレクティブ

:::custom-listing{title="Export formats" variant=stacked}
These are the formats available for sending completed audit records to another workspace.

:::item{id=csv title="CSV" url="/docs/exports/csv/"}
Tabular rows for spreadsheet analysis and flat-file ingestion.

- Best for: Spreadsheet analysis
- Availability: All plans
- Action: View CSV export setup
:::

:::item{id=json title="JSON" url="/docs/exports/json/"}
Nested records that preserve relationships for applications and data pipelines.

- Best for: Automated workflows
- Availability: Pro and Enterprise
- Action: Read the JSON reference
:::

:::item{id=sheets title="Google Sheets" url="/docs/exports/google-sheets/"}
A synchronized worksheet for teams that review data without code.

- Best for: Shared review
- Availability: Pro and Enterprise
- Action: Connect Google Sheets
:::
:::

例のURLはポータブル構文のみを説明しています。実装ではこれらを検証済みの宛先に置き換える必要があります。コードブロックに表示されているという理由だけで、例のパスをライブリンクとして公開してはいけません。

Hugoアダプター

{{< custom-listing title="Export formats" variant="stacked" >}}
  {{< custom-listing-item id="csv" title="CSV" url="/docs/exports/csv/" action-label="View CSV export setup" >}}
  Tabular rows for spreadsheet analysis and flat-file ingestion.

  **Best for:** Spreadsheet analysis  
  **Availability:** All plans
  {{< /custom-listing-item >}}
{{< /custom-listing >}}

この表記は将来の、またはプロジェクトレベルのアダプターを指定します。ページローカルのショートコードを作成することを許可するものではありません。すべてのパラメータは名前付きです。アダプターが存在するまでは、フィールド関係を静かに破棄するのではなく、コレクションを<ul>および<li>を使用したセマンティックHTMLとして、またはネイティブマークダウンとしてレンダリングします。

WordPressブロック

<!-- wp:amicited/custom-listing {"title":"Export formats","variant":"stacked"} -->
<ul class="custom-listing">
  <li data-item-id="csv">
    <h3>CSV</h3>
    <p>Tabular rows for spreadsheet analysis and flat-file ingestion.</p>
    <dl><dt>Best for</dt><dd>Spreadsheet analysis</dd><dt>Availability</dt><dd>All plans</dd></dl>
    <a href="/docs/exports/csv/">View CSV export setup</a>
  </li>
</ul>
<!-- /wp:amicited/custom-listing -->

ネイティブブロックは、1つのリスト、エントリごとに1つのリストアイテム、実際の見出し、ラベル付きメタデータの定義リスト、および説明的リンクを生成する場合に許容可能なフォールバックです。一般的なColumnsブロックは、ソース順序とアイテムグループ化がモバイルでしばしば壊れるため、信頼できる代替にはなりません。

例

良い例：一貫したリソースリスティング

移行リソース

これらのリソースは、サイト移行を準備、実行、および検証するチームをサポートします。

1. リダイレクトマッピングワークシート — 各古いURL、その承認済み宛先、所有者、および検証ステータスを記録します。形式： スプレッドシート。段階： 計画。アクション： リダイレクトワークシートをダウンロード。
2. ローンチ日検証スクリプト — 移行されたURLセットのレスポンスコード、リダイレクトチェーン、カノニカルターゲット、およびインデックス可能性をチェックします。形式： スクリプト。段階： ローンチ。アクション： 検証設定を確認。
3. ローンチ後モニタリングビュー — デプロイ後のクロール失敗と予期しないトラフィック変更を追跡します。形式： ダッシュボード。段階： モニタリング。アクション： モニタリングビューを設定。

これは、各アイテムが同じ5つのフィールド（タイトル、サマリー、形式、段階、アクション）を使用しているため機能します。スコープはリソースがなぜ一緒に属するかを説明します。番号付けは宣言された移行段階を反映しており、最初のリソースが「最良」であるという主張ではありません。各アクションは「もっと学ぶ」を繰り返す代わりに、その宛先を特定します。

悪い例：共有モデルなしのボックス

役立つもの

• SEOチェックリスト — 私たちのおすすめガイド。最近更新。もっと詳しく。
• プレミアム監査 — €499、通話とレポート付き。星5つ。今すぐ購入。
• Viktor — ブラチスラバ拠点のテクニカルリード、火曜日対応可能。
• APIドキュメント — 認証、制限、エラー、例、SDK、変更ログ、ステータス、サポート、および20以上のトピック。

これはビジュアルデザインが始まる前に失敗しています。セットはリソース、サービス、人物、およびドキュメントエリアを混在させています。フィールドはアイテムごとに変わり、「最近」には日付がなく、評価にはソースとスケールが欠けており、アイテムの深さは断片からセクションの概要まで幅があります。目的別にコンテンツを分割し、各コレクションに登録された要素を選択します。一貫性のないデータの周りの境界線は、カスタムリスティングを作り出しません。

悪い例：テーブルにすべきリスティング

6つのプランがあり、それぞれに月額料金、年額料金、ユーザー制限、ストレージ、サポート応答時間、SSO利用可否が表示されているとします。読者はすべてのプラン間で同じ6つの値を比較する必要があります。リスティングでは、プラン6までスクロールしている間、プラン1を覚えておく必要があります。タスクがアイテム間の評価であるため、比較表を使用します。各プランにポジショニングステートメントと購入アクションも必要な場合は、それらを表の外側または横に、ページの登録されたプランコンポーネントを使用して配置します。2つのソースで競合する値を複製してはいけません。

スキーママークアップとアクセシビリティ

コレクションをネイティブリストセマンティクスでレンダリングします。アイテム順序に意味がない場合は<ul>を使用し、ページが実際の順序またはランキングを宣言する場合は<ol>を使用します。すべてのエントリは1つの<li>に属します。その中で、正しいドキュメントレベルの実際の見出し、サマリー用の段落、およびラベル付きメタデータ用の<dl>、<dt>、<dd>を使用します。スクリーンリーダーは、説明、事実、およびアクションの前にアイテムタイトルに遭遇する必要があります。

アイテム全体を、別のコントロールや複数のテキスト領域を含む場合に特大のリンクにしてはいけません。プライマリリンクには「CSVエクスポート設定を表示」のような説明的なラベルを付けます。ストレッチリンクパターンを使用する場合、そのフォーカスインジケーターは表示されたままで、アクセシブル名は依然として宛先を説明する必要があります。アイコンは、テキストにまだ存在しない情報を伝える場合にのみ代替テキストが必要です。装飾的なアイコンは支援技術から隠す必要があります。

視覚的な順序とソースの順序は一致している必要があります。マルチカラムのデスクトップレイアウトは、アイテム1、アイテム3、アイテム5、次にアイテム2という読み取り順序にならずに折りたたむ必要があります。繰り返される値が視覚的に整列しているという理由だけでメタデータラベルが消えてはいけません。「Enterprise」だけでは、非視覚的な読者にそれが利用可否、オーディエンス、またはサポートのいずれを説明しているかがわかりません。

ItemList構造化データはオプションであり、デフォルトのスタイリングフックではありません。表示されるコレクションが意味のある有限のリストであり、ページがそのコレクションを特定することで利益を得る場合に使用します。表示されるすべてのエントリをitemListElementにマッピングします。実際の順序付きリストの場合にのみpositionを含め、名前、URL、および数がレンダリングされたコンテンツと一致することを確認します。ナビゲーションメニュー、任意の機能ティーザー、または部分的なセットを完全なランク付きリストであるかのようにマークアップしてはいけません。エントリが組織やソフトウェアアプリケーションなどの識別可能なエンティティである場合、ページが必要なIDデータを提供および検証する場合にのみ、最も具体的な該当タイプを使用します。

記述ルール

1. メンバーを提示する前にメンバーシップを説明します。 読者は、セットが完全か、選択済みか、スポンサー付きか、ランク付けされているか、例示的かを、欠落や順序を解釈する前に知る必要があります。スコープ文に包含ルールを記載します。
2. アイテムを起草する前に1つのアイテムスキーマを定義します。 一貫したフィールドにより、読者は1つのスキャンパターンを学習でき、検証は欠落コンテンツを捕捉できます。作成者がコレクションを入力する前に、必須フィールドとオプションフィールドを登録します。
3. 必須フィールドは真に普遍的であることを保ちます。 作成者がエントリの半数で「該当なし」と入力する名目上の必須フィールドは、間違ったフィールドであるか、コレクションに異なるアイテムタイプが含まれている証拠です。
4. 可視メタデータを3ペアに制限します。 より多くのフィールドはタスクを比較に移行させ、各行をスキャンしにくくします。二次的な事実は宛先ページに移動するか、テーブルを使用します。
5. 繰り返しではなく差異のためにサマリーを書きます。 タイトルはすでにアイテムに名前を付けています。サマリーを使用して、その関連する機能、オーディエンス、制限、または役割を説明します。
6. 並列的なラベルと単位を使用します。 同じ概念に対して「プラン」「利用可能なプラン」「ティア」を交互に使用してはいけません。レンダリングする前に日付、通貨、単位、ステータス用語を正規化します。
7. 各アイテムに1つのプライマリアクションを与えます。 競合するボタンはリファレンスリストをカードグリッドに変え、意図された次のステップを不明瞭にします。二次的な宛先は詳細ページに配置します。
8. 意味のある順序を宣言します。 アルファベット順、時系列順、ランク順、編集順、およびソースシステム順は異なる期待を生み出します。解釈に影響を与える可能性がある場合は順序を明記します。
9. 最小数と最大数を設定します。 通常は3〜12アイテムを使用し、有用なグループの場合にのみ最大24まで許可します。コレクションがこれらの境界を超える場合はパターンを切り替えます。
10. 単一の真実のソースを維持します。 価格、ステータス、利用可否、またはその他の変動するフィールドが他の場所に表示される場合、すべての表現を同じ所有ソースから入力し、必要に応じて検証日を公開します。

使用する投稿タイプ

• リスティクルガイド は、各選択エントリに同じサマリー、適合性、制限、および遷移リンクが必要だが、密集した比較マトリックスは必要ない場合にカスタムリスティングを使用します。
• Best-X-for-Yページ は、評価方法を説明した後、オーディエンス固有の推奨事項にそれを使用する場合があります。ランキングは視覚的な順序によって暗示されるのではなく、明示的である必要があります。
• Alternatives-to-Xページ は、より狭い比較の前に、一貫した「最適な用途」、トレードオフ、および詳細リンクフィールドで代替オプションを提示できます。
• カテゴリページ は、フィルタリングがまだ必要でない場合に、管理可能な子製品またはサービスのセットをプレビューするためにコンパクトまたはグループ化されたリスティングを使用します。
• ディレクトリインデックスは、プレビューまたは小規模で安定したディレクトリにのみこの要素を使用します。大規模なエンティティセットには、検索、フィルター、ページネーション、およびデータバックアップされたディレクトリインターフェースが必要です。
• 会社プロフィール は、すべてのエントリが同じフィールドを共有する場合に、検証済みの事業部門、認定資格、または拠点をリストできます。
• ベンダープロフィール は、プロフィールを製品グリッドに変えることなく、サポートされているサービス、地域、または契約モデルをリストできます。
• 統合ページ は、予測可能な機能と要件のスキーマを使用して、サポートされているワークフロー、データオブジェクト、トリガー、または宛先をリストできます。

コレクションの存在はこの要素を必要としません。カスタムフィールドモデルが検索またはナビゲーションを改善する場合にのみ使用します。前提条件の短いセットは依然として箇条書きに属し、機能のマトリックスは依然としてテーブルに属します。

QAチェックリスト

• コレクションにタイトルと包含を定義するスコープ文がある。
• すべてのアイテムが同じ種類のエンティティ、リソース、機能、またはオプションを表している。
• 必須フィールドとオプションフィールドがコンテンツ入力前に文書化されている。
• すべてのアイテムに一意の安定したID、タイトル、および12〜60語のサマリーがある。
• 登録されたスキーマにないフィールドをアイテムが発明していない。
• コレクションに3〜12アイテム、または正当なグループで合計24以下が含まれている。
• アイテムに3つ以下の可視メタデータペアと1つのプライマリアクションがある。
• ラベル、単位、ステータス、日付、アクションの文言が一貫している。
• 順序がランキング、時系列、または優先順位を暗示する場合に宣言されている。
• アイテム間の比較が主なタスクである場合、代わりにテーブルが選択されている。
• 出力が1つのセマンティック<ul>または<ol>と、アイテムごとに1つの<li>を使用している。
• 見出しがページ階層に従い、メタデータが用語と説明のセマンティクスを使用している。
• キーボードフォーカスが可視であり、リンクがその宛先を説明している。
• ソース順序がデスクトップとモバイルの幅で視覚的順序と一致している。
• ItemListマークアップが存在する場合、表示されるアイテム、順序、数、名前、URLと一致している。
• 変動する値が所有ソースから取得され、適切な検証日が含まれている。

FAQ

以下の質問は、カスタムリスティング が箇条書き、カード、またはテーブルに陥る原因となる最も一般的な境界を解決します。

カスタムリスティングとは何ですか？

カスタムリスティングは、タイトル、サマリー、メタデータ、リンクなどの小さな名前付きフィールドスキーマをアイテム間で共有する繰り返し可能なコレクションです。シンプルな箇条書きリストと視覚的に独立したカードグリッドの中間に位置します。

カスタムリスティングはいくつのアイテムを含むべきですか？

通常の編集範囲として3〜12個のアイテムを使用します。2個のアイテムは通常、散文または横並びのコンポーネントが必要です。12個を超える場合は有用なグループ化、フィルタリング、ページネーション、またはディレクトリパターンが必要です。グループ化バリアントは24アイテムを超えてはいけません。

カスタムリスティングはいつテーブルになるべきですか？

読者が同じ3つ以上のフィールド（特に数値、日付、ステータス、またはyes/noの機能）でほとんどのアイテムを比較する必要がある場合はテーブルを使用します。サマリーと遷移リンクがアイテム間の比較よりも重要な場合はリスティングを維持します。

カスタムリスティングにはItemListスキーマが必要ですか？

いいえ。コレクションが意味があり有限で、マークアップされたすべてのアイテムが可視であり、位置が宣言された順序を反映している場合にのみItemListを追加します。通常のナビゲーション、ティーザー、および関連コンテンツのリスティングは、特別なスキーマではなくセマンティックHTMLを必要とすることがほとんどです。

アイテムごとに異なるフィールドを持つことはできますか？

共有スキーマで定義されたオプションフィールドのみが欠落する可能性があります。作成者がアイテムごとにフィールドを発明することを許可してはいけません。複数のアイテムに異なる情報モデルが必要な場合は、それらを別のリスティングに分割するか、より適切な要素を選択します。