# 桌面文件夹

# 能力介绍

开发者可通过调用相关 API，创建桌面文件夹小组件，并将当前游戏添加至桌面文件夹的快捷启动列表中。

平台差异说明：

Android：支持完整的桌面小组件状态检测功能

iOS：由于系统限制，iOS 无法准确检测是否已添加到桌面，此接口仅能作为参考。返回结构中不支持 isPinned 字段，可以无视

iOS 实现方式：iOS 平台通过跳转到 Safari 浏览器，然后点击分享按钮，再选择"添加到主屏幕"来实现桌面快捷方式的创建。

# 处理逻辑

小游戏客户端通过 tap.hasHomeScreenWidgetAndPinned() 接口检测桌面文件夹小组件是否已创建，并判断当前小游戏是否位于桌面文件夹列表首位。
若桌面文件夹小组件尚未创建，或当前小游戏未置于小组件列表首位，可适时引导用户添加或调整位置。
当用户确认添加操作时，调用 tap.createHomeScreenWidget() 接口，该接口将触发桌面文件夹组件的创建，并将当前小游戏置于桌面文件夹的首位。
根据操作结果，向用户展示相应的反馈信息。

# 最佳实践

# 第一步：在Tap后台创建小游戏

# 第二步：提交审核并通过后，能够在Tap线上游戏中看到这个小游戏

# 第三步：在Tap App体验该小游戏的线上版本（开发者后台扫码自测的情况下暂无法测试此功能）

# iOS 平台特殊说明

iOS 平台需要用户手动操作来添加桌面快捷方式：

点击"添加到桌面"按钮后，会跳转到 Safari 浏览器
在 Safari 中点击底部的分享按钮
选择"添加到主屏幕"选项
确认添加即可完成桌面快捷方式的创建

# 第四步：测试查询&创建桌面快捷方式api

# API说明

# 查询api：

tap.hasHomeScreenWidgetAndPinned({
  success: ({hasWidget, isPinned, isAdded}) => {
     /* 查询成功回调
    * @param hasWidget 用户是否使用Tap App添加了桌面小组件
    * @param isPinned 本小游戏是否在桌面小组件列表中并且是第一个（iOS平台不支持）
    * @param isAdded 本小游戏是否在桌面小组件列表中
    * 
    * 平台差异：
    * - Android：支持完整的桌面小组件状态检测
    * - iOS：isPinned 字段不支持
    */
   },
  fail: ({errMsg, errno}) => {
      /* 查询失败回调
    * @param errMsg 错误信息 
    * @param errno 错误码
    */
  },
  complete: ({errMsg, errno}) => {
      /* 查询完成回调
    * @param errMsg 错误信息 
    * @param errno 错误码
    */
  }
})

# 创建桌面小组件并把本小游戏放在桌面小组件列表的第一个：

tap.createHomeScreenWidget({
  success: ({errMsg, errno}) => {
    /* 创建桌面小组件并把本小游戏放在桌面小组件列表的第一个 执行成功
    * @param errMsg 错误信息 
    * @param errno 错误码
    */
  },
  fail: ({errMsg, errno}) => {
 /* 创建桌面小组件并把本小游戏放在桌面小组件列表的第一个 执行失败
    * @param errMsg 错误信息 
    * @param errno 错误码
    */  
   },
  complete: ({errMsg, errno}) => {
    /* 创建桌面小组件并把本小游戏放在桌面小组件列表的第一个 执行完成
    * @param errMsg 错误信息 
    * @param errno 错误码
    */  
  }
})

# 场景使用示例：

  tap.hasHomeScreenWidgetAndPinned({
  success: ({hasWidget, isPinned}) => {
     // 注意：iOS平台isPinned字段不支持
     if(!hasWidget || !isPinned){
          tap.createHomeScreenWidget({
      success: ({errMsg, errno}) => {
        // todo 创建桌面快捷启动本小游戏成功，给抽奖机会/积分 等奖励
        // 注意：iOS平台会跳转到Safari，需要用户手动完成添加操作
     }
   })
  }
  }
})