社交通讯全场景协同最佳实践

概述

在办公、创作和社区交友等应用中，内容发布和浏览分享是用户互动与交流的核心。它允许用户创作并分享包含图片、视频、文字等多媒体信息，从而增强用户间的连接与互动。随着手机、平板、电脑等电子设备的普及，用户对跨设备处理图片/视频/文字及接续编辑内容、在不同设备间无缝切换及快速便捷分享内容的需求日益增长。本文介绍如何通过跨端迁移和多端协同功能，实现不同设备间的快速无缝切换，提升内容发布和浏览分享的便利性。

本文主要包含以下几个方面内容：

• 跨设备互通：基于分布式协同框架，面向跨设备拍照等业务场景，提供createCollaborationServiceMenuItems（相机设备列表组件）和CollaborationServiceStateDialog（远端相机状态弹窗组件）两个组件。应用只需要调用这两个组件，即可实现跨设备调用相机、拍照、扫描及访问图库的功能。
• 跨设备拖拽图片/文字：支持跨设备拖拽场景，系统自动完成键鼠穿越和跨设备的数据传递，应用可根据实际需求，使用拖拽控制和拖拽事件能力，实现在平板或电脑类型的任意两台设备间拖拽图片和文本的功能。
• 跨设备剪贴图片/视频/文字：基于@ohos.pasteboard (剪贴板)能力，支持系统复制、粘贴功能，实现本地剪贴板和跨设备剪贴板的业务场景。本地剪贴板提供设备内的内容复制粘贴，跨设备剪贴板提供跨设备的内容复制粘贴。
• 跨设备应用接续：基于UIAbility应用组件，通过在本端使用onContinue()接口保存迁移数据，在目的端使用onCreate()或onNewWant()接口恢复迁移数据，实现应用接续的场景。即当用户在一个设备上操作某个应用时，可以在另一个设备的同一个应用中快速切换，并无缝衔接上一个设备的应用体验。
• 碰一碰插入图片：基于系统手机与PC/2in1碰一碰分享能力，实现将移动端设备图库中的图片分享后插入到电脑端应用页面中。
• 碰一碰分享页面：基于系统碰一碰分享能力，支持通过碰一碰分享内容页面到其他设备。并结合App Linking技术（详情可参考App Linking Kit简介），可实现内容的快速跨设备分享，直达目标应用，提供高效、便捷、无缝的分享体验。
• 隔空传送分享页面：基于系统隔空传送能力，支持通过隔空传送手势分享内容页面到其他设备。通过隔空传送手势触发分享App Linking链接，安装应用的接收端可直接打开查看内容。

用户体验

体验

使用限制

跨设备互通

场景描述

用户在平板或电脑上使用文本编辑应用（如备忘录、邮件、笔记等）时，若当前设备不便拍摄，可利用跨设备互通功能，直接调用手机或平板的相机完成拍摄，也可从其图库中选择图片或视频。手机和平板设备在拍摄灵活性、取景便利性及相机性能上更具优势。所选素材将快速传输至原设备的应用中，帮助用户高效完成图文编辑任务。

实现原理

场景分析

1. 用户在本端（平板或电脑）应用界面操作，选择使用远端设备的拍照、扫描或图库功能，向远端发起请求。
2. 系统将自动唤醒远端设备上的相机、图库或扫描，进入相应的界面。
3. 使用远端设备完成拍照或选择图片/视频并确认，远端拍摄状态信息实时回传到本端，并将数据插入到本端设备的应用中。

关键技术

跨设备互通的核心在于使用HarmonyOS的分布式协同框架：

1. 设备发现：通过createCollaborationServiceMenuItems组件获取组网内具有对应能力的设备列表。
2. 远端唤醒：系统自动唤醒远端设备上的相机、图库或扫描功能。
3. 状态回传：通过CollaborationServiceStateDialog组件实时回传远端拍摄状态信息。
4. 数据接收：在onState()回调中处理接收到的数据。

