HarmonyOS 闪控窗开发复盘：从入口触发到窗口状态管理的完整落地【鸿蒙心迹】

这篇不是功能介绍稿，而是一篇真实开发复盘。表面上看，闪控窗只是"弹出一个小窗"；真做起来，入口触发、窗口创建、状态切换、快捷动作、回流同步，每一段都藏着工程细节。

一、最开始我以为这只是一个"小浮窗"需求

第一次接到闪控窗需求时，我的判断很朴素：业务希望用户在不完全离开当前任务的情况下，快速处理一个轻量动作。比如新建待办、查看一条信息、做一次快捷确认，或者记录一个临时想法。

从产品描述上看，它不像完整页面那么重，也不像通知栏交互那么弱，处在一个很微妙的中间地带。

我当时以为事情会比较简单：

提供一个入口；
点击后拉起小窗；
小窗里放几个按钮；
操作完关闭就行。

真正开始做以后，我很快发现，闪控窗麻烦的地方，从来不是"窗能不能弹出来"，而是下面这些问题：

从哪里触发才合理。应用内按钮、通知、联动场景、手势入口，触发源不同，准备的数据就不同。
窗口是什么状态启动的。一上来是紧凑态，还是直接展开态？不同业务的默认选择并不一样。
动作做完以后怎么反馈。用户在小窗里点了一次"收藏"或者"新建待办"，主页面是否要同步？需不需要提示？
小窗和完整应用怎么配合。闪控窗不是替代页面，而是帮用户少跳一步。什么时候该留在窗里，什么时候该回应用，是要设计的。

也就是说，闪控窗真正难的，不是 UI 形态，而是它横跨了"入口、上下文、窗口、动作、回流"五个环节。

如果只盯着窗口本身，很容易做出一个看着像、用起来别扭的 Demo。后面我就是按这条链路，把这个需求重新拆了一遍。

二、先别急着写页面，先把能力链路画出来

我现在做这种"系统能力 + 业务结合"的功能，有一个习惯：先画链路图。

因为这类需求最怕一头扎进页面开发，写了半天才发现，窗口状态和业务上下文根本没打通，动作回调也没有落点。

这次闪控窗，我最后收敛成了一条 6 段式流程：用户触发入口 → 业务上下文准备 → 闪控窗创建与展示 → 紧凑态 / 展开态切换 → 快捷动作处理 → 页面回流与状态同步。

这个图里，我最想强调的是两个判断。

1. 闪控窗不是一个"单页面功能"

很多人第一反应会把它理解成一个特殊页面。但它实际更像一个穿插在业务中的轻交互容器。它既要有页面内容，又不能完全按普通页面的节奏走。

2. 闪控窗不是"弹出来就结束"

如果窗只是展示，不处理动作，那它价值不大。真正有用的闪控窗，一定要能承接轻操作，然后把结果回传回去。这一步才决定它是不是一个真实可用的能力。

所以我给自己定的目标很明确：不是做一个能弹出来的小窗，而是做一条完整可落地的轻交互链路。

三、入口设计不对，后面全都会别扭

闪控窗的第一步，是触发入口。

这个环节看起来最不技术，实际上很影响后续实现。因为不同入口决定了两件事：

小窗启动时带什么数据；
用户当下的操作意图是什么。

举个很实际的例子。

如果入口来自应用首页按钮，用户通常还处在"浏览 / 决策"阶段，小窗更适合做快捷创建、快速记录这类动作。

如果入口来自通知提醒，用户大概率已经有一个明确目标，比如处理待办、确认状态，那小窗就应该直接进入对应业务，而不是让用户在里面再选一次。

再比如入口来自手势或某个联动场景，这时候上下文可能更少，窗口内容就不能依赖太多未准备好的数据。

所以我后来没有把入口统一粗暴处理，而是先定义了一层启动参数，明确这次拉起闪控窗，到底带来了什么业务上下文。

这段代码解决的就是这个问题：根据不同入口，构造一份可消费的启动配置。

arkts 复制代码

export type FlashWindowLaunchOptions = {
  source: 'home_button' | 'notification' | 'gesture' | 'scene_link'
  bizType: 'todo' | 'focus' | 'record' | 'quick_view'
  contentId?: string
  title?: string
  initialMode: 'compact' | 'expanded'
  payload?: Record<string, Object>
}

function buildLaunchOptions(source: string): FlashWindowLaunchOptions {
  if (source === 'notification') {
    return {
      source: 'notification',
      bizType: 'todo',
      title: '待处理任务',
      initialMode: 'expanded',
      payload: { fromNotice: true }
    }
  }
  return {
    source: 'home_button',
    bizType: 'focus',
    title: '专注计时',
    initialMode: 'compact'
  }
}

这类代码的价值，不在于语法本身，而在于它让后面的创建逻辑不再拍脑袋。窗口拉起之前，至少已经知道：从哪里来、要做什么、默认什么形态打开。

