《不想上班》× HarmonyOS 7.0:一个打工人 App 的原生开发实录(系列预告篇)

本文是「不想上班」鸿蒙技术系列的开篇预告。App 从立项之初就基于 HarmonyOS 7.0(API 26)进行全新原生开发——文本搜图、图像超分、平行视界等一批 7.0 新特性,都是“生而逢时”地长在架构里的。文中提到的每一个功能点,后续都会有一篇独立的技术详解文章;本文只做“菜单”。


一、引言:一个“不想上班”的 App,为什么要押注鸿蒙 7.0

在这里插入图片描述

先自我介绍一下。《不想上班》是一款为打工人开发的鸿蒙原生应用——秒级工资显示、内置 100+ 品牌的快乐水记录、待办、加油充电记录、文件密码保险箱、番茄钟、愿望清单、劳动法百科……40+ 个页面,加上首页 40+ 个自定义功能卡片,覆盖了从“工位摸鱼”到“提桶跑路”的全场景。

App 的定位很情绪化,但技术追求一点也不发疯。项目从第一行代码起就长在 HarmonyOS 7.0 上:targetSdk 直接锁定 26.0.0(HarmonyOS 7.0),整个项目接入了 24 个系统 Kit,从 AI 视觉到多模态感知,从安全存储到服务卡片,基本把鸿蒙的“技能树”点了一遍。

为什么这么卷?因为鸿蒙从 5.0 到 7.0 一路走来,不是修修补补,而是实打实的生产力跃迁:

  • 端侧 AI 能力全面开放:文本搜图、图像超分、文字识别、语音识别全部端侧运行,不用自建服务、不花一分钱推理费用,数据不出设备;
  • 交互范式升级:闪控球、智感握姿这些酷炫能力,三方应用可以直接调用;
  • 一多体验闭环:从直板机到阔折叠,断点体系 + 栅格布局 + 平行视界让一套代码跑遍所有形态。

下面按章节展开。每讲一个特性,我们都会给出项目中的真实代码片段和踩坑心得。


二、鸿蒙 7.0 新特性实践

2.1 文本搜图:用一句话把日志图片“搜”出来(CoreVisionKit · textSearchImage)

这是什么:HarmonyOS 7.0(API 26)新增的端侧图文检索能力。把图片插入图片库后,输入一句自然语言描述(比如“团建聚餐的照片”),系统返回匹配的图片路径和相似度。纯端侧推理,无网络、无权限、无隐私焦虑。

我们的场景:工作日志模块支持配图,时间一长图片就“石沉大海”。接入文本搜图后,全局搜索里输入“白板上的架构图”,相关日志图片直接命中——相当于让 AI 替你整理相册。

核心实现(摘自 utils/TextSearchImageUtil.ets):

import { textSearchImage } from '@kit.CoreVisionKit';

// 把日志图片插入系统侧图片库(scope 用于业务隔离,本项目固定 'worklog')
await textSearchImage.insertImage({
  imagePath: '/data/storage/el2/base/haps/entry/files/worklog_images/1024/cover.jpg',
  scope: 'worklog',
});

// 文本搜图:返回图片路径 + 相似度 [-1,1]
const results = await textSearchImage.search({ query: '团建聚餐', scope: 'worklog' });

踩坑实录(下一篇的干货预告):

  • imagePath 限 1–128 字符且必须是沙箱绝对路径;query 不支持纯数字/纯字母;
  • 同一特性不支持并发调用,并发会直接返回“系统繁忙”——我们用一条 FIFO 串行队列把所有系统调用排队执行;
  • 错误码 1013100003(模型能力更新)意味着旧特征全部失效,需要清库重建索引——我们做成了幂等的后台对账机制;
  • textSearchImage 是系统服务级单例,生命周期管理要“懒 init、不 release”,避免引用计数泄漏。

2.2 图像超分:老照片一键高清(CoreVisionKit · imageSuperResolution)

这是什么:API 26 新增的端侧图像超分辨率能力,ImageSRAnalyzer 在提高图像质量的同时,将像素同步放大四倍。NPU 加速,画质肉眼可见地“支棱起来”。

