QinJs 官网

Appearance

qinjs 的 js API 由标准 ECMAScript 的 js API 和 qin 扩展 API 这两部分组成。

标准 ECMAScript 的 js 仅是最基础的 js。浏览器基于它扩展了 window 、 document 、 navigator 等对象。小程序也基于标准 js 扩展了各种 wx.xx 、 tt.xx 、 swan.xx 的 API 。 node 也扩展了 fs 等模块。

qinjs 基于 ECMAScript 扩展了 qin 对象，并且 API 命名与小程序保持兼容。

标准 js 和浏览器 js 的区别 ​

qinjs 的 js 代码，小程序在 v8 引擎中，都没有运行在浏览器或 webview 里。

非 h5 端，虽然不支持 window 、 document 、 navigator 等浏览器的 js API ，但也支持标准 ECMAScript 。

请注意不要把浏览器里的 js 等价于标准 js。

所以 qinjs 的 h5 端，一样支持标准 js ，支持 if、for 等语法，支持字符串、数字、时间、布尔值、数组、自定义对象等变量类型及各种处理方法。仅仅是不支持 window 、 document 、navigator 等浏览器专用对象。

各端特色 API 调用 ​

除了 qinjs 框架内置的跨端 API，各端自己的特色 API 也可通过条件编译自由使用。

各端特色 API 规范参考各端的开发文档。

各平台的 API 新增，不需要 qinjs 升级，开发者就可以直接使用。

说明 ​

  • qin.on 开头的 API 是监听某个事件发生的 API 接口，接受一个 CALLBACK 函数作为参数。当该事件触发时，会调用 CALLBACK 函数。
  • 如未特殊约定，其他 API 接口都接受一个 OBJECT 作为参数。
  • OBJECT 中可以指定 success ， fail ， complete 来接收接口调用结果。
  • 平台差异说明若无特殊说明，则表示所有平台均支持。
  • 异步 API 会返回 errMsg 字段，同步 API 则不会。比如：getSystemInfoSync 在返回结果中不会有 errMsg。

API Promise 化 ​

  1. 具体 API Promise 化 的策略：

    • 异步的方法，如果不传入 success 、 fail 、 complete 等 callback 参数，将以 Promise 返回数据。例如：qin.getImageInfo()

    • 异步的方法，且有返回对象，如果希望获取返回对象，必须至少传入一项 success 、 fail 、 complete 等 callback 参数。例如：

      js
       // 正常使用
 const task = qin.connectSocket(
  success(res){
   console.log(res)
  }
 )

 // Promise 化
 qin.connectSocket().then(res => {
   // 此处即为正常使用时 success 回调的 res
   // qin.connectSocket() 正常使用时是会返回 task 对象的，如果想获取 task ，则不要使用 Promise 化
   console.log(res)
 })
       // 正常使用
 const task = qin.connectSocket(
  success(res){
   console.log(res)
  }
 )

 // Promise 化
 qin.connectSocket().then(res => {
   // 此处即为正常使用时 success 回调的 res
   // qin.connectSocket() 正常使用时是会返回 task 对象的，如果想获取 task ，则不要使用 Promise 化
   console.log(res)
 })

  2. 不进行 Promise 化 的 API：

    • 同步的方法（即以 sync 结束）。例如：qin.getSystemInfoSync()
    • 以 create 开头的方法。例如：qin.createMapContext()
    • 以 manager 结束的方法。例如：qin.getBackgroundAudioManager()

Vue 3 的 API Promise 化 ​

Vue 3 项目中 API Promise 化 返回格式不一致，以下为 不同点 和 返回格式互相转换

Vue3 对部分 API 进行了 Promise 封装，调用成功会进入 then 方法 回调。调用失败会进入 catch 方法 回调

使用示例：

js
// 默认方式
qin.request({
  url: "https://www.example.com/request",
  success: (res) => {
    console.log(res.data);
  },
  fail: (err) => {
    console.error(err);
  },
});

// 使用 Promise then/catch 方式调用
qin
  .request({
    url: "https://www.example.com/request",
  })
  .then((res) => {
    // 此处的 res 参数，与使用默认方式调用时 success 回调中的 res 参数一致
    console.log(res.data);
  })
  .catch((err) => {
    // 此处的 err 参数，与使用默认方式调用时 fail 回调中的 err 参数一致
    console.error(err);
  });

