更新记录

0.1.13（2026-08-18） 下载此版本

• 修复 scroll-view 标签属性区条件编译注释被解析为属性的隐患：@scrollend（仅鸿蒙/iOS）改为条件编译双分支渲染（注释移至标签外）

0.1.10（2026-08-14） 下载此版本

• 精简 readme：移除内部开发向内容（设计说明 / 实现细节 / 平台差异实现等），只保留安装、用法、API、主题等用户文档

0.1.8（2026-08-07） 下载此版本

• 修复 iOS 端滑动掉帧：onScroll 从每个 scroll 事件同步更新窗口改为 32ms 合并 + scrollend 强制同步（APP-IOS 复用鸿蒙机制，scroll/visible-change 在 scrollend 同步触发），并在窗口中部滚动时跳过重建
• 修复 iOS 端快速滑动下方空白：缓冲行数下限抬到 12（APP-IOS），scrollend 用最新 scrollTop 强制对齐窗口
• Android、Web 和小程序行为保持不变

平台兼容性

uni-app x(4.25)

其他

nax-virtual-list

固定行高虚拟列表。使用 scroll-view + 上下 spacer，只渲染可视区与缓冲行，适合一次性持有大量数据。

与 nax-list 的区别：nax-list 是滚动壳（内容自行 v-for，不裁剪 DOM）；本组件接管数据源并做窗口裁剪。

能力

• 固定 itemHeight：全端窗口裁剪
• 作用域插槽自定义行：{ item, index }
• 触底 load、下拉刷新、空 / 加载 / 结束 / 错误态（对齐 nax-list）
• 方法：scrollToIndex / scrollToOffset / getVisibleRange

用法

基础（大数据）

<nax-virtual-list
  height="480px"
  :list="list"
  :item-height="56"
  :buffer="8"
  key-field="id"
>
  <template #default="{ item, index }">
    <nax-cell :title="item.title" :value="'' + (index + 1)" is-link></nax-cell>
  </template>
</nax-virtual-list>

const list = ref([] as UTSJSONObject[])
// 一次性生成 / 从本地读入大量数据

触底加载更多

<nax-virtual-list
  height="480px"
  :list="list"
  :item-height="48"
  :loading="loading"
  :finished="finished"
  @load="onLoad"
>
  <template #default="{ item, index }">
    <nax-cell :title="item.title"></nax-cell>
  </template>
</nax-virtual-list>

滚动到指定行

// 模板 ref
const vlRef = ref(null)
// 调用
// vlRef.value!.scrollToIndex(500)

Props

Events

Methods

Slots

主题

通过 CSS 变量覆盖：

依赖

• nax-empty
• nax-loading
• nax-ui-theme（可选 token）

注意

1. 必须等高：每行实际高度应等于 item-height，否则滚动定位会漂。
2. 必须有明确高度：height 或父级 flex 高度链。
3. 作用域插槽在部分端对类型较严，建议用 UTSJSONObject 取字段。
4. 不做瀑布流 / 不等高测量。