我们的场景:图片预览页加了“高清化”按钮。聊天记录里的压缩图、多年前的老截图,一键超分后直接从“马赛克考古现场”变身“4K 修复版”。

能力探测与创建(摘自 pages/PicturePreviewPage.ets):

import { imageSuperResolution } from '@kit.CoreVisionKit';

// 设备超分能力探测:API 版本 + 系统能力双重拦截
// (图像超分为 API 26 新增,低版本上模块未定义,直接访问属性会 crash)
private probeSrSupport(): void {
  if (getSdkApiVersion() < 26 || !canIUse('SystemCapability.AI.Vision.VisionBase')) {
    this.srSupported = false;
    return;
  }
  // 不支持超分的设备 create 抛 801;创建成功则复用,避免二次开销
  imageSuperResolution.ImageSRAnalyzer.create()
    .then((analyzer: imageSuperResolution.ImageSRAnalyzer) => {
      this.srAnalyzer = analyzer;
    })
    .catch(() => { this.srSupported = false; });
}

细节控福利:超分过程我们配了一个粒子扫描线动画(ImageItemView),让“AI 处理中”不再是一个干巴巴的 loading——体验上像给照片做了一次“激光焕肤”。切图时超分结果按下标缓存,来回翻页不重复计算。
在这里插入图片描述

2.3 Grid 不同尺寸元素的拖动换位:工位卡片随心摆(ForEach.onMove)

这是什么:API 26 起,官方在 ForEach.onMove 上支持了 Grid 元素的原生拖拽换位。配合 Grid.editMode + supportAnimation,系统自动处理拖拽浮起、占位交换和落位动画。

我们的场景:首页是 17 种可自定义的“电子工位卡片”(工资进度、番茄钟、喝水量、词云球等)。不同尺寸卡片(1×1、2×2、2×1)混排拖拽顺滑,用户长按卡片即可拖动换位,搭建自己的专属工位。

能力门控(摘自 common/Constants.ets):

/**
 * 首页卡片原生拖拽编辑能力(ForEach.onMove 官方标注自 API 26 起支持)。
 * 不支持编辑的设备(API < 26):隐藏「+」入口,避免用户加了卡片却没法管理
 */
export const NATIVE_DRAG_ENABLED: boolean = deviceInfo.sdkApiVersion >= 26;

官方示例的原生换位逻辑(onMove 回调):

// 拖拽松手时,被拖拽项落位与拖拽前不同则触发:from 起始索引,to 目标索引
.onMove((from: number, to: number) => {
  let tmp = this.arr.splice(from, 1);   // 从原位置取出被拖拽元素
  this.arr.splice(to, 0, tmp[0]);       // 插入目标位置
}, {
  onLongPress: (index) => { /* 长按浮起 */ },
  onDragStart: (index) => { /* 开始拖拽 */ },
  onMoveThrough: (from, to) => { /* 拖拽过程中持续触发 */ },
})

不同尺寸元素的占位推挤、跨尺寸交换的弹性细节,将在后续详解文章中展开。
在这里插入图片描述


三、多端适配:一套代码,从直板机到阔折叠全都要

3.1 断点体系:xs–xl 五档 + 纵向断点

鸿蒙“一多”(一次开发、多端部署)的核心是断点。我们的 BreakpointSystem 是全 App 唯一标准实现,横向五档断点覆盖所有形态:

断点宽度(vp)典型设备
xs[0, 320)超小窗口(自由多窗)
sm[320, 600)直板机竖屏、折叠外屏
md[600, 840)折叠内屏展开、小平板
lg[840, 1440)平板横屏、三折展开
xl[1440, +∞)超宽窗口 / PC 2in1

实现上没有自己算宽度,而是以 UIContext.getWindowWidthBreakpoint() 为事实源,监听 windowSizeChange 与 systemDensityChange(DPI 变化),状态用 @ObservedV2 + @Trace 驱动 UI 精准刷新(摘自 utils/BreakpointSystem.ets):

@ObservedV2
export class BreakpointState {
  @Trace value: BreakpointTypeEnum = BreakpointTypeEnum.SM;
  @Trace vertical: VerticalBreakpointEnum = VerticalBreakpointEnum.LG;