// 使用 Async/Await 方式调用
async function request() {
  try {
    var res = await qin.request({
      url: "https://www.example.com/request",
    });
    // 此处的 res 参数，与使用默认方式调用时 success 回调中的 res 参数一致
    console.log(res);
  } catch (err) {
    // 此处的 err 参数，与使用默认方式调用时 fail 回调中的 err 参数一致
    console.error(err);
  }
}
// 默认方式
qin.request({
  url: "https://www.example.com/request",
  success: (res) => {
    console.log(res.data);
  },
  fail: (err) => {
    console.error(err);
  },
});

// 使用 Promise then/catch 方式调用
qin
  .request({
    url: "https://www.example.com/request",
  })
  .then((res) => {
    // 此处的 res 参数，与使用默认方式调用时 success 回调中的 res 参数一致
    console.log(res.data);
  })
  .catch((err) => {
    // 此处的 err 参数，与使用默认方式调用时 fail 回调中的 err 参数一致
    console.error(err);
  });

// 使用 Async/Await 方式调用
async function request() {
  try {
    var res = await qin.request({
      url: "https://www.example.com/request",
    });
    // 此处的 res 参数，与使用默认方式调用时 success 回调中的 res 参数一致
    console.log(res);
  } catch (err) {
    // 此处的 err 参数，与使用默认方式调用时 fail 回调中的 err 参数一致
    console.error(err);
  }
}
  • 返回格式互相转换
js
function isPromise(obj) {
  return (
    !!obj &&
    (typeof obj === "object" || typeof obj === "function") &&
    typeof obj.then === "function"
  );
}

qin.addInterceptor({
  returnValue(res) {
    if (!isPromise(res)) {
      return res;
    }
    const returnValue = [undefined, undefined];
    return res
      .then((res) => {
        returnValue[1] = res;
      })
      .catch((err) => {
        returnValue[0] = err;
      })
      .then(() => returnValue);
  },
});
function isPromise(obj) {
  return (
    !!obj &&
    (typeof obj === "object" || typeof obj === "function") &&
    typeof obj.then === "function"
  );
}

qin.addInterceptor({
  returnValue(res) {
    if (!isPromise(res)) {
      return res;
    }
    const returnValue = [undefined, undefined];
    return res
      .then((res) => {
        returnValue[1] = res;
      })
      .catch((err) => {
        returnValue[0] = err;
      })
      .then(() => returnValue);
  },
});

API 列表 ​

基础 ​

日志打印 ​
API说明
日志打印向控制台打印日志信息
定时器在定时到期以后执行注册的回调函数
qin.base64ToArrayBuffer将 Base64 字符串转成 ArrayBuffer 对象
qin.arrayBufferToBase64将 ArrayBuffer 对象转成 Base64 字符串
应用级事件监听应用事件
拦截器拦截 Api 等调用并执行回调

环境 ​

API说明
qin.platform会返回当前打包环境环境
qin.isH5会返回是否是 h5 环境
qin.isWxH5会返回是否是 微信浏览器 环境
qin.isWx会返回是否是 微信小程序 环境
qin.isTt会返回是否是 抖音小程序 环境
qin.isKs会返回是否是 快手小程序 环境
qin.isXhs会返回是否是 小红书小程序 环境
qin.isHarmonyOS会返回是否是 鸿蒙 浏览器环境
qin.isTtWebview会返回是否是在抖音小程序 webview 中
qin.isWxWebview会返回是否是在微信小程序 webview 中
qin.isKsWebview会返回是否是在快手小程序 webview 中
qin.isWebview会返回是否是在 webview 中

网络 ​

发起请求 ​
API说明
qin.request发起网络请求
上传、下载 ​
API说明
qin.uploadFile上传文件
qin.downloadFile下载文件
WebSocket ​
API说明
qin.connectSocket创建 WebSocket 连接
qin.onSocketOpen监听 WebSocket 打开
qin.onSocketError监听 WebSocket 错误
qin.sendSocketMessage发送 WebSocket 消息
qin.onSocketMessage接受 WebSocket 消息
qin.closeSocket关闭 WebSocket 连接
qin.onSocketClose监听 WebSocket 关闭
SocketTask ​
API说明
SocketTask.onMessage监听 WebSocket 接受到服务器的消息事件
SocketTask.send通过 WebSocket 连接发送数据
SocketTask.close关闭 WebSocket 连接
SocketTask.onOpen监听 WebSocket 连接打开事件
SocketTask.onClose监听 WebSocket 连接关闭事件
SocketTask.onError监听 WebSocket 错误事件

