更新记录

1.1.19（2026-10-27）

• 新增 uni-app x Canvas 临时图片分享示例，与 uni-app 示例统一放在“更多测试”中，保留原有分享调用。
• 修复示例页面和辅助模块使用相对引入路径的问题，统一通过 @/uni_modules/ 引用插件内文件，复制页面到其他目录时无需另行复制辅助代码。
• 修复示例诊断日志将普通标签当作 JSON 解析的问题，保留日志脱敏、完整报告和分段复制。
• 优化两类示例的导航、模块顺序、按钮分组和窄屏显示；统一就地结果提示、忙碌状态、平台能力及清空反馈。
• uni-app x 新增画布示例需要自定义基座包含 Canvas 内置模块；未包含时需重新制作基座或进行原生联编。

1.1.18（2026-10-17）

• 修复 iOS 分享前预检将可访问的项目静态图片或本地文件误报为不存在的问题。
• 无需修改现有配置或调用代码；升级后需要重新制作并安装 iOS 自定义基座或 IPA，Android 无需因本次改动重新制作基座。

1.1.17（2026-10-09）

• shareToInstagram 增加 Android 单张真实 PNG/JPEG 分享，复用原生文件准备、远程下载和 URI 临时读取授权，固定调起 Instagram；无需额外 SDK。
• 新增结果 launched；Android 成功仅确认入口启动，handedOff=false，不能确认图片接收、取消或发帖。iOS 仍在系统文件交付结束后返回 handedOff=true。
• 两端专用入口任何非空 text（含纯空白）明确返回 9011002；原通用系统分享、任意 Android targetPackage、旧按钮与调用保持不变。
• 两套示例的 Instagram 按钮支持 Android/iOS，并按平台结果区分启动与交付提示。使用新版需对应平台原生联编或重新制作并安装自定义基座/安装包。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-share-plus

介绍

lizhao-share-plus 是面向 uni-app 与 uni-app x 的系统分享 UTS API 插件。它用一套调用方式分享文字、网页链接、图片、视频、PDF、Office 文档和其他文件，并支持多文件分享、远程文件下载后分享、指定 Android 应用以及分享前预检。

功能特色

适合哪些场景

插件负责把内容交给系统或目标应用。Android 与 HarmonyOS 的成功回调表示分享面板已经成功调起，不表示用户已经完成发送；iOS 可以从系统完成回调中得到用户是否完成分享。

下载与导入

保留完整插件目录，从插件根入口导入；按使用宿主注册下方示例页面。文中含类型声明的脚本片段适用于 uni-app x / UTS；<script setup> 完整页需 Vue 3。普通 uni-app 使用无类型的 JavaScript 写法，Options API 示例兼容 Vue 2 / Vue 3。

1. 从 DCloud 插件市场把插件导入项目。
2. 页面只能从插件根目录导入，不要在路径后追加 utssdk 或平台目录。
3. App 端请使用已经包含本插件原生代码的安装包运行。

uni-app 导入

// 普通 uni-app 页面从插件根目录导入。
import * as LizhaoSharePlus from '@/uni_modules/lizhao-share-plus'

uni-app x 导入

// <script setup lang="uts"> 中同样从插件根目录导入。
import * as LizhaoSharePlus from '@/uni_modules/lizhao-share-plus'

下面的示例以普通 uni-app 写法为主；uni-app x 使用相同的 API 名称和参数结构。第一次接入先用最少参数分享一段文字：

LizhaoSharePlus.shareText({
  text: '这是一段分享内容',
  success(res) {
    console.log('分享面板已调起', res)
  },
  fail(err) {
    console.log('分享失败', err)
  },
  complete(res) {
    console.log('本次调用已结束', res)
  }
})

确认 App 能够调起系统分享面板后，再继续接入链接和文件分享。

完整示例

• uni-app 示例：uni_modules/lizhao-share-plus/example/uniapp/share.vue
• uni-app x 示例：uni_modules/lizhao-share-plus/example/uniappx/index.uvue

完整示例保留原七个测试模块，并增加独立“Instagram 图片分享”区域。可直接编辑路径、可选 MIME、下载地址和包名；页面提供操作状态与最近结果，包含 success / fail / complete 回调。Instagram 区域可先用默认 /static/logo.png 点击“分享到 Instagram”，或点击“相册选图”后再分享，也可填写远程图片地址。业务页面仍应只从插件根目录导入 API。

从基础到进阶：按业务模块使用

