cbvirtua 1.0.106 → 1.0.107

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

@@ -0,0 +1,51 @@
+# observe-dom
+Enable detection of content and content child DOM changes. When the plugin is used and these DOM elements change, `bs.refresh()` will be triggered. The observe-dom plugin has the following features:
+
+- Debounce feature for CSS attributions which change frequently
+- If the scroll elements change occurs during the scroll animation, refresh will not be triggered.
+
+## Install
+
+```bash
+npm install @better-scroll/observe-dom --save
+
+// or
+
+yarn add @better-scroll/observe-dom
+```
+
+## Usage
+
+  ```js
+    import BScroll from '@better-scroll/core'
+    import ObserveDOM from '@better-scroll/observe-dom'
+    BScroll.use(ObserveDOM)
+
+    new BScroll('.bs-wrapper', {
+      //...
+      observeDOM: true // init observe-dom plugin
+    })
+  ```
+
+## Demo
+
+  <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
+For version <= `2.0.6`, because the internal implementation of the plugin uses [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver), it cannot detect whether the load of the `img` Element is complete, so for images with uncertain heights inside the content, you need to wait for the image to load before calling `bs.refresh()` to recalculate the scrollable size. If the browser does not support MutationObserver, the fallback inside the plugin is to recalculate the scrollable size every second.
+:::
+
+:::tip
+In the v2.1.0 version, the [observe-image](./observe-image) plugin is added to detect the loading of the img tag, so the two can be combined to complement the **autorefresh** ability to update BetterScroll every time.
+:::

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

@@ -0,0 +1,78 @@
+# observe-image <Badge text='2.1.0' />
+
+## Introduction
+
+Turn on the detection of the loading of image elements in the wrapper child element. Regardless of whether the image is loaded successfully or not, BetterScroll's `refresh` method is automatically called to recalculate the scrollable width or height, which was supported in v2.1.0.
+
+:::tip
+For scenes where CSS has been used to determine the width and height of the image, this plugin should not be used, because each call to refresh will affect performance. You only need it if the width or height of the image is uncertain.
+:::
+
+## Install
+
+```bash
+npm install @better-scroll/observe-image --save
+
+// or
+
+yarn add @better-scroll/observe-image
+```
+
+## Usage
+
+```js
+  import BScroll from '@better-scroll/core'
+  import ObserveImage from '@better-scroll/observe-image'
+  BScroll.use(ObserveImage)
+
+  new BScroll('.bs-wrapper', {
+    //...
+    observeImage: true
+  })
+```
+
+## Demo
+
+  <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 Options
+
+:::tip
+When `observeImage` is configured as `true`, the plugin uses the default plugin option.
+
+```js
+const bs = new BScroll('.wrapper', {
+  observeImage: true
+})
+
+// equals
+
+const bs = new BScroll('.wrapper', {
+  observeImage: {
+    debounceTime: 100 // ms
+  }
+})
+```
+:::
+
+### debounceTime
+
+  - **Type**: `number`
+  - **Default**: `100`
+
+    After detecting the success or failure of the image loading, the refresh method will be called after **debounceTime** milliseconds to recalculate the scrollable height or width. If multiple images load successfully or fail within debounceTime milliseconds, the **refresh** method will only be called once.
+
+    :::tip
+    When **debounceTime** is 0, the **refresh** method will be called immediately instead of using **setTimeout**.
+    :::

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

