VueVirtualScroller

常用的几个组件

主要有 RecycleScroller.vue、DynamicScroller.vue和DynamicScrollerItem.vue这三个组件，然而RecycleScroller为实现核心

笔记

RecycleScroller 和 DynamicScroller 两者之间的区别是什么呢？

在应用上 RecycleScroller 需要item的高度为静态的，也就是列表每个item的高度都是一致的。而 DynamicScroller就可以兼容item的高度为动态的。但是理论上 RecycleScroller也可以实现动态高度的item，只要有方案计算到item的height就可以(DynamicScrollerItem解决的就是这个问题)。

RecycleScroller使用案例

<template>
  <RecycleScroller
    class="scroller"
    :items="list"
    :item-size="32"
    key-field="id"
    v-slot="{ item }">
    <div class="user">
      {{ item.name }}
    </div>
  </RecycleScroller>
</template>
<script>
export default {
  props: {
    list: Array,
  }
}
</script>
<style scoped>
.scroller {
  height: 100%;
}
.user {
  height: 32%;
  padding: 0 12px;
  display: flex;
  align-items: center;
}
</style>

DynamicScroller使用案例

<template>
  <DynamicScroller
    :items="items"
    :min-item-size="54"
    class="scroller">
    <template v-slot="{ item, index, active }">
      <DynamicScrollerItem
        :item="item"
        :active="active"
        :size-dependencies="[item.message]"
        :data-index="index">
        <div class="avatar">
          <img
            :src="item.avatar"
            :key="item.avatar"
            alt="avatar"
            class="image">
        </div>
        <div class="text">{{ item.message }}</div>
      </DynamicScrollerItem>
    </template>
  </DynamicScroller>
</template>
<script>
export default {
  props: {
    items: Array,
  },
}
</script>
<style scoped>
.scroller {
  height: 100%;
}
</style>

实际使用过程中遇到的问题

扩展下拉刷新功能

<template>
  <div ref="container" class="dynamic-scroller-container">
    <div
      class="refresh-wrapper"
      @touchstart="handleTouchStart"
      @touchmove="handleTouchMove"
      @touchend="handleTouchEnd"
      @mousedown="handleMouseDown"
      @mousemove="handleMouseMove"
      @mouseup="handleMouseUp"
      @mouseleave="handleMouseUp"
    >
      <div
        ref="refreshIndicator"
        class="refresh-indicator"
        :style="{ height: refreshDistance + 'px' }"
      >
        <div v-if="refreshing" class="refresh-text"><v-loading /></div>
        <div v-else-if="pullingDown" class="refresh-text">下拉刷新</div>
        <div v-else-if="refreshSuccess" class="refresh-text">刷新成功</div>
      </div>

      <DynamicScroller
        v-if="hasData"
        :items="list"
        :min-item-size="minItemSize"
        :key-field="keyField"
        class="virtual-scroller"
        :style="{ marginTop: computedTopOffset + 'px' }"
        @scroll-end="handleScrollEnd"
        ref="scroller"
      >
        <template v-slot="{ item, index, active }">
          <DynamicScrollerItem
            :item="item"
            :active="active"
            :size-dependencies="sizeDependencies"
            :data-index="index"
            class="virtual-scroller-item"
          >
            <slot
              name="item"
              :item="item"
              :index="index"
              @click="handleItemClick(item)"
            />
          </DynamicScrollerItem>
        </template>
        <template #after>
          <div :class="afterClass">
            <div
              v-if="pageOption.end && !hasMoreData"
              class="flex-row transition h-50 justify-center items-center text-secondary fs-26 mt-auto"
            >
              <span>~没有更多了~</span>
            </div>
            <div
              v-else-if="loadingMore"
              class="w-full flex-row transition h-50 justify-center items-center text-secondary fs-26 mt-auto"
              style="z-index: 10"
            >
              <v-loading />
            </div>
            <div v-else class="h-50" />
          </div>
        </template>
      </DynamicScroller>

      <!-- 空状态 -->
      <div
        v-else-if="showEmptyState"
        class="flex-row transition justify-center text-secondary fs-26 mt-auto h-full items-center"
      >
        {{ emptyText }}
      </div>

      <!-- 初始加载状态 -->
      <div
        v-else-if="showInitialLoading"
        class="flex-row transition h-full justify-center text-secondary fs-26 mt-auto items-center"
      >
        <v-loading />
      </div>
    </div>
  </div>
