更新记录

0.1.7（2026-08-01） 下载此版本

• 新增 nested-scroll：Android 端（APP-ANDROID）通过内层 scroll-view 的 associative-container 建立嵌套滚动协商；Web、iOS、HarmonyOS 及未启用该属性的实例行为保持不变。
• 修复 Android 演示页空白与内层列表无法滚动：外层滚动容器启用 type="nested"，并以 nested-scroll-header / nested-scroll-body 包裹页面内容；移除会阻断边界交接的 touchmove.stop。
• 修复 Android 警告：不再给 nested-scroll-body 设置仅适用于视图节点的 flex-direction 样式。

平台兼容性

uni-app x(4.25)

其他

nax-virtual-list

固定行高虚拟列表。使用 scroll-view + 上下 spacer，只渲染可视区与缓冲行，适合一次性持有大量数据。鸿蒙端对窗口更新做滞后合并，scroll/visible-change 在 scrollend 同步。

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

能力

• 固定 itemHeight：全端窗口裁剪；鸿蒙滞后更新 + scrollend 事件
• 作用域插槽自定义行：{ 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

依赖

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

注意

1. 必须等高：每行实际高度应等于 item-height，否则滚动定位会漂。
2. 必须有明确高度：height 或父级 flex 高度链。
3. 作用域插槽在部分端对类型较严，demo 用 UTSJSONObject 取字段。
4. 鸿蒙端使用与其它端相同的窗口裁剪（不用全量 list-view 挂载，避免进页卡死）；滚动窗口滞后更新，scroll/visible-change 在 scrollend 同步。
5. 不做瀑布流 / 不等高测量（后续可增强）。
6. Web 端使用固定总高 + translateY 窗口偏移，并关闭 overflow-anchor，避免滚动锚定导致连滚到底。
7. Web / 微信小程序：每次进入触底阈值只派发一次 load；组件按滚动区剩余距离判断是否真正离开底部，并在追加数据后恢复原 scrollTop，避免视口跳到新增页底部（#ifdef WEB || MP-WEIXIN）。
8. 微信小程序：行节点使用窗口位置 key，避免 “More than one slot named d-N” 警告。