cbvirtua 1.0.105 → 1.0.107

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

@@ -0,0 +1,240 @@
+# zoom
+
+## Introduction
+
+Add zoom functionality for BetterScroll.
+
+## Install
+
+```bash
+npm install @better-scroll/zoom --save
+
+// or
+
+yarn add @better-scroll/zoom
+```
+
+## Usage
+
+import `zoom`, then call `BScroll.use()`.
+
+```js
+import BScroll from '@better-scroll/core'
+import Zoom from '@better-scroll/zoom'
+
+BScroll.use(Zoom)
+```
+
+pass in the correct configuration in options, for example:
+
+```js
+new BScroll('.bs-wrapper', {
+  freeScroll: true,
+  scrollX: true,
+  scrollY: true,
+  zoom: {
+    start: 1,
+    min: 0.5,
+    max: 2
+  }
+})
+```
+
+The following is related to `zoom` plugin and [BetterScroll configuration](../guide/base-scroll-options.html):
+
+- **zoom(for plugin)**
+
+  Enable zoom functionality. That is to say, the zoom plugin won't work without the zoom option, see [zoom option](./zoom.html#option).
+
+- **freeScroll**
+
+  If you want to scroll in x and y axies after zooming in, the **freeScroll** value should be set to `true`. In addtional, **scrollX** and **scrollY** are also need to be true.
+
+- **scrollX**
+
+  `true` is be required if you want to scroll in x axies after zooming in.
+
+- **scrollY**
+
+  `true` is be required if you want to scroll in y axies after zooming in.
+
+## Demo
+
+  :::warning
+  pc is not allowed, scan the qrcode.
+  :::
+
+  <demo qrcode-url="zoom/default" :render-code="true">
+    <template slot="code-template">
+      <<< @/examples/vue/components/zoom/default.vue?template
+    </template>
+    <template slot="code-script">
+      <<< @/examples/vue/components/zoom/default.vue?script
+    </template>
+    <template slot="code-style">
+      <<< @/examples/vue/components/zoom/default.vue?style
+    </template>
+    <zoom-default slot="demo"></zoom-default>
+  </demo>
+
+## Option
+
+### start
+  - **Type**: `number`
+  - **Default**: `1`
+
+    Initial scale.
+
+### min
+  - **Type**: `number`
+  - **Default**: `1`
+
+    min scale.
+
+### max
+  - **Type**: `number`
+  - **Default**: `4`
+
+    max scale.
+
+### initialOrigin
+  - **Type**: `[OriginX, OriginY]`
+    - **OriginX**: `number | 'left' | 'right' | 'center'`
+    - **OriginY**: `number | 'top' | 'bottom' | 'center'`
+  - **Default**: `[0, 0]`
+
+    The origin of first initializing zoom instance, It is valid when `start` is not `1`.The origin is all based on the coordinate system of `scaled element`.
+
+  - **Examples**
+
+  ```js
+    new BScroll('.bs-wrapper', {
+      // ... other configuration
+      zoom: {
+        initialOrigin: [50, 50], // Based on 'scaled element', offsetLeft is 50px, offsetRight is 50px
+        initialOrigin: [0, 0], // Based on 'scaled element', the left vertex
+        initialOrigin: ['left', 'top'], // same as above
+        initialOrigin: ['center', 'center'], // Based on 'scaled element', center position
+        initialOrigin: ['right', 'top'], // Based on 'scaled element', the right vertex
+      }
+    })
+  ```
+
+  When you initialize zoom, you usually focus on zooming with the endpoint or center. You can refer to the above example.
+
+### minimalZoomDistance
+  - **Type**: `number`
+  - **Default**: `5`
+
+    When you zoom with two fingers, only when the zoom distance exceeds `minimalZoomDistance`, the zoom will take effect.
+
+### bounceTime
+  - **Type**: `number`
+  - **Default**: `800`(ms)
+
+    When the two fingers continue to zoom and the scale exceeds the threshold of `max`, when the two fingers leave, the internal "bounce" to the form of `max`, and `bounceTime` is the animation of this "bounce" behavior duration.
+
+:::tip
+When `zoom` is configured as `true`, the plugin uses the default plugin option.
+
+```js
+const bs = new BScroll('.wrapper', {
+  zoom: true
+})
+
+// equals
+
+const bs = new BScroll('.wrapper', {
+  zoom: {
+    start: 1,
+    min: 1,
+    max: 4,
+    initialOrigin: [0, 0],
+    minimalZoomDistance: 5,
+    bounceTime: 800, // ms
+  }
+})
+```
+:::
+
+## Instance Methods
+
+### zoomTo(scale, x, y, [bounceTime])
+  - **Arguments**
+    - `{number} scale`: scale ratio
+    - `{OriginX} x`: The x of origin that is based on the left vertex of the **scaled element**
+      - `OriginX: 'number | 'left' | 'right' | 'center'`
+    - `{OriginY} y`:  The y of origin that is based on the left vertex of the **scaled element**
+      - `OriginY: 'number | 'top' | 'bottom' | 'center'`
+    - `{number} [bounceTime]<Optional>: Animation duration of a zoom action`
+
+    Scale the element with `[x, y]` as the coordinate origin. x and y can be not only `number`, but also corresponding `string`, because general scenes are scaled based on endpoints or centers.
+
+  - **Examples**
+
+  ```js
+  const bs = new BScroll('.bs-wrapper', {
+    freeScroll: true,
+    scrollX: true,
+    scrollY: true,
+    zoom: {
+      start: 1,
+      min: 0.5,
+      max: 2
+    }
+  })
+  // scaled to 1.8 based on the bottom left point of the scaled element
+  bs.zoomTo(1.8, 'left', 'bottom')
+  // animation duration is 1000ms
+  bs.zoomTo(1.8, 'left', 'bottom', 1000)
+  // scaled to 1.8 based on offsetLeft 100px & offsetTop 100px of the scaled element
+  bs.zoomTo(1.8, 100, 100)
+  // scaled to 2 based on the center of scaled element
+  bs.zoomTo(2, 'center', 'center')
+  ```
+
+## Events
+
+### beforeZoomStart
+- **Arguments**: none
+- **Trigger timing**: When two fingers touch the scaled element, it does not include directly calling the `zoomTo` method
+
+### zoomStart
+
+  - **Arguments**: none
+  - **Trigger timing**: The two finger zoom distance exceeds the minimum threshold `minimalZoomDistance`, and the zoom will start soon. it does not include directly calling the `zoomTo` method
+
+### zooming
+
+  - **Arguments**: `{ scale }`
+  - **Type**: `{ scale: number }`
+  - **Trigger timing**: the process of two-finger zooming action in progress or directly calling `zoomTo` to zoom
+
+  - **Examples**:
+  ```js
+    const bs = new BScroll('.bs-wrapper', {
+      freeScroll: true,
+      scrollX: true,
+      scrollY: true,
+      zoom: {
+        start: 1,
+        min: 0.5,
+        max: 2
+      }
+    })
+
+    bs.on('zooming', ({ scale }) => {
+      // use scale
+      console.log(scale) // current scale
+    })
+  ```
+
+### zoomEnd
+
+  - **Arguments**: `{ scale }`
+  - **Type**: `{ scale: number }`
+  - **Trigger timing**: After two finger zooming behavior ends (if there is a rebound, the trigger timing is after the rebound animation ends) or after calling `zoomTo` to complete the zoom
+
+  ::: warning
+  In the zoom scenario, you should listen to events such as `zoomStart`, `zooming`, `zoomEnd`, and not the lower-level `scroll` and `scrollEnd` events, otherwise it may not match your expectations.
+  :::

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/FAQ/README.md