媒体 ​

图片 ​
API说明
qin.chooseImage从相册选择图片，或者拍照
qin.previewImage预览图片
qin.closePreviewImage关闭预览图片
qin.getImageInfo获取图片信息
qin.saveImageToPhotosAlbum保存图片到系统相册
文件 ​
API说明
qin.chooseFile从本地选择文件

文件 ​

API说明
qin.saveFile保存文件
qin.getSavedFileList获取已保存的文件列表
qin.getSavedFileInfo获取已保存的文件信息
qin.removeSavedFile删除已保存的文件信息
qin.getFileInfo获取文件信息
qin.openDocument打开文件

数据缓存 ​

API说明
qin.getStorage获取本地数据缓存
qin.getStorageSync获取本地数据缓存
qin.setStorage设置本地数据缓存
qin.setStorageSync设置本地数据缓存
qin.getStorageInfo获取本地缓存的相关信息
qin.getStorageInfoSync获取本地缓存的相关信息
qin.removeStorage删除本地缓存内容
qin.removeStorageSync删除本地缓存内容
qin.clearStorage清理本地数据缓存
qin.clearStorageSync清理本地数据缓存

位置 ​

获取位置 ​
API说明
qin.getLocation获取当前位置
qin.chooseLocation打开地图选择位置
qin.gainLocation用于获取经纬度信息
qin.selectLocation用于获取经纬度信息
查看位置 ​
API说明
qin.openLocation打开内置地图
地图组件控制 ​
API说明
qin.createMapContext地图组件控制

设备 ​

系统信息 ​
API说明
qin.getSystemInfo获取系统信息
qin.getSystemInfoSync获取系统信息
qin.canIUse判断应用的 API，回调，参数，组件等是否在当前版本可用
qin.getSystemSetting获取设备设置
拨打电话 ​
API说明
qin.makePhoneCall拨打电话
扫码 ​
API说明
qin.scanCode扫码
剪切板 ​
API说明
qin.setClipboardData设置剪贴板内容
qin.getClipboardData获取剪贴板内容
屏幕亮度 ​
API说明
qin.setScreenBrightness设置屏幕亮度
qin.getScreenBrightness获取屏幕亮度
qin.setKeepScreenOn设置是否保持常亮状态
振动 ​
API说明
qin.vibrate使手机发生振动
qin.vibrateLong使手机发生较长时间的振动
qin.vibrateShort使手机发生较短时间的振动

界面 ​

交互反馈 ​
API说明
qin.showToast显示提示框
qin.showLoading显示加载提示框
qin.hideToast隐藏提示框
qin.hideLoading隐藏加载提示框
qin.showModal显示模态弹窗
qin.showActionSheet显示菜单列表
设置导航条 ​
API说明
qin.setNavigationBarTitle设置当前页面标题
qin.setNavigationBarColor设置页面导航条颜色
qin.showNavigationBarLoading显示导航条加载动画
qin.hideNavigationBarLoading隐藏导航条加载动画
设置 TabBar ​
API说明
qin.setTabBarItem动态设置 tabBar 某一项的内容
qin.setTabBarStyle动态设置 tabBar 的整体样式
qin.hideTabBar隐藏 tabBar
qin.showTabBar显示 tabBar
qin.setTabBarBadge为 tabBar 某一项的右上角添加文本
qin.removeTabBarBadge移除 tabBar 某一项右上角的文本
qin.showTabBarRedDot显示 tabBar 某一项的右上角的红点
qin.hideTabBarRedDot隐藏 tabBar 某一项的右上角的红点
背景 ​
API说明
qin.setBackgroundColor动态设置窗口的背景色。
qin.setBackgroundTextStyle动态设置下拉背景字体、loading 图的样式。
动画 ​
API说明
qin.createAnimation创建一个动画实例 animation。调用实例的方法来描述动画。最后通过动画实例的 export 方法导出动画数据传递给组件的 animation 属性。
滚动 ​
API说明
qin.pageScrollTo将页面滚动到目标位置。
下拉刷新 ​
API说明
onPullDownRefresh监听该页面用户下拉刷新事件
qin.startPullDownRefresh开始下拉刷新
qin.stopPullDownRefresh停止当前页面下拉刷新
节点信息 ​
API说明
qin.createSelectorQuery创建查询请求
selectorQuery.select根据选择器选择单个节点
selectorQuery.in将选择器的选取范围更改为自定义组件 component 内
selectorQuery.selectAll根据选择器选择全部节点
selectorQuery.selectViewport选择显示区域
selectorQuery.exec执行查询请求
nodesRef.boundingClientRect获取布局位置和尺寸
nodesRef.scrollOffset获取滚动位置
nodesRef.fields获取任意字段
节点布局相交状态 ​
API说明
qin.createIntersectionObserver创建 IntersectionObserver 对象
intersectionObserver.relativeTo指定参照节点
intersectionObserver.relativeToViewport指定页面显示区域作为参照区域
intersectionObserver.observe指定目标节点并开始监听
intersectionObserver.disconnect停止监听