  /** md 及以上(折叠展开态、平板竖屏) */
  get isWide(): boolean {
    return this.value === BreakpointTypeEnum.MD
      || this.value === BreakpointTypeEnum.LG
      || this.value === BreakpointTypeEnum.XL;
  }

  /** 近方屏(阔折叠外屏、部分展开态) */
  get isSquare(): boolean { return this.vertical === VerticalBreakpointEnum.MD; }
}

3.2 阔折叠专项:纵向断点解决“方屏尴尬”

阔折叠(外折形态折叠屏)有个独特痛点:外屏是近方形,传统“手机竖屏 / 平板横屏”的二维思维直接失效。官方设计规范也明确指出:阔折叠屏幕比直板机更宽、更矮,信息显示效率需要专门的设计补偿。

我们的解法是引入纵向断点(按高宽比 height/width 三档):

  • < 0.8:横向窗口(平板横屏)
  • 0.8 ~ 1.2:方屏——正是阔折叠外屏,isSquare 为 true
  • ≥ 1.2:纵向窗口(直板机竖屏)

首页工位卡片在 isSquare 时自动切换列数与卡片跨行跨列配置;onboarding 页用 GridCol 的 span/offset 做栅格重排(8 列布局 + 偏移 2),保证方屏上不出现“内容被拉伸变形”的惨案。展开内屏(md/lg)则走双栏内容布局。

3.3 折叠态切换的无感体验

折叠/展开瞬间窗口尺寸突变,windowSizeChange 监听 + 断点自动重算让布局即时切换;配合 canIUse('SystemCapability.Window.SessionManager') 门控的 DPI 监听,系统字号调整时布局也能自适应。整个过程用户零感知——这才是“一多”该有的样子。

3.4 平行视界:宽屏设备的“分栏外挂”

这是什么:鸿蒙针对折叠屏展开态、平板等宽屏设备提供的系统级分栏显示技术——同一个应用在一个窗口里同时显示两个页面,“一级页面靠左、二级页面靠右”,默认 1:1 平分(平板上还支持 1:2 / 2:1 比例)。对应用而言,它最有吸引力的地方在于:不需要自己写分栏布局代码,系统按标准路由规则自动完成分栏编排;从 API 23 起还支持开发者自配置分栏规则。

在《不想上班》中的应用:本 App 全量页面基于 HdsNavigation + route_map 的 Navigation 路由体系构建,天然契合平行视界的“导航模式”。在折叠屏展开态或平板上:

  • 劳动法模块:左侧法条列表、右侧法条详情,查劳动法像翻书一样丝滑;
  • 工作日志:左侧日志列表、右侧日志编辑,边翻历史边写今天的吐槽;
  • 全局搜索:左侧搜索结果、右侧命中详情,“搜什么看什么”一步到位。

也就是说,40+ 个页面零分栏改造代码,直接获得宽屏双栏体验——选对架构(Navigation),系统级能力就是白送的。
在这里插入图片描述


四、其他鸿蒙特性:把系统能力用出花

4.1 闪控球:番茄钟的“贴身管家”(ArkUI · floatingBall)

这是什么:系统级悬浮球能力。应用可在任意界面上方显示一个小球,点击可唤回应用,支持动态更新标题、内容与背景色。

我们的场景:番茄钟切到后台、用户去其他应用时,闪控球悬浮在屏幕边缘,实时显示 倒计时 + 阶段标签(专注/休息),背景色随阶段变色。点击小球直接跳回番茄钟页面——“上班的仪式感,从一颗球开始”。

核心实现(摘自 model/PomodoroDataManager.ets):

import { floatingBall } from '@kit.ArkUI';

// 懒创建控制器 + 注册点击/状态回调
const config: floatingBall.FloatingBallConfiguration = {
  context: this.context as common.UIAbilityContext,
};
this.ballController = await floatingBall.create(config);
this.ballController.on('click', this.ballClickCallback);        // 点击唤回
this.ballController.on('stateChange', this.ballStateCallback);  // 系统侧停止同步状态