</template>

<script>
import lodash from "lodash";

export default {
  name: "DynamicScrollerList",
  components: {},
  props: {
    request: {
      type: Function,
      required: true,
      validator: (value) => typeof value === "function",
    },
    minItemSize: {
      type: Number,
      default: 100,
      validator: (value) => value > 0,
    },
    keyField: {
      type: String,
      default: "id",
    },
    sizeDependencies: {
      type: Array,
      default: () => [],
    },
    afterClass: {
      type: String,
      default: "flex-col",
    },
    emptyText: {
      type: String,
      default: "暂无数据",
    },
    pageSize: {
      type: Number,
      default: 20,
      validator: (value) => value > 0,
    },
    debounceDelay: {
      type: Number,
      default: 300,
      validator: (value) => value >= 0,
    },
    // 下拉刷新触发阈值（达到即触发刷新）
    pullThreshold: {
      type: Number,
      default: 60,
      validator: (value) => value >= 30,
    },
    // 最大可下拉距离（视觉上限）
    maxPullDistance: {
      type: Number,
      default: 100,
      validator: (value) => value >= 60,
    },
    // 是否启用下拉刷新
    enablePullToRefresh: {
      type: Boolean,
      default: true,
    },
  },
  data() {
    return {
      loading: false,
      loadingMore: false,
      userHasInteracted: false,
      refreshing: false,
      refreshSuccess: false,
      pullingDown: false,
      error: null,
      pageOption: {
        end: false,
        curPage: 1,
        pageSize: this.pageSize,
      },
      list: [],
      hasMoreData: true,

      // 下拉刷新相关数据
      startY: 0,
      currentY: 0,
      refreshDistance: 0,
      touchScrollTop: 0,
      isTouching: false,
      lastMoveY: 0,

      // 鼠标事件相关
      isMouseDown: false,
    };
  },
  computed: {
    hasData() {
      return this.list && this.list.length > 0;
    },
    showEmptyState() {
      return (
        !this.loading &&
        !this.hasData &&
        (this.pageOption.end || !this.hasMoreData)
      );
    },
    showInitialLoading() {
      return this.loading && !this.hasData;
    },
    // 列表顶部需要下移的距离：刷新中固定为阈值，其余按实时下拉距离
    computedTopOffset() {
      if (!this.enablePullToRefresh) return 0;
      return this.refreshing ? this.pullThreshold : this.refreshDistance;
    },
  },
  watch: {
    pageSize: {
      handler(newVal) {
        this.pageOption.pageSize = newVal;
      },
      immediate: true,
    },
  },
  created() {
    this.debouncedScrollEnd = lodash.debounce(
      this.loadMoreData,
      this.debounceDelay
    );
  },
  mounted() {
    this.$nextTick(() => {
      this.loadInitialData();
    });
  },
  methods: {
    // 鼠标事件处理（支持PC端）
    handleMouseDown(e) {
      if (!this.enablePullToRefresh || this.refreshing) return;
      this.startY = e.pageY;
      this.lastMoveY = this.startY;
      const scrollerRef = this.$refs.scroller;
      const scroller = scrollerRef && scrollerRef.$el ? scrollerRef.$el : null;
      this.touchScrollTop = scroller ? scroller.scrollTop : 0;
      this.isMouseDown = true;
    },

    handleMouseMove(e) {
      if (!this.enablePullToRefresh || !this.isMouseDown || this.refreshing) {
        return;
      }

      const currentY = e.pageY;
      const diff = currentY - this.startY;

      // 实时读取滚动位置，确保只能在顶部触发
      const scrollerRef = this.$refs.scroller;
      const scroller = scrollerRef && scrollerRef.$el ? scrollerRef.$el : null;
      const currentScrollTop = scroller ? scroller.scrollTop : 0;

      // 仅向下拉且在顶部时处理
      if (currentScrollTop <= 0 && diff > 0) {
        e.preventDefault();
        this.pullingDown = true;
        this.currentY = currentY;
        this.lastMoveY = currentY;

        // 阻尼：前半段跟手，后半段递减
        const raw = diff;
        const damped =
          raw < this.pullThreshold
            ? raw
            : this.pullThreshold + (raw - this.pullThreshold) * 0.4;
        this.refreshDistance = Math.min(damped, this.maxPullDistance);
      } else {
        this.pullingDown = false;
        this.refreshDistance = 0;
      }
    },

    handleMouseUp() {
      if (!this.enablePullToRefresh) return;
      this.isMouseDown = false;

      // 触发刷新或复位
      if (
        this.pullingDown &&
        this.refreshDistance >= this.pullThreshold &&
        !this.refreshing
      ) {
        this.handleRefresh();
      } else {
        this.refreshDistance = 0;
        this.pullingDown = false;
      }
    },

    // 下拉刷新相关方法
    handleTouchStart(e) {
      if (!this.enablePullToRefresh || this.refreshing) return;
      const touch = e.touches && e.touches[0];
      if (!touch) return;
      this.startY = touch.pageY;
      this.lastMoveY = this.startY;
      const scrollerRef = this.$refs.scroller;
      const scroller = scrollerRef && scrollerRef.$el ? scrollerRef.$el : null;
      this.touchScrollTop = scroller ? scroller.scrollTop : 0;
      this.isTouching = true;
    },

    handleTouchMove(e) {
      if (!this.enablePullToRefresh || !this.isTouching || this.refreshing) {
        return;
      }

      const touch = e.touches && e.touches[0];
      if (!touch) return;
      const currentY = touch.pageY;
      const diff = currentY - this.startY;

      // 实时读取滚动位置，确保只能在顶部触发
      const scrollerRef = this.$refs.scroller;
      const scroller = scrollerRef && scrollerRef.$el ? scrollerRef.$el : null;
      const currentScrollTop = scroller ? scroller.scrollTop : 0;

      // 仅向下拉且在顶部时处理
      if (currentScrollTop <= 0 && diff > 0) {
        // 阻止浏览器原生回弹（仅在可取消时）
        if (e.cancelable) e.preventDefault();
        this.pullingDown = true;
        this.currentY = currentY;
        this.lastMoveY = currentY;

        // 阻尼：前半段跟手，后半段递减
        const raw = diff;
        const damped =
          raw < this.pullThreshold
            ? raw
            : this.pullThreshold + (raw - this.pullThreshold) * 0.4;
        this.refreshDistance = Math.min(damped, this.maxPullDistance);
      } else {
        this.pullingDown = false;
        this.refreshDistance = 0;
      }
    },

    handleTouchEnd() {
      if (!this.enablePullToRefresh) return;
      this.isTouching = false;

      // 触发刷新或复位
      if (
        this.pullingDown &&
        this.refreshDistance >= this.pullThreshold &&
        !this.refreshing
      ) {
        this.handleRefresh();
      } else {
        this.refreshDistance = 0;
        this.pullingDown = false;
      }
    },

    /**
     * 加载初始数据
     */
    async loadInitialData() {
      // 优化：即使在end状态下，如果正在刷新也应该加载数据
      if (this.pageOption.end && !this.refreshing) {
        this.loading = false;
        return;
      }

      await this.fetchData(true);
    },

    /**
     * 加载更多数据
     */
    async loadMoreData() {
      // 优化：简化条件判断
      if (
        this.pageOption.end ||
        this.loading ||
        this.loadingMore ||
        !this.hasMoreData
      ) {
        return;
      }

      this.userHasInteracted = true;
      this.loadingMore = true;
      await this.fetchData(false);
      this.loadingMore = false;
    },

    /**
     * 统一的数据获取方法
     * @param {boolean} isInitial - 是否为初始加载
     */
    async fetchData(isInitial = false) {
      try {
        this.loading = true;
        this.error = null;

        const requestParams = {
          curPage: isInitial ? 1 : this.pageOption.curPage,
          pageSize: this.pageOption.pageSize,
        };

        const response = await this.request(requestParams);

        if (!response || typeof response !== "object") {
          throw new Error("Invalid response format");
        }

        const { data = {} } = response;
        const { records = [] } = data;

        // 处理数据
        if (isInitial || this.refreshing) {
          this.list = records;
        } else {
          this.list = [...this.list, ...records];
        }

        // 更新分页状态
        this.updatePageState(records.length);
      } catch (error) {
        this.handleError(error);
      } finally {
        this.loading = false;
        // 刷新结束的可视状态交由 handleRefresh 收尾
      }
    },

    /**
     * 更新分页状态
     * @param {number} recordCount - 当前页记录数
     */
    updatePageState(recordCount) {
      // 修复分页逻辑：只有当返回记录数小于页面大小时才标记为结束
      if (recordCount < this.pageOption.pageSize) {
        this.pageOption.end = true;
        this.hasMoreData = false;
      } else {
        this.pageOption.curPage += 1;
        this.hasMoreData = true;
      }
    },

    /**
     * 错误处理
     * @param {Error} error - 错误对象
     */
    handleError(error) {
      console.error("获取数据失败:", error);
      this.error = error.message || "数据加载失败";

      // 不要直接设置end为true，除非确认没有更多数据
      // this.pageOption.end = true;

      // 触发错误事件
      this.$emit("error", {
        error,
        message: this.error,
      });
    },

    /**
     * 滚动到底部处理函数
     */
    handleScrollEnd() {
      this.userHasInteracted = true;
      this.debouncedScrollEnd();
    },

    /**
     * 处理项目点击
     * @param {Object} data - 项目数据
     */
    handleItemClick(data) {
      this.$emit("itemClick", data);
    },

    /**
     * 重置组件状态
     */
    resetState() {
      this.pageOption = {
        end: false,
        curPage: 1,
        pageSize: this.pageSize,
      };
      this.list = [];
      this.error = null;
      this.hasMoreData = true;
      this.userHasInteracted = false;
    },

    /**
     * 刷新数据
     */
    async refresh() {
      // 重置分页状态
      this.pageOption = {
        end: false,
        curPage: 1,
        pageSize: this.pageSize,
      };
      this.error = null;
      this.hasMoreData = true;

      await this.fetchData(true);
    },

    /**
     * 下拉刷新处理函数
     */
    async handleRefresh() {
      this.refreshing = true;
      this.refreshSuccess = false;

      try {
        // 固定指示器在阈值高度
        this.refreshDistance = this.pullThreshold;
        await this.refresh();
        this.$emit("refresh");
        this.refreshSuccess = true;

        // 显示刷新成功状态一小段时间
        setTimeout(() => {
          this.refreshSuccess = false;
        }, 500);
      } finally {
        this.refreshing = false;
        this.pullingDown = false;
        // 轻微延迟复位，避免抖动
        setTimeout(() => {
          this.refreshDistance = 0;
        }, 500);
      }
    },

    /**
     * 手动触发加载更多
     */
    async loadMore() {
      await this.loadMoreData();
    },

    /**
     * 重新加载数据
     */
    async reload() {
      this.resetState();
      await this.loadInitialData();
    },
  },
};
</script>
<style lang="less" scoped>
.dynamic-scroller-container {
  height: 100%;
  width: 100%;
  position: relative;
}

