摘要

闪控窗（小艺建议/情景智能类悬浮窗）能盖在其他 App 之上、可常驻、可监听交互，属于系统里的高敏感能力。本文以一次真实的审核打回经历为起点，围绕权限申请、隐私声明、最小权限、关闭路径四件事，给出 HarmonyOS 闪控窗合规落地的完整方案：module.json5 声明与运行时申请分离、when: inuse 按需申请、悬浮窗常驻关闭按钮、设置页统一撤销入口，以及打包前的权限自检脚本。文中逐段拆解四段可复用代码的设计取舍与易错点，并附合规流程图与踩坑清单，帮助读者一次过审。

关键词：闪控窗、悬浮窗权限、SYSTEM_FLOAT_WINDOW、合规审核、HarmonyOS

目录

• 一、背景与痛点
• 二、环境与能力规格
• 三、核心代码（可复用骨架）
• 四、代码深入分析
  • 4.1 声明层：module.json5 为什么只写"声明"
  • 4.2 申请层：requestPermissionsFromUser 的返回值陷阱
  • 4.3 承载层：悬浮窗本体的生命周期管理
  • 4.4 管理层：设置页入口与上架自检
  • 4.5 四条链路的协作关系
• 五、合规流程与关键节点
• 六、运行效果与踩坑
• 七、小结与适用边界
• 八、实战清单（可直接抄）
• 九、总结

一、背景与痛点

上篇讲了闪控窗（小艺建议/情景智能类悬浮窗）的能力接入与场景设计，但悬浮窗是系统里的"高敏感能力"——它能盖在别的 App 上、能常驻、能监听交互。我第一次提交就被审核打回，理由是"悬浮窗权限申请无明确用途说明 + 未提供关闭入口"。这才意识到：闪控窗能不能过审，七成看合规，三成看技术。

本文把权限申请、隐私声明、最小权限、关闭路径这四件事讲清，避免重蹈覆辙。

二、环境与能力规格

维度	规格
能力归属	闪控窗 / 悬浮窗能力，需 ohos.permission.SYSTEM_FLOAT_WINDOW
声明位置	module.json5 的 requestPermissions
隐私要求	必须在隐私声明中告知用途、数据范围、用户可撤销
关闭入口	设置页 + 悬浮窗自身常驻关闭按钮
运行位置	端侧，敏感数据不出设备

核心认知：悬浮窗权限是 system_basic 级敏感权限，不能"静默常开"，必须可感知、可关闭、可解释。

三、核心代码（可复用骨架）

// module.json5
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.SYSTEM_FLOAT_WINDOW",
        "reason": "$string:float_window_reason",
        "usedScene": { "abilities": ["MainAbility"], "when": "inuse" }
      }
    ]
  }
}

// 运行时再向用户解释并申请
import { abilityAccessCtrl } from '@kit.AbilityKit';
async function ensureFloatPermission(ctx: Context) {
  const atManager = abilityAccessCtrl.createAtManager();
  const grant = await atManager.requestPermissionsFromUser(ctx, ['ohos.permission.SYSTEM_FLOAT_WINDOW']);
  if (!grant.authResults[0]) {
    // 引导去设置页，而非反复弹窗骚扰
    openSettings('app_float_window');
  }
}

// 悬浮窗本体：常驻关闭按钮 + 状态自检
import { window } from '@kit.ArkUI';

@Entry
@Component
struct FloatCard {
  private win?: window.Window;

  aboutToAppear() {
    // 拿到悬浮窗实例，便于后续关闭
    window.getLastWindow(getContext(this)).then((w) => { this.win = w; });
  }

  // 关闭悬浮窗：先销毁 UI，再释放窗口，避免残留
  private closeFloat() {
    this.win?.destroyWindow().catch((e: Error) => {
      console.error(`destroy float window failed: ${e.message}`);
    });
  }