路由 ​

API说明
qin.navigateTo保留当前页面，跳转到应用内的某个页面，使用 qin.navigateBack 可以返回到原页面
qin.redirectTo关闭当前页面，跳转到应用内的某个页面
qin.reLaunch关闭所有页面，打开到应用内的某个页面
qin.switchTab跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面
qin.navigateBack关闭当前页面，返回上一页面或多级页面
qin.getPageOpts获取页面参数
qin.preloadPage预加载页面

键盘 ​

API说明
qin.hideKeyboard隐藏已经显示的软键盘，如果软键盘没有显示则不做任何操作。
qin.onKeyboardHeightChange监听键盘高度变化
qin.offKeyboardHeightChange取消监听键盘高度变化事件
qin.getSelectedTextRange在input、textarea等focus之后，获取输入框的光标位置

其他 ​

设置 ​
API说明
qin.openSetting调起客户端小程序设置界面，返回用户设置的操作结果。
qin.getSetting获取用户的当前设置。
收货地址 ​
API说明
qin.chooseAddress获取用户收货地址
获取发票抬头 ​
API说明
qin.chooseInvoiceTitle选择用户的发票抬头，需要用户授权 scope.invoiceTitle。
小程序跳转 ​
API说明
qin.navigateToMiniProgram打开另一个小程序。
qin.navigateBackMiniProgram跳转回上一个小程序，只有当另一个小程序跳转到当前小程序时才会能调用成功。
模板消息 ​
API说明
addTemplate组合模板并添加至帐号下的个人模板库。
deleteTemplate删除帐号下的某个模板。
getTemplateLibraryById获取模板库某个模板标题下关键词库。
getTemplateLibraryList获取 APP 模板库标题列表
getTemplateList获取帐号下已存在的模板列表。
sendTemplateMessage发送模板消息
alipay.open.app.mini.templatemessage.send支付宝小程序通过 openapi 给用户触达消息，主要为支付后的触达（通过消费 id）和用户提交表单后的触达（通过 formId）。
小程序更新 ​
API说明
qin.getUpdateManager返回全局唯一的版本更新管理器对象： updateManager，用于管理小程序更新。
qin.updatePackageqin.getUpdateManager 的二次封装，如果有就直接更新。
菜单 ​
API说明
qin.getMenuButtonBoundingClientRect获取菜单按钮（右上角胶囊按钮）的布局位置信息。
qin.getCustomButtonBoundingClientRect获取自定义导航栏下不可改变的元素。
分享 ​
API说明
qin.showShareMenu小程序的原生菜单中显示分享按钮
qin.hideShareMenu小程序的原生菜单中隐藏分享按钮
获取用户信息 ​
API说明
qin.getUserProfile获取用户信息
获取第三方平台数据 ​
API说明
qin.getExtConfig获取第三方平台自定义的数据字段。
qin.getExtConfigSyncqin.getExtConfig 的同步版本。

因文档同步原因，本页面列出的API可能不全。如在本文未找到相关API，可以在左侧树中寻找或使用文档右上角的搜索功能。