.refresh-wrapper {
  height: 100%;
  width: 100%;
  position: relative;
  // 添加鼠标事件相关样式
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}

.refresh-indicator {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
  overflow: hidden;
  transform: translateY(-100%);
  // transition: height 0.2s ease-out;
}

.refresh-text {
  font-size: 26px;
  color: #999;
}

.virtual-scroller {
  /* 开启硬件加速 */
  -webkit-overflow-scrolling: touch;
  /* 禁用回弹效果 */
  overscroll-behavior: none;
  height: 100%;
  width: 100%;
}

.virtual-scroller-item {
  /* 确保项目正确渲染 */
  contain: layout style paint;
}

/* 优化滚动性能 */
.virtual-scroller::-webkit-scrollbar {
  width: 0;
  background: transparent;
}

/* 加载状态样式优化 */
.transition {
  transition: opacity 0.3s ease;
}

/* 空状态样式 */
.transition:has(span) {
  opacity: 0.8;
}
</style>

如何在元素间实现间隔

1.通过样式边距

<RecycleScroller
  :item-style="() => ({ marginBottom: '10px' })"
/>

2.添加额外元素

<template> 
// ... existing code ..
  <div class="pb-20 box-border h-full">
    <DynamicScrollerList
      class="h-full mx-30 rounded-8 bc-white overflow-y-auto"
      afterClass="bc-grey mt-10"
      :request="getList"
    >
      <template #item="{ item }">
        <div class="px-30 py-20 flex-col fs-26">
          {{ item.content }}
        </div>
        <div class="border-b mx-30"></div>
      </template>
    </DynamicScrollerList>
  </div>
// ... existing code ...
</template>
// ... existing code ...
<style lang="less" scoped>
::v-deep .vue-recycle-scroller__item-wrapper > *:last-child {
  .border-b {
    border: none;
  }
}
</style>