  build() {
    Column({ space: 8 }) {
      Text('快捷控制卡片').fontSize(14)
      Button('关闭')
        .fontSize(12)
        .onClick(() => this.closeFloat())
    }
    .padding(12)
    .borderRadius(12)
    .backgroundColor('#F1F3F5')
  }
}

// 设置页统一管理入口：用户可随时撤销悬浮窗授权
import { common } from '@kit.AbilityKit';
import { bundleManager } from '@kit.AbilityKit';

function openSettings(scene: string) {
  const ctx = getContext() as common.UIAbilityContext;
  // 跳转到本应用的权限/悬浮窗管理页，而非系统总设置
  ctx.startAbility({
    bundleName: 'com.ohos.settings',
    abilityName: 'com.ohos.settings.MainAbility',
    parameters: { scene, bundleName: ctx.abilityInfo.bundleName }
  });
}

// 上架前自检：权限是否已声明、是否可撤销
async function checkFloatCompliance() {
  const info = await bundleManager.getBundleInfoForSelf(
    bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_REQUESTED_PERMISSION
  );
  const declared = info.reqPermissionDetails.some(
    (p) => p.name === 'ohos.permission.SYSTEM_FLOAT_WINDOW'
  );
  if (!declared) {
    console.warn('悬浮窗权限未在 module.json5 声明，审核必被驳回');
  }
}

四、代码深入分析

上一节的四段代码是"能跑"的骨架，但真正决定过审与稳定性的，是每一行背后的设计取舍。下面按「声明 → 申请 → 承载 → 管理」四条链路逐段拆解。

4.1 声明层：module.json5 为什么只写"声明"

{
  "name": "ohos.permission.SYSTEM_FLOAT_WINDOW",
  "reason": "$string:float_window_reason",
  "usedScene": { "abilities": ["MainAbility"], "when": "inuse" }
}

• reason 必须走资源引用：直接写中文字符串在多语言环境下会失效，且审核侧要求可追溯，$string: 引用便于统一维护与本地化。
• when: "inuse" 是合规红线：它表示"仅在使用中申请"，对应审核口径里的"按需"。写成 always 等于自证"常驻监听"，是打回高发项。
• abilities 要收敛：只声明真正需要悬浮窗的 Ability，声明一堆再实际只用一个是典型的"超范围申请"。
• 声明 ≠ 授权：这里只是"告诉系统我要用"，用户是否给，取决于下一节的运行时申请。

4.2 申请层：requestPermissionsFromUser 的返回值陷阱

const grant = await atManager.requestPermissionsFromUser(ctx, ['ohos.permission.SYSTEM_FLOAT_WINDOW']);
if (!grant.authResults[0]) {
  openSettings('app_float_window');
}

• authResults 是数组，且与入参顺序一一对应：多权限申请时不能只看 [0]，应按索引或按 permission 字段匹配，否则会误判。
• 0 表示拒绝，-1 表示权限不存在/未声明：两者处理方式不同——前者引导设置页，后者说明 module.json5 漏配，属于开发期就该暴露的问题。
• 拒绝后不要立刻二次弹窗：系统对短时间内重复申请有节流，反复调用不仅无效，还会被判定"骚扰式引导"。正确做法是跳设置页，把决定权交还用户。
• ctx 必须是 UIAbilityContext：用 getContext() 拿到的类型不对会直接抛错，这是新手最常见的运行时崩溃点。

4.3 承载层：悬浮窗本体的生命周期管理

aboutToAppear() {
  window.getLastWindow(getContext(this)).then((w) => { this.win = w; });
}

private closeFloat() {
  this.win?.destroyWindow().catch((e: Error) => {
    console.error(`destroy float window failed: ${e.message}`);
  });
}

• getLastWindow 是异步的：aboutToAppear 里拿到的 win 可能还没赋值，若在 build 阶段就依赖它做判断，需要加空值保护（代码里的 this.win?. 正是为此）。
• 关闭顺序不能反：先销毁 UI 再释放窗口，若先 destroyWindow 而组件仍在渲染，会出现"窗口已销毁但组件还在画"的残留报错。
• destroyWindow 要 catch：窗口可能已被系统回收（如用户从最近任务划掉），此时销毁会抛异常，不捕获会污染日志、干扰问题定位。
• 关闭按钮必须常驻：不要做成"点击卡片才出现"的悬浮按钮，审核明确要求"用户可随时关闭"，隐藏式关闭等同于没有。