在分布式协同框架下，针对跨设备互通图片/视频信息的业务场景，应用只需要调用createCollaborationServiceMenuItems（相机设备列表组件）和CollaborationServiceStateDialog（远端相机状态弹窗组件）两个组件，即可实现跨端拍照、扫描、图库访问功能，开发者无需关注分布式场景下的数据传输和指令控制等细节，具体运作机制可参考：跨设备互通特性简介中的运作机制章节。

实现方案

• 拉取远端菜单，选择远端设备

  通过createCollaborationServiceMenuItems组件，获取组网内具有对应能力的设备列表。当用户选择特定的设备功能后，系统将自动激活远端设备的相机或图库，并使设备屏幕自动点亮。可设置传输照片/视频的最大数量canReceiveNumber，范围为1至50张；若设置数量小于或等于0，则不会触发设备的相应功能；若设置数量超过50，则默认为50。

  收起

  自动换行

  深色代码主题

  复制

  // Remote menu.
  @Builder
  MyTestMenu() {
    Menu() {
      MenuItem({
        symbolStartIcon: new SymbolGlyphModifier($r('sys.symbol.picture_2')),
        content: $r('app.string.local_device')
      })
        .onClick(() => {
          if (this.mediaUriArray.length < CommonConstants.MAX_ADD_MEDIA_NUM) {
            this.selectImage();
          } else {
            try {
              this.getUIContext().getPromptAction().showToast({ message: $r('app.string.add_picture_prompt') });
            } catch (err) {
              hilog.error(DOMAIN, TAG, FORMAT, `ShowToast failed. Cause code: ${err.code}, message: ${err.message}`);
            }
          }
        })
  
      if (canIUse('SystemCapability.Collaboration.Service')) {
        createCollaborationServiceMenuItems([CollaborationServiceFilter.ALL, CollaborationServiceFilter.VIDEO_PICKER],
          CommonConstants.MAX_ADD_MEDIA_NUM)
      }
    }
  }

  AddMedia.ets
• 将远端拍摄状态信息实时回传

  应用将弹出提示框，实时回传远端拍摄状态信息到组件CollaborationServiceStateDialog（远端相机状态弹窗组件），为弹窗组件绑定和实现onState()方法，在业务开始后，此方法将被协同框架调用，用于接收和处理数据。该回调函数接收的数据中，stateCode表示完成状态，bufferType表示回传的数据类型，buffer则是回传数据。当bufferType取值为"general.image"时，buffer返回图片数据；当其取值为"general.video"时,buffer则返回沙箱视频uri路径。

  收起

  自动换行

  深色代码主题

  复制

  build() {
    Column() {
      CollaborationServiceStateDialog({
        onState: (stateCode: number, bufferType: string, buffer: ArrayBuffer): void => this.doInsertMedia(stateCode,
          bufferType, buffer)
      })
      // ...
    }
    // ...
  }

  AddMedia.ets
• 将回传数据写入页面

  用户使用远端设备完成拍照或选择图库照片/视频后，通过自定义方法将返回的图片/视频数据写入本端设备的页面。远端设备将自动退出相机或图库界面，恢复到初始状态。

  收起

  自动换行

  深色代码主题

  复制

  // Remote images or videos fall into.
  doInsertMedia(stateCode: number, bufferType: string, buffer: ArrayBuffer): void {
    if (stateCode != 0) {
      return;
    }
    if (this.mediaUriArray.length >= CommonConstants.MAX_ADD_MEDIA_NUM) {
      return;
    }
  
    if (bufferType === 'general.image') {
      let imageSource = image.createImageSource(buffer);
      imageSource.createPixelMap().then((pixelMap) => {
        let uuid = util.generateRandomUUID();
        this.PixelMapToBuffer(pixelMap, uuid);
        this.mediaUriArray.push({ imagePixelMap: pixelMap, mediaName: uuid, mediaType: MediaType.MEDIA_IMAGE });
        imageSource.release();
      })
    } else if (bufferType === 'general.video') {
      let uuid = util.generateRandomUUID();
      let decoder = util.TextDecoder.create('utf-8');
      let videoUriStr = decoder.decodeToString(new Uint8Array(buffer));
      writeDistributedFile(this.context, uuid, MediaType.MEDIA_VIDEO, undefined, videoUriStr);
      this.mediaUriArray.push({ videoUri: videoUriStr, mediaName: uuid, mediaType: MediaType.MEDIA_VIDEO });
    }
  }

  AddMedia.ets

