扩展 SDK

扩展SDK 是对核心SDK的补充，所以要使用扩展SDK，也必须依赖核心SDK。

为了保证 SDK 的安全稳定性，将需要权限的API尽可能放到扩展SDK，FinClip 将 SDK 拆分为核心 SDK 与扩展 SDK，后者是前者的补充，因此使用扩展 SDK 也必须依赖核心 SDK。

一些涉及到权限的api，我们将其拆分到各个扩展SDK，您可以根据实际情况集成相应的扩展SDK。

请注意

注意：使用扩展SDK需要保证与核心SDK版本号保持一致，避免出现未知问题

请注意

注意：从 1.3.3 开始，为了使 SDK 合规，各个扩展 SDK 都声明了对应的权限。如果证书没有相关权限，集成时会报错。

1 蓝牙扩展SDK

@finclip/bluetooth-sdk是蓝牙扩展SDK。

涉及到的权限：ohos.permission.ACCESS_BLUETOOTH

1.1 集成蓝牙扩展SDK

在 dependencies 添加 @finclip/bluetooth-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/bluetooth-sdk": "latest"
  }

1.2 注册蓝牙扩展SDK

import { FinAppletBluetooth } from '@finclip/bluetooth-sdk';
// BluetoothSDK初始化
FinAppletBluetooth.init()

1.3 蓝牙SDK相关api概览

api名称	api描述信息
蓝牙-通用	一系列的api
蓝牙-低功耗中心设备	一系列的api
蓝牙-信标	鸿蒙系统不支持

2 通讯录扩展SDK

@finclip/contact-sdk是通讯录扩展SDK。

涉及到的权限：ohos.permission.WRITE_CONTACTS、ohos.permission.READ_CONTACTS

2.1 集成通讯录扩展SDK

在 dependencies 添加 @finclip/contact-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/contact-sdk": "latest"
  }

2.2 注册通讯录扩展SDK

import { FinAppletContact } from '@finclip/contact-sdk';
// ContactSDK初始化
FinAppletContact.init()

2.3 通讯录SDK相关api概览

api名称	api描述信息
addPhoneContact	添加手机通讯录联系人。
chooseContact	拉起手机通讯录，选择联系人。

3 剪贴板扩展SDK

@finclip/clipboard-sdk是剪贴板扩展SDK。

涉及到的权限：ohos.permission.READ_PASTEBOARD

3.1 集成剪贴板扩展SDK

在 dependencies 添加 @finclip/clipboard-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/clipboard-sdk": "latest"
  }

3.2 注册剪贴板扩展SDK

import { FinAppletClipboard } from '@finclip/clipboard-sdk';
// ClipboardSDK初始化
FinAppletClipboard.init()

注意

由于 剪贴板 权限比较敏感，且api比较冷门。您也可以通过注册自定义api的方式添加剪贴板相关的两个api。

注入的源码如下：

import { AbstractAPIManager, FinAppClient, IApiManager, PermissionHelper } from '@finclip/sdk-core';
import { pasteboard } from '@kit.BasicServicesKit';

namespace IClipboardAPI {
  export interface IClipboardData {
    data: string
  }
}

function getClipboardData(args: IApiManager.IInvokeArgs, apiManager: AbstractAPIManager) {
  const callback = args.callback
  const context = apiManager.UIContext
  PermissionHelper.requestPermissions(context, ['ohos.permission.READ_PASTEBOARD'], () => {
    const systemPasteboard = pasteboard.getSystemPasteboard();
    systemPasteboard.getData().then((pasteData) => {
      const text = pasteData.getPrimaryText();
      const res: IApiManager.IInvokeBaseResponse = {
        errMsg: 'getClipboardData:ok',
        data: text
      }
      callback.onSuccess(res)
    }).catch((err: Error) => {
      callback.onFail({ errMsg: err.message })
    });
  }, (index: number) => {
    // 用户拒绝授权
    callback.onFail({ errMsg: PermissionHelper.authDenyMsg })
  })
}


function setClipboardData(args: IApiManager.IInvokeArgs, apiManager: AbstractAPIManager) {
  const callback = args.callback
  const params = args.params as IClipboardAPI.IClipboardData
  const text: string = params.data
  const pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, text);
  const systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
  const res: IApiManager.IInvokeBaseResponse = {
    errMsg: 'setClipboardData:ok'
  }
  systemPasteboard.setData(pasteData).then(() => {
    callback.onSuccess(res)
  }).catch((err: Error) => {
    callback.onFail({ errMsg: err.message })
  });
}

