更新记录

1.0.3（2026-08-10）

• 修复 iOS 云打包 UTS→Swift 编译失败：补齐 XviewShareRemoteHeader 引用、收窄远程 MIME 的 String?，并将远程下载桥接数值参数改为 NSNumber 以匹配 UTS number。
• 继续加固 iOS 侧 split/自定义数组下标与 join 空安全，降低同类可选类型编译风险。

1.0.2（2026-08-05）

• 修复 Android 指定单应用（targetPackages 仅一个包名）分享多图时被提前截断为单图的问题；优先 ACTION_SEND_MULTIPLE，无匹配 Activity 时再回退单文件 ACTION_SEND。

1.0.1（2026-08-02）

• 新增远程分享 shareRemoteFilesAsync：App 端最多 20 个文件、三路并发、部分成功与 24 小时缓存；Web 返回 9040002。
• 新增远程任务 taskId、cancelShareRemoteFiles 与 listShareCacheFilesAsync；下载阶段可真实取消，取消后以 cancelled: true 结束 Promise。
• 补齐能力探测、缓存、Web File 示例；远程下载 Modal 支持进度、速度与取消；同步 uni-app / uni-app x 示例与文档。
• 修复 Android 虚拟路径解析、文件分享 Intent、多图权限预检、微信/QQ 候选优选，以及 Kotlin/UTS 桥接与编解码编译问题。

平台兼容性

uni-app(4.87)

uni-app x(5.0)

xview-share

跨平台系统分享 UTS 插件。统一封装 Android / iOS / HarmonyOS / Web 的系统分享能力，公共 API 一致；平台差异体现在能力边界与返回错误，不改变调用方式。

支持：文本、链接、单文件、多图片、多文件、远程多文件、系统面板预览（preview）、平台专属配置（platformOptions）。Android 额外支持按包名直达与安装检测。

功能特性

• 基础分享：文本、链接、单文件、多图片、多文件；回调与 Promise 双形态
• 远程分享：最多 20 个远程文件、下载进度、真实取消、部分成功与失败明细
• 平台增强：preview 预览、platformOptions、Android 指定应用 / Chooser Actions、邮件收件人
• 权限与检测：运行时权限申请与静默检查、Android 包名 / iOS Scheme 安装检测
• 缓存管理：远程下载缓存统计、安全文件列表、主动清理
• Web 能力：navigator.share 文本/链接；浏览器 File 对象分享
• 诊断能力：平台能力矩阵、统一错误码（不支持端返回 9040002 等，不抛未捕获异常）

快速使用

import {
  requestSharePermission,
  share,
  shareAsync,
  shareText,
  shareTextAsync,
  shareFile,
  shareImages,
  shareImagesAsync,
  cancelShareRemoteFiles,
  shareRemoteFilesAsync,
  isShareAppInstalled
} from '@/uni_modules/xview-share'

// Android 分享外部媒体前可先申请权限
requestSharePermission({
  type: 'file',
  mimeType: '*/*',
  files: [
    '/storage/emulated/0/Download/a.jpg',
    '/storage/emulated/0/Download/a.mp4'
  ],
  success: (res) => {
    console.log('权限', res.granted, res.permissions)
  }
})

shareText({
  title: '推荐应用',
  text: 'xview-share 支持系统分享',
  url: 'https://uniapp.dcloud.net.cn',
  success: (res) => console.log('成功', res),
  fail: (err) => console.log('失败', err.errCode, err.errMsg)
})

shareTextAsync({
  title: 'Promise 分享',
  text: 'Async 接口返回 Promise'
}).then((res) => {
  console.log(res)
}).catch((err) => {
  console.log(err.errCode, err.errMsg)
})

shareFile({
  title: '分享文件',
  file: '/storage/emulated/0/Download/report.pdf',
  type: 'file',
  mimeType: 'application/pdf'
})

shareImages({
  title: '多图片分享',
  files: [
    '/storage/emulated/0/Pictures/a.jpg',
    '/storage/emulated/0/Pictures/b.jpg'
  ]
})