4.4 管理层：设置页入口与上架自检

const declared = info.reqPermissionDetails.some(
  (p) => p.name === 'ohos.permission.SYSTEM_FLOAT_WINDOW'
);

• GET_BUNDLE_INFO_WITH_REQUESTED_PERMISSION 这个 flag 不能省：不带它，reqPermissionDetails 是空数组，自检会永远"通过"，形成假阴性。
• 自检要放进打包流水线：人工点一遍容易漏，把它挂到 CI 的构建后置步骤，漏声明直接让构建失败，比审核打回便宜得多。
• startAbility 跳设置页要带 bundleName：只传 scene 会落到系统总设置首页，用户找不到本应用开关，体验断点就在这里。
• 撤销路径要闭环：设置页关掉后，悬浮窗应能感知并自动收起，否则会出现"权限已撤销但窗口还挂着"的不一致状态。

4.5 四条链路的协作关系

四层不是孤立的：声明层决定"能不能申请"，申请层决定"用户给不给"，承载层决定"给了之后稳不稳"，管理层决定"能不能收回"。任何一层缺失，链路就断在审核那一关。

五、合规流程与关键节点

从申请到上架，闪控窗的合规链路可以拆成五个节点，任一节点缺失都会被打回：

关键节点说明：

• 需求确认：先回答"这个悬浮窗解决了什么用户主动诉求"，答不上来就不该做。
• 声明与申请分离：module.json5 只负责"声明"，运行时 requestPermissionsFromUser 才真正"申请"，两者缺一不可。
• 拒绝路径：用户拒绝后必须给出口，而不是循环弹窗，这是审核最常抓的点。
• 自检对账：用 checkFloatCompliance 这类脚本在打包前跑一遍，比事后返工便宜得多。

六、运行效果与踩坑

• 踩坑 1：权限 reason 写"提升体验"被驳回。 必须写具体用途，如"在锁屏外显快捷控制卡片"。改具体后过审。- 踩坑 2：悬浮窗没有关闭按钮。 用户无法关闭=投诉高风险。务必在窗体内放常驻关闭 + 设置页统一管理。
• 踩坑 3：后台仍频繁拉起悬浮窗。 被判定"过度打扰"。只在用户主动场景下拉起，闲时休眠。
• 踩坑 4：隐私声明未覆盖悬浮窗数据。 补充"本窗仅展示本地状态，不上传"后合规。
• 效果： 重提后一次过审，悬浮窗日活留存反而提升，因为用户"知道它在干嘛、能关掉"。

七、小结与适用边界

闪控窗是强能力也是高风险点，合规先行：具体用途声明、可关闭、最小权限、隐私对齐。适合快捷控制、情景卡片；不适合无明确价值的“常驻广告类”悬浮。

八、实战清单（可直接抄）- 悬浮窗权限 SYSTEM_FLOAT_WINDOW 是敏感权限，reason 必须写具体用途（如"锁屏外显快捷控制"），写"提升体验"会被驳回。

• 悬浮窗本体必须常驻关闭按钮，设置页也要有统一管理入口，用户能随时关。
• 权限按需申请（when: inuse），别常开常驻，后台频繁拉起会被判过度打扰。
• 隐私声明单独覆盖悬浮窗的数据范围与撤销方式，声明和数据行为要一致。
• 申请被拒引导去设置页，而非反复弹窗骚扰用户。

合规不是拦路虎，而是产品的护城河。用户信你"看得见、关得掉"，才愿意长期开着用。上架前用"权限—声明—功能"三张表对账，是闪控窗类能力最快的过审捷径。把合规当产品力，闪控窗才能既强又稳，用户才敢一直开着。