FinAppClient.getInstance()?.registerCustomApi('getClipboardData', getClipboardData)
FinAppClient.getInstance()?.registerCustomApi('setClipboardData', setClipboardData)

3.3 剪贴板SDK相关api概览

api名称	api描述信息
setClipboardData	设置剪贴板内容
getClipboardData	获取剪贴板内容

4 日历扩展SDK

@finclip/calendar-sdk是日历扩展SDK。

涉及到的权限：ohos.permission.READ_CALENDAR、ohos.permission.WRITE_CALENDAR

4.1 集成日历扩展SDK

在 dependencies 添加 @finclip/calendar-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/calendar-sdk": "latest"
  }

4.2 注册日历扩展SDK

import { FinAppletCalendar } from '@finclip/calendar-sdk';
// CalendarSDK初始化
FinAppletCalendar.init()

4.3 日历SDK相关api概览

api名称	api描述信息
addPhoneCalendar	添加日历普通事件
addPhoneRepeatCalendar	添加日历重复事件

5 百度地图扩展SDK

@finclip/baidu-map-sdk是百度地图扩展SDK。

百度地图使用准备请参考文档：百度地图 (opens new window)

涉及到的权限：ohos.permission.LOCATION、ohos.permission.LOCATION_IN_BACKGROUND、ohos.permission.APPROXIMATELY_LOCATION、

5.1 集成百度地图扩展SDK

在 dependencies 添加 @finclip/baidu-map-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/baidu-map-sdk": "latest"
  }

5.2 注册百度地图扩展SDK

5.2.1 快速使用

import { FinAppletBaiduMap } from '@finclip/baidu-map-sdk';

// 会初始化百度地图 SDK 和注册地图组件
FinAppletBaiduMap.init('api_key')  // 传入在开放平台申请的 API key

5.2.2 只注册组件

import { FinAppletBaiduMap } from '@finclip/baidu-map-sdk';

// 如果项目中已初始化过百度地图，可以只注册地图组件
FinAppletBaiduMap.registerComponent()

5.3 修改坐标系

地图 SDK 提供的 CoordType 是从 @bdmap/base 内导出的，具体定义可以参考百度地图文档 (opens new window)

import { FinAppletBaiduMap, CoordType } from '@finclip/baidu-map-sdk';

// 可以使用API修改百度地图坐标系
FinAppletBaiduMap.setBDMapCoordinateType(CoordType.GCJ02)

5.4 百度地图SDK相关api概览

api名称	api描述信息
Map组件	视图组件
MapContext	一系列的api
openLocation	查看位置
chooseLocation	选择位置
choosePoi	打开POI列表选择位置

6 相册扩展SDK

@finclip/album-sdk是相册扩展SDK。

涉及到的权限：ohos.permission.WRITE_IMAGEVIDEO

6.1 集成相册扩展SDK

在 dependencies 添加 @finclip/album-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/album-sdk": "latest"
  }

6.2 注册相册扩展SDK

import { FinAppletAlbum } from '@finclip/album-sdk';
// AlbumSDK初始化
FinAppletAlbum.init()

6.3 相册SDK相关api概览

注意

相册扩展SDK使用 ACL 权限实现了 ACLPermissionHandler.saveMediaToPhotosAlbum，如果已自行实现了该代理方法请不要使用该 SDK，会覆盖实现

注入的源码如下：

import { common, Permissions } from '@kit.AbilityKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { CommonUtils, FinAppProxyHandlerManager, IFinProxyHandlerItem, PermissionHelper } from '@finclip/sdk-core';
import { fileIo as fs } from '@kit.CoreFileKit';