// 构造显示参数:倒计时 + 阶段标签 + 随阶段变色
const params: floatingBall.FloatingBallParams = {
  template: floatingBall.FloatingBallTemplate.NORMAL,
  title: this.formatBallTitle(),        // "24:59"
  content: this.getPhaseLabel(),        // "专注中"
  backgroundColor: this.getBallBackgroundColor(),
};
await this.ballController.startFloatingBall(params);

踩坑点:restoreMainWindow 在应用已在前台时会报错,需静默忽略;权限 USE_FLOAT_BALL 必须声明。

4.2 智感握姿:悬浮按钮会“看人下菜”(MultimodalAwarenessKit · motion)

这是什么:系统通过传感器实时识别握持手(左/右/双手/未握持),应用据此把高频操作按钮移到拇指舒适区。官方最佳实践明确其价值:降低操作吃力感与误触率。

我们的场景:全局悬浮按钮(FAB)默认在右下角;检测到左手握持时,自动带动画“漂移”到左下角。大屏单手党狂喜——这功能属于“用过就回不去”系列。

实现(摘自 model/GripDetectionManager.ets + views/FabButton.ets):

import { motion } from '@kit.MultimodalAwarenessKit';

// 支持性判断:API 20+ 且具备多模态感知能力(模拟器不支持)
isSupported(): boolean {
  return deviceInfo.sdkApiVersion >= 20
    && canIUse('SystemCapability.MultimodalAwareness.Motion');
}

// 订阅握持手变化;仅左手/右手更新状态(双手/未握持保持上次位置,防止按钮乱跳)
motion.on('holdingHandChanged', (status: motion.HoldingHandStatus) => {
  if (status === motion.HoldingHandStatus.LEFT_HAND_HELD) {
    this.updateFabSide(true);   // FAB 漂移到左下角
  } else if (status === motion.HoldingHandStatus.RIGHT_HAND_HELD) {
    this.updateFabSide(false);  // 漂移回右下角
  }
});

注意:需要 ohos.permission.DETECT_GESTURE 权限;官方约束——设备需在“设置-系统”中存在“智感握姿”开关,否则返回 801;保护壳厚度不能超过 3mm。

4.3 沉浸光感:HDS 组件的“氛围感大师”(UIDesignKit · hdsMaterial)

这是什么:从 6.1.0(23) 版本开始,HDS 组件新增沉浸光感材质能力——滚动内容从组件背后掠过时,呈现系统级模糊 + 光影效果,且系统会根据设备算力动态调整材质效果,实现性能与显示效果的最佳平衡。

我们的场景:底部悬浮页签和标题栏全接了自适应沉浸光感,内容滚动时页签背后是流动的光影——“别人家的 App 氛围感,我们直接焊死在框架层”。

实现(摘自 pages/Index.ets):

import { hdsMaterial, HdsNavigation, HdsTabs } from '@kit.UIDesignKit';

HdsTabs()
  .barFloatingStyle({
    barBottomMargin: 28,
    // 沉浸光感:ADAPTIVE 类型 + ADAPTIVE 等级 = 材质效果由系统按设备性能自适应
    systemMaterialEffect: {
      materialType: hdsMaterial.MaterialType.ADAPTIVE,
      materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE,
    }
  })
  .titleBar({
    titleBarStyleOptions: {
      enableScrollEffect: true,
      scrollEffectType: ScrollEffectType.GRADIENT_BLUR, // 滚动渐变模糊
      blurEffectiveStartOffset: LengthMetrics.vp(0),
      blurEffectiveEndOffset: LengthMetrics.vp(20),
      systemMaterialEffect: {
        materialType: hdsMaterial.MaterialType.ADAPTIVE,
        materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE,
      },
    },
  })

4.4 密码安全存储:把主密钥焊死在 TEE 里(AssetStoreKit + UserAuthenticationKit + CryptoArchitectureKit)

这是什么:关键资产存储服务(Asset Store Kit)提供用户短敏感数据(密码、Token、银行卡号)的系统级安全存储,以密文形式存放在系统侧,可与用户认证(生物识别)联动。

