从“按钮里写下载逻辑”到“动作语义上推”：React Native 鸿蒙跨平台项目里的 onDownload/onShare 实践

在我接手一个 React Native 鸿蒙跨平台项目第三周的时候，一个文件卡片组件把我气得够呛。那个组件里塞了下载逻辑、分享逻辑、失败重试、进度回调、埋点上报……一个列表项组件比整个页面还重，换了个页面想复用，结果发现下载路径写死了、分享文案写死了，根本提不出来。后来我把 onDownload 和 onShare 这两个事件从组件内部抽出来，用“动作语义”上推到页面层统一处理，整个结构才算理顺。这篇文章就把这套设计思路在鸿蒙 RN 环境里的完整落地方式拆开讲讲，适合正在做 React Native 鸿蒙跨平台、尤其被下载分享这类“组件内副作用”折磨过的同学参考。

1. 从“按钮里写下载逻辑”到“动作语义上推”：先讲清楚概念差异

1.1 命令式写法的三个典型问题

很多团队拿到 RN 鸿蒙项目后的第一版代码是这样的：文件卡片组件里直接调原生下载模块，或者直接调系统分享面板。

typescript复制// 命令式写法（不推荐的典型风格）
const FileCard = ({ file }: { file: FileItem }) => {
  const handleDownload = async () => {
    // 组件内部直接调用原生能力
    const result = await NativeModules.DownloadModule.download(file.url, file.name);
    if (result.success) {
      Toast.show('下载成功');
    }
    trackEvent('download', { fileId: file.id });
  };
  // 分享逻辑也从这里直接拉起来
  return (
    <View style={styles.card}>
      <Text>{file.name}</Text>
      <Button title="下载" onPress={handleDownload} />
    </View>
  );
};

这么写有三个问题，我一个个说。

第一个是复用性差。文件卡片出现的场景绝不止一个页面，可能是首页列表、搜索结果、收藏夹、分享回流页。如果下载逻辑写在卡片内部，那每个页面都得复制一份组件，或者很别扭地给组件塞一堆 props 来控制行为差异。

第二个是职责混乱。下载涉及权限申请、进度展示、错误处理、文件重名策略，分享涉及分享文案拼接、分享渠道选择、用户授权。这些都属于业务编排逻辑，不该由展示型组件承担。组件一重，测试和排查的成本就直线上升。

第三个是鸿蒙侧能力无法统一收敛。鸿蒙对文件读写、分享拉起有自己的一套权限和路径约束，如果每个组件都直接碰原生模块，一旦鸿蒙的 API 升级或权限策略调整，你要改的地方可能是十几个分散的组件。

1.2 动作语义的本质：按钮只报告意图，页面负责执行

“动作语义上推”解决的就是这三类问题。它的核心思想是：子组件不负责执行任何有副作用的操作，只负责把“用户想做什么”这个意图向上报告。

拿我们业务里的 onDownload 和 onShare 来说，这两个并不是 React Native 官方内置的组件事件，而是我们自己定义的一套动作协议。子组件在用户点击下载按钮时，不做任何下载操作，只调用 props.onDownload(file)，把这个文件对象提交给上层；具体是下载到沙箱、保存到相册还是交给系统下载服务，由页面统一决定。

打个比方：客人进餐厅不自己下厨，而是告诉服务员“我要一份宫保鸡丁”。服务员把这张单子送到后厨，后厨决定用什么锅、放多少油、几分钟出锅。这里的“服务员”就是 onDownload 事件，而“后厨”就是页面层面的统一处理器。

做这种设计时有个容易混淆的点：动作语义不等于传统意义上的回调函数。回调函数的关注点是“子组件完成某事后通知父组件”，而动作语义的关注点是“子组件触发某个意图，由父组件决定如何执行”。前者是结果通知，后者是命令上抛，思考方向是相反的。

2. RN 鸿蒙环境下，下载与分享能力是怎么暴露给 JS 层的

2.1 鸿蒙原生能力与 RN 之间的桥接现状

要在业务层设计好 onDownload/onShare，先得搞清楚鸿蒙原生能力如何到达 RN 的 JS 层。

React Native 在鸿蒙上的适配主要走的是 OpenHarmony 社区的 react-native-harmony 方案，核心包名通常是 @react-native-oh/react-native-harmony。它保留了 RN 的 JS 运行时和渲染管线，同时通过 TurboModule（新架构）或传统的 NativeModule（旧架构）把鸿蒙原生能力暴露给 JS。