跨设备拖拽图片/文字

场景描述

当用户拥有多台设备时，开启键鼠共享功能，可以实现键鼠在不同设备间的自由移动。通过跨设备拖拽，用户可以轻松地将本端上的素材拖拽到远端，快速完成内容创作，享受高效的跨设备协同工作体验。

实现原理

场景分析

1. 用户通过长按鼠标触发拖拽事件，可以从本端编辑页面将图片或文字拖拽到远端的编辑页面。
2. 在此过程中，系统自动处理跨设备的数据传输，开发者无需介入。
3. 当用户释放鼠标时，触发拖拽松手事件，远端应用处理接收到的拖拽数据，并将其写入远端编辑页面。

关键技术

在开发跨设备拖拽功能时，系统会自动处理鼠标的跨设备操作及数据传递。应用可以根据实际需求，实现组件的拖入或拖出，完成拖拽事件的开发。具体运作机制可参考：跨设备拖拽中的运作机制章节。

实现方案

• 设置组件允许拖拽

  将需要触发拖拽事件和松手事件的Image组件、TextInput组件及TextArea组件设置draggable()为true，以允许拖拽。

• 设置组件允许落入的类型

  使用allowDrop()方法设置组件允许拖入的数据类型，包括PLAIN_TEXT、IMAGE、OPENHARMONY_PIXEL_MAP等，具体可参考UniformDataType。

• 定义拖拽事件

  将允许拖入的组件绑定onDrop()事件作为释放目标。当在该组件范围内停止拖拽操作时，将触发回调函数，实现图片的拖出和拖入页面的功能。

  收起

  自动换行

  深色代码主题

  复制

  build() {
    Column() {
      // ...
    }
    .draggable(true)
    .allowDrop([uniformTypeDescriptor.UniformDataType.IMAGE,
      uniformTypeDescriptor.UniformDataType.OPENHARMONY_PIXEL_MAP])
    .onDrop((dragEvent?: DragEvent) => {
      // The logic behind the image falling in, achieving image writing.
      // ...
      })
    })
  
  }
  
  
  // ...
  
  /*
   *  Adding an image or video.
   */
  @Builder
  addMedia() {
    Row() {
      List({ space: CommonConstants.LIST_COMM_SPACE }) {
        ForEach(this.mediaUriArray, (item: MediaInfo) => {
          ListItem() {
            if (item.imagePixelMap) {
              Image(item.imagePixelMap)// ...
                .draggable(true)
                .onDragEnd((event) => {
                  // The logic after dragging and dropping is completed.
                  // ...
                })// ...
            } else if (item.videoUri) {
              Video({
                src: item.videoUri,
                posterOptions: {
                  showFirstFrame: true
                }
              })// ...
                .draggable(true)
                .controls(false)
                .autoPlay(true)
                .loop(true)
                .onDragEnd((event) => {
                  // The logic after dragging and dropping is completed.
                  // ...
                })// ...
            }
          }
        }, (item: MediaInfo, index: number) => JSON.stringify(item) + index)
        // ...
      }
      // ...
    }
    // ...
  }

  AddMedia.ets

  当在TextInput和TextArea组件范围内停止拖放行为时，将触发回调，实现文字拖出和写入页面的效果。

  收起

  自动换行

  深色代码主题

  复制

  build() {
    Flex({ direction: FlexDirection.Column }) {
      TextInput({ text: this.mainTitle, placeholder: $r('app.string.text_input_placeholder') })// ...
        .draggable(true)
        .allowDrop([uniformTypeDescriptor.UniformDataType.PLAIN_TEXT])
        .onDrop((dragEvent?: DragEvent) => {
          // The logic after the text falls in, realizing the writing of text.
          // ...
        })
  
      TextArea({ text: this.textContent, placeholder: $r('app.string.richEditor_placeholder') })// ...
        .draggable(true)
        .allowDrop([uniformTypeDescriptor.UniformDataType.PLAIN_TEXT])
        .onDrop((dragEvent?: DragEvent) => {
          // The logic after the text falls in, realizing the writing of text.
          // ...
        })
    }
    .backgroundColor($r('sys.color.background_primary'))
    // ...
  }

  EditorComponent.ets