export class ACLPermissionHandler extends IFinProxyHandlerItem.ACLPermissionHandler {
  /**
   * 保存图片或视频到相册的方法，默认需要 'ohos.permission.WRITE_IMAGEVIDEO' 权限
   * @param type 需要保存的媒体类型
   * @param realPath 文件的完整路径
   * @param context
   * @returns 成功时不需要返回值，如果失败请将对应的错误信息 reject 返回，比如 reject('auth deny')
   */
  public saveMediaToPhotosAlbum(type: 'image' | 'video', realPath: string,
    context: common.UIAbilityContext): Promise<void> {
    return new Promise((resolve, reject) => {
      const defaultExt = type === 'image' ? 'jpg' : 'mp4'
      const accessType = type === 'image' ? photoAccessHelper.PhotoType.IMAGE : photoAccessHelper.PhotoType.VIDEO
      const permissions: Array<Permissions> = ['ohos.permission.WRITE_IMAGEVIDEO']
      PermissionHelper.requestPermissions(context, permissions, async () => {
        try {
          const helper = photoAccessHelper.getPhotoAccessHelper(context);
          const ext = CommonUtils.getFileExtension(realPath) || defaultExt
          const uri = await helper.createAsset(accessType, ext);
          const file = await fs.open(uri, fs.OpenMode.READ_WRITE | fs.OpenMode.APPEND)
          const readStream = await fs.createStream(realPath, 'r+')
          const arrayBuffer = new ArrayBuffer(4096)
          let len = await readStream.read(arrayBuffer);
          while (len) {
            await fs.write(file.fd, arrayBuffer)
            len = await readStream.read(arrayBuffer);
          }
          await readStream.close()
          await fs.close(file)
          resolve()
        } catch (err) {
          reject(err.message)
        }
      }, (index: number) => {
        reject(PermissionHelper.authDenyMsg)
      })
    })
  }
}

FinAppProxyHandlerManager.ACLPermissionHandler = new ACLPermissionHandler()

7 直播SDK（live SDK）

@finclip/live-sdk是直播扩展SDK。

涉及到的权限：ohos.permission.MICROPHONE、ohos.permission.MICROPHONE、ohos.permission.CAMERA、ohos.permission.INTERNET

7.1 集成 live 扩展SDK

在 dependencies 添加 @finclip/live-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/live-sdk": "latest"
  }

7.2 注册 live 扩展SDK

import { FinAppletLive } from '@finclip/live-sdk';

FinAppletLive.init()

7.3 LiveSDK（live-player）相关api概览

api名称	api描述信息
play	播放
stop	停止
pause	暂停
resume	恢复
mute	静音

7.4 LiveSDK（live-pusher）相关api概览

api名称	api描述信息
start	开始推流
stop	停止推流，同时停止摄像头预览
pause	暂停推流
resume	恢复推流
startPreview	开启摄像头预览
stopPreview	关闭摄像头预览
switchCamera	切换前后摄像头

7.4.1 LiveSDK涉及到的敏感权限

权限	相关接口、组件
摄像头	初始化的时候就会请求权限
录制音频	初始化的时候就会请求权限

8 分享 SDK

@finclip/share-sdk是分享扩展SDK，使用分享扩展SDK时，需要将 uiConfig 里的 hideShareAppletMenu 设置为 false，在更多菜单里才会显示分享按钮

8.1 集成分享扩展SDK

在 dependencies 添加 @finclip/share-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/share-sdk": "latest"
  }

8.2 注册分享扩展SDK

import { FinAppletShare } from '@finclip/share-sdk';

/**
 * 初始化分享 SDK
 * @param wxAppId 在微信开放平台申请AppID或者传入 WXApi 实例
 * @param scheme 分享链接的 scheme，用于访问链接时拉起应用，需要应用配置
 */
FinAppletShare.init('wxAppId','scheme')

8.3 配置自定义链接

8.3.1 自定义分享落地页的链接

 /**
 * 设置 自定义分享链接
 * @param {function} cb - 自定义分享链接回调函数
 * @param {Object} cb.appInfo - 小程序信息
 * @returns {string} cb.return - 自定义分享链接
 * */
FinAppletShare.onCustomShareUrl = async (appInfo) => {
 return `https://example.com/share`
};

8.3.2 自定义分享链接中的下载地址

 /**
 * 设置 自定义 APP 下载链接
 * @param {function} cb - 自定义APP下载链接回调函数
 * @param {Object} cb.appInfo - 小程序信息
 * @returns {string} cb.return - 自定义的APP下载链接
 * */
FinAppletShare.onCustomAppDownloadLink = async (appInfo) => {
 return `https://example.com/download`
};

8.4 工程配置

8.4.1 配置 scheme

可以参考官方文档 (opens new window)配置对应 scheme，然后传给分享 SDK

8.4.2 解析链接拉起小程序

