HarmonyOS 鸿蒙Next 碰一碰发起APPLinking应用实践分享|逸校园开发实践

if (canIUse(‘SystemCapability.Collaboration.HarmonyShare’)) {

  // 支持一碰分享的能力.

}

集成开发环境：DevEco Studio NEXT Beta1及以上版本。

Share Kit支持三种卡片模板：

纯图片布局，沉浸式大卡布局和白卡上下布局，区分方式为是否仅传递预览图（thumbnailUri）字段，以及预览图宽高比。

二、确认碰一碰卡片布局：

纯图片布局：

纯图片布局只包括预览图。

当分享数据为文件、图片等无需添加标题及描述的场景，推荐使用此卡片模板。

• 使用方法：

  构造分享数据时，仅传递预览图（thumbnailUri）字段，即可生成此卡片模板。

布局要求

预览图：支持最小宽高比1:4，超出部分将被裁剪。

沉浸式大卡布局：

当分享数据为链接类型时，需要向用户传递链接的内容，推荐使用此卡片模板。

• 使用方法：需同时满足以下2个条件：
  1. 构造分享数据时，需同时传入标题(title)、描述(description)字段和预览图(thumbnailUri)字段。
  2. 预览图宽高比小于1:1。

• 布局要求
  1. 预览图：支持最小宽高比1:4，超出部分将被裁剪。
  2. 标题：最大可显示2行，当文本超过2行时，未能正常在屏幕显示的文本用省略号代替。如果标题末尾有重要信息显示，需应用自行控制字数约20个中文左右。
  3. 描述：仅可显示1行，文本超过1行时，未能正常在屏幕上显示的文本用省略号代替。
  4. 应用图标：无需配置，系统将默认获取应用图标用于显示在卡片底部。

白卡上下布局：

白卡上下布局包括预览图、标题、描述、应用图标。当分享数据为链接类型时，需要向用户传递链接的内容，推荐使用此卡片模板。

• 使用方法：需同时满足以下2个条件：
  1. 构造分享数据时，需同时传入标题(title)、描述(description)字段和预览图(thumbnailUri)字段。
  2. 预览图宽高比大于1:1。
• 布局要求
  1. 预览图：仅显示在卡片上方，不会铺满整个卡片。
  2. 标题：最大可显示2行，当文本超过2行时，未能正常在屏幕显示的文本用省略号代替。如果标题末尾有重要信息显示，需应用自行控制字数约20个中文左右。
  3. 描述：仅可显示1行，文本超过1行时，未能正常在屏幕上显示的文本用省略号代替。
  4. 应用图标：无需配置，系统将默认获取应用图标用于显示在卡片底部。

三、开发碰一碰分享App Linking直达应用

前提条件：APP已接入APP Linking

开发步骤：

1. 导入相关模块。

import { uniformTypeDescriptor as utd } from ‘@kit.ArkData’;

import { systemShare, harmonyShare } from ‘@kit.ShareKit’;

import { fileUri } from ‘@kit.CoreFileKit’;

2. 定义碰一碰分享事件监听/取消监听方法（收到碰一碰分享事件回调后，需尽快调用sharableTarget.share()方法发起分享，超过3秒可能会失败）。

private immersiveCallback(sharableTarget: harmonyShare.SharableTarget) {

  const contextFaker: Context = getContext(this);

  let filePath = contextFaker.filesDir + ‘/exampleKnock1.jpg’;

  let shareData: systemShare.SharedData = new systemShare.SharedData({

    utd: utd.UniformDataType.HYPERLINK,

    content: ‘https://sharekitdemo.drcn.agconnect.link/ZB3p’,

    // 根据title,description,thumbnailUri会生成不同的卡片模板，具体可参考配套卡片模板章节。

    thumbnailUri: fileUri.getUriFromPath(filePath),

    title: ‘碰一碰分享卡片标题’,

    description: ‘碰一碰分享卡片描述’

  });

  sharableTarget.share(shareData);

}

private immersiveListening() {

  harmonyShare.on(‘knockShare’, this.immersiveCallback);

}

private immersiveDisablingListening() {

  harmonyShare.off(‘knockShare’, this.immersiveCallback);

}

3. 进入可分享页面时，注册碰一碰分享监听事件；离开可分享页面（包括应用退至后台等场景）时，取消碰一碰分享监听事件。

// Entry Component 代码片段

onPageHide(): void {

  let context = getContext(this);

  context.eventHub.emit(‘onBackGround’);

}

aboutToAppear(): void {

  this.immersiveListening();

  let context = getContext(this);

  context.eventHub.on(‘onBackGround’, this.onBackGround);

}

aboutToDisappear(): void {

  this.immersiveDisablingListening();

  let context = getContext(this);

  context.eventHub.on(‘onBackGround’, this.onBackGround);

}

private onBackGround() {

  this.immersiveDisablingListening();

}

四、开发TIPS：

可以根据业务需要选择合适的页面开启碰一碰分享，相关代码如下：

1. 当进入可分享页面时，使用harmonyShare.on()方法注册碰一碰监听事件，
2. 当离开可分享页面（包括应用退至后台等场景）时，使用harmonyShare.off()方法取消碰一碰监听事件。

aboutToAppear(): void {
  if (canIUse(‘SystemCapability.Collaboration.HarmonyShare’)) {
    this.immersiveListening();
  }
  let context = getContext(this);
  context.eventHub.on(‘onBackGround’, this.onBackGround);
}

onPageHide(): void {
  let context = getContext(this);
  context.eventHub.emit(‘onBackGround’);
}

aboutToDisappear(): void {
  if (canIUse(‘SystemCapability.Collaboration.HarmonyShare’)) {
    this.immersiveDisablingListening();
  }
    let context = getContext(this);
    context.eventHub.on(‘onBackGround’, this.onBackGround);
}

private onBackGround() {
  if (canIUse(‘SystemCapability.Collaboration.HarmonyShare’)) {
    this.immersiveDisablingListening();
  }
}

碰一碰卡片预览图除了文档的读取方法还可以从资源文件读取：

private async immersiveCallback(sharableTarget: harmonyShare.SharableTarget) {
  const contextFaker: Context = getContext(this);
  let resourceMgr = contextFaker.resourceManager;
  let imageData = await resourceMgr.getMediaContent($r(“app.media.temp”))  //从资源文件读取分享缩略图
  let shareData: systemShare.SharedData = new systemShare.SharedData({    utd: utd.UniformDataType.HYPERLINK,    content: ‘https://www.app.temp’,    // 根据title,description,thumbnailUri会生成不同的卡片模板，具体可参考配套卡片模板章节。    thumbnail: imageData,    title: ‘快来体验逸校园’,    description: ‘一站式掌握校园生活！’  });  sharableTarget.share(shareData);}private immersiveListening() {  harmonyShare.on(‘knockShare’, this.immersiveCallback);}private immersiveDisablingListening() {  harmonyShare.off(‘knockShare’, this.immersiveCallback);}

五、效果：