@capacitor/native-settings

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

简介

@capacitor/native-settings是capacitor生态系统中的核心插件，用于打开原生设置屏幕，为跨平台应用开发提供访问设备系统设置的能力。为跨平台应用开发提供设备差异化适配能力，本文档仅说明在OpenHarmony环境下的使用情况。

API提供了打开原生设置页面的功能，支持Android、iOS和OpenHarmony等主流移动平台。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/native-settings

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/native-settings

手动引入安装

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

1. 添加插件配置

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

{
  "pkg": "@capacitor/native-settings",
  "classpath": "NativeSettings"
}

2. 修改CMake配置

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

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

// ...

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

3. 复制源码文件

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

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

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

4. 添加 ArkTS 配置

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

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

卸载

# 卸载 native-settings 插件
hionic plugin remove @capacitor/native-settings

约束与限制

兼容性

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

1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

无需额外配置应用权限。

插件配置

无特殊插件配置项。

使用示例

示例1：打开原生设置

import { NativeSettings, AndroidSettings, IOSSettings } from '@capacitor/native-settings';

const handleOpenSettings = async () => {
  try {
    const result = await NativeSettings.open({
      optionAndroid: AndroidSettings.ApplicationDetails,
      optionIOS: IOSSettings.App,
    });
    console.log('打开设置结果：', result);
  } catch (error) {
    console.error('打开设置失败:', error);
  }
};

示例2：打开Android设置

import { NativeSettings, AndroidSettings } from '@capacitor/native-settings';

const handleOpenAndroidSettings = async () => {
  try {
    const result = await NativeSettings.openAndroid({
      option: AndroidSettings.ApplicationDetails,
    });
    console.log('打开Android设置结果：', result);
  } catch (error) {
    console.error('打开Android设置失败:', error);
  }
};

示例3：打开iOS设置

import { NativeSettings, IOSSettings } from '@capacitor/native-settings';

const handleOpenIOSSettings = async () => {
  try {
    const result = await NativeSettings.openIOS({
      option: IOSSettings.App,
    });
    console.log('打开iOS设置结果：', result);
  } catch (error) {
    console.error('打开iOS设置失败:', error);
  }
};

使用说明

引入@capacitor/native-settings插件的NativeSettings模块使用，所有API均基于Promise实现，支持异步调用。

1. 打开原生设置

方法签名

open(options: PlatformOptions): Promise<NativeSettingsResult>

参数说明

| 参数名 | 类型 | 说明 | |---------|---------|--------| | options | PlatformOptions | 必选，平台设置选项 |

PlatformOptions

| 属性名 | 类型 | 说明 | |---------|---------|--------| | optionAndroid | AndroidSettings | Android设置选项 | | optionIOS | IOSSettings | iOS设置选项 |

NativeSettingsResult

| 属性名 | 类型 | 说明 | |---------|---------|--------| | success | boolean | 操作是否成功 | | error | string | 操作失败时的错误信息 |

2. 打开Android设置

方法签名

openAndroid(options: AndroidOptions): Promise<NativeSettingsResult>

参数说明

| 参数名 | 类型 | 说明 | |---------|---------|--------| | options | AndroidOptions | 必选，Android设置选项 |

AndroidOptions

| 属性名 | 类型 | 说明 | |---------|---------|--------| | option | AndroidSettings | Android设置选项 |

3. 打开iOS设置

方法签名

openIOS(options: IOSOptions): Promise<NativeSettingsResult>

参数说明

| 参数名 | 类型 | 说明 | |---------|---------|--------| | options | IOSOptions | 必选，iOS设置选项 |

IOSOptions

| 属性名 | 类型 | 说明 | |---------|---------|--------| | option | IOSSettings | iOS设置选项 |

4. 枚举类型

AndroidSettings

