cbvirtua 1.0.106 → 1.0.107

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

@@ -0,0 +1,125 @@
+# plugins
+
+## Why need plugins
+
+In order to decouple the functions of the various features of BetterScroll 1.x, to prevent unlimited increase in the size of the bundle. In the `2.x` architecture design, a "plugin" architecture design is adopted. Each feature of 1.x will be implemented in the form of Plugin in `2.x`.
+
+Existing plugins:
+- [pulldown](./pulldown.html)
+- [pullup](./pullup.html)
+- [scrollbar](./scroll-bar.html)
+- [slide](./slide.html)
+- [wheel](./wheel.html)
+- [zoom](./zoom.html)
+- [mouse-wheel](./mouse-wheel.html)
+- [observe-dom](./observe-dom.html)
+- [observe-image](./observe-image.html)
+- [nested-scroll](./nested-scroll.html)
+- [infinity](./infinity.html)
+- [movable](./movable.html)
+- [indicators](./indicators.html)
+
+You can write a plugin by yourself to add new feature to `bs`. If you want do this, please refer to [How to write a plugin](./how-to-write.html).
+
+## Use a plugin
+
+Use plugins by calling the `BScroll.use()` static method. This has to be done before you call `new BScroll()`:
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Plugin from 'somewhere'
+
+  new BScroll('.wrapper', {
+    // pluginKey corresponds to the value of the static attribute pluginName on the Plugin class,
+    // otherwise the plugin cannot be instantiated
+    pluginKey: {}
+  })
+```
+
+## Use a method or property of plugins
+
+The plugin may expose some methods or properties. These methods or properties are proxied to `bs` via `Object.defineProperty` method. For example, the `zoomTo` method is provided in the zoom plugin, which you can use by `bs.zoomTo`.
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Zoom from '@better-scroll/zoom'
+
+  BScroll.use(Zoom)
+
+  const bs = new BScroll('#scroll-wrapper', {
+    freeScroll: true,
+    scrollX: true,
+    scrollY: true,
+    disableMouse: true,
+    useTransition: true,
+    zoom: {
+      start: 1,
+      min: 0.5,
+      max: 2
+    }
+  })
+
+  bs.zoomTo(1.5, 0, 0) // zoomTo from Zoom Plugin is proxied to bs instance
+```
+
+## Use a event of plugins
+
+The hooks exposed in the plugin will be delegated to `bs`. For example, you can listen to the `zoomStart` event, which is exposed in zoom plugin, in the following way:
+
+```js
+  import BScroll from '@better-scroll/core'
+  import Zoom from '@better-scroll/zoom'
+
+  BScroll.use(Zoom)
+  const bs = new BScroll('#scroll-wrapper', {
+    freeScroll: true,
+    scrollX: true,
+    scrollY: true,
+    zoom: {
+      start: 1,
+      min: 0.5,
+      max: 2
+    }
+  })
+
+  bs.on('zoomStart', () => {
+
+  })
+```
+
+## BetterScroll with all plugins
+
+Considering the trouble of registering plugins one by one, if your project uses the full plugins of BetterScroll, we offer a once-in-a-lifetime solution.
+
+
+```js
+  import BScroll from 'better-scroll'
+
+  const bs = new BScroll('#scroll-wrapper', {
+    pullUpLoad: true,
+    pullDownRefresh: true,
+    scrollbar: true,
+    // and so on
+  })
+```
+
+::: warning
+import all of BetterScroll may have a big impact on the size of your bundle, and as the function of BetterScroll expands, the size will increase unlimitedly, **try to import what you need**.
+:::
+
+::: warning
+Normally, you should pay attention to the properties and methods exposed by the BetterScroll instance, because the properties and methods on the plugin instance have been proxied to the bs. If you really need to care about the plugin instance, you can also use `bs.plugins ` to get all plugin information.
+
+```js
+  import BScroll from '@better-scroll/scroll'
+  import zoom from '@better-scroll/zoom'
+
+  BScroll.use(zoom)
+
+  const bs = new BScroll('.wrapper', {
+    zoom: true
+  })
+
+  console.log(bs.plugins.zoom)
+```
+:::

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/en-US/plugins/how-to-write.md

