使用组件化封装实现笔记卡片复用与状态隔离

举报
yd_284811271 发表于 2026/11/15 20:42:15 2026/11/15
【摘要】 前言在开发笔记类应用时,首页通常会渲染大量笔记卡片。如果直接在页面内写卡片UI,会出现代码臃肿、状态互相干扰、修改一处多处受影响的问题。基于ArkUI的自定义组件能力,我们可以把笔记卡片抽离成独立组件,实现UI复用、状态隔离、事件回调解耦,同时配合@ComponentV2新范式,拿到更稳定的内存表现,适合长列表场景。本文基于HarmonyOS NEXT,实现可复用笔记卡片组件,支持标题、摘...

前言

在开发笔记类应用时,首页通常会渲染大量笔记卡片。如果直接在页面内写卡片UI,会出现代码臃肿、状态互相干扰、修改一处多处受影响的问题。基于ArkUI的自定义组件能力,我们可以把笔记卡片抽离成独立组件,实现UI复用、状态隔离、事件回调解耦,同时配合@ComponentV2新范式,拿到更稳定的内存表现,适合长列表场景。

本文基于HarmonyOS NEXT,实现可复用笔记卡片组件,支持标题、摘要、时间、标签、收藏点击、点击跳转详情,同时解决组件实例之间状态污染问题。

方案选型说明

  • @ComponentV2:新一代自定义组件,状态管理更清晰,适合列表循环渲染大量卡片
  • @Param:外部传入只读参数,笔记原始数据由父页面传入,子组件不直接修改源数据
  • @Event:向外抛出点击、收藏事件,子组件只负责UI响应,业务逻辑交给父层处理
  • LazyForEach + 独立卡片组件:和之前的瀑布流方案搭配,减少主页面代码量

核心思路:组件只做“展示+触发回调”,不持有业务数据源,保证单向数据流。

完整代码实现

1. 笔记数据实体

// model/Note.ets
export class NoteItem {
  id: string;
  title: string;
  summary: string;
  createTime: string;
  tagList: string[];
  isCollected: boolean;

  constructor(
    id: string,
    title: string,
    summary: string,
    createTime: string,
    tagList: string[],
    isCollected: boolean
  ) {
    this.id = id;
    this.title = title;
    this.summary = summary;
    this.tagList = tagList;
    this.createTime = createTime;
    this.isCollected = isCollected;
  }
}

2. 封装笔记卡片自定义组件

// component/NoteCard.ets
import { NoteItem } from '../model/Note';

@ComponentV2
export struct NoteCard {
  @Param note: NoteItem;
  @Event onCardClick: (note: NoteItem) => void;
  @Event onCollectClick: (noteId: string, collected: boolean) => void;

  build() {
    Column() {
      Row() {
        Text(this.note.title)
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .layoutWeight(1)
          .maxLines(1)
          .textOverflow({ overflow: TextOverflow.Ellipsis })

        Image(this.note.isCollected ? $r('sys.media.ohos_ic_public_star_filled') : $r('sys.media.ohos_ic_public_star'))
          .width(20)
          .height(20)
          .fillColor(this.note.isCollected ? '#FFC107' : '#999999')
          .onClick(() => {
            this.onCollectClick(this.note.id, !this.note.isCollected);
          })
      }
      .width('100%')
      .margin({ bottom: 8 })

      Text(this.note.summary)
        .fontSize(13)
        .fontColor('#666666')
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
        .width('100%')
        .margin({ bottom: 8 })

      Row() {
        Text(this.note.createTime)
          .fontSize(11)
          .fontColor('#999999')

        Blank()

        Flex({ wrap: FlexWrap.Wrap }) {
          ForEach(this.note.tagList, (tag: string) => {
            Text(tag)
              .fontSize(10)
              .fontColor('#3366FF')
              .padding({ left: 6, right: 6, top: 2, bottom: 2 })
              .backgroundColor('#E8F0FF')
              .borderRadius(4)
              .margin({ left: 4 })
          }, (tag: string) => tag)
        }
      }
      .width('100%')
    }
    .width('100%')
    .padding(12)
    .backgroundColor('#ffffff')
    .borderRadius(12)
    .shadow({ radius: 8, color: '#1A000000', offsetX: 0, offsetY: 2 })
    .onClick(() => {
      this.onCardClick(this.note);
    })
  }
}

3. 父页面中使用卡片组件

// pages/Index.ets
import { NoteCard } from '../component/NoteCard';
import { NoteItem } from '../model/Note';
import { LazyDataSource } from '../utils/LazyDataSource';

@Entry
@ComponentV2
struct Index {
  @Local noteList: NoteItem[] = [];
  dataSource: LazyDataSource<NoteItem> = new LazyDataSource(this.noteList);

  aboutToAppear() {
    // 模拟加载笔记数据,实际可从RDB/网络读取
    this.noteList = [
      new NoteItem('1', 'HarmonyOS组件化实践', '抽离卡片组件,实现UI复用和状态隔离...', '2026-11-15', ['ArkUI', '组件化'], false),
      new NoteItem('2', '富文本图片插入踩坑记录', '沙盒文件拷贝、权限申请、RichEditor渲染图片方案...', '2026-11-14', ['RichEditor', '图片'], true),
    ];
    this.dataSource.reload(this.noteList);
  }

  // 卡片点击:跳转详情页
  handleCardClick(note: NoteItem) {
    router.pushUrl({
      url: 'pages/NoteDetail',
      params: { noteId: note.id }
    })
  }

  // 收藏状态变更,交由父层统一处理(更新数据库+刷新列表)
  handleCollectChange(noteId: string, collected: boolean) {
    const target = this.noteList.find(item => item.id === noteId);
    if (target) {
      target.isCollected = collected;
    }
    // 这里可以追加RDB更新、同步队列入队逻辑
  }

  build() {
    Scroll() {
      LazyForEach(this.dataSource, (item: NoteItem) => {
        NoteCard({
          note: item,
          onCardClick: this.handleCardClick,
          onCollectClick: this.handleCollectChange
        })
        .margin({ left: 12, right: 12, bottom: 12 })
      }, (item: NoteItem) => item.id)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}

关键问题与避坑

  1. 不要在子组件内部直接修改@Param参数@Param是单向传入,直接修改会触发警告,收藏这类状态变更,必须通过事件抛给父组件,父组件修改数据源后驱动刷新,符合单向数据流。
  2. LazyForEach的key必须稳定唯一
    使用笔记id作为key,不要用数组下标,否则滚动复用时会出现卡片内容错乱、收藏状态串掉。
  3. 大量卡片渲染时,@ComponentV2相比旧版@Component
    减少多余的状态订阅,列表滑动时GC压力更小,适合笔记这种长列表业务。
  4. 样式统一收口在组件内部
    圆角、阴影、内边距全部封装在卡片里,后续想要全局换卡片样式,只修改这一处即可,不需要改动每一处调用地方。

扩展方向

  • 给卡片增加长按菜单(置顶、删除、分享),继续追加@Event回调
  • 增加骨架屏版本的NoteCardSkeleton组件,网络加载时占位
  • 配合之前的RDB持久化、离线同步能力,卡片状态变更自动落库

小结

组件化不是简单的“复制粘贴抽UI”,核心是数据、UI、事件解耦。笔记卡片作为高频复用单元,抽成独立组件之后,首页代码可读性大幅提升,也方便多人协作开发,同时天然适配懒加载瀑布流,是笔记类应用架构里很基础但很重要的一步。

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

评论(0)

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

全部回复

上滑加载中

设置昵称

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

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

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