【共创稿事节】 HarmonyOS7 【拼词小达人】服务卡片的版面密度与取词轮换
桌面卡片只有两种尺寸,2×2 和 4×4,相差四倍的面积。这个差距不能靠同一套布局缩放解决 —— 2×2 上放不下一个 36 号字的大单词,4×4 上放三个统计数字又太空。项目为此写了两份完全独立的 ArkUI 声明,连颜色都是从零硬编码的,而取词逻辑只关心一件事:下一次刷新该给第几个词。
两份独立的声明
两个卡片文件都以 @ComponentV2 开头:
@Entry
@ComponentV2
struct ProgressWidgetCard {
@Local gradeName: string = '未选择年级';
@Local learnedCount: string = '0';
@Local masteredCount: string = '0';
@Local collectedCount: string = '0';
@Local dateStr: string = '';
@Entry
@ComponentV2
struct WordOfDayWidgetCard {
@Local wordText: string = 'Welcome';
@Local phonetic: string = '/ˈwelkəm/';
@Local meaning: string = '欢迎';
@Local category: string = '基础词汇';
@Local unitTopic: string = '开始学习';
五个 @Local 对应 formBindingData 里的五个键,键名完全一致。@ComponentV2 与主应用的 @Component 是两套状态管理:卡片侧用 @Local,主应用侧用 @State / @Prop / @StorageLink。选 V2 的原因是卡片只需要「接收绑定数据并显示」,没有任何 @Prop 传递、没有跨组件同步,V2 的 @Local 语义更贴近这个场景 —— 它就是「这个组件自己的可变状态」。
所有字段的初值都是 Welcome / 0 这类占位值。这些初值在真机上几乎看不到,因为 formBindingData 一到位就会覆盖,但它们决定了「数据键名对不上时卡片长什么样」:wordText 拼错成 wordtext,卡片就永远停在 Welcome。初值的作用相当于一个可视化的错误提示。
2×2 的三列统计
进度卡是纵向四段:标题栏、年级、三列数字、底部提示。
Column() {
// 顶部:应用标题区域
Row() {
Image($r('app.media.ic_book_learn'))
.width(16)
.height(16)
.margin({ right: 6 })
Text('拼词小达人')
.fontSize(14)
.fontWeight(FontWeight.Bold)
.fontColor('#2D3436')
.layoutWeight(1)
Text(this.dateStr)
.fontSize(10)
.fontColor('#636E72')
}
.width('100%')
.padding({ left: 12, right: 12, top: 10 })
// 年级信息
Text(this.gradeName)
.fontSize(11)
.fontColor('#4ECDC4')
.fontWeight(FontWeight.Medium)
.margin({ top: 2 })
.width('100%')
.padding({ left: 12 })
.textAlign(TextAlign.Start)
标题栏用 layoutWeight(1) 把「拼词小达人」撑开,日期被推到最右侧。年级行单独占一行,padding 只给左边 12 —— 与标题栏的左右各 12 对齐,但右侧不需要,因为文本左对齐。
三列数字是全卡的核心,结构完全对称:
Row() {
// 已学
Column() {
Image($r('app.media.ic_book_word'))
.width(18)
.height(18)
.margin({ bottom: 2 })
Text(this.learnedCount)
.fontSize(20)
.fontWeight(FontWeight.Bold)
.fontColor('#4ECDC4')
Text('已学')
.fontSize(10)
.fontColor('#636E72')
.margin({ top: 2 })
}
.layoutWeight(1)
.alignItems(HorizontalAlign.Center)
// 已掌握 / 收藏 同构
}
.width('100%')
.padding({ left: 12, right: 12, top: 10, bottom: 8 })
三个 Column 各拿 layoutWeight(1),宽度均分。每个内部是「图标 → 数字 → 标签」的竖排,数字用 20 号加粗、标签 10 号灰色。三列的颜色分别是 #4ECDC4(青绿)、#FF6B9D(粉)、#45B7D1(蓝),与主应用 AppColors 里的 MINT_GREEN / SOFT_PINK / SKY_BLUE 数值相同。
同一组颜色值在两处各写一份,是卡片不能 import 主应用常量的结果 —— widget/pages/*.ets 是独立的构建入口,form_config.json 用 src 直接指过去,它跑在自己的渲染树里。技术上可以 import ../common/Constants,但那样会把 Constants 打进卡片包,而卡片包里真正用到的只有 6 个色值。这里选了复制。
数字的字号是 20,比标题的 14 还大 —— 这是 2×2 空间下的必然选择:统计数字是这张卡唯一的信息量,字号必须压过装饰元素。
底部提示用 Blank() 顶到底:
Blank()
Row() {
Text('点击打开开始学习')
.fontSize(10)
.fontColor('#999999')
Image($r('app.media.ic_arrow_right'))
.width(10)
.height(10)
.margin({ left: 2 })
}
.margin({ bottom: 8 })
整卡挂了 onClick 拉起应用:
.onClick(() => {
postCardAction(this, {
action: 'router',
abilityName: 'EntryAbility',
params: {}
});
})
所以底部这行「点击打开开始学习」不是按钮,是提示 —— 点它和点空白处效果一样。
4×4 的单卡主体
单词卡竖排五段:标题栏、提示语、白色卡片、底部按钮、渐变底。
白色卡片是唯一有阴影的容器:

图:服务卡片在不同版面密度下的实际效果。
Column() {
// 大单词
Text(this.wordText)
.fontSize(36)
.fontWeight(FontWeight.Bold)
.fontColor('#2D3436')
// 音标
Text(this.phonetic)
.fontSize(14)
.fontColor('#4ECDC4')
.margin({ top: 6 })
// 分类标签
Row() {
Text(this.category)
.fontSize(10)
.fontColor('#4ECDC4')
.backgroundColor('#E0F7F5')
.borderRadius(10)
.padding({ left: 8, right: 8, top: 3, bottom: 3 })
}
.margin({ top: 10 })
// 释义
Text(this.meaning)
.fontSize(18)
.fontWeight(FontWeight.Medium)
.fontColor('#636E72')
.margin({ top: 12 })
.textAlign(TextAlign.Center)
}
.width('85%')
.padding({ top: 20, bottom: 20 })
.backgroundColor('#FFFFFF')
.borderRadius(20)
.shadow({
radius: 8,
color: '#1A000000',
offsetX: 0,
offsetY: 2
})
width('85%') 让白卡从外层渐变底上「浮」起来,左右各留 7.5% 的底。阴影用 #1A000000 —— 前两位 1A 是 alpha(约 10%),后六位是纯黑,radius: 8 配 offsetY: 2 是一个很轻的下投影,只负责把白卡从浅绿底上分离出来,不制造「浮起」的错觉。
四个文本元素的纵向间距靠 margin({ top: n }) 逐个指定:音标 6、标签 10、释义 12。没有用 space 参数(Column({ space: n }) 只能统一间距),因为四个元素的亲密程度不同 —— 单词和音标是一组(6),音标和标签是一组(10),标签和释义再松一点(12)。
字号梯度与 2×2 的对比:
| 元素 | 2×2 字号 | 4×4 字号 | 说明 |
|---|---|---|---|
| 应用名 | 14 粗体 | 13 粗体 | 4×4 上应用名退居次要 |
| 日期 / 单元话题 | 10 | 10 | 同类辅助信息 |
| 主数字 / 主单词 | 20 粗体 ×3 | 36 粗体 ×1 | 面积翻倍后集中到单个元素 |
| 音标 | 无 | 14 | 只在 4×4 出现 |
| 分类标签 | 无 | 10 | 只在 4×4 出现 |
| 释义 | 无 | 18 中等 | 只在 4×4 出现 |
| 底部提示 / 按钮 | 10 | 12 | 4×4 的按钮更像按钮 |
两张卡的信息密度差得很远:2×2 显示 3 个数字 + 1 个年级,4×4 显示 1 个单词 + 音标 + 分类 + 释义 + 单元话题,共 5 项。2×2 的三个数字各占约三分之一宽度,4×4 的单个单词独占 85% 白卡的整行宽度。
取词的三级兜底
buildWordOfDayData 是卡片侧唯一的「业务逻辑」,它要在一个没有页面、没有用户输入的环境里挑出一个词:
private buildWordOfDayData(): Record<string, string> {
const storage = StorageService.getInstance();
const repo = WordRepository.getInstance();
// 获取当前年级的所有单词
const versionCode: string = AppStorage.get<string>('selectedVersionCode') ?? '';
const gradeKey: string = AppStorage.get<string>('selectedGradeKey') ?? '';
let allWords: WordInfo[] = [];
if (versionCode.length > 0 && gradeKey.length > 0) {
const units = repo.getUnits(versionCode, gradeKey);
for (const unit of units) {
allWords = allWords.concat(unit.words);
}
}
第一级是「当前年级的全部单词」。getUnits 返回该年级的 UnitInfo[],逐个 concat 拼成一个大数组。concat 每次都新建数组,pep 四年级上册有 6 个单元、262 个词,这轮拼接会造 6 个中间数组。换成 push(...unit.words) 能省掉这些拷贝,但 concat 的写法读起来更直接。
第二级在候选为空时启动:
// 如果没有加载到单词,从历史记录反推
if (allWords.length === 0) {
const history: HistoryEntry[] = storage.getHistory();
for (const h of history) {
const w = repo.getWordById(h.wordId);
if (w) {
allWords.push(w);
}
}
}
allWords 为空有两种原因:AppStorage 里的 versionCode / gradeKey 是空的(用户没选过年级),或者选了但该年级下没有词。两种情况都退到历史记录 —— 用户学过哪些词,storage.getHistory() 里有最多 200 条,逐条 getWordById 换成词对象。
这条兜底路径有个隐含前提:历史记录里的 wordId 在当前词库里能找到。切教材版本后,旧版本的词 id 仍然在 allWords 表里(四份词库同时加载),所以能找到;如果词库本身被换掉,getWordById 返回 undefined,if (w) 会跳过。
第三级是硬编码:
let word: WordInfo | undefined;
if (allWords.length > 0) {
// 轮换取词
this.wordIndex = (this.wordIndex + 1) % allWords.length;
word = allWords[this.wordIndex];
}
if (!word) {
return {
'wordText': 'Welcome',
'phonetic': '/ˈwelkəm/',
'meaning': '欢迎',
'category': '基础词汇',
'unitTopic': '开始学习'
};
}
return {
'wordText': word.text,
'phonetic': word.phonetic || '/--/',
'meaning': word.meaning,
'category': word.category,
'unitTopic': word.unitTopic
};
}
三级兜底的结果覆盖了从「完全没数据」到「数据完备」的全部情况:
| 场景 | 第一级 | 第二级 | 第三级 | 卡片显示 |
|---|---|---|---|---|
| 选过年级,有词 | 命中 262 词 | 不执行 | 取一个 | 真词 |
| 选过年级,单元全空 | 0 词 | 历史反推 | 取一个 | 历史里的词 |
| 没选年级,有历史 | 0 词 | 历史反推 | 取一个 | 历史里的词 |
| 全新安装 | 0 词 | 0 词 | 命中 | Welcome / 欢迎 |
轮换是怎么步进的
this.wordIndex = (this.wordIndex + 1) % allWords.length 先自增再取模。wordIndex 初值是 0,所以第一次进这个方法取到的是下标 1,不是 0 —— 数组第一个词永远不会被选中,除非数组只有一个元素(1 % 1 = 0)。
把自增写在取值之前,好处是「同一个词不会被连续推两次」,代价是漏掉第一个。改成后置(先取 allWords[this.wordIndex] 再自增)能拿到第一个词,但连续两次调用的第二次会和第一次不同 —— 两种写法各有取舍,这里选了不需要额外判断的那种。
步进的触发点只有两个:onAddForm 里的第二次 refreshForm,和 onUpdateForm(每日 08:00 由系统触发)。按 scheduledUpdateTime: "08:00" 的设计意图,用户每天早上会看到一个新词,一天推进一格,262 个词走完一轮要 262 天。
实际的步进节奏受实例生命周期影响。wordIndex 是 FormAbility 的实例字段:
export default class FormAbility extends FormExtensionAbility {
private formMap: Map<string, string> = new Map<string, string>();
private wordIndex: number = 0;
卡片扩展进程被回收后重新拉起,wordIndex 回到 0,下一次刷新又从下标 1 开始。所以「一天一格」只在进程长期存活时成立;进程重启过,就会看到「又跳回前面某个词」。
如果要做严格的「每日一词」,得把日期算进去 —— 比如用「自首次使用以来的天数」对词数取模:
const days: number = GradeUtils.getDaysSince(firstUseDate);
const index: number = days % allWords.length;
这样同一天内不论刷新几次、进程重启几次,取到的都是同一个词,跨天才会变。当前的「每次刷新推进一格」更像是「换一个」,与 onFormEvent 里那个手动换词按钮的语义一致 —— 两者都会推进 wordIndex,区别只在触发者。
数据契约的键名
FormAbility 返回的 Record<string, string> 和卡片里的 @Local 之间靠键名对应,没有任何类型检查:
| 卡片 | 键 | 值来源 |
|---|---|---|
ProgressWidgetCard | gradeName | AppStorage 的 selectedGradeName,缺失为「未选择年级」 |
learnedCount | getLearnedCount() 转字符串 | |
masteredCount | getMasteredTotal() 转字符串 | |
collectedCount | getCollectedTotal() 转字符串 | |
dateStr | ${month}月${day}日 | |
WordOfDayWidgetCard | wordText | word.text |
phonetic | word.phonetic,空则 /--/ | |
meaning | word.meaning | |
category | word.category(解析时已兜底为「单词」) | |
unitTopic | word.unitTopic |
十个键全部是字符串。计数用 ${learned} 转成字符串而不是传数字,是因为 createFormBindingData 的对象值可以混合类型,但卡片侧统一用 string 更省事 —— 数值型在 ArkTS 卡片里要额外处理格式化,而这三个数字不需要任何格式化。
category 与 unitTopic 两个键在 4×4 卡片里出现的位置很近(分类标签在中间,单元话题在标题栏右侧),但它们的值来自不同层级:category 是词条自己的字段(88.5% 是「单词」),unitTopic 是单元级的话题(如「文具与书包」)。同一个词在同一个单元里,unitTopic 恒定而 category 可能每词不同。
unitTopic 在卡片上被裁剪到极小:fontSize(10),配一个 12×12 的书本图标,放在标题栏右端。这个位置本来可以放日期(像进度卡那样),但单词卡选了单元话题 —— 它比日期更有信息量,能告诉用户这个词属于哪个主题。
版面这一层的东西看起来琐碎,但它决定了卡片在桌面上「一眼能不能读懂」。2×2 靠三个大数字,4×4 靠一个大单词加四行辅助信息,两种密度对应两种阅读距离:瞥一眼看数字,多看一眼读单词。取词逻辑反过来服务版面 —— 三级兜底的目标不是「逻辑完备」,而是「任何时候卡片上都有一个像样的词可显示」。
更多推荐
所有评论(0)