@@ -0,0 +1,199 @@
+# pulldown
+
+## Introduction
+
+The pulldown plugin provides BetterScroll with the ability to monitor pulldown operation.
+
+## Install
+
+```bash
+npm install @better-scroll/pull-down --save
+
+// or
+
+yarn add @better-scroll/pull-down
+```
+
+## Usage
+
+First, install the plugin via the static method `BScroll.use()`
+
+```js
+import BScroll from '@better-scroll/core'
+import PullDown from '@better-scroll/pull-down'
+
+BScroll.use(PullDown)
+```
+
+pass in the correct configuration in [options](./pulldown.html#pulldownrefresh-options), for example:
+
+```js
+new BScroll('.bs-wrapper', {
+  pullDownRefresh: true
+})
+```
+
+## Demo
+
+- **Basic Usage**
+
+<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>
+
+- **Sina-Weibo <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>
+
+In order to match the effects of App, in version v2.4.0, pulldown has made some changes and is compatible with previous versions. During a pulldown procedure, there are three internal circulation states, and the states are irreversible. They are as follows:
+
+1. **default**
+
+  The initial state.
+
+2. **moving**
+
+  Moving state, this state represents that the user's finger is manipulating BetterScroll, and the finger is keeping in touch. In this state, BetterScroll will dispatch two events.
+
+  - **enterThreshold**
+
+    Dispatched when BetterScroll scrolls **into** the pulldown threshold area. Inside this event, you can do the logic of texts initialization, such as prompting the user to "pull down to refresh"
+  
+  - **leaveThreshold**
+
+    Dispatched when BetterScroll scrolls **out of** the pulldown threshold area. You can prompt the user to "Release finger"
+
+3. **fetching**
+
+  Once the finger went away, the pullingDown event is triggered to execute the logic of fetching data
+
+The state change can only be `default -> moving -> fetching` or `default -> moving`. The latter means that at the moment the user's finger is released, the conditions for triggering the pullingDown event are not met.
+
+## pullDownRefresh Options
+
+### threshold
+
+  - **Type**: `number`
+  - **Default**: `90`
+
+  Configure the top pull-down distance to determine dispatching `pullingDown` hooks.
+
+### stop
+
+  - **Type**: `number`
+  - **Default**: `40`
+
+  Rebound distance. After BetterScroll dispatches the `pullingDown` hook, it will immediately execute the rebound animation.
+
+:::tip
+When `pullDownRefresh` is configured as `true`, the plugin uses the default plugin option.
+
+```js
+const bs = new BScroll('.wrapper', {
+  pullDownRefresh: true
+})
+
+// equals
+
+const bs = new BScroll('.wrapper', {
+  pullDownRefresh: {
+    threshold: 90,
+    stop: 40
+  }
+})
+```
+:::
+
+## Instance Methods
+
+:::tip
+All methods are proxied to BetterScroll instance, for example:
+
+```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()`
+
+  - **Details**: End the pull-down refresh behavior.
+
+  ::: warning
+  Every time the `pullingDown` hook is triggered, you should **actively call** `finishPullDown()` to tell BetterScroll to be ready for the next pullingDown hook.
+  :::
+
+### `openPullDown(config: PullDownRefreshOptions = {})`
+
+  - **Details**: Turn on the pull-down refresh dynamically.
+  - **Arguments**:
+    - `{ PullDownRefreshOptions } config`: Modify the option of the pulldown plugin
+    - `PullDownRefreshOptions`:
+
+    ```typescript
+    export type PullDownRefreshOptions = Partial<PullDownRefreshConfig> | true
+
+    export interface PullDownRefreshConfig {
+      threshold: number
+      stop: number
+    }
+    ```
+
+  ::: warning
+  The **openPullDown** method should be used with **closePullDown**, because in the process of generating the pulldown plugin, the pull-down refresh action has been automatically monitored.
+  :::
+
+### `closePullDown()`
+
+  - **Details**: Turn off the pull-down refresh dynamically.
+
+## Events
+
+### `pullingDown`
+
+  - **Arguments**: None
+  - **Trigger**: A `pullingDown` event is fired when the top pull-down distance is greater than the `threshold` value after touchend.
+
+::: danger Note
+After the pull-down refresh action is detected, the consumption opportunity of the `pullingDown` hook is only once, so you need to call `finishPullDown()` to tell BetterScroll to provide the next consumption opportunity of the `pullingDown` event.
+:::
+
+### `enterThreshold` <Badge text='2.4.0' />
+
+  - **Arguments**: None
+  - **Trigger**: when pulldown is in the **moving** state and **enters** threshold area.
+
+### `leaveThreshold` <Badge text='2.4.0' />
+
+  - **Arguments**: None
+  - **Trigger**: when pulldown is in the **moving** state and **leaves** threshold area.

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

@@ -0,0 +1,145 @@
+# pullup
+
+## Introduction
+
+The pullup plugin provides BetterScroll with the ability to monitor pulldown operation.
+
+## Install
+
+```bash
+npm install @better-scroll/pull-up --save
+
+// or
+
+yarn add @better-scroll/pull-up
+```
+
+## Usage
+
+First, install the plugin via the static method `BScroll.use()`
+
+```js
+  import BScroll from '@better-scroll/core'
+  import PullUp from '@better-scroll/pull-up'
+
+  BScroll.use(PullUp)
+```
+
+pass in the correct configuration in [options](./pullup.html#pullupload-options), for example:
+
+```js
+  new BScroll('.bs-wrapper', {
+    pullUpLoad: true
+  })
+```
+
+## Demo
+
+<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 Options
+
+### threshold
+
+  - **Type**: `number`
+  - **Default**: `0`
+
+  The threshold for triggering a `pullingUp` hook.
+
+:::tip
+When `pullUpLoad` is configured as `true`, the plugin uses the default plugin option.
+
+```js
+const bs = new BScroll('.wrapper', {
+  pullUpLoad: true
+})
+
+// equals
+
+const bs = new BScroll('.wrapper', {
+  pullUpLoad: {
+    threshold: 0
+  }
+})
+```
+:::
+
+## Instance Methods
+
+:::tip
+All methods are proxied to BetterScroll instance, for example:
+
+```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()`
+
+  - **Details**: Finish the pullUpLoad behavior.
+
+  ::: warning
+  Every time you trigger the `pullingUp` hook, you should **actively call** `finishPullUp()` to tell BetterScroll to be ready for the next pullingUp hook.
+  :::
+
+### `openPullUp(config: PullUpLoadOptions = {})`
+
+  - **Details**: Turn on the pullUpLoad dynamically.
+  - **Arguments**:
+    - `{ PullDownRefreshOptions } config`: Modify the option of the pullup plugin
+    - `PullDownRefreshOptions`:
+
+    ```typescript
+    export type PullUpLoadOptions = Partial<PullUpLoadConfig> | true
+
+    export interface PullUpLoadConfig {
+      threshold: number
+    }
+    ```
+
+  ::: warning
+  The **openPullUp** method should be used with **closePullUp**, because in the process of generating the pullup plugin, the pullUpLoad action has been automatically monitored.
+  :::
+
+### `closePullUp()`
+
+  - **Details**: Turn off pullUpLoad dynamically.
+
+### `autoPullUpLoad()`
+
+  - **Details**：Auto pullUp.
+
+## Events
+
+### `pullingUp`
+
+  - **Arguments**: None
+  - **Trigger**: When the distance to the bottom is less than the value of `threshold`, a `pullingUp` event is triggered.
+
+  > When threshold is a positive number, it means `pullingUp` is triggered when the threshold pixel is away from the scroll boundary. On the contrary, it means that the event will be triggered when it crosses the scroll boundary.
+
+::: danger Note
+After the pullUpLoad action is detected, the consumption opportunity of the `pullingUp` event is only once, so you need to call `finishPullUp()` to tell BetterScroll to provide the next consumption opportunity of the `pullingUp` event.
+:::

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

@@ -0,0 +1,237 @@
+# scrollbar
+
+## Introduciton
+
+The scrollbar plugin provides a nice scrollbar for BetterScroll.
+
+:::tip
+For v2.2.0, users can provide custom scroll bars.
+:::
+
+## Install
+
+```bash
+npm install @better-scroll/scroll-bar --save
+
+// or
+
+yarn add @better-scroll/scroll-bar
+```
+
+## Usage
+
+First, install the plugin via the static method `BScroll.use()`
+
+```js
+import BScroll from '@better-scroll/core'
+import ScrollBar from '@better-scroll/scroll-bar'
+
+BScroll.use(ScrollBar)
+```
+
+pass correct [scrollbar options](./scroll-bar.html#scrollbar-options)
+
+```js
+new BScroll('.bs-wrapper', {
+  scrollY: true,
+  scrollbar: true
+})
+```
+
+## Demo
+
+  - **Vertical Scrollbar**
+
+    <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>
+
+  - **Horizontal Scrollbar**
+
+    <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>
+
+  - **Custom Scrollbar**
+
+    <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>
+
+  - **With Mousewheel**
+
+    <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 options
+
+### fade
+
+  - **Type**: `boolean`
+  - **Default**: `true`
+
+  When the scroll stops, the scrollbar fades out.
+
+### interactive
+
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+  Whether scrollbar can interacted with.
+### customElements <Badge text="2.2.0" />
+
+  - **Type**: `HTMLElement[]`
+  - **Default**: `[]`
+
+  The user provides a custom scroll bar.
+
+  ```js
+  // horizontal
+  const horizontalEl = document.getElementById('User-defined scrollbar')
+  new BScroll('.bs-wrapper', {
+    scrollY: true,
+    scrollbar: {
+      customElements: [horizontalEl]
+    }
+  })
+  // vertical
+  const verticalEl = document.getElementById('User-defined scrollbar')
+  new BScroll('.bs-wrapper', {
+    scrollY: false,
+    scrollX: true,
+    scrollbar: {
+      customElements: [verticalEl]
+    }
+  })
+  // freeScroll
+  const horizontalEl = document.getElementById('User-defined scrollbar')
+  const verticalEl = document.getElementById('User-defined scrollbar')
+  new BScroll('.bs-wrapper', {
+    freeScroll: true,
+    scrollbar: {
+      // When there are two scrollbars
+      // the first element of the array is the horizontal
+      customElements: [horizontalEl, verticalEl]
+    }
+  })
+  ```
+
+### minSize <Badge text="2.2.0" />
+
+  - **Type**: `number`
+  - **Default**: `8`
+
+  The minimum size of the scrollbar. When the user provides a custom scrollbar, this configuration is invalid.
+
+### scrollbarTrackClickable <Badge text="2.2.0" />
+
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+  Whether the scrollbar track allows clicking.
+
+  **Note**：When enabling this configuration, please ensure that the `click` of BetterScroll Options is true, otherwise the click event cannot be triggered. [The reason is here](../FAQ/diagnosis.html#question-4-why-are-the-listeners-for-all-click-events-inside-betterscroll-content-not-triggered).
+
+  ```js
+  new BScroll('.bs-wrapper', {
+    scrollY: true,
+    click: true // essential
+    scrollbar: {
+      scrollbarTrackClickable: true
+    }
+  })
+  ```
+
+### scrollbarTrackOffsetType <Badge text="2.2.0" />
+
+  - **Type**: `string`
+  - **Default**: `'step'`
+
+  After the scroll bar track is clicked, the calculation method of the scroll distance is the same as the browser's performance by default. It can be configured as `'clickedPoint'`, which means the scroll bar is scrolled to the clicked position.
+
+### scrollbarTrackOffsetTime <Badge text="2.2.0" />
+
+  - **Type**: `number`
+  - **Default**: `300`
+
+  the scroll time after the scrollbar track is clicked.
+
+### fadeInTime <Badge text="2.4.0" />
+
+  - **Type**: `number`
+  - **Default**: `250`
+
+  The duration of the animation when the scrollbar fades in.
+
+### fadeOutTime <Badge text="2.4.0" />
+
+  - **Type**: `number`
+  - **Default**: `500`
+
+  The duration of the animation when the scrollbar fades out.
+
+:::tip
+When `scrollbar` is configured as `true`, the plugin uses the default plugin option.
+
+```js
+const bs = new BScroll('.wrapper', {
+  scrollbar: true
+})
+
+// equals
+
+const bs = new BScroll('.wrapper', {
+  scrollbar: {
+    fade: true,
+    interactive: false,
+    // supported in v2.2.0
+    customElements: [],
+    minSize: 8,
+    scrollbarTrackClickable: false,
+    scrollbarTrackOffsetType: 'step',
+    scrollbarTrackOffsetTime: 300,
+    // supported in v2.4.0
+    fadeInTime: 250,
+    fadeOutTime: 500
+  }
+})
+```
+:::