鸿蒙侧下载，常见做法是封装 @ohos.request 或 @ohos.file.fs 相关能力；分享则通常拉起系统分享面板或调用分享 SDK。但这些 API 在 JS 层并不能直接使用，必须在鸿蒙原生侧写一个 TurboModule，把它们封装成 JS 可调用方法。

原生侧大致是这样的结构（ArkTS 简化解法示意）：

typescript复制// 鸿蒙原生侧示意（简化）
@NativeModule
export class DownloadModule extends TurboModule {
  @Method
  download(url: string, fileName: string): Promise<DownloadResult> {
    // 这里调用鸿蒙下载或文件管理能力
  }
}

@NativeModule
export class ShareModule extends TurboModule {
  @Method
  share(options: ShareOptions): Promise<ShareResult> {
    // 这里拉起系统分享面板
  }
}

而 JS 侧在业务代码里通常会这样调用：

typescript复制import { NativeModules } from 'react-native';
const { DownloadModule, ShareModule } = NativeModules;

关键点来了：原生模块暴露的是“执行能力”，而不是“业务协议”。如果你的业务代码到处直接 NativeModules.DownloadModule.download(...)，那原生模块的任何改动都可能引发连锁反应。所以操作能力之上还需要一层业务抽象，这正是 onDownload/onShare 存在的价值。

2.2 为什么业务层需要 onDownload / onShare 这层抽象

我先说结论：这层抽象是给“变化”留缓冲区的。

鸿蒙侧的下载和分享策略变化非常频繁。比如鸿蒙对公共目录写入的控制越来越严格，某些路径可能要求使用安全控件；分享面板的拉起方式在不同 API 版本上也有差异。如果业务层和原生层贴得太紧，每次策略调整都要改业务代码。有了 onDownload/onShare 这层动作语义，页面层完全可以内部消化这些变化，展示组件一行都不用动。

另外，RN 鸿蒙跨平台项目通常还要兼顾 Android 和 iOS。Android 的下载可能是系统 DownloadManager，iOS 可能是 NSURLSession 下载后存到 FileManager。鸿蒙又是另一套。动作语义上推后，各端的差异只收敛在页面层对应的处理器里，跨平台业务代码可以共用一套组件结构。

3. 完整实现：子组件抛出动作，页面统一接住下载与分享

3.1 先把动作事件协议定清楚

动手写代码前，先把动作事件的结构定死。我的建议是不要传一堆散参数，而是定义一个统一的动作载荷（Action Payload）类型。这一步非常重要，协议定清楚了，后续所有组件和页面的对接都会顺畅。

typescript复制// types/action.ts
export interface DownloadActionPayload {
  action: 'download';
  fileId: string;
  fileName: string;
  fileUrl: string;
  fileSize?: number;
  source?: string; // 埋点用：从哪个页面/模块发起
  ext?: Record<string, unknown>;
}

export interface ShareActionPayload {
  action: 'share';
  fileId: string;
  fileName: string;
  fileUrl?: string;
  shareText?: string;
  shareImage?: string;
  source?: string;
  ext?: Record<string, unknown>;
}

为什么要把 source 放进去？因为下载和分享大概率需要埋点。如果每个页面自己拼埋点参数，十个页面就有十种拼法；放统一载荷里，页面层拿到动作载荷后顺手就能把埋点一起打掉，谁也不漏。

协议里还有个细节：fileUrl 的形态在不同端可能不同。鸿蒙沙箱路径、网络 URL、临时缓存文件路径是三种完全不同的东西。协议层不要限制死，让页面处理器各自归一化。

3.2 子组件侧：只发动作，不碰原生能力

子组件 FileCard 的职责变得很纯粹：渲染文件信息，处理用户点击，然后上抛动作。

typescript复制import React from 'react';
import { View, Text, Button } from 'react-native';
import { DownloadActionPayload, ShareActionPayload } from '../types/action';

interface FileCardProps {
  file: {
    id: string;
    name: string;
    url: string;
    size?: number;
  };
  source?: string;
  onDownload: (payload: DownloadActionPayload) => void;
  onShare: (payload: ShareActionPayload) => void;
}

const FileCard = ({ file, source = 'unknown', onDownload, onShare }: FileCardProps) => {
  const handleDownload = () => {
    onDownload({
      action: 'download',
      fileId: file.id,
      fileName: file.name,
      fileUrl: file.url,
      fileSize: file.size,
      source,
    });
  };

  const handleShare = () => {
    onShare({
      action: 'share',
      fileId: file.id,
      fileName: file.name,
      fileUrl: file.url,
      shareText: `分享文件：${file.name}`,
      source,
    });
  };

  return (
    <View style={styles.card}>
      <Text style={styles.name}>{file.name}</Text>
      <Text style={styles.size}>{file.size ? `${file.size}MB` : '大小未知'}</Text>
      <View style={styles.buttonGroup}>
        <Button title="下载" onPress={handleDownload} />
        <Button title="分享" onPress={handleShare} />
      </View>
    </View>
  );
};