@@ -0,0 +1,151 @@
+# How to write plugins
+
+### Conceive The Function Of The Plugin
+
+```js
+  import BScroll from '@better-scroll/core'
+  import MyPlugin from '@better-scroll/my-plugin'
+
+  BScroll.use(MyPlugin)
+
+  const bs = new BScroll('.wrapper', {
+    myPlugin: {
+      scrollText: 'I am scrolling',
+      scrollEndText: 'Scroll has ended'
+    },
+    // or
+    myPlugin: true
+  })
+
+  // Use the event that is proxied to bs by plugin
+  bs.on('printScrollEndText', (scrollEndText) => {
+    console.log(scrollEndText) // print "Scroll has ended, position is (xx, yy)"
+  })
+
+  // Use the method that is proxied to bs by plugin
+  bs.printScrollText() // print "I am scrolling"
+```
+
+### Write Plugin
+
+1. **TypeScript declare merging and expose plugin methods**
+
+```typescript
+import BScroll from '@better-scroll/core'
+
+export type MyPluginOptions = Partial<MyPluginConfig> | true
+
+type MyPluginConfig = {
+  scrollText: string,
+  scrollEndText: string
+}
+
+interface PluginAPI {
+  printScrollText(): void
+}
+
+declare module '@better-scroll/core' {
+  interface CustomOptions {
+    myPlugin?: myPluginOptions
+  }
+
+  interface CustomAPI {
+    myPlugin: PluginAPI
+  }
+}
+```
+
+The advantage of this is that when the `myPlugin` plugin is imported and BetterScroll is instantiated, there can be corresponding Options prompts and bs can have corresponding method prompts. Take the pulldown plugin as an example:
+
+<img data-zoomable :src="$withBase('/assets/images/tip1.png')" alt="">
+
+
+<img data-zoomable :src="$withBase('/assets/images/tip2.png')" alt="">
+
+2. **Write the plugin logic**
+
+    - **BetterScroll plugins need to be a class, and have the following characteristics:**
+
+      - The static pluginName property.
+      - Implement the PluginAPI interface (only if it is necessary to proxy the plugin method to bs).
+      - The first argument of the constructor is the BetterScroll instance `bs`. You can inject your own logic through the **event** or **hook** of bs.
+
+      ```typescript
+        export default class MyPlugin implements PluginAPI {
+          static pluginName = 'myPlugin'
+          public options: MyPluginConfig
+          constructor(public scroll: BScroll){
+            this.handleOptions()
+
+            this.handleBScroll()
+
+            this.registerHooks()
+          }
+        }
+      ```
+
+    - **handleOptions**
+
+      Merge user options，narrow down it‘s type。
+
+      ```typescript
+        import { extend } from '@better-scroll/shared-utils'
+        export default class MyPlugin {
+          private handleOptions() {
+            const userOptions = (this.scroll.options.myPlugin === true
+              ? {}
+              : this.scroll.options.myPlugin) as Partial<MyPluginConfig>
+            const defaultOptions: MyPluginConfig = {
+              scrollText: 'I am scrolling',
+              scrollEndText: 'Scroll has ended'
+            }
+            this.options = extend(defaultOptions, userOptions)
+          }
+        }
+      ```
+
+    - **handleBScroll**
+
+      Proxy events and methods to the BetterScroll instance.
+
+      ```typescript
+        export default class MyPlugin implements PluginAPI {
+          private handleBScroll() {
+            const propertiesConfig = [
+              {
+                key: 'printScrollText',
+                sourceKey: 'plugins.myPluginOptions.printScrollText'
+              }
+            ]
+            // myPlugin.printScrollText is proxied to bs.printScrollText
+            this.scroll.proxy(propertiesConfig)
+            // Proxy printScrollEndText event to bs
+            // Users can subscribe to events via bs.on('printScrollEndText', handler)
+            this.scroll.registerType(['printScrollEndText'])
+          }
+
+          printScrollText() {
+            console.log(this.options.scrollText)
+          }
+        }
+      ```
+
+    - **registerHooks**
+
+      Tap into the bs hook, implement the logic of the plugin, and dispatch custom events of the plugin.
+
+      ```typescript
+        export default class MyPlugin implements PluginAPI {
+          private registerHooks() {
+            const scroll = this.scroll
+            scroll.on(scroll.eventTypes.scrollEnd, ({ x, y }) => {
+              scroll.trigger(
+                scroll.eventTypes.printScrollEndText,
+                `${this.options.scrollEndText}, position is (${x}, ${y})`
+              )
+            })
+          }
+        }
+      ```
+
+Congratulations, a simple BetterScroll plugin has been completed. If you need more complex plugin to meet your need, you can read [Events and Hooks](../guide/base-scroll-api.html#events-vs-hooks), it can help you to complete a fantastic plugin.

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

@@ -0,0 +1,109 @@
+# indicators <Badge text="2.2.0" />
+
+## Introduciton
+
+The indicators provides the ability to link with another BetterScroll. With this, you can achieve effects such as **Parallax Scrolling**, **Magnifier**.
+
+::: tip
+This is a very powerful and creative plugin.
+:::
+
+## Install
+
+```bash
+npm install @better-scroll/indicators --save
+
+// or
+
+yarn add @better-scroll/indicators
+```
+
+## Usage
+
+First, install the plugin via the static method `BScroll.use()`
+
+```js
+import BScroll from '@better-scroll/core'
+import Indicators from '@better-scroll/indicators'
+
+BScroll.use(Indicators)
+```
+
+pass correct [indicators options](./indicators.html#indicators-options).
+
+```js
+new BScroll('.wrapper', {
+  indicators: {
+    // For details, please refer to the demo below
+    relationElement: someHTMLElement
+  }
+})
+```
+## Demos
+
+  - **Magnifier**
+
+    <demo qrcode-url="indicators/minimap" :render-code="true">
+      <template slot="code-template">
+        <<< @/examples/vue/components/indicators/minimap.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/indicators/minimap.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/indicators/minimap.vue?style
+      </template>
+      <indicators-minimap slot="demo"></indicators-minimap>
+    </demo>
+
+  - **Parallax Scrolling**
+
+    <demo qrcode-url="indicators/parallax-scroll">
+      <template slot="code-template">
+        <<< @/examples/vue/components/indicators/parallax-scroll.vue?template
+      </template>
+      <template slot="code-script">
+        <<< @/examples/vue/components/indicators/parallax-scroll.vue?script
+      </template>
+      <template slot="code-style">
+        <<< @/examples/vue/components/indicators/parallax-scroll.vue?style
+      </template>
+      <indicators-parallax-scroll slot="demo"></indicators-parallax-scroll>
+    </demo>
+
+## indicators options
+
+### relationElement
+
+  - **Type**: `HTMLElement`
+
+  The container element associated with another BetterScroll, just like the above demo, `div.scroll-indicator` is releationElement. **releationElement must be passed in by the user and has child elements**.
+
+### relationElementHandleElementIndex
+
+  - **Type**: `number`
+  - **Default**: `0`
+
+  Specify the child element of releationElement as the manipulated element. For details, please refer to the above demo.
+
+### ratio
+
+  - **Type**: `number | Ratio | undefined`
+  - **Default**: `undefined`
+
+  ```ts
+  type Ratio = {
+    // Specify the ratio of the scroll distance of x
+    x: number
+    // Specify the ratio of the scroll distance of y
+    y: number
+  }
+  ```
+  Specify the ratio of releationElement to the scrolling distance of BetterScroll. Usually,**the plugin will automatically** calculate the scroll ratio of the two, but you can also manually specify the ratio to achieve the effect of `Parallax Scrolling`. For details, please refer to the demo above.
+
+### interactive
+
+  - **Type**: `boolean | undefined`
+  - **Default**: `undefined`
+
+  Decide whether the relationElementHandleElementIndex of relationElement can interact. When it is set to `false`, it will not respond to touch / mouse events.

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

@@ -0,0 +1,71 @@
+# infinity
+
+The infinity plugin provides BetterScroll with unlimited scrolling capabilities. If you have a large amount of list data to render, you can use the infinity plugin, in which BetterScroll will only render a certain number of DOM elements, so that the page will continue to scroll smoothly when a large amount of data.
+
+> Note: Unless you have a lot of data rendering needs, use coreScroll.
+
+## Install
+
+```shell
+npm install @better-scroll/infinity --save
+
+// or
+
+yarn add @better-scroll/infinity
+```
+
+## Usage
+
+First, install the plugin via the static method `BScroll.use()`
+
+```js
+import BScroll from '@better-scroll/core'
+import InfinityScroll from '@better-scroll/infinity'
+
+BScroll.use(InfinityScroll)
+```
+
+Then, To instantiate BetterScroll, you need to pass the related configuration item `infinity`:
+
+```typescript
+new BScroll('.bs-wrapper', {
+  scrollY: true,
+  infinity: {
+    fetch(count) {
+      // Fetch data that is larger than count, the function is asynchronous, and it needs to return a Promise.。
+      // After you have successfully fetch the data, you need resolve an array of data (or resolve Promise).
+      // Each element of the array is list data, which will be rendered when the render method executes。
+      // If there is no data, you can resolve (false) to tell the infinite scroll list that there is no more data。
+    }
+    render(item, div?: HTMLElement) {
+      // Rendering each element node, item is data from fetch function
+      // div is an element which is recycled from document or undefined
+      // The function needs to return to a html element.
+    },
+    createTombstone() {
+      // Must return a tombstone DOM node.
+    }
+  }
+})
+```
+
+::: danger Note
+`fetch`, `render`, `createTombstone` must be implemented in accordance with the comments as above, otherwise an internal error will be reported.
+
+The plugin relies on Promise internally. If the browser does not support it, the Promise Polyfill is required.
+:::
+
+## Demo
+
+<demo qrcode-url="infinity/" :render-code="true">
+  <template slot="code-template">
+    <<< @/examples/vue/components/infinity/default.vue?template
+  </template>
+  <template slot="code-script">
+    <<< @/examples/vue/components/infinity/default.vue?script
+  </template>
+  <template slot="code-style">
+    <<< @/examples/vue/components/infinity/default.vue?style
+  </template>
+  <infinity-default slot="demo"></infinity-default>
+</demo>