cbvirtua 1.0.105 → 1.0.107

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/plugins/observe-dom.md

@@ -0,0 +1,53 @@
+# observe-dom
+
+开启对 content 以及 content 子元素 DOM 改变的探测。当插件被使用后，当这些 DOM 元素发生变化时，将会触发 scroll 的 refresh 方法。 observe-dom 插件具有以下几个特性：
+
+- 针对改变频繁的 CSS 属性，增加 debounce
+- 如果改变发生在 scroll 动画过程中，则不会触发 refresh
+
+## 安装
+
+```bash
+npm install @better-scroll/observe-dom --save
+
+// or
+
+yarn add @better-scroll/observe-dom
+```
+
+## 使用
+
+```js
+  import BScroll from '@better-scroll/core'
+  import ObserveDOM from '@better-scroll/observe-dom'
+  BScroll.use(ObserveDOM)
+
+  new BScroll('.bs-wrapper', {
+    //...
+    observeDOM: true // 开启 observe-dom 插件
+  })
+```
+
+## 示例
+
+  <demo qrcode-url="observe-dom/" :render-code="true">
+    <template slot="code-template">
+      <<< @/examples/vue/components/observe-dom/default.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/observe-dom/default.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/observe-dom/default.vue?style
+    </template>
+    <observe-dom-default slot="demo"></observe-dom-default>
+  </demo>
+
+
+:::warning 注意
+由于插件的内部实现使用的是 [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)，它无法探测到 img 标签的是否加载完成，因此对于 content 内部含有不确定高度的图片，需要等图片加载完成再调用 bs.refresh() 来重新计算可滚动尺寸。如果浏览器不支持 MutationObserver，插件内部的降级方案是每秒重新计算可滚动的尺寸。
+:::
+
+:::tip 提示
+v2.1.0 版本，新增 [observe-image](./observe-image) 插件来探测 img 标签的加载，因此这两者可以搭配起来，补齐**主动刷新**的能力来更新 BetterScroll 每次滚动的宽度或者高度。
+:::

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/plugins/observe-image.md

@@ -0,0 +1,78 @@
+# observe-image <Badge text='2.1.0' />
+
+## 介绍
+
+开启对 wrapper 子元素中图片元素的加载的探测。无论图片的加载成功与否，都会自动调用 BetterScroll 的 refresh 方法来重新计算可滚动的宽度或者高度，新增于 v2.1.0 版本。
+
+:::tip 提示
+对于已经用 CSS 确定图片宽高的场景，不应该使用该插件，因为每次调用 refresh 对性能会有影响。只有在**图片的宽度或者高度不确定**的情况下，你才需要它。
+:::
+
+## 安装
+
+```bash
+npm install @better-scroll/observe-image --save
+
+// or
+
+yarn add @better-scroll/observe-image
+```
+
+## 使用
+
+```js
+  import BScroll from '@better-scroll/core'
+  import ObserveImage from '@better-scroll/observe-image'
+  BScroll.use(ObserveImage)
+
+  new BScroll('.bs-wrapper', {
+    //...
+    observeImage: true // 开启 observe-image 插件
+  })
+```
+
+## 示例
+
+  <demo qrcode-url="observe-image/" :render-code="true">
+    <template slot="code-template">
+      <<< @/examples/vue/components/observe-image/default.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/observe-image/default.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/observe-image/default.vue?style
+    </template>
+    <observe-image-default slot="demo"></observe-image-default>
+  </demo>
+
+## observeImage 选项对象
+
+:::tip 提示
+当 observeImage 配置为 true 的时候，插件内部使用的是默认的插件选项对象。
+
+```js
+const bs = new BScroll('.wrapper', {
+  observeImage: true
+})
+
+// 相当于
+
+const bs = new BScroll('.wrapper', {
+  observeImage: {
+    debounceTime: 100 // ms
+  }
+})
+```
+:::
+
+### debounceTime
+
+  - **类型：** `number`
+  - **默认值：** `100`
+
+    探测到图片加载成功或者失败后，过 debounceTime 毫秒后才会调用 refresh 方法，重新计算可滚动的高度或者宽度，如果在 debounceTime 毫秒内有多张图片加载成功或者失败，**只会调用一次 refresh**。
+
+    :::tip 提示
+    当 debounceTime 为 0 的时候，会立马调用 **refresh** 方法，而不是使用 **setTimeout**。
+    :::

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/plugins/pulldown.md

