文章导读

• ArkTS 严格模式下，用 class + 默认值 承载业务实体，比到处写对象字面量更稳。
• Article、Equipment、Player、SportEvent 共用一套建模约束，页面层只管渲染和交互。
• 本地 Resource 与远程 URL 并存，能同时兜住离线内置数据和联网抓取数据。

页面效果

这一层的好坏，最终会直接反映到页面是否稳定。球员动态页要能直接读取头像、简介、点赞数和关注态；资讯详情页要能顺着正文块类型渲染文本、单图和图集，而不是在页面里到处做空判断。

实战拆解

很多项目在刚开始时会把模型写得很轻，只保留几个必填字段，等到页面增多后再补字段、补默认值、补兜底逻辑。这样短期看起来快，后面却会把判断逻辑摊到每个页面和组件里。羽球联盟没有走这条路，而是先在 common 层把几个核心实体的边界定清楚。

这里最关键的不是“字段多不多”，而是字段的职责要稳定。比如 Article 既要服务本地内置资讯，也要服务联网抓取资讯，所以 cover: Resource 和 coverUrl?: string 会同时存在；ContentBlock 则把正文拆成 text / image / gallery 三种块，让详情页可以按块分发渲染，不需要把正文当成一大段字符串硬塞进页面。

同样的思路也体现在 Player、SportEvent 这些实体上。球员动态页直接消费头像、简介、统计字段；赛事列表直接消费赛事名称、时间、状态和赛程数组。模型先约束清楚，页面层就能保持很薄。

关键代码

export class ContentBlock {
  type: ContentBlockType = 'text';
  text?: string;
  image?: Resource;
  images?: Resource[];
  caption?: string;
  imageUrl?: string;
  imageUrls?: string[];
}

export class Article {
  id: string = '';
  title: string = '';
  cover: Resource = $r('app.media.startIcon');
  tag: string = '';
  tagColor: string = '#0F7B5F';
  author: string = '';
  publishTime: string = '';
  readCount: number = 0;
  summary: string = '';
  content: ContentBlock[] = [];
  related?: RelatedVideo[];
  category: 'event' | 'equipment' | 'skill' = 'event';
  coverUrl?: string;
  source?: string;
  url?: string;
}

这段代码真正解决的问题有两个：第一，页面拿到模型后可以立即渲染，默认值把大量 undefined 分支提前消化掉；第二，本地资源和远程内容共存时，不必为了适配某一类数据源去重写整套页面逻辑。

取舍分析

这里更像是在“模型集中约束”和“页面自由发挥”之间做取舍。模型层把默认值、类型和兜底字段先定义好，会多写一些代码，但它换来的收益很直接：详情页、卡片组件、收藏页、历史页都能复用同一批实体，不会每多一个页面就复制一份轻微不同的数据结构。

Resource 和 URL 双字段看上去有点重复，其实是在承认真实数据来源并不统一。本地演示数据需要直接引用资源，联网抓取又可能只给封面链接，统一塞成一个字段反而会让渲染层更混乱。把差异收口在模型里，比把差异扩散到每个页面里更可控。

设计落点

• 业务实体全部落到 common 层，组件和页面只消费实体，不重新发明结构。
• 默认值优先在模型层解决，避免页面渲染时充满空值分支。
• ContentBlock 负责描述正文块类型，详情页只负责根据类型分发 UI。
• 本地资源与远程链接并存时，优先把兼容逻辑收在模型里，而不是散落到多个页面。

易踩坑

• 不要把函数、UIContext 或运行时对象塞进实体模型，否则持久化和跨模块传递都会变得别扭。
• 不要为了“纯粹”只保留一种封面字段。真实项目里，本地资源和远程数据并存是常态。
• ContentBlock 一旦开始支持图集、视频、引用块，最好继续沿用块级建模，不要退回长字符串拼接。

验证方式

• 给 Article 增加一个可选字段，确认老数据仍能渲染，不需要回填全部 mock 数据。
• 分别打开本地资讯详情页和联网资讯详情页，确认封面和正文块都能被兜住。
• 在球员动态页和赛事页同时使用实体模型，检查统计字段、头像和状态标签是否正常显示。

参考资料

• [学习 ArkTS 语言（官方文档）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-more-cases-V5)
• [资源分类与访问（官方文档）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/resource-categories-and-access)

小结

这篇最值得带走的不是某个字段名字，而是建模顺序：先把实体边界、默认值和资源来源说明白，再去写页面。这样做的好处是，后续不管继续加收藏、历史、搜索还是远程抓取，页面层都能保持稳定，复杂度不会一路外溢。