RichEditor 嵌入本地图片实现与适配

举报
yd_284811271 发表于 2026/11/12 08:52:26 2026/11/12
【摘要】 前言富文本笔记只有文字会比较单调,插入图片是刚需功能。在 HarmonyOS NEXT 里,RichEditor 支持图片节点渲染,但它不会自动帮我们处理图片选择、权限、图片路径转换、大图缩放、内存回收这些逻辑。本文实现:相册选择图片、权限申请、转为沙盒路径、插入富文本、图片点击预览,同时解决常见的图片变形、路径失效问题。目标效果:在编辑页点击插入图片按钮,拉起相册选择图片;图片成功插入富...

前言

富文本笔记只有文字会比较单调,插入图片是刚需功能。在 HarmonyOS NEXT 里,RichEditor 支持图片节点渲染,但它不会自动帮我们处理图片选择、权限、图片路径转换、大图缩放、内存回收这些逻辑。本文实现:相册选择图片、权限申请、转为沙盒路径、插入富文本、图片点击预览,同时解决常见的图片变形、路径失效问题。

目标效果:在编辑页点击插入图片按钮,拉起相册选择图片;图片成功插入富文本;点击图片可全屏预览;应用卸载后图片跟随清理。

一、方案选型

方案 说明 适用场景
直接使用相册原路径 受相册权限管控,重启后大概率无法访问 不推荐
复制到应用沙盒 cache 目录 私有目录,权限稳定,适合临时图片 编辑草稿图片
复制到 files 持久目录 长期保存,笔记入库后绑定图片 正式笔记配图

笔记场景推荐:选中图片后,先拷贝到应用沙盒目录,再把沙盒路径传给 RichEditor,避免跨目录访问权限问题。

二、依赖导入与权限说明

需要的模块:

import picker from '@ohos.file.picker';
import fs from '@ohos.file.fs';
import common from '@ohos.app.ability.common';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';

模块权限说明(module.json5)

"requestPermissions": [
  {
    "name": "ohos.permission.READ_IMAGEVIDEO"
  }
]

说明:HarmonyOS NEXT 使用 PhotoPicker 拉起相册,推荐使用系统照片选择器,不需要完整文件访问权限,用户只授权选中的图片,隐私性更好。

三、封装图片选择 + 沙盒拷贝工具

export class ImageInsertUtil {
  private static ctx: common.UIAbilityContext;

  static setContext(context: common.UIAbilityContext) {
    this.ctx = context;
  }

  /**
   * 拉起照片选择器,返回沙盒内的图片绝对路径
   */
  static async pickImageToSandbox(): Promise<string | null> {
    try {
      const photoPicker = new picker.PhotoViewPicker();
      const result = await photoPicker.select({
        MIMEType: picker.PhotoViewMIMETypes.IMAGE_TYPE,
        maxSelectNumber: 1
      });
      if (!result.photoUris.length) return null;

      const srcUri = result.photoUris[0];
      // 目标沙盒路径,cache目录,适合草稿图片
      const cacheDir = this.ctx.cacheDir;
      const fileName = `img_${Date.now()}.jpg`;
      const destPath = `${cacheDir}/${fileName}`;

      // 复制文件到沙盒
      await fs.copyFile(srcUri, destPath);
      return destPath;
    } catch (err) {
      const e = err as BusinessError;
      console.error(`图片选择拷贝失败: ${e.code}, ${e.message}`);
      return null;
    }
  }
}

四、RichEditor 插入图片核心代码

RichEditor 通过 addImage 接口插入图片节点,可以设置初始宽高。

@Entry
@Component
struct NoteEditPage {
  @State richContent: string = '';
  private richEditorController: RichEditorController = new RichEditorController();

  aboutToAppear() {
    ImageInsertUtil.setContext(getContext(this) as common.UIAbilityContext);
  }

  // 插入图片按钮点击事件
  async insertImage() {
    const sandboxPath = await ImageInsertUtil.pickImageToSandbox();
    if (!sandboxPath) return;

    // 在光标位置插入图片,设置宽高
    this.richEditorController.addImage({
      value: sandboxPath,
      imageWidth: 300,
      imageHeight: 200
    });
  }

  build() {
    Column() {
      Row() {
        Button("插入图片")
          .onClick(() => this.insertImage())
      }
      RichEditor(this.richEditorController)
        .onChange((val: string) => {
          this.richContent = val;
        })
        .imageOnClick((imgSrc: string) => {
          // 点击图片,跳转到预览页面,传递图片路径
          router.pushUrl({
            url: 'pages/ImagePreviewPage',
            params: { imgUrl: imgSrc }
          })
        })
    }
    .width('100%')
    .height('100%')
    .padding(12)
  }
}

五、图片预览页面简单实现 ImagePreviewPage.ets

@Entry
@Component
struct ImagePreviewPage {
  @State imgUrl: string = router.getParams()?.['imgUrl'] as string;

  build() {
    Column() {
      Image(this.imgUrl)
        .objectFit(ImageFit.Contain)
        .width('100%')
        .layoutWeight(1)
      Button("关闭")
        .margin(16)
        .onClick(() => router.back())
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#000000')
  }
}

六、关键踩坑点

  1. 不能直接把 photoPicker 的 uri 传给 RichEditor
    选中的 uri 是临时授权 uri,页面重建、应用重启之后权限失效,图片直接空白,必须复制到应用私有沙盒。
  2. cache 目录图片会被系统清理
    cache 目录是缓存目录,系统存储空间不足时自动删除里面的文件。如果是正式保存的笔记配图,需要拷贝到 this.ctx.filesDir 持久目录,并且把图片路径存入RDB和笔记绑定。
  3. 大图内存溢出
    相册原图分辨率很高,直接加载容易OOM。可以增加一步:使用 image 模块压缩图片后再保存到沙盒。
  4. 富文本序列化存储
    RichEditor 的 onChange 返回的字符串会包含图片路径,存入数据库时一并保存;打开笔记时,再把字符串 setValue 回填到编辑器。
  5. 图片删除逻辑
    用户在编辑器里删除图片节点时,需要解析富文本字符串,拿到对应的沙盒路径,调用 fs.unlink 删除文件,避免沙盒内垃圾图片堆积。

七、进阶优化方向

  • 图片压缩:选择图片后先压缩,控制长边不超过1080px,减少存储占用和加载耗时;
  • 多图批量选择:修改 PhotoPicker 的 maxSelectNumber,循环批量插入;
  • 图片拖拽调整大小:监听图片手势,动态修改图片宽高;
  • 图片上传端云:同步笔记时,上传图片到对象存储,沙盒路径替换成远端URL;
  • 垃圾图片巡检:打开笔记页的时候,异步扫描沙盒图片,删除没有被任何笔记引用的孤立图片。

结语

RichEditor 的图片能力本身基础能力齐全,但配套的权限、文件管理、生命周期清理都需要上层业务补齐。这套方案可以直接嵌入前面的笔记草稿、RDB存储流程,形成「文字+图片」完整富文本笔记链路,是笔记类应用非常核心的一环。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。