四、真正进入创建阶段时，先解决"窗能稳定创建"这件事

当入口和上下文准备好了，才轮到窗口创建。

这一段最容易出现一种错觉：只要 API 调通，就等于完成了。实际不是。创建阶段至少要回答三个问题：

窗口类型和参数怎么配；
失败时如何兜底；
首帧内容如何尽快显示。

我的实现思路是，把创建过程单独包成一个方法，并显式维护创建状态、窗口 ID 和窗口当前形态。这样做不是为了"代码好看"，而是为了后面好调试。

arkts 复制代码

@Entry
@Component
struct FlashWindowPage {
  @State isExpanded: boolean = false
  @State flashWindowId: number = -1
  @State isCreating: boolean = false
  @State message: string = ''

  async createFlashWindow(): Promise<void> {
    try {
      this.isCreating = true
      const context = getContext(this) as UIAbilityContext
      const want: Want = {
        bundleName: 'com.example.flashfocus',
        abilityName: 'FocusWindowAbility',
        parameters: {
          mode: this.isExpanded ? 'expanded' : 'compact'
        }
      }

      this.flashWindowId = await window.createWindow(context, want, {
        windowType: window.WindowType.FLASH_WINDOW,
        designWidth: 320,
        designHeight: 200,
        autoDestroy: true
      })

      this.message = `闪窗创建成功，窗口ID: ${this.flashWindowId}`
    } catch (err) {
      const e = err as BusinessError
      this.message = `创建闪窗失败: ${e.message}`
    } finally {
      this.isCreating = false
    }
  }
}

这段代码解决了三个很现实的问题。

第一，显式状态管理。创建过程不再是一个黑盒动作，而是可以知道当前是否正在创建、创建成功没有、成功后的窗口 ID 是多少。

第二，失败可见。很多时候不是功能一定会失败，而是你在开发阶段看不到失败发生在哪里。把错误信息落下来，后面排查会省很多时间。

第三，默认形态可控。窗口是先以紧凑态出现，还是直接以展开态出现，最好在创建前就明确，而不是等弹出来以后再补处理。

五、闪控窗一旦出来，最关键的不是样子，而是状态管理

我觉得这次开发里，真正的核心不在创建，而在状态管理。

因为闪控窗和普通页面最大的差异，就在于它会在不同形态之间切换。最典型的就是：

紧凑态：信息简、动作少、打断弱；
展开态：信息更完整、动作更多、停留时间更长。

这两个状态，不只是尺寸不同。它们其实对应了不同的使用语境。

紧凑态更适合：

快速查看；
一步完成轻操作；
不打断用户当前主任务。

展开态更适合：

需要输入内容；
需要连续操作；
需要展示更多上下文。

所以后面我没有把"展开 / 收起"当成简单的按钮切换，而是把它当成一个明确的状态流转。

为了让这个切换更可控，我单独写了一个状态切换方法：

arkts 复制代码

enum FlashMode {
  COMPACT = 'compact',
  EXPANDED = 'expanded'
}

@State currentMode: FlashMode = FlashMode.COMPACT

function switchMode(nextMode: FlashMode) {
  if (this.currentMode === nextMode) {
    return
  }
  this.currentMode = nextMode
  this.isExpanded = nextMode === FlashMode.EXPANDED
  this.message = nextMode === FlashMode.EXPANDED
    ? '已切换为展开态'
    : '已切换为收起态'
}

这段逻辑看着不复杂，但它把"形态切换"从 UI 事件里抽离出来了。后面无论是按钮点击、手势触发，还是系统策略触发，都能共用同一套收口逻辑。

这件事在工程上特别重要。因为一旦切换逻辑散落在各个按钮、各个事件回调里，后期只要你多加一种触发方式，行为就容易不一致。

六、真正的体验差异，往往体现在紧凑态和展开态分别承载了什么

光有切换机制还不够，还要想清楚：不同状态下到底给用户看什么。

我这次做的是一个"专注助手"的业务载体，比较适合拿来说明闪控窗。

在紧凑态里，我尽量让内容足够收敛：

一眼能看到当前任务；
一眼能看到剩余时间；
最多 3 到 4 个高频动作；
不出现需要长时间停留处理的内容。

最终效果大致是这样：

这个紧凑态里，我只保留了最关键的信息：当前是否专注中、任务标题、剩余时间和几个快捷按钮。它的目标不是把事情做完，而是帮用户快速接一手。

而在展开态里，我明显放开了内容密度：

展示完整任务说明；
展示当前专注进度；
给出更多动作，比如继续、暂停、标记完成、返回应用；
补充今日进度、快捷记录、时间线等辅助信息。

这两张图放在一起看，你会更容易理解为什么我一直强调：闪控窗不是一个页面缩小版，而是不同状态下承载不同层级的信息。

紧凑态的重点是"不打断"；展开态的重点是"可继续处理"。如果两个状态只是尺寸不同、内容一模一样，那设计价值其实没有发挥出来。