我们的场景:密码保险箱 + 卡证保险箱。架构是三层纵深防御:

  1. 主密钥(32 字节随机串)存入系统 TEE 关键资产,要求设备必须设置锁屏密码;
  2. 业务数据用主密钥经 cryptoFramework 派生密钥 AES 加密落库;
  3. 访问门禁走 UserAuthenticationKit 生物识别,且空闲 5 分钟自动上锁。
import { asset } from '@kit.AssetStoreKit';

// 主密钥入 TEE:必须已设锁屏密码 + 首次解锁后可读
const attrs: asset.AssetMap = new Map();
attrs.set(asset.Tag.SECRET, keyBytes);
attrs.set(asset.Tag.ALIAS, aliasBytes());
attrs.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED);
attrs.set(asset.Tag.REQUIRE_PASSWORD_SET, true);
await asset.add(attrs);

配合一个小细节:全局搜索会明确提示“保险箱内容不参与搜索”——安全这件事,防的就是自己手滑。

4.5 文字识别:端侧 OCR 白嫖指南(CoreVisionKit · textRecognition)

拍照提取工资条、合同关键条款,直接调系统端侧 OCR:支持中/英/日/韩/繁体,无权限要求、无调用次数限制。我们的封装做了引用计数生命周期管理,init/release 配对不漏(摘自 utils/OcrUtil.ets):

const visionInfo: textRecognition.VisionInfo = { pixelMap: pixelMap };
const config: textRecognition.TextRecognitionConfiguration = {
  isDirectionDetectionSupported: true, // 方向检测:歪着拍的图也能认
};
const result = await textRecognition.recognizeText(visionInfo, config);
// 按识别行拼接,保留版面行结构

4.6 卡证识别:拍照即建档(VisionKit)

银行卡、身份证“咔嚓”一拍,自动框选、裁切、识别结构化字段并入库到卡证保险箱;文档扫描则用于合同/证明文件的边缘检测与去阴影,扫描件直接存档。基于 VisionKit 的 CardScanner / DocumentScanner,交互全部系统级接管,我们只负责把识别结果“稳稳落库”。

4.7 语音识别:说出来的工作日志(CoreSpeechKit)

通勤路上动口不动手,语音转文字记日志。端侧 ASR、短语音 ≤60s / 长语音 ≤8h 两档模式,按子句回调渐进上屏(蹦字预览 → 子句定稿追加)。引擎必须随页面退出释放,否则报 1002200006 占用错误——这是官方文档都会让你踩的坑。

4.8 服务卡片:把工位搬到桌面(FormKit)

这是什么:服务卡片是鸿蒙桌面上的“应用切片”——不用点进 App,卡片本身就能展示实时内容、响应点击直达指定页面。《不想上班》一共上架了 7 张全动态 ArkTS 卡片,规格从 2×2 到 4×4 全覆盖:

卡片规格内容
实时薪资卡2×2工资每分钟实时跳动
今日待办卡2×2今日事项速览,点卡片直达 Todo
愿望进度卡2×2存钱/目标进度条
今日全景卡2×4当日工资 + 待办 + 日程一屏尽览
今日日历卡2×4月历视角的班表
今日工位卡4×4大尺寸综合工位面板
照片墙卡4×4日志图片轮播

刷新机制(含金量所在,摘自 entryformability/UnWorkFormAbility.ets):

7 张卡均为动态卡片(isDynamic: true),由独立于主进程的 FormExtensionAbility 供数,四个生命周期回调各司其职:

  • onAddForm:同步返回默认样式首帧(背景/文字/主题色),避免加卡瞬间白屏,真实快照由异步推送补齐;
  • onUpdateForm:30 分钟定时校准(updateDuration: 1),兜住跨天、跨月、卡片冻结期间的数据漂移;
  • onFormEvent:薪资卡挂了 TextClock 分钟心跳(tick 节流 55 秒),实现分钟级主动刷新——桌面上的工资数字跟着时间一起跳,打工人的“心跳”上桌面了;
  • onRemoveForm:formId 注销,不浪费一次推送。

