先问一个很多人踩过的坑:你调用系统分享,把本地 PDF 或者图片塞进去,分享面板弹出来了,选好微信,点发送直接一闪退回 App,没有任何报错提示? 文本分享好好的,但是分享沙箱里的本地文件就频繁失败;还有的场景,分享之后分不清用户是发送成功、取消还是对方拒绝,没有回调可以判断;甚至有些机型分享面板里渠道时有时无。

很多新手误区:分享就是组装好数据丢给分享接口,系统会自动处理所有文件权限和渠道兼容。 HarmonyOS 7 对分享模块做了权限隔离和 Uri 校验,旧版本很多可以直接传本地绝对路径的写法,现在直接拦截。尤其是应用沙箱内文件,必须生成临时授权 Uri;而且第三方 App(微信等)对文件类型、大小、后缀校验很严,很多失败不是分享 API 的问题,是目标 App 不支持。

为什么要吃透分享? 分享是传播、导出文件的高频能力:导出 PDF、分享截图、分享文本链接。自己写一套分享选择页工作量巨大,系统分享面板是首选。但它有两层坑:一层是鸿蒙侧的 Uri、文件访问权限;另一层是各个目标 App 的兼容限制,两层混在一起,排查起来很折磨。

先分清两个核心概念:

  • 纯文本分享:最简单,没有文件,直接字符串,几乎不会翻车
  • 文件分享:图片、PDF、文档,不能直接传 fs 绝对路径,必须构造UniformData + 临时授权 Uri,给分享框架访问这个文件的权限

吐槽一句:分享失败的日志真的太克制了!很多时候只返回一个通用错误码,不会告诉你到底是 Uri 无效、文件不存在,还是微信不支持这个文件类型。鸿蒙 7 不会帮你自动做文件授权,这一步必须自己写。

下面是适配 HarmonyOS7 的可运行代码,包含文本分享、本地 PDF 分享、分享结果监听、失败兜底。

import { share } from '@kit.ShareKit';
import { fs, fileUri } from '@kit.FileKit';

@Entry
@Component
struct ShareDemoPage {
  @State shareTip: string = "等待分享操作"

  // 1. 纯文本分享
  async shareText() {
    try {
      const uniformData = share.createUniformData()
      uniformData.addText("这是一段分享文本,附带链接:https://xxx.com")
      const res = await share.share(uniformData, {
        preview: true
      })
      this.handleShareResult(res)
    } catch (err) {
      this.shareTip = `分享异常:${JSON.stringify(err)}`
    }
  }

  // 2. 分享本地PDF文件(重点:生成文件Uri,授权给分享服务)
  async sharePdfFile() {
    // 本地文件路径:cache目录下的test.pdf
    const filePath = getContext().cacheDir + "/test.pdf"
    // 判断文件是否存在
    const exists = await fs.access(filePath).then(()=>true).catch(()=>false)
    if (!exists) {
      this.shareTip = "待分享文件不存在"
      return
    }
    try {
      // 关键!把沙箱路径转为标准文件Uri
      const uri = fileUri.getUriFromPath(filePath)
      const uniformData = share.createUniformData()
      // mimeType 一定要匹配文件,pdf是 application/pdf
      uniformData.addFile(uri, "application/pdf")
      const res = await share.share(uniformData, {
        preview: true
      })
      this.handleShareResult(res)
    } catch (err) {
      this.shareTip = `文件分享失败:${JSON.stringify(err)}`
    }
  }

  // 统一处理分享结果
  private handleShareResult(result: share.ShareResult) {
    switch(result.resultCode) {
      case share.ShareResultCode.SUCCESS:
        this.shareTip = "分享成功"
        break
      case share.ShareResultCode.CANCEL:
        this.shareTip = "用户取消分享"
        break
      case share.ShareResultCode.FAIL:
        this.shareTip = "分享失败(目标App不支持/文件异常)"
        break
      default:
        this.shareTip = "未知返回状态"
    }
  }