这些模块按由浅入深的顺序排列。只需要基础分享时，完成前两个模块即可；需要分享附件、指定应用或远程文件时，再继续阅读后面的模块。

模块一：分享文字

适合公告、邀请码、订单号、客服文案等纯文字内容，也是第一次接入时最简单的验证方式。

直接使用快速开始中的 shareText() 即可。纯文字分享不需要填写 file 或 mimeType；title、subject 和 Android 的 targetPackage 都是可选增强参数。

LizhaoSharePlus.shareText({
  text: '订单已完成',
  fail(err) { console.error(err.errCode, err.errMsg) }
})

模块二：分享网页链接

适合活动页、商品页、文章页和邀请链接。text 用来补充说明，url 必须是有效的 http 或 https 地址。

LizhaoSharePlus.shareUrl({
  title: '活动详情',
  text: '把这个活动分享给朋友',
  url: 'https://uniapp.dcloud.net.cn/',
  success(res) {
    console.log('链接分享面板已调起', res)
  },
  fail(err) {
    console.log('链接分享失败', err)
  }
})

目标应用如何组合标题、说明和链接由其自身决定，部分应用可能只显示其中一部分。

模块三：分享本地文件

适合分享图片、视频、PDF、Word 文档、TXT 或其他附件。file 必须是 App 在运行时真实可访问的文件路径。通常只传路径即可，插件自动识别类型；只有需要覆盖识别结果时才填写 mimeType。支持任意可访问的普通文件，不代表接收应用一定支持该格式；目录不作为文件分享。

LizhaoSharePlus.shareFile({
  file: '/storage/emulated/0/Download/report.pdf',
  success(res) {
    console.log('PDF 分享面板已调起', res)
  },
  fail(err) {
    console.log('PDF 分享失败', err)
  }
})

常见文件 MIME 类型：

未传 mimeType 时插件会自动识别：先使用可用的系统文件元数据或下载响应类型，再按文件扩展名判断；Android/iOS 正式处理文件时还会读取最多 4096 字节，补充识别 PNG、JPEG、GIF、PDF、ZIP 等常见文件头。HarmonyOS 使用扩展名与系统类型库。无法识别时，单文件信息记录为 application/octet-stream，整体分享使用 */* 兜底，不会仅因扩展名未知而拒绝文件。

主动传入 mimeType（包括 */*）始终优先，不会被自动识别覆盖。上表适合需要手动指定类型时查询。

模块四：一次分享多个文件

files 用于一次分享多个文件，不必手动填写共同 MIME。插件逐项识别：类型相同使用精确 MIME，同属图片等大类使用 image/* 等通配类型，混合大类或存在未知类型时使用 */*。任意文件不可读取时整体失败，不会悄悄丢弃文件。

LizhaoSharePlus.shareFile({
  text: '请查收这两份报告',
  files: [
    '/storage/emulated/0/Download/report-a.pdf',
    '/storage/emulated/0/Download/report-b.pdf'
  ],
  success(res) {
    console.log('多文件分享面板已调起', res.filesResolved)
  },
  fail(err) {
    console.log('多文件分享失败', err)
  }
})

HarmonyOS 支持一次分享最多 500 个本地文件，并为每个文件创建独立的系统分享记录。最终能否完整接收多个文件还取决于接收应用，少数应用可能只处理第一项。

文件类型不同也可省略 mimeType，插件自动合并。最终能否接收混合类型由目标应用决定；对交付结果要求较高时，建议按文件类型分开分享。

模块五：下载远程文件后分享

Android/iOS 会先把远程文件下载到本地缓存后再分享。适合文件存放在服务器或 CDN 上、页面暂时没有本地路径的场景。

LizhaoSharePlus.shareFile({
  file: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
  fileNameStrategy: 'keep',
  success(res) {
    console.log('远程文件已下载并调起分享', res.filesResolved)
  },
  fail(err) {
    console.log('下载或分享失败', err)
  }
})

autoDownloadRemote 默认是 true。fileNameStrategy 支持：

需要指定下载目录时可以传 downloadDir，插件会在其下创建本次调用的独立子目录。同名文件不会覆盖其他调用的文件；下载完整后才交给分享面板，失败时清理本次未交付缓存。响应 Content-Type 和 Content-Disposition 可帮助识别类型与文件名。远程文件无法下载时返回 9011004。

autoDownloadRemote: false 保留直接交给系统处理远程 URI 的行为，不保证接收应用会下载或将其当作附件。大文件下载仍受网络、剩余存储空间与接收应用限制。