@@ -0,0 +1,205 @@
+# pulldown
+
+## 介绍
+
+pulldown 插件为 BetterScroll 扩展下拉刷新的能力。
+
+## 安装
+
+```bash
+npm install @better-scroll/pull-down --save
+
+// or
+
+yarn add @better-scroll/pull-down
+```
+
+## 使用
+
+首先引入 pulldown 插件，并通过静态方法 `BScroll.use()` 初始化插件
+
+```js
+import BScroll from '@better-scroll/core'
+import PullDown from '@better-scroll/pull-down'
+
+BScroll.use(PullDown)
+```
+
+然后，实例化 BetterScroll 时需要传入[ pulldown 配置项](./pulldown.html#pulldownrefresh-选项对象)。
+
+```js
+new BScroll('.bs-wrapper', {
+  pullDownRefresh: true
+})
+```
+
+## 示例
+
+- **基础使用**
+
+<demo qrcode-url="pulldown/default" :render-code="true">
+  <template slot="code-template">
+    <<< @/examples/vue/components/pulldown/default.vue?template
+  </template>
+  <template slot="code-script">
+    <<< @/examples/vue/components/pulldown/default.vue?script
+  </template>
+  <template slot="code-style">
+    <<< @/examples/vue/components/pulldown/default.vue?style
+  </template>
+  <pulldown-default slot="demo"></pulldown-default>
+</demo>
+
+- **仿新浪微博 <Badge text='2.4.0' />**
+
+<demo qrcode-url="pulldown/sina">
+  <template slot="code-template">
+    <<< @/examples/vue/components/pulldown/sina-weibo.vue?template
+  </template>
+  <template slot="code-script">
+    <<< @/examples/vue/components/pulldown/sina-weibo.vue?script
+  </template>
+  <template slot="code-style">
+    <<< @/examples/vue/components/pulldown/sina-weibo.vue?style
+  </template>
+  <pulldown-sina-weibo slot="demo"></pulldown-sina-weibo>
+</demo>
+
+为了拉齐客户端的交互效果，在 v2.4.0 版本，pulldown 内部进行了功能的改造并且兼容以前的版本，在一次 pulldown 的操作过程中，内部存在三个流转的状态，并且状态是不可逆的。分别如下：
+
+1. **default**
+
+  初始状态。
+
+2. **moving**
+
+  移动状态，这个状态代表用户的手指正在操控 BetterScroll，手指未移开，在这种状态下，BetterScroll 会派发两个事件。
+
+  - **enterThreshold**
+
+    当 BetterScroll 滚动到 pulldown 的 threshold 阈值区域**之内**的时候派发，在这个事件内部，你可以做文案初始化的逻辑，比如提示用户“下拉刷新”
+  
+  - **leaveThreshold**
+
+    当 BetterScroll 滚动到 pulldown 的 threshold 阈值区域**之外**的时候派发。你可以提示用户“手指释放刷新”
+
+3. **fetching**
+
+  手指移开的瞬间，触发 pullingDown 事件，执行获取数据的逻辑
+
+状态的变换只可能是 `default -> moving -> fetching` 或者是 `default -> moving`，后者代表用户的手指在释放的瞬间，没有满足触发 pullingDown 事件的条件。
+
+
+
+## pullDownRefresh 选项对象
+
+### threshold
+
+  - **类型：** `number`
+  - **默认值：** `90`
+
+    配置顶部下拉的距离来决定刷新时机。
+
+### stop
+
+  - **类型：** `number`
+  - **默认值：** `40`
+
+    回弹悬停的距离。BetterScroll 在派发 `pullingDown` 钩子之后，会立马执行回弹悬停动画。
+
+:::tip 提示
+当 pullDownRefresh 配置为 true 的时候，插件内部使用的是默认的插件选项对象。
+
+```js
+const bs = new BScroll('.wrapper', {
+  pullDownRefresh: true
+})
+
+// 相当于
+
+const bs = new BScroll('.wrapper', {
+  pullDownRefresh: {
+    threshold: 90,
+    stop: 40
+  }
+})
+```
+:::
+
+## 实例方法
+
+:::tip 提示
+以下方法皆已代理至 BetterScroll 实例，例如：
+
+```js
+import BScroll from '@better-scroll/core'
+import PullDown from '@better-scroll/pull-down'
+
+BScroll.use(PullDown)
+
+const bs = new BScroll('.bs-wrapper', {
+  pullDownRefresh: true
+})
+
+bs.finishPullDown()
+bs.openPullDown({})
+bs.autoPullDownRefresh()
+```
+:::
+
+### `finishPullDown()`
+
+  - **介绍**：结束下拉刷新行为。
+
+::: warning 注意
+每次触发 `pullingDown` 钩子后，你应该**主动调用** `finishPullDown()` 告诉 BetterScroll 准备好下一次的 pullingDown 钩子。
+:::
+
+### `openPullDown(config: PullDownRefreshOptions = {})`
+
+  - **介绍**：动态开启下拉刷新功能。
+  - **参数**：
+    - `{ PullDownRefreshOptions } config`：修改 pulldown 插件的选项对象
+    - `PullDownRefreshOptions`：类型如下
+    ```typescript
+    export type PullDownRefreshOptions = Partial<PullDownRefreshConfig> | true
+
+    export interface PullDownRefreshConfig {
+      threshold: number
+      stop: number
+    }
+    ```
+  - **返回值**：无
+
+::: warning 注意
+openPullDown 方法应该配合 closePullDown 一起使用，因为在 pulldown 插件的生成过程当中，已经**自动监测了下拉刷新的动作**。
+:::
+
+### `closePullDown()`
+
+  - **介绍**：动态关闭下拉刷新功能。
+
+### `autoPullDownRefresh()`
+
+  - **介绍**：自动执行下拉刷新。
+
+## 事件
+
+### `pullingDown`
+
+- **参数**：无
+- **触发时机**：当顶部下拉的距离大于 `threshold` 值时，触发一次 `pullingDown` 钩子。
+
+::: danger 危险
+监测到下拉刷新的动作之后，`pullingDown` 钩子的消费机会只有一次，因此你需要调用 `finishPullDown()` 来告诉 BetterScroll 来提供下一次 `pullingDown` 钩子的消费机会。
+:::
+
+### `enterThreshold` <Badge text='2.4.0' />
+
+- **参数**：无
+- **触发时机**：当 pulldown 正处于 moving 状态，并且**进入** threshold 区域的瞬间。
+
+### `leaveThreshold` <Badge text='2.4.0' />
+
+- **参数**：无
+- **触发时机**：当 pulldown 正处于 moving 状态，并且**离开** threshold 区域的瞬间。

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/plugins/pullup.md

@@ -0,0 +1,144 @@
+# pullup
+
+## 介绍
+
+pullup 插件为 BetterScroll 扩展上拉加载的能力。
+
+## 安装
+
+```bash
+npm install @better-scroll/pull-up --save
+
+// or
+
+yarn add @better-scroll/pull-up
+```
+
+## 使用
+
+通过静态方法 `BScroll.use()` 注册插件
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Pullup from '@better-scroll/pull-up'
+
+  BScroll.use(Pullup)
+```
+
+然后，实例化 BetterScroll 时需要传入[ pullup 配置项](./pullup.html#pullupload-选项对象)。
+
+```js
+  new BScroll('.bs-wrapper', {
+    pullUpLoad: true
+  })
+```
+## 示例
+
+<demo qrcode-url="pullup/" :render-code="true">
+  <template slot="code-template">
+    <<< @/examples/vue/components/pullup/default.vue?template
+  </template>
+  <template slot="code-script">
+    <<< @/examples/vue/components/pullup/default.vue?script
+  </template>
+  <template slot="code-style">
+    <<< @/examples/vue/components/pullup/default.vue?style
+  </template>
+  <pullup-default slot="demo"></pullup-default>
+</demo>
+
+## pullUpLoad 选项对象
+
+### threshold
+
+  - **类型：** `number`
+  - **默认值：** `0`
+
+    触发上拉事件的阈值。
+
+
+:::tip 提示
+当 pullUpLoad 配置为 true 的时候，插件内部使用的是默认的插件选项对象。
+
+```js
+const bs = new BScroll('.wrapper', {
+  pullUpLoad: true
+})
+
+// 相当于
+
+const bs = new BScroll('.wrapper', {
+  pullUpLoad: {
+    threshold: 0
+  }
+})
+```
+:::
+
+## 实例方法
+
+:::tip 提示
+以下方法皆已代理至 BetterScroll 实例，例如：
+
+```js
+import BScroll from '@better-scroll/core'
+import PullUp from '@better-scroll/pull-up'
+
+BScroll.use(PullUp)
+
+const bs = new BScroll('.bs-wrapper', {
+  pullUpLoad: true
+})
+
+bs.finishPullUp()
+bs.openPullUp({})
+bs.closePullUp()
+```
+:::
+
+### `finishPullUp()`
+
+  - **介绍**：结束上拉加载行为。
+
+  ::: warning 注意
+  每次触发 `pullingUp` 钩子后，你应该**主动调用** `finishPullUp()` 告诉 BetterScroll 准备好下一次的 pullingUp 钩子。
+  :::
+
+### `openPullUp(config: PullUpLoadOptions = {})`
+
+  - **介绍**：动态开启上拉功能。
+  - **参数**：
+    - `{ PullUpLoadOptions } config`：修改 pullup 插件的选项对象
+    - `PullUpLoadOptions`：类型如下
+    ```typescript
+    export type PullUpLoadOptions = Partial<PullUpLoadConfig> | true
+
+    export interface PullUpLoadConfig {
+      threshold: number
+    }
+    ```
+
+  ::: warning 注意
+  openPullUp 方法应该配合 closePullUp 一起使用，因为在 pullup 插件的生成过程当中，已经**自动监测了上拉加载的动作**。
+  :::
+
+### `closePullUp()`
+
+  - **介绍**：关闭上拉加载功能。
+
+### `autoPullUpLoad()`
+
+  - **介绍**：自动执行上拉加载。
+
+## 事件
+
+### `pullingUp`
+
+  - **参数**：无
+  - **触发时机**：当距离滚动到底部小于 `threshold` 值时，触发一次 `pullingUp` 事件。
+
+  > 当 threshold 为正数，代表距离滚动边界 threshold 像素的时候触发 `pullingUp`，反之，代表越过滚动边界才会触发事件
+
+  ::: danger 警告
+  监测到上拉刷新的动作之后，`pullingUp` 事件的消费机会只有一次，因此你需要调用 `finishPullUp()` 来告诉 BetterScroll 来提供下一次 `pullingUp` 事件的消费机会。
+  :::

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/plugins/scroll-bar.md

@@ -0,0 +1,229 @@
+# scrollbar
+
+## 介绍
+
+scrollbar 插件为 BetterScroll 提供了样式美观的滚动条。
+
+:::tip 提示
+从 v2.2.0 开始，用户可以提供自定义的滚动条。
+:::
+
+## 安装
+
+```bash
+npm install @better-scroll/scroll-bar --save
+
+// or
+
+yarn add @better-scroll/scroll-bar
+```
+
+## 使用
+
+首先引入 scrollbar 插件，并通过静态方法 `BScroll.use()` 注册插件
+
+```js
+  import BScroll from '@better-scroll/core'
+  import ScrollBar from '@better-scroll/scroll-bar'
+
+  BScroll.use(ScrollBar)
+```
+
+接着在 `options` 传入正确的配置。
+
+```js
+  new BScroll('.bs-wrapper', {
+    scrollY: true,
+    scrollbar: true
+  })
+```
+## 示例
+
+  - **竖向滚动条**
+
+    <demo qrcode-url="scrollbar/vertical" :render-code="true">
+      <template slot="code-template">
+        <<< @/examples/vue/components/scrollbar/vertical.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/scrollbar/vertical.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/scrollbar/vertical.vue?style
+      </template>
+      <scrollbar-vertical slot="demo"></scrollbar-vertical>
+    </demo>
+
+  - **横向滚动条**
+
+    <demo qrcode-url="scrollbar/horizontal" :render-code="true">
+      <template slot="code-template">
+        <<< @/examples/vue/components/scrollbar/horizontal.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/scrollbar/horizontal.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/scrollbar/horizontal.vue?style
+      </template>
+      <scrollbar-horizontal slot="demo"></scrollbar-horizontal>
+    </demo>
+
+  - **用户定制化滚动条**
+
+    <demo qrcode-url="scrollbar/custom" :render-code="true">
+      <template slot="code-template">
+        <<< @/examples/vue/components/scrollbar/custom.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/scrollbar/custom.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/scrollbar/custom.vue?style
+      </template>
+      <scrollbar-custom slot="demo"></scrollbar-custom>
+    </demo>
+
+  - **搭配鼠标滚轮**
+
+    <demo qrcode-url="scrollbar/mousewheel" :render-code="true">
+      <template slot="code-template">
+        <<< @/examples/vue/components/scrollbar/mousewheel.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/scrollbar/mousewheel.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/scrollbar/mousewheel.vue?style
+      </template>
+      <scrollbar-mousewheel slot="demo"></scrollbar-mousewheel>
+    </demo>
+
+## scrollbar 选项对象
+
+### fade
+
+  - **类型**：`boolean`
+  - **默认值**：`true`
+
+  当滚动停止的时候，滚动条渐隐。
+
+### interactive
+
+  - **类型**：`boolean`
+  - **默认值**：`false`
+
+  滚动条是否可以交互。
+
+### customElements <Badge text="2.2.0" />
+
+  - **类型**：`HTMLElement[]`
+  - **默认值**：`[]`
+
+  用户提供自定义的滚动条。
+
+  ```js
+  // 横向滚动条
+  const horizontalEl = document.getElementById('用户自定义的滚动条')
+  new BScroll('.bs-wrapper', {
+    scrollY: true,
+    scrollbar: {
+      customElements: [horizontalEl]
+    }
+  })
+  // 竖向滚动条
+  const verticalEl = document.getElementById('用户自定义的滚动条')
+  new BScroll('.bs-wrapper', {
+    scrollY: false,
+    scrollX: true,
+    scrollbar: {
+      customElements: [verticalEl]
+    }
+  })
+  // 双向滚动条
+  const horizontalEl = document.getElementById('用户自定义的滚动条')
+  const verticalEl = document.getElementById('用户自定义的滚动条')
+  new BScroll('.bs-wrapper', {
+    freeScroll: true,
+    scrollbar: {
+      // 当滚动条是 2 个的时候，数组第一个元素是横向滚动条
+      customElements: [horizontalEl, verticalEl]
+    }
+  })
+  ```
+
+### minSize <Badge text="2.2.0" />
+
+  - **类型**：`number`
+  - **默认值**：`8`
+
+  滚动条的最小尺寸，当用户提供了自定义的滚动条，该配置无效。
+
+### scrollbarTrackClickable <Badge text="2.2.0" />
+
+  - **类型**：`boolean`
+  - **默认值**：`false`
+
+  滚动条轨道是否允许点击。
+
+  **注意**：当开启该配置的时候，请保证 BetterScroll Options 的 `click` 为 true，否则无法触发点击事件。[详细原因在这](../FAQ/diagnosis.html#【问题四】为什么-betterscroll-content-内部的所有的-click-事件的侦听器都不触发？)
+
+  ```js
+  new BScroll('.bs-wrapper', {
+    scrollY: true,
+    click: true // 必不可少
+    scrollbar: {
+      scrollbarTrackClickable: true
+    }
+  })
+  ```
+
+### scrollbarTrackOffsetType <Badge text="2.2.0" />
+
+  - **类型**：`string`
+  - **默认值**：`'step'`
+
+  滚动条轨道被点击之后，滚动距离的计算方式，默认与浏览器的表现形式一样，可以配置为 `'clickedPoint'`，代表滚动条滚动至点击的位置。
+
+### fadeInTime <Badge text="2.4.0" />
+
+  - **类型**：`number`
+  - **默认值**：`250`
+
+  滚动条渐显的动画时长。
+
+### fadeOutTime <Badge text="2.4.0" />
+
+  - **类型**：`number`
+  - **默认值**：`500`
+
+  滚动条渐隐的动画时长。
+
+
+:::tip 提示
+当 scrollbar 配置为 true 的时候，插件内部使用的是默认的插件选项对象。
+
+```js
+const bs = new BScroll('.wrapper', {
+  scrollbar: true
+})
+
+// 相当于
+
+const bs = new BScroll('.wrapper', {
+  scrollbar: {
+    fade: true,
+    interactive: false,
+    // 以下配置项 v2.2.0 才支持
+    customElements: [],
+    minSize: 8,
+    scrollbarTrackClickable: false,
+    scrollbarTrackOffsetType: 'step',
+    scrollbarTrackOffsetTime: 300,
+    // 以下配置项 v2.4.0 才支持
+    fadeInTime: 250,
+    fadeOutTime: 500
+  }
+})
+```
+:::