@shanjuhudong/qq-base v1.4.0

QQ小程序公用包

安装

前提：项目要使用npm包，关于npm包的使用，请参考官方文档。也可以直接使用脚手架qq-mini-cli，但要注意更新版本及版本变更迁移。

1. 在你的项目运行指令： npm install --save @shanjuhudong/qq-base(升级版本也可以用这个命令)
2. 在小程序开发者工具菜单：工具 -> 构建npm
3. 在你的项目的app.js最顶部引入: import '@shanjuhudong/qq-base'

功能说明

• App和Page的生命周期支持异步函数进行异步串行，方便做登录拦截等异步操作

  // 例：
  // app.js
  App({
      // async/wait写法
      async onLaunch(){
          await new Promise(resolve => {
              setTimeout(resolve, 1000)
          })
      },
      // 返回Promise写法
      onLaunch(){
          return new Promise(resolve => {
              setTimeout(resolve, 1000)
          })
      }
  })
  // page.js
  Page({
      onLoad(){
          //这里将会等到app.js的onLaunch异步结束后，才执行
          console.log('page loaded')
      }
  })

• Component自定义组件实例增加了parent和emit字段，parent是在父组件调用this.selectComponent后产生，是父级组件或页面的实例对象，emit是增强版事件触发器（代替triggerEvent），让事件支持异步串行机制，也就是说，它可以现实等待异步事件函数完成后才往下继续执行，另外，emit不需要在qml文件内的标签上使用bind绑定事件，即使绑定也无效，它必须只能在父级声明与事件同名（一般使用带on开头）的函数才会生效。

  //例：
  // 原生事件：
  // my-component.js
  Component({
      lifetimes: {
          created(){
              //原生事件触发方法
              this.triggerEvent('created')
          }
      }
  })
  // page.qml
  <my-compoent bindcreated="onCreated"/>
  // page.js
  Page({
      //原生事件函数
      onCreated(){
          console.log('native event handler')
      }
  })
  // 增强事件：
  // my-component.js
  Component({
      lifetimes: {
          created(){
              //增强事件触发方法，注意：事件名建议用大陀峰命名法
              this.emit('Created')
          }
      }
  })
  // page.qml 这里不需要在标签上bind或catch事件，直接在父级页面定义函数名on拼接事件名(created)即可，即onCreated
  <my-compoent/>
  // page.js
  Page({
      //增强版事件函数
      onCreated(){
          console.log('plus event handler')
      }
  })
  // 增加版事件的特点：假如我们需要在组件内等待事件函数异步执行结果再往下走逻辑，那么原生事件是无法做到的，而增加版事件则可以如下操作
  // my-component.js
  Component({
      lifetimes: {
          async created(){
              let result = await this.emit('Created')
              // 往下逻辑依赖于上面的结果
              console.log(result) //这里将在1秒后打印: 1000ms
          }
      }
  })
  // page.qml 这里不需要在标签上bind或catch事件，直接在父级页面定义函数名on拼接事件名(created)即可，即onCreated
  <my-compoent/>
  // page.js
  Page({
      //增强版事件函数
      onCreated(){
          console.log('plus event handler')
          return new Promise(resolve => {
              setTimeout(() => {
                  resolve('1000ms')
              }, 1000)
          })
      }
  })

• 放弃使用app.globalData对象而创建qq.SJ公用对象，在它身上挂载所有全局公用的数据和函数，详细见下方文档

文档

1. 公用函数

2. 常量

• BASE_WIDTH: 视觉稿宽度，值750
• BRAND: 设备品牌
• IS_ANDROID: 是否安卓系统
• IS_IOS: 是否IOS系统
• MODEL: 设备型号。新机型刚推出一段时间会显示unknown
• OS: 操作系统及版本
• SDK_VERSION: 客户端基础库版本
• VERSION: 版本号
• VIDEO_H: 播放页视频原高度
• VIDEO_S: 播放页视频高宽比（VIDEO_H / VIDEO_W）
• VIDEO_W: 播放页视频原宽度
• WIDTH_CALC_CUT: 最终裁切宽度，基于UI宽750
• WIDTH_CUT_LIMIT: 裁切的上限
• WIN_H: 屏幕显示区域高
• WIN_S: 屏幕显示区域高宽比(WIN_H/WIN_S)
• WIN_W: 屏幕显示区域宽
• W_RATE: 屏幕显示区域宽与视觉稿宽比例 (WIN_S/BASE_WIDTH)