shareImagesAsync({
  title: 'Promise 多图片分享',
  files: [
    '/storage/emulated/0/Pictures/a.jpg',
    '/storage/emulated/0/Pictures/b.jpg'
  ]
}).then((res) => {
  console.log('已调起文件分享', res.sharedCount)
}).catch((err) => {
  console.log(err.errCode, err.errMsg)
})

// 远程文件会先下载到插件临时缓存；每个文件可以独立配置名称、MIME 和请求头
const remoteTaskId = 'remote-demo-001'
shareRemoteFilesAsync({
  taskId: remoteTaskId,
  title: '远程单文件分享',
  files: [
    {
      url: 'http://files.maxiaoqu.com/images/001.jpg',
      fileName: '001.jpg',
      mimeType: 'image/jpeg'
    }
  ],
  type: 'image',
  mimeType: 'image/jpeg'
}).then((res) => {
  console.log(res.downloadedCount, res.sharedCount)
}).catch((err) => {
  console.log(err.errCode, err.errMsg, err.data)
})

// 仅下载尚未结束时可取消；成功取消后 Promise resolve cancelled: true，并清理当前批次缓存
function cancelRemoteDownload() {
  const result = cancelShareRemoteFiles(remoteTaskId)
  console.log('是否已取消下载任务', result.cancelled)
}

shareRemoteFilesAsync({
  title: '远程多文件分享',
  files: [
    {
      url: 'http://files.maxiaoqu.com/images/001.jpg',
      fileName: '001.jpg',
      mimeType: 'image/jpeg'
    },
    {
      url: 'http://files.maxiaoqu.com/images/002.jpg',
      fileName: '002.jpg',
      mimeType: 'image/jpeg'
    }
  ],
  type: 'image',
  mimeType: 'image/*'
}).then((res) => {
  // 某个文件失败时，只要至少一个下载成功仍会调起分享，并在这里返回失败明细
  console.log(res.downloadedCount, res.failedCount, res.failedFiles)
}).catch((err) => {
  // 全部下载失败时 errCode 为 9040008，err.data.failures 为逐文件原因
  console.log(err.errCode, err.errMsg, err.data)
})

// 仅 Android 有效
if (isShareAppInstalled({ target: 'wechat' })) {
  share({
    title: '分享到指定应用',
    text: 'Android 自定义包名示例',
    target: 'custom',
    targetPackages: ['com.tencent.mm']
  })
}

// 预览与平台专属配置
share({
  title: '业务标题',
  text: '正文',
  url: 'https://uniapp.dcloud.net.cn',
  type: 'url',
  preview: {
    title: '系统面板预览标题',
    summary: '系统面板预览摘要',
    image: '/storage/emulated/0/Download/preview.jpg'
  },
  platformOptions: {
    android: { htmlText: '<p>可选 HTML 正文</p>' },
    harmony: { previewMode: 'detail', selectionMode: 'batch' },
    mail: { to: ['demo@example.com'] }
  }
})

API

回调版通过 success / fail / complete 返回结果；*Async 与 shareRemoteFilesAsync 返回 Promise，成功 resolve 对应结果类型，失败 reject XviewShareFail（errCode + errMsg，远程全部失败时 err.data 为 XviewShareRemoteFilesErrorData）。若 Promise 版同时传入回调，回调仍会触发。完整类型定义见插件内 utssdk/interface.uts。

类型定义

type XviewShareType = 'text' | 'url' | 'image' | 'video' | 'audio' | 'file'

type XviewShareTarget =
  | 'system'   // 完整系统分享面板
  | 'wechat' | 'qq' | 'dingtalk' | 'feishu' | 'weibo'
  | 'mail'     // 邮件；iOS 使用 MFMailComposeViewController
  | 'custom'   // Android 自定义包名；需配合 targetPackages

type XviewSharePreviewOptions = {
  title?: string    // 预览标题；空则回退 options.title
  summary?: string  // 预览摘要；Android 文本/链接/邮件会合并进 EXTRA_TEXT
  image?: string    // 本地缩略图；Web 忽略
}

