Cb-vue-virtual-scroller NPM

Vue Virtual Scroller 中文翻译文档

版本说明

这是一个修改版的 Vue Virtual Scroller，修改了滚动到底的函数 scrollToBottom () 实现。使其可以在滚动到底的时候实现平滑滚动，而不是瞬间到底。
安装

npm install --save cb-vue-virtual-scroller@next

yarn add cb-vue-virtual-scroller@next

默认导入

安装所有组件：

import VueVirtualScroller from 'cb-vue-virtual-scroller'

app.use(VueVirtualScroller)

使用特定组件：

import { RecycleScroller } from 'cb-vue-virtual-scroller'

app.component('RecycleScroller', RecycleScroller)

⚠️ 导入包时应包含以下行：

import 'cb-vue-virtual-scroller/dist/vue-virtual-scroller.css'

浏览器

<link rel="stylesheet" href="cb-vue-virtual-scroller/dist/vue-virtual-scroller.css"/>

<script src="vue.js"></script>
<script src="cb-vue-virtual-scroller/dist/vue-virtual-scroller.min.js"></script>

安装组件：

app.use(VueVirtualScroller)

或使用自定义名称注册：

app.component('RecycleScroller', VueVirtualScroller.RecycleScroller)

使用

cb-vue-virtual-scroller 提供了几个组件：

RecycleScroller 是一个仅渲染列表中可见项目的组件。它还重用组件和 DOM 元素，以尽可能高效和高性能地运行。

DynamicScroller 是一个包装 RecycleScroller 组件并扩展其功能以包括动态大小管理的组件。其主要用例是在您无法提前知道项目大小时。Dynamic Scroller 在滚动过程中渲染新项目时自动“发现”项目尺寸。

DynamicScrollerItem 必须包装在 DynamicScroller 中的每个项目，以处理尺寸计算。

IdState 是一个混入，用于简化在 RecycleScroller 中重用组件的本地状态管理。

RecycleScroller

RecycleScroller 是一个虚拟滚动器，仅渲染可见项目。当用户滚动时，RecycleScroller 重用所有组件和 DOM 节点以保持最佳性能。

基本用法

使用作用域插槽渲染列表中的每个项目：

<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>

重要注意事项

⚠️ 您需要设置虚拟滚动器元素和项目元素的大小（例如，通过 CSS）。除非您使用可变大小模式，否则所有项目应具有相同的高度（或在水平模式下的宽度）以防止显示故障。
⚠️ 如果项目是对象，滚动器需要能够识别它们。默认情况下，它将查找项目上的 id 字段。如果您使用其他字段名称，可以通过 keyField 属性进行配置。
不建议在 RecycleScroller 中使用函数式组件，因为组件会被重用（因此实际上会更慢）。
列表项组件必须对 item 属性的更新具有反应性，而无需重新创建（使用计算属性或观察者来正确响应属性更改！）。
您不需要在列表内容上设置 key（但您应该在所有嵌套的 <img> 元素上设置，以防止加载故障）。
浏览器对 DOM 元素的大小有限制，这意味着当前虚拟滚动器无法显示超过约 500k 个项目，具体取决于浏览器。
由于 DOM 元素被重用于项目，建议使用提供的 hover 类而不是 :hover 状态选择器定义悬停样式（例如 .vue-recycle-scroller__item-view.hover 或 .hover .some-element-inside-the-item-view）。

它是如何工作的？

RecycleScroller 创建视图池以向用户呈现可见项目。
视图持有一个渲染的项目，并在其池中重用。
对于每种类型的项目，将创建一个新的池，以便为相同类型重用相同的组件（和 DOM 树）。
如果视图离开屏幕，它们可以被停用，并且可以随时重用于新可见项目。

以下是 RecycleScroller 在垂直模式下的内部结构：

<RecycleScroller>
  <!-- 包装元素，具有预先计算的总高度 -->
  <wrapper
    :style="{ height: computedTotalHeight + 'px' }"
  >
    <!-- 每个视图被转换到计算的位置 -->
    <view
      v-for="view of pool"
      :style="{ transform: 'translateY(' + view.computedTop + 'px)' }"
    >
      <!-- 您的元素将在此处呈现 -->
      <slot
        :item="view.item"
        :index="view.nr.index"
        :active="view.nr.used"
      />
    </view>
  </wrapper>
