Share | Unif Umeng

分享 API，支持命令式面板（推荐）和直拉单平台两种模式，目标平台为微信会话 / 钉钉。

引用

import { Share } from '@unif/react-native-umeng';

方法	签名	返回
`openSheet`	`openSheet(payload, options?)`	`Promise<ShareResult>`
`shareText`	`shareText(options: ShareTextOptions)`	`Promise<ShareResult>`
`shareImage`	`shareImage(options: ShareImageOptions)`	`Promise<ShareResult>`
`shareLink`	`shareLink(options: ShareLinkOptions)`	`Promise<ShareResult>`
`isInstalled`	`isInstalled(platform: Platform)`	`Promise<boolean>`
`listPlatforms`	`listPlatforms()`	`Promise<PlatformInfo[]>`

取消 / 失败走 reject，不走 resolve

openSheet 与所有 shareXxx 只有成功才 resolve（resolve 到手的 ShareResult.code 恒为 'success'）；用户取消、分享失败、目标未安装都会抛 UmengError。永远 try/catch，详见取消与失败的处理。

`Share.openSheet(payload, options?)`

命令式拉起分享面板（推荐用法）。需在 App 根挂载 <ShareSheetHost />，否则 Promise 立即 reject（E_UNKNOWN，message No <ShareSheetHost /> mounted）。一次只能有一个 active session，重入直接 reject且不会覆盖旧 Promise。

function openSheet(
  payload: ShareSheetPayload,
  options?: ShareSheetOptions
): Promise<ShareResult>;

`ShareSheetPayload`

判别联合，type 决定其余字段：

type ShareSheetPayload =
  | { type: 'text'; text: string }
  | { type: 'image'; image: string; thumb?: string }
  | { type: 'link'; title: string; url: string; description?: string; thumb?: string };

`type`	字段	必填	说明
`'text'`	`text: string`	✅	纯文字内容
`'image'`	`image: string`	✅	图片网络 URL(本地路径 / base64 暂不支持)
	`thumb?: string`	—	缩略图
`'link'`	`title: string`	✅	链接标题
	`url: string`	✅	链接 URL
	`description?: string`	—	链接描述
	`thumb?: string`	—	缩略图

`ShareSheetOptions`

字段	类型	默认值	说明
`title`	`string`	`'分享至'`	面板标题
`cancelText`	`string`	`'取消'`	取消按钮文案
`subtitles`	`Partial<Record<Platform, string>>`	见 `PLATFORM_DEFAULT_SUBTITLES`	各平台副标题覆盖
`hideUninstalled`	`boolean`	`false`	`true` 完全隐藏未安装平台；`false` 时仍显示且可点击

hideUninstalled=false 时，点击未安装的平台不会调用 native share；openSheet 返回的 Promise 会 reject UmengError，code 为 E_PLATFORM_NOT_INSTALLED。只有 hideUninstalled=true 才会完全隐藏未安装平台。

openSheet 先进入 loadingPlatforms 并调用 listPlatforms()。查询失败时 Modal 不会伪装成“全部未安装”,而是用原错误结束当前 Promise。多个 Host 同时挂载时,最早注册者成为本次 owner;owner 在 loading / ready / sharing 任一阶段卸载都会 reject E_UNKNOWN,message 为 The active <ShareSheetHost /> unmounted before the share completed.。非 owner 卸载不影响当前 session。

controller 用递增 sessionId 隔离会话。当前 session 开始 sharing 后，遮罩/返回键 dismiss 不会抢先结算；平台回调才决定成功或失败。旧 session 的迟到 callback、重复 callback 或旧 Host 事件不能结算后续 session。

import { Share, UmengError } from '@unif/react-native-umeng';

try {
  const r = await Share.openSheet(
    { type: 'link', title: '问问看', url: 'https://example.com', description: '一句话描述' },
    { title: '分享到', hideUninstalled: true }
  );
  // r.code === 'success'
} catch (e) {
  if (e instanceof UmengError && e.code === 'E_USER_CANCEL') {
    /* 用户取消，通常静默 */
  }
}

`Share.shareText(options)`

直拉单平台分享纯文字，跳过面板。

function shareText(options: ShareTextOptions): Promise<ShareResult>;

字段	类型	必填	说明
`platform`	`Platform`	✅	目标平台（`Platform` 枚举）
`text`	`string`	✅	文字内容

text 为空时抛 E_INVALID_OPTIONS。

`Share.shareImage(options)`

直拉单平台分享图片。

function shareImage(options: ShareImageOptions): Promise<ShareResult>;

字段	类型	必填	说明
`platform`	`Platform`	✅	目标平台
`image`	`string`	✅	图片网络 URL(本地路径 / base64 暂不支持)
`thumb`	`string`	—	缩略图 URL

