cbvirtua 1.0.106 → 1.0.107

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

@@ -0,0 +1,283 @@
+# mouse-wheel
+
+mouseWheel 扩展 BetterScroll 鼠标滚轮的能力。
+
+# 安装
+
+```bash
+npm install @better-scroll/mouse-wheel --save
+
+// or
+
+yarn add @better-scroll/mouse-wheel
+```
+
+:::tip
+目前支持鼠标滚轮有：core、slide、wheel、pullup、pulldown
+:::
+
+## 基础使用
+
+为了开启鼠标滚动功能，你需要首先引入 mouseWheel 插件，通过静态方法 `BScroll.use()` 注册插件，最后传入正确的 [mouseWheel 选项对象](./mouse-wheel.html#mousewheel-选项对象)
+
+```js
+  import BScroll from '@better-scroll/core'
+  import MouseWheel from '@better-scroll/mouse-wheel'
+  BScroll.use(MouseWheel)
+
+  new BScroll('.bs-wrapper', {
+    //...
+    mouseWheel: {
+      speed: 20,
+      invert: false,
+      easeTime: 300
+    }
+  })
+```
+
+- **纵向普通滚动示例**
+
+  <demo :hide-qrcode="true" qrcode-url="mouse-wheel/vertical-scroll" :render-code="true">
+    <template slot="code-template">
+      <<< @/examples/vue/components/mouse-wheel/vertical-scroll.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/mouse-wheel/vertical-scroll.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/mouse-wheel/vertical-scroll.vue?style
+    </template>
+    <mouse-wheel-vertical-scroll slot="demo"></mouse-wheel-vertical-scroll>
+  </demo>
+
+- **横向普通滚动示例**
+
+  <demo :hide-qrcode="true" qrcode-url="mouse-wheel/horizontal-scroll">
+    <template slot="code-template">
+      <<< @/examples/vue/components/mouse-wheel/horizontal-scroll.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/mouse-wheel/horizontal-scroll.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/mouse-wheel/horizontal-scroll.vue?style
+    </template>
+    <mouse-wheel-horizontal-scroll slot="demo"></mouse-wheel-horizontal-scroll>
+  </demo>
+
+## 进阶使用
+
+mouseWheel 插件还可以搭配其他的插件，为其增加鼠标滚轮的操作。
+
+- **mouseWheel & slide**
+
+  通过鼠标滚轮操作 [slide](./slide.html)。
+
+  - **横向 slide 示例**
+
+    <demo :hide-qrcode="true" qrcode-url="mouse-wheel/horizontal-slide">
+      <template slot="code-template">
+        <<< @/examples/vue/components/mouse-wheel/horizontal-slide.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/mouse-wheel/horizontal-slide.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/mouse-wheel/horizontal-slide.vue?style
+      </template>
+      <mouse-wheel-horizontal-slide slot="demo"></mouse-wheel-horizontal-slide>
+    </demo>
+
+  - **纵向 slide 示例**
+
+    <demo :hide-qrcode="true" qrcode-url="mouse-wheel/vertical-slide">
+      <template slot="code-template">
+        <<< @/examples/vue/components/mouse-wheel/vertical-slide.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/mouse-wheel/vertical-slide.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/mouse-wheel/vertical-slide.vue?style
+      </template>
+      <mouse-wheel-vertical-slide slot="demo"></mouse-wheel-vertical-slide>
+    </demo>
+
+- **mouseWheel & pullup**
+
+  通过鼠标触发上拉加载 [pullup](./pullup.html)。
+
+  <demo :hide-qrcode="true" qrcode-url="mouse-wheel/pullup">
+    <template slot="code-template">
+      <<< @/examples/vue/components/mouse-wheel/pullup.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/mouse-wheel/pullup.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/mouse-wheel/pullup.vue?style
+    </template>
+    <mouse-wheel-pullup slot="demo"></mouse-wheel-pullup>
+  </demo>
+
+- **mouseWheel & pulldown**
+
+  通过鼠标触发下拉加载 [pulldown](./pulldown.html)。
+
+  <demo :hide-qrcode="true" qrcode-url="mouse-wheel/pulldown">
+    <template slot="code-template">
+      <<< @/examples/vue/components/mouse-wheel/pulldown.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/mouse-wheel/pulldown.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/mouse-wheel/pulldown.vue?style
+    </template>
+    <mouse-wheel-pulldown slot="demo"></mouse-wheel-pulldown>
+  </demo>
+
+- **mouseWheel & wheel**
+
+  通过鼠标触发 [wheel](./wheel.html)。
+
+  <demo :hide-qrcode="true" qrcode-url="mouse-wheel/picker">
+    <template slot="code-template">
+      <<< @/examples/vue/components/mouse-wheel/picker.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/mouse-wheel/picker.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/mouse-wheel/picker.vue?style
+    </template>
+    <mouse-wheel-picker slot="demo"></mouse-wheel-picker>
+  </demo>
+
+## mouseWheel 选项对象
+
+### speed
+
+  - **类型**：`number`
+  - **默认值**：`20`
+
+  鼠标滚轮滚动的速度。
+
+### invert
+
+  - **类型**：`boolean`
+  - **默认值**：`false`
+
+  当该值为 true 时，表示滚轮滚动和 BetterScroll 滚动的方向相反。
+
+### easeTime
+
+  - **类型**：`number`
+  - **默认值**： `300`(ms)
+
+  滚动动画的缓动时长。
+
+### discreteTime
+
+  - **类型**：`number`
+  - **默认值**： `400`(ms)
+
+  由于滚轮滚动是一种离散的运动，并没有 start、move、end 的事件类型，因此只要在 discreteTime 时间内没有探测到滚动，那么一次的滚轮动作就结束了。
+
+  ::: warning 注意
+  当搭配 [pulldown](./pulldown.html) 插件的时候，`easeTime` 和 `discreteTime` 会被内部修改成合理的固定值，以便触发 `pullingDown` 钩子
+  :::
+
+### throttleTime
+
+  - **类型**：`number`
+  - **默认值**： `0`(ms)
+
+  由于滚轮滚动是高频率的动作，因此可以通过 throttleTime 来限制触发频率，mouseWheel 内部会缓存滚动的距离，并且每隔 throttleTime 会计算缓存的距离并且滚动。
+
+  > 修改 throttleTime 可能会造成滚动动画不连贯，请根据实际场景进行调整。
+
+### dampingFactor
+
+  - **类型**：`number`
+  - **默认值**： `0.1`
+
+  阻尼因子，值的范围是[0, 1]，当 BetterScroll 滚出边界的时候，需要施加阻力，防止滚动幅度过大，值越小，阻力越大。
+
+:::tip 提示
+当 mouseWheel 配置为 true 的时候，插件内部使用的是默认的插件选项对象。
+
+```js
+const bs = new BScroll('.wrapper', {
+  mouseWheel: true
+})
+
+// 相当于
+
+const bs = new BScroll('.wrapper', {
+  mouseWheel: {
+    speed: 20,
+    invert: false,
+    easeTime: 300,
+    discreteTime: 400,
+    throttleTime: 0,
+    dampingFactor: 0.1
+  }
+})
+```
+:::
+
+## 事件
+
+### alterOptions
+
+  - **参数**：`MouseWheelConfig`
+    ```typescript
+    export interface MouseWheelConfig {
+      speed: number
+      invert: boolean
+      easeTime: number
+      discreteTime: number
+      throttleTime: number,
+      dampingFactor: number
+    }
+    ```
+  - **触发时机**：滚轮滚动开始
+
+  允许修改 options 来控制滚动中的某些行为。
+
+### mousewheelStart
+
+  - **参数**：无
+  - **触发时机**：滚轮滚动开始。
+
+### mousewheelMove
+
+  - **参数**： `{ x, y }`
+  - `{ number } x`：当前 BetterScroll 的横向滚动位置
+  - `{ number } y`：当前 BetterScroll 的纵向滚动位置
+  - **类型**： `{ x: number, y: number }`
+  - **触发时机**：滚轮滚动中
+
+### mousewheelEnd
+
+  - **参数**：`delta`
+  - **类型**： `WheelDelta`
+  ```typescript
+    interface WheelDelta {
+      x: number
+      y: number
+      directionX: Direction
+      directionY: Direction
+    }
+  ```
+  - **触发时机**：discreteTime 之后如果还没有触发 mousewheel 事件，那么便结算一次滚轮滚动行为。
+
+  ::: danger 警告
+  由于 mousewheel 事件的特殊性，mousewheelEnd 派发并不代表滚动动画结束。
+  :::
+
+
+::: tip 提示
+在绝大多数的场景下，如果你想要精确的知道当前 BetterScroll 的滚动位置，请监听 scroll、scrollEnd 钩子，而不是 `mouseXXX` 钩子。
+:::

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

@@ -0,0 +1,201 @@
+# movable
+
+## 介绍
+
+movable 插件为 BetterScroll 拓展可移动拖拽的能力。
+
+## 安装
+
+```bash
+npm install @better-scroll/movable --save
+
+// or
+
+yarn add @better-scroll/movable
+```
+
+## 基本使用
+
+首先引入 movable 插件，并通过全局方法 `BScroll.use()` 注册插件
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Movable from '@better-scroll/movable'
+
+  BScroll.use(Movable)
+```
+
+上面步骤完成后，需要在 `options` 中传入正确的配置：
+
+```js
+new BScroll('.bs-wrapper', {
+  bindToTarget: true,
+  scrollX: true,
+  scrollY: true,
+  freeScroll: true,
+  bounce: true
+  movable: true // for movable plugin
+})
+```
+
+以下是移动插件专属以及[ BetterScroll 的配置](../guide/base-scroll-options.html)：
+
+- **movable<插件专属>**
+
+  开启 movable 功能，必须设置为 `true`，若没有该项，则插件不会生效。
+
+- **bindToTarget**
+
+  必须设置为 `true`，主动将 touch 事件绑定在**待移动**的元素上，因为BetterScroll 默认将 touch 事件在绑定容器元素（wrapper）上。
+
+- **freeScroll**
+
+  记录 x 和 y 轴的手指偏移量，设置为 `true`。同时需要设置 scrollX 和 scrollY 均为 true。
+
+- **scrollX**
+
+  开启 x 轴方向滚动能力，设置为 `true`。
+
+- **scrollY**
+
+  开启 y 轴方向滚动能力，设置为 `true`。
+
+- **bounce**
+
+  指定开启边界回弹。
+
+  - **示例**
+
+    ```js
+      {
+        bounce: true // 开启四个方向,
+        bounce: {
+          left: true, // 开启左边界回弹
+          right: true, // 开启右边界回弹
+          top: false,
+          bottom: false
+        }
+      }
+    ```
+## 示例
+
+  - **只有一个 content**
+
+    通常场景下，只存在一个 content。
+
+    <demo qrcode-url="movable/default" :render-code="true">
+      <template slot="code-template">
+        <<< @/examples/vue/components/movable/default.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/movable/default.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/movable/default.vue?style
+      </template>
+      <movable-default slot="demo"></movable-default>
+    </demo>
+
+  - **多个 content**
+
+    但是在某些场景下，可能存在多个 content。
+
+    <demo qrcode-url="movable/multi-content">
+      <template slot="code-template">
+        <<< @/examples/vue/components/movable/multi-content.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/movable/multi-content.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/movable/multi-content.vue?style
+      </template>
+      <movable-multi-content slot="demo"></movable-multi-content>
+    </demo>
+
+## 进阶使用
+
+搭配[ zoom ](./zoom.html#介绍)插件，增加缩放能力。
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Movable from '@better-scroll/movable'
+  import Zoom from '@better-scroll/zoom'
+  new BScroll('.bs-wrapper', {
+    bindToTarget: true,
+    scrollX: true,
+    scrollY: true,
+    freeScroll: true,
+    bounce: true
+    movable: true // for movable plugin
+    zoom: { // for zoom plugin
+      start: 1,
+      min: 1,
+      max: 3
+    }
+  })
+```
+
+## 示例
+
+  :::warning
+  zoom 暂不支持在 pc 端的交互操作，下方 demo 请扫码体验。
+  :::
+
+  - **一个 content**
+
+    <demo qrcode-url="movable/scale">
+      <template slot="code-template">
+        <<< @/examples/vue/components/movable/scale.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/movable/scale.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/movable/scale.vue?style
+      </template>
+      <movable-scale slot="demo"></movable-scale>
+    </demo>
+
+  - **多个 content**
+
+    <demo qrcode-url="movable/multi-content-scale">
+      <template slot="code-template">
+        <<< @/examples/vue/components/movable/multi-content-scale.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/movable/multi-content-scale.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/movable/multi-content-scale.vue?style
+      </template>
+      <movable-multi-content-scale slot="demo"></movable-multi-content-scale>
+    </demo>
+
+## 实例方法
+
+### putAt(x, y, [time], [easing]) <Badge text='2.0.4' />
+  - **参数**
+    - `{PositionX} x`： x 坐标
+      - `PositionX：'number | 'left' | 'right' | 'center'`
+    - `{PositionY} y`： y 坐标
+      - `PositionY：'number | 'top' | 'bottom' | 'center'`
+    - `{number} [time]<可选>`：滚动的动画时长
+    - `{EaseItem} [easing]<可选>`：缓动效果配置，参考 [ease.ts](https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/shared-utils/src/ease.ts)，默认是 `bounce` 效果
+
+    将 content 元素放置在某一个位置。x 与 y 不仅可以是数字，也可以是对应的字符串。
+
+  - **示例**
+
+  ```js
+  const bs = new BScroll('.bs-wrapper', {
+    bindToTarget: true,
+    scrollX: true,
+    scrollY: true,
+    freeScroll: true,
+    movable: true
+  })
+
+  bs.putAt('center', 'center', 0) // 放置在 wrapper 的正中心
+  bs.putAt('right', 'bottom', 1000) // 放置在 wrapper 的右下角，动画时长 1s
+  ```

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

@@ -0,0 +1,223 @@
+# nested-scroll
+
+## 介绍
+
+协调嵌套的 BetterScroll 滚动行为。
+
+::: warning 警告
+v2.1.0 支持**多层嵌套**的 BetterScroll，并且功能更强大，性能更好。在这之前，只支持**双层嵌套**，请尽快升级至 2.1.0 版本。
+:::
+
+::: tip 提示
+**v2.1.0** 完美解决多层嵌套 BetterScroll 的 click 事件多次派发的问题。
+:::
+
+## 安装
+
+```bash
+npm install @better-scroll/nested-scroll --save
+
+// or
+
+yarn add @better-scroll/nested-scroll
+```
+
+## 使用
+
+你需要首先引入 `nested-scroll` 插件，并通过全局方法 `BScroll.use()` 使用
+
+```js
+  import BScroll from '@better-scroll/core'
+  import NestedScroll from '@better-scroll/nested-scroll'
+
+  BScroll.use(NestedScroll)
+```
+
+上面步骤完成后，BScroll 的 `options` 中配置 `nestedScroll`。
+
+```js
+  // < v2.1.0
+  // parent bs
+  new BScroll('.outerWrapper', {
+    nestedScroll: true
+  })
+  // child bs
+  new BScroll('.innerWrapper', {
+    nestedScroll: true
+  })
+
+  // v2.1.0
+  // parent bs
+  new BScroll('.outerWrapper', {
+    nestedScroll: {
+      groupId: 'dummy-divide' // string or number
+    }
+  })
+  // child bs
+  new BScroll('.innerWrapper', {
+    nestedScroll: {
+      groupId: 'dummy-divide'
+    }
+  })
+```
+
+具有相同 `groupId` 的 BetterScroll 实例（bs）**共享同一个** NestedScroll 实例（ns），ns 会协调每个 bs 滚动行为，一旦某个 bs 销毁的时候，ns 都会失去对它的掌控，例如：
+
+```js
+// parent bs
+const bs1 = new BScroll('.outerWrapper', {
+  nestedScroll: {
+    groupId: 'shared' // string or number
+  }
+})
+// child bs
+const bs2 = new BScroll('.innerWrapper', {
+  nestedScroll: {
+    groupId: 'shared'
+  }
+})
+
+console.log(bs1.plugins.nestedScroll === bs2.plugins.nestedScroll) // true
+
+bs2.destroy() // nestedScroll 不再约束 bs2，不再协调 bs1 与 bs2 的滚动行为
+```
+
+## 示例
+
+- **竖向双层嵌套 <Badge text='2.1.0' />**
+
+  <demo qrcode-url="nested-scroll/vertical" :render-code="true">
+    <template slot="code-template">
+      <<< @/examples/vue/components/nested-scroll/vertical.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/nested-scroll/vertical.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/nested-scroll/vertical.vue?style
+    </template>
+    <nested-scroll-vertical slot="demo"></nested-scroll-vertical>
+  </demo>
+
+- **竖向三层嵌套 <Badge text='2.1.0' />**
+
+  <demo qrcode-url="nested-scroll/triple-vertical" :render-code="true">
+    <template slot="code-template">
+      <<< @/examples/vue/components/nested-scroll/triple-vertical.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/nested-scroll/triple-vertical.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/nested-scroll/triple-vertical.vue?style
+    </template>
+    <nested-scroll-triple-vertical slot="demo"></nested-scroll-triple-vertical>
+  </demo>
+
+- **横向双层嵌套 <Badge text='2.1.0' />**
+
+  <demo qrcode-url="nested-scroll/horizontal">
+    <template slot="code-template">
+      <<< @/examples/vue/components/nested-scroll/horizontal.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/nested-scroll/horizontal.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/nested-scroll/horizontal.vue?style
+    </template>
+    <nested-scroll-horizontal slot="demo"></nested-scroll-horizontal>
+  </demo>
+
+  - **横向竖向双层嵌套 <Badge text='2.1.0' />**
+
+    <demo qrcode-url="nested-scroll/horizontal-in-vertical">
+      <template slot="code-template">
+        <<< @/examples/vue/components/nested-scroll/horizontal-in-vertical.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/nested-scroll/horizontal-in-vertical.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/nested-scroll/horizontal-in-vertical.vue?style
+      </template>
+      <nested-scroll-horizontal-in-vertical slot="demo"></nested-scroll-horizontal-in-vertical>
+    </demo>
+
+## 实例方法 <Badge text='2.1.0' />
+
+:::tip 提示
+以下方法皆已代理至 BetterScroll 实例，例如：
+
+```js
+import BScroll from '@better-scroll/core'
+import NestedScroll from '@better-scroll/nested-scroll'
+
+BScroll.use(NestedScroll)
+
+const bs1 = new BScroll('.parent-wrapper', {
+  nestedScroll: {
+    groupId: 'dummy'
+  }
+})
+
+const bs2 = new BScroll('.child-wrapper', {
+  nestedScroll: {
+    groupId: 'dummy'
+  }
+})
+
+// 销毁 nestedScroll，bs1 与 bs2 共享同一个 nestedScroll 实例，因为他们的 groupId 相同
+bs1.purgeNestedScroll() // 与 bs2.purgeNestedScroll() 的效果一样
+```
+:::
+
+### `purgeNestedScroll()`
+
+  - **介绍**：销毁管控自己的 nestedScroll
+
+::: warning 注意
+不同的 `groupId` 会生成不同的 nestedScroll，相同的 `groupId` 会共享同一份 nestedScroll，因此你应该在合适的时机（比如组件销毁的时候）调用 `purgeNestedScroll` 来清理内存。或者你也可以调用 BetterScroll 的 destroy 方法把自身从 nestedScroll 移除，例如：
+
+```js
+const bs1 = new BScroll('.parent-wrapper', {
+  nestedScroll: {
+    groupId: 'dummy'
+  }
+})
+
+const bs2 = new BScroll('.child-wrapper', {
+  nestedScroll: {
+    groupId: 'dummy'
+  }
+})
+
+bs1.destroy() // nestedScroll 不再管控 bs1
+bs2.destroy() // nestedScroll 不再管控 bs2
+```
+:::
+
+## 静态方法 <Badge text='2.1.0' />
+
+### `getAllNestedScrolls()`
+
+  - **介绍**：获取当前所有的 nestedScroll 实例
+
+  - **返回**：nestedScroll 实例组成的数组
+
+  ```typescript
+  import NestedScroll from '@better-scroll/nested-scroll'
+
+  const nestedScrolls: NestedScroll[] = NestedScroll.getAllNestedScrolls()
+  ```
+
+### `purgeAllNestedScrolls()`
+
+  - **介绍**：销毁当前所有的 nestedScroll 实例
+
+  ```typescript
+  import NestedScroll from '@better-scroll/nested-scroll'
+
+  // 不再约束任何 BetterScroll 实例
+  NestedScroll.purgeAllNestedScrolls()
+  ```