使用组件化封装实现笔记卡片复用与状态隔离
【摘要】 前言在开发笔记类应用时,首页通常会渲染大量笔记卡片。如果直接在页面内写卡片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')
}
}
关键问题与避坑
- 不要在子组件内部直接修改@Param参数
@Param是单向传入,直接修改会触发警告,收藏这类状态变更,必须通过事件抛给父组件,父组件修改数据源后驱动刷新,符合单向数据流。 - LazyForEach的key必须稳定唯一
使用笔记id作为key,不要用数组下标,否则滚动复用时会出现卡片内容错乱、收藏状态串掉。 - 大量卡片渲染时,
@ComponentV2相比旧版@Component
减少多余的状态订阅,列表滑动时GC压力更小,适合笔记这种长列表业务。 - 样式统一收口在组件内部
圆角、阴影、内边距全部封装在卡片里,后续想要全局换卡片样式,只修改这一处即可,不需要改动每一处调用地方。
扩展方向
- 给卡片增加长按菜单(置顶、删除、分享),继续追加
@Event回调 - 增加骨架屏版本的NoteCardSkeleton组件,网络加载时占位
- 配合之前的RDB持久化、离线同步能力,卡片状态变更自动落库
小结
组件化不是简单的“复制粘贴抽UI”,核心是数据、UI、事件解耦。笔记卡片作为高频复用单元,抽成独立组件之后,首页代码可读性大幅提升,也方便多人协作开发,同时天然适配懒加载瀑布流,是笔记类应用架构里很基础但很重要的一步。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)