鸿蒙学习实战之路-STG系列(6/11)-守护策略管理-查询与删除策略

朋友们,前几篇我们学习了如何添加和修改守护策略。今天这篇我们就来学习如何查询和删除守护策略 o(╯□╰)o

查询策略就像查看家规本,看看都有哪些规则。删除策略就像废除某条家规,这条规则就不再执行了~

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

---

一、查询守护策略

查询守护策略就像查看家规本,可以了解当前都有哪些管控规则。

1. 业务流程

查询守护策略的流程就像这样:

应用调用查询策略接口
    ↓
系统检查应用是否有权限、用户是否授权
    ↓
如果没有权限 → 抛出错误码
如果有权限 → 查询本地数据库
    ↓
返回该应用下的所有管控策略

2. 核心接口

查询策略的接口:

接口名	说明
queryGuardStrategies()	查询该应用下的所有管控策略

3. 开发步骤

步骤 1: 导入相关模块

import { guardService } from '@kit.ScreenTimeGuardKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

步骤 2: 查询所有策略

@Entry
@Component
struct QueryStrategyDemo {
  @State strategies: guardService.GuardStrategy[] = [];
  @State strategyCount: number = 0;

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

      Text('当前策略数量: ' + this.strategyCount)
        .fontSize(18)
        .margin({ top: 30 })