由于鸿蒙系统机制，SDK 无法处理拉起请求，可以参考下面的代码，解析链接并调用打开小程序API实现拉起小程序。

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, TAG, '%{public}s', `Ability onCreate`);
  }

  onDestroy(): void {
    hilog.info(0x0000, TAG, '%{public}s', 'Ability onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Main window is created, set main page for this ability
    hilog.info(0x0000, TAG, '%{public}s', 'Ability onWindowStageCreate');

    windowStage.loadContent('pages/Index', storage,(err, data) => {
      if (err.code) {
        hilog.error(0x0000, TAG, 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
        return;
      }
      hilog.info(0x0000, TAG, 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
    });
  }

  onWindowStageDestroy(): void {
    // Main window is destroyed, release UI related resources
    hilog.info(0x0000, TAG, '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground(): void {
    // Ability has brought to foreground
    hilog.info(0x0000, TAG, '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    // Ability has back to background
    hilog.info(0x0000, TAG, '%{public}s', 'Ability onBackground');
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Receive the parameters passed by UIAbility from the caller
    this.processStartUri(want)
    hilog.info(0x0000, TAG, '%{public}s', 'Ability onNewWant');
  }

  processStartUri(want:Want) {
    const startUri = want.uri
    if (startUri) {
      // 解析路径中的appid
      const url = new uri.URI(startUri)
      const pathSegments = url.path.split('/')
      const appId = pathSegments[pathSegments.length - 1]

      // 解析查询参数
      const query = url.getQueryValue('query') || ''
      const path = url.getQueryValue('path') || ''
      const scene = url.getQueryValue('scene') || '0'
      const shareDepth = url.getQueryValue('shareDepth') || '0'

      // 配置对应的 apiServer
      const apiServer = 'your apiServer'
      if (apiServer) {
        FinAppClient.getInstance()?.startApplet({
          appId,
          apiServer,
          startParams: {
            path,
            query,
            shareDepth: Number(shareDepth),
            scene: Number(scene)
          }
        })
      }
    }
  }
}

9 高德地图扩展SDK

@finclip/gd-map-sdk是高德地图扩展SDK。如果使用高德地图扩展SDK，那么定位相关的 API 都会使用高德定位

高德地图使用准备请参考文档：高德地图 (opens new window)

涉及到的权限：ohos.permission.LOCATION、ohos.permission.LOCATION_IN_BACKGROUND、ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.KEEP_BACKGROUND_RUNNING

9.1 集成高德地图扩展SDK

在 dependencies 添加 @finclip/gd-map-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/gd-map-sdk": "latest"
  }

9.2 注册高德地图扩展SDK

9.2.1 更新隐私协议状态

如果已经更新过高德的隐私协议可以跳过这一步

import { FinAppletGDMap, AMapPrivacyAgreeStatus,  AMapPrivacyInfoStatus,  AMapPrivacyShowStatus } from '@finclip/gd-map-sdk';
FinAppletGDMap.updateLocationPrivacyShow(
  AMapPrivacyShowStatus.DidShow,
  AMapPrivacyInfoStatus.DidContain,
  this.context)
FinAppletGDMap.updateLocationPrivacyAgree(
  AMapPrivacyAgreeStatus.DidAgree,
  this.context
);
// 搜索SDK隐私政策
FinAppletGDMap.updateSearchPrivacyShow(
  AMapPrivacyShowStatus.DidShow,
  AMapPrivacyInfoStatus.DidContain,
  this.context
);
FinAppletGDMap.updateSearchPrivacyAgree(
  AMapPrivacyAgreeStatus.DidAgree,
  this.context
);

9.2.2 快速使用

import { FinAppletGDMap} from '@finclip/gd-map-sdk';

// 会初始化高德地图 SDK 和注册地图组件
FinAppletGDMap.init('api_key')

9.2.3 只注册组件

import { FinAppletGDMap } from '@finclip/gd-map-sdk';

// 如果项目中已初始化过高德地图，可以只注册地图组件
FinAppletGDMap.registerComponent()

9.3 高德地图SDK相关api概览

api名称	api描述信息
Map组件	视图组件
MapContext	一系列的api
getLocation	获取当前的地理位置
startLocationUpdate	开启小程序进入前台时接收位置消息
startLocationUpdateBackground	开启小程序在前后台时均可接收位置消息
openLocation	查看位置
chooseLocation	选择位置
choosePoi	打开POI列表选择位置

10 XLog 扩展SDK

@finclip/xlog-sdk是XLog扩展SDK。

注意

从 1.4.3 版本开始，核心 SDK 中将不再包含将日志持久化存储在本地的功能。

若有持久化日志的需求，可以选择集成XLogSDK，并开启日志代理 LogHandler对应的配置项。

10.1 集成 XLog 扩展SDK

在 dependencies 添加 @finclip/xlog-sdk

  "dependencies": {
    "@finclip/sdk": "latest",
    "@finclip/xlog-sdk": "latest"
  }

10.2 注册 XLog 扩展SDK

import { FinAppletXLog } from '@finclip/xlog-sdk';
// XLog SDK初始化
FinAppletXLog.init()