Virtual scroll

窗口化列表——1万行，约25个DOM节点。

浏览器: Chrome 123+Firefox 121+Safari 17.5+
层级: 2
压缩后大小: 4.16 kB
强制布局预算: 0 ms
axe 预算: 0
支持 SSR: 是
公开契约: 测试环境

交互示例

React

CSS

Tailwind

/* Generic skin for custom core surfaces used by the demo and consumers. */

@layer components {
  [data-uiify-surface] {
    display: grid;
    gap: var(--space-md);
    inline-size: max-content;
    max-inline-size: min(28rem, calc(100vw - 2 * var(--space-lg)));
    padding: var(--space-lg);
    border: var(--border-width) solid var(--border);
    border-radius: var(--radius-xl);
    corner-shape: squircle;
    background-color: var(--card);
    color: var(--card-foreground);
    box-shadow: var(--shadow-popover);
  }

  [data-uiify-surface][popover]:not(:popover-open) {
    display: none;
  }

  @media (prefers-reduced-motion: no-preference) {
    [data-uiify-surface][popover] {
      transition: var(--transition-presence);
    }

    [data-uiify-surface][popover]:not(:popover-open) {
      opacity: 0;
      scale: var(--presence-scale);
    }

    @starting-style {
      [data-uiify-surface][popover]:popover-open {
        opacity: 0;
        scale: var(--presence-scale);
      }
    }
  }
}

import { VirtualScroll } from "@gunkin/uiify";

const items = Array.from({ length: 10000 }, (_, index) => ({
  id: String(index),
  label: "Row " + (index + 1),
}));

export default function Example() {
  return (
    <>
      <VirtualScroll
        className="
          grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl
          [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden
          motion-safe:[&[popover]]:[transition:var(--transition-presence)]
          motion-safe:[&[popover]:not(:popover-open)]:opacity-0
          motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)]
          motion-safe:starting:[&[popover]:popover-open]:opacity-0
          motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]
        "
        height={400}
        items={items}
        renderRow={(item) => <div>{item.label}</div>}
      />
      {/* rowHeight is the item size along the scroll axis — here, each card's width. */}
      <VirtualScroll
        className="
          grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl
          [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden
          motion-safe:[&[popover]]:[transition:var(--transition-presence)]
          motion-safe:[&[popover]:not(:popover-open)]:opacity-0
          motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)]
          motion-safe:starting:[&[popover]:popover-open]:opacity-0
          motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]
        "
        height={120}
        items={items}
        orientation="horizontal"
        rowHeight={144}
        renderRow={(item) => <div>{item.label}</div>}
      />
    </>
  );
}

/* app.css */

@layer reset, ui, app, tokens, base, demo, components, utilities, theme;

@import "@gunkin/uiify/styles/reset";

@import "@gunkin/uiify/components/behavior.css";

@import "@gunkin/uiify/styles/tokens";

@import "@gunkin/uiify/styles/tailwind";

@import "tailwindcss/utilities.css";

@theme { --spacing: 0.25rem; --font-weight-normal: 400; --font-weight-medium: 500; --font-weight-semibold: 600; --font-weight-bold: 700; }

@source inline('grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden motion-safe:[&[popover]]:[transition:var(--transition-presence)] motion-safe:[&[popover]:not(:popover-open)]:opacity-0 motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)] motion-safe:starting:[&[popover]:popover-open]:opacity-0 motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]');

@layer base { :root { --uiify-control-text: var(--text-sm); } @media (pointer: coarse) { :root { --uiify-control-text: var(--text-base); } } }

/* Authored animation and registered properties used by the Tailwind skin.
 * Visual rules belong in utility recipes; only at-rule definitions live here. */