HarmonyOS 当前要求调用前自行下载为本地文件，再把本地路径传给 shareFile()；直接传远程 URL 会返回 9011001。

模块六：指定 Android 应用

Android 希望直接调起微信等应用时，填写目标应用包名；不传 targetPackage 时显示系统分享面板。

LizhaoSharePlus.shareFile({
  file: '/storage/emulated/0/Download/report.docx',
  targetPackage: 'com.tencent.mm',
  success(res) {
    console.log('目标应用已调起', res)
  },
  fail(err) {
    console.log('指定应用分享失败', err)
  }
})

targetPackage 只用于 Android，文字、链接和文件分享都可以使用。目标应用未安装，或没有可接收当前 MIME 的分享入口时，会进入失败回调。iOS 与 HarmonyOS 不支持按 Android 包名定向分享。

模块七：组合分享

需要在同一次调用中组合文字、链接和文件时，使用通用 share()。preset: 'auto' 会按实际内容判断场景；目标应用最终可能只展示其中一部分字段。

LizhaoSharePlus.share({
  preset: 'auto',
  title: '活动资料',
  text: '活动详情和附件',
  url: 'https://uniapp.dcloud.net.cn/',
  file: '/storage/emulated/0/Download/activity.pdf',
  success(res) {
    console.log('组合内容已交给系统分享', res)
  },
  fail(err) {
    console.log('组合分享失败', err)
  }
})

场景预设用于提示插件按哪类内容归一化参数：

文件 MIME 自动识别是独立流程，不要求额外设置 preset。

模块八：分享前预检

prepareShare(options) 不会下载文件，也不会打开系统分享面板。它用于在正式分享前检查平台支持、参数、本地文件元数据和需要注意的事项；不发网络请求、不创建下载缓存、不读取文件头。

const prepared = LizhaoSharePlus.prepareShare({
  preset: 'remoteFile',
  file: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
  fileNameStrategy: 'timestamp'
})

console.log('是否可以继续分享', prepared.canShare)
console.log('是否需要先下载', prepared.needsDownload)
console.log('平台提示', prepared.tips)

if (prepared.canShare) {
  LizhaoSharePlus.shareFile({
    file: prepared.normalized.file,
    mimeType: prepared.normalized.mimeType,
    fileNameStrategy: prepared.normalized.fileNameStrategy,
    fail(err) {
      console.log('正式分享失败', err)
    }
  })
} else {
  console.log('当前不能分享', prepared.reason)
}

预检检查当前可获取的本地文件状态；远程文件仅按 URL 推断，正式下载后的类型可能不同。预计整体 MIME 位于 resolvedMimeType，不会写回 normalized.mimeType，因此将归一参数用于正式分享时仍能继续自动识别。预检不能代替正式文件读取、目标应用兼容性或用户最终发送结果。

如果只需要简单查询平台能力，可以使用：

const capability = LizhaoSharePlus.canIShare({
  file: '/storage/emulated/0/Download/report.pdf',
  mimeType: 'application/pdf'
})

if (!capability.supported) {
  console.log(capability.reason)
}

模块九：文件归一化

normalizeShareFiles() 用于检查文件路径和识别结果，不会调起分享面板。Android/iOS 不会因此下载远程文件或读取文件头，适合在提交分享前展示本地文件的归一路径、类型和整体 MIME。

LizhaoSharePlus.normalizeShareFiles({
  files: [
    '/storage/emulated/0/Download/report.pdf',
    '/storage/emulated/0/Download/photo.png'
  ],
  success(res) {
    console.log('文件信息', res.filesResolved)
    console.log('整体类型', res.resolvedMimeType)
  },
  fail(err) {
    console.log('文件归一化失败', err)
  }
})

filesResolved 返回每个文件的原始地址、实际路径、MIME、文件名和可用的大小信息。远程文件的最终名称、路径和类型仍以正式下载后的结果为准；需要判断整个分享场景是否可用时使用 prepareShare()。

模块十：兼容旧参数调用

旧项目如果使用 type / title / summary / path 参数，可以先用 shareWithSystem() 保持原有业务结构，再逐步迁移到 shareText()、shareUrl() 和 shareFile()。

LizhaoSharePlus.shareWithSystem({
  type: 'file',
  title: '报告文件',
  summary: '请查看这份 PDF 报告',
  path: '/storage/emulated/0/Download/report.pdf',
  fileNameStrategy: 'keep',
  success(res) {
    console.log('分享面板已调起', res)
  },
  fail(err) {
    console.log('分享失败', err)
  }
})