特别注意：组件内部没有 NativeModules、没有 Toast、没有 trackEvent。组件对鸿蒙原生能力一无所知，它唯一知道的是“用户按了这两个按钮，我把意图抛出去”。这样组件才能在任何页面、任何场景下被放心复用。

3.3 页面侧：集中处理下载、分享、权限与埋点

页面层是动作语义的“后厨”。以首页为例：

typescript复制import React from 'react';
import { View, FlatList, Alert } from 'react-native';
import FileCard from '../components/FileCard';
import { downloadFile } from '../services/downloadService';
import { shareFile } from '../services/shareService';
import { DownloadActionPayload, ShareActionPayload } from '../types/action';

const HomePage = () => {
  const files = [...]; // 从接口拿到的文件列表

  const handleDownload = async (payload: DownloadActionPayload) => {
    // 埋点统一上报
    trackEvent('file_download_click', {
      fileId: payload.fileId,
      source: payload.source,
    });
    try {
      // 权限申请、路径策略、重名策略都在这里统一处理
      await downloadFile(payload.fileUrl, payload.fileName, payload.fileId);
      Alert.alert('下载完成', `${payload.fileName} 已保存`);
    } catch (error) {
      Alert.alert('下载失败', error.message);
    }
  };

  const handleShare = async (payload: ShareActionPayload) => {
    trackEvent('file_share_click', {
      fileId: payload.fileId,
      source: payload.source,
    });
    try {
      await shareFile({
        fileName: payload.fileName,
        shareText: payload.shareText,
        fileUrl: payload.fileUrl,
      });
    } catch (error) {
      Alert.alert('分享失败', error.message);
    }
  };

  return (
    <View style={{ flex: 1 }}>
      <FlatList
        data={files}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => (
          <FileCard
            file={item}
            source="home_page"
            onDownload={handleDownload}
            onShare={handleShare}
          />
        )}
      />
    </View>
  );
};

页面处理器里可以做很多事情：弹确认框、申请权限、显示下载进度、失败重试、成功后的 Toast 提示；分享前检查文件是否存在、分享后统计用户是否完成分享。所有这些逻辑都被“后厨”收拢了，以后要改下载策略，只改 downloadService 或页面处理器，组件和协议都不用动。

3.4 事件载荷与多场景复用

动作语义上推还有一个隐性红利：同一个组件可以对接完全不同的业务逻辑。比如在收藏夹页面，下载前可能先检查用户是否登录；在网盘页面，分享前可能弹出“生成分享链接”的确认框。两个页面的 handleDownload/handleShare 实现完全不同，但 FileCard 组件不用改一行代码。

如果一个页面里有多个文件卡片，而页面处理器需要区分来源，source 字段或者载荷里的 fileId 就派上用场了。还可以在页面层维护一个 pendingAction 状态，把并发点击串行化，避免用户狂点下载按钮导致启动多个下载任务。

4. 鸿蒙适配里最容易翻车的几个点：白屏、权限、分享面板

动作语义设计得再好，落到鸿蒙真机上还是会遇到一波适配问题。这几个月踩下来，最典型的有三个。

4.1 启动白屏：引擎与页面时序问题复盘

RN 鸿蒙项目启动白屏，是我被问过最多的问题，自己也踩过一次。那次的场景是：应用冷启动后，首页偶尔白屏几秒甚至更久，Logcat 里也没有明显的 JS 报错。排查链路大概是这样的：

第一步，先确认 bundle 是否加载成功。RN 鸿蒙的 bundle 可以在本地 assets 里，也可以从远程拉取。如果远程加载失败，页面就没有内容可渲染，表现就是白屏。把加载逻辑改为本地 bundle 优先、远程作为增量更新，白屏概率明显下降。

第二步，排查 UIAbility 的窗口时序。鸿蒙侧的 RN 容器需要等到窗口加载完成后再挂载 RN 视图，如果 JS 侧代码在 RootView 尚未准备好时就执行了业务初始化，可能出现页面空白。这个问题的关键是在原生侧给 RN 容器设置正确的生命周期回调。