七、快捷动作能不能成立，决定这个窗到底是不是"有用"

很多闪控窗 Demo 都会做一个问题：窗有了、形态有了，但里面的动作很空。

比如按钮很多，真正点下去以后要么只是 toast，要么最后还是把用户完整拉回应用。那用户很快就会意识到：这个窗只是看起来方便，实际上没替我省操作。

所以这次我在动作设计上，给自己定了一个原则：闪控窗里的动作，必须优先是能在窗内闭环的轻操作。

比如：

新建一条待办；
记录一句语音；
快速截图识别；
标记完成；
收藏、复制、分享这类轻动作。

而对于需要更完整上下文的操作，比如大量编辑、复杂配置、长表单输入，我更倾向于把它引导回应用，而不是硬塞在小窗里。

这里的关键不是"能不能做"，而是"做了以后顺不顺"。

所以动作层我会明确区分两类：

1. 窗内闭环动作

这类动作执行后，直接更新状态，给用户一个明确反馈即可。

2. 应用跳转动作

这类动作不强行在窗内做完，而是把必要上下文带回主应用，交给完整页面处理。

这样做以后，闪控窗的角色就很清楚：它是一个轻交互加速器，不是完整业务页面的替身。

八、真正容易踩坑的，是动作做完以后怎么"回流"

这个问题我觉得很多人一开始会低估。

闪控窗不是孤立存在的。用户在里面做的事，最后通常都要反映到主页面、列表、卡片甚至其他设备上。

如果你只把窗里的动作做完，但没有把结果同步回去，就会出现一种很尴尬的体验：

用户在窗里标记完成了；
回到应用以后，列表还显示进行中；
用户会怀疑自己刚才到底有没有操作成功。

所以我后来专门加了一层状态回流策略，核心就做三件事：

回传操作结果：告诉调用方刚才做了什么。
同步页面状态：让主页面列表、统计信息跟着更新。
保留关键行为日志：后面便于调试和行为分析。

这也是我在开发时为什么一直盯着日志的原因。因为闪控窗这类能力，不少 bug 都不是"窗没弹出来"，而是"动作做了但主页面没感知到"。

开发阶段，我基本就是一边看代码，一边看模拟器里的状态切换和底部日志输出，确认创建、切换、动作、销毁这几条链有没有全部走通。

这张 DevEco 界面对我来说，不只是一个截图，而是整个联调过程的真实缩影：

左侧看项目结构有没有拆干净；
中间看创建与状态逻辑是否收口；
右侧看模拟器里的交互是否符合预期；
底部日志看每一步行为有没有被准确记录。

九、这次开发里，我最后总结出的几个工程判断

做完这一版闪控窗，我觉得最值得留下来的，不是某一段 API 代码，而是下面几个工程判断。

1. 先定入口，再定窗口

不要反过来。一上来先做小窗样式，后面会发现不同入口需要不同上下文，最后窗里内容越改越乱。

2. 先收口状态，再扩展交互

紧凑态、展开态、关闭态之间的切换，一定要有统一的收口逻辑。否则后面按钮一多、手势一多，行为很快就不一致。

3. 轻操作尽量窗内闭环

这类能力存在的意义，就是减少跳转成本。如果点一个按钮最后还得进完整页面，那这个窗的价值就被削弱了。

4. 重操作不要硬塞进窗里

闪控窗不是万能容器。复杂输入、长流程编辑、信息密度很高的操作，最好还是回主页面完成。

5. 回流同步一定要提前设计

别等功能快做完了才想"主页面怎么更新"。如果状态同步是后补的，后面很容易出现数据和视图不一致的问题。

十、本文小记

回头看这次开发，我最大的感受是：闪控窗这个能力，真正难的地方不在"会不会弹"，而在于你有没有把它放到合适的位置上。

它既不能太重，重了就失去"轻交互"的意义；也不能太轻，轻到只剩一个壳子，用户就感觉不到价值。

对我来说，这次比较重要的收获有两个。

第一，是对"轻交互闭环"的理解更清楚了。一个好用的闪控窗，应该是让用户少跳一步、少想一步、少等一步。

第二，是对"窗口状态管理"这件事更谨慎了。紧凑态、展开态、关闭态看着只是形态变化，实际上背后对应的是不同的信息密度和不同的操作语义。

如果后面继续往下做，我会优先补两块：

一块是更细的状态策略，比如不同业务的默认展开规则、切换动画和保活策略；
一块是更完整的动作回流，比如和任务中心、统计页、跨设备同步的数据联动。

这篇文章先把第一阶段的工程落地复盘到这里。它不是概念介绍，也不是单纯的 API 试用，而是一次从入口触发、窗口创建、状态切换到动作回流的完整走通。

如果你也在做类似需求，我的建议很简单：别把闪控窗当成一个"会浮起来的小页面"，把它当成一条轻交互链路去设计，很多问题会一下子清楚很多。