| 成员 | 值 | 描述 | | --- | --- | --- | | Accessibility | accessibility | 无障碍功能 | | Account | account | 显示用于创建新账户的添加账户屏幕 | | AirplaneMode | airplane_mode | 显示允许进入/退出飞行模式的设置 | | Apn | apn | 显示允许配置 APN 的设置（需要手动进入下一级页面） | | ApplicationDetails | application_details | 显示有关特定应用的详细信息屏幕 | | ApplicationDevelopment | application_development | 显示允许配置应用开发相关设置的设置 | | Application | application | 显示允许配置应用相关设置的设置 | | AppNotification | app_notification | 显示允许配置应用特定通知的设置 | | BatteryOptimization | battery_optimization | 显示用于控制哪些应用可以忽略电池优化的屏幕 | | Bluetooth | bluetooth | 显示允许配置蓝牙的设置 | | Captioning | captioning | 显示视频字幕的设置，暂不支持 | | Cast | cast | 显示允许配置投射端点的设置 | | DataRoaming | data_roaming | 显示用于选择 2G/3G/4G 的设置（需要手动进入下一级页面） | | Date | date | 显示允许配置日期和时间的设置 | | Display | display | 显示允许配置显示的设置 | | Dream | dream | 显示 Daydream 设置，暂不支持 | | Home | home | 显示主屏幕选择设置，暂不支持 | | Keyboard | keyboard | 显示配置输入法的设置，特别是允许用户启用输入法 | | KeyboardSubType | keyboard_subtype | 显示启用/禁用输入法子类型的设置 | | Locale | locale | 显示允许配置区域设置的设置 | | Location | location | 显示允许配置当前位置源的设置 | | ManageApplications | manage_applications | 显示管理已安装应用的设置 | | ManageAllApplications | manage_all_applications | 显示管理所有应用的设置 | | MemoryCard | memory_card | 显示存储卡存储的设置，暂不支持 | | Network | network | 显示选择网络运营商的设置 | | NfcSharing | nfcsharing | 显示 NFC 共享设置，暂不支持 | | NfcPayment | nfc_payment | 显示 NFC 点击支付设置（需要手动进入下一级页面） | | NfcSettings | nfc_settings | 显示 NFC 设置 | | Print | print | 显示打印设置，暂不支持 | | Privacy | privacy | 显示允许配置隐私选项的设置 | | QuickLaunch | quick_launch | 显示快速启动设置，暂不支持 | | Search | search | 显示搜索设置，暂不支持 | | Security | security | 显示安全设置 | | Settings | settings | 显示系统设置的主屏幕 | | ShowRegulatoryInfo | show_regulatory_info | 显示设备的监管信息屏幕 | | Sound | sound | 显示声音设置 | | Storage | storage | 显示存储设置 | | Sync | sync | 显示同步设置，暂不支持 | | TextToSpeech | text_to_speech | 显示文本转语音设置，暂不支持 | | Usage | usage | 显示应用使用情况设置 | | UserDictionary | user_dictionary | 显示用户词典设置，暂不支持 | | VoiceInput | voice_input | 显示语音输入设置 | | VPN | vpn | 显示 VPN 设置 | | Wifi | wifi | 显示 Wi-Fi 设置 | | WifiIp | wifi_ip | 显示 Wi-Fi IP 设置（需要手动进入下一级页面） | | Wireless | wireless | 显示允许配置无线控制的设置 | | ZenMode | zen_mode | 禅模式设置 | | ZenModePriority | zen_mode_priority | 禅模式优先级设置（需要手动进入下一级页面） | | ZenModeBlockedEffects | zen_mode_blocked_effects | 禅模式阻止效果设置（需要手动进入下一级页面） |

IOSSettings

| 成员 | 值 | 描述 | | --- | --- | --- | | About | about | 设置 > 关于页面 | | App | app | 打开应用特定的设置屏幕（Apple 官方支持） | | AppNotification | appNotification | 打开 iOS 15.4+ 的应用特定通知设置屏幕；对于早期版本，打开通用应用特定设置 | | AutoLock | autoLock | 用于设置屏幕是否以及何时自动锁定，暂不支持 | | Bluetooth | bluetooth | 蓝牙设置，允许用户启用/禁用蓝牙并搜索设备 | | DateTime | dateTime | 日期和时间设置 | | FaceTime | facetime | FaceTime 设置，暂不支持 | | General | general | 打开 iOS 通用设置屏幕 | | Keyboard | keyboard | 键盘设置 | | ICloud | iCloud | iCloud 设置，暂不支持 | | ICloudStorageBackup | iCloudStorageBackup | iCloud 存储和备份设置，暂不支持 | | International | international | 语言和区域设置 | | LocationServices | locationServices | 显示允许配置当前位置源的设置 | | Music | music | 音乐设置 | | Notes | notes | 备忘录设置 | | Notifications | notifications | 通知设置 | | Phone | phone | 电话设置| | Photos | photos | 照片设置 | | ManagedConfigurationList | managedConfigurationList | 允许用户管理安装在手机上的配置文件 | | Reset | reset | 用户可以将手机重置为出厂设置的屏幕 | | Ringtone | ringtone | 铃声设置 | | Sounds | sounds | 用于设置电话音量、振动设置等 | | SoftwareUpdate | softwareUpdate | 软件更新屏幕 | | Store | store | 商店设置，暂不支持 | | Tracking | tracking | 跟踪设置，暂不支持 | | VPN | vpn | VPN 设置 | | Wallpaper | wallpaper | 壁纸设置（需要手动进入下一级页面） | | WiFi | wifi | Wi-Fi 设置 | | Tethering | tethering | 网络共享设置（用于使用移动数据创建热点） | | DoNotDisturb | doNotDisturb | 勿扰模式设置 | | TouchIdPasscode | touchIdPasscode | Touch ID 密码设置 | | ScreenTime | screenTime | 屏幕使用时间设置，暂不支持 | | Accessibility | accessibility | 辅助功能设置 |

特殊说明

无特殊说明。

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml       # 插件配置文件

贡献代码

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

许可证

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