@@ -0,0 +1,41 @@
+# FAQ
+
+### 为什么 BetterScroll 初始化不能滚动？
+
+BetterScroll 滚动原理是 content 元素的高度／宽度超过 wrapper 元素的高度／宽度。而且，如果你的 content 元素含有不固定尺寸的图片，你必须在图片加载完之后，调用 `refresh()` 方法来确保高度计算正确。还存在一种情况是页面存在表单元素，弹出键盘之后，将页面的视口高度压缩，导致 bs 不能正常工作，依然是调用 `refresh()` 方法。
+
+### 为什么 BetterScroll 区域的点击事件无法被触发？
+
+BetterScroll 默认会阻止浏览器的原生 click 事件。如果你想要 click 事件生效，BetterScroll 会派发一个 click 事件，并且 event 参数的 `_constructed` 为 true。配置项如下：
+
+```js
+import BScroll from '@better-scroll/core'
+
+let bs = new BScroll('./div', {
+  click: true
+})
+```
+
+### 为什么我的 BetterScroll 监听 `scroll` 钩子，监听器不执行？
+
+BetterScroll 通过 probeType 配置项来决定是否派发 `scroll` 钩子，因为这是有一些性能损耗的。probeType 为 2 的时候会实时的派发事件，probeType 为 3 的时候会在 momentum 动量动画的时候派发事件。建议设置为 3。
+
+```js
+import BScroll from '@better-scroll/core'
+
+let bs = new BScroll('./div', {
+  probeType: 3
+})
+```
+
+### slide 用了横向滚动，发现在 slide 区域纵向滚动无效？
+
+如果想要保留浏览器的原生纵向滚动，需要如下配置项：
+
+```js
+import BScroll from '@better-scroll/core'
+
+let bs = new BScroll('./div', {
+  eventPassthrough: 'vertical'
+})
+```

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/FAQ/diagnosis.md

