diff --git a/docs/angular/src/content/en/images/anatomy-content-light/virtual-scroll-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/virtual-scroll-lt-a.png new file mode 100644 index 0000000000..5aa26700cb Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/virtual-scroll-lt-a.png differ diff --git a/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do-not.png b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do-not.png new file mode 100644 index 0000000000..2c0aefe334 Binary files /dev/null and b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do-not.png differ diff --git a/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do.png b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do.png new file mode 100644 index 0000000000..79dec6a823 Binary files /dev/null and b/docs/angular/src/content/en/images/virtual-scroll/virtual-scroll-do.png differ diff --git a/docs/angular/src/content/jp/images/anatomy-content-light/virtual-scroll-lt-a.png b/docs/angular/src/content/jp/images/anatomy-content-light/virtual-scroll-lt-a.png new file mode 100644 index 0000000000..5aa26700cb Binary files /dev/null and b/docs/angular/src/content/jp/images/anatomy-content-light/virtual-scroll-lt-a.png differ diff --git a/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do-not.png b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do-not.png new file mode 100644 index 0000000000..2c0aefe334 Binary files /dev/null and b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do-not.png differ diff --git a/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do.png b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do.png new file mode 100644 index 0000000000..79dec6a823 Binary files /dev/null and b/docs/angular/src/content/jp/images/virtual-scroll/virtual-scroll-do.png differ diff --git a/docs/xplat/src/assets/images/anatomy-content-light/virtual-scroll-lt-a.png b/docs/xplat/src/assets/images/anatomy-content-light/virtual-scroll-lt-a.png new file mode 100644 index 0000000000..5aa26700cb Binary files /dev/null and b/docs/xplat/src/assets/images/anatomy-content-light/virtual-scroll-lt-a.png differ diff --git a/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do-not.png b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do-not.png new file mode 100644 index 0000000000..2c0aefe334 Binary files /dev/null and b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do-not.png differ diff --git a/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do.png b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do.png new file mode 100644 index 0000000000..79dec6a823 Binary files /dev/null and b/docs/xplat/src/assets/images/virtual-scroll/virtual-scroll-do.png differ diff --git a/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx b/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx index 8ffc42f3d3..07991e57d1 100644 --- a/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx +++ b/docs/xplat/src/content/en/components/layouts/virtual-scroll.mdx @@ -2,19 +2,23 @@ title: "Virtual Scroll" description: "The Virtual Scroll is a component that renders only the items in its viewport plus a small buffer, so large lists scroll smoothly." keywords: "{Platform} Virtual Scroll, virtualization, virtual list, large lists, infinite scroll, remote data, {ProductName}" -last_updated: "2026-09-17" +last_updated: "2026-09-25" license: MIT mentionedTypes: ["VirtualScroll"] -relatedComponents: ["List", "Card"] +relatedComponents: ["List", "Grid", "Card"] llms: description: "The {ProductName} Virtual Scroll is a component that renders large lists by keeping only the items in its viewport, plus a configurable buffer, in the DOM." --- -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import virtualScrollAnatomy from '@xplat-images/anatomy-content-light/virtual-scroll-lt-a.png'; +import virtualScrollDo from '@xplat-images/virtual-scroll/virtual-scroll-do.png'; +import virtualScrollDoNot from '@xplat-images/virtual-scroll/virtual-scroll-do-not.png'; # Virtual Scroll Component @@ -38,7 +42,29 @@ The {ProductName} Virtual Scroll is a component that renders large lists by keep The {Platform} Virtual Scroll renders the visible items plus a configurable buffer, and its track preserves the scroll range of the whole collection. -{/*TODO: add the Virtual Scroll anatomy image and render it with the component.*/} + + + + +1. Host: The scroll container. Its fixed height (width when horizontal) sets how many items are visible.
+2. Track: A spacer sized to the estimated length of the whole collection, so the scrollbar spans every item.
+3. Content element: Holds only the rendered items. It starts at the first rendered buffer item, above the viewport, and takes its size from the rendered items.
+4. Item wrapper: One per rendered item. It hosts the item template and is the box that gets measured.
+5. Over-scan buffer: The overScan items (2 by default) rendered past each edge of the viewport. @@ -115,7 +141,7 @@ virtualScroll.data = Array.from({ length: 100_000 }, (_, i) => ({ name: `Item ${ -The Virtual Scroll host needs a fixed height for vertical scrolling or a fixed width for horizontal scrolling. A host that grows with its content has no viewport to fill. +The Virtual Scroll host needs a fixed height for vertical scrolling or a fixed width for horizontal scrolling. A host that grows with its content renders every item, so the list is not virtualized. ### Prerequisites and Version Compatibility @@ -151,7 +177,7 @@ Mark an `ng-template` with `igxVirtualItem`, or pass a template defined elsewher ```html - + @@ -424,13 +450,11 @@ await virtualScroll.layoutComplete; ### Do/Don't -{/*TODO: add the Virtual Scroll Do/Don't guidance image from Indigo.Design when it is available.*/} - **When to use:** Use the Virtual Scroll for a long list that is too large to render at once, such as a directory, a feed, a log, or a strip of cards, including lists that load remote data while scrolling. -**When not to use:** Render a short list directly with the [List](../list.mdx) and `@for`. Use the [Grid](../grid/grid.mdx) for tabular data with columns, sorting, or filtering. Show a small set of rich items as [Card](../card.mdx) elements without virtualization. +**When not to use:** Render a short list directly with the [List](../list.mdx) and `@for`. Use the [{Platform} Data Grid](../grid/grid.mdx) for tabular data with columns, sorting, or filtering. Show a small set of rich items as [Card](../card.mdx) elements without virtualization. @@ -438,16 +462,26 @@ await virtualScroll.layoutComplete; **When to use:** Use the Virtual Scroll for a long list that is too large to render at once, such as a directory, a feed, a log, or a strip of cards, including lists that load remote data while scrolling. -**When not to use:** Render a short list directly with the [List](../grids/list.mdx). Show a small set of rich items as [Card](./card.mdx) elements without virtualization. +**When not to use:** Render a short list directly with the [List](../grids/list.mdx). Use the [{Platform} Data Grid](../grids/data-grid.mdx) for tabular data with columns, sorting, or filtering. Show a small set of rich items as [Card](./card.mdx) elements without virtualization. -| Do | Don't | -| --- | --- | -| Give the host a fixed height (vertical) or width (horizontal). | Let the host grow with its content. | -| Set `estimatedItemSize` close to the average item size. | Keep the 50px default for much larger or smaller items. | -| Assign a new array when the collection changes. | Change the bound array in place. | -| Space items with padding or `gap`. | Space items with margins. | +
+ + + + + + + + + + + + + +
DoDon't
{Platform} Virtual Scroll showing a list of 100,000 employees{Platform} Virtual Scroll used for a list of only five employees
+
## Properties @@ -562,6 +596,7 @@ The host has no `tabindex`. Browsers differ in whether a scroll container withou - The host has `role="list"`; the track, the content element, and the item wrappers have `role="presentation"`. Items that render `role="listitem"`, such as `igx-list-item`, are exposed as items of that list. +- Inside a container that already provides list semantics, such as `igx-list`, set `role="presentation"` on the host so that the items are not nested in a second list. - Map the `index` and `count` template variables to `aria-posinset` and `aria-setsize`. - Give a focusable host an accessible name with `aria-label` or `aria-labelledby`. @@ -628,7 +663,7 @@ The Virtual Scroll measures items at runtime and creates its own scroll containe | `igxForScrollContainer` | Not needed: the host is the scroll container | | `scrollTo(index)` | `scrollToIndex(index, options)`, which returns a promise | | `chunkLoad`, `chunkPreload` | `stateChange` | -| `igxForRemote` with `totalItemCount` | `dataWindow` with `totalCount`, or `data` with `dataRequest` for append-only loading | +| `igxForTotalItemCount` for remote data | `dataWindow` with `totalCount`, or `data` with `dataRequest` for append-only loading | | `index`, `count`, `first`, `last`, `even`, `odd` | The same template variables | The grids keep their own row and column virtualization; see [Grid Virtualization](../grid/virtualization.mdx). @@ -674,6 +709,7 @@ The {Platform} Virtual Scroll has no dependencies on other components and needs - [List](../list.mdx) - Use the List for a short list, or as the container of a virtualized list. +- [Data Grid](../grid/grid.mdx) - Use the Data Grid for tabular data with columns, sorting, or filtering. - [Card](../card.mdx) - Use cards for a small set of rich items, or as items of a horizontal Virtual Scroll. - [Virtual ForOf Directive](../for-of.mdx) - The directive-based virtualization used by existing lists. @@ -682,6 +718,7 @@ The {Platform} Virtual Scroll has no dependencies on other components and needs - [List](../grids/list.mdx) - Use the List for a short list, or as the container of a virtualized list. +- [Data Grid](../grids/data-grid.mdx) - Use the Data Grid for tabular data with columns, sorting, or filtering. - [Card](./card.mdx) - Use cards for a small set of rich items, or as items of a horizontal Virtual Scroll. diff --git a/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx b/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx index b5dbdd5708..90b5b70452 100644 --- a/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx +++ b/docs/xplat/src/content/jp/components/layouts/virtual-scroll.mdx @@ -1,25 +1,29 @@ --- title: "Virtual Scroll" description: "Virtual Scroll は、ビューポート内のアイテムと少量のバッファーのみをレンダリングするコンポーネントであり、大量のリストでもスムーズにスクロールできます。" -keywords: "{Platform} Virtual Scroll, virtualization, virtual list, large lists, infinite scroll, remote data, {ProductName}" -last_updated: "2026-09-17" +keywords: "{Platform} Virtual Scroll, virtualization, virtual list, large lists, infinite scroll, remote data, {ProductName}, 仮想スクロール, 仮想化, 仮想リスト, 大量リスト, 無限スクロール, リモート データ" +last_updated: "2026-09-25" license: MIT mentionedTypes: ["VirtualScroll"] -relatedComponents: ["List", "Card"] +relatedComponents: ["List", "Grid", "Card"] _language: ja llms: description: "{ProductName} Virtual Scroll は、ビューポート内のアイテムと設定可能なバッファーのみを DOM 内に保持することで、大量のリストをレンダリングするコンポーネントです。" --- -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import virtualScrollAnatomy from '@xplat-images/anatomy-content-light/virtual-scroll-lt-a.png'; +import virtualScrollDo from '@xplat-images/virtual-scroll/virtual-scroll-do.png'; +import virtualScrollDoNot from '@xplat-images/virtual-scroll/virtual-scroll-do-not.png'; # Virtual Scroll コンポーネント -{ProductName} Virtual Scroll は、ビューポート内のアイテムと設定可能なバッファーのみを DOM 内に保持することで、大量のリストをレンダリングするコンポーネントです。スクロールバーはコレクション全体に及ぶため、10 万件のアイテムを持つ仮想リストでも通常のリストと同じようにスクロールできます。 +{ProductName} Virtual Scroll は、ビューポート内のアイテムと設定可能なバッファーのみを DOM 内に保持することで、大量のリストをレンダリングするコンポーネントです。スクロールバーは常にコレクション全体の範囲を表すため、10 万件のアイテムを持つ仮想リストでも通常のリストと同じようにスクロールできます。 ## ライブ デモ @@ -39,7 +43,29 @@ import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; {Platform} Virtual Scroll は、表示されているアイテムと設定可能なバッファーをレンダリングし、そのトラックはコレクション全体のスクロール範囲を保持します。 -{/*TODO: add the Virtual Scroll anatomy image and render it with the component.*/} + + + + +1. ホスト: スクロール コンテナーです。固定の高さ (水平の場合は幅) によって、表示されるアイテムの数が決まります。
+2. トラック: コレクション全体の推定される長さに合わせてサイズが設定されるスペーサーです。これにより、スクロールバーがすべてのアイテムに及びます。
+3. コンテンツ要素: レンダリングされたアイテムのみを保持します。ビューポートの上にある、最初にレンダリングされたバッファー アイテムから始まり、そのサイズはレンダリングされたアイテムによって決まります。
+4. アイテム ラッパー: レンダリングされたアイテムごとに 1 つ存在し、アイテム テンプレートをホストします。サイズが測定されるのはこのボックスです。
+5. オーバー スキャン バッファー: ビューポートの各端を超えてレンダリングされる overScan 個のアイテム (デフォルトは 2) です。 @@ -116,7 +142,7 @@ virtualScroll.data = Array.from({ length: 100_000 }, (_, i) => ({ name: `Item ${ -Virtual Scroll のホストには、垂直スクロールの場合は固定の高さ、水平スクロールの場合は固定の幅が必要です。コンテンツに合わせてサイズが拡大するホストには、埋めるべきビューポートがありません。 +Virtual Scroll のホストには、垂直スクロールの場合は固定の高さ、水平スクロールの場合は固定の幅が必要です。コンテンツに合わせてサイズが拡大するホストはすべてのアイテムをレンダリングするため、リストは仮想化されません。 ### 前提条件とバージョン互換性 @@ -144,15 +170,15 @@ Virtual Scroll のホストには、垂直スクロールの場合は固定の ### アイテム テンプレート -Virtual Scroll のアイテム テンプレートは、アイテムとコレクション全体におけるその位置を受け取ります。位置に依存するコンテンツ（交互のスタイルや `aria-posinset`、`aria-setsize` など）には、インデックスと合計件数を使用します。 +Virtual Scroll のアイテム テンプレートは、アイテムとコレクション全体におけるその位置を受け取ります。位置に依存するコンテンツ (交互のスタイルや `aria-posinset`、`aria-setsize` など) には、インデックスと合計件数を使用します。 -`ng-template` に `igxVirtualItem` を付与するか、 を通じて他の場所で定義されたテンプレートを渡します（こちらが優先されます）。テンプレートのコンテキストは `$implicit`（アイテム）、`index`、`count`、`first`、`last`、`even`、`odd` を提供します。 +`ng-template` に `igxVirtualItem` を付与するか、 を通じて他の場所で定義されたテンプレートを渡します (こちらが優先されます)。テンプレートのコンテキストは `$implicit` (アイテム)、`index`、`count`、`first`、`last`、`even`、`odd` を提供します。 ```html - + @@ -168,7 +194,7 @@ Virtual Scroll のアイテム テンプレートは、アイテムとコレク - に、Lit テンプレートを返す関数を設定します。この関数は、`value`（アイテム）、`index`、`count`、`isFirst`、`isLast` を持つ `VirtualScrollItemContext` を受け取ります。アイテム テンプレートがない場合、コンポーネントは何もレンダリングしません。 + に、Lit テンプレートを返す関数を設定します。この関数は、`value` (アイテム)、`index`、`count`、`isFirst`、`isLast` を持つ `VirtualScrollItemContext` を受け取ります。アイテム テンプレートがない場合、コンポーネントは何もレンダリングしません。 ```ts virtualScroll.itemTemplate = (ctx: VirtualScrollItemContext) => html` @@ -202,11 +228,11 @@ virtualScroll.data = [...virtualScroll.data, newEmployee]; -`data` が変更されると、コンポーネントは最初に変更されたインデックスより前のアイテムの測定済みサイズを保持し、それ以降のアイテムはレンダリング時に再度測定します。追加操作ではすべての既存の測定値が保持されますが、置換、フィルタリング、並べ替えでは最初に変更されたアイテム以降の測定値が破棄されます。 +`data` が変更されると、コンポーネントは最初に変更されたインデックスより前のアイテムの測定済みサイズを保持し、それ以降のアイテムはレンダリング時に再度測定します。追加操作ではすべての既存の測定値が保持されますが、置換、フィルタリング、ソートでは最初に変更されたアイテム以降の測定値が破棄されます。 ### 推定アイテム サイズ -Virtual Scroll の は、アイテムがレンダリングされて測定されるまでのピクセル単位のサイズです（デフォルトは `50`）。アイテムは異なるサイズを持つことができ、測定されたサイズがそれぞれ推定値を置き換えます。アイテムが測定される前にスクロールバーと `scrollToIndex` を正確に保つため、推定値はアイテムの平均サイズに近い値に設定してください。 +Virtual Scroll の は、アイテムがレンダリングされて測定されるまでのピクセル単位のサイズです (デフォルトは `50`)。アイテムは異なるサイズを持つことができ、測定されたサイズがそれぞれ推定値を置き換えます。アイテムが測定される前にスクロールバーと `scrollToIndex` を正確に保つため、推定値はアイテムの平均サイズに近い値に設定してください。 @@ -232,7 +258,7 @@ Virtual Scroll の は、スクロール軸を `vertical`（デフォルト）または `horizontal` に設定します。水平リストでは、各アイテムに幅を、ホストに高さを設定してください。右から左のコンテキストでは、水平スクロールとアイテムの配置が反転します。 +Virtual Scroll の は、スクロール軸を `vertical` (デフォルト) または `horizontal` に設定します。水平リストでは、各アイテムに幅を、ホストに高さを設定してください。右から左のコンテキストでは、水平スクロールとアイテムの配置が反転します。 @@ -260,7 +286,7 @@ Virtual Scroll の は、ビューポートの各端を超えてレンダリングされる追加アイテムの数です（デフォルトは `2`）。値を大きくすると、高速スクロール中の空白領域が減りますが、レンダリングする要素が増えます。 +Virtual Scroll の は、ビューポートの各端を超えてレンダリングされる追加アイテムの数です (デフォルトは `2`)。値を大きくすると、高速スクロール中の空白領域が減りますが、レンダリングする要素が増えます。 @@ -280,7 +306,7 @@ Virtual Scroll の メソッドは、アイテムが表示される位置までスクロールします。オプションはネイティブの `scrollIntoView` と同じで、`block`（`start`、`center`、`end`、または `nearest`）、水平リスト用の `inline`、`behavior`（`auto` または `smooth`）を指定できます。まだレンダリングされていないアイテムには推定サイズしかないため、コンポーネントは到達した位置のアイテムを測定して位置を補正します。返されるプロミスは最終的な位置が確定すると解決されます。 +Virtual Scroll の メソッドは、アイテムが表示される位置までスクロールします。オプションはネイティブの `scrollIntoView` と同じで、`block` (`start`、`center`、`end`、または `nearest`)、水平リスト用の `inline`、`behavior` (`auto` または `smooth`) を指定できます。まだレンダリングされていないアイテムには推定サイズしかないため、コンポーネントは到達した位置のアイテムを測定して位置を補正します。返されるプロミスは最終的な位置が確定すると解決されます。 @@ -306,13 +332,13 @@ await virtualScroll.scrollToIndex(index, { block: 'center' }); -`block: 'nearest'` を指定した場合、アイテムがすでに完全に表示されているときは位置が変更されません。コレクションの範囲外のインデックスは、最初または最後のアイテムにクランプされます。 +`block: 'nearest'` を指定した場合、アイテムがすでに完全に表示されているときは位置が変更されません。コレクションの範囲外のインデックスは、最初または最後のアイテムに丸められます。 ### 無限スクロール -Virtual Scroll の 出力は、リモート データからの追加専用の読み込みをサポートします。これは、レンダリングされたウィンドウが `data` の末尾に近づいたときや、読み込まれたアイテムが最初のレンダリングでビューポートを満たさない場合に発行されます。要求されたアイテムを新しい配列として追加します。 +Virtual Scroll の 出力は、リモート データからの追加専用の読み込みをサポートします。これは、レンダリングされたウィンドウが `data` の末尾に近づいたときや、読み込まれたアイテムが最初のレンダリングでビューポートを満たさない場合に発生します。要求されたアイテムを新しい配列として追加します。 ```html @@ -336,7 +362,7 @@ public loadMore(request: VirtualScrollDataRequest): void { -Virtual Scroll の `igcDataRequest` イベントは、リモート データからの追加専用の読み込みをサポートします。これは、レンダリングされたウィンドウが `data` の末尾に近づいたときや、読み込まれたアイテムが最初のレンダリングでビューポートを満たさない場合に発行されます。要求されたアイテムを新しい配列として追加します。 +Virtual Scroll の `igcDataRequest` イベントは、リモート データからの追加専用の読み込みをサポートします。これは、レンダリングされたウィンドウが `data` の末尾に近づいたときや、読み込まれたアイテムが最初のレンダリングでビューポートを満たさない場合に発生します。要求されたアイテムを新しい配列として追加します。 ```ts virtualScroll.addEventListener('igcDataRequest', (event: CustomEvent) => { @@ -351,13 +377,13 @@ virtualScroll.addEventListener('igcDataRequest', (event: CustomEvent -一度に保留できるデータ要求は 1 つだけで、次の要求は `data` が次に変更された後に発行されます。`data` が空の場合は要求が発行されないため、最初のページは自分で読み込む必要があります。ソースにこれ以上アイテムがない場合は追加を停止してください。コンポーネントは同じ開始インデックスを再度要求することはありません。 +一度に保留できるデータ要求は 1 つだけで、次の要求は `data` が次に変更された後に発行されます。`data` が空の場合は要求が発行されないため、最初のページは自分で読み込む必要があります。ソースにこれ以上アイテムがない場合は、追加を停止するだけでかまいません。コンポーネントが同じ開始インデックスを再度要求することはありません。 ### ページ分割されたデータ -Angular Virtual Scroll の 入力は、`data` の代わりに大きなコレクションの 1 ページをバインドします。リストは `totalCount` と同じ長さになるため、ページのみがメモリ上にある間もスクロールバーはコレクション全体に及び、ページがカバーしていないインデックスは何もレンダリングしません。 +Angular Virtual Scroll の 入力は、`data` の代わりに大きなコレクションの 1 ページをバインドします。リストは `totalCount` と同じ長さになるため、ページのみがメモリ上にある間もスクロールバーはコレクション全体の範囲を表し、ページがカバーしていないインデックスは何もレンダリングしません。 ```ts interface VirtualDataWindow { @@ -397,7 +423,7 @@ public onStateChange(state: VirtualScrollState): void { -`totalCount` が変わらない間は、インデックスごとに測定済みサイズが保持されます。フィルタリング結果のように `totalCount` が異なるページは再度測定されます。`dataWindow` がバインドされている間は `dataRequest` は発行されません。コンポーネントはインデックスごとに 1 つのサイズ エントリを保存するため、そのメモリは `totalCount` に応じて増加します。100 万件のアイテムでおおよそ 17 MB です。 +`totalCount` が変わらない間は、インデックスごとに測定済みサイズが保持されます。フィルタリング結果のように `totalCount` が異なるページは再度測定されます。`dataWindow` がバインドされている間は `dataRequest` は発生しません。コンポーネントはインデックスごとに 1 つのサイズ エントリを保存するため、そのメモリは `totalCount` に応じて増加します。100 万件のアイテムでおおよそ 17 MB です。 @@ -425,30 +451,38 @@ await virtualScroll.layoutComplete; ### 使用すべき場合と使用すべきでない場合 -{/*TODO: add the Virtual Scroll Do/Don't guidance image from Indigo.Design when it is available.*/} - -**使用すべき場合:** ディレクトリ、フィード、ログ、カードのストリップなど、一度にレンダリングするには大きすぎる長いリストに対して Virtual Scroll を使用します。これには、スクロール中にリモート データを読み込むリストも含まれます。 +**使用すべき場合:** ディレクトリ、フィード、ログ、横一列に並んだカードなど、一度にレンダリングするには大きすぎる長いリストに対して Virtual Scroll を使用します。これには、スクロール中にリモート データを読み込むリストも含まれます。 -**使用すべきでない場合:** 短いリストは [List](../list.mdx) と `@for` で直接レンダリングします。列、並べ替え、フィルタリングを伴う表形式のデータには [Grid](../grid/grid.mdx) を使用します。仮想化を行わずにリッチなアイテムの少量のセットを表示するには [Card](../card.mdx) を使用します。 +**使用すべきでない場合:** 短いリストは [List](../list.mdx) と `@for` で直接レンダリングします。列、ソート、フィルタリングを伴う表形式のデータには [{Platform} Data Grid](../grid/grid.mdx) を使用します。仮想化せずに少数のリッチなアイテムを表示するには [Card](../card.mdx) を使用します。 -**使用すべき場合:** ディレクトリ、フィード、ログ、カードのストリップなど、一度にレンダリングするには大きすぎる長いリストに対して Virtual Scroll を使用します。これには、スクロール中にリモート データを読み込むリストも含まれます。 +**使用すべき場合:** ディレクトリ、フィード、ログ、横一列に並んだカードなど、一度にレンダリングするには大きすぎる長いリストに対して Virtual Scroll を使用します。これには、スクロール中にリモート データを読み込むリストも含まれます。 -**使用すべきでない場合:** 短いリストは [List](../grids/list.mdx) で直接レンダリングします。仮想化を行わずにリッチなアイテムの少量のセットを表示するには [Card](./card.mdx) を使用します。 +**使用すべきでない場合:** 短いリストは [List](../grids/list.mdx) で直接レンダリングします。列、ソート、フィルタリングを伴う表形式のデータには [{Platform} Data Grid](../grids/data-grid.mdx) を使用します。仮想化せずに少数のリッチなアイテムを表示するには [Card](./card.mdx) を使用します。 -| 推奨 | 非推奨 | -| --- | --- | -| ホストに固定の高さ（垂直）または幅（水平）を指定する。 | ホストのサイズをコンテンツに合わせて拡大させる。 | -| `estimatedItemSize` をアイテムの平均サイズに近い値に設定する。 | はるかに大きい、または小さいアイテムに対してデフォルトの 50px を維持する。 | -| コレクションが変更されたときに新しい配列を割り当てる。 | バインドされた配列をその場で変更する。 | -| パディングまたは `gap` でアイテム間の間隔を設定する。 | マージンでアイテム間の間隔を設定する。 | +
+ + + + + + + + + + + + + +
使用すべき使用すべきでない
{Platform} Virtual Scroll showing a list of 100,000 employees{Platform} Virtual Scroll used for a list of only five employees
+
## プロパティ @@ -462,7 +496,7 @@ await virtualScroll.layoutComplete; | | `number` | `2` | ビューポートの各端を超えてレンダリングされる追加アイテムの数。 | | | `number` | `50` | アイテムが測定されるまでのピクセル単位のサイズ。0 以下の値の場合は `50` が使用されます。 | | | `TemplateRef> \| null` | `null` | アイテム テンプレート。投影された `ng-template[igxVirtualItem]` より優先されます。 | -| | `Promise`（読み取り専用） | — | レンダリングとアイテムの測定が落ち着くと解決されます。 | +| | `Promise` (読み取り専用) | — | レンダリングとアイテムの測定が完了すると解決されます。 | @@ -475,7 +509,7 @@ await virtualScroll.layoutComplete; | | `number` | `2` | ビューポートの各端を超えてレンダリングされる追加アイテムの数。属性: `over-scan`。 | | | `number` | `50` | アイテムが測定されるまでのピクセル単位のサイズ。0 以下の値の場合は `50` が使用されます。属性: `estimated-item-size`。 | | | `VirtualScrollItemTemplate \| null` | `null` | 各アイテムをレンダリングする関数。プロパティのみ。 | -| | `Promise`（読み取り専用） | — | レンダリングとアイテムの測定が落ち着くと解決されます。 | +| | `Promise` (読み取り専用) | — | レンダリングとアイテムの測定が完了すると解決されます。 | @@ -483,7 +517,7 @@ await virtualScroll.layoutComplete; | 名前 | 戻り値 | 説明 | | --- | --- | --- | -| | `Promise` | `index` のアイテムをビューにスクロールし、最終的なスクロール位置が確定すると完了します。 | +| | `Promise` | `index` のアイテムをビューにスクロールし、最終的なスクロール位置が確定すると解決されます。 | ## イベント @@ -491,8 +525,8 @@ await virtualScroll.layoutComplete; | 名前 | ペイロード | 説明 | | --- | --- | --- | -| | `VirtualScrollState` | レンダリングされたウィンドウが変更されたときに発行されます: `startIndex`、`endIndex`、`viewportSize`、`totalSize`。 | -| | `VirtualScrollDataRequest` | レンダリングされたウィンドウが `data` の末尾に近づいたときに発行されます: `startIndex`、`count`。`dataWindow` がバインドされている間は発行されません。 | +| | `VirtualScrollState` | レンダリングされたウィンドウが変更されたときに発生します: `startIndex`、`endIndex`、`viewportSize`、`totalSize`。 | +| | `VirtualScrollDataRequest` | レンダリングされたウィンドウが `data` の末尾に近づいたときに発生します: `startIndex`、`count`。`dataWindow` がバインドされている間は発生しません。 | @@ -500,8 +534,8 @@ await virtualScroll.layoutComplete; | 名前 | 詳細 | 説明 | | --- | --- | --- | -| `igcStateChange` | `VirtualScrollState` | レンダリングされたウィンドウが変更されたときに発行されます: `startIndex`、`endIndex`、`viewportSize`、`totalSize`。 | -| `igcDataRequest` | `VirtualScrollDataRequest` | レンダリングされたウィンドウが `data` の末尾に近づいたときに発行されます: `startIndex`、`count`。 | +| `igcStateChange` | `VirtualScrollState` | レンダリングされたウィンドウが変更されたときに発生します: `startIndex`、`endIndex`、`viewportSize`、`totalSize`。 | +| `igcDataRequest` | `VirtualScrollDataRequest` | レンダリングされたウィンドウが `data` の末尾に近づいたときに発生します: `startIndex`、`count`。 | @@ -547,7 +581,7 @@ igc-virtual-scroll.employees [data-vs-index]:nth-child(even) { ### キーボード インタラクション -{Platform} Virtual Scroll はキー ハンドラーを追加しません。ホストはネイティブのスクロール コンテナーであり、フォーカスされたスクロール コンテナーはブラウザーのキーでスクロールします。 +{Platform} Virtual Scroll はキー ハンドラーを追加しません。ホストはネイティブのスクロール コンテナーであり、フォーカスされたスクロール コンテナーはブラウザー標準のキー操作でスクロールします。 | キー | アクション | | --- | --- | @@ -563,6 +597,7 @@ igc-virtual-scroll.employees [data-vs-index]:nth-child(even) { - ホストには `role="list"` が設定されています。トラック、コンテンツ要素、アイテム ラッパーには `role="presentation"` が設定されています。`igx-list-item` のように `role="listitem"` をレンダリングするアイテムは、そのリストのアイテムとして公開されます。 +- `igx-list` のように既にリストのセマンティクスを提供するコンテナー内では、アイテムが二重のリストに入れ子にならないよう、ホストに `role="presentation"` を設定してください。 - `index` と `count` のテンプレート変数を `aria-posinset` と `aria-setsize` にマップします。 - フォーカス可能なホストには、`aria-label` または `aria-labelledby` でアクセシブルな名前を付けてください。 @@ -578,25 +613,25 @@ igc-virtual-scroll.employees [data-vs-index]:nth-child(even) { ### アクセシビリティ準拠 -Infragistics は、{ProductName} が対象とするアクセシビリティ標準を [アクセシビリティ準拠](../interactivity/accessibility-compliance.mdx) トピックで文書化しています。このトピックは Virtual Scroll に対する準拠の主張を行うものではありません。表にはコンポーネントが提供する内容が記載されており、その後のリストにはアプリケーションが追加する必要がある内容が記載されています。 +インフラジスティックスは、{ProductName} が対象とするアクセシビリティ標準を [アクセシビリティ準拠](../interactivity/accessibility-compliance.mdx) トピックで文書化しています。このトピックは Virtual Scroll に対する準拠の主張を行うものではありません。表にはコンポーネントが提供する内容が記載されており、その後のリストにはアプリケーションが追加する必要がある内容が記載されています。 | 基準 | コンポーネントが要件をサポートする方法 | | --- | --- | -| [1.3.1 情報及び関係性](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | ラッパーは表示専用であるため、リスト構造はホストとアイテム テンプレートから提供され、`aria-posinset` と `aria-setsize` で各アイテムの位置を公開できます。 | +| [1.3.1 情報及び関係性](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | ラッパーには `role="presentation"` が設定されているため、リスト構造はホストとアイテム テンプレートから提供され、`aria-posinset` と `aria-setsize` で各アイテムの位置を公開できます。 | | [2.1.1 キーボード](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | ホストはネイティブのスクロール コンテナーであり、フォーカスを得るとキーボードでスクロールできます。キーボードでホストに到達できるかどうかはアプリケーションに依存します。以下のリストを参照してください。 | ユーザー側の責任: - アイテムにフォーカス可能な要素が含まれない場合は、`tabindex="0"` を設定してホストをキーボードで到達可能にし、アクセシブルな名前を付けてください。 - アイテム テンプレートから `aria-posinset` と `aria-setsize` でアイテムの位置を公開してください。 -- アイテム テンプレートに適したリスト セマンティクスを提供してください（[スクリーン リーダー / ARIA](#スクリーン-リーダー--aria) を参照）。 +- アイテム テンプレートに適したリスト セマンティクスを提供してください ([スクリーン リーダー / ARIA](#スクリーン-リーダー--aria) を参照)。 - 選択などのアプリケーションの状態は、レンダリングされたアイテム要素ではなくデータ内に保持してください。 ## トラブルシューティング ### Virtual Scroll がアイテムをレンダリングしないのはなぜですか? -ホストにスクロール軸方向のサイズがない、アイテム テンプレートがない、または `data` が空です。ホストに固定の高さ（垂直）または幅（水平）を設定し、アイテム テンプレートを設定して、バインドされたコレクションを確認してください。 +ホストにスクロール軸方向のサイズがない、アイテム テンプレートがない、または `data` が空です。ホストに固定の高さ (垂直) または幅 (水平) を設定し、アイテム テンプレートを設定して、バインドされたコレクションを確認してください。 ### アイテムを追加してもリストが更新されないのはなぜですか? @@ -625,14 +660,14 @@ Virtual Scroll は実行時にアイテムを測定し、独自のスクロー | `*igxFor="let item of data"` | `ng-template igxVirtualItem` を伴う `[data]="data"` | | `igxForScrollOrientation` | `orientation` | | `igxForContainerSize` | CSS で設定するホストの高さまたは幅 | -| `igxForItemSize` | `estimatedItemSize`（開始時の推定値。アイテムは測定されます） | +| `igxForItemSize` | `estimatedItemSize` (開始時の推定値。アイテムは測定されます) | | `igxForScrollContainer` | 不要: ホストがスクロール コンテナーです | | `scrollTo(index)` | プロミスを返す `scrollToIndex(index, options)` | | `chunkLoad`、`chunkPreload` | `stateChange` | -| `totalItemCount` を伴う `igxForRemote` | `totalCount` を伴う `dataWindow`、または追加専用の読み込み向けに `dataRequest` を伴う `data` | +| リモート データ向けの `igxForTotalItemCount` | `totalCount` を伴う `dataWindow`、または追加専用の読み込み向けに `dataRequest` を伴う `data` | | `index`、`count`、`first`、`last`、`even`、`odd` | 同じテンプレート変数 | -グリッドは独自の行と列の仮想化を維持します。[グリッドの仮想化](../grid/virtualization.mdx) を参照してください。 +グリッドには独自の行と列の仮想化機能があります。[グリッドの仮想化](../grid/virtualization.mdx) を参照してください。 @@ -675,7 +710,8 @@ Angular Virtual Scroll は、他のコンポーネントへの依存関係を持 - [List](../list.mdx) - 短いリストや、仮想化されたリストのコンテナーとして List を使用します。 -- [Card](../card.mdx) - リッチなアイテムの少量のセット、または水平の Virtual Scroll のアイテムとしてカードを使用します。 +- [Data Grid](../grid/grid.mdx) - 列、ソート、フィルタリングを伴う表形式のデータには Data Grid を使用します。 +- [Card](../card.mdx) - 少数のリッチなアイテムの表示や、水平方向の Virtual Scroll のアイテムとしてカードを使用します。 - [Virtual ForOf ディレクティブ](../for-of.mdx) - 既存のリストで使用されるディレクティブ ベースの仮想化。 @@ -683,7 +719,8 @@ Angular Virtual Scroll は、他のコンポーネントへの依存関係を持 - [List](../grids/list.mdx) - 短いリストや、仮想化されたリストのコンテナーとして List を使用します。 -- [Card](./card.mdx) - リッチなアイテムの少量のセット、または水平の Virtual Scroll のアイテムとしてカードを使用します。 +- [Data Grid](../grids/data-grid.mdx) - 列、ソート、フィルタリングを伴う表形式のデータには Data Grid を使用します。 +- [Card](./card.mdx) - 少数のリッチなアイテムの表示や、水平方向の Virtual Scroll のアイテムとしてカードを使用します。