所有推送统一走 WidgetPushManager.pushFormById(快照 + 样式 + 背景图文件描述符三合一);FormExtension 进程首次数据就绪后还会 pushAllOnce 全量兜底,修复系统重启后 formImages 内存映射失联导致的背景图悬空——这种边角问题,官方文档可不会替你踩。

另外每张卡都支持样式自定义(背景图 / 文字色 / 主题色透传到卡片渲染),formConfigAbility 一键跳回应用内的“卡片工坊”配置。桌面上 7 张卡,张张都是你的赛博工位皮肤。
在这里插入图片描述

4.9 一句话带过的其他能力

  • 系统分享/文件预览/PDF:ShareKit、PreviewKit、PDFKit 打通日志导出全链路;
  • 状态管理 V2:@ObservedV2/@Trace/@ComponentV2 全家桶,精细粒度刷新,性能上“遥遥领先”于 V1 的粗放模式。

五、动画和交互:细节才是灵魂

5.1 一镜到底:词球的全屏变形记(geometryTransition)

在这里插入图片描述

心情卡片上的关键词词球,点击后从卡片内平滑变形铺满全屏——这就是“一镜到底”转场。实现核心是 geometryTransition:转场前后两个组件绑定同一 id,系统自动衔接宽高、位置与透明度过渡(摘自 views/homewidgets/MoodCard.ets):

// 卡片内词球 与 全屏词球 绑定同一 id,转场时系统自动做空间衔接
.geometryTransition('keyword_ball_oneshot')
.transition(TransitionEffect.opacity(0.99)) // 配合 transition 保证离场组件不被立即析构

官方最佳实践:必须配合 transition 使用,否则 out 组件离场时会被立即析构,动画可能无法呈现;还要确保绑定节点的宽高动画不跳变。

5.2 实时薪资的数字翻动:打工人的“心跳”(RollingNumberView)

“今日已赚 ¥86.42”每秒都在涨——老虎机式逐位滚动。实现思路很有意思:

  • 数值拆成“前缀 + 千分位整数 + 小数”的字符序列,数字位是 0–9 竖排滚动列,¥ , . 静态展示;
  • 每个数字列固定高窗口 + clip,内部一条 "0\n1\n…\n9" 的多行 Text,用 translate 滚动 + .animation 补间;
  • 循环滚动:条带铺两圈,@Monitor('cell.ch') 里取模算最少前进步数,9→0 也恒向前滚,滚过第二圈后动画结束瞬时回绕(duration=0,视觉无感);
  • 响应式核心是 @ObservedV2 + @Trace 的原地变更:切勿用 ForEach key 承载数字值——ForEach 是纯 key diff,key 不变时子组件不会刷新,数字会“钉死不动”(这是真实踩过的坑)。

5.3 词球动画:数学课代表的浪漫

关键词 3D 词球是纯手写球面坐标投影:每个词有 (x, y, z) 坐标,定时器驱动旋转矩阵变换,z 值映射透明度与缩放——远小近大、远暗近亮,手势可拖拽控制旋转角速度。加上全屏一镜到底,就是“工位上的多巴胺发生器”。

5.4 悬浮按钮:会漂移的 FAB

FAB 不只是个按钮:它结合智感握姿按握持手左右漂移(带绕行动画,不是瞬移),支持展开子操作菜单,压感反馈走 vibrator 震动。位置变化的补间曲线、与页签避让的安全区计算,细节都在系列文章里展开。


六、总结

《不想上班》从第一行代码起就长在 HarmonyOS 7.0 上,一句话总结:情绪价值拉满,技术含量超纲。24 个 Kit、5 档断点、7 张卡片、40+ 页面,每一个特性都不是“能跑就行”,而是抠到错误码、抠到帧率的落地。

本文提到的每一个功能点——文本搜图、图像超分、Grid 拖动换位、阔折叠与平行视界适配、闪控球、智感握姿、沉浸光感、密码保险箱、服务卡片、一镜到底动画……后续都会陆续推出独立的技术详解文章,把源码和踩坑细节一一摊开。

打工人的命也是命,摸鱼的 App 也要是顶配。鸿蒙的能力清单,就是《不想上班》的功能清单——我们不见不散。


Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