Question

介绍

zoom 插件为 BetterScroll 提供缩放功能。

安装

npm install @better-scroll/zoom --save
// or
yarn add @better-scroll/zoom

使用

为了开启缩放功能，你需要首先引入 zoom 插件，并通过静态方法 BScroll.use() 注册插件

import BScroll from '@better-scroll/core'
import Zoom from '@better-scroll/zoom'

BScroll.use(Zoom)

上面步骤完成后，在 BetterScroll 的基础能力上扩展了缩放的功能，但是想要缩放真正生效，还需要在 options 中传入正确的配置：

new BScroll('.bs-wrapper', {
  freeScroll: true,
  scrollX: true,
  scrollY: true,
  zoom: {
    start: 1,
    min: 0.5,
    max: 2
  }
})

以下是 zoom 插件专属以及 BetterScroll 的配置：

• zoom<插件专属>

  开启 zoom 功能。若没有该项，则插件不会生效。该配置同时也是用来设置 zoom 特性的相关配置，具体请参考 zoom 选项对象。

• freeScroll

  如果希望当放大之后，当前区域在 x 和 y 轴方向都可以滚动时，必须设置为 true。同时需要设置 scrollX 和 scrollY 均为 true。

• scrollX

  如果希望当放大之后，当前区域在 x 轴方向可以滚动时，必须设置为 true。

• scrollY

  如果希望当放大之后，当前区域在 y 轴方向可以滚动时，必须设置为 true。

示例

:::warning zoom 暂不支持在 pc 端的交互操作，下方 demo 请扫码体验。 :::

<<< @/examples/vue/components/zoom/default.vue?template <<< @/examples/vue/components/zoom/default.vue?script <<< @/examples/vue/components/zoom/default.vue?style

zoom 选项对象

start

• 类型：number

• 默认值：1

  初始缩放比例。

min

• 类型：number

• 默认值：1

  最小缩放比例。

max

• 类型：number

• 默认值：4

  最大缩放比例。

initialOrigin

• 类型：[OriginX, OriginY]
  • OriginX：number | 'left' | 'right' | 'center'
  • OriginY：number | 'top' | 'bottom' | 'center'

• 默认值：[0, 0]

  初始化 zoom 插件的缩放原点，当 start 不为 1 的时候有效，缩放原点都是以缩放元素为坐标系。

• 示例

  new BScroll('.bs-wrapper', {
    // ... 其他配置项
    zoom: {
      initialOrigin: [50, 50], // 基于缩放元素的左顶点上下偏移量都是 50 px
      initialOrigin: [0, 0], // 基于缩放元素的左顶点
      initialOrigin: ['left', 'top'], // 与上面效果相同
      initialOrigin: ['center', 'center'], // 基于缩放元素的中心
      initialOrigin: ['right', 'top'], // 基于缩放元素的右顶点
    }
  })
  

  往往你初始化 zoom 的时候只专注于以端点或者中心进行缩放，可以参考以上示例。

minimalZoomDistance

• 类型：number

• 默认值：5

  当你双指进行缩放操作的时候，只有当缩放的距离超过 minimalZoomDistance，zoom 才生效。

bounceTime

• 类型：number

• 默认值：800(毫秒)

  双指不断进行缩放操作并且 scale 超过 max 阈值的时候，当双指离开的时候，内部会「回弹」至 max 的形态，而 bounceTime 就是这次「回弹」行为的动画时长。

:::tip 提示 当 zoom 配置为 true 的时候，插件内部使用的是默认的插件选项对象。

const bs = new BScroll('.wrapper', {
  zoom: true
})

// 相当于

const bs = new BScroll('.wrapper', {
  zoom: {
    start: 1,
    min: 1,
    max: 4,
    initialOrigin: [0, 0],
    minimalZoomDistance: 5,
    bounceTime: 800, // ms
  }
})

:::

实例方法

zoomTo(scale, x, y, [bounceTime])

• 参数

  • {number} scale： 缩放比例
  • {OriginX} x： 缩放原点的 x 坐标，相当于缩放元素的左顶点
    • OriginX：'number | 'left' | 'right' | 'center'
  • {OriginY} y： 缩放原点的 y 坐标，相当于缩放元素的左顶点
    • OriginY：'number | 'top' | 'bottom' | 'center'
  • {number} [bounceTime]<可选>：一次缩放行为的动画时长

  以 [x, y] 坐标作为原点对元素进行缩放。x 与 y 不仅可以是数字，也可以是对应的字符串，因为一般的场景都是基于端点或者中心进行缩放。

• 示例

  const bs = new BScroll('.bs-wrapper', {
  freeScroll: true,
  scrollX: true,
  scrollY: true,
  zoom: {
    start: 1,
    min: 0.5,
    max: 2
  }
  })
  
  bs.zoomTo(1.8, 'left', 'bottom') // 基于缩放元素的左底点缩放至 1.8 倍
  bs.zoomTo(1.8, 'left', 'bottom', 1000) // 基于缩放元素的左底点缩放，动画时长为 1s
  bs.zoomTo(1.8, 100, 100) // 基于缩放元素左顶点的上下偏移量 100 为原点进行缩放
  bs.zoomTo(2, 'center', 'center') // 基于缩放元素的中心进行缩放
  

事件

beforeZoomStart

• 参数：无
• 触发时机：双指接触缩放元素时，不包括直接调用 zoomTo 方法

zoomStart

• 参数：无
• 触发时机：双指缩放距离超过最小阈值 minimalZoomDistance，缩放即将开始。不包括直接调用 zoomTo 方法

zooming

• 参数：{ scale }
• 类型：{ scale: number }

• 触发时机：双指缩放行为正在进行时或者直接调用 zoomTo 进行缩放的过程

• 示例：

  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) // 当前 scale 的值
  })
  

zoomEnd

• 参数：{ scale }
• 类型：{ scale: number }

• 触发时机：双指缩放行为结束后（如果有回弹，触发时机在回弹动画结束之后）或者调用 zoomTo 完成缩放之后

  :::warning 在 zoom 的场景下，你应该监听 zoomStart、zooming、zoomEnd 等等事件，而不是更底层的 scroll、scrollEnd 事件，要不然可能与你的预期不符。 :::