</RecycleScroller>

当用户在 RecycleScroller 中滚动时，视图主要只是移动以填充新的可见空间，并更新默认插槽属性。这样，我们获得了最小的组件/元素创建和销毁，并利用 Vue 虚拟 DOM 差异算法的全部功能来优化 DOM 操作！

属性

items：您希望在滚动器中显示的项目列表。
direction（默认：'vertical'）：滚动方向，可以是 'vertical' 或 'horizontal'。
itemSize（默认：null）：项目的显示高度（或在水平模式下的宽度），以像素为单位，用于计算滚动大小和位置。如果设置为 null（默认值），将使用可变大小模式。
gridItems：在同一行上显示多个项目以创建网格。您必须为 itemSize 设置一个值才能使用此属性（不支持动态大小）。
itemSecondarySize：项目在网格中的大小（在垂直模式下为宽度，在水平模式下为高度），以像素为单位。当设置了 gridItems 时使用。如果未设置 itemSecondarySize，将使用 itemSize 的值。
minItemSize：如果项目的高度（或在水平模式下的宽度）未知，则使用的最小大小。
sizeField（默认：'size'）：在可变大小模式下用于获取项目大小的字段。
typeField（默认：'type'）：用于区分列表中不同类型组件的字段。对于每种不同类型，将创建一个重用项目的池。
keyField（默认：'id'）：用于标识项目并优化管理渲染视图的字段。
pageMode（默认：false）：启用页面模式。
prerender（默认：0）：为服务器端渲染（SSR）渲染固定数量的项目。
buffer（默认：200）：在滚动可见区域的边缘添加的像素数量，以开始渲染更远的项目。
emitUpdate（默认：false）：每次虚拟滚动器内容更新时发出 'update' 事件（可能影响性能）。
updateInterval（默认：0）：滚动后检查视图更新的间隔时间（以毫秒为单位）。当设置为 0 时，检查将在下一个动画帧期间进行。
listClass（默认：''）：添加到项目列表包装器的自定义类。
itemClass（默认：''）：添加到每个项目的自定义类。
listTag（默认：'div'）：要渲染为列表包装器的元素。
itemTag（默认：'div'）：要渲染为列表项的元素（默认插槽内容的直接父级）。

事件

resize：当滚动器大小更改时发出。
visible：当滚动器认为自己在页面中可见时发出。
hidden：当滚动器在页面中隐藏时发出。
update (startIndex, endIndex, visibleStartIndex, visibleEndIndex)：每次视图更新时发出，仅当 emitUpdate 属性为 true 时。
scroll-start：当第一个项目被渲染时发出。
scroll-end：当最后一个项目被渲染时发出。

默认作用域插槽属性

item：在视图中渲染的项目。
index：反映每个项目在 items 数组中的位置。
active：视图是否处于活动状态。活动视图被视为可见并由 RecycleScroller 定位。非活动视图不被视为可见，并且对用户隐藏。如果视图处于非活动状态，应跳过任何与渲染相关的计算。

其他插槽

<main>
  <slot name="before"></slot>
  <wrapper>
    <!-- 重用的视图池在此处 -->
    <slot name="empty"></slot>
  </wrapper>
  <slot name="after"></slot>
</main>

示例：

<RecycleScroller
  class="scroller"
  :items="list"
  :item-size="32"
>
  <template #before>
    嘿！我是显示在项目之前的消息！
  </template>

  <template v-slot="{ item }">
    <div class="user">
      {{ item.name }}
    </div>
  </template>
</RecycleScroller>

页面模式

页面模式扩展了虚拟滚动器，并使用页面视口来计算哪些项目是可见的。这样，您可以在一个大页面中使用它，并在其前后添加 HTML 元素（如页眉和页脚）。将 page-mode 属性设置为 true：

<header>
  <menu></menu>
</header>

<RecycleScroller page-mode>
  <!-- ... -->
</RecycleScroller>