跨设备剪贴图片/视频/文字

场景描述

当用户拥有多台设备时，可以利用跨设备剪贴板的功能，在本端的应用中复制文本、图片或视频，并在远端的应用中粘贴，实现高效的内容共享。

实现原理

场景分析

1. 用户在本端复制数据，写入到系统剪贴板服务。

2. 系统剪贴板服务处理数据并完成同步，此过程开发者不感知。

3. 用户在远端读取系统剪贴板内容，粘贴来自本端的数据。

关键技术

在开发跨设备剪贴板功能时，系统会自动处理设备间的数据传输，应用程序可根据实际需求接入跨设备剪贴板，实现跨设备间的数据共享。具体运作机制可参考：跨设备剪贴板中的运作机制章节。

实现方案

• 本端复制数据，写入到剪贴板服务

  使用SystemPasteboard（系统剪贴板对象）的setData()方法将本端复制的数据写入剪贴板服务。

  收起

  自动换行

  深色代码主题

  复制

  // Copy picture or video.
  async setPasteDataTest(data: image.PixelMap | string): Promise<void> {
    let pasteData: pasteboard.PasteData;
    if (typeof data === 'string') {
      pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, data);
    } else {
      pasteData = pasteboard.createData(pasteboard.MIMETYPE_PIXELMAP, data);
    }
    let systemPasteBoard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
    await systemPasteBoard.setData(pasteData).catch((err: BusinessError) => {
      hilog.error(DOMAIN, TAG, FORMAT, `Failed to set pastedata. Code: ${err.code}, message: ${err.message}`);
    });
  }

  AddMedia.ets
• 远端粘贴数据，读取剪贴板内容

  在远端设备上粘贴数据时，使用系统剪贴板对象SystemPasteboard的getData()方法读取剪贴板中的内容，并将数据展示在页面上。

  收起

  自动换行

  深色代码主题

  复制

  // Paste picture or video.
  async getPasteDataTest(): Promise<void> {
    let systemPasteBoard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
    systemPasteBoard.getData((err: BusinessError, data: pasteboard.PasteData) => {
      if (err) {
        hilog.error(DOMAIN, TAG, FORMAT, `Failed to get pastedata. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      // Process pasteData, obtain type, number, etc
      // Retrieve the number of records in the clipboard.
      let recordCount: number = data.getRecordCount();
      // Retrieve the type of data from the clipboard.
      let type: string = data.getPrimaryMimeType();
      hilog.info(DOMAIN, TAG, FORMAT, `recordCount: ${recordCount}, type: ${type}`);
      // Retrieve the content of data from the clipboard.
      if (this.mediaUriArray.length < CommonConstants.MAX_ADD_MEDIA_NUM) {
        if (type === pasteboard.MIMETYPE_PIXELMAP) {
          let primaryPixelMap: image.PixelMap = data.getPrimaryPixelMap();
          let uuid = util.generateRandomUUID();
          this.PixelMapToBuffer(primaryPixelMap, uuid);
          this.mediaUriArray.push({
            imagePixelMap: primaryPixelMap,
            mediaName: uuid,
            mediaType: MediaType.MEDIA_IMAGE
          });
        } else if (type === pasteboard.MIMETYPE_TEXT_URI) {
          let uuid = util.generateRandomUUID();
          writeDistributedFile(this.context, uuid, MediaType.MEDIA_VIDEO, undefined, data.getPrimaryUri());
          this.mediaUriArray.push({
            videoUri: data.getPrimaryUri(),
            mediaName: uuid,
            mediaType: MediaType.MEDIA_VIDEO
          });
        }
      } else {
        this.toastShow = true;
      }
    });
  }

  AddMedia.ets