鸿蒙学习实战之路-STG系列(5/11)-守护策略管理-添加与修改策略

朋友们,前四篇我们学习了 Screen Time Guard Kit 的基本概念、开发准备、用户授权管理和应用选择页。今天这篇我们就来学习守护策略管理的核心功能 - 添加和修改策略 o(╯□╰)o

守护策略就像"家长的家规",规定孩子在什么时间可以使用哪些应用、使用多长时间等。有了策略,系统就能自动执行这些规则了~

今天这篇,我会手把手带你实现守护策略的添加和修改功能,全程不超过5分钟(不含你测试的时间)~

一、什么是守护策略?

守护策略(Guard Strategy)是 Screen Time Guard Kit 的核心功能,用于定义屏幕时间管控的规则。

1. 策略的组成部分

一个完整的守护策略包含以下几个部分:

组成部分 说明 示例
策略名称 策略的唯一标识 “游戏管控”、“学习时段”
时间策略 定义时间规则 起止时间、总时长、共享时长
应用信息 要管控的应用列表 游戏应用、娱乐应用
限制类型 限制的方式 禁止清单、允许清单
重复规则 周期性执行 周一到周五

2. 三种时间策略类型

类型 说明 适用场景
起止时间策略 在指定时间段内生效 工作日 9:00-18:00 禁止游戏
总时长策略 从当前开始的总时长限制 每天游戏不超过 2 小时
共享时长策略 多个应用共享总时长 游戏和视频总共不超过 3 小时

🥦 西兰花小贴士:
起止时间策略就像"营业时间",总时长策略就像"额度限制",共享时长策略就像"家庭共享预算"~

二、添加守护策略

添加守护策略就像制定家规,一旦制定好,系统就会自动执行。

1. 业务流程

添加守护策略的流程就像这样:

应用调用添加策略接口
    ↓
系统检查应用是否有权限、用户是否授权
    ↓
如果没有权限 → 抛出错误码
如果有权限 → 解析策略参数
    ↓
检查策略是否有效、是否重复、数量是否超限
    ↓
如果策略无效 → 抛出错误码
如果策略有效 → 保存到本地数据库
    ↓
策略添加成功

2. 核心接口

添加策略的接口:

接口名 说明
addGuardStrategy(guardStrategy) 添加屏幕时间管控策略

3. 策略参数详解

GuardStrategy 参数说明
interface GuardStrategy {
  name: string;              // 策略名称,唯一标识
  timeStrategy: TimeStrategy; // 时间策略
  appInfo: AppInfo;          // 应用信息
  appRestrictionType: RestrictionType; // 限制类型
}
TimeStrategy 参数说明
interface TimeStrategy {
  type: TimeStrategyType;    // 时间策略类型
  startTime?: string;        // 开始时间,格式 "HH:mm"
  endTime?: string;          // 结束时间,格式 "HH:mm"
  duration?: number;         // 总时长,单位秒
  repeat?: number[];         // 重复规则,[1-7] 表示周一到周日
}
TimeStrategyType 枚举值
枚举值 说明
START_END_TIME_TYPE 起止时间策略
TOTAL_DURATION_TYPE 总时长策略
SHARED_DURATION_TYPE 共享时长策略
RestrictionType 枚举值
枚举值 说明
BLOCKLIST_TYPE 禁止清单,对选中的应用进行限制
ALLOWLIST_TYPE 允许清单,对选中的应用以外的应用进行限制

🥦 西兰花小贴士:
禁止清单就像"黑名单",允许清单就像"白名单"。黑名单里的人不能进,白名单里的人才能进,其他人都不能进~

4. 开发步骤

步骤 1: 导入相关模块
import { guardService, appPicker } from '@kit.ScreenTimeGuardKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
步骤 2: 添加起止时间策略
@Entry
@Component
struct AddStrategyDemo {
  @State selectedTokens: string[] = [];

  build() {
    Column() {
      Text('添加守护策略演示')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 40 })