<footer>
  版权所有 2017 - Cat
</footer>

可变大小模式

⚠️ 这种模式在项目较多时可能会影响性能。请谨慎使用。

如果 itemSize 属性未设置或设置为 null，虚拟滚动器将切换到可变大小模式。然后，您需要在项目对象上公开一个数字字段，该字段表示项目元素的大小。

⚠️ 您仍然需要使用 CSS 正确设置项目的大小（例如，通过类）。

使用 sizeField 属性（默认为 'size'）来设置滚动器用于获取每个项目大小的字段。

示例：

const items = [
  {
    id: 1,
    label: 'Title',
    size: 64,
  },
  {
    id: 2,
    label: 'Foo',
    size: 32,
  },
  {
    id: 3,
    label: 'Bar',
    size: 32,
  },
]

缓冲区

您可以在虚拟滚动器上设置 buffer 属性（以像素为单位），以扩展在确定可见项目时考虑的视口。例如，如果您设置了 1000 像素的缓冲区，虚拟滚动器将开始渲染滚动器可见区域底部以下 1000 像素的项目，并将保留可见区域顶部以上 1000 像素的项目。

默认值为 200。

<RecycleScroller :buffer="200" />

服务器端渲染

可以将 prerender 属性设置为虚拟滚动器中服务器上渲染的项目数量：

<RecycleScroller
  :items="items"
  :item-size="42"
  :prerender="10"
>

DynamicScroller

这与 RecycleScroller 的工作方式相同，但它可以渲染大小未知的项目！

基本用法

<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>

重要注意事项

minItemSize 是项目初始渲染所必需的。
DynamicScroller 不会自行检测大小变化，但您可以在 DynamicScrollerItem 上使用 size-dependencies 放置可能影响项目大小的值。
您不需要在项目上有一个 size 字段。

属性

扩展了所有 RecycleScroller 属性。

不建议更改 sizeField 属性，因为所有大小管理都是在内部完成的。

事件

扩展了所有 RecycleScroller 事件。

默认作用域插槽属性

扩展了所有 RecycleScroller 作用域插槽属性。

其他插槽

扩展了所有 RecycleScroller 其他插槽。

DynamicScrollerItem

应包装在 DynamicScroller 中的所有项目的组件。

属性

item（必需）：在滚动器中渲染的项目。
active（必需）：RecycleScroller 中的持有视图是否处于活动状态。将防止不必要的大小重新计算。
sizeDependencies：可能影响项目大小的值。此属性将被监视，如果某个值发生变化，大小将重新计算。推荐使用而不是 watchData。
watchData（默认：false）：深度监视 item 的变化以重新计算大小（不推荐，可能影响性能）。
tag（默认：'div'）：用于渲染组件的元素。
emitResize（默认：false）：每次重新计算大小时发出 resize 事件（可能影响性能）。

事件

resize：每次重新计算大小时发出，仅当 emitResize 属性为 true 时。

IdState

这是一个方便的混入，可以替换在 RecycleScroller 中渲染的组件中的 data。

为什么这很有用？

由于 RecycleScroller 中的组件是重用的，您不能直接使用 Vue 标准的 data 属性：否则它们将与列表中的不同项目共享！

IdState 将提供一个 idState 对象，相当于 $data，但它与具有其标识符的单个项目相关联（您可以通过 idProp 参数更改哪个字段）。

示例

在此示例中，我们使用 item 的 id 来为项目提供“作用域”状态：

<template>
  <div class="question">
    <p>{{ item.question }}</p>
    <button @click="idState.replyOpen = !idState.replyOpen">回复</button>
    <textarea
      v-if="idState.replyOpen"
      v-model="idState.replyText"
      placeholder="输入您的回复"
    />
  </div>
</template>

<script>
import { IdState } from 'cb-vue-virtual-scroller'

export default {
  mixins: [
    IdState({
      // 您可以自定义此项
      idProp: vm => vm.item.id,
    }),
  ],

  props: {
    // 列表中的项目
    item: Object,
  },

  // 这替代了 data () { ... }
  idState () {
    return {
      replyOpen: false,
      replyText: '',
    }
  },
}
</script>