新接入项目优先使用 shareText()、shareUrl()、shareFile() 或通用 share()；shareWithSystem() 主要用于平滑迁移已有调用。

模块十一：Android/iOS 分享图片到 Instagram

按 Instagram Sharing to Feed 官方文档 接入，适用普通 Instagram 账号。App 必须包含新版插件原生代码，设备安装 Instagram。该入口交付单张真实 PNG/JPEG，支持 /static/logo.png、相册临时文件、可访问的本地文件、file:// 与远程 http/https 图片；远程图片会先下载。

LizhaoSharePlus.shareToInstagram({
  file: '/static/logo.png',
  success(res) {
    console.log(res.handedOff ? '图片已交给 Instagram，发布由用户确认' : '已启动 Instagram 分享入口，请在应用内确认图片并发布', res)
  },
  fail(err) {
    console.log('Instagram 图片分享未完成', err)
  },
  complete(res) {
    console.log('本次调用结束', res)
  }
})

Android 使用系统 ACTION_SEND 和固定目标包名 com.instagram.android，不需要额外的 Instagram SDK；插件准备图片并授予临时 URI 读取权限。success 只表示目标入口已启动，不能确认 Instagram 已读取图片，也无法报告用户随后在 Instagram 内取消或发布。目标未安装或不接受该分享返回 9011005。

iOS 系统文档交互菜单可能仍需用户选择 Instagram，随后由 Instagram 提供编辑和发布界面；只在系统文件交付结束后报告 success，交付前取消返回 9011006。两端均没有自动发帖、专业账号授权或 Content Publishing 流程。

官方页面未提供正文预填参数。text 为空或省略；传任何非空字符串（含纯空白）返回 9011002，不会静默忽略、写剪贴板或将文字画进图片。正文请在 Instagram 中输入。图片保持原始尺寸和字节，不强制裁成 640×640；HEIC、GIF、WebP、视频、多图与“发给好友/群”不属于该入口。

InstagramShareResult 包含以下字段。任意成功结果都不能证明用户已发帖。

fileResolved 沿用下文文件元数据：original 保留客户输入，mimeType 为实际 PNG/JPEG。成功后的请求缓存会保留，避免接收方异步读取时失效；应用可按自身缓存保留策略在后续适当时机清理。

HarmonyOS、Web 和小程序调用此入口异步返回 9011001；原系统分享和任意 Android targetPackage 继续使用原 API。canIShare()、prepareShare() 仍检查原系统分享，不能当作 Instagram 是否安装或能接收的保证。

API 用途速查

详细参数、默认值、回调与返回字段见本节下方的参数表和返回值说明。

参数与回调

通用回调

详细的完成状态以“主要返回值”中的 ShareResult 为准。

ShareOptions 参数

至少应传入 text、url、file 或 files 中的一项有效内容。

场景预设

preset 主要用于通用 share() 和分享前预检。完整取值和适用场景见“模块七：组合分享”；使用 shareText()、shareUrl() 或 shareFile() 时通常不需要再填写。

ShareWithSystemOptions 参数

常用配置

选择接入方式

返回值

PrepareShareResult

ShareCapability

ShareResult

iOS 的 completed 来自系统完成回调，用户取消时可能为 false。Android 与 HarmonyOS 的 completed 表示已成功调起分享面板，不能据此判断用户是否已经把内容发送出去。

ShareResolvedFile

NormalizeShareFilesResult

错误码说明

错误主题 errSubject 为 lizhao-share-plus；失败时保留 errCode 和 errMsg，按下表处理。

注意事项

支持平台

uni-app 与 uni-app x 使用相同的公开 API。平台是否能够执行真实分享，以本表和 canIShare() / prepareShare() 的结果为准。

