@capacitor/text-zoom

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/text-zoom 是 capacitor 生态系统中的插件，用于管理和控制应用内的文本缩放级别，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台，本文档主要说明在 OpenHarmony 系统中的使用。

该插件允许开发者获取当前文本缩放比率、获取系统的文本缩放比率，以及设置应用内的文本缩放比率，满足无障碍需求中用户调整字体大小的场景。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/text-zoom

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/text-zoom

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
    "pkg": "@capacitor/text-zoom",
    "classpath": "TextZoom"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(TextZoom)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  TextZoom
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中 src/main/cpp/TextZoom 目录下的 TextZoom.h、TextZoom.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/TextZoom 目录下。

将源码中 src/main/ets/components/TextZoom 目录下的 TextZoom.ets 文件引入到 capacitor 模块中 src/main/ets/components/TextZoom 目录下。

4. 添加 ArkTS 配置

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

"buildOption": {
  // ...
  "arkOptions": {
    "runtimeOnly": [
      // ...
      "./src/main/ets/components/TextZoom/TextZoom.ets"
      // ...
    ]
  }
}

卸载

# 卸载 text-zoom 插件
hionic plugin remove @capacitor/text-zoom

参数配置

需要在应用中配置字体缩放支持：

1. 新建配置文件

AppScope/resources/base/profile/configuration.json

{
  "configuration": {
    "fontSizeScale": "followSystem",
    "fontSizeMaxScale": "3.2"
  }
}

2. 在 AppScope/app.json5 中引用该配置

{
  "app": {
    "bundleName": "com.example.temp_demo",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    // 引用配置
    "configuration": "$profile:configuration"
  },
}

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不涉及特殊权限。

使用示例

示例：获取和设置文本缩放

import { TextZoom } from '@capacitor/text-zoom';

const manageTextZoom = async () => {
  // 获取当前缩放值
  const current = await TextZoom.get();
  console.log('当前缩放比例:', current.value);

  // 获取系统偏好值
  const preferred = await TextZoom.getPreferred();
  console.log('系统偏好缩放比例:', preferred.value);

  // 设置新的缩放值 (例如设置为 1.5 倍)
  try {
    await TextZoom.set({ value: 1.5 });
    console.log('文本缩放已设置为 1.5');
  } catch (error) {
    console.error('设置失败:', error);
  }
};

使用说明

TextZoom 是插件导出对象，可直接导入使用，无需等待就绪事件触发，导入后即可调用插件提供的所有方法。

接口方法

| 方法名 | 调用方式 | 入参类型 | 功能描述 | | ---------------- | ------------------------ | ------------------------- | ------------------------------------------ | | get() | TextZoom.get() | 无入参 | 获取当前的文本缩放级别 | | getPreferred() | TextZoom.getPreferred() | 无入参 | 获取系统的默认文本缩放级别 | | set(options) | TextZoom.set(options) | SetOptions | 设置应用内的文本缩放级别，缩放值必须大于 0 |

数据结构

SetOptions

调用 set 方法时的入参对象

| 参数 | 类型 | 描述 | | --------- | -------- | ------------------------------------------------------------------------------------------------------------- | | value | number | 要设置的文本缩放比例。必须是数字且大于 0。例如 1.0 代表 100% (正常大小)，1.5 代表 150%，2.0 代表 200%。 |

GetResult

get 和 getPreferred 方法的返回对象

| 参数 | 类型 | 描述 | | --------- | -------- | ------------------------------ | | value | number | 文本缩放比例数值。例如 1.0。 |

常见问题

Q: 设置缩放值时报错 "Value must be greater than 0"？

• 原因：插件对输入的 value 进行了有效性校验，要求缩放值必须大于 0。
• 解决方案：确保传入的 value 参数是大于 0 的数字。例如 0.5、1.0、1.5、2.0 等都是有效值。

Q: 设置的缩放值会保存吗？

• 说明：插件不会持久化保存缩放值。调用 set 方法只会在当前运行时生效，应用重启后会恢复到默认值（跟随系统）。如果需要持久化保存用户的缩放偏好，需要应用侧自行实现保存和恢复逻辑。

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- TextZoom   # 插件核心 C++ 实现
|                             |---- TextZoom.cpp
|                             |---- TextZoom.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- TextZoom   # ArkTS 组件实现
|                                   |---- TextZoom.ets
|     |---- README.md                # 说明文档
|     |---- package.json             # npm 配置文件
|     |---- plugin.xml               # capacitor 插件配置
|     |---- LICENSE                  # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。