      Button('查询所有策略')
        .onClick(async () => {
          try {
            const strategies = await guardService.queryGuardStrategies();
            this.strategies = strategies;
            this.strategyCount = strategies.length;

            // 打印所有策略名称
            strategies.forEach((strategy) => {
              hilog.info(0x0000, 'QueryStrategyDemo', 
                `策略名称: ${strategy.name}`);
            });
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'QueryStrategyDemo',
              `queryGuardStrategies failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 20 })
        .width('80%')

      // 显示策略列表
      if (this.strategies.length > 0) {
        List() {
          ForEach(this.strategies, (strategy: guardService.GuardStrategy) => {
            ListItem() {
              Column() {
                Text(strategy.name)
                  .fontSize(16)
                  .fontWeight(FontWeight.Bold)
                  .margin({ top: 10 })

                Text(this.getStrategyDesc(strategy))
                  .fontSize(14)
                  .margin({ top: 5 })
                  .fontColor('#666666')
              }
              .width('100%')
              .padding(15)
              .backgroundColor('#F5F5F5')
              .borderRadius(8)
              .margin({ top: 10 })
            }
          })
        }
        .width('100%')
        .height('60%')
        .margin({ top: 20 })
      }
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }

  /**
   * 获取策略描述
   */
  getStrategyDesc(strategy: guardService.GuardStrategy): string {
    const time = strategy.timeStrategy;
    let desc = '';

    if (time.type === guardService.TimeStrategyType.START_END_TIME_TYPE) {
      desc = `${time.startTime}-${time.endTime}`;
    } else if (time.type === guardService.TimeStrategyType.TOTAL_DURATION_TYPE) {
      desc = `总时长: ${Math.floor((time.duration || 0) / 60)} 分钟`;
    } else if (time.type === guardService.TimeStrategyType.SHARED_DURATION_TYPE) {
      desc = `共享时长: ${Math.floor((time.duration || 0) / 60)} 分钟`;
    }

    const repeat = time.repeat || [];
    if (repeat.length > 0) {
      const days = repeat.map(d => ['日', '一', '二', '三', '四', '五', '六'][d - 1]).join('、');
      desc += ` 周${days}`;
    }

    return desc;
  }
}

🥦 西兰花小贴士:
查询策略可以返回所有策略的详细信息,包括策略名称、时间策略、应用信息等。你可以根据需要展示给用户~

---

二、删除守护策略

删除守护策略就像废除某条家规,这条规则就不再执行了。

1. 业务流程

删除守护策略的流程就像这样:

应用调用删除策略接口
    ↓
系统检查应用是否有权限、用户是否授权
    ↓
如果没有权限 → 抛出错误码
如果有权限 → 解析策略名称
    ↓
检查策略是否存在
    ↓
如果策略不存在 → 抛出错误码
如果策略存在 → 检查是否正在执行
    ↓
如果正在执行 → 先停止策略,再删除
如果未执行 → 直接删除
    ↓
策略删除成功

2. 核心接口

删除策略的接口:

接口名	说明
removeGuardStrategy(strategyName)	删除指定的管控策略

🥦 西兰花小贴士:
如果策略正在执行,系统会先停止策略再删除,这个过程是自动的,你不需要手动停止~

3. 开发步骤

@Entry
@Component
struct RemoveStrategyDemo {
  @State strategies: guardService.GuardStrategy[] = [];
  @State selectedStrategy: string = '';

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

      Button('1. 查询所有策略')
        .onClick(async () => {
          try {
            const strategies = await guardService.queryGuardStrategies();
            this.strategies = strategies;
            hilog.info(0x0000, 'RemoveStrategyDemo', 
              `found ${strategies.length} strategies`);
          } catch (err) {
            const message = (err as BusinessError).message;
            const code = (err as BusinessError).code;
            hilog.error(0x0000, 'RemoveStrategyDemo',
              `queryGuardStrategies failed with error code: ${code}, message: ${message}`);
          }
        })
        .margin({ top: 30 })
        .width('80%')

      // 显示策略列表
      if (this.strategies.length > 0) {
        Text('选择要删除的策略: ' + this.selectedStrategy)
          .fontSize(16)
          .margin({ top: 20 })

        List() {
          ForEach(this.strategies, (strategy: guardService.GuardStrategy) => {
            ListItem() {
              Row() {
                Text(strategy.name)
                  .fontSize(16)
                  .layoutWeight(1)

                if (this.selectedStrategy === strategy.name) {
                  Text('✓')
                    .fontSize(16)
                    .fontColor('#00FF00')
                }
              }
              .width('100%')
              .padding(15)
              .backgroundColor(
                this.selectedStrategy === strategy.name ? '#E8F5E9' : '#F5F5F5'
              )
              .borderRadius(8)
              .margin({ top: 5 })
              .onClick(() => {
                this.selectedStrategy = strategy.name;
              })
            }
          })
        }
        .width('100%')
        .height('40%')
        .margin({ top: 10 })

        Button('2. 删除选中的策略')
          .onClick(async () => {
            if (!this.selectedStrategy) {
              hilog.warn(0x0000, 'RemoveStrategyDemo', '请先选择策略');
              return;
            }

            try {
              await guardService.removeGuardStrategy(this.selectedStrategy);
              hilog.info(0x0000, 'RemoveStrategyDemo', 
                `removeGuardStrategy succeeded: ${this.selectedStrategy}`);

              // 刷新策略列表
              const strategies = await guardService.queryGuardStrategies();
              this.strategies = strategies;
              this.selectedStrategy = '';
            } catch (err) {
              const message = (err as BusinessError).message;
              const code = (err as BusinessError).code;
              hilog.error(0x0000, 'RemoveStrategyDemo',
                `removeGuardStrategy failed with error code: ${code}, message: ${message}`);
            }
          })
          .margin({ top: 20 })
          .width('80%')
      } else {
        Text('暂无策略')
          .fontSize(16)
          .margin({ top: 30 })
          .fontColor('#999999')
      }
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

---

三、完整示例代码

下面是一个完整的示例,展示了如何实现守护策略的查询和删除功能:

import { guardService } from '@kit.ScreenTimeGuardKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct StrategyQueryDeleteDemo {
  @State strategies: guardService.GuardStrategy[] = [];
  @State selectedStrategy: string = '';
  @State message: string = '';

  async queryStrategies() {
    try {
      const strategies = await guardService.queryGuardStrategies();
      this.strategies = strategies;
      this.message = `查询成功,共 ${strategies.length} 个策略`;
      hilog.info(0x0000, 'StrategyQueryDeleteDemo', 
        `found ${strategies.length} strategies`);
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      this.message = `查询失败: ${message}`;
      hilog.error(0x0000, 'StrategyQueryDeleteDemo',
        `queryGuardStrategies failed with error code: ${code}, message: ${message}`);
    }
  }

  async removeStrategy() {
    if (!this.selectedStrategy) {
      this.message = '请先选择要删除的策略';
      return;
    }

    try {
      await guardService.removeGuardStrategy(this.selectedStrategy);
      this.message = `删除成功: ${this.selectedStrategy}`;
      hilog.info(0x0000, 'StrategyQueryDeleteDemo', 
        `removeGuardStrategy succeeded: ${this.selectedStrategy}`);

      // 刷新策略列表
      await this.queryStrategies();
      this.selectedStrategy = '';
    } catch (err) {
      const message = (err as BusinessError).message;
      const code = (err as BusinessError).code;
      this.message = `删除失败: ${message}`;
      hilog.error(0x0000, 'StrategyQueryDeleteDemo',
        `removeGuardStrategy failed with error code: ${code}, message: ${message}`);
    }
  }

  getStrategyDesc(strategy: guardService.GuardStrategy): string {
    const time = strategy.timeStrategy;
    let desc = '';

    if (time.type === guardService.TimeStrategyType.START_END_TIME_TYPE) {
      desc = `${time.startTime}-${time.endTime}`;
    } else if (time.type === guardService.TimeStrategyType.TOTAL_DURATION_TYPE) {
      desc = `总时长: ${Math.floor((time.duration || 0) / 60)} 分钟`;
    } else if (time.type === guardService.TimeStrategyType.SHARED_DURATION_TYPE) {
      desc = `共享时长: ${Math.floor((time.duration || 0) / 60)} 分钟`;
    }

    const repeat = time.repeat || [];
    if (repeat.length > 0) {
      const days = repeat.map(d => ['日', '一', '二', '三', '四', '五', '六'][d - 1]).join('、');
      desc += ` 周${days}`;
    }

    return desc;
  }

  getRestrictionTypeDesc(type: guardService.RestrictionType): string {
    return type === guardService.RestrictionType.BLOCKLIST_TYPE ? 
      '禁止清单' : '允许清单';
  }

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

      Text(this.message)
        .fontSize(14)
        .margin({ top: 20 })
        .fontColor('#666666')

      Row() {
        Button('查询策略')
          .onClick(() => this.queryStrategies())
          .layoutWeight(1)
          .margin({ right: 10 })

        Button('删除选中')
          .onClick(() => this.removeStrategy())
          .layoutWeight(1)
          .margin({ left: 10 })
      }
      .margin({ top: 20 })
      .width('80%')

      // 策略列表
      if (this.strategies.length > 0) {
        List() {
          ForEach(this.strategies, (strategy: guardService.GuardStrategy) => {
            ListItem() {
              Column() {
                // 策略名称
                Row() {
                  Text(strategy.name)
                    .fontSize(16)
                    .fontWeight(FontWeight.Bold)
                    .layoutWeight(1)

                  if (this.selectedStrategy === strategy.name) {
                    Text('✓')
                      .fontSize(16)
                      .fontColor('#00FF00')
                  }
                }
                .width('100%')

                // 策略详情
                Row() {
                  Text(this.getStrategyDesc(strategy))
                    .fontSize(14)
                    .fontColor('#666666')
                    .layoutWeight(1)

                  Text(this.getRestrictionTypeDesc(strategy.appRestrictionType))
                    .fontSize(12)
                    .fontColor('#999999')
                }
                .width('100%')
                .margin({ top: 5 })

                // 应用数量
                Text(`应用数量: ${strategy.appInfo.appTokens.length}`)
                  .fontSize(12)
                  .fontColor('#999999')
                  .margin({ top: 5 })
              }
              .width('100%')
              .padding(15)
              .backgroundColor(
                this.selectedStrategy === strategy.name ? '#E8F5E9' : '#F5F5F5'
              )
              .borderRadius(8)
              .margin({ top: 5 })
              .onClick(() => {
                this.selectedStrategy = strategy.name;
              })
            }
          })
        }
        .width('100%')
        .height('50%')
        .margin({ top: 20 })
      } else {
        Text('暂无策略,点击"查询策略"查看')
          .fontSize(16)
          .margin({ top: 30 })
          .fontColor('#999999')
      }
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

---

四、注意事项

🥦 西兰花警告:

1. 必须先获得用户授权: 查询和删除策略之前,必须先请求用户授权,否则会报错
2. 删除正在执行的策略: 如果策略正在执行,系统会自动先停止再删除,不需要手动停止
3. 策略名称要准确: 删除策略时,策略名称必须准确,否则会抛出"策略不存在"的错误
4. 删除后无法恢复: 策略删除后无法恢复,如果需要重新使用,需要重新添加
5. 查询返回所有策略: queryGuardStrategies 会返回该应用下的所有策略,包括未启动的

---

五、典型使用场景

查询和删除策略在很多场景下都非常有用:

1. 策略管理页面

在策略管理页面,用户可以查看所有策略,选择要删除的策略。

// 显示所有策略
const strategies = await guardService.queryGuardStrategies();

// 用户选择后删除
await guardService.removeGuardStrategy(selectedStrategyName);

2. 策略清理

用户可以删除不再需要的策略,保持策略列表的整洁。

// 删除所有未启动的策略
const strategies = await guardService.queryGuardStrategies();
for (const strategy of strategies) {
  // 检查策略是否正在执行
  if (!isStrategyRunning(strategy)) {
    await guardService.removeGuardStrategy(strategy.name);
  }
}

3. 策略重置

在特定场景下,可以删除所有策略,重置应用状态。

// 删除所有策略
const strategies = await guardService.queryGuardStrategies();
for (const strategy of strategies) {
  await guardService.removeGuardStrategy(strategy.name);
}

---

六、文档资源

官方文档链接:

• 守护策略管理
• 查询策略
• 删除策略
• 示例代码:基于屏幕时间守护服务实现应用访问限制功能

---

七、总结

查询和删除守护策略是策略管理的重要功能,让用户可以方便地查看和管理管控规则。

核心要点:

1. 查询策略可以返回该应用下的所有策略
2. 删除策略时,如果策略正在执行会自动先停止
3. 策略名称必须准确,否则会抛出错误
4. 删除后无法恢复,需要重新添加
5. 查询返回包括未启动的所有策略

查询策略就像查看家规本,删除策略就像废除某条家规。有了这两个功能,用户就可以灵活地管理管控规则了 ^_

---

下一步行动

建议你:

1. 先实现策略查询功能,显示所有策略
2. 实现策略选择功能,让用户选择要删除的策略
3. 实现策略删除功能
4. 添加删除确认对话框,防止误删
5. 结合添加、修改、查询、删除功能,实现完整的策略管理页面

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

---

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