      Button('1. 选择要管控的应用')
        .onClick(async () => {
          try {
            const tokens = await appPicker.startAppPicker(
              this.getUIContext().getHostContext() as common.UIAbilityContext,
              { appTokens: [] }
            );
            this.selectedTokens = tokens;
            hilog.info(0x0000, 'AddStrategyDemo', 
              `selected tokens: ${JSON.stringify(tokens)}`);
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'AddStrategyDemo',
              `startAppPicker failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 30 })
        .width('80%')

      Button('2. 添加起止时间策略')
        .onClick(async () => {
          if (this.selectedTokens.length === 0) {
            hilog.warn(0x0000, 'AddStrategyDemo', '请先选择应用');
            return;
          }

          try {
            // 创建起止时间策略
            const time: guardService.TimeStrategy = {
              type: guardService.TimeStrategyType.START_END_TIME_TYPE,
              startTime: '09:00',  // 早上 9 点
              endTime: '18:00',    // 下午 6 点
              repeat: [1, 2, 3, 4, 5] // 周一到周五
            };

            const appInfo: guardService.AppInfo = {
              appTokens: this.selectedTokens
            };

            const strategy: guardService.GuardStrategy = {
              name: '工作日游戏管控',  // 策略名称
              timeStrategy: time,
              appInfo: appInfo,
              appRestrictionType: guardService.RestrictionType.BLOCKLIST_TYPE
            };

            await guardService.addGuardStrategy(strategy);
            hilog.info(0x0000, 'AddStrategyDemo', 'addGuardStrategy succeeded');
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'AddStrategyDemo',
              `addGuardStrategy failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 10 })
        .width('80%')

      Button('3. 添加总时长策略')
        .onClick(async () => {
          if (this.selectedTokens.length === 0) {
            hilog.warn(0x0000, 'AddStrategyDemo', '请先选择应用');
            return;
          }

          try {
            // 创建总时长策略
            const time: guardService.TimeStrategy = {
              type: guardService.TimeStrategyType.TOTAL_DURATION_TYPE,
              duration: 7200 // 2 小时 = 7200 秒
            };

            const appInfo: guardService.AppInfo = {
              appTokens: this.selectedTokens
            };

            const strategy: guardService.GuardStrategy = {
              name: '每天游戏2小时',  // 策略名称
              timeStrategy: time,
              appInfo: appInfo,
              appRestrictionType: guardService.RestrictionType.BLOCKLIST_TYPE
            };

            await guardService.addGuardStrategy(strategy);
            hilog.info(0x0000, 'AddStrategyDemo', 'addGuardStrategy succeeded');
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'AddStrategyDemo',
              `addGuardStrategy failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 10 })
        .width('80%')
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

🥦 西兰花小贴士:
重复规则使用数字数组,[1,2,3,4,5] 表示周一到周五,[1,2,3,4,5,6,7] 表示每天~

三、修改守护策略

修改守护策略就像修改家规,规则变了,系统也会跟着变。

1. 业务流程

修改守护策略的流程就像这样:

应用调用修改策略接口
    ↓
系统检查应用是否有权限、用户是否授权
    ↓
如果没有权限 → 抛出错误码
如果有权限 → 解析策略参数
    ↓
检查策略是否有效、是否存在
    ↓
如果策略不存在 → 抛出错误码
如果策略存在 → 更新到本地数据库
    ↓
策略修改成功

2. 核心接口

修改策略的接口:

接口名 说明
updateGuardStrategy(strategyName, guardStrategy) 修改屏幕时间管控策略

🥦 西兰花警告:
修改策略时,策略名称必须和已存在的策略名称一致,否则会抛出"策略不存在"的错误~

3. 开发步骤

@Entry
@Component
struct UpdateStrategyDemo {
  @State selectedTokens: string[] = [];

  build() {
    Column() {
      Text('修改守护策略演示')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 40 })

      Button('1. 选择要管控的应用')
        .onClick(async () => {
          try {
            const tokens = await appPicker.startAppPicker(
              this.getUIContext().getHostContext() as common.UIAbilityContext,
              { appTokens: [] }
            );
            this.selectedTokens = tokens;
            hilog.info(0x0000, 'UpdateStrategyDemo', 
              `selected tokens: ${JSON.stringify(tokens)}`);
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'UpdateStrategyDemo',
              `startAppPicker failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 30 })
        .width('80%')

      Button('2. 修改起止时间策略')
        .onClick(async () => {
          if (this.selectedTokens.length === 0) {
            hilog.warn(0x0000, 'UpdateStrategyDemo', '请先选择应用');
            return;
          }

          try {
            // 创建新的时间策略
            const time: guardService.TimeStrategy = {
              type: guardService.TimeStrategyType.START_END_TIME_TYPE,
              startTime: '08:00',  // 改为早上 8 点
              endTime: '20:00',    // 改为晚上 8 点
              repeat: [1, 2, 3, 4, 5, 6, 7] // 改为每天
            };

            const appInfo: guardService.AppInfo = {
              appTokens: this.selectedTokens
            };

            const strategy: guardService.GuardStrategy = {
              name: '工作日游戏管控',  // 策略名称必须和已存在的一致
              timeStrategy: time,
              appInfo: appInfo,
              appRestrictionType: guardService.RestrictionType.BLOCKLIST_TYPE
            };

            await guardService.updateGuardStrategy('工作日游戏管控', strategy);
            hilog.info(0x0000, 'UpdateStrategyDemo', 'updateGuardStrategy succeeded');
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'UpdateStrategyDemo',
              `updateGuardStrategy failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 10 })
        .width('80%')
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

四、完整示例代码

下面是一个完整的示例,展示了如何实现守护策略的添加和修改功能:

import { guardService, appPicker } from '@kit.ScreenTimeGuardKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { preferences } from '@kit.ArkData';

@Entry
@Component
struct StrategyManagerDemo {
  @State selectedTokens: string[] = [];
  @State strategyName: string = '';
  @State strategyType: string = '';
  @State strategyDesc: string = '';

  async selectApps() {
    try {
      const tokens = await appPicker.startAppPicker(
        this.getUIContext().getHostContext() as common.UIAbilityContext,
        { appTokens: [] }
      );
      this.selectedTokens = tokens;
      hilog.info(0x0000, 'StrategyManagerDemo', 
        `selected tokens: ${JSON.stringify(tokens)}`);
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      hilog.error(0x0000, 'StrategyManagerDemo',
        `startAppPicker failed with error code: ${code}, message: ${message}`);
    }
  }

  async addStartEndTimeStrategy() {
    if (this.selectedTokens.length === 0) {
      hilog.warn(0x0000, 'StrategyManagerDemo', '请先选择应用');
      return;
    }

    try {
      const time: guardService.TimeStrategy = {
        type: guardService.TimeStrategyType.START_END_TIME_TYPE,
        startTime: '09:00',
        endTime: '18:00',
        repeat: [1, 2, 3, 4, 5]
      };

      const appInfo: guardService.AppInfo = {
        appTokens: this.selectedTokens
      };

      const strategy: guardService.GuardStrategy = {
        name: '工作日游戏管控',
        timeStrategy: time,
        appInfo: appInfo,
        appRestrictionType: guardService.RestrictionType.BLOCKLIST_TYPE
      };

      await guardService.addGuardStrategy(strategy);
      this.strategyName = '工作日游戏管控';
      this.strategyType = '起止时间策略';
      this.strategyDesc = '周一到周五 9:00-18:00';
      hilog.info(0x0000, 'StrategyManagerDemo', 'addGuardStrategy succeeded');
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      hilog.error(0x0000, 'StrategyManagerDemo',
        `addGuardStrategy failed with error code: ${code}, message: ${message}`);
    }
  }

  async addTotalDurationStrategy() {
    if (this.selectedTokens.length === 0) {
      hilog.warn(0x0000, 'StrategyManagerDemo', '请先选择应用');
      return;
    }

    try {
      const time: guardService.TimeStrategy = {
        type: guardService.TimeStrategyType.TOTAL_DURATION_TYPE,
        duration: 7200 // 2 小时
      };

      const appInfo: guardService.AppInfo = {
        appTokens: this.selectedTokens
      };

      const strategy: guardService.GuardStrategy = {
        name: '每天游戏2小时',
        timeStrategy: time,
        appInfo: appInfo,
        appRestrictionType: guardService.RestrictionType.BLOCKLIST_TYPE
      };

      await guardService.addGuardStrategy(strategy);
      this.strategyName = '每天游戏2小时';
      this.strategyType = '总时长策略';
      this.strategyDesc = '每天最多 2 小时';
      hilog.info(0x0000, 'StrategyManagerDemo', 'addGuardStrategy succeeded');
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      hilog.error(0x0000, 'StrategyManagerDemo',
        `addGuardStrategy failed with error code: ${code}, message: ${message}`);
    }
  }

  async updateStrategy() {
    if (this.selectedTokens.length === 0 || !this.strategyName) {
      hilog.warn(0x0000, 'StrategyManagerDemo', '请先选择应用或策略');
      return;
    }

    try {
      const time: guardService.TimeStrategy = {
        type: guardService.TimeStrategyType.START_END_TIME_TYPE,
        startTime: '08:00',
        endTime: '20:00',
        repeat: [1, 2, 3, 4, 5, 6, 7]
      };

      const appInfo: guardService.AppInfo = {
        appTokens: this.selectedTokens
      };

      const strategy: guardService.GuardStrategy = {
        name: this.strategyName,
        timeStrategy: time,
        appInfo: appInfo,
        appRestrictionType: guardService.RestrictionType.BLOCKLIST_TYPE
      };

      await guardService.updateGuardStrategy(this.strategyName, strategy);
      this.strategyDesc = '每天 8:00-20:00';
      hilog.info(0x0000, 'StrategyManagerDemo', 'updateGuardStrategy succeeded');
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      hilog.error(0x0000, 'StrategyManagerDemo',
        `updateGuardStrategy failed with error code: ${code}, message: ${message}`);
    }
  }

  build() {
    Column() {
      Text('守护策略管理演示')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 40 })

      Text('当前策略: ' + this.strategyName)
        .fontSize(16)
        .margin({ top: 20 })

      Text('策略类型: ' + this.strategyType)
        .fontSize(14)
        .margin({ top: 5 })

      Text('策略描述: ' + this.strategyDesc)
        .fontSize(14)
        .margin({ top: 5 })

      Button('1. 选择要管控的应用')
        .onClick(() => this.selectApps())
        .margin({ top: 30 })
        .width('80%')

      Button('2. 添加起止时间策略')
        .onClick(() => this.addStartEndTimeStrategy())
        .margin({ top: 10 })
        .width('80%')

      Button('3. 添加总时长策略')
        .onClick(() => this.addTotalDurationStrategy())
        .margin({ top: 10 })
        .width('80%')

      Button('4. 修改当前策略')
        .onClick(() => this.updateStrategy())
        .margin({ top: 10 })
        .width('80%')
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

五、注意事项

🥦 西兰花警告:

  1. 必须先获得用户授权: 添加和修改策略之前,必须先请求用户授权,否则会报错
  2. 策略名称必须唯一: 不能有两个同名的策略,否则会报错
  3. 修改策略名称要一致: 修改策略时,策略名称必须和已存在的策略名称一致
  4. 时间格式要正确: 起止时间格式必须是 “HH:mm”,比如 “09:00”、“18:00”
  5. 重复规则要合理: 重复规则使用 [1-7] 的数字数组,代表周一到周日
  6. 策略数量有限制: 每个应用的策略数量有限制,不能无限添加
  7. 策略需要启动才能生效: 添加或修改策略后,需要调用启动策略接口才能生效

六、文档资源

官方文档链接:

七、总结

守护策略是 Screen Time Guard Kit 的核心功能,通过添加和修改策略,可以灵活地管控用户的应用使用行为。

核心要点:

  1. 守护策略包含策略名称、时间策略、应用信息、限制类型等
  2. 有三种时间策略类型:起止时间、总时长、共享时长
  3. 修改策略时,策略名称必须和已存在的策略名称一致
  4. 策略添加或修改后,需要启动才能生效
  5. 每个应用的策略数量有限制

守护策略就像"家长的家规",制定好了,系统就会自动执行。修改家规,系统也会跟着变 o(╯□╰)o

下一步行动

建议你:

  1. 先实现基本的应用选择功能
  2. 实现起止时间策略的添加功能
  3. 实现总时长策略的添加功能
  4. 实现策略修改功能
  5. 结合查询和启动功能,实现完整的策略管理流程

记住,不教理论,只给你能跑的代码和避坑指南! _

我是盐焗西兰花,
不教理论,只给你能跑的代码和避坑指南。
下期见!🥦

# harmonyos # 学习 # 服务器
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

Flutter 三方库 front_end — 揭秘鸿蒙应用编译过程中的源码解析与内核转换内幕，实现鸿蒙深度适配下的自研工具链内核实战全解

当你点击 DevEco Studio 的“运行”按钮，将 Flutter 代码部署到鸿蒙（OpenHarmony）真机时，幕后发生了一场复杂的“代码进化”。在这场进化的第一阶段，源代码需要经历解析、语义分析，并转变为一种中间表示格式（Kernel）。front_end(通常指或相关的 CFE - Common Front End) 是 Dart 编译器架构中掌管“解析与验证”的核心大脑。在 Flu

avatar 人工智能6S服务平台
cover

Flutter 三方库 dart_style — 鸿蒙应用全方位代码格式化与规范治理神器，实现鸿蒙深度适配下的工程化整洁代码规范全实战

avatar 人工智能6S服务平台
cover

Flutter 三方库 dispose_scope — 鸿蒙应用开发中的精细化资源释放与内存管理利器，实现鸿蒙深度适配下的生命周期管理实战（适配鸿蒙 HarmonyOS Next ohos）

avatar 人工智能6S服务平台