@@ -0,0 +1,178 @@
+# BetterScroll 的“疑难杂症”
+
+### 【问题一】为什么我的 BetterScroll 滑动不了？
+
+问题基本上出在于**高度的计算错误**。首先，你必须对 `BetterScroll` 的滚动原理有一个清晰的认识，对于竖向滚动，简单的来说就是 `wrapper` 容器的高度大于 `content` 内容的高度，修改 `translateY` 来达到滚动的目的，横向滚动的原理类似。那么计算**可滚动的高度**就是 BetterScroll 必备的逻辑。一般这个逻辑出错的场景在于：
+
+  1. **存在不确定尺寸的图片**
+
+      - **原因**
+
+        bs 执行计算**可滚动高度**的时候，图片还未渲染完成，也无法监听到图片的加载。有时候甚至配置 `observeDOM` 为 `true` 也没效果。
+
+      - **解决**
+
+        在图片的 onload 的回调函数里面调用 `bs.refresh()` 来确保得到正确的图片高度之后再计算**可滚动的高度**。
+
+        :::tip
+        `observeDOM` 为 `true` 的时候，BetterScroll 首先通过 [MutationObserver](https://developer.mozilla.org/zh-CN/docs/Web/API/MutationObserver) 来监视对 DOM Tree 的改变，但是**无法监听图片是否加载完成**，所以需要手动调用 `refresh()` 来计算高度。
+
+        如果当前浏览器不支持 MutationObserver，会降级用 `setTimeout` 每隔 1s 来重复计算可滚动的高度，这样又能保证在图片加载完成之后，可滚动的高度计算正确。
+        :::
+
+  2. **Vue 的 keep-alive 组件**
+
+      - **场景**
+
+        假设存在 A、B 两个被 `keep-alive` 包裹的组件，A 组件使用了 BetterScroll，在 A 组件做了某种操作，弹出输入键盘，之后进入到 B 组件，再返回 A 组件的时候，bs 无法滚动。
+
+      - **原因**
+
+        由于 Vue 的 keep-alive 的缓存加上输入键盘弹起时候，会压缩可视区域的高度，导致之前计算过的可滚动的高度有误。
+
+      - **解决**
+
+        可以在 Vue 的 `activated` 的钩子里面调用 `bs.refresh()` 重新计算高度或者重新实例化 bs。
+
+### 【问题二】为什么我用 BetterScroll 做了横向滚动之后，纵向滚动失效？
+
+BetterScroll 提供了 `slide` 的 feature。如果实现了一个横向滚动的 `slide`，在 `slide` 区域做竖向滚动的操作，无法冒泡到浏览器，这样就无法操纵原生浏览器的滚动条了。
+
+- **原因**
+
+  BetterScroll 内部的滚动计算存在于用户的交互，比如移动端就是 `touchstart/touchmove/touchend` 事件，这些事件的侦听器一般都有 `e.preventDefault()` 这一行代码，会阻止浏览器的默认行为，这样浏览器的滚动条无法被滚动。
+
+- **解决**
+
+  配置 `eventPassthrough` 属性。
+
+  ```js
+  let bs = new BScroll('.wrapper', {
+    eventPassthrough: 'vertical' // 保持纵向的原生浏览器滚动
+  })
+  ```
+
+### 【问题三】为什么我用 BetterScroll 之后，无法在浏览器弹出长按图片保存等弹窗。
+
+- **原因**
+
+  在**问题二**已经提到了，`touchstart` 事件里面的`e.preventDefault()` 造成的。
+
+- **解决**
+
+  方案一：配置 `preventDefaultException` 属性。
+
+  ```js
+  let bs = new BScroll('.wrapper', {
+    preventDefaultException: {
+      className: /(^|\s)test(\s|$)/
+    }
+  })
+  ```
+
+  通过 `preventDefaultException` 可以控制 `touchstart` 和 `touchmove` 事件的 `e.preventDefault()`。上述的正则是用来校验当前触摸的目标元素 class 名称是否含有 `test`，如果通过了，则不会调用 `e.preventDefault()`。
+
+  方案二：配置 `preventDefault` 属性。
+
+  ```js
+  let bs = new BScroll('.wrapper', {
+    preventDefault: false
+  })
+  ```
+
+  preventDefault 设置为 false，会有一些副作用，一般推荐使用**方案一**。
+
+  :::warning
+  副作用在于：touch 事件可能会冒泡到 document，导致文档也被拖拽。这个时候你需要监听 `wrapper` 元素的父元素或者祖先元素，给他们绑定 touchmove 事件，并且调用 `e.preventDefault()`。最常见的应该是[禁止微信下拉浏览器查看域名](https://www.cnblogs.com/jasonwang2y60/p/6848464.html)
+  :::
+
+### 【问题四】为什么 BetterScroll content 内部的所有的 click 事件的侦听器都不触发？
+
+- **原因**
+
+  依然是 `touch` 事件的 `e.preventDefault()` 的原因。在移动端，如果你在 `touchstart/touchmove/touchend` 的逻辑里面调用 `e.preventDefault()`，会阻止它以及它子元素的 click 事件的执行。因此，BetterScroll 内部会管理 `click` 事件的派发，你只需要 `click` 配置项即可。
+
+- **解决**
+
+  配置 `click` 属性。
+
+  ```js
+  let bs = new BScroll('.wrapper', {
+    click: true
+  })
+  ```
+
+### 【问题五】为什么在嵌套 BetterScroll 的时候，click 事件派发两次？
+
+- **原因**
+
+  正如**问题四**所说，BetterScroll 内部会派发 `click` 事件，并且嵌套场景肯定是存在两个或两个以上的 bs。
+
+- **解决**
+
+  你可以通过实例化内层 BetterScroll 的 `stopPropagation` 配置项来管理事件的冒泡，或者通过配置内层 BetterScroll 的 `click` 配置项来防止 click 的多次触发。
+
+  ```js
+  let innerBS = new BScroll('.wrapper', {
+    stopPropagation: true
+  })
+
+  // 或者
+  let innerBS = new BScroll('.wrapper', {
+    click: false
+  })
+  ```
+
+### 【问题六】为什么我监听了 bs 的 scroll 事件，为啥回调不执行？
+
+- **原因**
+
+  BetterScroll 并不是在任何时刻都会派发 `scroll` 事件，因为获取 bs 的滚动位置是有一定的性能损耗。至于是否派发，是取决于 `probeType` 配置项。
+
+- **解决**
+
+  ```js
+  let bs = new BScroll('.div', {
+    probeType: 3 // 实时派发
+  })
+  ```
+
+### 【问题七】在两个纵向嵌套的 bs 场景，为什么移动内层的 bs，会导致外层也被滚动。
+
+- **原因**
+
+  BetterScroll 的内部逻辑都在 touch 事件的侦听器函数体内，既然内部的 bs 的 touch 事件被触发，自然会冒泡到外层的 bs。
+
+- **解决**
+
+  既然知道原因，那么也有相对应的解决办法。比如在你滚动内层的 bs 时候，监听 scroll 事件，调用外层的 `bs.disable()` 来禁用外层的 bs。当内层的 bs 滚动到底部的时候，说明这个时候需要滚动外层的 bs，这个时候调用外层的 `bs.enable()` 来激活外层，并且调用内层的 `bs.disable()` 禁止内层滚动。其实仔细想一想，这个交互就跟原生 Web 的嵌套滚动行为表现一致，只不过浏览器帮你处理了各种滚动嵌套的逻辑，而在 BetterScroll 需要你自己通过派发的事件以及暴露的 API 来实现。
+
+  > cube-ui 的 [scroll](https://didi.github.io/cube-ui/example/#/scroll/v-scrolls) 组件对此场景给出了相应的解决思路。[代码在这](https://github.com/didi/cube-ui/blob/dev/src/components/scroll/scroll.vue)
+
+### 【问题八】在纵向 bs 嵌套横向 bs 的场景，为什么在横向 bs 的区域竖向移动不会使得外层纵向 bs 的垂直滚动？
+
+- **原因**
+
+  原因与**问题二**类似，还是因为 `e.preventDefault()` 影响了默认的滚动行为，导致外层的 bs 不会触发 touch 事件。
+
+- **解决**
+
+  解决办法就是配置内层的 bs 的 `eventPassthrough` 属性，让其保持默认的原生竖向滚动，
+
+  ```js
+  let innerBS = new BScroll('.wrapper', {
+    eventPassthrough: 'vertical' // 保持纵向的原生浏览器滚动
+  })
+  ```
+ 
+### 【问题九】国产浏览器中，横向 slide 切换卡顿或无效问题。
+
+- **原因**
+
+  国产浏览器大多数都会监听默认的横滑事件，以实现浏览器的快速“回退”和”前进“。
+  
+- **解决**
+
+  主要是使用一个 CSS 特性`touch-action`，如果是横向的滑动，将 `touch-action: pan-y` CSS 设置在 `wrapper` 上面，这样就可以避免横向的切换触发浏览器的默认行为。
+
+

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

@@ -0,0 +1,14 @@
+---
+home: true
+heroText: BetterScroll 2.0
+actionText: 快速上手 →
+actionLink: /zh-CN/guide/
+features:
+- title: 优雅的滚动
+  details: 为移动端（已支持 PC）各种滚动场景提供丝滑的滚动效果。
+- title: 零依赖
+  details: 基于原生 JS 实现的，不依赖任何框架。完美运用于 Vue、React 等 MVVM 框架。
+- title: 扩展灵活
+  details: 提供插件机制，便于对基础滚动进行功能扩展，目前支持上拉加载、下拉刷新、Picker、鼠标滚轮、放大缩小、移动缩放、轮播图、滚动视觉差，放大镜等等能力
+footer: MIT Licensed | Copyright © 2018-present ustbhuangyi and theniceangel
+---

package/better-scroll-dev/better-scroll-dev/packages/vuepress-docs/docs/zh-CN/guide/README.md

@@ -0,0 +1,83 @@
+# 介绍
+
+## BetterScroll 是什么
+
+BetterScroll 是一款重点解决移动端（已支持 PC）各种滚动场景需求的插件。它的核心是借鉴的 [iscroll](https://github.com/cubiq/iscroll) 的实现，它的 API 设计基本兼容 iscroll，在 iscroll 的基础上又扩展了一些 feature 以及做了一些性能优化。
+
+BetterScroll 是使用纯 JavaScript 实现的，这意味着它是无依赖的。
+
+## 示例
+
+[地址](https://better-scroll.github.io/examples/)
+
+<img data-zoomable :src="$withBase('/assets/images/qrcode.png')" alt="示例">
+
+## 起步
+
+BetterScroll 最常见的应用场景是列表滚动，我们来看一下它的 html 结构。
+
+```html
+<div class="wrapper">
+  <ul class="content">
+    <li>...</li>
+    <li>...</li>
+    ...
+  </ul>
+  <!-- 这里可以放一些其它的 DOM，但不会影响滚动 -->
+</div>
+```
+上面的代码中 BetterScroll 是作用在外层 **wrapper** 容器上的，滚动的部分是 **content** 元素。这里要注意的是，BetterScroll 默认处理容器（wrapper）的第一个子元素（content）的滚动，其它的元素都会被忽略。
+
+最简单的初始化代码如下：
+
+``` js
+import BScroll from '@better-scroll/core'
+let wrapper = document.querySelector('.wrapper')
+let scroll = new BScroll(wrapper)
+```
+BetterScroll 提供了一个类，实例化的第一个参数是一个原生的 DOM 对象。当然，如果传递的是一个字符串，BetterScroll 内部会尝试调用 querySelector 去获取这个 DOM 对象。
+
+:::warning 注意
+BetterScroll 2.X 里面，我们将 1.X 耦合的 feature 拆分至插件，以达到按需加载、减少包体积的目的。因此，`@better-scroll/core` 只提供了最核心的滚动能力。如果想要实现**上拉加载**、**下拉刷新**的功能，你需要使用对应的[插件](/zh-CN/plugins)。
+:::
+
+:::tip 提示
+版本 2.0.4 的 BetterScroll 可以通过 [specifiedIndexAsContent](./base-scroll-options.html#specifiedindexascontent-2-0-4) 来指定 wrapper 的某个子元素作为 content。
+:::
+
+## 滚动原理
+
+很多人已经用过 BetterScroll，我收到反馈最多的问题是：
+
+> BetterScroll 初始化了， 但是没法滚动。
+
+不能滚动是现象，我们得搞清楚这其中的根本原因。在这之前，我们先来看一下浏览器的滚动原理：
+浏览器的滚动条大家都会遇到，当页面内容的高度超过视口高度的时候，会出现纵向滚动条；当页面内容的宽度超过视口宽度的时候，会出现横向滚动条。也就是当我们的视口展示不下内容的时候，会通过滚动条的方式让用户滚动屏幕看到剩余的内容。
+
+BetterScroll 也是一样的原理，我们可以用一张图更直观的感受一下：
+
+<img data-zoomable :src="$withBase('/assets/images/schematic.png')" alt="原理图">
+
+绿色部分为 wrapper，也就是父容器，它会有**固定的高度**。黄色部分为 content，它是父容器的**第一个子元素**，它的高度会随着内容的大小而撑高。那么，当 content 的高度不超过父容器的高度，是不能滚动的，而它一旦超过了父容器的高度，我们就可以滚动内容区了，这就是 BetterScroll 的滚动原理。
+
+## BetterScroll 在 MVVM 框架的应用
+
+我之前写过一篇[当 BetterScroll 遇见 Vue](https://zhuanlan.zhihu.com/p/27407024)，也希望大家投稿，分享一下 BetterScroll 在其它框架下的使用心得。
+
+一款超赞的基于 Vue 实现的组件库 [cube-ui](https://github.com/didi/cube-ui/)。
+
+## BetterScroll 在实战项目中的运用
+
+如果你想学习 BetterScroll 在实战项目中的运用，也可以去学习我的 2 门实战课程。
+
+[Vue.js 高仿外卖饿了么实战课程](https://coding.imooc.com/class/74.html)
+
+[项目演示地址](http://ustbhuangyi.com/sell/)
+
+![二维码](https://qr.api.cli.im/qr?data=http%253A%252F%252Fustbhuangyi.com%252Fsell%252F%2523%252Fgoods&level=H&transparent=false&bgcolor=%23ffffff&forecolor=%23000000&blockpixel=12&marginblock=1&logourl=&size=280&kid=cliim&key=686203a49c4613080b5b3004323ff977)
+
+[Vue.js 音乐 App 高级实战课程](http://coding.imooc.com/class/107.html)
+
+[项目演示地址](http://ustbhuangyi.com/music/)
+
+![二维码](https://qr.api.cli.im/qr?data=http%253A%252F%252Fustbhuangyi.com%252Fmusic%252F&level=H&transparent=false&bgcolor=%23ffffff&forecolor=%23000000&blockpixel=12&marginblock=1&logourl=&size=280&kid=cliim&key=731bbcc2b490454d2cc604f98539952c)