第三步，确认 TurboModule 注册时机。如果是新架构项目，TurboModule 初始化较慢时，业务代码调用原生方法可能拿到空对象。建议在页面层把涉及原生模块的动作处理器做“懒加载 + 重试”，避免在模块未就绪时直接抛异常。

4.2 下载权限与沙箱路径：不是装上就能写文件

鸿蒙应用沙箱对文件写入的限制比很多人想象中严格。普通下载保存到应用沙箱的 files 目录通常没问题，但如果用户想从系统相册或“文件”App 里直接访问，就需要保存到公共目录，这时必须申请对应权限，或者直接使用鸿蒙提供的安全控件，让用户在系统弹窗里主动授权。

另外，下载文件的重名处理也要提前想好。鸿蒙沙箱内写入同名文件不会报错，但可能导致覆盖，用户会奇怪为什么之前下载的文件没了。我的建议是在 downloadService 里做统一策略：先检查目标文件是否存在，存在则自动拼“(1)”“(2)”后缀。

还有一个小坑是下载后的文件 URI 格式。在鸿蒙上，沙箱内文件路径和可分享给其他应用的 URI 不是一回事，分享前往往需要把沙箱路径转换成可供系统分享组件识别的 URI。这个转换如果漏掉，会出现“文件下载成功但分享时对方打不开”的诡异问题。

4.3 分享面板拉起失败：URI 格式与回调时序

onShare 动作上推到页面层后，页面处理器调用鸿蒙分享面板。分享面板拉起失败主要有几个原因：传入的 URI 格式不被系统识别；文件不存在；分享的数据类型和文件扩展名不匹配。

这里有个非常容易忽略的细节：鸿蒙分享面板的拉起时机最好在 ReactNative 应用处于前台且页面渲染完成之后。如果你在组件刚 mount 完就立刻调用分享（比如某些自动分享场景），面板可能弹不出来。一个有效缓解手段是在页面处理器里把分享动作包一层 InteractionManager.runAfterInteractions，等交互任务跑完再拉起原生面板。

分享结果的回调也要留神。鸿蒙分享面板的 onResult 回调并不保证在用户关闭面板前一定触发，某些取消操作可能没有回调。因此页面处理器里不要依赖“分享结果成功”来清理状态，比如不要把分享中的 loading 状态一直转着等回调。

5. 动作语义上推还能扩展到哪些场景

5.1 从下载/分享推广到通用动作协议

当你把 onDownload/onShare 这套动作语义跑通后，会发现它其实是一种通用的组件设计模式：评论、点赞、删除、预览、重命名……凡是“展示组件不关心如何执行、由页面统一编排”的操作，都可以用同一套协议来承载。

比如文件卡片上的“预览”动作，组件只需要抛出 onPreview(payload)，页面层决定用 WebView 打开、用原生预览器打开还是跳到详情页。“删除”动作也一样，组件只负责“用户想删除这个文件”的意图，页面层负责弹确认框、调删除接口、处理失败回滚。

可以把动作协议定义成一张表：

协议统一后，埋点逻辑、错误处理、交互确认框都可以在页面处理器里复用公共工具函数，组件层则保持单薄。

5.2 与状态管理、埋点框架的配合方式

如果你的项目用了 Redux、Zustand 或 MobX，动作语义上推不会和它们冲突，反而可以形成清晰的边界：组件只发动作事件，页面处理器里再决定是 dispatch 一个 Redux action、调用 service 层方法，还是直接修改本地 state。

埋点框架的配合也很自然。所有动作事件在页面处理器落地时，都先经过一个统一的 trackEvent 入口。这样产品经理想调整埋点参数，你只需在页面处理器附近改，不必翻遍所有组件。

我个人的建议是：动作语义上推不要上推得太深。推到页面层就够了，没必要每个事件都全局转一圈再回来，那样会引入不必要的状态同步和性能损耗。有些跨页面共享的动作（比如全局下载任务队列），可以通过 service 层单例承接，而不是把组件和全局状态强绑定。

我在实际项目里的体会是，动作语义上推这件事，最难的不是写代码，而是统一团队意识——让大家都能忍住“在组件里顺手调一下原生模块”的冲动。只要协议设计得够清楚、页面处理器的公共逻辑做得够顺手，这套模式带来的收益会越来越明显。最后再分享一个小技巧：给动作载荷设计好类型后，可以用 TypeScript 的判别联合类型把所有动作收在一个 ActionPayload 里，页面处理器里 switch 一下就能覆盖所有场景，代码结构非常清爽，排查问题时也只需要顺着动作类型找对应分支就行。