3. 其他变量

• config: 一些全局的基础配置项，如：异步请求的base_url，header以及版本号等，可以通过$merge(SJ.config, {})插入更多配置项
• voice: 音效控制对象
  • voice.add(arr: String[], baseUrl: String='https://img.shanju.fun/voice'): 添加音效初始化，可以一次添加多个相同base地址的音效，例如，
    • 添加默认地址的音效：add(['a.mp3', 'b.mp3']), 音效在腾讯云上传
    • 添加其他地址的音效：add(['c.mp3'], 'https://***')
  • voice.play(name: String, loop: Boolean): 播放，必须先add之后再play，否则无效，播放参数name只需要写音效的名字即可，如：
    • play('a')，则播放https://img.shanju.fun/voice/a.mp3
    • play('c')，则播放https://***/c.mp3
    • 循环播放：play('a', true)，一般用于播放背景音乐之类的
  • voice.pause(name): 暂停指定name的音频
  • voice.stop(name): 停止指定name的音频
  • voice.destroy(name): 销毁指定name的音频
  • voice.clear(): 销毁所有音频，世界安静了

4. 组件

• scene(播放页)

  • 参数:
    • optionUse: Object 选项消耗配置
      • adNormal: Object 广告解锁选项配置
        • id: String 广告id
        • mark: Number 参考$videoAd，默认值由init.cfg.sad参数决定，为T时，mark为2，否则为0
        • times: Number 参考$videoAd
        • errorMsg: String 参考$videoAd
        • outedMsg: String 参考$videoAd，默认: '要看完视频才可以解锁诶！'
        • endedMsg: String 参考$videoAd
      • adCoin02: Object 看广告补充金币/体力/资源等用以解锁选项
        • id: String 广告id
        • mark: Number 参考$videoAd
        • times: Number 参考$videoAd
        • errorMsg: String 参考$videoAd
        • outedMsg: String 参考$videoAd
        • endedMsg: String 参考$videoAd
        • overTimesMsg: String 补充次数达上限时弹出的消息
        • successMsg: String 补充成功时弹出的消息
        • modal: Object 未看完广告弹出modal参数配置
          • title: String 标题，默认：'提示'
          • content: String 内容，默认：'看完整视频即可补满体力！'
          • cancelText: String 取消按钮文案，默认：'返回首页'
          • confirmText: String 确定按钮文案，默认：'继续恢复'
  • 属性:
    • data: 数据模型
    • state: 数据管理对象，通过它可以访问剧数据，片段数据等
    • options: 选项组件
    • player: 播放器组件
  • 事件（增强版）:
    • onGameLoadStart: 请求剧数据前执行
    • onGameLoadEnd: 剧数据请求完成后执行
    • onSceneLoadStart: 请求片段前执行
    • onSceneLoadEnd: 请求片段完成后执行
    • onWillPlay: 即将开始（首次）播放时执行
    • onPlay: 播放器播放时执行
    • onReplay: 点击重玩时执行
    • onPause: 播放器暂停时执行
    • onEnded: 片段视频播放结束时执行
    • onWaiting: 视频加载缓冲时执行
    • onNextMount: 播放下个片段前将要播放的片段准备就绪时执行
    • onBeforeOptionsHide: 选项hide方法被调之前执行，即使无选项或选项处于隐藏状态也会执行(这与onOptionsHideStart不同)，一般用于处理选项将要执行隐藏环节之前要处理的逻辑
    • onAfterOptionsShow: 选项hide方法被调用之后执行，即使无选项或选项处于隐藏状态也会执行(这与onOptionsHideEnd不同)，一般用于处理选项执行完隐藏环节之后要处理的逻辑
    • onGameOver: 到达最后一个片段，游戏结束时执行
    • onOptionsShowStart: 选项出现前执行
    • onOptionsShowEnd: 选项出现动画结束后执行
    • onOptionsHideStart: 选项退出前执行
    • onOptionsHideEnd: 选项完全退出后执行
    • onOptionsClickOption: 点击选项时执行
    • OptionsClickTopic: 点击选项标题时执行（如果选项标题允许点击的话）
    • onOptionsSubmit: 点击选项时选项表单提交事件回调执行
  • 方法:
    • init: 初始化，需要传入onLoad的参数
    • start: 开始剧，需要传入剧请求参数