type XviewSharePlatformOptions = {
  android?: { htmlText?: string }                          // Intent.EXTRA_HTML_TEXT
  ios?: { excludedActivityTypes?: string[] }              // 排除的 ActivityType
  harmony?: {
    previewMode?: 'default' | 'detail'                     // 默认 default
    selectionMode?: 'single' | 'batch'                     // 默认 batch
  }
  mail?: { to?: string[]; cc?: string[]; bcc?: string[] }  // 邮件收件人
}

type XviewShareOptions = {
  title?: string
  text?: string
  url?: string                              // 须 http:// 或 https://
  file?: string                             // 单文件；支持绝对路径、file://、content://、_doc 等
  files?: string[]                          // 多文件/多图
  type?: XviewShareType
  mimeType?: string
  target?: XviewShareTarget                 // 默认 system
  targetPackages?: string[]                 // target 为 custom 时必填
  chooserTitle?: string                     // Android 分享面板标题
  preview?: XviewSharePreviewOptions
  platformOptions?: XviewSharePlatformOptions
  success?: (res: XviewShareResult) => void
  fail?: (err: XviewShareFail) => void
  complete?: (res: any) => void
}

type XviewShareRemoteFile = {
  url: string                               // HTTP/HTTPS 地址
  fileName?: string                         // 缓存文件名；不传则从响应头或 URL 推导
  mimeType?: string                         // 单文件 MIME；优先于 Content-Type
  headers?: Array<{ name: string; value: string }>  // 当前文件专属请求头；不会写入日志
}

type XviewShareRemoteFilesOptions = {
  title?: string
  text?: string
  files: XviewShareRemoteFile[]             // 必填，1–20 个
  type?: XviewShareType                     // 默认 file
  mimeType?: string                         // 不传则按成功文件汇总
  target?: XviewShareTarget
  targetPackages?: string[]
  chooserTitle?: string
  preview?: XviewSharePreviewOptions
  platformOptions?: XviewSharePlatformOptions
  timeoutMs?: number                        // 整批超时；默认且最大 1200000（20 分钟）
  maxFileBytes?: number                     // 单文件上限；默认且最大 52428800（50MB）
  maxTotalBytes?: number                    // 整批上限；默认且最大 209715200（200MB）
}

type XviewShareResult = {
  errCode: 0
  errMsg: string
  platform: 'android' | 'ios' | 'harmony' | 'web'
  target: XviewShareTarget
  targetPackage: string      // Android 命中包名；其他端为空串
  activityType: string       // iOS ActivityType；其他端为空串
  sharedCount: number        // 参与分享的本地文件数
  completed: boolean | null  // iOS 可确认是否完成；其他端固定 null，见下文说明
}

type XviewSharePermissionResult = {
  errCode: 0
  errMsg: string
  platform: string
  granted: boolean
  permissions: string[]
}

type XviewShareRemoteFilesResult = XviewShareResult & {
  requestedCount: number
  downloadedCount: number
  failedCount: number
  failedFiles: Array<{
    index: number
    url: string
    fileName: string
    errCode: XviewShareErrorCode
    errMsg: string
    httpStatus: number
  }>
}

share 参数

快捷方法复用上表字段子集：shareText 需 text；shareFile 需 file；shareImages 需 files。

shareRemoteFilesAsync 参数

行为说明：

• 限制参数只允许调小；最多 20 个文件、三路并发。
• 至少一个文件下载成功时继续分享并 resolve；failedFiles 按输入索引返回跳过项。
• 全部失败时 reject 9040008，err.data 为 { requestedCount, failures }。
• 调用 cancelShareRemoteFiles(taskId) 仅在下载阶段有效；任务已进入系统分享、已结束或不存在时返回 cancelled: false。成功取消会停止网络下载、清理当前批次缓存，原 Promise 会 resolve 并返回 cancelled: true，不会打开系统分享面板。
• 缓存按调用批次隔离，成功文件保留给接收 App 延迟读取；下一次远程分享会清理超过 24 小时的批次。
• 文件名优先级：显式 fileName、响应建议名、URL 路径、自动名称。
• MIME 优先级：单文件配置、响应 Content-Type、扩展名、application/octet-stream。

requestSharePermission 参数

isShareAppInstalled 参数

错误码