前言

无障碍功能是现代应用不可或缺的一部分。HarmonyOS提供了灰阶模式和颜色反转等视觉辅助功能，帮助视觉障碍用户更好地使用应用。@pura/harmony-utils 的 AppUtil 封装了这些功能的查询与设置方法，开发者可以轻松实现无障碍相关的功能适配。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、灰阶与颜色模式核心API

AppUtil 提供了以下无障碍状态查询方法，开发者可以根据实际需求选择调用：

方法	说明	返回类型	使用场景
isGrayScale()	判断是否开启灰阶模式	boolean	UI配色适配
isInvertColor()	判断是否开启颜色反转	boolean	颜色方案调整
isHighContrastText()	判断是否开启高对比度文字	boolean	文字样式调整
isDaltonizationColorFilter()	判断是否开启色觉校正	boolean	色盲友好适配

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 实时查询：每次调用获取最新的系统设置状态
• 统一风格：与harmony-utils其他工具类保持一致的调用风格

1.2 无障碍模式对比

模式	影响范围	适配建议
灰阶模式	全局颜色去饱和	避免仅靠颜色区分信息
颜色反转	全局颜色取反	注意深浅色反转后的对比度
高对比度文字	文字与背景对比度	增大文字与背景的色差
色觉校正	针对色盲用户的颜色调整	不依赖单一颜色传达信息

二、完整使用步骤

2.1 安装依赖

在项目根目录执行以下命令安装harmony-utils：

ohpm install @pura/harmony-utils

安装完成后，在 oh-package.json5 中确认依赖已添加：

{
  "dependencies": {
    "@pura/harmony-utils": "^1.0.0"
  }
}

2.2 查询无障碍状态

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct GrayScaleDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('查询灰阶模式')
        .width('100%')
        .onClick(() => {
          try {
            let isGray = AppUtil.isGrayScale();
            this.result = `灰阶模式: ${isGray ? '已开启' : '未开启'}`;
          } catch (e) {
            this.result = '异常: ' + e;
          }
        });

      Button('查询颜色反转')
        .width('100%')
        .onClick(() => {
          try {
            let isInvert = AppUtil.isInvertColor();
            this.result = `颜色反转: ${isInvert ? '已开启' : '未开启'}`;
          } catch (e) {
            this.result = '异常: ' + e;
          }
        });

      Button('查询全部无障碍状态')
        .width('100%')
        .onClick(() => {
          try {
            let gray = AppUtil.isGrayScale();
            let invert = AppUtil.isInvertColor();
            let highContrast = AppUtil.isHighContrastText();
            let daltonization = AppUtil.isDaltonizationColorFilter();
            this.result = `灰阶: ${gray}\n颜色反转: ${invert}\n高对比度: ${highContrast}\n色觉校正: ${daltonization}`;
          } catch (e) {
            this.result = '异常: ' + e;
          }
        });

      Text(this.result)
        .fontSize(14)
        .fontColor('#333333')
        .width('100%')
        .padding(12)
        .backgroundColor('#F5F5F5')
        .borderRadius(8)
    }
    .padding(16)
  }
}

2.3 根据无障碍状态适配UI

aboutToAppear() {
  if (AppUtil.isGrayScale()) {
    this.currentTheme = 'grayscale';
  } else if (AppUtil.isHighContrastText()) {
    this.currentTheme = 'highContrast';
  } else {
    this.currentTheme = 'default';
  }
}

三、完整页面示例

以下是一个完整的页面组件，展示了无障碍状态查询在实际项目中的集成方式：

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct AccessibilityDemo {
  @State result: string = '';
  @State theme: string = 'default';

  aboutToAppear() {
    this.updateTheme();
  }

  updateTheme() {
    if (AppUtil.isGrayScale()) {
      this.theme = 'grayscale';
    } else if (AppUtil.isHighContrastText()) {
      this.theme = 'highContrast';
    } else {
      this.theme = 'default';
    }
  }

  build() {
    Column({ space: 12 }) {
      Button('刷新无障碍状态').width('100%').onClick(() => {
        this.updateTheme();
        this.result = `当前主题: ${this.theme}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
        .width('100%').padding(12).backgroundColor('#F5F5F5').borderRadius(8)
    }
    .padding(16)
  }
}

四、进阶用法

4.1 结合其他工具类使用

AppUtil 的无障碍查询可以与 ToastUtil 配合，在状态变化时提醒用户：

import { AppUtil, ToastUtil } from '@pura/harmony-utils';

function checkAccessibilityAndNotify() {
  try {
    let gray = AppUtil.isGrayScale();
    let highContrast = AppUtil.isHighContrastText();
    if (gray || highContrast) {
      ToastUtil.showToast('检测到无障碍模式已开启，已为您适配界面');
    }
  } catch (e) {
    console.error('无障碍检测失败: ' + e);
  }
}

4.2 动态主题切换

根据无障碍状态动态切换应用主题色：

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct ThemedPage {
  @State bgColor: string = '#FFFFFF';
  @State textColor: string = '#333333';

  aboutToAppear() {
    if (AppUtil.isHighContrastText()) {
      this.bgColor = '#000000';
      this.textColor = '#FFFFFF';
    } else if (AppUtil.isGrayScale()) {
      this.bgColor = '#F5F5F5';
      this.textColor = '#666666';
    }
  }

  build() {
    Column() {
      Text('动态主题适配示例')
        .fontSize(16)
        .fontColor(this.textColor)
    }
    .width('100%')
    .height('100%')
    .backgroundColor(this.bgColor)
  }
}

五、注意事项

1. 系统设置：灰阶等模式由系统设置控制，应用只能查询状态，不能修改
2. 实时监听：如需实时响应变化，需配合系统配置变更监听
3. 无障碍适配：建议在应用中根据这些状态调整UI配色方案
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 性能考量：频繁调用建议缓存结果，避免重复查询

六、常见问题

Q1: 调用AppUtil方法时抛出异常怎么办？

首先检查 AppUtil.init() 是否已正确调用，其次确认是否配置了所需权限。如果问题仍然存在，请检查方法参数是否正确。

Q2: AppUtil支持在多线程环境中使用吗？

harmony-utils的工具类主要设计用于主线程，如果需要在Worker线程中使用，建议通过消息机制将结果传递回主线程处理。

Q3: 如何在HSP模块中使用AppUtil？

在HSP（Harmony Shared Package）中使用时，需要依赖主应用的 AppUtil.init() 初始化。确保主应用启动时已完成初始化，HSP模块即可正常调用。

Q4: 灰阶模式对图片有影响吗？

灰阶模式是系统级设置，会影响整个屏幕的显示，包括图片。应用层面无法单独控制图片的灰阶显示。

总结

AppUtil 的灰阶与颜色模式查询功能，让开发者能够感知用户的视觉辅助偏好，从而提供更好的无障碍体验。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理适配这些状态，可以让应用对所有用户都更加友好，是构建无障碍应用的重要一环。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。