• player(播放器)

  • 属性:
    • data
  • 事件:
    • play: 视频播放时执行
    • replay: 重玩时执行
    • pause: 视频暂停时执行
    • ended: 视频结束时执行
    • waiting: 视频缓冲时执行
  • 方法:
    • init: 初始化，需要传入state
    • start: 放入片段开始自动播放，需要传入state，state包含片段
    • play: 播放
    • pause: 暂停
    • stop: 停止
• options(选项)
  • 属性:
    • data
    • stopClick: 为true时阻止点击，设置为false时允许点击。如果在点击选项后做一些网络请求的等待无法往下走流程时，要主动设置为false才可以点击，否则只有选项完成退出动画后才会自动为false
  • 事件（增强版）:
    • OptionsClickTopic: 点击选项标题时执行（如果选项标题允许点击的话）
    • onOptionsShowStart: 选项出现前执行
    • onOptionsShowEnd: 选项出现动画结束后执行
    • onOptionsHideStart: 选项退出前执行
    • onOptionsHideEnd: 选项完全退出后执行
    • onOptionsClickOption: 点击选项时执行
    • onOptionsSubmit: 点击选项时选项表单提交事件回调执行
  • 方法:
    • init: 初始化，需要传入state
    • show: 显示选项，需要传入state
    • hide: 隐藏选项
• option(选项子项)
  • 参数:
    • index: Number, 选项的下标
    • item: Object, 选项的item数据
    • style: Object, 选项样式
    • shareType: Number, 选项有分享功能时，分享的类型（参数小程序官方文档button的share-type），默认值2
    • adPay: Number, 去广告，默认0
    • activeLink: Number, 点击时被点击的选项的link（取自item.link)
  • 属性:
    • data
  • 事件: 无
  • 方法: 无
• topic(选项题目)
  • 参数:
    • bgColor: String, 背景颜色
    • title: String, 题目文案
    • ltImg: String, 左上角饰
    • lbImg: String, 左下角饰
    • rtImg: String, 右上角饰
    • rbImg: String, 右下角饰
  • 属性:
    • data
  • 事件:
    • click 点击
  • 方法: 无
• sj-modal(模态框底座)
  • 参数:
    • maskColor: String, 背景遮罩颜色，默认rgba(0,0,0,.5)
    • clkBlankHide: Boolean, 点击空白区域是否隐藏，默认true
  • 属性:
    • data
  • 事件:
    • click 点击时触发
    • show 显示后触发
    • hide 隐藏后触发
  • 方法:
    • show 显示，接收object类型参数，会被放置到data中
    • hide 隐藏
    • toggle 显示/隐藏 来回互换，接收参数同show方法

5. state（数据管理对象）

• 基本属性:
  • query: 剧请求的参数
  • game: 剧数据，与接口video/game数据相同
  • attr: 剧或片段属性，取自接口video/scene中的res.data.scene.addition.attr
  • next: 片段列表，取自接口video/scene中的res.data.next
  • levelInfo: 片段列表，取自接口video/scene中的res.data.scene.addition.levelInfo
  • sceneState: 片段加载状态, 开始加载时，值为loadstart，加载完成时值为loadend
  • option: 点击选项后，选项数据将暂存到此
  • clickX: 点击时，点击位置的x坐标
  • clickY: 点击时，点击位置的x坐标
  • 其他（自行打印到控制台查看）
• 方法:
  • $get: 从state上获取指定属性的值。如获取剧数据：state.$get('game')，当然，也可以直接state.game，但如果要获取下一级字段如：state.game.scene，state.$get会自动处理访问链的值是否有效的问题，即let scene = state.$get('game.scene')等价于let scene = state.game && state.game.scene || null，所以为了安全起见，请尽量通过$get访问
  • $set: 给state上挂载数据，如：state.$set('game', gameData)，同样，它支持任意多级链设置，如：state.$set('game.scene', sceneData)，当访问链中的某个字段值不存在时，自动创建对象