image 为空时抛 E_INVALID_OPTIONS。本地图(截图 / 相册路径 / base64)传不进原生层 —— 需先上传拿到 https:// URL 再分享。

`Share.shareLink(options)`

直拉单平台分享图文链接。

function shareLink(options: ShareLinkOptions): Promise<ShareResult>;

字段	类型	必填	说明
`platform`	`Platform`	✅	目标平台
`title`	`string`	✅	链接标题
`url`	`string`	✅	链接 URL
`description`	`string`	—	链接描述
`thumb`	`string`	—	缩略图 URL

title 或 url 为空时抛 E_INVALID_OPTIONS。

`Share.isInstalled(platform)`

查询指定平台 App 是否已安装。

function isInstalled(platform: Platform): Promise<boolean>;

Android 在无前台 Activity 时无法可靠判断，保守返回 false。

`Share.listPlatforms()`

获取全部支持平台的安装状态列表（按 SUPPORTED_PLATFORMS 顺序）。<ShareSheetHost /> 用它渲染面板的平台条目。

function listPlatforms(): Promise<PlatformInfo[]>;

返回 PlatformInfo[]：

字段	类型	说明
`platform`	`Platform`	平台枚举值
`installed`	`boolean`	是否已安装
`displayName`	`string`	平台显示名称（如 `'微信'` / `'钉钉'`）

返回值 `ShareResult`

interface ShareResult {
  code: 'success';
  platform: Platform;
  message?: string;
}

公共 ShareResult.code 只有 'success'。native 内部可以报告 cancel / failed,但 JS 会在公共边界把它们转换为 UmengError;它们不是 ShareResult 的成员。

取消与失败:reject-on-cancel

openSheet 与所有 shareXxx 把 native 的 cancel / failed 翻成 UmengError 抛出，只有 success 才 resolve：

// ❌ Incorrect:取消 / 失败不会 resolve，判别分支永远到不了
const r = await Share.openSheet(payload);
if (r.code === 'cancel') { /* 永远到不了 */ }

// ✅ Correct:try/catch 看 e.code;resolve 的 r.code 必为 'success'
try {
  const r = await Share.openSheet(payload); // r.code === 'success'
} catch (e) {
  if (e instanceof UmengError) {
    switch (e.code) {
      case 'E_USER_CANCEL':            /* 用户取消，静默 */ break;
      case 'E_PLATFORM_NOT_INSTALLED': /* 目标 App 未安装 */ break;
      case 'E_SHARE_FAILED':           /* 分享失败，查 e.message */ break;
    }
  }
}

可能抛出的 UmengError.code：

`code`	触发
`E_USER_CANCEL`	用户点取消 / 点遮罩 / 平台侧取消
`E_SHARE_FAILED`	分享失败（未配 URL Scheme、网络错、内容不合规等）
`E_PLATFORM_NOT_INSTALLED`	目标微信 / 钉钉未安装（面板内点击未安装平台时）
`E_PLATFORM_NOT_SUPPORTED`	传了不在 `SUPPORTED_PLATFORMS` 的平台
`E_INVALID_OPTIONS`	必填字段缺失（`shareText` 缺 `text`、`shareLink` 缺 `title`/`url` 等）
`E_NOT_INITIALIZED`	尚未完成 `Common.init()` 就调用 `shareXxx` / `isInstalled` / `listPlatforms`;`openSheet` 在 loading 阶段传播此错误
`E_UNKNOWN`	未挂 Host、面板重入、owner Host 卸载、平台查询失败或 SDK 未知错

完整错误码表见常见问题 → 错误码速查。

平台支持

API	iOS	Android
`openSheet`	✅ UI/controller；真分享待真机	✅ UI/controller；真分享待真机
`shareText` / `shareImage` / `shareLink`	✅ init gate / first-settle XCTest	✅ native contract / JVM callback tests
`isInstalled`	✅ init gate XCTest	✅ native contract / JVM tests
`listPlatforms`	✅	✅

iOS simulator/XCTest 与 Android native contract/JVM tests 已验证桥接、门禁和结算语义；两类自动化证据都不能替代微信 / 钉钉真实 App 的拉起与回包。

分享指南 —— 任务导向用法、payload 类型、坑
Platform & ShareSheetHost —— Platform 枚举 + 宿主组件挂载
常见问题 —— 错误码速查与分享无回调排障

引用​

Share.openSheet(payload, options?)​

ShareSheetPayload​

ShareSheetOptions​

Share.shareText(options)​

Share.shareImage(options)​

Share.shareLink(options)​

Share.isInstalled(platform)​

Share.listPlatforms()​

返回值 ShareResult​

取消与失败:reject-on-cancel​

平台支持​

相关​

引用