  build() {
    Column() {
      Text(this.shareTip).fontSize(16).margin({bottom:20})
      Button("分享文本")
        .onClick(()=> this.shareText())
        .margin({bottom:12})
      Button("分享本地PDF")
        .onClick(()=> this.sharePdfFile())
        .margin({bottom:12})
    }.width('100%').padding(24)
  }
}

关键语句拆解

  1. fileUri.getUriFromPath():鸿蒙 7 文件分享的核心!直接把 /data/app/xxx/cache/test.pdf 这种绝对路径传给 addFile 会报错。必须转换成 file:// 标准 Uri,系统分享组件才能拿到访问权限。
  2. mimeType:不能乱写!PDF 是 application/pdf,png 图片是 image/png,mimeType 不匹配,很多分享渠道直接拒绝接收文件。
  3. share.ShareResult 回调:只能拿到【成功 / 取消 / 失败】,无法区分是分享到微信、QQ 还是其他渠道,也拿不到对方是否点开文件,这是系统层面的限制,不要强行做业务判断。
  4. preview 参数:开启预览面板,部分渠道支持预览文件;关闭后直接跳渠道发送页。

HarmonyOS 7 高频踩坑清单

  1. ❌ 直接传入文件绝对路径,不转 Uri 现象:分享面板能打开,选中渠道发送瞬间失败,回调返回 FAIL。 ✅ 方案:所有本地文件,一律用 fileUri.getUriFromPath 生成 Uri 再添加。
  2. ❌ mimeType 填错、或者直接写 */* 很多开发者图省事统一写 */*,在鸿蒙 7 里微信、钉钉等 App 校验更严格,识别不到文件类型直接拒收。 ✅ 规范:pdf → application/pdf;jpg → image/jpeg;png → image/png
  3. ❌ 分享 rawfile 里的文件 rawfile 是只读打包资源,不支持直接分享!rawfile 文件必须先拷贝到 cache 目录,再生成 Uri 分享。rawfile 没有可授权的文件访问句柄。
  4. ❌ 一次性同时分享多个不同类型的文件混搭 比如同时放图片 + PDF,部分第三方分享渠道不支持混合资源,直接失败。 ✅ 策略:一次分享只放同类型文件。
  5. ❌ 混淆【系统分享面板】和【微信自有分享 SDK】 系统分享是统一面板,能不能出微信渠道,取决于设备上是否安装微信、微信是否向系统注册分享入口。不能保证微信一定出现在列表里。如果你必须稳定分享到微信,要接入微信开放 SDK,不要依赖系统分享。
  6. ❌ 大文件分享 微信对单个文件大小有限制,PDF 超过 100MB 大概率发送失败。这个限制是微信的,不是鸿蒙分享接口的问题,系统不会提前拦截。
  7. ❌ 后台分享、页面销毁之后等待分享回调 分享面板是系统弹窗,页面提前销毁,回调可能丢失。分享操作期间尽量不要路由跳转离开页面。

项目复盘总结

我之前做一个文档工具项目,导出 PDF 之后需要分享给好友。一开始直接传 cache 的绝对路径,测试机上部分机型正常,升级鸿蒙 7 之后大量用户反馈分享 PDF 发送闪退。 调试很久才发现:新版本分享框架不再自动适配沙箱路径,必须显式转 Uri。同时很多人把 mimeType 写成 */*,导致微信偶尔拒收 PDF。 改成标准 Uri + 正确 mimeType 之后,绝大多数分享失败的问题收敛。另外我加了判断:如果分享结果是 FAIL,给用户提示 “可尝试保存到本地后手动发送” 兜底。

开发规范:

  • 文本分享:直接 addText;文件分享:必须 fileUri 转 Uri;
  • mimeType 严格和文件类型对应,不要用通配符;
  • rawfile 资源先拷贝到 cache,再分享;
  • 不要依赖系统分享保证某个第三方 App(微信)一定在渠道列表;
  • 区分:系统分享只提供三个结果:成功 / 取消 / 失败,无法感知具体分享渠道。
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