• 页面只能从 @/uni_modules/lizhao-share-plus 导入，不要直接导入 utssdk 或平台实现文件。
• App 端必须运行包含本插件原生代码的安装包；仅更新页面资源不能替换已经编译进安装包的 UTS 原生逻辑。
• 只调整业务页面参数或本文档时，不需要因此重新制作自定义基座；插件原生代码、依赖或原生配置变化后才需要重新构建对应安装包。
• 文件路径必须在 App 运行时真实存在并可访问；mimeType 不会修复错误路径，也不会转换文件格式。
• Android 指定应用时使用真实包名；不确定目标应用是否支持某种文件时，先不传 targetPackage，通过系统分享面板验证。
• Android/iOS 下载远程文件时会占用网络与本地缓存空间；包含敏感信息的文件应按项目隐私和清理策略处理。
• HarmonyOS 支持最多 500 个本地文件；Android/iOS 和接收应用也可能存在各自的数量或大小限制。
• 不传 MIME 时每个文件独立识别，再合并整体分享类型；显式传入一个 MIME 时按该值处理整批文件。接收应用可能限制文件数量、格式与大小。
• 分享完成状态请按 ShareResult.completed 的平台说明处理，不要只根据按钮点击更新页面状态。
• Instagram 专用 API 返回 InstagramShareResult.launched 和 handedOff；Android 仅能确认启动，iOS 可确认系统文件交付，两者均不能证明用户已发帖。使用该入口前需匹配当前源码的 Android/iOS 原生联编、自定义基座或安装包，页面资源热更新不能更新原生部分。
• 分享前预检只能减少参数和平台错误，不能代替目标应用、真实设备和真实文件的最终验证。
• Web/H5、微信小程序和支付宝小程序不提供本插件的真实 App 系统分享能力，应根据 9011001 做业务降级。

常见问题

DOCX 或 TXT 文件需要修改 mimeType 吗

通常不需要。省略 mimeType 时只需换成实际文件路径，插件会自动识别 DOCX、TXT 等类型。如果代码已手动填写 MIME，则仍应随文件一起调整，例如：

// DOCX
mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'

// TXT
mimeType: 'text/plain'

如果 DOCX 仍填写 application/pdf，系统会把它当成 PDF 类型交给目标应用，可能导致目标应用不显示、无法打开或识别错误。

mimeType 可以不传吗

可以，推荐普通文件场景省略。插件自动识别 DOCX、TXT、PDF、图片等常见类型；无法识别时使用通用类型兜底。显式传入 MIME 则以你的值为准。

mimeType 会把文件转换成对应格式吗

不会。mimeType 只是告诉系统“这个文件是什么类型”，不会修改文件内容或扩展名。扩展名、实际内容和 MIME 应保持一致。

为什么指定微信后没有调起分享

先确认只在 Android 使用 targetPackage: 'com.tencent.mm'，并确认设备已经安装微信。还要检查 MIME 是否正确；即使应用已安装，如果它没有可接收该类型的分享入口，也可能进入失败回调。调试时可以暂时移除 targetPackage，观察系统分享面板中是否出现微信。

success 是否表示用户已经发送成功

不一定。请按“主要返回值”中的 ShareResult.completed 平台语义处理。

为什么本地文件返回 9011003

传入的必须是 App 运行时真实可访问路径，不应直接使用仅存在于源码目录中的路径。Android 优先使用可访问的绝对路径或 content:// URI，由插件为普通绝对路径生成可授权读取的文件 URI；不要把 file:// 作为 Android 对外分享的首选。iOS 使用可访问的绝对路径或有效 file:// 地址。HarmonyOS 可以解析项目内 /static/... 路径、应用沙箱路径和有效文件 URI。

多文件分享为什么接收应用只收到一个文件

插件会调用平台的原生多文件分享能力，但最终接收数量取决于目标应用。一些应用只处理第一项。请先用同类型文件测试，并确保每个文件都存在且可访问。

可以一次分享 PDF、DOCX 和图片吗

可以，不传 mimeType 时会逐项识别并合并为 */*。目标应用匹配和接收结果可能不同；必要时按文件类型分组分享。

HarmonyOS 为什么不能直接分享远程 URL

HarmonyOS 支持本地文件系统分享，但不会在分享过程中自动下载远程文件。请先由项目把远程文件下载到应用可访问位置，再将本地路径传给 shareFile()。

预检通过后为什么正式分享仍可能失败

prepareShare() 不下载文件、不打开目标应用，也不能模拟接收应用的真实行为。网络变化、文件被删除、目标应用不兼容或用户取消仍会影响正式结果，因此正式分享仍需处理 fail 和平台完成语义。

Web/H5 或小程序为什么返回不支持

这些平台目前只保留统一 API 和明确的降级错误，不执行 App 原生系统分享。业务页面可以先调用 canIShare()，在不支持时隐藏按钮或显示替代提示。

作者系列 UTS 插件

以下为作者已上架的 UTS 插件，详情见各市场页面或作者主页。