@layer components {
  @keyframes uiify-presence-in {
    from {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@layer components {
  @keyframes uiify-presence-out {
    to {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@property --uiify-spinner-tail {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@property --uiify-spinner-length {
  syntax: "<angle>";
  inherits: false;
  initial-value: 36deg;
}

@layer components {
  @keyframes uiify-spinner-rotate {
    to {
      transform: rotate(360deg);
    }
  }
}

@layer components {
  @keyframes uiify-spinner-orbit {
    0% {
      --uiify-spinner-tail: 0deg;
      --uiify-spinner-length: 36deg;
    }

    50% {
      --uiify-spinner-tail: 90deg;
      --uiify-spinner-length: 324deg;
    }

    100% {
      --uiify-spinner-tail: 360deg;
      --uiify-spinner-length: 36deg;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-pulse {
    50% {
      opacity: 0.45;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-shimmer {
    to {
      background-position: -200% 0;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-reveal {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }
}

@property --candle-body-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-body-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-slot {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 100%;
}

@property --candle-wick-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-wick-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-x {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@property --line-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-prev-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-count {
  syntax: "<integer>";
  inherits: false;
  initial-value: 1;
}

@property --line-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@layer components {
  @keyframes uiify-otp-input-caret-blink {
    50% {
      opacity: 0;
    }
  }
}

API

`VirtualScroll`

属性	类型	默认值	说明
`items`*	`T[]`	—	完整的项目列表，每项都有稳定id；只渲染当前范围内的行。
`renderRow`*	`(item: T, index: number) => ReactNode`	—	根据项目及其绝对索引渲染单行内容。
`height`	`number`	—	以像素为单位的显式高度。省略并传入style={{ blockSize: '100%' }}可填满高度确定的父元素；两者均未提供时默认为600px。
`rowHeight`	`number`	`64`	每行在滚动轴上的固定像素尺寸（纵向为高度，横向为宽度），用于计算滚动尺寸和可见行。
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	滚动轴。横向列表沿行内轴滚动，根据实测视口宽度确定渲染窗口大小，在从右向左的布局中正确镜像，并将值同步到`data-orientation`。
`overscan`	`number`	`5`	在可见范围上方和下方额外渲染的行数，避免快速滚动时出现空白。
`estimateRowHeight`	`(index: number) => number`	—	按索引估算高度，使列表切换为动态布局；渲染后的行会被测量，并据此修正估算。
`role`	`"list" \| "grid"`	`"list"`	应用于滚动容器的ARIA角色。
`anchor`	`"start" \| "end"`	`"start"`	添加或移除项目时，滚动位置固定在列表的哪一端。
`followAppend`	`boolean \| "smooth"`	`false`	列表已滚动到底部时，滚动到新追加的项目，可选择平滑滚动。
`scrollRef`	`Ref<VirtualScrollHandle>`	—	接收命令式句柄，暴露scrollToIndex、scrollToOffset和scrollToEnd。
`onRangeChange`	`(range: VirtualScrollRangeChange) => void`	—	渲染窗口移动时，使用可见及额外预渲染的索引范围调用。
`onScrollStateChange`	`(state: VirtualScrollScrollState) => void`	—	开始滚动和滚动停止时调用。
`isScrollingResetDelay`	`number`	`150`	浏览器不支持scrollend事件时，判定滚动停止所需的无活动时长，单位为毫秒。
`className`	`string`	—	应用于滚动容器的类名。
`testId`	`string`	—	滚动容器data-testid属性的值。

键盘

按键	操作
`Scroll`	通过滚轮、触控板或滚动条移动渲染窗口
`Tab`	在行控件之间移动焦点（复选框、菜单触发器）
`Arrow keys`	在已打开的下拉菜单内移动焦点
`Escape`	关闭已打开的下拉菜单

无障碍

全高占位元素保证原生滚动条准确，同时只挂载固定数量的行槽及额外预渲染行；稳定的槽位key用于复用DOM节点。行在role="list"滚动区域内暴露role="listitem"、aria-posinset和aria-setsize。滚动同步使用被动监听；滚动条、Home/End或Cmd+Arrow等大幅跳转会同步更新范围。

样式钩子

data-uiify-virtual-scrolldata-part="spacer"data-part="row"

框架

样式

主题

语言

Virtual scroll

交互示例

Virtual scroll

Horizontal

API

`VirtualScroll`

键盘

无障碍

样式钩子