cbvirtua 1.0.105 → 1.0.107

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/en-US/plugins/mouse-wheel.md

@@ -0,0 +1,277 @@
+# mouse-wheel
+
+mouseWheel extends the capabilities of the BetterScroll mouse wheel.
+
+## Install
+
+```bash
+npm install @better-scroll/mouse-wheel --save
+
+// or
+
+yarn add @better-scroll/mouse-wheel
+```
+
+::: tip
+Currently supports mouse wheel: core, slide, wheel, pullup, pulldown plugins.
+:::
+
+## Basic Usage
+
+In order to enable the mouseWheel plugin, you need to first import it, register the plugin through the static method `BScroll.use()`, and finally pass in the correct [mouseWheel option](./mouse-wheel.html#mousewheel-options)
+
+```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
+    }
+  })
+```
+
+ - **VerticalScroll Demo**
+
+  <demo :hide-qrcode="true" :render-code="true" qrcode-url="mouse-wheel/vertical-scroll">
+    <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>
+
+- **HorizontalScroll 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>
+
+
+## Advanced Usage
+
+The mouseWheel plugin can also be used with other plugins to increase the operation of the mouse wheel.
+
+- **mouseWheel & slide**
+
+  Operate [slide](./slide.html) with the mouse wheel.
+
+  - **HorizontalSlide Demo**
+
+    <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>
+
+  - **VerticalSlide Demo**
+
+    <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**
+
+  use mousewheel do [pullup](./pullup.html) operation.
+
+  <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**
+
+  use mousewheel do [pulldown](./pulldown.html)  operation.
+
+  <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**
+
+  use mousewheel do [wheel](./wheel.html) operation.
+
+  <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 options
+
+### speed
+
+  - **Type**: `number`
+  - **Default**: `20`
+
+  The speed at which the mouse wheel scrolls.
+
+### invert
+
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+  When the value is true, it means that the scrolling direction of the wheel is opposite to that of BetterScroll.
+
+### easeTime
+
+  - **Type**: `number`
+  - **Default**: `300`(ms)
+
+  The duration of the scroll animation.
+
+### discreteTime
+
+  - **Type**: `number`
+  - **Default**: `400`(ms)
+
+  Because the mouse wheel is a discrete movement, there is no event type of **start**, **move**, **end**, so as long as no scroll is detected within `discreteTime`, then one scroll wheel action ends.
+
+  ::: warning
+  When integrated with [pulldown](./pulldown.html) plugin, `easeTime` and `discreteTime` will be **internally** modified to **reasonable fixed value** to trigger the `pullingDown` hook
+  :::
+
+### throttleTime
+
+  - **Type**: `number`
+  - **Default**: `0`(ms)
+
+  Since the scroll wheel is a high-frequency action, the trigger frequency can be limited by `throttleTime`. MouseWheel will cache the scrolling distance, and calculate the cached distance and scroll every throttleTime.
+
+  > Modifying throttleTime may cause discontinuous scrolling animation, please adjust it according to the actual scene.
+
+### dampingFactor
+
+  - **Type**: `number`
+  - **Default**: `0.1`
+
+  Damping factor, the value range is [0, 1]. When BetterScroll rolls out of the boundary, resistance needs to be applied to prevent the rolling range from being too large. The smaller the value, the greater the resistance.
+
+:::tip
+When `mouseWheel` is configured as `true`, the plugin uses the default plugin option.
+
+```js
+const bs = new BScroll('.wrapper', {
+  mouseWheel: true
+})
+
+// equals
+
+const bs = new BScroll('.wrapper', {
+  mouseWheel: {
+    speed: 20,
+    invert: false,
+    easeTime: 300,
+    discreteTime: 400,
+    throttleTime: 0,
+    dampingFactor: 0.1
+  }
+})
+```
+:::
+
+## Events
+
+### alterOptions
+  - **Arguments**: `MouseWheelConfig`
+    ```typescript
+      export interface MouseWheelConfig {
+        speed: number
+        invert: boolean
+        easeTime: number
+        discreteTime: number
+        throttleTime: number,
+        dampingFactor: number
+      }
+    ```
+  - **Triggered Timing**: The mousewheel begins to scroll, allowing to modify options to control certain behaviors during scrolling.
+
+### mousewheelStart
+  - **Arguments**: none
+  - **Triggered Timing**: The mousewheel starts.
+
+### mousewheelMove
+  - **Arguments**: `{ x, y }`
+  - `{ number } x`: The current x of BetterScroll
+  - `{ number } y`: The current y of BetterScroll
+  - **Type**: `{ x: number, y: number }`
+  - **Triggered Timing**: Mousewheel is scrolling
+
+### mousewheelEnd
+  - **Arguments**:`delta`
+  - **Type**: `WheelDelta`
+  ```typescript
+    interface WheelDelta {
+      x: number
+      y: number
+      directionX: Direction
+      directionY: Direction
+    }
+  ```
+  - **Triggered Timing**: If the mousewheel hook has not been triggered after `discreteTime`, a mousewheel action will be settled.
+
+  ::: danger Note
+  Due to the particularity of the mousewheel hook, the dispatch of mousewheelEnd does not mean the end of the scroll animation.
+  :::
+
+::: tip
+In most scenarios, if you want to know the current scroll position of BetterScroll accurately, please listen to the scroll and scrollEnd hooks instead of the `mouseXXX` hooks.
+:::

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/en-US/plugins/movable.md

@@ -0,0 +1,204 @@
+# movable
+
+## Introduction
+
+Add move functionality for BetterScroll.
+
+## Install
+
+```bash
+npm install @better-scroll/movable --save
+
+// or
+
+yarn add @better-scroll/movable
+```
+
+## Basic Usage
+
+import `movable`, then call `BScroll.use()`.
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Movable from '@better-scroll/movable'
+
+  BScroll.use(Movable)
+```
+
+pass in the correct configuration in options, for example:
+
+```js
+  new BScroll('.bs-wrapper', {
+    bindToTarget: true,
+    scrollX: true,
+    scrollY: true,
+    freeScroll: true,
+    bounce: true
+    movable: true // for movable plugin
+  })
+```
+
+The following is related to `movable` plugin and [BetterScroll configuration](../guide/base-scroll-options.html):
+
+- **movable(for plugin)**
+
+  Enable zoom functionality, set it `true`.
+
+- **bindToTarget**
+
+  Must be set to `true` to actively bind the touch event to **the element to be moved**, because BetterScroll binds the touch event to **the wrapper element** by default.
+
+- **freeScroll**
+
+  Record the offset of x and y direction when finger moved, set it `true`. In addtional, **scrollX** and **scrollY** are also need to be true.
+
+- **scrollX**
+
+  Enable the scrolling ability in the x direction and set it to `true`.
+
+- **scrollY**
+
+  Enable the scrolling ability in the y direction and set it to `true`.
+
+- **bounce**
+
+  Specifies to turn on boundary rebound.
+
+  - **Examples**
+
+  ```js
+    {
+      bounce: true // Enable all directions,
+      bounce: {
+        left: true, // Enable the left
+        right: true, // Enable the right
+        top: false,
+        bottom: false
+      }
+    }
+  ```
+## Demo
+
+  - **Only one content**
+
+    Usually, there is only one 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>
+
+  - **Multi content**
+
+    However, in some scenarios, there may be multiple 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>
+
+## Advanced Usage
+
+With [ zoom ](./zoom.html#introduction) plugin, increase the zoom capability.
+
+```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
+    }
+  })
+```
+
+## Demo
+
+  :::warning
+  pc is not allowed, scan the qrcode.
+  :::
+
+  - **One 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>
+
+  - **Multi 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>
+
+## Instance Methods
+
+### putAt(x, y, [time], [easing]) <Badge text='2.0.4' />
+  - **Arguments**
+    - `{PositionX} x`: x coordinate
+      - `PositionX: 'number | 'left' | 'right' | 'center'`
+    - `{PositionY} y`: y coordinate
+      - `PositionY: 'number | 'top' | 'bottom' | 'center'`
+    - `{number} [time]<Optional>`: Scroll animation duration
+    - `{EaseItem} [easing]<Optional>`: Ease effect configuration, refer to [ease.ts](https://github.com/ustbhuangyi/better-scroll/blob/dev/packages/shared-utils/src/ease.ts), the default is `bounce` effect
+
+    Put the content element in a certain position. x and y can be not only numbers, but also corresponding strings.
+
+  - **Examples**
+
+  ```js
+  const bs = new BScroll('.bs-wrapper', {
+    bindToTarget: true,
+    scrollX: true,
+    scrollY: true,
+    freeScroll: true,
+    movable: true
+  })
+
+  // Placed in the center of the wrapper
+  bs.putAt('center', 'center', 0)
+
+  // Placed in the right-bottom corner of the wrapper, the animation duration is 1s
+  bs.putAt('right', 'bottom', 1000)
+  ```

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/en-US/plugins/nested-scroll.md

@@ -0,0 +1,211 @@
+# nested-scroll
+
+## Introduction
+
+Coordinates nested BetterScroll scrolling behavior.
+
+::: warning
+**v2.1.0** supports BetterScroll with **Multi Nesting**, with more powerful functions and better performance. Only **Double Nesting** is supported in old version, please upgrade to **v2.1.0** as soon as possible.
+:::
+
+::: tip
+**v2.1.0** Perfectly solves the problem that the click event of multi-level nested BetterScroll is dispatched multiple times.
+:::
+
+## Install
+
+```bash
+npm install @better-scroll/nested-scroll --save
+
+// or
+
+yarn add @better-scroll/nested-scroll
+```
+
+## Usage
+
+import the `nested-scroll` plugin and use it with the static method `BScroll.use()`
+
+```js
+  import BScroll from '@better-scroll/core'
+  import NestedScroll from '@better-scroll/nested-scroll'
+
+  BScroll.use(NestedScroll)
+```
+
+After the above steps are completed, `nestedScroll` is configured in BScroll's `options`.
+
+```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'
+    }
+  })
+```
+
+BetterScroll instances (bs) with the same `groupId` **share the same NestedScroll instance**(`ns`), `ns` will coordinate the scrolling behavior of each bs, once a bs is destroyed, `ns` will lose control of it, for example:
+
+```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
+
+// nestedScroll no longer constrains bs2
+// nestedScroll no longer coordinates the scrolling behavior of bs1 and bs2
+bs2.destroy()
+```
+
+## Demo
+
+- **Nested vertical scroll <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>
+
+- **Nested triple vertical scroll <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>
+
+- **Nested horizontal scroll <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>
+
+## Instance Methods <Badge text='2.1.0' />
+
+:::tip
+All methods are proxied to BetterScroll instance, for example:
+
+```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'
+  }
+})
+
+// purge nestedScroll
+// bs1 and bs2 share the same nestedScroll instance because they have the same groupId
+bs1.purgeNestedScroll() // Same as bs2.purgeNestedScroll()
+```
+:::
+
+### `purgeNestedScroll()`
+
+  - **Details**: Purge the nestedScroll that controls itself
+
+  ::: warning
+  Different `groupId` will generate different nestedScroll, and the same `groupId` will share the same nestedScroll, so you should call `purgeNestedScroll` at the right time (such as when the component is destroyed) to clean up the memory. Or you can call the destroy method of BetterScroll to remove itself from nestedScroll, for example:
+
+  ```js
+  const bs1 = new BScroll('.parent-wrapper', {
+    nestedScroll: {
+      groupId: 'dummy'
+    }
+  })
+
+  const bs2 = new BScroll('.child-wrapper', {
+    nestedScroll: {
+      groupId: 'dummy'
+    }
+  })
+
+  bs1.destroy() // nestedScroll no longer constrains bs1
+  bs2.destroy() // nestedScroll no longer constrains bs2
+  ```
+  :::
+
+## Static Methods <Badge text='2.1.0' />
+
+### `getAllNestedScrolls()`
+
+  - **Details**: Get all current nestedScroll instances
+
+  - **Returns**: An array of nestedScroll instances
+
+  ```typescript
+  import NestedScroll from '@better-scroll/nested-scroll'
+
+  const nestedScrolls: NestedScroll[] = NestedScroll.getAllNestedScrolls()
+  ```
+
+### `purgeAllNestedScrolls()`
+
+  - **Details**: Purge all current nestedScroll instances
+
+  ```typescript
+  import NestedScroll from '@better-scroll/nested-scroll'
+
+  // No longer constrain any BetterScroll instances
+  NestedScroll.purgeAllNestedScrolls()
+  ```