diff --git a/CODEOWNERS b/CODEOWNERS index cd5e192f6dfec673acfd1a1c594cb33b3a173978..02ff9150c412e86055638ca4cbf6f730f6a54fe2 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -164,6 +164,24 @@ zh-cn/application-dev/reference/arkui-js/ @HelloCrease zh-cn/application-dev/reference/arkui-ts/ @HelloCrease zh-cn/application-dev/reference/native-apis @RayShih zh-cn/application-dev/reference/native-lib @RayShih +zh-cn/application-dev/quick-start/start-overview.md @ge-yafang +zh-cn/application-dev/quick-start/start-with-ets.md @ge-yafang +zh-cn/application-dev/quick-start/start-with-ets-low-code.md @ge-yafang +zh-cn/application-dev/quick-start/start-with-js.md @ge-yafang +zh-cn/application-dev/quick-start/start-with-js-low-code.md @ge-yafang +zh-cn/application-dev/quick-start/deveco-studio-user-guide-for-openharmony.md @ge-yafang +zh-cn/application-dev/quick-start/package-structure.md @RayShih +zh-cn/application-dev/quick-start/basic-resource-file-categories.md @RayShih +zh-cn/application-dev/quick-start/syscap.md @RayShih +zh-cn/application-dev/napi/napi-guidelines.md @RayShih +zh-cn/application-dev/napi/drawing-guidelines.md @ge-yafang +zh-cn/application-dev/napi/rawfile-guidelines.md @HelloCrease +zh-cn/application-dev/reference/js-service-widget-ui/ @HelloCrease +zh-cn/application-dev/website.md @zengyawen +zh-cn/application-dev/faqs/ @zengyawen +zh-cn/application-dev/file-management/ @qinxiaowang +zh-cn/application-dev/application-test/ @HelloCrease + zh-cn/application-dev/reference/apis/js-apis-DataUriUtils.md @RayShih zh-cn/application-dev/reference/apis/js-apis-ability-errorCode.md @RayShih zh-cn/application-dev/reference/apis/js-apis-ability-wantConstant.md @RayShih @@ -186,7 +204,6 @@ zh-cn/application-dev/reference/apis/js-apis-particleAbility.md @RayShih zh-cn/application-dev/reference/apis/js-apis-service-extension-ability.md @RayShih zh-cn/application-dev/reference/apis/js-apis-application-StartOptions.md @RayShih zh-cn/application-dev/reference/apis/js-apis-application-staticSubscriberExtensionAbility.md @RayShih -zh-cn/application-dev/reference/apis/js-apis-uripermissionmanager.md @RayShih zh-cn/application-dev/reference/apis/js-apis-application-Want.md @RayShih zh-cn/application-dev/reference/apis/js-apis-wantAgent.md @RayShih zh-cn/application-dev/reference/apis/js-apis-dataAbilityHelper.md @RayShih @@ -209,7 +226,7 @@ zh-cn/application-dev/reference/apis/js-apis-application-shellCmdResult.md @RayS zh-cn/application-dev/reference/apis/js-apis-commonEvent.md @RayShih zh-cn/application-dev/reference/apis/js-apis-emitter.md @RayShih zh-cn/application-dev/reference/apis/js-apis-notification.md @RayShih -zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-eventhub.md @RayShih zh-cn/application-dev/reference/apis/js-apis-Bundle.md @RayShih zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @RayShih @@ -277,15 +294,15 @@ zh-cn/application-dev/reference/apis/js-apis-http.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-request.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-socket.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-webSocket.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-bluetooth.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-nfcTag.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-nfcTech.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-tagSession.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-connectedTag.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-bluetooth.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-nfcTag.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-nfcTech.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-tagSession.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-connectedTag.md @RayShih zh-cn/application-dev/reference/apis/js-apis-rpc.md @qinxiaowang -zh-cn/application-dev/reference/apis/js-apis-wifi.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-wifiext.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-accessibility.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-wifi.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-wifiext.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-accessibility.md @RayShih zh-cn/application-dev/reference/apis/js-apis-faultLogger.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-hiappevent.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-hichecker.md @zengyawen @@ -293,31 +310,31 @@ zh-cn/application-dev/reference/apis/js-apis-hidebug.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-hilog.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-hitracechain.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-hitracemeter.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-inputmethod.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-inputmethodengine.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-inputmethod.md @ge-yafang +zh-cn/application-dev/reference/apis/js-apis-inputmethodengine.md @ge-yafang zh-cn/application-dev/reference/apis/js-apis-pasteboard.md @ge-yafang -zh-cn/application-dev/reference/apis/js-apis-screen-lock.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-system-time.md @zengyawen -zh-cn/application-dev/reference/apis/js-apis-wallpaper.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-screen-lock.md @ge-yafang +zh-cn/application-dev/reference/apis/js-apis-system-time.md @ge-yafang +zh-cn/application-dev/reference/apis/js-apis-wallpaper.md @ge-yafang zh-cn/application-dev/reference/apis/js-apis-timer.md @HelloCrease -zh-cn/application-dev/reference/apis/js-apis-battery-info.md @qinxiaowang -zh-cn/application-dev/reference/apis/js-apis-brightness.md @qinxiaowang -zh-cn/application-dev/reference/apis/js-apis-device-info.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-battery-info.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-brightness.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-device-info.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-device-manager.md -zh-cn/application-dev/reference/apis/js-apis-geolocation.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-geolocation.md @RayShih zh-cn/application-dev/reference/apis/js-apis-inputconsumer.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-inputdevice.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-inputeventclient.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-inputmonitor.md @HelloCrease -zh-cn/application-dev/reference/apis/js-apis-power.md @qinxiaowang -zh-cn/application-dev/reference/apis/js-apis-runninglock.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-power.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-runninglock.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-sensor.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-system-sensor.md @HelloCrease -zh-cn/application-dev/reference/apis/js-apis-system-parameter.md @qinxiaowang -zh-cn/application-dev/reference/apis/js-apis-thermal.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-system-parameter.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-thermal.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-update.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-usb.md @ge-yafang -zh-cn/application-dev/reference/apis/js-apis-colorSpaceManager.mdd @ge-yafang +zh-cn/application-dev/reference/apis/js-apis-colorSpaceManager.md @ge-yafang zh-cn/application-dev/reference/apis/js-apis-vibrator.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-appAccount.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-distributed-account.md @zengyawen @@ -349,24 +366,85 @@ zh-cn/application-dev/reference/apis/js-apis-hisysevent.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-privacyManager.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-EnterpriseAdminExtensionAbility.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-uiappearance.md @HelloCrease -zh-cn/application-dev/quick-start/start-overview.md @ge-yafang -zh-cn/application-dev/quick-start/start-with-ets.md @ge-yafang -zh-cn/application-dev/quick-start/start-with-ets-low-code.md @ge-yafang -zh-cn/application-dev/quick-start/start-with-js.md @ge-yafang -zh-cn/application-dev/quick-start/start-with-js-low-code.md @ge-yafang -zh-cn/application-dev/quick-start/deveco-studio-user-guide-for-openharmony.md @ge-yafang -zh-cn/application-dev/quick-start/package-structure.md @RayShih -zh-cn/application-dev/quick-start/basic-resource-file-categories.md @RayShih -zh-cn/application-dev/quick-start/syscap.md @RayShih -zh-cn/application-dev/napi/napi-guidelines.md @RayShih -zh-cn/application-dev/napi/drawing-guidelines.md @ge-yafang -zh-cn/application-dev/napi/rawfile-guidelines.md @HelloCrease -zh-cn/application-dev/reference/apis/js-apis-buffer.md @zengyawen -zh-cn/application-dev/reference/js-service-widget-ui @HelloCrease -zh-cn/application-dev/website.md @zengyawen -zh-cn/application-dev/faqs/ @zengyawen zh-cn/application-dev/reference/apis/js-apis-useriam-faceauth.md @zengyawen zh-cn/application-dev/reference/apis/js-apis-userfilemanager.md @qinxiaowang zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-buffer.md @zengyawen zh-cn/application-dev/reference/apis/Readme-CN.md @zengyawen -zh-cn/application-dev/file-management/ @qinxiaowang \ No newline at end of file +zh-cn/application-dev/reference/apis/development-intro.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-application-abilityManager.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-application-applicationContext.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-application-EnvironmentCallback.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-AbilityInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-ApplicationInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-BundleInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-BundleInstaller.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-CustomizeData.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-defaultAppManager.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-Bundle-distributedBundle.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-ElementName.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-ExtensionAbilityInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-HapModuleInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-Bundle-InnerBundleManager.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-LauncherAbilityInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-Metadata.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-ModuleInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-PermissionDef.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-remoteAbilityInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bytrace.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-continuation-continuationExtraParams.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-continuation-continuationManager.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-continuation-continuationResult.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-dispatchInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-distributedMissionManager.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-errorManager.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-inputevent.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-inputmethod-extension-ability.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-inputmethod-extension-context.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-keycode.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-keyevent.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-logs.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-mouseevent.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-nfcController.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-nfctech.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-pointer.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-processrunninginformation.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-securityLabel.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-system-app.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-system-battery.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-system-bluetooth.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-system-brightness.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-system-configuration.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-system-device.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-system-fetch.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-system-file.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-system-location.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-system-mediaquery.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-system-network.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-system-notification.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-system-package.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-system-prompt.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-system-request.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-system-router.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-system-timer.md @ge-yafang +zh-cn/application-dev/reference/apis/js-apis-system-vibrate.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-touchevent.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-accessibility-config.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-application-quickFixManager.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-Bundle-BundleStatusCallback.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-bundle-PackInfo.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-enterpriseDeviceManager-DeviceSettingsManager.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-fileAccess.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-fileExtensionInfo.md @qinxiaowang +zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-net-policy.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-net-sharing.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-net-statistics.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-tlsSocket.md @zengyawen +zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md @HelloCrease +zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md @zengyawen diff --git a/en/application-dev/napi/napi-guidelines.md b/en/application-dev/napi/napi-guidelines.md index f471f4a6eed7d3eb2c96dab8cae4cb7480a13616..188b4f1336e2c56562f594e42dc26cabf8a8fc55 100644 --- a/en/application-dev/napi/napi-guidelines.md +++ b/en/application-dev/napi/napi-guidelines.md @@ -17,11 +17,11 @@ You can `import` the native .so that contains the JS processing logic. For examp ### .so Naming Rules -Each module has a .so file. For example, if the module name is `hello`, name the .so file **libhello.so**. The `nm_modname` field in `napi_module` must be `hello`, which is the same as the module name. The sample code for importing the .so file is `import hello from 'libhello.so'`. +Each module has a .so file. For example, if the module name is `hello`, name the .so file `libhello.so`. The `nm_modname` field in `napi_module` must be `hello`, which is the same as the module name. The sample code for importing the .so file is `import hello from 'libhello.so'`. ### JS Objects and Threads -The Ark engine prevents NAPIs from being called to operate JS objects in non-JS threads. Otherwise, the application will crash. +The Ark engine prevents NAPIs from being called to operate JS objects in non-JS threads. Otherwise, the application will crash. Observe the following rules: * The NAPIs can be used only in JS threads. * **env** is bound to a thread and cannot be used across threads. The JS object created by a NAPI can be used only in the thread, in which the object is created, that is, the JS object is bound to the **env** of the thread. @@ -640,8 +640,3 @@ export default { } } ``` -## Samples -The following samples are provided for native API development: -- [`NativeAPI`: NativeAPI (eTS) (API8)](https://gitee.com/openharmony/app_samples/tree/master/Native/NativeAPI) -- [First Native C++ Application (eTS) (API9)](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/NativeTemplateDemo) -- [Native Component (eTS) (API9) ](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/XComponent) diff --git a/zh-cn/application-dev/Readme-CN.md b/zh-cn/application-dev/Readme-CN.md index 4743c1e020b9e08362342363ba79178e9c07139e..dde8993091b6eb93c20db2f5b35e86fb670c40e6 100644 --- a/zh-cn/application-dev/Readme-CN.md +++ b/zh-cn/application-dev/Readme-CN.md @@ -16,6 +16,17 @@ - [应用包结构说明(Stage模型)](quick-start/stage-structure.md) - [SysCap说明](quick-start/syscap.md) - [HarmonyAppProvision配置文件](quick-start/app-provision-structure.md) + - 学习ArkTS语言 + - [初识ArkTS语言](quick-start/arkts-get-started.md) + - ArkTS语法（声明式UI） + - [基本UI描述](quick-start/arkts-basic-ui-description.md) + - 状态管理 + - [基本概念](quick-start/arkts-state-mgmt-concepts.md) + - [页面级变量的状态管理](quick-start/arkts-state-mgmt-page-level.md) + - [应用级变量的状态管理](quick-start/arkts-state-mgmt-application-level.md) + - [动态构建UI元素](quick-start/arkts-dynamic-ui-elememt-building.md) + - [渲染控制](quick-start/arkts-rendering-control.md) + - [使用限制与扩展](quick-start/arkts-restrictions-and-extensions.md) - 开发 - [Ability开发](ability/Readme-CN.md) - [UI开发](ui/Readme-CN.md) diff --git a/zh-cn/application-dev/ability/fa-brief.md b/zh-cn/application-dev/ability/fa-brief.md index eff2aef25d1eb9e1f2a6a3a9b9938971304cab9d..3d8989bc1f7c56a6e9b614b3a6cfb7647d21f865 100644 --- a/zh-cn/application-dev/ability/fa-brief.md +++ b/zh-cn/application-dev/ability/fa-brief.md @@ -39,15 +39,15 @@ FA模型的应用包的工程目录结构，请参考[OpenHarmony工程介绍](h 针对FA模型下的Ability开发，有以下相关实例可供参考： -- [`FaModel`：FA模型（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FaModel) +- [`FaModel`：FA模型（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FaModel) - [`DistributedCalc`：分布式计算器（JS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/DistributeCalc) -- [`DistributedCalc`：分布式计算器（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Preset/DistributeCalc) -- [`DistributeGraffiti`：分布式涂鸦（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DistributedGraffiti) +- [`DistributedCalc`：分布式计算器（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Preset/DistributeCalc) +- [`DistributeGraffiti`：分布式涂鸦（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DistributedGraffiti) - [分布式调度启动远程FA（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/RemoteStartFA) - [分布式新闻客户端（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/NewsDemo) -- [分布式手写板（eTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/DistributeDatabaseDrawEts) +- [分布式手写板（ArkTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/DistributeDatabaseDrawEts) - [分布式鉴权（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/GameAuthOpenH) -- [分布式游戏手柄（eTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/HandleGameApplication) -- [分布式邮件（eTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/OHMailETS) -- [分布式亲子早教系统（eTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/OpenHarmonyPictureGame) -- [分布式遥控器（eTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/RemoteControllerETS) \ No newline at end of file +- [分布式游戏手柄（ArkTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/HandleGameApplication) +- [分布式邮件（ArkTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/OHMailETS) +- [分布式亲子早教系统（ArkTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/OpenHarmonyPictureGame) +- [分布式遥控器（ArkTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/RemoteControllerETS) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/fa-dataability.md b/zh-cn/application-dev/ability/fa-dataability.md index bd66df25aa9f2b56c6bdfda61bbf68e0c10f1be1..78855f0834476bf389e9a17faed5cdf6a126894f 100644 --- a/zh-cn/application-dev/ability/fa-dataability.md +++ b/zh-cn/application-dev/ability/fa-dataability.md @@ -311,4 +311,4 @@ URI示例： 针对DataAbility开发，有以下相关实例可供参考： -- [`DataAbility`：DataAbility的创建与访问（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DataAbility) +- [`DataAbility`：DataAbility的创建与访问（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DataAbility) diff --git a/zh-cn/application-dev/ability/fa-formability.md b/zh-cn/application-dev/ability/fa-formability.md index 0f2be340b5dbad6500929a80eceec167f58a1fde..3fbe75aba88249f3248233b5626a3b1fa9139a70 100644 --- a/zh-cn/application-dev/ability/fa-formability.md +++ b/zh-cn/application-dev/ability/fa-formability.md @@ -403,5 +403,5 @@ onUpdate(formId) { ## 相关实例 针对FA模型卡片提供方的开发，有以下相关实例可供参考： -- [`FormAbility`：FA模型卡片（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FormAbility) -- [`FormLauncher`：卡片使用方（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FormLauncher) \ No newline at end of file +- [`FormAbility`：FA模型卡片（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FormAbility) +- [`FormLauncher`：卡片使用方（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FormLauncher) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/fa-pageability.md b/zh-cn/application-dev/ability/fa-pageability.md index c854269adc4054c88b3f3d1a61c89bf6db1d6129..abab9903310c167f82cdb8dbe8cb80d4243686cb 100644 --- a/zh-cn/application-dev/ability/fa-pageability.md +++ b/zh-cn/application-dev/ability/fa-pageability.md @@ -80,19 +80,17 @@ ability支持单实例和多实例两种启动模式。 ```javascript import featureAbility from '@ohos.ability.featureAbility' featureAbility.startAbility({ - want: - { - action: "", - entities: [""], - type: "", - deviceId: "", - bundleName: "com.example.myapplication", - /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", - uri: "" - }, - }, - ); + want: { + action: "", + entities: [""], + type: "", + deviceId: "", + bundleName: "com.example.myapplication", + /* FA模型中abilityName由package + Ability name组成 */ + abilityName: "com.example.entry.secondAbility", + uri: "" + } + }); ``` ### 启动远程PageAbility（当前仅对系统应用开放） @@ -227,4 +225,4 @@ export default { 针对PageAbility开发，有以下相关实例可供参考： -- [`DMS`：分布式Demo（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DMS) \ No newline at end of file +- [`DMS`：分布式Demo（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DMS) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/fa-serviceability.md b/zh-cn/application-dev/ability/fa-serviceability.md index d00801955385bee15b008864cb96537879272cb3..162f45f14406b52de45c9bf13e1c9fe08882e73c 100644 --- a/zh-cn/application-dev/ability/fa-serviceability.md +++ b/zh-cn/application-dev/ability/fa-serviceability.md @@ -406,5 +406,5 @@ export default { ## 相关实例 针对ServiceAbility开发，有以下相关实例可供参考： -- [`ServiceAbility`：ServiceAbility的创建与使用（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/ServiceAbility) -- [`DMS`：分布式Demo（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DMS) +- [`ServiceAbility`：ServiceAbility的创建与使用（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/ServiceAbility) +- [`DMS`：分布式Demo（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/DMS) diff --git a/zh-cn/application-dev/ability/stage-ability.md b/zh-cn/application-dev/ability/stage-ability.md index b10f8d6934228cf668dca0390e47e5ef6c60ce8a..4a39afa52ebff9f2d33fc8dcac0a79e17fdaaf75 100644 --- a/zh-cn/application-dev/ability/stage-ability.md +++ b/zh-cn/application-dev/ability/stage-ability.md @@ -324,4 +324,4 @@ struct Index { ## 相关实例 针对Stage模型Ability开发，有以下相关示例可供参考： -- [`StageCallAbility`：StageCallAbility的创建与使用（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageCallAbility) +- [`StageCallAbility`：StageCallAbility的创建与使用（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageCallAbility) diff --git a/zh-cn/application-dev/ability/stage-brief.md b/zh-cn/application-dev/ability/stage-brief.md index 858dc74a03b441bf7a4f48aef1cd55c8648c2f85..5adca9fd9cd56566346a079a5ecc3aee9b0fda47 100644 --- a/zh-cn/application-dev/ability/stage-brief.md +++ b/zh-cn/application-dev/ability/stage-brief.md @@ -111,7 +111,7 @@ Stage模型的应用包的工程目录结构，请参考[OpenHarmony工程介绍 针对Stage模型下的Ability开发，有以下相关实例可供参考： -- [`StageModel`：Stage模型（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageModel) -- [`WindowExtAbility`：窗口扩展（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/WindowExtAbility) -- [`MissionManager`：系统任务管理（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/MissionManager) -- [`Launcher`：仿桌面应用（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/Launcher) +- [`StageModel`：Stage模型（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageModel) +- [`WindowExtAbility`：窗口扩展（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/WindowExtAbility) +- [`MissionManager`：系统任务管理（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/MissionManager) +- [`Launcher`：仿桌面应用（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/Launcher) diff --git a/zh-cn/application-dev/ability/stage-call.md b/zh-cn/application-dev/ability/stage-call.md index eae390bd7e04f88317f70d2d2875506cb947ff94..7aa9769c0a56c39bc9d93772c5a1e0cd7d4ba2f3 100644 --- a/zh-cn/application-dev/ability/stage-call.md +++ b/zh-cn/application-dev/ability/stage-call.md @@ -284,4 +284,4 @@ releaseCall() { ## 相关实例 针对Stage模型本地Call功能开发，有以下相关实例可供参考： -- [`StageCallAbility`：StageCallAbility的创建与使用（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageCallAbility) +- [`StageCallAbility`：StageCallAbility的创建与使用（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageCallAbility) diff --git a/zh-cn/application-dev/ability/stage-formextension.md b/zh-cn/application-dev/ability/stage-formextension.md index 1d4a427c3e8fb8d44dc18f4dab4a12803e063fff..1e9bcb98842c26520619ede57ac6b7f38f25f470 100644 --- a/zh-cn/application-dev/ability/stage-formextension.md +++ b/zh-cn/application-dev/ability/stage-formextension.md @@ -414,5 +414,5 @@ onUpdate(formId) { ## 相关实例 针对Stage模型卡片提供方的开发，有以下相关实例可供参考： -- [`FormExtAbility`：Stage模型卡片（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FormExtAbility) -- [`GalleryForm`：图库卡片（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/GalleryForm) \ No newline at end of file +- [`FormExtAbility`：Stage模型卡片（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/FormExtAbility) +- [`GalleryForm`：图库卡片（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/GalleryForm) \ No newline at end of file diff --git a/zh-cn/application-dev/ability/stage-serviceextension.md b/zh-cn/application-dev/ability/stage-serviceextension.md index 664eb0e4461ec704e55cf4f47d720faabef5cee4..f52701d88dfd1d9bca4be663ff8652c44e480a0b 100644 --- a/zh-cn/application-dev/ability/stage-serviceextension.md +++ b/zh-cn/application-dev/ability/stage-serviceextension.md @@ -75,4 +75,4 @@ OpenHarmony当前不支持三方应用创建ServiceExtensionAbility。 ## 相关实例 针对ServiceExtensionAbility开发，有以下相关实例可供参考： -- [`ServiceExtAbility`：StageExtAbility的创建与使用（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/ServiceExtAbility) +- [`ServiceExtAbility`：StageExtAbility的创建与使用（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/ServiceExtAbility) diff --git a/zh-cn/application-dev/connectivity/http-request.md b/zh-cn/application-dev/connectivity/http-request.md index 3605d45f313f84b9c70382a62e7754c121418dc4..08a74db395b4761440c0da4ed30417af6a9d14fb 100644 --- a/zh-cn/application-dev/connectivity/http-request.md +++ b/zh-cn/application-dev/connectivity/http-request.md @@ -76,5 +76,5 @@ httpRequest.request( ## 相关实例 针对HTTP数据请求，有以下相关实例可供参考： -- [`Http:`数据请求（eTS）（API9））](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/Http) -- [使用HTTP实现与服务端通信（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/SmartChatEtsOH) \ No newline at end of file +- [`Http:`数据请求（ArkTS）（API9））](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/Http) +- [使用HTTP实现与服务端通信（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/SmartChatEtsOH) \ No newline at end of file diff --git a/zh-cn/application-dev/connectivity/socket-connection.md b/zh-cn/application-dev/connectivity/socket-connection.md index a538d2134dee0e74e6510d81ddab7b2663535d73..2c04d2270a2f2b9c0e9a4551fe06bd1d91483620 100644 --- a/zh-cn/application-dev/connectivity/socket-connection.md +++ b/zh-cn/application-dev/connectivity/socket-connection.md @@ -125,6 +125,6 @@ UDP与TCP流程大体类似，下面以TCP为例： ## 相关实例 针对Socket连接开发，有以下相关实例可供参考： -- [`Socket`：Socket 连接（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/Socket) -- [使用UDP实现与服务端通信（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/UdpDemoOH) -- [使用TCP实现与服务端通信（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/TcpSocketDemo) \ No newline at end of file +- [`Socket`：Socket 连接（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/Socket) +- [使用UDP实现与服务端通信（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/UdpDemoOH) +- [使用TCP实现与服务端通信（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/TcpSocketDemo) \ No newline at end of file diff --git a/zh-cn/application-dev/connectivity/websocket-connection.md b/zh-cn/application-dev/connectivity/websocket-connection.md index 41ddfa0a73707b4d5cf0db3c3b30d735dbb775f3..6efe6b5b39ac1efb22d5dc89d6a75d2c018ad808 100644 --- a/zh-cn/application-dev/connectivity/websocket-connection.md +++ b/zh-cn/application-dev/connectivity/websocket-connection.md @@ -87,4 +87,4 @@ WebSocket连接功能主要由webSocket模块提供。使用该功能需要申 ## 相关实例 针对WebSocket连接的开发，有以下相关实例可供参考： -- [`WebSocket`：WebSocket（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/WebSocket) \ No newline at end of file +- [`WebSocket`：WebSocket（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/WebSocket) \ No newline at end of file diff --git a/zh-cn/application-dev/database/database-distributedobject-guidelines.md b/zh-cn/application-dev/database/database-distributedobject-guidelines.md index 6ba96a9b202191e1323ea2d362eab3ff58dfbea0..b18ca1730cce8cb3c8f89d63f4cfb3b140a7d763 100644 --- a/zh-cn/application-dev/database/database-distributedobject-guidelines.md +++ b/zh-cn/application-dev/database/database-distributedobject-guidelines.md @@ -259,5 +259,5 @@ ## 相关实例 针对分布式数据对象，有以下相关实例可供参考： -- [`DistributedNote`：分布式备忘录（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedNote) -- [`DistributedObjectDms`：分布式跑马灯（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedObjectDms) \ No newline at end of file +- [`DistributedNote`：分布式备忘录（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedNote) +- [`DistributedObjectDms`：分布式跑马灯（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedObjectDms) \ No newline at end of file diff --git a/zh-cn/application-dev/database/database-mdds-guidelines.md b/zh-cn/application-dev/database/database-mdds-guidelines.md index fa22e9d631121538f22ce310c081ff5bb00efa10..aa8938f6b21529ac5b0c3d76a72df8301bc56922 100644 --- a/zh-cn/application-dev/database/database-mdds-guidelines.md +++ b/zh-cn/application-dev/database/database-mdds-guidelines.md @@ -266,8 +266,8 @@ 针对分布式数据开发，有以下相关实例可供参考： - [`DistributedCalc`：分布式计算器（JS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/DistributeCalc) -- [`DistributedCalc`：分布式计算器（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Preset/DistributeCalc) -- [`DistributedDataGobang`：分布式五子棋（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedDataGobang) -- [`DDMQuery`：结果集与谓词（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DDMQuery) -- [`KvStore`：分布式数据库（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/Kvstore) +- [`DistributedCalc`：分布式计算器（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Preset/DistributeCalc) +- [`DistributedDataGobang`：分布式五子棋（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedDataGobang) +- [`DDMQuery`：结果集与谓词（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DDMQuery) +- [`KvStore`：分布式数据库（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/Kvstore) - [分布式数据库（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Data/JsDistributedData) \ No newline at end of file diff --git a/zh-cn/application-dev/database/database-preference-guidelines.md b/zh-cn/application-dev/database/database-preference-guidelines.md index 7714776aa3febdd6a41923b02f6c4bd7ae4a8b19..ad418f8682ffed9d5907105595555b3abeb3dbda 100644 --- a/zh-cn/application-dev/database/database-preference-guidelines.md +++ b/zh-cn/application-dev/database/database-preference-guidelines.md @@ -205,4 +205,4 @@ 针对首选项开发，有以下相关实例可供参考： -- [`Preferences`：首选项（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/Preferences) \ No newline at end of file +- [`Preferences`：首选项（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/Preferences) \ No newline at end of file diff --git a/zh-cn/application-dev/database/database-relational-guidelines.md b/zh-cn/application-dev/database/database-relational-guidelines.md index 64398cd48fbdd355d8a40a6f1464b7a553e7333c..3a89466da4747b55dae10e73bc1d17c1b2730ce4 100644 --- a/zh-cn/application-dev/database/database-relational-guidelines.md +++ b/zh-cn/application-dev/database/database-relational-guidelines.md @@ -418,5 +418,5 @@ ## 相关实例 针对关系型数据库开发，有以下相关实例可供参考： -- [`DistributedRdb`：分布式关系型数据库（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedRdb) +- [`DistributedRdb`：分布式关系型数据库（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedRdb) - [关系型数据库（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Data/JSRelationshipData) \ No newline at end of file diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md index 18c8143806545696068a51a76f06a34f7e34e9df..62fc83581a5869f2281914958d41cc164ef3f003 100644 --- a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md @@ -5,6 +5,8 @@ 设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。 部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。 +根据设备的使用信息统计接口，开发者可以开发出健康管理类应用来实现个人设备健康使用功能，并向用户展示其个人设备的使用记录。 + ## 接口说明 注册相关接口包导入： ```js @@ -56,7 +58,6 @@ import stats from '@ohos.bundleState'; ```js import stats from '@ohos.bundleState' - // 异步方法promise方式 stats.queryBundleActiveStates(0, 20000000000000).then(res => { console.log('BUNDLE_ACTIVE queryBundleActiveStates promise success.'); for (let i = 0; i < res.length; i++) { @@ -66,19 +67,6 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE queryBundleActiveStates promise failed, because: ' + err.code); }); - - // 异步方法callback方式 - stats.queryBundleActiveStates(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryBundleActiveStates callback success.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE queryBundleActiveStates callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE queryBundleActiveStates callback result ' + JSON.stringify(res[i])); - } - } - }); ``` 3. 通过指定起始和结束时间查询应用使用时长统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 @@ -86,7 +74,6 @@ import stats from '@ohos.bundleState'; ```js import stats from '@ohos.bundleState' - // 异步方法promise方式 stats.queryBundleStateInfos(0, 20000000000000).then(res => { console.log('BUNDLE_ACTIVE queryBundleStateInfos promise success.'); let i = 1; @@ -98,21 +85,6 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE queryBundleStateInfos promise failed, because: ' + err.code); }); - - // 异步方法callback方式 - stats.queryBundleStateInfos(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryBundleStateInfos callback success.'); - let i = 1; - for(let key in res){ - console.log('BUNDLE_ACTIVE queryBundleStateInfos callback number : ' + i); - console.log('BUNDLE_ACTIVE queryBundleStateInfos callback result ' + JSON.stringify(res[key])); - i++; - } - } - }); ``` 4. 通过指定起始和结束时间查询当前应用的事件集合，config.json中不需要配置权限。 @@ -120,7 +92,6 @@ import stats from '@ohos.bundleState'; ```js import stats from '@ohos.bundleState' - // 异步方法promise方式 stats.queryCurrentBundleActiveStates(0, 20000000000000).then(res => { console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.'); for (let i = 0; i < res.length; i++) { @@ -130,19 +101,6 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code); }); - - // 异步方法callback方式 - stats.queryCurrentBundleActiveStates(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i])); - } - } - }); ``` 5. 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 @@ -150,7 +108,6 @@ import stats from '@ohos.bundleState'; ```js import stats from '@ohos.bundleState' - // 异步方法promise方式 stats.queryBundleStateInfoByInterval(0, 0, 20000000000000).then(res => { console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.'); for (let i = 0; i < res.length; i++) { @@ -161,18 +118,6 @@ import stats from '@ohos.bundleState'; console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise failed, because: ' + err.code); }); - // 异步方法callback方式 - stats.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback success.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback result ' + JSON.stringify(res[i])); - } - } - }); ``` 6. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。 @@ -180,43 +125,24 @@ import stats from '@ohos.bundleState'; ```js import stats from '@ohos.bundleState' - // promise方式 stats.queryAppUsagePriorityGroup().then(res => { console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res)); }).catch(err => { console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code); }); - - // callback方式 - stats.queryAppUsagePriorityGroup((err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); - } - }); ``` -7. 判断指定Bundle Name的应用当前是否是空闲状态，config.json中不需要配置权限，三方应用只能查询自身的空闲状态。 +7. 判断指定Bundle Name的应用当前是否是空闲状态，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO，三方应用只能查询自身的空闲状态。 ```js import stats from '@ohos.bundleState' - // 异步方法promise方式 stats.isIdleState("com.ohos.camera").then(res => { console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); }).catch(err => { console.log('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code); }); - // 异步方法callback方式 - stats.isIdleState("com.ohos.camera", (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); - } - }); ``` 8. 查询FA使用记录。返回数量最大不超过maxNum设置的值，若不传入maxNum参数，则默认maxNum为1000。config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 @@ -245,32 +171,6 @@ import stats from '@ohos.bundleState'; }).catch( err=> { console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code); }); - - // 异步方法callback方式 - stats.getRecentlyUsedModules(1000, (err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i])); - } - } - }); - - // 无maNum参数异步方法callback方式 - stats.getRecentlyUsedModules((err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i])); - } - } - }); ``` 9. 通过指定起始和结束时间查询所有应用的通知次数，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 @@ -278,23 +178,12 @@ import stats from '@ohos.bundleState'; ```js import stats from '@ohos.bundleState' - // 异步方法promise方式 stats.queryAppNotificationNumber(0, 20000000000000).then(res => { console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise success.'); console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise result ' + JSON.stringify(res)); }).catch(err => { console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise failed, because: ' + err.code); }); - - // 异步方法callback方式 - stats.queryAppNotificationNumber(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback success.'); - console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback result ' + JSON.stringify(res)); - } - }); ``` 10. 通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 @@ -309,16 +198,6 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise failed, because: ' + err.code); }); - - // 异步方法callback方式 - stats.queryBundleActiveEventStates(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback success.'); - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback result ' + JSON.stringify(res)); - } - }); ``` 11. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。查询（有参）指定应用的使用优先级群组，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 @@ -333,14 +212,6 @@ import stats from '@ohos.bundleState'; console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code); }); - // 无bundleName异步方法callback方式 - stats.queryAppUsagePriorityGroup((err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); - } - }); let bundleName = "com.ohos.camera"; // 有bundleName异步promise方式 stats.queryAppUsagePriorityGroup(bundleName).then(res => { @@ -348,15 +219,6 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); }); - - // 有bundleName异步方法callback方式 - stats.queryAppUsagePriorityGroup(bundleName, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); - } - }); ``` 11. 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功 @@ -364,20 +226,11 @@ import stats from '@ohos.bundleState'; ```javascript import stats from '@ohos.bundleState' - // 异步方法promise stats.setBundleGroup(this.bundleName, this.newGroup).then(() => { console.log('BUNDLE_ACTIVE SetBundleGroup promise succeeded.'); }).catch( err => { console.log('BUNDLE_ACTIVE SetBundleGroup promise failed. because: ' + err.code); }); - // 异步方法callback - stats.setBundleGroup(this.bundleName, this.newGroup, (err) => { - if (err) { - console.log('BUNDLE_ACTIVE SetBundleGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE SetBundleGroup callback succeeded.'); - } - }); ``` 12. 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息 @@ -399,22 +252,6 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise failed. because: ' + err.code); }); - // 异步方法callback形式 - let onBundleGroupChanged = (err,res) => { - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s oldGroup is : ' + res.oldGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s newGroup is : ' + res.newGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s changeReason is : ' + res.newGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s userId is : ' + res.userId); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s bundleName is : ' + res.bundleName); - }; - stats.registerGroupCallBack(onBundleGroupChanged, (err) => { - if (err) { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback success.'); - } - }); ``` 13. 解除应用分组监听回调 @@ -428,16 +265,9 @@ import stats from '@ohos.bundleState'; }).catch(err => { console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise failed. because: ' + err.code); }); - // callback - stats.unRegisterGroupCallBack((err) => { - if (err) { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback success.'); - } - }); ``` + ## 相关实例 针对设备使用信息统计，有以下相关实例可供参考： -- [`DeviceUsageStatistics`：设备使用信息统计（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/DeviceUsageStatistics) +- [`DeviceUsageStatistics`：设备使用信息统计（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/DeviceUsageStatistics) diff --git a/zh-cn/application-dev/device/device-location-overview.md b/zh-cn/application-dev/device/device-location-overview.md index d1ca6ae0f462711023deceaab0df665287072f3e..b955a1a06d6b9b71b47d012f9a1c6fe14627fd47 100644 --- a/zh-cn/application-dev/device/device-location-overview.md +++ b/zh-cn/application-dev/device/device-location-overview.md @@ -42,4 +42,4 @@ 针对位置服务，有以下相关实例可供参考： --[`Location`：位置服务（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Location) +- [`Location`：位置服务（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Location) diff --git a/zh-cn/application-dev/device/sensor-guidelines.md b/zh-cn/application-dev/device/sensor-guidelines.md index e0dfb477374c29ce46b2885b68a568678c2a627c..9c225832d3a0abb6f8afe034baa90f4239dc2ca3 100644 --- a/zh-cn/application-dev/device/sensor-guidelines.md +++ b/zh-cn/application-dev/device/sensor-guidelines.md @@ -96,4 +96,4 @@ 针对传感器开发，有以下相关实例可供参考： -- [`Sensor`：传感器（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Sensor) \ No newline at end of file +- [`Sensor`：传感器（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Sensor) \ No newline at end of file diff --git a/zh-cn/application-dev/device/usb-guidelines.md b/zh-cn/application-dev/device/usb-guidelines.md index cd215f3a67788ae7513aad04045a75f4b78e660d..5ae59b9f4e1b5dda5ede796fa32e93616ed76999 100644 --- a/zh-cn/application-dev/device/usb-guidelines.md +++ b/zh-cn/application-dev/device/usb-guidelines.md @@ -4,7 +4,7 @@ ## 场景介绍 -Host模式下，可以获取到已经连接的设备列表，并根据需要打开和关闭设备、控制设备权限、进行数据传输等。 +Host模式下，可以获取到已经连接的USB设备列表，并根据需要打开和关闭设备、控制设备权限、进行数据传输等。 ## 接口说明 @@ -19,6 +19,7 @@ USB类开放能力如下，具体请查阅[API参考文档](../reference/apis/js | ------------------------------------------------------------ | ------------------------------------------------------------ | | hasRight(deviceName: string): boolean | 如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 | | requestRight(deviceName: string): Promise<boolean> | 请求给定软件包的临时权限以访问设备。 | +| removeRight(deviceName: string): boolean | 移除软件包对设备的访问权限。| | connectDevice(device: USBDevice): Readonly<USBDevicePipe> | 根据`getDevices()`返回的设备信息打开USB设备。 | | getDevices(): Array<Readonly<USBDevice>> | 返回USB设备列表。 | | setConfiguration(pipe: USBDevicePipe, config: USBConfig): number | 设置设备的配置。 | @@ -163,4 +164,4 @@ USB设备可作为Host设备连接Device设备进行数据传输。开发示例 针对USB管理开发，有以下相关实例可供参考： -- [`USBManager`：USB管理（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/USBManager) \ No newline at end of file +- [`USBManager`：USB管理（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/USBManager) \ No newline at end of file diff --git a/zh-cn/application-dev/device/vibrator-guidelines.md b/zh-cn/application-dev/device/vibrator-guidelines.md index 6ba0789ca707b0034ee24c91b5e48e0d7fb5bc31..21853379693b3499c68320db080072573802be59 100644 --- a/zh-cn/application-dev/device/vibrator-guidelines.md +++ b/zh-cn/application-dev/device/vibrator-guidelines.md @@ -54,4 +54,4 @@ 针对振动开发，有以下相关实例可供参考： -- [`Vibrator`：振动（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Vibrator) \ No newline at end of file +- [`Vibrator`：振动（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Vibrator) \ No newline at end of file diff --git a/zh-cn/application-dev/dfx/hiappevent-guidelines.md b/zh-cn/application-dev/dfx/hiappevent-guidelines.md index cdecfcafbb0a94aaf26271a49abd3dabd0908a83..d56dc9a859e36738bb3a819cdb73ee628da4da86 100644 --- a/zh-cn/application-dev/dfx/hiappevent-guidelines.md +++ b/zh-cn/application-dev/dfx/hiappevent-guidelines.md @@ -1,4 +1,4 @@ -# 应用事件开发指导 +# 应用事件打点开发指导 ## 场景介绍 @@ -8,7 +8,7 @@ 应用事件JS打点接口由hiAppEvent模块提供。 -以下仅提供简单的接口介绍，API接口的具体使用说明（参数使用限制、具体取值范围等），请参考[应用事件打点API文档](../reference/apis/js-apis-hiappevent.md)。 +以下仅提供简单的接口介绍，API接口的具体使用说明（参数使用限制、具体取值范围等）请参考[应用事件打点API文档](../reference/apis/js-apis-hiviewdfx-hiappevent.md)。 **打点接口功能介绍：** @@ -17,17 +17,11 @@ | write(AppEventInfo info, AsyncCallback\ callback): void | 应用事件异步打点方法，使用callback方式作为异步回调。 | | write(AppEventInfo info): Promise\ | 应用事件异步打点方法，使用Promise方式作为异步回调。 | -当采用callback作为异步回调时，可以在callback中进行下一步处理。 - -当采用Promise对象返回时，也可以在Promise对象中类似地处理接口返回值。 - -具体结果码说明见[事件校验结果码](#事件校验结果码)。 - **打点配置接口功能介绍：** -| 接口名 | 描述 | -| --------------------------------------- | ---------------------------------------------------- | -| configure(ConfigOption config): boolean | 应用事件打点配置方法，可以对打点功能进行自定义配置。 | +| 接口名 | 描述 | +| ------------------------------------ | ---------------------------------------------------- | +| configure(ConfigOption config): void | 应用事件打点配置方法，可以对打点功能进行自定义配置。 | **订阅接口功能介绍：** @@ -42,24 +36,6 @@ | ----------------- | -------------------- | | clearData(): void | 清除本地的打点数据。 | -### 事件校验结果码 - -| 错误码 | 原因 | 校验规则 | 处理结果 | -| ------ | ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | -| 0 | 无 | 事件校验成功 | 事件正常打点。 | -| -1 | 无效的事件名称 | 非空且长度在48个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | -| -2 | 无效的事件基本参数类型 | 事件名称参数必须为string。
事件类型参数必须为number类型。
事件参数必须为object类型。 | 忽略该事件，不执行打点。 | -| -4 | 无效的事件领域名称 | 非空且长度在32个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | -| -99 | 应用打点功能被关闭 | 应用打点功能被关闭。 | 忽略该事件，不执行打点。 | -| -100 | 未知错误 | 无。 | 忽略该事件，不执行打点。 | -| 1 | 无效的key参数名称 | 非空且长度在16个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。
非下划线结尾。 | 忽略该键值对参数后，继续执行打点。 | -| 2 | 无效的key参数类型 | Key参数必须为字符串类型。 | 忽略该键值对参数后，继续执行打点。 | -| 3 | 无效的value参数类型 | value参数只支持以下类型：
boolean、number、string、Array[基本类型]。 | 忽略该键值对参数后，继续执行打点。 | -| 4 | 非法长度的string类型value参数 | 参数值长度必须在8*1024个字符以内（含）。 | 对字符串进行截断（只保留前8*1024个字符）后，继续执行打点。 | -| 5 | key-value参数对数过多 | key-value参数对数必须在32对以内（含）。 | 忽略后面多余的键值对参数后，继续执行打点。 | -| 6 | 非法容量的Array类型value参数 | Array类型的value参数容量必须在100个以内（含）。 | 对数组进行截断（只保留前100个元素）后，继续执行打点。 | -| 7 | 非法类型的Array类型value参数 | Array内的参数必须为同一类型，且只能为boolean、number、string类型。 | 忽略该键值对参数后，继续执行打点。 | - ## 开发步骤 以一次应用事件打点订阅流程为例，说明开发步骤。 @@ -67,7 +43,7 @@ 1. 新建一个ets应用工程，编辑工程中的“entry > src > main > ets > pages > index.ets” 文件，依次添加三个按钮，以对应用事件打点订阅流程进行模拟。其中，按钮1模拟了应用事件打点的调用，按钮2模拟了添加自动触发回调的事件订阅者的调用，按钮3模拟了移除事件订阅者的调用，完整示例代码如下： ```ts - import hiAppEvent from '@ohos.hiAppEvent'; + import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; @Entry @Component @@ -91,10 +67,10 @@ int_data: 100, str_data: "strValue" } - }).then((value) => { - console.log(`HiAppEvent success to write event: ${value}`); + }).then(() => { + console.log(`HiAppEvent success to write event`); }).catch((err) => { - console.error(`HiAppEvent failed to write event because ${err.code}`); + console.error(`code: ${err.code}, message: ${err.message}`); }); }) diff --git a/zh-cn/application-dev/dfx/hiappevent-overview.md b/zh-cn/application-dev/dfx/hiappevent-overview.md index 49d4a3baf10bec20a6239b24835fadba32271187..0a6d27bebe4dcd32a06284d31734267413ceb86d 100644 --- a/zh-cn/application-dev/dfx/hiappevent-overview.md +++ b/zh-cn/application-dev/dfx/hiappevent-overview.md @@ -4,7 +4,7 @@ HiAppEvent提供了应用事件打点接口，为应用提供事件打点的功 ## 基本概念 -HiAppEvent模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、应用事件订阅、应用事件清理等功能。 +HiAppEvent模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 **打点**：记录由用户操作引起的变化，提供业务数据信息，以供开发、产品、运维分析。 diff --git a/zh-cn/application-dev/internationalization/intl-guidelines.md b/zh-cn/application-dev/internationalization/intl-guidelines.md index 43d9e901f50bb1f1f8a3edf1bbc74295e85b409a..585764dac20d89d1e7d5691bfa0a0e240c945f57 100644 --- a/zh-cn/application-dev/internationalization/intl-guidelines.md +++ b/zh-cn/application-dev/internationalization/intl-guidelines.md @@ -324,4 +324,4 @@ -[`International`：国际化（JS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/UI/International) --[`International`：国际化（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/International) \ No newline at end of file +-[`International`：国际化（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/International) \ No newline at end of file diff --git a/zh-cn/application-dev/media/audio-playback.md b/zh-cn/application-dev/media/audio-playback.md index 3ca354a1305c8e1282367633aba33c3c098bbac7..5b833306e08d8370f6d8433fdcc3dd91f9af01ce 100644 --- a/zh-cn/application-dev/media/audio-playback.md +++ b/zh-cn/application-dev/media/audio-playback.md @@ -266,5 +266,5 @@ export class AudioDemo { - [`JsDistributedMusicPlayer:`分布式音乐播放（JS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/JsDistributedMusicPlayer) - [`JsAudioPlayer`：音频播放和管理（JS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/JsAudioPlayer) -- [`eTsAudioPlayer`: 音频播放器（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/blob/master/media/Recorder/entry/src/main/ets/MainAbility/pages/Play.ets) -- [音频播放器（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Media/Audio_OH_ETS) \ No newline at end of file +- [`eTsAudioPlayer`: 音频播放器（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/blob/master/media/Recorder/entry/src/main/ets/MainAbility/pages/Play.ets) +- [音频播放器（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Media/Audio_OH_ETS) \ No newline at end of file diff --git a/zh-cn/application-dev/media/audio-recorder.md b/zh-cn/application-dev/media/audio-recorder.md index 94215fe834e26b66115046fbe543137371ed5912..1da8cf5cc671fb009f9442008569a30b489c6582 100644 --- a/zh-cn/application-dev/media/audio-recorder.md +++ b/zh-cn/application-dev/media/audio-recorder.md @@ -200,6 +200,6 @@ export class AudioRecorderDemo { 针对音频录制开发，有以下相关实例可供参考： -- [`Recorder:`录音机（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/Recorder) -- [`eTsAudioPlayer`: 音频播放器（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/blob/master/media/Recorder/entry/src/main/ets/MainAbility/pages/Play.ets) -- [音频播放器（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Media/Audio_OH_ETS) +- [`Recorder:`录音机（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/Recorder) +- [`eTsAudioPlayer`: 音频播放器（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/blob/master/media/Recorder/entry/src/main/ets/MainAbility/pages/Play.ets) +- [音频播放器（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Media/Audio_OH_ETS) diff --git a/zh-cn/application-dev/media/image.md b/zh-cn/application-dev/media/image.md index 3536c857eed935735b273d047314dad492106421..8d69c76aca22570ed3a875670be6d0c3496bfa74 100644 --- a/zh-cn/application-dev/media/image.md +++ b/zh-cn/application-dev/media/image.md @@ -269,5 +269,5 @@ public async init(surfaceId: any) { 针对图片开发，有以下相关实例可供参考： -- [`Image`：图片处理（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/Image) -- [`GamePuzzle`：拼图（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/GamePuzzle) \ No newline at end of file +- [`Image`：图片处理（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/Image) +- [`GamePuzzle`：拼图（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/GamePuzzle) \ No newline at end of file diff --git a/zh-cn/application-dev/media/video-playback.md b/zh-cn/application-dev/media/video-playback.md index b9f30aab7ed944d3a702adc002d6e18627b31414..ea6044a54b0774ebd6954839a29b931874e0558a 100644 --- a/zh-cn/application-dev/media/video-playback.md +++ b/zh-cn/application-dev/media/video-playback.md @@ -451,5 +451,5 @@ export class VideoPlayerDemo { ## 相关实例 针对视频播放开发，有以下相关实例可供参考： -- [`VideoPlayer:`视频播放（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/VideoPlayer) -- [视频播放器（eTS）（API 9）](https://gitee.com/openharmony/codelabs/tree/master/Media/VideoPlayerStage) \ No newline at end of file +- [`VideoPlayer:`视频播放（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/VideoPlayer) +- [视频播放器（ArkTS）（API 9）](https://gitee.com/openharmony/codelabs/tree/master/Media/VideoPlayerStage) \ No newline at end of file diff --git a/zh-cn/application-dev/napi/napi-guidelines.md b/zh-cn/application-dev/napi/napi-guidelines.md index 99035e6ecc3d55ac10888ff664e171457143ba54..84c0b827089cf8001181fa2b45b6c2b820431d57 100644 --- a/zh-cn/application-dev/napi/napi-guidelines.md +++ b/zh-cn/application-dev/napi/napi-guidelines.md @@ -643,6 +643,6 @@ export default { ``` ## 相关实例 针对Native API的开发，有以下相关实例可供参考： -- [`NativeAPI`：NativeAPI（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Native/NativeAPI) -- [第一个Native C++应用（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/NativeTemplateDemo) -- [Native Component（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/XComponent) \ No newline at end of file +- [`NativeAPI`：NativeAPI（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Native/NativeAPI) +- [第一个Native C++应用（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/NativeTemplateDemo) +- [Native Component（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/XComponent) \ No newline at end of file diff --git a/zh-cn/application-dev/notification/common-event.md b/zh-cn/application-dev/notification/common-event.md index 1ccccada26dfc008c6ecbe669007459e6a42ce51..74f52e4b4073d12b41a8f0588127c6dc6a6447da 100644 --- a/zh-cn/application-dev/notification/common-event.md +++ b/zh-cn/application-dev/notification/common-event.md @@ -175,6 +175,6 @@ if (this.subscriber != null) { 针对公共事件开发，有以下相关实例可供参考： -- [`CommonEvent`：订阅公共事件（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Notification/CommonEvent) +- [`CommonEvent`：订阅公共事件（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Notification/CommonEvent) diff --git a/zh-cn/application-dev/notification/notification-guidelines.md b/zh-cn/application-dev/notification/notification-guidelines.md index 0003426cfca8a737d6cd8245140477c3afa70efa..05e9e97a51132ca686c0a27aebb3e44ed2327f04 100644 --- a/zh-cn/application-dev/notification/notification-guidelines.md +++ b/zh-cn/application-dev/notification/notification-guidelines.md @@ -262,6 +262,6 @@ Notification.cancel(1, "label", cancelCallback) 针对通知开发，有以下相关可供参考： -- [`Notification:`订阅、发送通知（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Notification/Notification) +- [`Notification:`订阅、发送通知（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Notification/Notification) -- [`Notification`：通知（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/Notification) +- [`Notification`：通知（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/Notification) diff --git a/zh-cn/application-dev/reference/Readme-CN.md b/zh-cn/application-dev/reference/Readme-CN.md index c6b9716ee49861922570a40f60f2e1fd59a6756a..8f418c7d5b60e0926e4dd14e7480a7c44827ab7b 100644 --- a/zh-cn/application-dev/reference/Readme-CN.md +++ b/zh-cn/application-dev/reference/Readme-CN.md @@ -1,6 +1,6 @@ # 开发参考 - [Syscap列表](syscap-list.md) -- [组件参考（基于eTS的声明式开发范式）](arkui-ts/Readme-CN.md) +- [组件参考（基于ArkTS的声明式开发范式）](arkui-ts/Readme-CN.md) - [组件参考（兼容JS的类Web开发范式）](arkui-js/Readme-CN.md) - [JS服务卡片UI组件参考](js-service-widget-ui/Readme-CN.md) - [接口参考（JS及TS API）](apis/Readme-CN.md) diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index 47c0e9762aab95ac8a503c9ced5f54f2cd680d35..17505b25c3bc59bef2f0650c6b61c5544a754746 100755 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -86,8 +86,9 @@ - bundle/[ModuleInfo (ModuleInfo)](js-apis-bundle-ModuleInfo.md) - bundle/[PermissionDef (PermissionDef)](js-apis-bundle-PermissionDef.md) - bundle/[RemoteAbilityInfo (RemoteAbilityInfo)](js-apis-bundle-remoteAbilityInfo.md) - - bundle/[ShortcutInfo (ShortcutInfo)](js-apis-bundle-ShortcutInfo.md) + - bundle/[ShortcutInfo(deprecated) (ShortcutInfo)](js-apis-bundle-ShortcutInfo.md) - bundle/[PackInfo (PackInfo)](js-apis-bundle-PackInfo.md) + - bundleManager/[ShortcutInfo (ShortcutInfo)](js-apis-bundleManager-shortcutInfo.md) - UI界面 - [@ohos.animator (动画)](js-apis-animator.md) - [@ohos.curves (插值计算)](js-apis-curve.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md b/zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md index 4b35dc7f3ab6e51cba34b076656dc7c4e847d9fa..5d9652b9b8b19146444f6e689ba415becf2288e3 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md +++ b/zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md @@ -214,7 +214,7 @@ var AtManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId let permissionFlag = 1; try { - AtManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (data, err) => { + AtManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (err, data) => { if (err) { console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); } else { @@ -321,7 +321,7 @@ var AtManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId let permissionFlag = 1; try { - AtManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (data, err) => { + AtManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (err, data) => { if (err) { console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); } else { diff --git a/zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePath.md b/zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePath.md new file mode 100644 index 0000000000000000000000000000000000000000..738f1d435cc9b122042735559b2232af370c21ab --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePath.md @@ -0,0 +1,49 @@ +# 手势路径 + +GesturePath表示手势路径信息。 + +本模块用于创建辅助功能注入手势所需的手势路径信息。 + +>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> +>本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```ts +import GesturePath from "@ohos.accessibility.GesturePath"; +``` + +## GesturePath + +表示手势路径信息。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core + +### 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------------ | ---------------------------------------- | ---- | ---- | ------ | +| points | Array<[GesturePoint](js-apis-accessibility-GesturePoint.md#gesturepoint)> | 是 | 是 | 手势触摸点。 | +| durationTime | number | 是 | 是 | 手势总耗时, 单位为毫秒。 | + +### constructor + +constructor(durationTime: number); + +构造函数。 + +**系统能力**：SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| durationTime | number | 是 | 手势总耗时,单位为毫秒。 | + +**示例：** + +```typescript +let durationTime = 20; +let gesturePath = new GesturePath(durationTime); +``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md b/zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md new file mode 100644 index 0000000000000000000000000000000000000000..b5a2cd1a6c1315b6d20e1cafbde2440f14880849 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md @@ -0,0 +1,51 @@ +# 手势触摸点 + +GesturePoint表示手势触摸点。 + +本模块用于创建辅助功能注入手势所需的手势路径的触摸点信息。 + +>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> +>本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```ts +import GesturePoint from "@ohos.accessibility.GesturePoint"; +``` + +## GesturePoint + +表示手势触摸点。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core + +### 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| --------- | ------ | ---- | ---- | ------- | +| positionX | number | 是 | 是 | 触摸点X坐标。 | +| positionY | number | 是 | 是 | 触摸点Y坐标。 | + +### constructor + +constructor(positionX: number, positionY: number); + +构造函数。 + +**系统能力**：SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| positionX | number | 是 | 触摸点X坐标。 | +| positionY | number | 是 | 触摸点Y坐标。 | + +**示例：** + +```typescript +let positionX = 1; +let positionY = 2; +let gesturePoint = new GesturePoint(positionX, positionY); +``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md b/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md index a8fbb343f2b44e1e20e6be71a3005c773861774a..b82d3dfc5a8937c8c5af571e5c8088dc89415b2f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md +++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md @@ -1,8 +1,8 @@ -# AccessibilityExtensionContext +# 辅助功能扩展上下文 AccessibilityExtensionContext是AccessibilityExtensionAbility上下文环境，继承自ExtensionContext。 -AccessibilityExtensionContext模块提供扩展的上下文的能力，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。 +辅助功能扩展上下文模块提供辅助功能扩展的上下文环境的能力，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。 > **说明：** > @@ -17,7 +17,7 @@ AccessibilityExtensionContext模块提供扩展的上下文的能力，包括允 import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtensionAbility' class MainAbility extends AccessibilityExtensionAbility { onConnect(): void { - console.log("AxExtensionAbility onConnect"); + console.log('AxExtensionAbility onConnect'); let axContext = this.context; } } @@ -77,7 +77,7 @@ class MainAbility extends AccessibilityExtensionAbility { setTargetBundleName(targetNames: Array\): Promise\; -设置关注的事件类型。 +设置关注的目标包名，使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -91,19 +91,52 @@ setTargetBundleName(targetNames: Array\): Promise\; | 类型 | 说明 | | ---------------------- | --------------------- | -| Promise<boolean> | Promise对象。返回当前设置是否成功。 | +| Promise<void> | 无返回结果的Promise对象。 | **示例：** ```ts -this.context.setTargetBundleName(['com.ohos.mms']); +let targetNames = ['com.ohos.xyz']; +this.context.setTargetBundleName().then(() => { + console.info('set target bundle names success'); +}).catch((err) => { + console.error('failed to set target bundle names because ' + JSON.stringify(err)); +}); +``` + +## AccessibilityExtensionContext.setTargetBundleName + +setTargetBundleName(targetNames: Array\, callback: AsyncCallback\): void; + +设置关注的目标包名，使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ------------------- | ---- | -------- | +| targetNames | Array<string> | 是 | 关注的目标包名。 | +| callback | AsyncCallback<void> | 是 | 回调函数，如果设置关注的目标包名失败，则AsyncCallback中err有数据返回。 | + +**示例：** + +```ts +let targetNames = ['com.ohos.xyz']; +this.context.setTargetBundleName().then((err, data) => { + if (err) { + console.error('failed to set target bundle names because ' + JSON.stringify(err)); + return; + } + console.info('set target bundle names success'); +}); ``` ## AccessibilityExtensionContext.getFocusElement getFocusElement(isAccessibilityFocus?: boolean): Promise\; -获取焦点元素。 +获取焦点元素, 使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -117,77 +150,296 @@ getFocusElement(isAccessibilityFocus?: boolean): Promise\; | 类型 | 说明 | | ----------------------------------- | ---------------------- | -| Promise<AccessibilityElement> | Promise对象。返回当前对应的焦点元素。 | +| Promise<AccessibilityElement> | Promise对象，返回当前对应的焦点元素。 | **示例：** ```ts -this.context.getFocusElement().then(focusElement => { - console.log("AxExtensionAbility getFocusElement success"); -}) +let focusElement; +this.context.getFocusElement().then((data) => { + focusElement = data; + console.log('get focus element success'); +}).catch((err) => { + console.error('failed to get focus element because ' + JSON.stringify(err)); +}); ``` +## AccessibilityExtensionContext.getFocusElement + +getFocusElement(callback: AsyncCallback\): void; + +获取焦点元素, 使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<AccessibilityElement> | 是 | 回调函数，返回当前对应的焦点元素。 | + +**示例：** + +```ts +let focusElement; +this.context.getFocusElement().then((err, data) => { + if (err) { + console.error('failed to get focus element because ' + JSON.stringify(err)); + return; + } + focusElement = data; + console.info('get focus element success'); +}); +``` + +## AccessibilityExtensionContext.getFocusElement + +getFocusElement(isAccessibilityFocus: boolean, callback: AsyncCallback\): void; + +获取焦点元素, 使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------------------- | ------- | ---- | ------------------- | +| isAccessibilityFocus | boolean | 是 | 获取的是否是无障碍焦点元素。 | +| callback | AsyncCallback<AccessibilityElement> | 是 | 回调函数，返回当前对应的焦点元素。 | + +**示例：** + +```ts +let isAccessibilityFocus = true; +this.context.getFocusElement(isAccessibilityFocus).then((err, data) => { + if (err) { + console.error('failed to get focus element because ' + JSON.stringify(err)); + return; + } + focusElement = data; + console.info('get focus element success'); +}); +``` ## AccessibilityExtensionContext.getWindowRootElement getWindowRootElement(windowId?: number): Promise\; -获取窗口的根节点元素。 +获取指定窗口的根节点元素, 使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core **参数：** -| 参数名 | 参数类型 | 必填 | 说明 | -| -------- | ------ | ---- | --------------------------- | -| windowId | number | 否 | 指定获取根节点元素的窗口，未指定则从当前活跃窗口获取。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------------------- | ------- | ---- | ------------------- | +| windowId | number | 否 | 指定窗口的编号，未指定则从当前活跃窗口获取。 | **返回值：** -| 类型 | 说明 | -| ----------------------------------- | ----------------------- | -| Promise<AccessibilityElement> | Promise对象。返回当前对应的根节点元素。 | +| 类型 | 说明 | +| ----------------------------------- | ---------------------- | +| Promise<AccessibilityElement> | Promise对象，返回指定屏幕的所有窗口。 | + +**示例：** + +```ts +let rootElement; +this.context.getWindowRootElement().then((data) => { + rootElement = data; + console.log('get root element of the window success'); +}).catch((err) => { + console.error('failed to get root element of the window because ' + JSON.stringify(err)); +}); +``` + +## AccessibilityExtensionContext.getWindowRootElement + +getWindowRootElement(callback: AsyncCallback\): void; + +获取指定窗口的根节点元素, 使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<AccessibilityElement> | 是 | 回调函数，返回指定窗口的根节点元素。 | + +**示例：** + +```ts +let rootElement; +this.context.getWindowRootElement().then((err, data) => { + if (err) { + console.error('failed to get root element of the window because ' + JSON.stringify(err)); + return; + } + rootElement = data; + console.info('get root element of the window success'); +}); +``` + +## AccessibilityExtensionContext.getWindowRootElement + +getWindowRootElement(windowId: number, callback: AsyncCallback\): void; + +获取指定屏幕中的所有窗口, 使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------------------- | ------- | ---- | ------------------- | +| windowId | number | 是 | 指定窗口的编号，未指定则从当前活跃窗口获取。 | +| callback | AsyncCallback<AccessibilityElement> | 是 | 回调函数，返回指定窗口的根节点元素。 | **示例：** ```ts -this.context.getWindowRootElement().then(rootElement => { - console.log("AxExtensionAbility getWindowRootElement success"); -}) +let displayId = 10; +let rootElement; +this.context.getWindowRootElement(displayId).then((err, data) => { + if (err) { + console.error('failed to get root element of the window because ' + JSON.stringify(err)); + return; + } + rootElement = data; + console.info('get root element of the window success'); +}); ``` ## AccessibilityExtensionContext.getWindows -getWindows(displayId?: number): Promise>; +getWindows(displayId?: number): Promise\>; -获取用户可见的窗口列表。 +获取指定屏幕中的所有窗口, 使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core **参数：** -| 参数名 | 参数类型 | 必填 | 说明 | -| --------- | ------ | ---- | ------------------------- | -| displayId | number | 否 | 指定获取窗口信息的屏幕，未指定则从默认主屏幕获取。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------------------- | ------- | ---- | ------------------- | +| displayId | number | 否 | 指定的屏幕编号，未指定则从默认主屏幕获取。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------------- | ------------------------ | -| Promise<Array<AccessibilityElement>> | Promise对象。返回当前对应的窗口列表信息。 | +| 类型 | 说明 | +| ----------------------------------- | ---------------------- | +| Promise<Array<AccessibilityElement>> | Promise对象，返回指定屏幕的所有窗口。 | **示例：** ```ts -this.context.getWindows().then(windows => { - console.log("AxExtensionAbility getWindows success"); -}) +let windows; +this.context.getWindows().then((data) => { + windows = data; + console.log('get windows success'); +}).catch((err) => { + console.error('failed to get windows because ' + JSON.stringify(err)); +}); +``` + +## AccessibilityExtensionContext.getWindows + +getWindows(callback: AsyncCallback\>): void; + +获取指定屏幕中的所有窗口, 使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<Array<AccessibilityElement>> | 是 | 回调函数，返回指定屏幕的所有窗口。 | + +**示例：** + +```ts +let windows; +this.context.getWindows().then((err, data) => { + if (err) { + console.error('failed to get windows because ' + JSON.stringify(err)); + return; + } + windows = data; + console.info('get windows success'); +}); +``` + +## AccessibilityExtensionContext.getWindows + +getWindows(displayId: number, callback: AsyncCallback\>): void; + +获取指定屏幕中的所有窗口, 使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------------------- | ------- | ---- | ------------------- | +| displayId | number | 是 | 指定的屏幕编号，未指定则从默认主屏幕获取。 | +| callback | AsyncCallback<Array<AccessibilityElement>> | 是 | 回调函数，返回指定屏幕的所有窗口。 | + +**示例：** + +```ts +let displayId = 10; +let windows; +this.context.getWindows(displayId).then((err, data) => { + if (err) { + console.error('failed to get windows because ' + JSON.stringify(err)); + return; + } + windows = data; + console.info('get windows success'); +}); ``` ## AccessibilityExtensionContext.injectGesture +injectGesture(gesturePath: GesturePath): Promise\; + +注入手势，使用Promise异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| gesturePath | [GesturePath](js-apis-accessibility-GesturePath.md#gesturepath) | 是 | 表示手势的路径信息。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | ---------------------- | +| Promise<void> | 无返回结果的Promise对象。 | + +**示例：** + +```ts +import { GesturePath } from "../@ohos.accessibility.GesturePath"; +let gesturePath = new GesturePath(100); +for (let i = 0; i < 10; i++) { + let gesturePoint = new GesturePosition(100, i * 200); + gesturePath.positions.push(gesturePoint); +} +this.context.gestureInject(gesturePath, () => { + console.info('inject gesture success'); +}).catch((err) => { + console.error('failed to inject gesture because ' + JSON.stringify(err)); +}); +``` +## AccessibilityExtensionContext.injectGesture + injectGesture(gesturePath: GesturePath, callback: AsyncCallback\): void -注入手势。 +注入手势，使用callback异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -195,8 +447,8 @@ injectGesture(gesturePath: GesturePath, callback: AsyncCallback\): void | 参数名 | 参数类型 | 必填 | 说明 | | ----------- | ---------------------------------------- | ---- | -------------- | -| gesturePath | [GesturePath](js-apis-application-AccessibilityExtensionAbility.md#GesturePath) | 是 | 表示手势的路径信息。 | -| callback | AsyncCallback<void> | 是 | 表示注入手势执行结果的回调。 | +| gesturePath | [GesturePath](js-apis-accessibility-GesturePath.md#gesturepath) | 是 | 表示手势的路径信息。 | +| callback | AsyncCallback<void> | 是 | 回调函数，表示注入手势执行结果的回调。 | **示例：** @@ -206,15 +458,25 @@ for (let i = 0; i < 10; i++) { let gesturePoint = new GesturePosition(100, i * 200); gesturePath.positions.push(gesturePoint); } -this.context.gestureInject(gesturePath, (result) => { - console.info('gestureInject result: ' + result); -}) +this.context.gestureInject(gesturePath, (err, data) => { + if (err) { + console.error('failed to inject gesture because ' + JSON.stringify(err)); + return; + } + console.info('inject gesture success'); +}); ``` -## AccessibilityElement.attributeNames +## AccessibilityElement9 + +无障碍节点元素。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.BarrierFree.Accessibility.Core + +## attributeNames attributeNames\(): Promise\>; -获取节点元素的所有属性名称。 +获取节点元素的所有属性名称，使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -222,28 +484,61 @@ attributeNames\(): Promise\>; | 类型 | 说明 | | ---------------------------------------- | ------------------------ | -| Promise<Array<T>> | Promise对象。返回获取元素所有属性名称的调用结果。 | +| Promise<Array<T>> | Promise对象，返回节点元素的所有属性名称。 | **示例：** ```ts let accessibilityElement; +let attributeNames; try { - accessibilityElement.attributeNames().then((values) => { - console.log("get attribute names success"); + accessibilityElement.attributeNames().then((data) => { + console.log('get attribute names success'); + attributeNames = data; }).catch((err) => { - console.log("get attribute names err: " + JSON.stringify(err)); + console.log('get attribute names err: ' + JSON.stringify(err)); }); } catch (e) { - console.log("An unexpected error occurred. Error:" + e); + console.log('An unexpected error occurred. Error:' + e); } ``` +## attributeNames + +attributeNames\(callback: AsyncCallback\>): void; + +获取节点元素的所有属性名称，使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback<Array<T>> | 是 | 回调函数，返回节点元素的所有属性名称。 | + +**示例：** +```ts +let accessibilityElement; +let attributeNames; +try { + accessibilityElement.attributeNames().then((err, data) => { + if (err) { + console.error('failed to get attribute names because ' + JSON.stringify(err)); + return; + } + attributeNames = data; + console.info('get attribute names success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` ## AccessibilityElement.attributeValue attributeValue\(attributeName: T): Promise\; -根据属性名称获取属性值。 +根据属性名称获取属性值，使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -257,29 +552,65 @@ attributeValue\(attributeName: T): Promi | 类型 | 说明 | | ---------------------------------------- | ------------------------ | -| Promise<Array<ElementAttributeValues[T]>> | Promise对象。返回根据属性名称获取属性值的调用结果。 | +| Promise<ElementAttributeValues[T]> | Promise对象，返回根据节点属性名称获取的属性值。 | **示例：** ```ts let accessibilityElement; +let attributeValue; try { let attributeName = 'name'; - accessibilityElement.attributeValue(attributeName).then((value) => { - console.log("get attribute value by name success"); + accessibilityElement.attributeValue(attributeName).then((data) => { + console.log('get attribute value by name success'); + attribtueValue = data; }).catch((err) => { - console.log("get attribute value by name err: " + JSON.stringify(err)); + console.log('get attribute value by name err: ' + JSON.stringify(err)); }); } catch (e) { - console.log("An unexpected error occurred. Error:" + e); + console.log('An unexpected error occurred. Error:' + e); } ``` +## AccessibilityElement.attributeValue + +attributeValue\(attributeName: T, + callback: AsyncCallback\): void; + +根据属性名称获取属性值，使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| attributeName | T | 是 | 表示属性的名称。 | +| callback | AsyncCallback<ElementAttributeValues[T]> | 是 | 回调函数，返回根据节点属性名称获取的属性值。 | + +**示例：** -## AccessibilityElement.actionNames +```ts +let accessibilityElement; +let attributeValue; +try { + let attributeName = 'name'; + accessibilityElement.attributeValue(attributeName).then((err, data) => { + if (err) { + console.error('failed to get attribute value because ' + JSON.stringify(err)); + return; + } + attributeValue = data; + console.info('get attribute value success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## actionNames actionNames(): Promise\>; -获取节点元素支持的所有操作名称。 +获取节点元素支持的所有操作名称，使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -287,28 +618,61 @@ actionNames(): Promise\>; | 类型 | 说明 | | ---------------------------------------- | ------------------------ | -| Promise<Array<string>> | Promise对象。返回获取节点元素支持的所有操作名称的调用结果。 | +| Promise<Array<string>> | Promise对象，返回节点元素支持的所有操作名称。 | **示例：** ```ts let accessibilityElement; +let actionNames; try { - accessibilityElement.actionNames().then((values) => { - console.log("get action names success"); + accessibilityElement.actionNames().then((data) => { + console.log('get action names success'); + actionNames = data; }).catch((err) => { - console.log("get action names err: " + JSON.stringify(err)); + console.log('get action names err: ' + JSON.stringify(err)); }); } catch (e) { - console.log("An unexpected error occurred. Error:" + e); + console.log('An unexpected error occurred. Error:' + e); } ``` +## actionNames -## AccessibilityElement.performAction +actionNames(callback: AsyncCallback\>): void; + +获取节点元素支持的所有操作名称，使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback<Array<string>> | 是 | 回调函数，返回节点元素支持的所有操作名称。 | + +**示例：** + +```ts +let accessibilityElement; +let actionNames; +try { + accessibilityElement.actionNames().then((err, data) => { + if (err) { + console.error('failed to get action names because ' + JSON.stringify(err)); + return; + } + actionNames = data; + console.info('get action names success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## performAction performAction(actionName: string, parameters?: object): Promise\; -根据操作名称执行某个操作。 +根据操作名称执行某个操作，使用Promise异步回调。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -323,29 +687,139 @@ performAction(actionName: string, parameters?: object): Promise\; | 类型 | 说明 | | ---------------------------------------- | ------------------------ | -| Promise<Array<boolean>> | Promise对象。返回获取元素所有属性名的调用结果。 | +| Promise<boolean> | Promise对象，返回执行指定操作后的回调结果，true为执行成功，false为执行失败。 | **示例：** ```ts let accessibilityElement; +let performActionRes; try { - - accessibilityElement.performAction('action').then((result) => { - console.info('perform action result: ' + result); + accessibilityElement.performAction('action').then((data) => { + console.info('perform action success'); + performActionRes = data; }).catch((err) => { - console.log("perform action err: " + JSON.stringify(err)); + console.log('failed to perform action because ' + JSON.stringify(err)); }); } catch (e) { - console.log("An unexpected error occurred. Error:" + e); + console.log('An unexpected error occurred. Error:' + e); } ``` +## performAction + +performAction(actionName: string, callback: AsyncCallback\): void; + +根据操作名称执行某个操作，使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** -## AccessibilityElement.findElement +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| actionName | string | 是 | 表示属性的名称。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回执行指定操作后的回调结果，true为执行成功，false为执行失败。 | + +**示例：** + +```ts +let accessibilityElement; +let performActionRes; +try { + accessibilityElement.performAction('action').then((err, data) => { + if (err) { + console.error('failed to perform action because ' + JSON.stringify(err)); + return; + } + performActionRes = data; + console.info('perform action success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## performAction + +performAction(actionName: string, parameters: object, callback: AsyncCallback\): void; + +根据操作名称执行某个操作，使用callback异步回调。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| actionName | string | 是 | 表示属性的名称。 | +| parameters | object | 是 | 表示执行操作时所需要的参数。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回执行指定操作后的回调结果，true为执行成功，false为执行失败。 | + +**示例：** + +```ts +let accessibilityElement; +let actionName = 'action'; +let parameters = { + 'setText': 'test text' +}; +let performActionRes; +try { + accessibilityElement.performAction(actionName, parameters).then((err, data) => { + if (err) { + console.error('failed to perform action because ' + JSON.stringify(err)); + return; + } + performActionRes = data; + console.info('perform action success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## findElement('content') findElement(type: 'content', condition: string): Promise\>; -查询节点元素的指定内容。 +根据节点内容查询所有节点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | 是 | 固定为'content', 表示查找的类型为节点元素内容。 | +| condition | string | 是 | 表示查找的条件。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | ------------------------ | +| Promise<Array<AccessibilityElement>> | Promise对象，返回满足指定查询关键字的所有节点元素。 | + +**示例：** + +```ts +let accessibilityElement; +let type = 'content'; +let condition = 'keyword'; +let elements; +try { + accessibilityElement.findElement(type, condition).then((data) => { + elements = data; + console.log('find element success'); + }).catch((err) => { + console.log('failed to find element because ' + JSON.stringify(err)); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## findElement('content') + +findElement(type: 'content', condition: string, callback: AsyncCallback\>): void; + +根据节点内容查询所有节点元素。 **系统能力：** SystemCapability.BarrierFree.Accessibility.Core @@ -355,25 +829,175 @@ findElement(type: 'content', condition: string): Promise\ { + if (err) { + console.error('failed to find element because ' + JSON.stringify(err)); + return; + } + elements = data; + console.info('find element success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## findElement('focusType') + +findElement(type: 'focusType', condition: FocusType): Promise\; + +根据焦点元素类型查询节点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | 是 | 固定为'focusType', 表示查询的类型为节点的焦点元素类型。 | +| condition | [FocusType](#focustype) | 是 | 表示查询焦点元素的类型。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------------------ | -| Promise<Array<T>> | Promise对象。返回获取元素所有属性名的调用结果。 | +| Promise<AccessibilityElement> | Promise对象，返回满足指定查询焦点元素类型的节点元素。 | **示例：** ```ts let accessibilityElement; +let type = 'focusType'; +let condition = 'normal'; +let elements; try { - let condition = 'keyword'; - accessibilityElement.findElement('content', condition).then((values) => { - console.log("find element success"); + accessibilityElement.findElement(type, condition).then((data) => { + elements = data; + console.log('find element success'); }).catch((err) => { - console.log("find element err: " + JSON.stringify(err)); + console.log('failed to find element because ' + JSON.stringify(err)); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## findElement('focusType') + +findElement(type: 'focusType', condition: FocusType, callback: AsyncCallback\): void; + +根据焦点元素类型查询节点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | 是 | 固定为'focusType', 表示查询的类型为节点的焦点元素类型。 | +| condition | [FocusType](#focustype) | 是 | 表示查询焦点元素的类型。 | +| callback | AsyncCallback<AccessibilityElement> | 是 | 回调函数，返回满足指定查询焦点元素类型的节点元素。 | + +**示例：** + +```ts +let accessibilityElement; +let type = 'focusType'; +let condition = 'normal'; +let elements; +try { + accessibilityElement.findElement(type, condition).then((err, data) => { + if (err) { + console.error('failed to find element because ' + JSON.stringify(err)); + return; + } + elements = data; + console.info('find element success'); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## findElement('focusDirection') + +findElement(type: 'focusDirection', condition: FocusDirection): Promise\; + +根据下一焦点元素方向查询节点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | 是 | 固定为'focusDirection', 表示查询的类型为节点的下一焦点元素方向。 | +| condition | [FocusDirection](#focusdirection) | 是 | 表示查询下一焦点元素的方向。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | ------------------------ | +| Promise<AccessibilityElement> | Promise对象，返回满足指定查询下一焦点元素方向的节点元素。 | + +**示例：** + +```ts +let accessibilityElement; +let type = 'focusDirection'; +let condition = 'up'; +let elements; +try { + accessibilityElement.findElement(type, condition).then((data) => { + elements = data; + console.log('find element success'); + }).catch((err) => { + console.log('failed to find element because ' + JSON.stringify(err)); + }); +} catch (e) { + console.log('An unexpected error occurred. Error:' + e); +} +``` +## findElement('focusDirection') + +findElement(type: 'focusDirection', condition: FocusDirection, callback: AsyncCallback\): void; + +根据下一焦点元素方向查询所有节点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----------- | ---------------------------------------- | ---- | -------------- | +| type | string | 是 | 固定为'focusDirection', 表示查询的类型为节点的下一焦点元素方向。 | +| condition | [FocusDirection](#focusdirection) | 是 | 表示下一查询焦点元素的方向。 | +| callback | AsyncCallback<AccessibilityElement> | 是 | 回调函数，返回满足指定查询下一焦点元素方向的节点元素。 | + +**示例：** + +```ts +let accessibilityElement; +let type = 'focusDirection'; +let condition = 'up'; +let elements; +try { + accessibilityElement.findElement(type, condition).then((err, data) => { + if (err) { + console.error('failed to find element because ' + JSON.stringify(err)); + return; + } + elements = data; + console.info('find element success'); }); } catch (e) { - console.log("An unexpected error occurred. Error:" + e); + console.log('An unexpected error occurred. Error:' + e); } ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-accessibility.md b/zh-cn/application-dev/reference/apis/js-apis-accessibility.md index de981f480adff501aedf34b43da4e74b905d01f9..77311ac0c1b9cc3f9c26db1b916ef21dc3d1f10f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-accessibility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility.md @@ -144,7 +144,7 @@ import accessibility from '@ohos.accessibility'; ## CaptionsManager8+ -字幕配置。 +字幕配置管理，在调用CaptionsManager的方法前，需要先通过 [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8)获取 captionsManager实例。 **系统能力**：以下各项对应的系统能力均为SystemCapability.BarrierFree.Accessibility.Hearing @@ -155,90 +155,92 @@ import accessibility from '@ohos.accessibility'; | enabled | boolean | 是 | 否 | 表示是否启用字幕配置。 | | style | [CaptionsStyle](#captionsstyle8) | 是 | 否 | 表示字幕风格。 | -下列 API 示例中都需要使用 [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8) 获取 captionsManager 实例，再通过此实例调用对应的方法。 - ### on('enableChange') on(type: 'enableChange', callback: Callback<boolean>): void; -注册字幕配置启用的监听函数。 +监听字幕配置启用状态变化事件。 -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | type | string | 是 | 监听字幕配置启用状态。 | - | callback | Callback<boolean> | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 是 | 监听的事件名，固定为‘enableChange’，即字幕配置启用状态变化事件。 | +| callback | Callback<boolean> | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | -- **示例：** +**示例：** ```typescript - let captionsManager = accessibility.getCaptionsManager(); + let captionsManager = accessibility.getCaptionsManager(); captionsManager.on('enableChange',(data) => { console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) - }) + }); ``` ### on('styleChange') on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; -注册字幕风格变化的监听函数。 +监听字幕风格变化事件。 -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | type | string | 是 | 监听字幕风格变化。 | - | callback | Callback<[CaptionsStyle](#captionsstyle8)> | 是 | 回调函数，在字幕风格变化时通过此函数进行通知。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 是 | 监听的事件名，固定为‘styleChange’，即字幕风格变化事件。 | +| callback | Callback<[CaptionsStyle](#captionsstyle8)> | 是 | 回调函数，在字幕风格变化时通过此函数进行通知。 | -- **示例：** +**示例：** ```typescript - let captionsManager = accessibility.getCaptionsManager(); + let captionsManager = accessibility.getCaptionsManager(); captionsManager.on('styleChange',(data) => { console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) - }) + }); ``` ### off('enableChange') off(type: 'enableChange', callback?: Callback<boolean>): void; -移除字幕配置启用的监听函数。 +取消监听字幕配置启用状态变化事件。 -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | type | string | 是 | 监听字幕配置启用状态。 | - | callback | Callback<boolean> | 否 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 是 | 取消监听的事件名，固定为‘enableChange’，即字幕配置启用状态变化事件。 | +| callback | Callback<boolean> | 否 | 回调函数，在字幕配置启用状态变化时将状态通过此函数进行通知。 | -- **示例：** +**示例：** ```typescript - let captionsManager = accessibility.getCaptionsManager(); - captionsManager.off('enableChange') + let captionsManager = accessibility.getCaptionsManager(); + captionsManager.off('enableChange',(data) => { + console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) + }); ``` ### off('styleChange') off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; -移除字幕风格变化的监听函数。 +取消字幕风格变化监听事件。 -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | type | string | 是 | 字幕风格变化。 | - | callback | Callback<[CaptionsStyle](#captionsstyle8)> | 否 | 回调函数，在字幕风格变化时通过此函数进行通知。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 是 | 取消监听的事件名，固定为‘styleChange’，即字幕风格变化事件。 | +| callback | Callback<[CaptionsStyle](#captionsstyle8)> | 否 | 回调函数，在字幕风格变化时通过此函数进行通知。 | -- **示例：** +**示例：** ```typescript - let captionsManager = accessibility.getCaptionsManager(); - captionsManager.off('styleChange') + let captionsManager = accessibility.getCaptionsManager(); + captionsManager.off('styleChange',(data) => { + console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) + }); ``` ## EventInfo @@ -274,16 +276,20 @@ constructor(jsonObject) **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | jsonObject | string | 是 | 创建对象所需要的 JSON 格式字符串。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| jsonObject | string | 是 | 创建对象所需要的 JSON 格式字符串。 | -- **示例：** +**示例：** ```typescript - let eventInfo = new accessibility.EventInfo({"type":"click","bundleName":"com.example.MyApplication","triggerAction":"click"}) + let eventInfo = new accessibility.EventInfo({ + "type":"click", + "bundleName":"com.example.MyApplication", + "triggerAction":"click" + }); ``` ## EventType @@ -338,306 +344,348 @@ constructor(jsonObject) getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> -查询辅助应用列表。 +查询辅助应用列表，使用Promise异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 | - | stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 | +| stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 | -- **返回值：** +**返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | 返回辅助应用信息列表。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | Promise对象，返回辅助应用信息列表。 | -- **示例：** +**示例：** - ```typescript - accessibility.getAbilityLists("spoken", "enable") - .then((data) => { - console.info('success data:getAbilityList1 : ' + JSON.stringify(data)); - for (let item of data) { - console.info(item.id); - console.info(item.name); - console.info(item.description); - console.info(item.bundleName); - } - }).catch((error) => { - console.error('failed to getAbilityList1 because ' + JSON.stringify(error)); - }) - ``` +```typescript +accessibility.getAbilityLists("spoken", "enable").then((data) => { + console.info('success data:getAbilityList1 : ' + JSON.stringify(data)); + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.bundleName); + } +}).catch((err) => { + console.error('failed to getAbilityList1 because ' + JSON.stringify(err)); +}); +``` ## accessibility.getAbilityLists getAbilityLists(abilityType: AbilityType, stateType: AbilityState,callback: AsyncCallback<Array<AccessibilityAbilityInfo>>): void -查询辅助应用列表。 +查询辅助应用列表，使用callback异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 | - | stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 | - | callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | 是 | 回调函数，返回辅助应用信息列表。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 | +| stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 | +| callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | 是 | 回调函数，返回辅助应用信息列表。 | -- **示例：** +**示例：** - ```typescript - accessibility.getAbilityLists("visual", "enable", (err, data) => { - if (err) { - console.error('failed to getAbilityList2 because ' + JSON.stringify(err)); - return; - } - console.info('success data:getAbilityList2 : ' + JSON.stringify(data)); - for (let item of data) { - console.info(item.id); - console.info(item.name); - console.info(item.description); - console.info(item.bundleName); - } - }) +```typescript +accessibility.getAbilityLists("visual", "enable", (err, data) => { + if (err) { + console.error('failed to getAbilityList2 because ' + JSON.stringify(err)); + return; + } + console.info('success data:getAbilityList2 : ' + JSON.stringify(data)); + for (let item of data) { + console.info(item.id); + console.info(item.name); + console.info(item.description); + console.info(item.bundleName); + } +}); ``` ## accessibility.getCaptionsManager8+ getCaptionsManager(): CaptionsManager -获取无障碍字幕配置。 +获取无障碍字幕配置管理实例。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing -- **返回值：** +**返回值：** - | 类型 | 说明 | - | -------- | -------- | - | [CaptionsManager](#captionsmanager8) | 无障碍字幕配置管理。 | +| 类型 | 说明 | +| -------- | -------- | +| [CaptionsManager](#captionsmanager8) | 无障碍字幕配置管理。 | -- **示例：** +**示例：** - ```typescript - let captionsManager = accessibility.getCaptionsManager() - ``` +```typescript +let captionsManager = accessibility.getCaptionsManager(); +``` -## accessibility.on('accessibilityStateChange' | 'touchGuideStateChange') +## accessibility.on('accessibilityStateChange') -on(type: 'accessibilityStateChange' | 'touchGuideStateChange', callback: Callback<boolean>): void +on(type: 'accessibilityStateChange', callback: Callback<boolean>): void -启用辅助应用和触摸浏览功能的状态变化监听。 +监听辅助应用启用状态变化事件。 **系统能力**：以下各项对应的系统能力有所不同，详见下表。 -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | type | string | 是 | 监听的事件类型。
- type 为'accessibilityStateChange'时表示监听类型为辅助功能启用状态变化监听；
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- type 为'touchGuideStateChange'时表示监听类型为触摸浏览启用状态变化监听。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision | - | callback | Callback<boolean> | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 是 | 监听的事件名，固定为‘accessibilityStateChange’，即辅助应用启用状态变化事件。 | +| callback | Callback<boolean> | 是 | 回调函数，在辅助应用启用状态变化时将状态通过此函数进行通知。 | -- **示例：** +**示例：** - ```typescript - accessibility.on('accessibilityStateChange',(data) => { - console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) - }) - ``` +```typescript +accessibility.on('accessibilityStateChange',(data) => { + console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) +}); +``` -## accessibility.off('accessibilityStateChange' | 'touchGuideStateChange') +## accessibility.on('touchGuideStateChange') -off(type: ‘accessibilityStateChange ’ | ‘touchGuideStateChange’, callback?: Callback<boolean>): void +on(type: 'touchGuideStateChange', callback: Callback<boolean>): void -关闭辅助应用和触摸浏览功能的状态变化监听。 +监听触摸浏览功能启用状态变化事件。 **系统能力**：以下各项对应的系统能力有所不同，详见下表。 -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | type | string | 否 | 监听的事件类型。
- type 为'accessibilityStateChange'时表示监听类型为辅助功能启用状态变化监听；
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- type 为'touchGuideStateChange'时表示监听类型为触摸浏览启用状态变化监听。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision | - | callback | Callback<boolean> | 否 | 要取消的监听回调函数。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 是 | 监听的事件名，固定为‘touchGuideStateChange’，即触摸浏览启用状态变化事件。 | +| callback | Callback<boolean> | 是 | 回调函数，在触摸浏览启用状态变化时将状态通过此函数进行通知。 | -- **示例：** +**示例：** - ```typescript - accessibility.off('accessibilityStateChange',(data) => { - console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) - }) - ``` +```typescript +accessibility.on('touchGuideStateChange',(data) => { + console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) +}); +``` + +## accessibility.off('accessibilityStateChange') + +off(type: 'accessibilityStateChange', callback?: Callback<boolean>): void + +取消监听辅助应用启用状态变化事件。 + +**系统能力**：以下各项对应的系统能力有所不同，详见下表。 + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 否 | 取消监听的事件名，固定为‘accessibilityStateChange’，即辅助应用启用状态变化事件。 | +| callback | Callback<boolean> | 否 | 回调函数，在辅助应用启用状态变化时将状态通过此函数进行通知。 | + +**示例：** + +```typescript +accessibility.off('accessibilityStateChange',(data) => { + console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) +}); +``` + +## accessibility.off('touchGuideStateChange') + +off(type: 'touchGuideStateChange', callback?: Callback<boolean>): void + +取消监听触摸浏览启用状态变化事件。 + +**系统能力**：以下各项对应的系统能力有所不同，详见下表。 + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| type | string | 否 | 取消监听的事件名，固定为‘touchGuideStateChange’，即触摸浏览启用状态变化事件。 | +| callback | Callback<boolean> | 否 | 回调函数，在触摸浏览启用状态变化时将状态通过此函数进行通知。 | + +**示例：** + +```typescript +accessibility.off('touchGuideStateChange',(data) => { + console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) +}); +``` ## accessibility.isOpenAccessibility isOpenAccessibility(): Promise<boolean> -判断是否启用了辅助功能。 +判断是否启用了辅助功能, 使用Promise异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **返回值：** +**返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<boolean> | 如果辅助功能已启用，则返回 true；否则返回 false。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<boolean> | Promise对象，如果辅助功能已启用，则返回 true；否则返回 false。 | -- **示例：** +**示例：** - ```typescript - accessibility.isOpenAccessibility() - .then((data) => { - console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) - }).catch((error) => { - console.error('failed to isOpenAccessibility because ' + JSON.stringify(error)); - }) - ``` +```typescript +accessibility.isOpenAccessibility().then((data) => { + console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) +}).catch((err) => { + console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); +}); +``` ## accessibility.isOpenAccessibility isOpenAccessibility(callback: AsyncCallback<boolean>): void -判断是否启用了辅助功能。 +判断是否启用了辅助功能，使用callback异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | 是 | 回调函数，如果辅助功能已启用，则返回 true；否则返回 false。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数，如果辅助功能已启用，则返回 true；否则返回 false。 | -- **示例：** +**示例：** - ```typescript - accessibility.isOpenAccessibility((err, data) => { - if (err) { - console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); - return; - } - console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) - }) - ``` +```typescript +accessibility.isOpenAccessibility((err, data) => { + if (err) { + console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); + return; + } + console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) +}); +``` ## accessibility.isOpenTouchGuide isOpenTouchGuide(): Promise<boolean> -判断触摸浏览模式是否开启。 +判断触摸浏览模式是否开启, 使用Promise异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Vision -- **返回值：** +**返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<boolean> | 如果触摸浏览模式已开启，则返回 true；否则返回 false。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<boolean> | Promise对象，如果触摸浏览模式已开启，则返回 true；否则返回 false。 | -- **示例：** +**示例：** - ```typescript - accessibility.isOpenTouchGuide() - .then((data) => { - console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) - }).catch((error) => { - console.error('failed to isOpenTouchGuide because ' + JSON.stringify(error)); - }) - ``` +```typescript +accessibility.isOpenTouchGuide().then((data) => { + console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) +}).catch((err) => { + console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); +}); +``` ## accessibility.isOpenTouchGuide isOpenTouchGuide(callback: AsyncCallback<boolean>): void -判断触摸浏览模式是否开启。 +判断触摸浏览模式是否开启, 使用callback异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Vision -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | 是 | 回调函数，如果触摸浏览模式已开启，则返回 true；否则返回 false。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数，如果触摸浏览模式已开启，则返回 true；否则返回 false。 | -- **示例：** +**示例：** - ```typescript - accessibility.isOpenTouchGuide((err, data) => { - if (err) { - console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); - return; - } - console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) - }) +```typescript +accessibility.isOpenTouchGuide((err, data) => { + if (err) { + console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); + return; + } + console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) +}); ``` ## accessibility.sendEvent sendEvent(event: EventInfo): Promise<void> -发送无障碍事件。 +发送无障碍事件, 使用Promise异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | event | [EventInfo](#eventinfo) | 是 | 无障碍事件对象。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| event | [EventInfo](#eventinfo) | 是 | 无障碍事件对象。 | -- **返回值：** +**返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 以 Promise 形式返回结果，如果发送无障碍事件成功，则 data 有数据返回；如果发送无障碍事件失败，则 err 有数据返回。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | 无返回结果的Promise对象。 | -- **示例：** +**示例：** - ```typescript - let eventInfo : accessibility.EventInfo = { - type: 'focus', - bundleName: 'bundle', - triggerAction: 'focus' - } - accessibility.sendEvent(eventInfo) - .then((data) => { - console.info('success data:sendEvent : ' + JSON.stringify(data)) - }).catch((error) => { - console.error('failed to sendEvent because ' + JSON.stringify(error)); - }) - ``` +```typescript +let eventInfo = new accessibility.EventInfo({ + "type":"click", + "bundleName":"com.example.MyApplication", + "triggerAction":"click" +}); +accessibility.sendEvent(eventInfo).then(() => { + console.info('send event success'); +}).catch((err) => { + console.error('failed to sendEvent because ' + JSON.stringify(err)); +}); +``` ## accessibility.sendEvent sendEvent(event: EventInfo, callback: AsyncCallback<void>): void -发送无障碍事件。 +发送无障碍事件, 使用callback异步回调。 **系统能力**：SystemCapability.BarrierFree.Accessibility.Core -- **参数：** +**参数：** - | 参数名 | 参数类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | event | [EventInfo](#eventinfo) | 是 | 辅助事件对象。 | - | callback | AsyncCallback<void> | 是 | 回调函数，如果发送无障碍事件成功，则 AsyncCallback 中 data 有数据返回；如果发送无障碍事件失败，则 AsyncCallback 中 err 有数据返回。 | +| 参数名 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| event | [EventInfo](#eventinfo) | 是 | 辅助事件对象。 | +| callback | AsyncCallback<void> | 是 | 回调函数，如果发送无障碍事件失败，则 AsyncCallback中err有数据返回。 | -- **示例：** +**示例：** - ```typescript - let eventInfo : accessibility.EventInfo = { - type: 'focus', - bundleName: 'bundle', - triggerAction: 'focus' - } - accessibility.sendEvent(eventInfo,(err, data) => { - if (err) { - console.error('failed to sendEvent because ' + JSON.stringify(err)); - return; - } - console.info('success data:sendEvent : ' + JSON.stringify(data)) - }) +```typescript +let eventInfo = new accessibility.EventInfo({ + "type":"click", + "bundleName":"com.example.MyApplication", + "triggerAction":"click" +}); +accessibility.sendEvent(eventInfo, (err, data) => { + if (err) { + console.error('failed to sendEvent because ' + JSON.stringify(err)); + return; + } + console.info('sendEvent success'); +}); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-appAccount.md b/zh-cn/application-dev/reference/apis/js-apis-appAccount.md index cbe6af5410c204f20bcfbe623b95bf7d71be0117..a11141d837c647265bb39b925f4d3a54d5cf6d28 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-appAccount.md +++ b/zh-cn/application-dev/reference/apis/js-apis-appAccount.md @@ -40,7 +40,7 @@ createAppAccountManager(): AppAccountManager createAccount(name: string, callback: AsyncCallback<void>): void; -将此应用的帐号名添加到帐号管理服务中，使用callback回调异步返回结果。 +将此应用的帐号名添加到帐号管理服务中。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -49,7 +49,16 @@ createAccount(name: string, callback: AsyncCallback<void>): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | -------------------- | | name | string | 是 | 要添加的应用帐号名称。 | -| callback | AsyncCallback<void> | 是 | 将此应用的帐号名添加到帐号管理服务回调。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当此应用的帐号名添加到帐号管理服务成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or options. | + | 12300008 | the account indicated by name already exist. | + | 12300011 | the account number has reached the upper limit. | **示例：** @@ -66,9 +75,9 @@ createAccount(name: string, callback: AsyncCallback<void>): void; ### createAccount9+ -createAccount(name: string, extraInfo: string, callback: AsyncCallback<void>): void +createAccount(name: string, options: CreateAccountOptions, callback: AsyncCallback<void>): void -将此应用程序的帐号名和额外信息（能转换string类型的其它信息，如token）添加到帐号管理服务中，使用callback回调异步返回结果。 +将此应用程序的帐号名和额外信息（能转换string类型的其它信息，如token）添加到帐号管理服务中。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -77,15 +86,29 @@ createAccount(name: string, extraInfo: string, callback: AsyncCallback<void&g | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------- | ---- | ---------------------------------------- | | name | string | 是 | 要添加的应用帐号名称。 | -| extraInfo | string | 是 | 要添加的应用帐号的额外信息(能转换string类型的其它信息，如token等)，额外信息不能是应用帐号的敏感信息（如应用账号密码）。 | -| callback | AsyncCallback<void> | 是 | 将此应用程序的帐号名和额外信息添加到帐号管理服务中回调。 | +| options | [CreateAccountOptions](#createaccountoptions9) | 是 | 要添加的应用帐号的选项，选项中不能包含应用帐号的敏感信息（如应用帐号密码）。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当此应用程序的帐号名和额外信息添加到帐号管理服务成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or options. | + | 12300008 | the account indicated by name already exist. | + | 12300011 | the account number has reached the upper limit. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.createAccount("LiSi", "token101", (err) => { + var option : CreateAccountOptions = { + customData: { + "age":10 + } + } + appAccountManager.createAccount("LiSi", option, (err) => { console.log("createAccount err: " + JSON.stringify(err)); }); } catch (err) { @@ -97,7 +120,7 @@ createAccount(name: string, extraInfo: string, callback: AsyncCallback<void&g createAccount(name: string, extraInfo?: string): Promise<void> -将此应用的帐号名或额外信息（能转换成string类型的其它信息）添加到帐号管理服务中，使用Promise方式异步返回结果。 +将此应用的帐号名或额外信息（能转换成string类型的其它信息）添加到帐号管理服务中。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -106,20 +129,34 @@ createAccount(name: string, extraInfo?: string): Promise<void> | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 要添加的应用帐号名称。 | -| extraInfo | string | 否 | 要添加的应用帐号的额外信息（能转换成string类型的其它信息），额外信息不能是应用帐号的敏感信息（如应用账号密码）。 | +| options | [CreateAccountOptions](#createaccountoptions9) | 否 | 要添加的应用帐号的选项，选项中不能包含应用帐号的敏感信息（如应用帐号密码），不填写不附带选项信息。 | **返回值：** | 类型 | 说明 | | ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or options. | + | 12300008 | the account indicated by name already exist. | + | 12300011 | the account number has reached the upper limit. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.createAccount("LiSi", "token101").then(()=> { + var option : CreateAccountOptions = { + customData: { + "age":10 + } + } + appAccountManager.createAccount("LiSi", option).then(()=> { console.log('createAccount Success'); }).catch((err) => { console.log("createAccount err: " + JSON.stringify(err)); @@ -129,98 +166,6 @@ createAccount(name: string, extraInfo?: string): Promise<void> } ``` -### addAccount(deprecated) - -addAccount(name: string, callback: AsyncCallback<void>): void - -将此应用的帐号名添加到帐号管理服务中，使用callback回调异步返回结果。 - -> **说明：** -> 从API version 9开始废弃, 建议使用[createAccount](#createaccount9)替代 -> -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | -------------------- | -| name | string | 是 | 要添加的应用帐号名称。 | -| callback | AsyncCallback<void> | 是 | 将此应用的帐号名添加到帐号管理服务回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.addAccount("WangWu", (err) => { - console.log("addAccount err: " + JSON.stringify(err)); - }); - ``` - -### addAccount(deprecated) - -addAccount(name: string, extraInfo: string, callback: AsyncCallback<void>): void - -将此应用程序的帐号名和额外信息（能转换string类型的其它信息，如token）添加到帐号管理服务中，使用callback回调异步返回结果。 - -> **说明：** > 从API version 9开始废弃, 建议使用[createAccount](#createaccount9-1)替代 -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------------------------- | ---- | ---------------------------------------- | -| name | string | 是 | 要添加的应用帐号名称。 | -| extraInfo | string | 是 | 要添加的应用帐号的额外信息(能转换string类型的其它信息，如token等)，额外信息不能是应用帐号的敏感信息（如应用账号密码）。 | -| callback | AsyncCallback<void> | 是 | 将此应用程序的帐号名和额外信息添加到帐号管理服务中回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.addAccount("LiSi", "token101", (err) => { - console.log("addAccount err: " + JSON.stringify(err)); - }); - ``` - -### addAccount(deprecated) - -addAccount(name: string, extraInfo?: string): Promise<void> - -将此应用的帐号名或额外信息（能转换成string类型的其它信息）添加到帐号管理服务中，使用Promise方式异步返回结果。 - -> **说明：** > 从API version 9开始废弃, 建议使用[createAccount](#createaccount9-2)替代 -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | ---------------------------------------- | -| name | string | 是 | 要添加的应用帐号名称。 | -| extraInfo | string | 否 | 要添加的应用帐号的额外信息（能转换成string类型的其它信息），额外信息不能是应用帐号的敏感信息（如应用账号密码）。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.addAccount("LiSi", "token101").then(()=> { - console.log('addAccount Success'); - }).catch((err) => { - console.log("addAccount err: " + JSON.stringify(err)); - }); - ``` - ### createAccountImplicitly9+ createAccountImplicitly(owner: string, callback: AuthCallback): void @@ -236,6 +181,15 @@ createAccountImplicitly(owner: string, callback: AuthCallback): void | owner | string | 是 | 要添加的应用帐号所有者包名。 | | callback | [AuthCallback](#authcallback9) | 是 | 认证回调，用于返回鉴权结果。 | +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or options. | + | 12300011 | the account number has reached the upper limit. | + | 12300008 | the account authenticator service does not exist. | + **示例：** ```js @@ -280,6 +234,15 @@ createAccountImplicitly(owner: string, options: CreateAccountImplicitlyOptions, | options | [CreateAccountImplicitlyOptions](#createaccountimplicitlyoptions9) | 是 | 隐式创建账号的选项。 | | callback | [AuthCallback](#authcallback9) | 是 | 认证回调，用于返回鉴权结果。 | +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or options. | + | 12300011 | the account number has reached the upper limit. | + | 12300008 | the account authenticator service does not exist. | + **示例：** ```js @@ -310,56 +273,11 @@ createAccountImplicitly(owner: string, options: CreateAccountImplicitlyOptions, ``` -### addAccountImplicitly(deprecated) - -addAccountImplicitly(owner: string, authType: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void - -根据指定的帐号所有者、鉴权类型和可选项隐式地添加应用帐号，并使用callback回调异步返回结果。 - -> **说明：** 从API version 9开始废弃, 建议使用[createAccountImplicitly](#createaccountimplicitly9)替代。 -> -> 从 API version 8开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | ----------------------- | -| owner | string | 是 | 要添加的应用帐号所有者包名。 | -| authType | string | 是 | 要添加的应用帐号鉴权类型。鉴权类型为自定义。 | -| options | {[key: string]: any} | 是 | 鉴权所需要的可选项。可选项可根据自己需要设置。 | -| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 认证器回调，用于返回鉴权结果。 | - -**示例：** - - ```js - import featureAbility from '@ohos.ability.featureAbility'; - - function onResultCallback(code, result) { - console.log("resultCode: " + code); - console.log("result: " + JSON.stringify(result)); - } - - function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err)=>{ - console.log("startAbility err: " + JSON.stringify(err)); - }); - } - - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.addAccountImplicitly("com.example.ohos.accountjsdemo", "getSocialData", {}, { - onResult: onResultCallback, - onRequestRedirected: onRequestRedirectedCallback - }); - ``` - ### removeAccount9+ removeAccount(name: string, callback: AsyncCallback<void>): void -从帐号管理服务中移除应用帐号，使用callback回调异步返回结果。 +从帐号管理服务中移除应用帐号。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -368,7 +286,15 @@ removeAccount(name: string, callback: AsyncCallback<void>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------------- | | name | string | 是 | 要删除的应用帐号名称。 | -| callback | AsyncCallback<void> | 是 | 帐号管理服务中移除应用帐号的回调。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当帐号管理服务中移除应用帐号成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name. | + | 12300003 | the account indicated by name dose not exist. | **示例：** @@ -388,7 +314,7 @@ removeAccount(name: string, callback: AsyncCallback<void>): void deleteAccount(name: string): Promise<void> -从帐号管理服务中移除应用帐号，使用Promise方式异步返回结果。 +从帐号管理服务中移除应用帐号。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -402,7 +328,15 @@ deleteAccount(name: string): Promise<void> | 类型 | 说明 | | :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name. | + | 12300003 | the account indicated by name dose not exist. | **示例：** @@ -420,69 +354,6 @@ deleteAccount(name: string): Promise<void> ``` -### deleteAccount(deprecated) - -deleteAccount(name: string, callback: AsyncCallback<void>): void - -从帐号管理服务中删除应用帐号，使用callback回调异步返回结果。 - -> **说明：** 从API version 9开始废弃, 建议使用[removeAccount](#removeaccount9)替代。 -> -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ---------------- | -| name | string | 是 | 要删除的应用帐号名称。 | -| callback | AsyncCallback<void> | 是 | 帐号管理服务中删除应用帐号回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.deleteAccount("ZhaoLiu", (err) => { - console.log("deleteAccount err: " + JSON.stringify(err)); - }); - ``` - -### deleteAccount(deprecated) - -deleteAccount(name: string): Promise<void> - -从帐号管理服务中删除应用帐号，使用Promise方式异步返回结果。 - -> **说明：** 从API version 9开始废弃, 建议使用[removeAccount](#removeaccount9)替代。 -> -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | ----------- | -| name | string | 是 | 要删除的应用帐号名称。 | - -**返回值：** - -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.deleteAccount("ZhaoLiu").then(() => { - console.log('deleteAccount Success'); - }).catch((err) => { - console.log("deleteAccount err: " + JSON.stringify(err)); - }); - ``` - ### setAppAccess9+ setAppAccess(name: string, bundleName: string, isAccessible: boolean, callback: AsyncCallback<void>): void @@ -500,6 +371,15 @@ setAppAccess(name: string, bundleName: string, isAccessible: boolean, callback: | isAccessible | boolean | 是 | 访问控制，允许访问或禁止访问。 | | callback | AsyncCallback<void> | 是 | 访问权限设置的回调。 | +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or bundlename. | + | 12300003 | the account indicated by localId dose not exist. | + | 12400001 | the application indicated by bundlename does not exist. | + **示例：** ```js @@ -518,7 +398,7 @@ setAppAccess(name: string, bundleName: string, isAccessible: boolean, callback: setAppAccess(name: string, bundleName: string, isAccessible: boolean): Promise<void> -设置指定第三方应用帐号名称对指定包名称的第三方应用的访问权限，由isAccessible指明是允许访问还是禁止访问，使用Promise方式异步返回结果。 +设置指定第三方应用帐号名称对指定包名称的第三方应用的访问权限，由isAccessible指明是允许访问还是禁止访问。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -534,7 +414,16 @@ setAppAccess(name: string, bundleName: string, isAccessible: boolean): Promise&l | 类型 | 说明 | | :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or bundlename. | + | 12300003 | the account indicated by localId dose not exist. | + | 12400001 | the application indicated by bundlename does not exist. | **示例：** @@ -551,15 +440,11 @@ setAppAccess(name: string, bundleName: string, isAccessible: boolean): Promise&l } ``` -### disableAppAccess(deprecated) - -disableAppAccess(name: string, bundleName: string, callback: AsyncCallback<void>): void +### checkAppAccess9+ -禁止指定第三方应用帐号名称对指定的第三方应用进行访问，使用callback回调异步返回结果。 +checkAppAccess(name: string, bundleName: string, callback: AsyncCallback<boolean>): void -> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9)替代。 -> -> 从 API version 7开始支持。 +查看指定第三方应用帐号名称对指定包名称的第三方应用的访问权限，callback回调异步返回结果。 **系统能力：** SystemCapability.Account.AppAccount @@ -567,170 +452,62 @@ disableAppAccess(name: string, bundleName: string, callback: AsyncCallback<vo | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------------------------- | ---- | --------------------------------- | -| name | string | 是 | 要禁用访问的第三方应用帐号名称。 | +| name | string | 是 | 应用帐号名称。 | | bundleName | string | 是 | 第三方应用的包名。 | -| callback | AsyncCallback<void> | 是 | 禁止指定第三方应用帐号名称对指定包名称的第三方应用进行访问的回调。 | +| callback | AsyncCallback<void> | 是 | 查看访问权限的回调。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or bundlename. | + | 12300003 | the account indicated by localId dose not exist. | + | 12400001 | the application indicated by bundlename does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.disableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo", (err) => { - console.log("disableAppAccess err: " + JSON.stringify(err)); - }); - ``` + try { + appAccountManager.checkAppAccess("ZhangSan", "com.example.ohos.accountjsdemo", (err) => { + console.log("checkAppAccess: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("checkAppAccess: " + JSON.stringify(err)); + } -### disableAppAccess(deprecated) + ``` -disableAppAccess(name: string, bundleName: string): Promise<void> +### checkAppAccess9+ -禁止指定第三方应用帐号名称对指定包名称的第三方应用进行访问，使用Promise方式异步返回结果。 +checkAppAccess(name: string, bundleName: string): Promise<void> -> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9-1)替代。 -> -> 从 API version 7开始支持。 +查看指定第三方应用帐号名称对指定包名称的第三方应用的访问权限。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ---------------- | -| name | string | 是 | 要禁用访问的第三方应用帐号名称。 | -| bundleName | string | 是 | 第三方应用的包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | --------- | +| name | string | 是 | 应用帐号名称。 | +| bundleName | string | 是 | 第三方应用的包名。 | **返回值：** | 类型 | 说明 | | :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | -**示例：** +**错误码：** - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.disableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo").then(() => { - console.log('disableAppAccess Success'); - }).catch((err) => { - console.log("disableAppAccess err: " + JSON.stringify(err)); - }); - ``` - -### enableAppAccess(deprecated) - -enableAppAccess(name: string, bundleName: string, callback: AsyncCallback<void>): void - -允许指定第三方应用帐号名称对指定包名称的第三方应用进行访问，使用callback回调异步返回结果。 - -> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9)替代。 -> -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------------- | ---- | --------------------------------- | -| name | string | 是 | 应用帐号名称。 | -| bundleName | string | 是 | 第三方应用的包名。 | -| callback | AsyncCallback<void> | 是 | 允许指定第三方应用帐号名称对指定包名称的第三方应用进行访问的回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.enableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo", (err) => { - console.log("enableAppAccess: " + JSON.stringify(err)); - }); - ``` - -### enableAppAccess(deprecated) - -enableAppAccess(name: string, bundleName: string): Promise<void> - -允许指定第三方应用帐号的名称对指定包名称的第三方应用进行访问，使用Promise方式异步返回结果。 - -> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9-1)替代。 -> -> 从 API version 7开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | --------- | -| name | string | 是 | 应用帐号名称。 | -| bundleName | string | 是 | 第三方应用的包名。 | - -**返回值：** - -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.enableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo").then(() => { - console.log('enableAppAccess Success'); - }).catch((err) => { - console.log("enableAppAccess err: " + JSON.stringify(err)); - }); - ``` - -### checkAppAccess9+ - -checkAppAccess(name: string, bundleName: string, callback: AsyncCallback<boolean>): void - -查看指定第三方应用帐号名称对指定包名称的第三方应用的访问权限，callback回调异步返回结果。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------------- | ---- | --------------------------------- | -| name | string | 是 | 应用帐号名称。 | -| bundleName | string | 是 | 第三方应用的包名。 | -| callback | AsyncCallback<void> | 是 | 查看访问权限的回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.checkAppAccess("ZhangSan", "com.example.ohos.accountjsdemo", (err) => { - console.log("checkAppAccess: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("checkAppAccess: " + JSON.stringify(err)); - } - - ``` - -### checkAppAccess9+ - -checkAppAccess(name: string, bundleName: string): Promise<void> - -查看指定第三方应用帐号名称对指定包名称的第三方应用的访问权限，使用Promise方式异步返回结果。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | --------- | -| name | string | 是 | 应用帐号名称。 | -| bundleName | string | 是 | 第三方应用的包名。 | - -**返回值：** - -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or bundlename. | + | 12300003 | the account indicated by localId dose not exist. | + | 12400001 | the application indicated by bundlename does not exist. | **示例：** @@ -752,7 +529,7 @@ checkAppAccess(name: string, bundleName: string): Promise<void> checkDataSyncEnabled(name: string, callback: AsyncCallback<boolean>): void -检查指定应用帐号是否允许应用数据同步，使用callback回调异步返回结果。 +检查指定应用帐号是否允许应用数据同步。使用callback异步回调。 **需要权限：** ohos.permission.DISTRIBUTED_DATASYNC @@ -763,7 +540,15 @@ checkDataSyncEnabled(name: string, callback: AsyncCallback<boolean>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | --------------------- | | name | string | 是 | 应用帐号名称。 | -| callback | AsyncCallback<boolean> | 是 | 检查指定应用帐号是否允许应用数据同步回调。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示指定应用帐号允许应用数据同步；返回false表示指定应用帐号不允许应用数据同步。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name. | + | 12300003 | the account indicated by localId dose not exist. | **示例：** @@ -784,7 +569,7 @@ checkDataSyncEnabled(name: string, callback: AsyncCallback<boolean>): void checkDataSyncEnabled(name: string): Promise<boolean> -检查指定应用帐号是否允许应用数据同步，使用Promise方式异步返回结果。 +检查指定应用帐号是否允许应用数据同步。使用Promise异步回调。 **需要权限：** ohos.permission.DISTRIBUTED_DATASYNC @@ -800,7 +585,15 @@ checkDataSyncEnabled(name: string): Promise<boolean> | 类型 | 说明 | | :--------------------- | :-------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果。 | +| Promise<boolean> | Promise对象。返回true表示允许应用数据同步；返回false表示不允许应用数据同步。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name. | + | 12300003 | the account indicated by localId dose not exist. | **示例：** @@ -818,79 +611,11 @@ checkDataSyncEnabled(name: string): Promise<boolean> ``` -### checkAppAccountSyncEnable(deprecated) - -checkAppAccountSyncEnable(name: string, callback: AsyncCallback<boolean>): void - -检查指定应用帐号是否允许应用数据同步，使用callback回调异步返回结果。 - -> **说明：** 从API version 9开始废弃。建议使用[checkDataSyncEnabled](#checkdatasyncenabled9)替代。 -> -> 从 API version 7开始支持。 - -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | --------------------- | -| name | string | 是 | 应用帐号名称。 | -| callback | AsyncCallback<boolean> | 是 | 检查指定应用帐号是否允许应用数据同步回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.checkAppAccountSyncEnable("ZhangSan", (err, result) => { - console.log("checkAppAccountSyncEnable err: " + JSON.stringify(err)); - console.log('checkAppAccountSyncEnable result: ' + result); - }); - ``` - -### checkAppAccountSyncEnable(deprecated) - -checkAppAccountSyncEnable(name: string): Promise<boolean> - -检查指定应用帐号是否允许应用数据同步，使用Promise方式异步返回结果。 - -> **说明：** 从API version 9开始废弃。建议使用[checkDataSyncEnabled](#checkdatasyncenabled9-1)替代。 -> -> 从 API version 7开始支持。 - -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | ------- | -| name | string | 是 | 应用帐号名称。 | - -**返回值：** - -| 类型 | 说明 | -| :--------------------- | :-------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.checkAppAccountSyncEnable("ZhangSan").then((data) => { - console.log('checkAppAccountSyncEnable, result: ' + data); - }).catch((err) => { - console.log("checkAppAccountSyncEnable err: " + JSON.stringify(err)); - }); - ``` - ### setCredential9+ setCredential(name: string, credentialType: string, credential: string,callback: AsyncCallback<void>): void -设置此应用程序帐号的凭据，使用callback回调异步返回结果。 +设置此应用程序帐号的凭据。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount @@ -901,7 +626,15 @@ setCredential(name: string, credentialType: string, credential: string,callback: | name | string | 是 | 应用程序帐号名称。 | | credentialType | string | 是 | 要设置的凭据类型。 | | credential | string | 是 | 要设置的凭据。 | -| callback | AsyncCallback<void> | 是 | 设置此应用帐号的凭据回调。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置此应用程序帐号的凭据成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or credentialType. | + | 12300003 | the account indicated by localId dose not exist. | **示例：** @@ -920,7 +653,7 @@ setCredential(name: string, credentialType: string, credential: string,callback: setCredential(name: string, credentialType: string, credential: string): Promise<void> -设置此应用程序帐号的凭据，使用Promise方式异步返回结果。 +设置此应用程序帐号的凭据。使用Promise异步回调。 > **说明：** 从API version 9开始废弃。 > @@ -940,7 +673,15 @@ setCredential(name: string, credentialType: string, credential: string): Promise | 类型 | 说明 | | :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or credentialType. | + | 12300003 | the account indicated by localId dose not exist. | **示例：** @@ -957,2908 +698,3708 @@ setCredential(name: string, credentialType: string, credential: string): Promise } ``` + +### setDataSyncEnabled9+ -### setAccountCredential(deprecated) - -setAccountCredential(name: string, credentialType: string, credential: string,callback: AsyncCallback<void>): void +setDataSyncEnabled(name: string, isEnable: boolean, callback: AsyncCallback<void>): void -设置此应用程序帐号的凭据，使用callback回调异步返回结果。 +设置指定的应用程序帐号是否允许应用程序数据同步。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[setCredential](#setcredential9)替代。 -> -> 从 API version 7开始支持。 +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------------------------- | ---- | ------------- | -| name | string | 是 | 应用程序帐号名称。 | -| credentialType | string | 是 | 要设置的凭据类型。 | -| credential | string | 是 | 要设置的凭据。 | -| callback | AsyncCallback<void> | 是 | 设置此应用帐号的凭据回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------- | +| name | string | 是 | 应用帐号名称。 | +| isEnable | boolean | 是 | 是否允许应用数据同步。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当指定的应用帐号是否允许应用程序数据设置成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name. | + | 12300003 | the account indicated by name dose not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAccountCredential("ZhangSan", "credentialType001", "credential001", (err) => { - console.log("setAccountCredential err: " + JSON.stringify(err)); - }); + try { + appAccountManager.setDataSyncEnabled("ZhangSan", true, (err) => { + console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + } ``` -### setAccountCredential(deprecated) +### setDataSyncEnabled9+ -setAccountCredential(name: string, credentialType: string, credential: string): Promise<void> +setDataSyncEnabled(name: string, isEnable: boolean): Promise<void> -设置此应用程序帐号的凭据，使用Promise方式异步返回结果。 +设置指定的应用程序帐号是否允许应用程序数据同步。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[setCredential](#setcredential9-1)替代。 -> -> 从 API version 7开始支持。 +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------ | ---- | ---------- | -| name | string | 是 | 应用帐号的名称。 | -| credentialType | string | 是 | 要设置的凭据的类型。 | -| credential | string | 是 | 要设置的凭据。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------- | ---- | ----------- | +| name | string | 是 | 应用帐号名称。 | +| isEnable | boolean | 是 | 是否允许应用数据同步。 | **返回值：** | 类型 | 说明 | | :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name. | + | 12300003 | the account indicated by name dose not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAccountCredential("ZhangSan", "credentialType001", "credential001").then(() => { - console.log('setAccountCredential Success'); - }).catch((err) => { - console.log("setAccountCredential err: " + JSON.stringify(err)); - }); + try { + appAccountManager .setDataSyncEnabled("ZhangSan", true).then(() => { + console.log('setDataSyncEnabled Success'); + }).catch((err) => { + console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + } ``` -### setAccountExtraInfo(deprecated) +### setCustomData9+ -setAccountExtraInfo(name: string, extraInfo: string, callback: AsyncCallback<void>): void - -设置此应用程序帐号的额外信息，使用callback回调异步返回结果。 - -> **说明：** 从API version 9开始废弃。 -> -> 从 API version 7开始支持。 +setAssociatedData(name: string, key: string, value: string, callback: AsyncCallback<void>): void +设置与此应用程序帐号关联的数据。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------------------------- | ---- | --------------- | -| name | string | 是 | 应用帐号名称。 | -| extraInfo | string | 是 | 要设置的额外信息。 | -| callback | AsyncCallback<void> | 是 | 设置此应用帐号的额外信息回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ----------------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | +| value | string | 是 | 要设置的数据的值。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置与此应用帐号关联的数据成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, key or value. | + | 12300003 | the account indicated by name dose not exist. | + | 12400008 | the number of customized data has reached the upper limit. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAccountExtraInfo("ZhangSan", "Tk002", (err) => { - console.log("setAccountExtraInfo err: " + JSON.stringify(err)); - }); + try { + appAccountManager.setCustomData("ZhangSan", "k001", "v001", (err) => { + console.log("setCustomData err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("setCustomData err: " + JSON.stringify(err)); + } ``` -### setAccountExtraInfo(deprecated) - -setAccountExtraInfo(name: string, extraInfo: string): Promise<void> - -设置此应用程序帐号的额外信息，使用Promise方式异步返回结果。 +### setCustomData9+ -> **说明：** 从API version 9开始废弃。 -> -> 从 API version 7开始支持。 +setAssociatedData(name: string, key: string, value: string): Promise<void> +设置与此应用程序帐号关联的数据。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | --------- | -| name | string | 是 | 应用帐号名称。 | -| extraInfo | string | 是 | 要设置的额外信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | +| value | string | 是 | 要设置的数据的值。 | **返回值：** | 类型 | 说明 | | :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, key or value. | + | 12300003 | the account indicated by name dose not exist. | + | 12400008 | the number of customized data has reached the upper limit. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAccountExtraInfo("ZhangSan", "Tk002").then(() => { - console.log('setAccountExtraInfo Success'); - }).catch((err) => { - console.log("setAccountExtraInfo err: " + JSON.stringify(err)); - }); + try { + appAccountManager.setCustomData("ZhangSan", "k001", "v001").then(() => { + console.log('setCustomData Success'); + }).catch((err) => { + console.log("setCustomData err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("setCustomData err: " + JSON.stringify(err)); + } ``` - -### setDataSyncEnabled9+ -setDataSyncEnabled(name: string, isEnable: boolean, callback: AsyncCallback<void>): void +### getAllAccounts9+ -设置指定的应用程序帐号是否允许应用程序数据同步，使用callback回调异步返回结果。 +getAllAccounts(callback: AsyncCallback<Array<AppAccountInfo>>): void -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC +获取全部应用已授权帐号信息。 + +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------------------- | -| name | string | 是 | 应用帐号名称。 | -| isEnable | boolean | 是 | 是否允许应用数据同步。 | -| callback | AsyncCallback<void> | 是 | 设置指定的应用帐号是否允许应用程序数据同步的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.setDataSyncEnabled("ZhangSan", true, (err) => { - console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + appAccountManager.getAllAccounts((err, data)=>{ + console.debug("getAllAccounts err:" + JSON.stringify(err)); + console.debug("getAllAccounts data:" + JSON.stringify(data)); }); } catch (err) { - console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + console.debug("getAllAccounts err:" + JSON.stringify(err)); } ``` -### setDataSyncEnabled9+ +### getAllAccounts9+ -setDataSyncEnabled(name: string, isEnable: boolean): Promise<void> +getAllAccounts(): Promise<Array<AppAccountInfo>> -设置指定的应用程序帐号是否允许应用程序数据同步，使用Promise方式异步返回结果。 +获取全部应用已授权帐号信息。 -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount -**参数：** +**返回值：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------- | ---- | ----------- | -| name | string | 是 | 应用帐号名称。 | -| isEnable | boolean | 是 | 是否允许应用数据同步。 | +| 类型 | 说明 | +| ---------------------------------------- | --------------------- | +| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise对象。返回全部应用已授权帐号信息对象。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager .setDataSyncEnabled("ZhangSan", true).then(() => { - console.log('setDataSyncEnabled Success'); + appAccountManager.getAllAccounts().then((data) => { + console.log('getAllAccounts: ' + data); }).catch((err) => { - console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + console.log("getAllAccounts err: " + JSON.stringify(err)); }); } catch (err) { - console.log("setDataSyncEnabled err: " + JSON.stringify(err)); + console.log("getAllAccounts err: " + JSON.stringify(err)); } ``` -### setAppAccountSyncEnable(deprecated) - -setAppAccountSyncEnable(name: string, isEnable: boolean, callback: AsyncCallback<void>): void +### getAccountsByOwner9+ -设置指定的应用程序帐号是否允许应用程序数据同步，使用callback回调异步返回结果。 +getAccountsByOwner(owner: string, callback: AsyncCallback<Array<AppAccountInfo>>): void -> **说明：** 从API version 9开始废弃, 建议使用[setDataSyncEnabled](#setdatasyncenabled9)替代。 -> -> 从 API version 7开始支持。 +获取指定应用全部帐号信息。 -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------------------- | -| name | string | 是 | 应用帐号名称。 | -| isEnable | boolean | 是 | 是否允许应用数据同步。 | -| callback | AsyncCallback<void> | 是 | 设置指定的应用帐号是否允许应用程序数据同步的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------- | +| owner | string | 是 | 应用包名称。 | +| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid owner. | + | 12300003 | the account indicated by owner dose not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAppAccountSyncEnable("ZhangSan", true, (err) => { - console.log("setAppAccountSyncEnable err: " + JSON.stringify(err)); - }); + const selfBundle = "com.example.actsgetallaaccounts"; + try { + appAccountManager.getAccountsByOwner(selfBundle, (err, data)=>{ + console.debug("getAccountsByOwner err:" + JSON.stringify(err)); + console.debug("getAccountsByOwner data:" + JSON.stringify(data)); + }); + } catch (err) { + console.debug("getAccountsByOwner err:" + JSON.stringify(err)); + } ``` -### setAppAccountSyncEnable(deprecated) - -setAppAccountSyncEnable(name: string, isEnable: boolean): Promise<void> +### getAccountsByOwner9+ -设置指定的应用程序帐号是否允许应用程序数据同步，使用Promise方式异步返回结果。 +getAccountsByOwner(owner: string): Promise<Array<AppAccountInfo>> -> **说明：** 从API version 9开始废弃, 建议使用[setDataSyncEnabled](#setdatasyncenabled9-1)替代。 -> -> 从 API version 7开始支持。 +获取指定应用全部帐号信息。 -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------- | ---- | ----------- | -| name | string | 是 | 应用帐号名称。 | -| isEnable | boolean | 是 | 是否允许应用数据同步。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ------ | +| owner | string | 是 | 应用包名称。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ---------------------------------------- | --------------------- | +| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise对象。返回指定应用全部帐号信息对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid owner. | + | 12300003 | the account indicated by owner dose not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager .setAppAccountSyncEnable("ZhangSan", true).then(() => { - console.log('setAppAccountSyncEnable Success'); - }).catch((err) => { - console.log("setAppAccountSyncEnable err: " + JSON.stringify(err)); - }); + const selfBundle = "com.example.actsgetallaaccounts"; + try { + appAccountManager.getAccountsByOwner(selfBundle).then((data) => { + console.log('getAccountsByOwner: ' + data); + }).catch((err) => { + console.log("getAccountsByOwner err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("getAccountsByOwner err: " + JSON.stringify(err)); + } ``` -### setCustomData9+ +### getCredential9+ -setAssociatedData(name: string, key: string, value: string, callback: AsyncCallback<void>): void +getCredential(name: string, credentialType: string, callback: AsyncCallback<string>): void -设置与此应用程序帐号关联的数据，使用callback回调异步返回结果。 +获取此应用帐号的凭据（如数字密码、人脸和PIN码等）。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ----------------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | -| value | string | 是 | 要设置的数据的值。 | -| callback | AsyncCallback<void> | 是 | 设置与此应用帐号关联的数据的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------- | ---- | -------------- | +| name | string | 是 | 应用帐号名称。 | +| credentialType | string | 是 | 获取此应用帐号的凭据的类型。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取此应用帐号的凭据成功时，err为undefined，data返回此应用帐号的凭据对象；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or credentialType. | + | 12300003 | the account indicated by name dose not exist. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.setCustomData("ZhangSan", "k001", "v001", (err) => { - console.log("setCustomData err: " + JSON.stringify(err)); - }); + appAccountManager.getCredential("ZhangSan", "credentialType001", (err, result) => { + console.log("getCredential err: " + JSON.stringify(err)); + console.log('getCredential result: ' + result); + }); } catch (err) { - console.log("setCustomData err: " + JSON.stringify(err)); + console.log("getCredential err: " + JSON.stringify(err)); } ``` -### setCustomData9+ +### getCredential9+ -setAssociatedData(name: string, key: string, value: string): Promise<void> +getCredential(name: string, credentialType: string): Promise<string> -设置与此应用程序帐号关联的数据，使用Promise方式异步返回结果。 +获取此应用程序帐号的凭据。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | -| value | string | 是 | 要设置的数据的值。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------ | ---- | ---------- | +| name | string | 是 | 应用帐号名称。 | +| credentialType | string | 是 | 要获取的凭据的类型。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :-------------------- | +| Promise<string> | Promise对象。返回此应用程序帐号的凭据对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or credentialType. | + | 12300003 | the account indicated by name dose not exist. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.setCustomData("ZhangSan", "k001", "v001").then(() => { - console.log('setCustomData Success'); + appAccountManager.getCredential("ZhangSan", "credentialType001").then((data) => { + console.log('getCredential, result: ' + data); }).catch((err) => { - console.log("setCustomData err: " + JSON.stringify(err)); + console.log("getCredential err: " + JSON.stringify(err)); }); } catch (err) { - console.log("setCustomData err: " + JSON.stringify(err)); + console.log("getCredential err: " + JSON.stringify(err)); } ``` -### setAssociatedData(deprecated) - -setAssociatedData(name: string, key: string, value: string, callback: AsyncCallback<void>): void - -设置与此应用程序帐号关联的数据，使用callback回调异步返回结果。 +### getCustomData9+ -> **说明：** 从API version 9开始废弃, 建议使用[setCustomData](#setcustomdata9)替代。 -> -> 从 API version 7开始支持。 +getCustomData(name: string, key: string, callback: AsyncCallback<string>): void +获取与此应用程序帐号关联的数据。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ----------------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | -| value | string | 是 | 要设置的数据的值。 | -| callback | AsyncCallback<void> | 是 | 设置与此应用帐号关联的数据的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要获取的数据的键。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取与此应用程序帐号关联的数据成功时，err为undefined，data返回与此应用程序帐号关联的数据对象；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or key. | + | 12300003 | the account indicated by name dose not exist. | + | 12400009 | the customData does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAssociatedData("ZhangSan", "k001", "v001", (err) => { - console.log("setAssociatedData err: " + JSON.stringify(err)); - }); + try { + appAccountManager.getCustomData("ZhangSan", "k001", (err, result) => { + console.log("getCustomData err: " + JSON.stringify(err)); + console.log('getCustomData result: ' + result); + }); + } catch (err) { + console.log("getCustomData err: " + JSON.stringify(err)); + } ``` -### setAssociatedData(deprecated) - -setAssociatedData(name: string, key: string, value: string): Promise<void> - -设置与此应用程序帐号关联的数据，使用Promise方式异步返回结果。 +### getCustomData9+ -> **说明：** 从API version 9开始废弃, 建议使用[setCustomData](#setcustomdata9-1)替代。 -> -> 从 API version 7开始支持。 +getCustomData(name: string, key: string): Promise<string> +获取与此应用程序帐号关联的数据。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | -| value | string | 是 | 要设置的数据的值。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | --------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要获取的数据的键。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :-------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setAssociatedData("ZhangSan", "k001", "v001").then(() => { - console.log('setAssociatedData Success'); - }).catch((err) => { - console.log("setAssociatedData err: " + JSON.stringify(err)); - }); - ``` - -### getAllAccounts9+ - -getAllAccounts(callback: AsyncCallback<Array<AppAccountInfo>>): void - -获取全部应用已授权帐号信息。 - -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 - -**系统能力：** SystemCapability.Account.AppAccount +| 类型 | 说明 | +| :-------------------- | :-------------------- | +| Promise<string> | Promise对象。返回与此应用程序帐号关联的数据对象。 | -**参数：** +**错误码：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | --------- | -| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or key. | + | 12300003 | the account indicated by name dose not exist. | + | 12400009 | the customData does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getAllAccounts((err, data)=>{ - console.debug("getAllAccounts err:" + JSON.stringify(err)); - console.debug("getAllAccounts data:" + JSON.stringify(data)); + appAccountManager.getCustomData("ZhangSan", "k001").then((data) => { + console.log('getCustomData: ' + data); + }).catch((err) => { + console.log("getCustomData err: " + JSON.stringify(err)); }); } catch (err) { - console.debug("getAllAccounts err:" + JSON.stringify(err)); + console.log("getCustomData err: " + JSON.stringify(err)); } ``` -### getAllAccounts9+ - -getAllAccounts(): Promise<Array<AppAccountInfo>> +### getCustomDataSync9+ -获取全部应用已授权帐号信息。 +getCustomDataSync(name: string, key: string): string; -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +获取与此应用程序帐号关联的数据，使用同步方式返回结果。 **系统能力：** SystemCapability.Account.AppAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | --------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要获取的数据的键。 | + **返回值：** -| 类型 | 说明 | -| ---------------------------------------- | --------------------- | -| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :-------------------- | +| string | 目标关联数据的取值。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or key. | + | 12300003 | the account indicated by name dose not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getAllAccounts().then((data) => { - console.log('getAllAccounts: ' + data); - }).catch((err) => { - console.log("getAllAccounts err: " + JSON.stringify(err)); - }); + var backData = appAccountManager.getCustomDataSync("ZhangSan", "k001"); + console.info("getCustomDataSync backData:" + JSON.stringify(backData)); } catch (err) { - console.log("getAllAccounts err: " + JSON.stringify(err)); + console.error(`getCustomDataSync err, code is ${e.code}, message is ${e.message}`); } ``` -### getAllAccessibleAccounts(deprecated) - -getAllAccessibleAccounts(callback: AsyncCallback<Array<AppAccountInfo>>): void - -获取全部应用已授权帐号信息。 +### on('accountChange')9+ -> **说明：** 从API version 9开始废弃, 建议使用[getAllAccounts](#getallaccounts9)替代。 -> -> 从 API version 7开始支持。 +on(type: 'accountChange', owners: Array<string>, callback: Callback<Array<AppAccountInfo>>): void -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +订阅指定帐号所有者的帐户变更事件。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | --------- | -| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------ | +| type | 'accountChange' | 是 | 事件回调类型，支持的事件为'accountChange'，当帐号所有者更新帐号时，触发该事件。 | +| owners | Array<string> | 是 | 指示帐号的所有者。 | +| callback | Callback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 回调函数。返回指定帐号所有者更新的帐号信息对象数组。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid type or owners. | + | 12300003 | the account indicated by owners dose not exist. | + | 12300005 | the listener has been registered. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAllAccessibleAccounts((err, data)=>{ - console.debug("getAllAccessibleAccounts err:" + JSON.stringify(err)); - console.debug("getAllAccessibleAccounts data:" + JSON.stringify(data)); - }); + function changeOnCallback(data){ + console.debug("receive change data:" + JSON.stringify(data)); + } + try{ + appAccountManager.on('accountChange', ["com.example.actsaccounttest"], changeOnCallback); + } + catch(err){ + console.error("on accountOnOffDemo err:" + JSON.stringify(err)); + } ``` -### getAllAccessibleAccounts(deprecated) +### off('accountChange')9+ -getAllAccessibleAccounts(): Promise<Array<AppAccountInfo>> +off(type: 'accountChange', callback?: Callback>): void -获取全部应用已授权帐号信息。 +取消订阅帐号事件。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[getAllAccounts](#getallaccounts9-1)替代。 -> -> 从 API version 7开始支持。 +**系统能力：** SystemCapability.Account.AppAccount -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +**参数：** -**系统能力：** SystemCapability.Account.AppAccount +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------- | ---- | ------------ | +| type | 'accountChange' | 是 | 事件回调类型，支持的事件为'accountChange'，当帐号所有者更新帐号时，触发该事件。 | +| callback | Callback> | 否 | 回调函数，返回指定帐号所有者更新的帐号信息数组。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| ---------------------------------------- | --------------------- | -| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid type. | + | 12300005 | the listener has been registered. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAllAccessibleAccounts().then((data) => { - console.log('getAllAccessibleAccounts: ' + data); - }).catch((err) => { - console.log("getAllAccessibleAccounts err: " + JSON.stringify(err)); - }); + function changeOnCallback(data){ + console.debug("receive change data:" + JSON.stringify(data)); + appAccountManager.off('accountChange', function(){ + console.debug("off finish"); + }) + } + try{ + appAccountManager.on('accountChange', ["com.example.actsaccounttest"], changeOnCallback); + } + catch(err){ + console.error("on accountOnOffDemo err:" + JSON.stringify(err)); + } ``` -### getAccountsByOwner9+ - -getAccountsByOwner(owner: string, callback: AsyncCallback<Array<AppAccountInfo>>): void +### auth9+ -获取指定应用全部帐号信息。 +auth(name: string, owner: string, authType: string, callback: AuthCallback): void -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +对应用帐户进行鉴权以获取Auth令牌。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | --------- | -| owner | string | 是 | 应用包名称。 | -| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | --------------- | +| name | string | 是 | 要鉴权的应用帐号名称。 | +| owner | string | 是 | 要鉴权的应用帐号所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| callback | [AuthCallback](#authcallback9) | 是 | 回调函数。返回鉴权结果对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner, authType or options. | + | 12300003 | the account indicated by owner dose not exist. | + | 12300016 | authentication timeout. | + | 12300017 | authentication service is busy. | + | 12300018 | authentication service is locked. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js + import featureAbility from '@ohos.ability.featureAbility'; + + function onResultCallback(code, result) { + console.log("resultCode: " + code); + console.log("result: " + JSON.stringify(result)); + } + + function onRequestRedirectedCallback(request) { + let abilityStartSetting = {want: request}; + featureAbility.startAbility(abilityStartSetting, (err)=>{ + console.log("startAbility err: " + JSON.stringify(err)); + }); + } + const appAccountManager = account_appAccount.createAppAccountManager(); - const selfBundle = "com.example.actsgetallaaccounts"; try { - appAccountManager.getAccountsByOwner(selfBundle, (err, data)=>{ - console.debug("getAccountsByOwner err:" + JSON.stringify(err)); - console.debug("getAccountsByOwner data:" + JSON.stringify(data)); + appAccountManager.auth("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", { + onResult: onResultCallback, + onRequestRedirected: onRequestRedirectedCallback }); } catch (err) { - console.debug("getAccountsByOwner err:" + JSON.stringify(err)); + console.log("auth err: " + JSON.stringify(err)); } ``` -### getAccountsByOwner9+ - -getAccountsByOwner(owner: string): Promise<Array<AppAccountInfo>> +### auth9+ -获取指定应用全部帐号信息。 +auth(name: string, owner: string, authType: string, options: {[key: string]: Object}, callback: AuthCallback): void -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +对应用帐户进行鉴权以获取OAuth令牌。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ------ | -| owner | string | 是 | 应用包名称。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | --------------- | +| name | string | 是 | 要鉴权的应用帐号名称。 | +| owner | string | 是 | 要鉴权的应用帐号所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| options | {[key: string]: Object} | 是 | 鉴权所需的可选项。 | +| callback | [AuthCallback](#authcallback9) | 是 | 回调函数。返回鉴权结果对象。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| ---------------------------------------- | --------------------- | -| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner, authType or options. | + | 12300003 | the account indicated by owner dose not exist. | + | 12300016 | authentication timeout. | + | 12300017 | authentication service is busy. | + | 12300018 | authentication service is locked. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js + import featureAbility from '@ohos.ability.featureAbility'; + + function onResultCallback(code, result) { + console.log("resultCode: " + code); + console.log("result: " + JSON.stringify(result)); + } + + function onRequestRedirectedCallback(request) { + let abilityStartSetting = {want: request}; + featureAbility.startAbility(abilityStartSetting, (err)=>{ + console.log("startAbility err: " + JSON.stringify(err)); + }); + } + const appAccountManager = account_appAccount.createAppAccountManager(); - const selfBundle = "com.example.actsgetallaaccounts"; try { - appAccountManager.getAccountsByOwner(selfBundle).then((data) => { - console.log('getAccountsByOwner: ' + data); - }).catch((err) => { - console.log("getAccountsByOwner err: " + JSON.stringify(err)); + appAccountManager.auth("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", {}, { + onResult: onResultCallback, + onRequestRedirected: onRequestRedirectedCallback }); } catch (err) { - console.log("getAccountsByOwner err: " + JSON.stringify(err)); + console.log("auth err: " + JSON.stringify(err)); } ``` -### getAllAccounts(deprecated) - -getAllAccounts(owner: string, callback: AsyncCallback<Array<AppAccountInfo>>): void - -获取指定应用全部帐号信息。 +### getAuthToken9+ -> **说明：** 从API version 9开始废弃, 建议使用[getAccountsByOwner]替代。 -> -> 从 API version 7开始支持。 +getAuthToken(name: string, owner: string, authType: string, callback: AsyncCallback<string>): void -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +获取指定应用帐号和鉴权类型的Auth令牌。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | --------- | -| owner | string | 是 | 应用包名称。 | -| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取指定应用帐号和鉴权类型的Auth令牌成功时，err为undefined，data返回Auth令牌对象；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner or authType. | + | 12300003 | the account indicated by owner dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - const selfBundle = "com.example.actsgetallaaccounts"; - appAccountManager.getAllAccounts(selfBundle, (err, data)=>{ - console.debug("getAllAccounts err:" + JSON.stringify(err)); - console.debug("getAllAccounts data:" + JSON.stringify(data)); - }); + try { + appAccountManager.getAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { + console.log('getAuthToken err: ' + JSON.stringify(err)); + console.log('getAuthToken token: ' + data); + }); + } catch (err) { + console.log('getAuthToken err: ' + JSON.stringify(err)); + } ``` -### getAllAccounts(deprecated) - -getAllAccounts(owner: string): Promise<Array<AppAccountInfo>> - -获取指定应用全部帐号信息。 +### getAuthToken9+ -> **说明：** 从API version 9开始废弃, 建议使用[getAccountsByOwner](#getaccountsbyowner9-1)替代。 -> -> 从 API version 7开始支持。 +getAuthToken(name: string, owner: string, authType: string): Promise<string> -**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 +获取指定应用帐户和鉴权类型的Auth令牌。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ------ | -| owner | string | 是 | 应用包名称。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------------- | --------------------- | -| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| --------------------- | --------------------- | +| Promise<string> | Promise对象。返回指定应用帐户和鉴权类型的Auth令牌对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner or authType. | + | 12300003 | the account indicated by owner dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - const selfBundle = "com.example.actsgetallaaccounts"; - appAccountManager.getAllAccounts(selfBundle).then((data) => { - console.log('getAllAccounts: ' + data); - }).catch((err) => { - console.log("getAllAccounts err: " + JSON.stringify(err)); - }); + try { + appAccountManager.getAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData").then((data) => { + console.log('getAuthToken token: ' + data); + }).catch((err) => { + console.log("getAuthToken err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("getAuthToken err: " + JSON.stringify(err)); + } ``` -### getCredential9+ +### setAuthToken9+ -getCredential(name: string, credentialType: string, callback: AsyncCallback<string>): void +setAuthToken(name: string, authType: string, token: string, callback: AsyncCallback<void>): void -获取此应用帐号的凭据（如数字密码、人脸和PIN码等），使用callback回调异步返回结果。 +设置指定应用帐号和鉴权类型的Auth令牌。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | --------------------------- | ---- | -------------- | -| name | string | 是 | 应用帐号名称。 | -| credentialType | string | 是 | 获取此应用帐号的凭据的类型。 | -| callback | AsyncCallback<string> | 是 | 获取此应用帐号的凭据的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | Auth令牌。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定应用帐号和鉴权类型的Auth令牌成功时，err为undefined；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner, authType or token. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | + | 12400007 | the number of token has reached the upper limit. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getCredential("ZhangSan", "credentialType001", (err, result) => { - console.log("getCredential err: " + JSON.stringify(err)); - console.log('getCredential result: ' + result); + appAccountManager.setAuthToken("LiSi", "getSocialData", "xxxx", (err) => { + console.log('setAuthToken err: ' + JSON.stringify(err)); }); } catch (err) { - console.log("getCredential err: " + JSON.stringify(err)); + console.log('setAuthToken err: ' + JSON.stringify(err)); } ``` -### getCredential9+ +### setAuthToken9+ -getCredential(name: string, credentialType: string): Promise<string> +setAuthToken(name: string, authType: string, token: string): Promise<void> -获取此应用程序帐号的凭据，使用Promise方式异步返回结果。 +设置指定应用帐户和鉴权类型的Auth令牌。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------ | ---- | ---------- | -| name | string | 是 | 应用帐号名称。 | -| credentialType | string | 是 | 要获取的凭据的类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | -------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | Auth令牌。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :-------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner, authType or token. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | + | 12400007 | the number of token has reached the upper limit. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getCredential("ZhangSan", "credentialType001").then((data) => { - console.log('getCredential, result: ' + data); + appAccountManager.setAuthToken("LiSi", "getSocialData", "xxxx").then(() => { + console.log('setAuthToken successfully'); }).catch((err) => { - console.log("getCredential err: " + JSON.stringify(err)); + console.log('setAuthToken err: ' + JSON.stringify(err)); }); } catch (err) { - console.log("getCredential err: " + JSON.stringify(err)); + console.log('setAuthToken err: ' + JSON.stringify(err)); } ``` -### getAccountCredential(deprecated) - -getAccountCredential(name: string, credentialType: string, callback: AsyncCallback<string>): void +### deleteAuthToken9+ -获取此应用帐号的凭据（如数字密码、人脸和PIN码等），使用callback回调异步返回结果。 +deleteAuthToken(name: string, owner: string, authType: string, token: string, callback: AsyncCallback<void>): void -> **说明：** 从API version 9开始废弃, 建议使用[getCredential](#getcredential9)替代。 -> -> 从 API version 7开始支持。 +删除指定应用帐户和鉴权类型的Auth令牌。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | --------------------------- | ---- | -------------- | -| name | string | 是 | 应用帐号名称。 | -| credentialType | string | 是 | 获取此应用帐号的凭据的类型。 | -| callback | AsyncCallback<string> | 是 | 获取此应用帐号的凭据的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------ | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | 要删除的Auth令牌。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当删除指定应用帐户和鉴权类型的Auth令牌成功时，err为undefined；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner, authType or token. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAccountCredential("ZhangSan", "credentialType001", (err, result) => { - console.log("getAccountCredential err: " + JSON.stringify(err)); - console.log('getAccountCredential result: ' + result); - }); + try { + appAccountManager.deleteAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx", (err) => { + console.log('deleteAuthToken err: ' + JSON.stringify(err)); + }); + } catch (err) { + console.log('deleteAuthToken err: ' + JSON.stringify(err)); + } ``` -### getAccountCredential(deprecated) - -getAccountCredential(name: string, credentialType: string): Promise<string> +### deleteAuthToken9+ -获取此应用程序帐号的凭据，使用Promise方式异步返回结果。 +deleteAuthToken(name: string, owner: string, authType: string, token: string): Promise<void> -> **说明：** 从API version 9开始废弃, 建议使用[getCredential](#getcredential9-1)替代。 -> -> 从 API version 7开始支持。 +删除指定应用帐户和鉴权类型的Auth令牌。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------ | ---- | ---------- | -| name | string | 是 | 应用帐号名称。 | -| credentialType | string | 是 | 要获取的凭据的类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------ | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | 要删除的Auth令牌。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :-------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner, authType or token. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAccountCredential("ZhangSan", "credentialType001").then((data) => { - console.log('getAccountCredential, result: ' + data); - }).catch((err) => { - console.log("getAccountCredential err: " + JSON.stringify(err)); - }); + try { + appAccountManager.deleteAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx").then(() => { + console.log('deleteAuthToken successfully'); + }).catch((err) => { + console.log("deleteAuthToken err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("deleteAuthToken err: " + JSON.stringify(err)); + } ``` -### getAccountExtraInfo(deprecated) - -getAccountExtraInfo(name: string, callback: AsyncCallback<string>): void +### setAuthTokenVisibility9+ -获取此应用帐号的额外信息（能转换成string类型的其它信息），使用callback回调异步返回结果。 +setAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean, callback: AsyncCallback<void>): void -> **说明：** 从API version 9开始废弃。 -> -> 从 API version 7开始支持。 +设置指定鉴权类型的Auth令牌对特定应用的可见性。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------- | -| name | string | 是 | 应用帐号名称。 | -| callback | AsyncCallback<string> | 是 | 获取此应用帐号的额外信息回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | ------------------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 被设置可见性的应用包名。 | +| isVisible | boolean | 是 | 是否可见。当设置成true可见，false不可见。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定鉴权类型的Auth令牌对特定应用的可见性成功时，err为undefined；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, authType or bundleName. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAccountExtraInfo("ZhangSan", (err, result) => { - console.log("getAccountExtraInfo err: " + JSON.stringify(err)); - console.log('getAccountExtraInfo result: ' + result); - }); + try { + appAccountManager.setAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true, (err) => { + console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); + }); + } catch (err) { + console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); + } ``` -### getAccountExtraInfo(deprecated) - -getAccountExtraInfo(name: string): Promise<string> +### setAuthTokenVisibility9+ -获取此应用程序帐号的额外信息，使用Promise方式异步返回结果。 +setAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean): Promise<void> -> **说明：** 从API version 9开始废弃。 -> -> 从 API version 7开始支持。 +设置指定鉴权类型的OAuth令牌对特定应用的可见性。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | ------- | -| name | string | 是 | 应用帐号名称。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------- | ---- | ------------ | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 被设置可见性的应用包名。 | +| isVisible | boolean | 是 | 是否可见。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :-------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, authType or bundleName. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAccountExtraInfo("ZhangSan").then((data) => { - console.log('getAccountExtraInfo, result: ' + data); - }).catch((err) => { - console.log("getAccountExtraInfo err: " + JSON.stringify(err)); - }); + try { + appAccountManager.setAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true).then(() => { + console.log('setAuthTokenVisibility successfully'); + }).catch((err) => { + console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); + }); + } catch (err) { + console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); + } ``` -### getCustomData9+ +### checkAuthTokenVisibility9+ -getCustomData(name: string, key: string, callback: AsyncCallback<string>): void +checkAuthTokenVisibility(name: string, authType: string, bundleName: string, callback: AsyncCallback<boolean>): void -获取与此应用程序帐号关联的数据，使用callback回调异步返回结果。 +检查指定鉴权类型的Auth令牌对特定应用的可见性。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ----------------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要获取的数据的键。 | -| callback | AsyncCallback<string> | 是 | 获取与此应用帐号关联的数据的回调。 | - +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------- | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 检查可见性的应用包名。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。当检查指定鉴权类型的Auth令牌对特定应用的可见性时，err为undefined，data为true表示可见，data为false表示不可见；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, authType or bundleName. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | + **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getCustomData("ZhangSan", "k001", (err, result) => { - console.log("getCustomData err: " + JSON.stringify(err)); - console.log('getCustomData result: ' + result); + appAccountManager.checkAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", (err, data) => { + console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); + console.log('checkAuthTokenVisibility isVisible: ' + data); }); } catch (err) { - console.log("getCustomData err: " + JSON.stringify(err)); + console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); } ``` -### getCustomData9+ +### checkAuthTokenVisibility9+ -getCustomData(name: string, key: string): Promise<string> +checkAuthTokenVisibility(name: string, authType: string, bundleName: string): Promise<boolean> -获取与此应用程序帐号关联的数据，使用Promise方式异步返回结果。 +检查指定鉴权类型的Auth令牌对特定应用的可见性。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | --------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要获取的数据的键。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 用于检查可见性的应用包名。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :-------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ---------------------- | --------------------- | +| Promise<boolean> | Promise对象。返回true表示指定鉴权类型的Auth令牌对特定应用的可见，返回false表示不可见。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, authType or bundleName. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getCustomData("ZhangSan", "k001").then((data) => { - console.log('getCustomData: ' + data); + appAccountManager.checkAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo").then((data) => { + console.log('checkAuthTokenVisibility isVisible: ' + data); }).catch((err) => { - console.log("getCustomData err: " + JSON.stringify(err)); + console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); }); } catch (err) { - console.log("getCustomData err: " + JSON.stringify(err)); + console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); } ``` -### getAssociatedData(deprecated) - -getAssociatedData(name: string, key: string, callback: AsyncCallback<string>): void +### getAllAuthTokens9+ -获取与此应用程序帐号关联的数据，使用callback回调异步返回结果。 +getAllAuthTokens(name: string, owner: string, callback: AsyncCallback<Array<OAuthTokenInfo>>): void -> **说明：** 从API version 9开始废弃, 建议使用[getCustomData](#getcustomdata9)替代。 -> -> 从 API version 7开始支持。 +获取指定应用对调用方全部可见的Auth令牌。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ----------------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要获取的数据的键。 | -| callback | AsyncCallback<string> | 是 | 获取与此应用帐号关联的数据的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| callback | AsyncCallback<Array< [AuthTokenInfo](#authtokeninfo9)>> | 是 | 回调函数。当获取指定应用对调 +用方全部可见的Auth令牌成功时，err为undefined，data为全部可见的Auth令牌数组；否则为错误对象。 | -**示例：** +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or owner. | + | 12300003 | the account indicated by name dose not exist. | + +**示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAssociatedData("ZhangSan", "k001", (err, result) => { - console.log("getAssociatedData err: " + JSON.stringify(err)); - console.log('getAssociatedData result: ' + result); - }); + try { + appAccountManager.getAllAuthTokens("LiSi", "com.example.ohos.accountjsdemo", (err, data) => { + console.log("getAllAuthTokens err: " + JSON.stringify(err)); + console.log('getAllAuthTokens data: ' + JSON.stringify(data)); + }); + } catch (err) { + console.log("getAllAuthTokens err: " + JSON.stringify(err)); + } ``` -### getAssociatedData(deprecated) - -getAssociatedData(name: string, key: string): Promise<string> +### getAllAuthTokens9+ -获取与此应用程序帐号关联的数据，使用Promise方式异步返回结果。 +getAllAuthTokens(name: string, owner: string): Promise<Array<AuthTokenInfo>> -> **说明：** 从API version 9开始废弃, 建议使用[getCustomData](#getcustomdata9-1)替代。 -> -> 从 API version 7开始支持。 +获取指定应用帐户对调用方可见的全部Auth令牌。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | --------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要获取的数据的键。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :-------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ---------------------------------------- | --------------------- | +| Promise<Array< [AuthTokenInfo](#authtokeninfo9)>> | Promise对象。返回指定应用帐户对调用方可见的全部Auth令牌对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or owner. | + | 12300003 | the account indicated by name dose not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAssociatedData("ZhangSan", "k001").then((data) => { - console.log('getAssociatedData: ' + data); - }).catch((err) => { - console.log("getAssociatedData err: " + JSON.stringify(err)); - }); + try { + appAccountManager.getAllAuthTokens("LiSi", "com.example.ohos.accountjsdemo").then((data) => { + console.log('getAllAuthTokens data: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("getAllAuthTokens err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("getAllAuthTokens err: " + JSON.stringify(err)); + } ``` -### getAssociatedDataSync9+ +### getAuthList9+ -getAssociatedDataSync(name: string, key: string): string; +getAuthList(name: string, authType: string, callback: AsyncCallback<Array<string>>): void -获取与此应用程序帐号关联的数据，使用同步方式返回结果。 +获取指定应用帐户和鉴权类型的Auth令牌的授权列表。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | --------- | -| name | string | 是 | 应用帐号名称。 | -| key | string | 是 | 要获取的数据的键。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 应用帐号的鉴权类型的Auth令牌的授权列表。 | +| callback | AsyncCallback<Array<string>> | 是 | 回调函数。当获取指定应用帐户和鉴权类型的Auth令牌的授权列表成功时，err为undefined，data为Auth令牌的授权列表；否则为错误对象。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| :-------------------- | :-------------------- | -| string | 目标关联数据的取值。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or authType. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - var backData = appAccountManager.getAssociatedDataSync("ZhangSan", "k001"); - console.info("getAssociatedDataSync backData:" + JSON.stringify(backData)); + appAccountManager.getAuthList("com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { + console.log('getAuthList err: ' + JSON.stringify(err)); + console.log('getAuthList data: ' + JSON.stringify(data)); + }); } catch (err) { - console.error(`getAssociatedDataSync err, code is ${e.code}, message is ${e.message}`); + console.log('getAuthList err: ' + JSON.stringify(err)); } ``` -### on('accountChange')9+ +### getAuthList9+ -on(type: 'accountChange', owners: Array<string>, callback: Callback<Array<AppAccountInfo>>): void +getAuthList(name: string, authType: string): Promise<Array<string>> -订阅指定帐号所有者的帐户变更事件，使用callback回调异步返回结果。 +获取指定应用帐户和鉴权类型的Auth令牌的授权列表。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ------------------------------ | -| type | 'accountChange' | 是 | 关于帐号更改事件，当帐号所有者更新帐号时，订阅者将收到通知。 | -| owners | Array<string> | 是 | 指示帐号的所有者。 | -| callback | Callback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 订阅指定帐号所有者的帐号变更事件的回调。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - function changeOnCallback(data){ - console.debug("receive change data:" + JSON.stringify(data)); - } - try{ - appAccountManager.on('accountChange', ["com.example.actsaccounttest"], changeOnCallback); - } - catch(err){ - console.error("on accountOnOffDemo err:" + JSON.stringify(err)); - } - ``` - -### on('change')(deprecated) - -on(type: 'change', owners: Array<string>, callback: Callback<Array<AppAccountInfo>>): void - -订阅指定帐号所有者的帐户变更事件，使用callback回调异步返回结果。 +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 应用帐号的鉴权类型的Auth令牌的授权列表。 | -> **说明：** 从API version 9开始废弃, 建议使用[on('accountChange')](#onaccountchange9)替代。 -> -> 从 API version 7开始支持。 +**返回值：** -**系统能力：** SystemCapability.Account.AppAccount +| 类型 | 说明 | +| ---------------------------------- | --------------------- | +| Promise<Array<string>> | Promise对象。返回指定应用帐户和鉴权类型的Auth令牌的授权列表对象。 | -**参数：** +**错误码：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ------------------------------ | -| type | 'change' | 是 | 关于帐号更改事件，当帐号所有者更新帐号时，订阅者将收到通知。 | -| owners | Array<string> | 是 | 指示帐号的所有者。 | -| callback | Callback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 订阅指定帐号所有者的帐号变更事件的回调。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or authType. | + | 12300003 | the account indicated by name dose not exist. | + | 12300015 | the authType is not supported on current device. | + | 12300019 | credential does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - function changeOnCallback(data){ - console.debug("receive change data:" + JSON.stringify(data)); - } - try{ - appAccountManager.on('change', ["com.example.actsaccounttest"], changeOnCallback); - } - catch(err){ - console.error("on accountOnOffDemo err:" + JSON.stringify(err)); + try { + appAccountManager.getAuthList("com.example.ohos.accountjsdemo", "getSocialData").then((data) => { + console.log('getAuthList data: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("getAuthList err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("getAuthList err: " + JSON.stringify(err)); } ``` -### off('accountChange')9+ +### getAuthCallback9+ -off(type: 'accountChange', callback?: Callback>): void +getAuthCallback(sessionId: string, callback: AsyncCallback<AuthCallback>): void -取消订阅帐号事件，使用callback回调异步返回结果。 +获取鉴权会话的认证器回调。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------------- | ---- | ------------ | -| type | 'accountChange' | 是 | 关于帐号更改事件。 | -| callback | Callback> | 否 | 取消订阅帐号事件的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| sessionId | string | 是 | 鉴权会话的标识。 | +| callback | AsyncCallback<[AuthCallback](#authcallback9)> | 是 | 回调函数。当获取鉴权会话的认证器回调函数成功时，err为undefined，data为认证器回调函数；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12400005 | the session indicated by sessionId does not exist. | **示例：** ```js + import featureAbility from '@ohos.ability.featureAbility'; const appAccountManager = account_appAccount.createAppAccountManager(); - function changeOnCallback(data){ - console.debug("receive change data:" + JSON.stringify(data)); - appAccountManager.off('accountChange', function(){ - console.debug("off finish"); - }) - } - try{ - appAccountManager.on('accountChange', ["com.example.actsaccounttest"], changeOnCallback); - } - catch(err){ - console.error("on accountOnOffDemo err:" + JSON.stringify(err)); - } + featureAbility.getWant((err, want) => { + var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; + try { + appAccountManager.getAuthCallback(sessionId, (err, callback) => { + if (err.code != account_appAccount.ResultCode.SUCCESS) { + console.log("getAuthCallback err: " + JSON.stringify(err)); + return; + } + var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", + [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", + [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", + [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; + callback.onResult(account_appAccount.ResultCode.SUCCESS, result); + }); + } catch (err) { + console.log("getAuthCallback err: " + JSON.stringify(err)); + } + }); ``` -### off('change')(deprecated) - -off(type: 'change', callback?: Callback>): void +### getAuthCallback9+ -取消订阅帐号事件，使用callback回调异步返回结果。 +getAuthCallback(sessionId: string): Promise<AuthCallback> -> **说明：** 从API version 9开始废弃, 建议使用[off('accountChange')](#offaccountchange9)替代。 -> -> 从 API version 7开始支持。 +获取鉴权会话的认证器回调。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------------- | ---- | ------------ | -| type | 'change' | 是 | 关于帐号更改事件。 | -| callback | Callback> | 否 | 取消订阅帐号事件的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | -------- | +| sessionId | string | 是 | 鉴权会话的标识。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------ | --------------------- | +| Promise<[AuthCallback](#authcallback9)> | Promise对象。返回鉴权会话的认证器回调对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12400005 | the session indicated by sessionId does not exist. | **示例：** ```js + import featureAbility from '@ohos.ability.featureAbility'; + const appAccountManager = account_appAccount.createAppAccountManager(); - function changeOnCallback(data){ - console.debug("receive change data:" + JSON.stringify(data)); - appAccountManager.off('change', function(){ - console.debug("off finish"); - }) - } - try{ - appAccountManager.on('change', ["com.example.actsaccounttest"], changeOnCallback); - } - catch(err){ - console.error("on accountOnOffDemo err:" + JSON.stringify(err)); - } + featureAbility.getWant().then((want) => { + var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; + try { + appAccountManager.getAuthCallback(sessionId).then((callback) => { + var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", + [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", + [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", + [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; + callback.onResult(account_appAccount.ResultCode.SUCCESS, result); + }).catch((err) => { + console.log("getAuthCallback err: " + JSON.stringify(err)); + }); + } + }).catch((err) => { + console.log("getWant err: " + JSON.stringify(err)); + }); ``` -### auth9+ +### queryAuthenticatorInfo9+ -auth(name: string, owner: string, authType: string, callback: AuthCallback): void +queryAuthenticatorInfo(owner: string, callback: AsyncCallback<AuthenticatorInfo>): void -对应用帐户进行鉴权以获取Auth令牌，使用callback回调异步返回结果。 +获取指定应用帐号的认证器信息。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | --------------- | -| name | string | 是 | 要鉴权的应用帐号名称。 | -| owner | string | 是 | 要鉴权的应用帐号所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| callback | [AuthCallback](#authcallback9) | 是 | 认证器回调，用于返回鉴权结果。 | - -**示例：** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ----------- | +| owner | string | 是 | 应用帐号的所有者包名。 | +| callback | AsyncCallback<[AuthenticatorInfo](#authenticatorinfo8)> | 是 | 回调函数。当获取指定应用帐号的认证器信息成功时，err为undefined，data为认证器信息对象；否则为错误对象。 | - ```js - import featureAbility from '@ohos.ability.featureAbility'; +**错误码：** - function onResultCallback(code, result) { - console.log("resultCode: " + code); - console.log("result: " + JSON.stringify(result)); - } + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid owner. | + | 12300003 | the account indicated by owner dose not exist. | - function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err)=>{ - console.log("startAbility err: " + JSON.stringify(err)); - }); - } +**示例：** + ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.auth("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", { - onResult: onResultCallback, - onRequestRedirected: onRequestRedirectedCallback + appAccountManager.queryAuthenticatorInfo("com.example.ohos.accountjsdemo", (err, data) => { + console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); + console.log('queryAuthenticatorInfo data: ' + JSON.stringify(data)); }); } catch (err) { - console.log("auth err: " + JSON.stringify(err)); + console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); } ``` -### auth9+ +### queryAuthenticatorInfo9+ -auth(name: string, owner: string, authType: string, options: {[key: string]: Object}, callback: AuthCallback): void +queryAuthenticatorInfo(owner: string): Promise<AuthenticatorInfo> -对应用帐户进行鉴权以获取OAuth令牌，使用callback回调异步返回结果。 +获取指定应用帐户的认证器信息。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | --------------- | -| name | string | 是 | 要鉴权的应用帐号名称。 | -| owner | string | 是 | 要鉴权的应用帐号所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| options | {[key: string]: Object} | 是 | 鉴权所需的可选项。 | -| callback | [AuthCallback](#authcallback9) | 是 | 认证器回调，用于返回鉴权结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------- | +| owner | string | 是 | 应用帐号的所有者包名。 | -**示例：** +**返回值：** - ```js - import featureAbility from '@ohos.ability.featureAbility'; +| 类型 | 说明 | +| -------------------------------- | --------------------- | +| Promise<[AuthenticatorInfo](#authenticatorinfo8)> | Promise对象。返回指定应用帐户的认证器信息对象。 | - function onResultCallback(code, result) { - console.log("resultCode: " + code); - console.log("result: " + JSON.stringify(result)); - } +**错误码：** - function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err)=>{ - console.log("startAbility err: " + JSON.stringify(err)); - }); - } + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid owner. | + | 12300003 | the account indicated by owner dose not exist. | + +**示例：** + ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.auth("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", {}, { - onResult: onResultCallback, - onRequestRedirected: onRequestRedirectedCallback + appAccountManager.queryAuthenticatorInfo("com.example.ohos.accountjsdemo").then((data) => { + console.log('queryAuthenticatorInfo: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); }); } catch (err) { - console.log("auth err: " + JSON.stringify(err)); + console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); } ``` -### authenticate(deprecated) - -authenticate(name: string, owner: string, authType: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void +### checkAccountLabels9+ -对应用帐户进行鉴权以获取OAuth令牌，使用callback回调异步返回结果。 +checkAccountLabels(name: string, owner: string, labels: Array<string>, callback: AsyncCallback<boolean>): void; -> **说明：** 从API version 9开始废弃, 建议使用[auth](#auth9)替代。 -> -> 从 API version 8开始支持。 +检查指定帐户是否具有特定的标签集合。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | --------------- | -| name | string | 是 | 要鉴权的应用帐号名称。 | -| owner | string | 是 | 要鉴权的应用帐号所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| options | {[key: string]: any} | 是 | 鉴权所需的可选项。 | -| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 认证器回调，用于返回鉴权结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------------------------- | ----- | --------------- | +| name | string | 是 | 应用帐户的名称。 | +| owner | string | 是 | 应用帐户的所有者。| +| labels | Array<string> | 是 | 标签数组。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。当检查指定帐户是否具有特定的标签集合成功时，err为undefined，data为true表示具有特定标签，data为false表示不具有特定标签；否则为错误对象。 | -**示例：** +**错误码：** - ```js - import featureAbility from '@ohos.ability.featureAbility'; + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or owner. | + | 12300003 | the account indicated by owner dose not exist. | + | 12400001 | the application indicated by name does not exist. | - function onResultCallback(code, result) { - console.log("resultCode: " + code); - console.log("result: " + JSON.stringify(result)); - } +**示例：** - function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err)=>{ - console.log("startAbility err: " + JSON.stringify(err)); + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + var labels = ["student"]; + try { + appAccountManager.checkAccountLabels("zhangsan", "com.example.ohos.accountjsdemo", labels, (err, data) => { + console.log('checkAccountLabels: ' + JSON.stringify(data)); + console.log("checkAccountLabels err: " + JSON.stringify(err)); }); + } catch (err) { + console.log("checkAccountLabels err: " + JSON.stringify(err)); } - - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.authenticate("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", {}, { - onResult: onResultCallback, - onRequestRedirected: onRequestRedirectedCallback - }); ``` -### getAuthToken9+ +### checkAccountLabels9+ -getAuthToken(name: string, owner: string, authType: string, callback: AsyncCallback<string>): void +checkAccountLabels(name: string, owner: string, labels: Array<string>): Promise<boolean> -获取指定应用帐号和鉴权类型的Auth令牌，使用callback回调异步返回结果。 +检查指定帐户是否具有特定的标签集合。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| callback | AsyncCallback<string> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------------------------- | ----- | --------------- | +| name | string | 是 | 应用帐户的名称。 | +| owner | string | 是 | 应用帐户的所有者。| +| labels | Array<string> | 是 | 标签数组。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | -------------------------------- | +| Promise<boolean> | Promise对象。返回true表示指定帐户具有特定的标签集合，返回false表示不具有特性的标签集合。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or owner. | + | 12300003 | the account indicated by owner dose not exist. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); + var labels = ["student"]; try { - appAccountManager.getAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { - console.log('getAuthToken err: ' + JSON.stringify(err)); - console.log('getAuthToken token: ' + data); + appAccountManager.checkAccountLabels("zhangsan", "com.example.ohos.accountjsdemo", labels).then((data) => { + console.log('checkAccountLabels: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("checkAccountLabels err: " + JSON.stringify(err)); }); } catch (err) { - console.log('getAuthToken err: ' + JSON.stringify(err)); + console.log("checkAccountLabels err: " + JSON.stringify(err)); } ``` -### getAuthToken9+ +### deleteCredential9+ -getAuthToken(name: string, owner: string, authType: string): Promise<string> +deleteCredential(name: string, credentialType: string, callback: AsyncCallback<void>): void -获取指定应用帐户和鉴权类型的Auth令牌，使用Promise方式异步返回结果。 +删除指定应用帐户的指定类型的凭据信息。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------------------------- | ----- | -------------- | +| name | string | 是 | 应用帐户的名称。 | +| credentialType | string | 是 | 凭据类型。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当删除指定应用帐户的指定类型的凭据信息成功时，err为undefined；否则为错误对象。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| --------------------- | --------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or credentialType. | + | 12300019 | credential does not exist. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.getAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData").then((data) => { - console.log('getAuthToken token: ' + data); - }).catch((err) => { - console.log("getAuthToken err: " + JSON.stringify(err)); + appAccountManager.deleteCredential("zhangsan", "pin", (err, data) => { + console.log('deleteCredential: ' + JSON.stringify(data)); + console.log("deleteCredential err: " + JSON.stringify(err)); }); } catch (err) { - console.log("getAuthToken err: " + JSON.stringify(err)); + console.log("deleteCredential err: " + JSON.stringify(err)); } ``` -### getOAuthToken(deprecated) - -getOAuthToken(name: string, owner: string, authType: string, callback: AsyncCallback<string>): void +### deleteCredential9+ -获取指定应用帐号和鉴权类型的OAuth令牌，使用callback回调异步返回结果。 +deleteCredential(name: string, credentialType: string): Promise<void> -> **说明：** 从API version 9开始废弃, 建议使用[getAuthToken](#getauthtoken9)替代。 -> -> 从 API version 8开始支持。 +删除指定应用帐户的指定类型的凭据信息。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| callback | AsyncCallback<string> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------ | ----- | --------------- | +| name | string | 是 | 应用帐户的名称。 | +| credentialType | string | 是 | 凭据类型。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | -------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name or credentialType. | + | 12300019 | credential does not exist. | + | 12400001 | the application indicated by name does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { - console.log('getOAuthToken err: ' + JSON.stringify(err)); - console.log('getOAuthToken token: ' + data); - }); + try { + appAccountManager.deleteCredential("zhangsan", "pin").then((data) => { + console.log('deleteCredential: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("deleteCredential err: " + JSON.stringify(err)); + }); + } catch (err) { + console.log("deleteCredential err: " + JSON.stringify(err)); + } ``` -### getOAuthToken(deprecated) - -getOAuthToken(name: string, owner: string, authType: string): Promise<string> +### selectAccountsByOptions9+ -获取指定应用帐户和鉴权类型的OAuth令牌，使用Promise方式异步返回结果。 +selectAccountsByOptions(options: SelectAccountsOptions, callback: AsyncCallback<Array<AppAccountInfo>>); -> **说明：** 从API version 9开始废弃, 建议使用[getAuthToken](#getauthtoken9-1)替代。 -> -> 从 API version 8开始支持。 +根据选项选择请求方可访问的帐号列表。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ----------------------------------- | ----- | --------------- | +| options | SelectAccountsOptions | 是 | 选择帐户的选项。 | +| callback | AsyncCallback<[AppAccountInfo](#appaccountinfo)> | 是 | 回调函数。当根据选项选择请求方可访问的帐号列表时，err为undefined，data为可访问的帐号信息对象；否则为错误对象。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| --------------------- | --------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果。 | - -**示例：** - - ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData").then((data) => { - console.log('getOAuthToken token: ' + data); - }).catch((err) => { - console.log("getOAuthToken err: " + JSON.stringify(err)); - }); - ``` - -### setAuthToken9+ - -setAuthToken(name: string, authType: string, token: string, callback: AsyncCallback<void>): void - -设置指定应用帐号和鉴权类型的Auth令牌，使用callback回调异步返回结果。 - -**系统能力：** SystemCapability.Account.AppAccount - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | -------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | Auth令牌。 | -| callback | AsyncCallback<void> | 是 | 设置结果的回调。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid options. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); + var options = { + allowedOwners: ["com.example.ohos.accountjsdemo"] + }; try { - appAccountManager.setAuthToken("LiSi", "getSocialData", "xxxx", (err) => { - console.log('setAuthToken err: ' + JSON.stringify(err)); + appAccountManager.selectAccountsByOptions(options, (err, data) => { + console.log('selectAccountsByOptions: ' + JSON.stringify(data)); + console.log("selectAccountsByOptions err: " + JSON.stringify(err)); }); } catch (err) { - console.log('setAuthToken err: ' + JSON.stringify(err)); + console.log("selectAccountsByOptions err: " + JSON.stringify(err)); } ``` -### setAuthToken9+ +### selectAccountsByOptions9+ -setAuthToken(name: string, authType: string, token: string): Promise<void> +selectAccountsByOptions(options: SelectAccountsOptions): Promise<Array<AppAccountInfo>> -设置指定应用帐户和鉴权类型的Auth令牌，使用Promise方式异步返回结果。 +根据选项选择请求方可访问的帐户列表。使用Promise异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | -------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | Auth令牌。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------------------------- | ----- | --------------- | +| options | [SelectAccountsOptions](#selectaccountsoptions9) | 是 | 选择帐户的选项。 | **返回值：** -| 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ------------------- | -------------------------------- | +| Promise<[AppAccountInfo](#appaccountinfo)> | Promise对象。返回请求方可访问的帐户对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid options. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); + var options = { + allowedOwners: ["com.example.ohos.accountjsdemo"] + }; try { - appAccountManager.setAuthToken("LiSi", "getSocialData", "xxxx").then(() => { - console.log('setAuthToken successfully'); + appAccountManager.selectAccountsByOptions(options).then((data) => { + console.log('selectAccountsByOptions: ' + JSON.stringify(data)); }).catch((err) => { - console.log('setAuthToken err: ' + JSON.stringify(err)); + console.log("selectAccountsByOptions err: " + JSON.stringify(err)); }); } catch (err) { - console.log('setAuthToken err: ' + JSON.stringify(err)); + console.log("selectAccountsByOptions err: " + JSON.stringify(err)); } ``` -### setOAuthToken(deprecated) - -setOAuthToken(name: string, authType: string, token: string, callback: AsyncCallback<void>): void +### verifyCredential9+ -设置指定应用帐号和鉴权类型的OAuth令牌，使用callback回调异步返回结果。 +verifyCredential(name: string, owner: string, callback: AuthenticatorCallback): void; -> **说明：** 从API version 9开始废弃, 建议使用[setAuthToken](#setauthtoken9)替代。 -> -> 从 API version 8开始支持。 +验证用户凭据。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | -------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | OAuth令牌。 | -| callback | AsyncCallback<void> | 是 | 设置结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ----- | ----------------------- | +| name | string | 是 | 应用帐户的名称。 | +| owner | string | 是 | 应用帐户的所有者。 | +| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 回调函数。返回认证结果回调函数。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner or options. | + | 12300003 | the account indicated by owner dose not exist. | + | 12400001 | the application indicated by name does not exist. | + | 12400002 | the account authenticator service does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setOAuthToken("LiSi", "getSocialData", "xxxx", (err) => { - console.log('setOAuthToken err: ' + JSON.stringify(err)); - }); + try { + appAccountManager.verifyCredential("zhangsan", "com.example.ohos.accountjsdemo", { + onResult: (resultCode, result) => { + console.log("verifyCredential onResult, resultCode:" + JSON.stringify(resultCode)); + console.log("verifyCredential onResult, result:" + JSON.stringify(result)); + }, + onRequestRedirected: (request) => { + console.log("verifyCredential onRequestRedirected, request:" + JSON.stringify(request)); + } + }); + } catch (err) { + console.log("verifyCredential err: " + JSON.stringify(err)); + } ``` -### setOAuthToken(deprecated) - -setOAuthToken(name: string, authType: string, token: string): Promise<void> +### verifyCredential9+ -设置指定应用帐户和鉴权类型的OAuth令牌，使用Promise方式异步返回结果。 +verifyCredential(name: string, owner: string, options: VerifyCredentialOptions, callback: AuthenticatorCallback): void; -> **说明：** 从API version 9开始废弃, 建议使用[setAuthToken](#setauthtoken9-1)替代。 -> -> 从 API version 8开始支持。 +验证用户凭据。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | -------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | OAuth令牌。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ----- | ----------------------- | +| name | string | 是 | 应用帐户的名称。 | +| owner | string | 是 | 应用帐户的所有者。 | +| options | [VerifyCredentialOptions](#verifycredentialoptions9) | 是 | 验证凭据的选项。 | +| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 回调函数。返回认证结果回调函数。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid name, owner or options. | + | 12300003 | the account indicated by owner dose not exist. | + | 12400001 | the application indicated by name does not exist. | + | 12400002 | the account authenticator service does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setOAuthToken("LiSi", "getSocialData", "xxxx").then(() => { - console.log('setOAuthToken successfully'); - }).catch((err) => { - console.log('setOAuthToken err: ' + JSON.stringify(err)); - }); + var options = { + credentialType: "pin", + credential: "123456" + }; + try { + appAccountManager.verifyCredential("zhangsan", "com.example.ohos.accountjsdemo", options, { + onResult: (resultCode, result) => { + console.log("verifyCredential onResult, resultCode:" + JSON.stringify(resultCode)); + console.log("verifyCredential onResult, result:" + JSON.stringify(result)); + }, + onRequestRedirected: (request) => { + console.log("verifyCredential onRequestRedirected, request:" + JSON.stringify(request)); + } + }); + } catch (err) { + console.log("verifyCredential err: " + JSON.stringify(err)); + } ``` -### deleteAuthToken9+ +### setAuthenticatorProperties9+ -deleteAuthToken(name: string, owner: string, authType: string, token: string, callback: AsyncCallback<void>): void +setAuthenticatorProperties(owner: string, callback: AuthCallback): void; -删除指定应用帐户和鉴权类型的Auth令牌，使用callback回调异步返回结果。 +设置认证器属性。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------ | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | 要删除的Auth令牌。 | -| callback | AsyncCallback<void> | 是 | 删除结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ----- | ----------------------- | +| owner | string | 是 | 认证器的所有者。 | +| callback | [AuthCallback](#authcallback9) | 是 | 回调函数。返回设置属性结果回调函数。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid owner or options. | + | 12300003 | the account indicated by owner dose not exist. | + | 12400002 | the account authenticator service does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); try { - appAccountManager.deleteAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx", (err) => { - console.log('deleteAuthToken err: ' + JSON.stringify(err)); + appAccountManager.setAuthenticatorProperties("com.example.ohos.accountjsdemo", { + onResult: (resultCode, result) => { + console.log("setAuthenticatorProperties onResult, resultCode:" + JSON.stringify(resultCode)); + console.log("setAuthenticatorProperties onResult, result:" + JSON.stringify(result)); + }, + onRequestRedirected: (request) => { + console.log("setAuthenticatorProperties onRequestRedirected, request:" + JSON.stringify(request)); + } }); } catch (err) { - console.log('deleteAuthToken err: ' + JSON.stringify(err)); + console.log("setAuthenticatorProperties err: " + JSON.stringify(err)); } ``` -### deleteAuthToken9+ +### setAuthenticatorProperties9+ -deleteAuthToken(name: string, owner: string, authType: string, token: string): Promise<void> +setAuthenticatorProperties(owner: string, options: SetPropertiesOptions, callback: AuthCallback): void; -删除指定应用帐户和鉴权类型的Auth令牌，使用Promise方式异步返回结果。 +设置认证器属性。使用callback异步回调。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ------------ | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | 要删除的Auth令牌。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ----- | ----------------------- | +| owner | string | 是 | 认证器的所有者。 | +| options | [SetPropertiesOptions](#setpropertiesoptions9) | 是 | 设置属性的选项。 | +| callback | [AuthCallback](#authcallback9) | 是 | 认证器回调，返回设置属性结果回调函数。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | + | 错误码ID | 错误信息| + | ------- | -------| + | 12300001 | system service exception. | + | 12300002 | invalid owner or options. | + | 12300003 | the account indicated by owner dose not exist. | + | 12400002 | the account authenticator service does not exist. | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); + var options = { + properties: {"prop1": "value1"} + }; try { - appAccountManager.deleteAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx").then(() => { - console.log('deleteAuthToken successfully'); - }).catch((err) => { - console.log("deleteAuthToken err: " + JSON.stringify(err)); - }); + appAccountManager.setAuthenticatorProperties("com.example.ohos.accountjsdemo", options, { + onResult: (resultCode, result) => { + console.log("setAuthenticatorProperties onResult, resultCode:" + JSON.stringify(resultCode)); + console.log("setAuthenticatorProperties onResult, result:" + JSON.stringify(result)); + }, + onRequestRedirected: (request) => { + console.log("setAuthenticatorProperties onRequestRedirected, request:" + JSON.stringify(request)); + } + }); } catch (err) { - console.log("deleteAuthToken err: " + JSON.stringify(err)); - } + console.log("setAuthenticatorProperties err: " + JSON.stringify(err)); + } + ``` -### deleteOAuthToken(deprecated) +### addAccount(deprecated) -deleteOAuthToken(name: string, owner: string, authType: string, token: string, callback: AsyncCallback<void>): void +addAccount(name: string, callback: AsyncCallback<void>): void -删除指定应用帐户和鉴权类型的OAuth令牌，使用callback回调异步返回结果。 +将此应用的帐号名添加到帐号管理服务中。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[deleteAuthToken](#deleteauthtoken9)替代。 +> **说明：** +> 从API version 9开始废弃, 建议使用[createAccount](#createaccount9)替代 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------ | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | 要删除的OAuth令牌。 | -| callback | AsyncCallback<void> | 是 | 删除结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------- | +| name | string | 是 | 要添加的应用帐号名称。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当此应用的帐号名添加到帐号管理服务成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.deleteOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx", (err) => { - console.log('deleteOAuthToken err: ' + JSON.stringify(err)); + appAccountManager.addAccount("WangWu", (err) => { + console.log("addAccount err: " + JSON.stringify(err)); }); ``` -### deleteOAuthToken(deprecated) +### addAccount(deprecated) -deleteOAuthToken(name: string, owner: string, authType: string, token: string): Promise<void> +addAccount(name: string, extraInfo: string, callback: AsyncCallback<void>): void -删除指定应用帐户和鉴权类型的OAuth令牌，使用Promise方式异步返回结果。 +将此应用程序的帐号名和额外信息（能转换string类型的其它信息，如token）添加到帐号管理服务中。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[setAuthToken](#setauthtoken9-1)替代。 -> -> 从 API version 8开始支持。 +> **说明：** > 从API version 9开始废弃, 建议使用[createAccount](#createaccount9-1)替代 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ------------ | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| authType | string | 是 | 鉴权类型。 | -| token | string | 是 | 要删除的OAuth令牌。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| name | string | 是 | 要添加的应用帐号名称。 | +| extraInfo | string | 是 | 要添加的应用帐号的额外信息(能转换string类型的其它信息，如token等)，额外信息不能是应用帐号的敏感信息（如应用账号密码）。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当此应用程序的帐号名和额外信息添加到帐号管理服务成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.deleteOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx").then(() => { - console.log('deleteOAuthToken successfully'); - }).catch((err) => { - console.log("deleteOAuthToken err: " + JSON.stringify(err)); + appAccountManager.addAccount("LiSi", "token101", (err) => { + console.log("addAccount err: " + JSON.stringify(err)); }); ``` -### setAuthTokenVisibility9+ +### addAccount(deprecated) -setAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean, callback: AsyncCallback<void>): void +addAccount(name: string, extraInfo?: string): Promise<void> + +将此应用的帐号名或额外信息（能转换成string类型的其它信息）添加到帐号管理服务中。使用Promise异步回调。 -设置指定鉴权类型的Auth令牌对特定应用的可见性，使用callback回调异步返回结果。 +> **说明：** > 从API version 9开始废弃, 建议使用[createAccount](#createaccount9-2)替代 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------------- | ---- | ------------------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 被设置可见性的应用包名。 | -| isVisible | boolean | 是 | 是否可见。当设置成true可见，false不可见。 | -| callback | AsyncCallback<void> | 是 | 设置结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | ---------------------------------------- | +| name | string | 是 | 要添加的应用帐号名称。 | +| extraInfo | string | 否 | 要添加的应用帐号的额外信息（能转换成string类型的其它信息），额外信息不能是应用帐号的敏感信息（如应用账号密码）。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.setAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true, (err) => { - console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); - }); - } catch (err) { - console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); - } + appAccountManager.addAccount("LiSi", "token101").then(()=> { + console.log('addAccount Success'); + }).catch((err) => { + console.log("addAccount err: " + JSON.stringify(err)); + }); ``` -### setAuthTokenVisibility9+ +### addAccountImplicitly(deprecated) -setAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean): Promise<void> +addAccountImplicitly(owner: string, authType: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void + +根据指定的帐号所有者、鉴权类型和可选项隐式地添加应用帐号，并使用callback回调异步返回结果。 -设置指定鉴权类型的OAuth令牌对特定应用的可见性，使用Promise方式异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[createAccountImplicitly](#createaccountimplicitly9)替代。 +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------- | ---- | ------------ | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 被设置可见性的应用包名。 | -| isVisible | boolean | 是 | 是否可见。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ----------------------- | +| owner | string | 是 | 要添加的应用帐号所有者包名。 | +| authType | string | 是 | 要添加的应用帐号鉴权类型。鉴权类型为自定义。 | +| options | {[key: string]: any} | 是 | 鉴权所需要的可选项。可选项可根据自己需要设置。 | +| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 认证器回调，用于返回鉴权结果。 | **示例：** ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.setAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true).then(() => { - console.log('setAuthTokenVisibility successfully'); - }).catch((err) => { - console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); + import featureAbility from '@ohos.ability.featureAbility'; + + function onResultCallback(code, result) { + console.log("resultCode: " + code); + console.log("result: " + JSON.stringify(result)); + } + + function onRequestRedirectedCallback(request) { + let abilityStartSetting = {want: request}; + featureAbility.startAbility(abilityStartSetting, (err)=>{ + console.log("startAbility err: " + JSON.stringify(err)); }); - } catch (err) { - console.log('setAuthTokenVisibility err: ' + JSON.stringify(err)); } + + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.addAccountImplicitly("com.example.ohos.accountjsdemo", "getSocialData", {}, { + onResult: onResultCallback, + onRequestRedirected: onRequestRedirectedCallback + }); ``` -### setOAuthTokenVisibility(deprecated) +### deleteAccount(deprecated) -setOAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean, callback: AsyncCallback<void>): void +deleteAccount(name: string, callback: AsyncCallback<void>): void -设置指定鉴权类型的Auth令牌对特定应用的可见性，使用callback回调异步返回结果。 +从帐号管理服务中删除应用帐号。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[setAuthTokenVisibility](#setauthtokenvisibility9)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[removeAccount](#removeaccount9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------------- | ---- | ------------------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 被设置可见性的应用包名。 | -| isVisible | boolean | 是 | 是否可见。当设置成true可见，false不可见。 | -| callback | AsyncCallback<void> | 是 | 设置结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------------- | +| name | string | 是 | 要删除的应用帐号名称。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当帐号管理服务中删除应用帐号成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true, (err) => { - console.log('setOAuthTokenVisibility err: ' + JSON.stringify(err)); - }); + appAccountManager.deleteAccount("ZhaoLiu", (err) => { + console.log("deleteAccount err: " + JSON.stringify(err)); + }); ``` -### setOAuthTokenVisibility(deprecated) +### deleteAccount(deprecated) -setOAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean): Promise<void> +deleteAccount(name: string): Promise<void> -设置指定鉴权类型的OAuth令牌对特定应用的可见性，使用Promise方式异步返回结果。 +从帐号管理服务中删除应用帐号。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[setAuthTokenVisibility](#setauthtokenvisibility9-1)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[removeAccount](#removeaccount9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------- | ---- | ------------ | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 被设置可见性的应用包名。 | -| isVisible | boolean | 是 | 是否可见。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | ----------- | +| name | string | 是 | 要删除的应用帐号名称。 | **返回值：** | 类型 | 说明 | -| ------------------- | --------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.setOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true).then(() => { - console.log('setOAuthTokenVisibility successfully'); - }).catch((err) => { - console.log('setOAuthTokenVisibility err: ' + JSON.stringify(err)); + appAccountManager.deleteAccount("ZhaoLiu").then(() => { + console.log('deleteAccount Success'); + }).catch((err) => { + console.log("deleteAccount err: " + JSON.stringify(err)); }); ``` +### disableAppAccess(deprecated) -### checkAuthTokenVisibility9+ +disableAppAccess(name: string, bundleName: string, callback: AsyncCallback<void>): void -checkAuthTokenVisibility(name: string, authType: string, bundleName: string, callback: AsyncCallback<boolean>): void +禁止指定第三方应用帐号名称对指定的第三方应用进行访问。使用callback异步回调。 -检查指定鉴权类型的Auth令牌对特定应用的可见性，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9)替代。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ---------------------------- | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 检查可见性的应用包名。 | -| callback | AsyncCallback<boolean> | 是 | 检查结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | --------------------------------- | +| name | string | 是 | 要禁用访问的第三方应用帐号名称。 | +| bundleName | string | 是 | 第三方应用的包名。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当禁止指定第三方应用帐号名称对指定包名称的第三方应用进行访问设置成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.checkAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", (err, data) => { - console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); - console.log('checkAuthTokenVisibility isVisible: ' + data); - }); - } catch (err) { - console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); - } + appAccountManager.disableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo", (err) => { + console.log("disableAppAccess err: " + JSON.stringify(err)); + }); ``` -### checkAuthTokenVisibility9+ +### disableAppAccess(deprecated) -checkAuthTokenVisibility(name: string, authType: string, bundleName: string): Promise<boolean> +disableAppAccess(name: string, bundleName: string): Promise<void> + +禁止指定第三方应用帐号名称对指定包名称的第三方应用进行访问。使用Promise异步回调。 -检查指定鉴权类型的Auth令牌对特定应用的可见性，使用Promise方式异步返回结果。 +> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9-1)替代。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 用于检查可见性的应用包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ---------------- | +| name | string | 是 | 要禁用访问的第三方应用帐号名称。 | +| bundleName | string | 是 | 第三方应用的包名。 | **返回值：** -| 类型 | 说明 | -| ---------------------- | --------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.checkAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo").then((data) => { - console.log('checkAuthTokenVisibility isVisible: ' + data); - }).catch((err) => { - console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); - }); - } catch (err) { - console.log('checkAuthTokenVisibility err: ' + JSON.stringify(err)); - } + appAccountManager.disableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo").then(() => { + console.log('disableAppAccess Success'); + }).catch((err) => { + console.log("disableAppAccess err: " + JSON.stringify(err)); + }); ``` -### checkOAuthTokenVisibility(deprecated) +### enableAppAccess(deprecated) -checkOAuthTokenVisibility(name: string, authType: string, bundleName: string, callback: AsyncCallback<boolean>): void +enableAppAccess(name: string, bundleName: string, callback: AsyncCallback<void>): void -检查指定鉴权类型的OAuth令牌对特定应用的可见性，使用callback回调异步返回结果。 +允许指定第三方应用帐号名称对指定包名称的第三方应用进行访问。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[checkAuthTokenVisibility](#checkauthtokenvisibility9)替代。 +> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ---------------------------- | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 检查可见性的应用包名。 | -| callback | AsyncCallback<boolean> | 是 | 检查结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | --------------------------------- | +| name | string | 是 | 应用帐号名称。 | +| bundleName | string | 是 | 第三方应用的包名。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当允许指定第三方应用帐号名称对指定包名称的第三方应用进行访问设置成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.checkOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", (err, data) => { - console.log('checkOAuthTokenVisibility err: ' + JSON.stringify(err)); - console.log('checkOAuthTokenVisibility isVisible: ' + data); - }); + appAccountManager.enableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo", (err) => { + console.log("enableAppAccess: " + JSON.stringify(err)); + }); ``` +### enableAppAccess(deprecated) -### checkOAuthTokenVisibility(deprecated) - -checkOAuthTokenVisibility(name: string, authType: string, bundleName: string): Promise<boolean> +enableAppAccess(name: string, bundleName: string): Promise<void> -检查指定鉴权类型的OAuth令牌对特定应用的可见性，使用Promise方式异步返回结果。 +允许指定第三方应用帐号的名称对指定包名称的第三方应用进行访问。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[checkAuthTokenVisibility](#checkauthtokenvisibility9-1)替代。 +> **说明：** 从API version 9开始废弃。建议使用[setAppAccess](#setappaccess9-1)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 鉴权类型。 | -| bundleName | string | 是 | 用于检查可见性的应用包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | --------- | +| name | string | 是 | 应用帐号名称。 | +| bundleName | string | 是 | 第三方应用的包名。 | **返回值：** -| 类型 | 说明 | -| ---------------------- | --------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.checkOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo").then((data) => { - console.log('checkOAuthTokenVisibility isVisible: ' + data); + appAccountManager.enableAppAccess("ZhangSan", "com.example.ohos.accountjsdemo").then(() => { + console.log('enableAppAccess Success'); }).catch((err) => { - console.log('checkOAuthTokenVisibility err: ' + JSON.stringify(err)); + console.log("enableAppAccess err: " + JSON.stringify(err)); }); ``` -### getAllAuthTokens9+ +### checkAppAccountSyncEnable(deprecated) -getAllAuthTokens(name: string, owner: string, callback: AsyncCallback<Array<OAuthTokenInfo>>): void +checkAppAccountSyncEnable(name: string, callback: AsyncCallback<boolean>): void + +检查指定应用帐号是否允许应用数据同步。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃。建议使用[checkDataSyncEnabled](#checkdatasyncenabled9)替代。 +> +> 从 API version 7开始支持。 -获取指定应用对调用方全部可见的Auth令牌，使用callback回调异步返回结果。 +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| callback | AsyncCallback<Array< [AuthTokenInfo](#authtokeninfo9)>> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | --------------------- | +| name | string | 是 | 应用帐号名称。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。当检查指定应用帐号是否允许应用数据同步成功，err为undefined，data返回true表示指定应用帐号允许应用数据同步，data返回false表示指定应用帐号不允许应用数据同步；否则为错误对象。 | -**示例：** +**示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.getAllAuthTokens("LiSi", "com.example.ohos.accountjsdemo", (err, data) => { - console.log("getAllAuthTokens err: " + JSON.stringify(err)); - console.log('getAllAuthTokens data: ' + JSON.stringify(data)); - }); - } catch (err) { - console.log("getAllAuthTokens err: " + JSON.stringify(err)); - } + appAccountManager.checkAppAccountSyncEnable("ZhangSan", (err, result) => { + console.log("checkAppAccountSyncEnable err: " + JSON.stringify(err)); + console.log('checkAppAccountSyncEnable result: ' + result); + }); ``` -### getAllAuthTokens9+ +### checkAppAccountSyncEnable(deprecated) -getAllAuthTokens(name: string, owner: string): Promise<Array<AuthTokenInfo>> +checkAppAccountSyncEnable(name: string): Promise<boolean> + +检查指定应用帐号是否允许应用数据同步。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃。建议使用[checkDataSyncEnabled](#checkdatasyncenabled9-1)替代。 +> +> 从 API version 7开始支持。 -获取指定应用帐户对调用方可见的全部Auth令牌，使用Promise方式异步返回结果。 +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | ------- | +| name | string | 是 | 应用帐号名称。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------------- | --------------------- | -| Promise<Array< [AuthTokenInfo](#authtokeninfo9)>> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :--------------------- | :-------------------- | +| Promise<boolean> | Promise对象。返回true表示允许应用数据同步；返回false表示不允许应用数据同步。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.getAllAuthTokens("LiSi", "com.example.ohos.accountjsdemo").then((data) => { - console.log('getAllAuthTokens data: ' + JSON.stringify(data)); - }).catch((err) => { - console.log("getAllAuthTokens err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("getAllAuthTokens err: " + JSON.stringify(err)); - } + appAccountManager.checkAppAccountSyncEnable("ZhangSan").then((data) => { + console.log('checkAppAccountSyncEnable, result: ' + data); + }).catch((err) => { + console.log("checkAppAccountSyncEnable err: " + JSON.stringify(err)); + }); ``` -### getAllOAuthTokens(deprecated) +### setAccountCredential(deprecated) -getAllOAuthTokens(name: string, owner: string, callback: AsyncCallback<Array<OAuthTokenInfo>>): void +setAccountCredential(name: string, credentialType: string, credential: string,callback: AsyncCallback<void>): void -获取指定应用对调用方全部可见的OAuth令牌，使用callback回调异步返回结果。 +设置此应用程序帐号的凭据。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[getAllAuthTokens](#getallauthtokens9)替代。 +> **说明：** 从API version 9开始废弃，建议使用[setCredential](#setcredential9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | -| callback | AsyncCallback<Array< [OAuthTokenInfo](#oauthtokeninfodeprecated)>> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------------------------- | ---- | ------------- | +| name | string | 是 | 应用程序帐号名称。 | +| credentialType | string | 是 | 要设置的凭据类型。 | +| credential | string | 是 | 要设置的凭据。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置此应用程序帐号的凭据成功时，err为undefined，否则为错误对象。 | -**示例：** +**示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAllOAuthTokens("LiSi", "com.example.ohos.accountjsdemo", (err, data) => { - console.log("getAllOAuthTokens err: " + JSON.stringify(err)); - console.log('getAllOAuthTokens data: ' + JSON.stringify(data)); + appAccountManager.setAccountCredential("ZhangSan", "credentialType001", "credential001", (err) => { + console.log("setAccountCredential err: " + JSON.stringify(err)); }); ``` -### getAllOAuthTokens(deprecated) +### setAccountCredential(deprecated) -getAllOAuthTokens(name: string, owner: string): Promise<Array<OAuthTokenInfo>> +setAccountCredential(name: string, credentialType: string, credential: string): Promise<void> -获取指定应用帐户对调用方可见的全部OAuth令牌，使用Promise方式异步返回结果。 +设置此应用程序帐号的凭据。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[getAllAuthTokens](#getallauthtokens9-1)替代。 +> **说明：** 从API version 9开始废弃，建议使用[setCredential](#setcredential9-1)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------- | -| name | string | 是 | 应用帐号的名称。 | -| owner | string | 是 | 应用帐号的所有者包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------ | ---- | ---------- | +| name | string | 是 | 应用帐号的名称。 | +| credentialType | string | 是 | 要设置的凭据的类型。 | +| credential | string | 是 | 要设置的凭据。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------------- | --------------------- | -| Promise<Array< [OAuthTokenInfo](#oauthtokeninfodeprecated)>> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAllOAuthTokens("LiSi", "com.example.ohos.accountjsdemo").then((data) => { - console.log('getAllOAuthTokens data: ' + JSON.stringify(data)); + appAccountManager.setAccountCredential("ZhangSan", "credentialType001", "credential001").then(() => { + console.log('setAccountCredential Success'); }).catch((err) => { - console.log("getAllOAuthTokens err: " + JSON.stringify(err)); + console.log("setAccountCredential err: " + JSON.stringify(err)); }); ``` -### getAuthList9+ +### setAccountExtraInfo(deprecated) -getAuthList(name: string, authType: string, callback: AsyncCallback<Array<string>>): void +setAccountExtraInfo(name: string, extraInfo: string, callback: AsyncCallback<void>): void + +设置此应用程序帐号的额外信息。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃。 +> +> 从 API version 7开始支持。 -获取指定应用帐户和鉴权类型的Auth令牌的授权列表，使用callback回调异步返回结果。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 应用帐号的鉴权类型的Auth令牌的授权列表。 | -| callback | AsyncCallback<Array<string>> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | --------------- | +| name | string | 是 | 应用帐号名称。 | +| extraInfo | string | 是 | 要设置的额外信息。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置此应用程序帐号的额外信息成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.getAuthList("com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { - console.log('getAuthList err: ' + JSON.stringify(err)); - console.log('getAuthList data: ' + JSON.stringify(data)); - }); - } catch (err) { - console.log('getAuthList err: ' + JSON.stringify(err)); - } + appAccountManager.setAccountExtraInfo("ZhangSan", "Tk002", (err) => { + console.log("setAccountExtraInfo err: " + JSON.stringify(err)); + }); ``` -### getAuthList9+ +### setAccountExtraInfo(deprecated) -getAuthList(name: string, authType: string): Promise<Array<string>> +setAccountExtraInfo(name: string, extraInfo: string): Promise<void> + +设置此应用程序帐号的额外信息。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃。 +> +> 从 API version 7开始支持。 -获取指定应用帐户和鉴权类型的Auth令牌的授权列表，使用Promise方式异步返回结果。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 应用帐号的鉴权类型的Auth令牌的授权列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | --------- | +| name | string | 是 | 应用帐号名称。 | +| extraInfo | string | 是 | 要设置的额外信息。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------- | --------------------- | -| Promise<Array<string>> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.getAuthList("com.example.ohos.accountjsdemo", "getSocialData").then((data) => { - console.log('getAuthList data: ' + JSON.stringify(data)); - }).catch((err) => { - console.log("getAuthList err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("getAuthList err: " + JSON.stringify(err)); - } + appAccountManager.setAccountExtraInfo("ZhangSan", "Tk002").then(() => { + console.log('setAccountExtraInfo Success'); + }).catch((err) => { + console.log("setAccountExtraInfo err: " + JSON.stringify(err)); + }); ``` -### getOAuthList(deprecated) +### setAppAccountSyncEnable(deprecated) -getOAuthList(name: string, authType: string, callback: AsyncCallback<Array<string>>): void +setAppAccountSyncEnable(name: string, isEnable: boolean, callback: AsyncCallback<void>): void -获取指定应用帐户和鉴权类型的OAuth令牌的授权列表，使用callback回调异步返回结果。 +设置指定的应用程序帐号是否允许应用程序数据同步。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[getAuthList](#getauthlist9)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[setDataSyncEnabled](#setdatasyncenabled9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 应用帐号的鉴权类型的OAuth令牌的授权列表。 | -| callback | AsyncCallback<Array<string>> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------- | +| name | string | 是 | 应用帐号名称。 | +| isEnable | boolean | 是 | 是否允许应用数据同步。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定的应用帐号是否允许应用程序数据同步成功时，err为undefined，否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getOAuthList("com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { - console.log('getOAuthList err: ' + JSON.stringify(err)); - console.log('getOAuthList data: ' + JSON.stringify(data)); + appAccountManager.setAppAccountSyncEnable("ZhangSan", true, (err) => { + console.log("setAppAccountSyncEnable err: " + JSON.stringify(err)); }); ``` -### getOAuthList(deprecated) +### setAppAccountSyncEnable(deprecated) -getOAuthList(name: string, authType: string): Promise<Array<string>> +setAppAccountSyncEnable(name: string, isEnable: boolean): Promise<void> -获取指定应用帐户和鉴权类型的OAuth令牌的授权列表，使用Promise方式异步返回结果。 +设置指定的应用程序帐号是否允许应用程序数据同步。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[getAuthList](#getauthlist9-1)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[setDataSyncEnabled](#setdatasyncenabled9-1)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------- | -| name | string | 是 | 应用帐号的名称。 | -| authType | string | 是 | 应用帐号的鉴权类型的OAuth令牌的授权列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------- | ---- | ----------- | +| name | string | 是 | 应用帐号名称。 | +| isEnable | boolean | 是 | 是否允许应用数据同步。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------- | --------------------- | -| Promise<Array<string>> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getOAuthList("com.example.ohos.accountjsdemo", "getSocialData").then((data) => { - console.log('getOAuthList data: ' + JSON.stringify(data)); + appAccountManager .setAppAccountSyncEnable("ZhangSan", true).then(() => { + console.log('setAppAccountSyncEnable Success'); }).catch((err) => { - console.log("getOAuthList err: " + JSON.stringify(err)); + console.log("setAppAccountSyncEnable err: " + JSON.stringify(err)); }); ``` -### getAuthCallback9+ +### setAssociatedData(deprecated) -getAuthCallback(sessionId: string, callback: AsyncCallback<AuthCallback>): void +setAssociatedData(name: string, key: string, value: string, callback: AsyncCallback<void>): void + +设置与此应用程序帐号关联的数据。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setCustomData](#setcustomdata9)替代。 +> +> 从 API version 7开始支持。 -获取鉴权会话的认证器回调，使用callback回调异步返回结果。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ---------------------------------------- | ---- | -------- | -| sessionId | string | 是 | 鉴权会话的标识。 | -| callback | AsyncCallback<[AuthCallback](#authcallback9)> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ----------------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | +| value | string | 是 | 要设置的数据的值。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置与此应用帐号关联的数据成功时，err为undefined，否则为错误对象。 | **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; const appAccountManager = account_appAccount.createAppAccountManager(); - featureAbility.getWant((err, want) => { - var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; - try { - appAccountManager.getAuthCallback(sessionId, (err, callback) => { - if (err.code != account_appAccount.ResultCode.SUCCESS) { - console.log("getAuthCallback err: " + JSON.stringify(err)); - return; - } - var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", - [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", - [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", - [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; - callback.onResult(account_appAccount.ResultCode.SUCCESS, result); - }); - } catch (err) { - console.log("getAuthCallback err: " + JSON.stringify(err)); - } + appAccountManager.setAssociatedData("ZhangSan", "k001", "v001", (err) => { + console.log("setAssociatedData err: " + JSON.stringify(err)); }); ``` -### getAuthCallback9+ +### setAssociatedData(deprecated) -getAuthCallback(sessionId: string): Promise<AuthCallback> +setAssociatedData(name: string, key: string, value: string): Promise<void> + +设置与此应用程序帐号关联的数据。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setCustomData](#setcustomdata9-1)替代。 +> +> 从 API version 7开始支持。 -获取鉴权会话的认证器回调，使用Promise方式异步返回结果。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | -------- | -| sessionId | string | 是 | 鉴权会话的标识。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要设置的数据的键，密钥可以自定义。 | +| value | string | 是 | 要设置的数据的值。 | **返回值：** -| 类型 | 说明 | -| ------------------------------------ | --------------------- | -| Promise<[AuthCallback](#authcallback9)> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :-------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; - const appAccountManager = account_appAccount.createAppAccountManager(); - featureAbility.getWant().then((want) => { - var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; - try { - appAccountManager.getAuthCallback(sessionId).then((callback) => { - var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", - [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", - [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", - [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; - callback.onResult(account_appAccount.ResultCode.SUCCESS, result); - }).catch((err) => { - console.log("getAuthCallback err: " + JSON.stringify(err)); - }); - } + appAccountManager.setAssociatedData("ZhangSan", "k001", "v001").then(() => { + console.log('setAssociatedData Success'); }).catch((err) => { - console.log("getWant err: " + JSON.stringify(err)); + console.log("setAssociatedData err: " + JSON.stringify(err)); }); ``` -### getAuthenticatorCallback(deprecated) +### getAllAccessibleAccounts(deprecated) -getAuthenticatorCallback(sessionId: string, callback: AsyncCallback<AuthenticatorCallback>): void +getAllAccessibleAccounts(callback: AsyncCallback<Array<AppAccountInfo>>): void -获取鉴权会话的认证器回调，使用callback回调异步返回结果。 +获取全部应用已授权帐号信息。 -> **说明：** 从API version 9开始废弃, 建议使用[getAuthCallback](#getauthcallback9)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[getAllAccounts](#getallaccounts9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ---------------------------------------- | ---- | -------- | -| sessionId | string | 是 | 鉴权会话的标识。 | -| callback | AsyncCallback<[AuthenticatorCallback](#authenticatorcallbackdeprecated)> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; const appAccountManager = account_appAccount.createAppAccountManager(); - featureAbility.getWant((err, want) => { - var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; - appAccountManager.getAuthenticatorCallback(sessionId, (err, callback) => { - if (err.code != account_appAccount.ResultCode.SUCCESS) { - console.log("getAuthenticatorCallback err: " + JSON.stringify(err)); - return; - } - var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", - [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", - [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", - [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; - callback.onResult(account_appAccount.ResultCode.SUCCESS, result); - }); + appAccountManager.getAllAccessibleAccounts((err, data)=>{ + console.debug("getAllAccessibleAccounts err:" + JSON.stringify(err)); + console.debug("getAllAccessibleAccounts data:" + JSON.stringify(data)); }); ``` -### getAuthenticatorCallback(deprecated) +### getAllAccessibleAccounts(deprecated) -getAuthenticatorCallback(sessionId: string): Promise<AuthenticatorCallback> +getAllAccessibleAccounts(): Promise<Array<AppAccountInfo>> -获取鉴权会话的认证器回调，使用Promise方式异步返回结果。 +获取全部应用已授权帐号信息。 -> **说明：** 从API version 9开始废弃, 建议使用[getAuthCallback](#getauthcallback9-1)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[getAllAccounts](#getallaccounts9-1)替代。 > -> 从 API version 8开始支持。 - -**系统能力：** SystemCapability.Account.AppAccount +> 从 API version 7开始支持。 -**参数：** +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | -------- | -| sessionId | string | 是 | 鉴权会话的标识。 | +**系统能力：** SystemCapability.Account.AppAccount **返回值：** -| 类型 | 说明 | -| ------------------------------------ | --------------------- | -| Promise<[AuthenticatorCallback](#authenticatorcallbackdeprecated)> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ---------------------------------------- | --------------------- | +| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise对象。返回全部应用已授权帐号信息对象。 | **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; - const appAccountManager = account_appAccount.createAppAccountManager(); - featureAbility.getWant().then((want) => { - var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; - appAccountManager.getAuthenticatorCallback(sessionId).then((callback) => { - var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", - [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", - [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", - [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; - callback.onResult(account_appAccount.ResultCode.SUCCESS, result); - }).catch((err) => { - console.log("getAuthenticatorCallback err: " + JSON.stringify(err)); - }); + appAccountManager.getAllAccessibleAccounts().then((data) => { + console.log('getAllAccessibleAccounts: ' + data); }).catch((err) => { - console.log("getWant err: " + JSON.stringify(err)); + console.log("getAllAccessibleAccounts err: " + JSON.stringify(err)); }); ``` -### queryAuthenticatorInfo9+ +### getAllAccounts(deprecated) -queryAuthenticatorInfo(owner: string, callback: AsyncCallback<AuthenticatorInfo>): void +getAllAccounts(owner: string, callback: AsyncCallback<Array<AppAccountInfo>>): void + +获取指定应用全部帐号信息。 -获取指定应用帐号的认证器信息，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[getAccountsByOwner]替代。 +> +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------------------- | ---- | ----------- | -| owner | string | 是 | 应用帐号的所有者包名。 | -| callback | AsyncCallback<[AuthenticatorInfo](#authenticatorinfo8)> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------- | +| owner | string | 是 | 应用包名称。 | +| callback | AsyncCallback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 应用帐号信息列表。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.queryAuthenticatorInfo("com.example.ohos.accountjsdemo", (err, data) => { - console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); - console.log('queryAuthenticatorInfo data: ' + JSON.stringify(data)); - }); - } catch (err) { - console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); - } + const selfBundle = "com.example.actsgetallaaccounts"; + appAccountManager.getAllAccounts(selfBundle, (err, data)=>{ + console.debug("getAllAccounts err:" + JSON.stringify(err)); + console.debug("getAllAccounts data:" + JSON.stringify(data)); + }); ``` -### queryAuthenticatorInfo9+ +### getAllAccounts(deprecated) -queryAuthenticatorInfo(owner: string): Promise<AuthenticatorInfo> +getAllAccounts(owner: string): Promise<Array<AppAccountInfo>> + +获取指定应用全部帐号信息。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAccountsByOwner](#getaccountsbyowner9-1)替代。 +> +> 从 API version 7开始支持。 -获取指定应用帐户的认证器信息，使用Promise方式异步返回结果。 +**需要权限：** ohos.permission.GET_ALL_APP_ACCOUNTS，仅系统应用可用。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------- | -| owner | string | 是 | 应用帐号的所有者包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ------ | +| owner | string | 是 | 应用包名称。 | **返回值：** -| 类型 | 说明 | -| -------------------------------- | --------------------- | -| Promise<[AuthenticatorInfo](#authenticatorinfo8)> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ---------------------------------------- | --------------------- | +| Promise<Array<[AppAccountInfo](#appaccountinfo)>> | Promise对象。返回指定应用全部帐号信息对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.queryAuthenticatorInfo("com.example.ohos.accountjsdemo").then((data) => { - console.log('queryAuthenticatorInfo: ' + JSON.stringify(data)); - }).catch((err) => { - console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("queryAuthenticatorInfo err: " + JSON.stringify(err)); - } + const selfBundle = "com.example.actsgetallaaccounts"; + appAccountManager.getAllAccounts(selfBundle).then((data) => { + console.log('getAllAccounts: ' + data); + }).catch((err) => { + console.log("getAllAccounts err: " + JSON.stringify(err)); + }); ``` -### getAuthenticatorInfo(deprecated) +### getAccountCredential(deprecated) -getAuthenticatorInfo(owner: string, callback: AsyncCallback<AuthenticatorInfo>): void +getAccountCredential(name: string, credentialType: string, callback: AsyncCallback<string>): void -获取指定应用帐号的认证器信息，使用callback回调异步返回结果。 +获取此应用帐号的凭据（如数字密码、人脸和PIN码等）。使用callback异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[queryAuthenticatorInfo](#queryauthenticatorinfo9)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[getCredential](#getcredential9)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------------------- | ---- | ----------- | -| owner | string | 是 | 应用帐号的所有者包名。 | -| callback | AsyncCallback<[AuthenticatorInfo](#authenticatorinfo8)> | 是 | 查询结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------- | ---- | -------------- | +| name | string | 是 | 应用帐号名称。 | +| credentialType | string | 是 | 获取此应用帐号的凭据的类型。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取此应用帐号的凭据成功时，err为undefined，data返回此应用帐号的凭据对象；否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAuthenticatorInfo("com.example.ohos.accountjsdemo", (err, data) => { - console.log("getAuthenticatorInfo err: " + JSON.stringify(err)); - console.log('getAuthenticatorInfo data: ' + JSON.stringify(data)); + appAccountManager.getAccountCredential("ZhangSan", "credentialType001", (err, result) => { + console.log("getAccountCredential err: " + JSON.stringify(err)); + console.log('getAccountCredential result: ' + result); }); ``` -### getAuthenticatorInfo(deprecated) +### getAccountCredential(deprecated) -getAuthenticatorInfo(owner: string): Promise<AuthenticatorInfo> +getAccountCredential(name: string, credentialType: string): Promise<string> -获取指定应用帐户的认证器信息，使用Promise方式异步返回结果。 +获取此应用程序帐号的凭据。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[queryAuthenticatorInfo](#queryauthenticatorinfo9-1)替代。 +> **说明：** 从API version 9开始废弃, 建议使用[getCredential](#getcredential9-1)替代。 > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------- | -| owner | string | 是 | 应用帐号的所有者包名。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------ | ---- | ---------- | +| name | string | 是 | 应用帐号名称。 | +| credentialType | string | 是 | 要获取的凭据的类型。 | **返回值：** -| 类型 | 说明 | -| -------------------------------- | --------------------- | -| Promise<[AuthenticatorInfo](#authenticatorinfo8)> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :-------------------- | +| Promise<string> | Promise对象。返回此应用程序帐号的凭据对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - appAccountManager.getAuthenticatorInfo("com.example.ohos.accountjsdemo").then((data) => { - console.log('getAuthenticatorInfo: ' + JSON.stringify(data)); + appAccountManager.getAccountCredential("ZhangSan", "credentialType001").then((data) => { + console.log('getAccountCredential, result: ' + data); }).catch((err) => { - console.log("getAuthenticatorInfo err: " + JSON.stringify(err)); + console.log("getAccountCredential err: " + JSON.stringify(err)); }); ``` -### checkAccountLabels9+ +### getAccountExtraInfo(deprecated) -checkAccountLabels(name: string, owner: string, labels: Array<string>, callback: AsyncCallback<boolean>): void; +getAccountExtraInfo(name: string, callback: AsyncCallback<string>): void + +获取此应用帐号的额外信息（能转换成string类型的其它信息）。使用callback异步回调。 -检查指定帐户是否具有特定的标签集合，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------------------------- | ----- | --------------- | -| name | string | 是 | 应用帐户的名称。 | -| owner | string | 是 | 应用帐户的所有者。| -| labels | Array<string> | 是 | 标签数组。 | -| callback | AsyncCallback<boolean> | 是 | 检查结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------- | +| name | string | 是 | 应用帐号名称。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取此应用帐号的额外信息成功时，err为undefined，data返回此应用帐号的额外信息对象；否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - var labels = ["student"]; - try { - appAccountManager.checkAccountLabels("zhangsan", "com.example.ohos.accountjsdemo", labels, (err, data) => { - console.log('checkAccountLabels: ' + JSON.stringify(data)); - console.log("checkAccountLabels err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("checkAccountLabels err: " + JSON.stringify(err)); - } + appAccountManager.getAccountExtraInfo("ZhangSan", (err, result) => { + console.log("getAccountExtraInfo err: " + JSON.stringify(err)); + console.log('getAccountExtraInfo result: ' + result); + }); ``` -### checkAccountLabels9+ +### getAccountExtraInfo(deprecated) -checkAccountLabels(name: string, owner: string, labels: Array<string>): Promise<boolean> +getAccountExtraInfo(name: string): Promise<string> -检查指定帐户是否具有特定的标签集合，使用Promise方式异步返回结果。 +获取此应用程序帐号的额外信息。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------------------------- | ----- | --------------- | -| name | string | 是 | 应用帐户的名称。 | -| owner | string | 是 | 应用帐户的所有者。| -| labels | Array<string> | 是 | 标签数组。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | ------- | +| name | string | 是 | 应用帐号名称。 | **返回值：** -| 类型 | 说明 | -| ------------------- | -------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :-------------------- | +| Promise<string> | Promise对象。返回此应用程序帐号的额外信息对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - var labels = ["student"]; - try { - appAccountManager.checkAccountLabels("zhangsan", "com.example.ohos.accountjsdemo", labels).then((data) => { - console.log('checkAccountLabels: ' + JSON.stringify(data)); - }).catch((err) => { - console.log("checkAccountLabels err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("checkAccountLabels err: " + JSON.stringify(err)); - } + appAccountManager.getAccountExtraInfo("ZhangSan").then((data) => { + console.log('getAccountExtraInfo, result: ' + data); + }).catch((err) => { + console.log("getAccountExtraInfo err: " + JSON.stringify(err)); + }); ``` -### deleteAccountCredential9+ +### getAssociatedData(deprecated) + +getAssociatedData(name: string, key: string, callback: AsyncCallback<string>): void -deleteAccountCredential(name: string, credentialType: string, callback: AsyncCallback<void>): void +获取与此应用程序帐号关联的数据。使用callback异步回调。 -删除指定应用帐户的指定类型的凭据信息，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[getCustomData](#getcustomdata9)替代。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------------------------- | ----- | -------------- | -| name | string | 是 | 应用帐户的名称。 | -| credentialType | string | 是 | 凭据类型。 | -| callback | AsyncCallback<void> | 是 | 删除结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要获取的数据的键。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取与此应用程序帐号关联的数据成功时，err为undefined，data返回与此应用程序帐号关联的数据对象；否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.deleteAccountCredential("zhangsan", "pin", (err, data) => { - console.log('deleteAccountCredential: ' + JSON.stringify(data)); - console.log("deleteAccountCredential err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("deleteAccountCredential err: " + JSON.stringify(err)); - } + appAccountManager.getAssociatedData("ZhangSan", "k001", (err, result) => { + console.log("getAssociatedData err: " + JSON.stringify(err)); + console.log('getAssociatedData result: ' + result); + }); ``` -### deleteAccountCredential9+ +### getAssociatedData(deprecated) + +getAssociatedData(name: string, key: string): Promise<string> -deleteAccountCredential(name: string, credentialType: string): Promise<void> +获取与此应用程序帐号关联的数据。使用Promise异步回调。 -删除指定应用帐户的指定类型的凭据信息，使用Promise方式异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[getCustomData](#getcustomdata9-1)替代。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------ | ----- | --------------- | -| name | string | 是 | 应用帐户的名称。 | -| credentialType | string | 是 | 凭据类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | --------- | +| name | string | 是 | 应用帐号名称。 | +| key | string | 是 | 要获取的数据的键。 | **返回值：** -| 类型 | 说明 | -| ------------------- | -------------------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :-------------------- | +| Promise<string> | Promise对象。返回与此应用程序帐号关联的数据对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.deleteAccountCredential("zhangsan", "pin").then((data) => { - console.log('deleteAccountCredential: ' + JSON.stringify(data)); - }).catch((err) => { - console.log("deleteAccountCredential err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("deleteAccountCredential err: " + JSON.stringify(err)); - } + appAccountManager.getAssociatedData("ZhangSan", "k001").then((data) => { + console.log('getAssociatedData: ' + data); + }).catch((err) => { + console.log("getAssociatedData err: " + JSON.stringify(err)); + }); ``` -### selectAccountsByOptions9+ +### on('change')(deprecated) -selectAccountsByOptions(options: SelectAccountsOptions, callback: AsyncCallback<Array<AppAccountInfo>>); +on(type: 'change', owners: Array<string>, callback: Callback<Array<AppAccountInfo>>): void + +订阅指定帐号所有者的帐户变更事件。使用callback异步回调。 -根据选项选择请求方可访问的帐号列表，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[on('accountChange')](#onaccountchange9)替代。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ----------------------------------- | ----- | --------------- | -| options | SelectAccountsOptions | 是 | 选择帐户的选项。 | -| callback | AsyncCallback<[AppAccountInfo](#appaccountinfo)> | 是 | 选择结果的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------ | +| type | 'change' | 是 | 事件回调类型，支持的事件为'change'，当帐号所有者更新帐号时，触发该事件。 | +| owners | Array<string> | 是 | 指示帐号的所有者。 | +| callback | Callback<Array<[AppAccountInfo](#appaccountinfo)>> | 是 | 回调函数。返回指定帐号所有者更新的帐号信息数组。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - var options = { - allowedOwners: ["com.example.ohos.accountjsdemo"] - }; - try { - appAccountManager.selectAccountsByOptions(options, (err, data) => { - console.log('selectAccountsByOptions: ' + JSON.stringify(data)); - console.log("selectAccountsByOptions err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("selectAccountsByOptions err: " + JSON.stringify(err)); + function changeOnCallback(data){ + console.debug("receive change data:" + JSON.stringify(data)); + } + try{ + appAccountManager.on('change', ["com.example.actsaccounttest"], changeOnCallback); + } + catch(err){ + console.error("on accountOnOffDemo err:" + JSON.stringify(err)); } ``` -### selectAccountsByOptions9+ +### off('change')(deprecated) -selectAccountsByOptions(options: SelectAccountsOptions): Promise<Array<AppAccountInfo>> +off(type: 'change', callback?: Callback>): void + +取消订阅帐号事件。使用callback异步回调。 -根据选项选择请求方可访问的帐户列表，使用Promise方式异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[off('accountChange')](#offaccountchange9)替代。 +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------------------------- | ----- | --------------- | -| options | [SelectAccountsOptions](#selectaccountsoptions9) | 是 | 选择帐户的选项。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | -------------------------------- | -| Promise<[AppAccountInfo](#appaccountinfo)> | Promise实例，用于获取异步返回结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------- | ---- | ------------ | +| type | 'change' | 是 | 事件回调类型，支持的事件为'change'，当帐号所有者更新帐号时，触发该事件。 | +| callback | Callback> | 否 | 回调函数，返回指定帐号所有者更新的帐号信息数组。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - var options = { - allowedOwners: ["com.example.ohos.accountjsdemo"] - }; - try { - appAccountManager.selectAccountsByOptions(options).then((data) => { - console.log('selectAccountsByOptions: ' + JSON.stringify(data)); - }).catch((err) => { - console.log("selectAccountsByOptions err: " + JSON.stringify(err)); - }); - } catch (err) { - console.log("selectAccountsByOptions err: " + JSON.stringify(err)); + function changeOnCallback(data){ + console.debug("receive change data:" + JSON.stringify(data)); + appAccountManager.off('change', function(){ + console.debug("off finish"); + }) + } + try{ + appAccountManager.on('change', ["com.example.actsaccounttest"], changeOnCallback); + } + catch(err){ + console.error("on accountOnOffDemo err:" + JSON.stringify(err)); } ``` -### verifyCredential9+ +### authenticate(deprecated) -verifyCredential(name: string, owner: string, callback: AuthenticatorCallback): void; +authenticate(name: string, owner: string, authType: string, options: {[key: string]: any}, callback: AuthenticatorCallback): void + +对应用帐户进行鉴权以获取OAuth令牌。使用callback异步回调。 -验证用户凭据，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[auth](#auth9)替代。 +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ----- | ----------------------- | -| name | string | 是 | 应用帐户的名称。 | -| owner | string | 是 | 应用帐户的所有者。 | -| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 认证器回调，返回验证结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | --------------- | +| name | string | 是 | 要鉴权的应用帐号名称。 | +| owner | string | 是 | 要鉴权的应用帐号所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| options | {[key: string]: any} | 是 | 鉴权所需的可选项。 | +| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 回调函数。返回鉴权结果对象。 | **示例：** ```js - const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.verifyCredential("zhangsan", "com.example.ohos.accountjsdemo", { - onResult: (resultCode, result) => { - console.log("verifyCredential onResult, resultCode:" + JSON.stringify(resultCode)); - console.log("verifyCredential onResult, result:" + JSON.stringify(result)); - }, - onRequestRedirected: (request) => { - console.log("verifyCredential onRequestRedirected, request:" + JSON.stringify(request)); - } + import featureAbility from '@ohos.ability.featureAbility'; + + function onResultCallback(code, result) { + console.log("resultCode: " + code); + console.log("result: " + JSON.stringify(result)); + } + + function onRequestRedirectedCallback(request) { + let abilityStartSetting = {want: request}; + featureAbility.startAbility(abilityStartSetting, (err)=>{ + console.log("startAbility err: " + JSON.stringify(err)); }); - } catch (err) { - console.log("verifyCredential err: " + JSON.stringify(err)); } + + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.authenticate("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", {}, { + onResult: onResultCallback, + onRequestRedirected: onRequestRedirectedCallback + }); ``` -### verifyCredential9+ +### getOAuthToken(deprecated) -verifyCredential(name: string, owner: string, options: VerifyCredentialOptions, callback: AuthenticatorCallback): void; +getOAuthToken(name: string, owner: string, authType: string, callback: AsyncCallback<string>): void -验证用户凭据，使用callback回调异步返回结果。 +获取指定应用帐号和鉴权类型的OAuth令牌。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAuthToken](#getauthtoken9)替代。 +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ----- | ----------------------- | -| name | string | 是 | 应用帐户的名称。 | -| owner | string | 是 | 应用帐户的所有者。 | -| options | [VerifyCredentialOptions](#verifycredentialoptions9) | 是 | 验证凭据的选项。 | -| callback | [AuthenticatorCallback](#authenticatorcallbackdeprecated) | 是 | 认证器回调，返回验证结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当获取指定应用帐号和鉴权类型的Auth令牌成功时，err为undefined，data返回Auth令牌对象；否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - var options = { - credentialType: "pin", - credential: "123456" - }; - try { - appAccountManager.verifyCredential("zhangsan", "com.example.ohos.accountjsdemo", options, { - onResult: (resultCode, result) => { - console.log("verifyCredential onResult, resultCode:" + JSON.stringify(resultCode)); - console.log("verifyCredential onResult, result:" + JSON.stringify(result)); - }, - onRequestRedirected: (request) => { - console.log("verifyCredential onRequestRedirected, request:" + JSON.stringify(request)); - } - }); - } catch (err) { - console.log("verifyCredential err: " + JSON.stringify(err)); - } + appAccountManager.getOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { + console.log('getOAuthToken err: ' + JSON.stringify(err)); + console.log('getOAuthToken token: ' + data); + }); ``` -### setAuthenticatorProperties9+ +### getOAuthToken(deprecated) -setAuthenticatorProperties(owner: string, callback: AuthCallback): void; +getOAuthToken(name: string, owner: string, authType: string): Promise<string> + +获取指定应用帐户和鉴权类型的OAuth令牌。使用Promise异步回调。 -设置认证器属性，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[getAuthToken](#getauthtoken9-1)替代。 +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ----- | ----------------------- | -| owner | string | 是 | 认证器的所有者。 | -| callback | [AuthCallback](#authcallback9) | 是 | 认证器回调，返回设置结果。 | - -**示例：** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------- | --------------------- | +| Promise<string> | Promise对象。返回指定应用帐户和鉴权类型的OAuth令牌对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.getOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData").then((data) => { + console.log('getOAuthToken token: ' + data); + }).catch((err) => { + console.log("getOAuthToken err: " + JSON.stringify(err)); + }); + ``` + +### setOAuthToken(deprecated) + +setOAuthToken(name: string, authType: string, token: string, callback: AsyncCallback<void>): void + +设置指定应用帐号和鉴权类型的OAuth令牌。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setAuthToken](#setauthtoken9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | OAuth令牌。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定应用帐号和鉴权类型的OAuth令牌成功时，err为undefined；否则为错误对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.setOAuthToken("LiSi", "getSocialData", "xxxx", (err) => { + console.log('setOAuthToken err: ' + JSON.stringify(err)); + }); + ``` + +### setOAuthToken(deprecated) + +setOAuthToken(name: string, authType: string, token: string): Promise<void> + +设置指定应用帐户和鉴权类型的OAuth令牌。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setAuthToken](#setauthtoken9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | -------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | OAuth令牌。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.setOAuthToken("LiSi", "getSocialData", "xxxx").then(() => { + console.log('setOAuthToken successfully'); + }).catch((err) => { + console.log('setOAuthToken err: ' + JSON.stringify(err)); + }); + ``` + +### deleteOAuthToken(deprecated) + +deleteOAuthToken(name: string, owner: string, authType: string, token: string, callback: AsyncCallback<void>): void + +删除指定应用帐户和鉴权类型的OAuth令牌。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[deleteAuthToken](#deleteauthtoken9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------ | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | 要删除的OAuth令牌。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当删除指定应用帐户和鉴权类型的OAuth令牌成功时，err为undefined；否则为错误对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.deleteOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx", (err) => { + console.log('deleteOAuthToken err: ' + JSON.stringify(err)); + }); + ``` + +### deleteOAuthToken(deprecated) + +deleteOAuthToken(name: string, owner: string, authType: string, token: string): Promise<void> + +删除指定应用帐户和鉴权类型的OAuth令牌。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setAuthToken](#setauthtoken9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------ | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| authType | string | 是 | 鉴权类型。 | +| token | string | 是 | 要删除的OAuth令牌。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.deleteOAuthToken("LiSi", "com.example.ohos.accountjsdemo", "getSocialData", "xxxxx").then(() => { + console.log('deleteOAuthToken successfully'); + }).catch((err) => { + console.log("deleteOAuthToken err: " + JSON.stringify(err)); + }); + ``` + +### setOAuthTokenVisibility(deprecated) + +setOAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean, callback: AsyncCallback<void>): void + +设置指定鉴权类型的Auth令牌对特定应用的可见性。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setAuthTokenVisibility](#setauthtokenvisibility9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | ------------------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 被设置可见性的应用包名。 | +| isVisible | boolean | 是 | 是否可见。当设置成true可见，false不可见。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定鉴权类型的Auth令牌对特定应用的可见性成功时，err为undefined；否则为错误对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.setOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true, (err) => { + console.log('setOAuthTokenVisibility err: ' + JSON.stringify(err)); + }); + ``` + +### setOAuthTokenVisibility(deprecated) + +setOAuthTokenVisibility(name: string, authType: string, bundleName: string, isVisible: boolean): Promise<void> + +设置指定鉴权类型的OAuth令牌对特定应用的可见性。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[setAuthTokenVisibility](#setauthtokenvisibility9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------- | ---- | ------------ | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 被设置可见性的应用包名。 | +| isVisible | boolean | 是 | 是否可见。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | --------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.setOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", true).then(() => { + console.log('setOAuthTokenVisibility successfully'); + }).catch((err) => { + console.log('setOAuthTokenVisibility err: ' + JSON.stringify(err)); + }); + ``` + +### checkOAuthTokenVisibility(deprecated) + +checkOAuthTokenVisibility(name: string, authType: string, bundleName: string, callback: AsyncCallback<boolean>): void + +检查指定鉴权类型的OAuth令牌对特定应用的可见性。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[checkAuthTokenVisibility](#checkauthtokenvisibility9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------- | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 检查可见性的应用包名。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。检查指定鉴权类型的OAuth令牌对特定应用的可见性时，err为undefined，data为true表示可见，data为false表示不可见；否则为错误对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.checkOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo", (err, data) => { + console.log('checkOAuthTokenVisibility err: ' + JSON.stringify(err)); + console.log('checkOAuthTokenVisibility isVisible: ' + data); + }); + ``` + +### checkOAuthTokenVisibility(deprecated) + +checkOAuthTokenVisibility(name: string, authType: string, bundleName: string): Promise<boolean> + +检查指定鉴权类型的OAuth令牌对特定应用的可见性。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[checkAuthTokenVisibility](#checkauthtokenvisibility9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 鉴权类型。 | +| bundleName | string | 是 | 用于检查可见性的应用包名。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------- | --------------------- | +| Promise<boolean> | Promise对象。返回true表示指定鉴权类型的OAuth令牌对特定应用的可见，返回false表示不可见。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.checkOAuthTokenVisibility("LiSi", "getSocialData", "com.example.ohos.accountjsdemo").then((data) => { + console.log('checkOAuthTokenVisibility isVisible: ' + data); + }).catch((err) => { + console.log('checkOAuthTokenVisibility err: ' + JSON.stringify(err)); + }); + ``` + +### getAllOAuthTokens(deprecated) + +getAllOAuthTokens(name: string, owner: string, callback: AsyncCallback<Array<OAuthTokenInfo>>): void + +获取指定应用对调用方全部可见的OAuth令牌。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAllAuthTokens](#getallauthtokens9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | +| callback | AsyncCallback<Array< [OAuthTokenInfo](#oauthtokeninfodeprecated)>> | 是 | 回调函数。当获取指定应用对调用方全部可见的OAuth令牌成功时，err为undefined，data为全部可见的OAuth令牌数组；否则为错误对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.getAllOAuthTokens("LiSi", "com.example.ohos.accountjsdemo", (err, data) => { + console.log("getAllOAuthTokens err: " + JSON.stringify(err)); + console.log('getAllOAuthTokens data: ' + JSON.stringify(data)); + }); + ``` + +### getAllOAuthTokens(deprecated) + +getAllOAuthTokens(name: string, owner: string): Promise<Array<OAuthTokenInfo>> + +获取指定应用帐户对调用方可见的全部OAuth令牌。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAllAuthTokens](#getallauthtokens9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------- | +| name | string | 是 | 应用帐号的名称。 | +| owner | string | 是 | 应用帐号的所有者包名。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | --------------------- | +| Promise<Array< [OAuthTokenInfo](#oauthtokeninfodeprecated)>> | Promise对象。返回指定应用帐户对调用方可见的全部OAuth令牌对象。 | + +**示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - try { - appAccountManager.setAuthenticatorProperties("com.example.ohos.accountjsdemo", { - onResult: (resultCode, result) => { - console.log("setAuthenticatorProperties onResult, resultCode:" + JSON.stringify(resultCode)); - console.log("setAuthenticatorProperties onResult, result:" + JSON.stringify(result)); - }, - onRequestRedirected: (request) => { - console.log("setAuthenticatorProperties onRequestRedirected, request:" + JSON.stringify(request)); - } + appAccountManager.getAllOAuthTokens("LiSi", "com.example.ohos.accountjsdemo").then((data) => { + console.log('getAllOAuthTokens data: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("getAllOAuthTokens err: " + JSON.stringify(err)); + }); + ``` + +### getOAuthList(deprecated) + +getOAuthList(name: string, authType: string, callback: AsyncCallback<Array<string>>): void + +获取指定应用帐户和鉴权类型的OAuth令牌的授权列表。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAuthList](#getauthlist9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 应用帐号的鉴权类型的OAuth令牌的授权列表。 | +| callback | AsyncCallback<Array<string>> | 是 | 回调函数。当获取指定应用帐户和鉴权类型的OAuth令牌的授权列表成功时，err为undefined，data为OAuth令牌的授权列表；否则为错误对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.getOAuthList("com.example.ohos.accountjsdemo", "getSocialData", (err, data) => { + console.log('getOAuthList err: ' + JSON.stringify(err)); + console.log('getOAuthList data: ' + JSON.stringify(data)); + }); + ``` + +### getOAuthList(deprecated) + +getOAuthList(name: string, authType: string): Promise<Array<string>> + +获取指定应用帐户和鉴权类型的OAuth令牌的授权列表。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAuthList](#getauthlist9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------- | +| name | string | 是 | 应用帐号的名称。 | +| authType | string | 是 | 应用帐号的鉴权类型的OAuth令牌的授权列表。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------- | --------------------- | +| Promise<Array<string>> | Promise对象。返回指定应用帐户和鉴权类型的OAuth令牌的授权列表对象。 | + +**示例：** + + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.getOAuthList("com.example.ohos.accountjsdemo", "getSocialData").then((data) => { + console.log('getOAuthList data: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("getOAuthList err: " + JSON.stringify(err)); + }); + ``` + +### getAuthenticatorCallback(deprecated) + +getAuthenticatorCallback(sessionId: string, callback: AsyncCallback<AuthenticatorCallback>): void + +获取鉴权会话的认证器回调。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAuthCallback](#getauthcallback9)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| sessionId | string | 是 | 鉴权会话的标识。 | +| callback | AsyncCallback<[AuthenticatorCallback](#authenticatorcallbackdeprecated)> | 是 | 回调函数。当获取鉴权会话的认证器回调函数成功时，err为undefined，data为认证器回调函数；否则为错误对象。 | + +**示例：** + + ```js + import featureAbility from '@ohos.ability.featureAbility'; + const appAccountManager = account_appAccount.createAppAccountManager(); + featureAbility.getWant((err, want) => { + var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; + appAccountManager.getAuthenticatorCallback(sessionId, (err, callback) => { + if (err.code != account_appAccount.ResultCode.SUCCESS) { + console.log("getAuthenticatorCallback err: " + JSON.stringify(err)); + return; + } + var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", + [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", + [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", + [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; + callback.onResult(account_appAccount.ResultCode.SUCCESS, result); + }); + }); + ``` + +### getAuthenticatorCallback(deprecated) + +getAuthenticatorCallback(sessionId: string): Promise<AuthenticatorCallback> + +获取鉴权会话的认证器回调。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[getAuthCallback](#getauthcallback9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | -------- | +| sessionId | string | 是 | 鉴权会话的标识。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------ | --------------------- | +| Promise<[AuthenticatorCallback](#authenticatorcallbackdeprecated)> | Promise对象。返回鉴权会话的认证器回调对象。 | + +**示例：** + + ```js + import featureAbility from '@ohos.ability.featureAbility'; + + const appAccountManager = account_appAccount.createAppAccountManager(); + featureAbility.getWant().then((want) => { + var sessionId = want.parameters[account_appAccount.Constants.KEY_SESSION_ID]; + appAccountManager.getAuthenticatorCallback(sessionId).then((callback) => { + var result = {[account_appAccount.Constants.KEY_NAME]: "LiSi", + [account_appAccount.Constants.KEY_OWNER]: "com.example.ohos.accountjsdemo", + [account_appAccount.Constants.KEY_AUTH_TYPE]: "getSocialData", + [account_appAccount.Constants.KEY_TOKEN]: "xxxxxx"}; + callback.onResult(account_appAccount.ResultCode.SUCCESS, result); + }).catch((err) => { + console.log("getAuthenticatorCallback err: " + JSON.stringify(err)); }); - } catch (err) { - console.log("setAuthenticatorProperties err: " + JSON.stringify(err)); - } + }).catch((err) => { + console.log("getWant err: " + JSON.stringify(err)); + }); ``` -### setAuthenticatorProperties9+ +### getAuthenticatorInfo(deprecated) -setAuthenticatorProperties(owner: string, options: SetPropertiesOptions, callback: AuthCallback): void; +getAuthenticatorInfo(owner: string, callback: AsyncCallback<AuthenticatorInfo>): void + +获取指定应用帐号的认证器信息。使用callback异步回调。 -设置认证器属性，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃, 建议使用[queryAuthenticatorInfo](#queryauthenticatorinfo9)替代。 +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.AppAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ----- | ----------------------- | -| owner | string | 是 | 认证器的所有者。 | -| options | [SetPropertiesOptions](#setpropertiesoptions9) | 是 | 设置属性的选项。 | -| callback | [AuthCallback](#authcallback9) | 是 | 认证器回调，返回设置结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ----------- | +| owner | string | 是 | 应用帐号的所有者包名。 | +| callback | AsyncCallback<[AuthenticatorInfo](#authenticatorinfo8)> | 是 | 回调函数。当获取指定应用帐号的认证器信息成功时，err为undefined，data为认证器信息对象；否则为错误对象。 | **示例：** ```js const appAccountManager = account_appAccount.createAppAccountManager(); - var options = { - properties: {"prop1": "value1"} - }; - try { - appAccountManager.setAuthenticatorProperties("com.example.ohos.accountjsdemo", options, { - onResult: (resultCode, result) => { - console.log("setAuthenticatorProperties onResult, resultCode:" + JSON.stringify(resultCode)); - console.log("setAuthenticatorProperties onResult, result:" + JSON.stringify(result)); - }, - onRequestRedirected: (request) => { - console.log("setAuthenticatorProperties onRequestRedirected, request:" + JSON.stringify(request)); - } - }); - } catch (err) { - console.log("setAuthenticatorProperties err: " + JSON.stringify(err)); - } + appAccountManager.getAuthenticatorInfo("com.example.ohos.accountjsdemo", (err, data) => { + console.log("getAuthenticatorInfo err: " + JSON.stringify(err)); + console.log('getAuthenticatorInfo data: ' + JSON.stringify(data)); + }); + ``` + +### getAuthenticatorInfo(deprecated) + +getAuthenticatorInfo(owner: string): Promise<AuthenticatorInfo> + +获取指定应用帐户的认证器信息。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[queryAuthenticatorInfo](#queryauthenticatorinfo9-1)替代。 +> +> 从 API version 8开始支持。 + +**系统能力：** SystemCapability.Account.AppAccount + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------- | +| owner | string | 是 | 应用帐号的所有者包名。 | + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | --------------------- | +| Promise<[AuthenticatorInfo](#authenticatorinfo8)> | Promise对象。返回指定应用帐户的认证器信息对象。 | + +**示例：** + ```js + const appAccountManager = account_appAccount.createAppAccountManager(); + appAccountManager.getAuthenticatorInfo("com.example.ohos.accountjsdemo").then((data) => { + console.log('getAuthenticatorInfo: ' + JSON.stringify(data)); + }).catch((err) => { + console.log("getAuthenticatorInfo err: " + JSON.stringify(err)); + }); ``` ## AppAccountInfo diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md b/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md index f9a869d66f263dc29bb2e10cbf488785f5375f66..ea67b7e858460f02207609e1b16c42d33475b878 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md @@ -2,7 +2,7 @@ **AccessibilityExtensionAbility**基于ExtensionAbility框架，提供辅助功能业务的能力。 ->**说明：** +>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > >本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 > @@ -32,36 +32,10 @@ import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtens | 名称 | 参数类型 | 可读 | 可写 | 说明 | | --------- | ---------------------------------------- | ---- | ---- | ---------- | -| eventType | [EventType](js-apis-accessibility.md#EventType) \| [WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](touchguidetype) \| [GestureType](gesturetype) \| [PageUpdateType](pageupdatetype) | 是 | 否 | 具体事件类型。 | +| eventType | [EventType](js-apis-accessibility.md#EventType) \| [WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](#touchguidetype) \| [GestureType](#gesturetype) \| [PageUpdateType](#pageupdatetype) | 是 | 否 | 具体事件类型。 | | target | AccessibilityElement | 是 | 否 | 发生事件的目标组件。 | | timeStamp | number | 是 | 否 | 事件时间戳。 | -## GesturePath - -表示手势路径信息。 - -**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core - -### 属性 - -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| ------------ | ---------------------------------------- | ---- | ---- | ------ | -| points | Array<[GesturePoint](gesturepoint)> | 是 | 是 | 手势。 | -| durationTime | number | 是 | 是 | 手势总耗时。 | - -## GesturePoint - -表示手势触摸点。 - -**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core - -### 属性 - -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| --------- | ------ | ---- | ---- | ------- | -| positionX | number | 是 | 是 | 触摸点X坐标。 | -| positionY | number | 是 | 是 | 触摸点Y坐标。 | - ## GestureType 手势事件类型。 @@ -117,16 +91,12 @@ onConnect(): void; **系统能力：** SystemCapability.BarrierFree.Accessibility.Core -**参数：** - -无 - **示例：** ```ts onConnect(): void { console.log("AxExtensionAbility onConnect"); -} +}; ``` ## AccessibilityExtensionAbility.onDisconnect @@ -137,16 +107,12 @@ onDisconnect(): void; **系统能力：** SystemCapability.BarrierFree.Accessibility.Core -**参数：** - -无 - **示例：** ```ts onDisconnect(): void { console.log("AxExtensionAbility onDisconnect"); -} +}; ``` ## AccessibilityExtensionAbility.onAccessibilityEvent @@ -171,7 +137,7 @@ onAccessibilityEvent(event: AccessibilityEvent): void { if (event.eventType == 'click') { console.log("AxExtensionAbility onAccessibilityEvent: click"); } -} +}; ``` ## AccessibilityExtensionAbility.onKeyEvent @@ -198,5 +164,5 @@ onKeyEvent(keyEvent: inputEventClient.KeyEvent): boolean { return true; } return false; -} +}; ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md index eacc955069bb833d0aca75099f828ccc1842cd63..59ee4c1d6948e357bc8b75df713466d53e089742 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -8,7 +8,7 @@ 应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。 -对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。 +对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如需要在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。 > **说明：** > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -27,7 +27,7 @@ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspen 后台应用申请延迟挂起。 -延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 +延迟挂起时间一般情况下默认值为180000毫秒，低电量（依据系统低电量广播）时默认值为60000毫秒。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask @@ -49,9 +49,9 @@ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspen let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { console.info("Request suspension delay will time out."); }) - - var id = delayInfo.requestId; - var time = delayInfo.actualDelayTime; + + let id = delayInfo.requestId; + let time = delayInfo.actualDelayTime; console.info("The requestId is: " + id); console.info("The actualDelayTime is: " + time); ``` @@ -68,14 +68,14 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): **参数**： | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------------- | ---- | ---------------------------------------- | -| requestId | number | 是 | 延迟挂起的请求ID。 | +| requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | **示例**： ```js - let id = 1; - backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { + let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); + backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId, (err, res) => { if(err) { console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code); } else { @@ -96,7 +96,7 @@ getRemainingDelayTime(requestId: number): Promise<number> **参数**： | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------- | -| requestId | number | 是 | 延迟挂起的请求ID。 | +| requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | **返回值**： | 类型 | 说明 | @@ -105,8 +105,8 @@ getRemainingDelayTime(requestId: number): Promise<number> **示例**： ```js - let id = 1; - backgroundTaskManager.getRemainingDelayTime(id).then( res => { + let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); + backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId).then( res => { console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); }).catch( err => { console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); @@ -125,12 +125,12 @@ cancelSuspendDelay(requestId: number): void **参数**： | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------- | -| requestId | number | 是 | 延迟挂起的请求ID。 | +| requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | **示例**： ```js - let id = 1; - backgroundTaskManager.cancelSuspendDelay(id); + let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); + backgroundTaskManager.cancelSuspendDelay(delayInfo.requestId); ``` @@ -153,6 +153,9 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | **示例**： + +FA模型示例： + ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -180,11 +183,48 @@ let wantAgentInfo = { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback) + backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback) }); ``` +Stage模型示例： + +```ts +import Ability from '@ohos.application.Ability' +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import wantAgent from '@ohos.wantAgent'; + +function callback(err, data) { + if (err) { + console.error("Operation startBackgroundRunning failed Cause: " + err); + } else { + console.info("Operation startBackgroundRunning succeeded"); + } +} + +export default class MainAbility extends Ability { + onCreate(want, launchParam) { + let wantAgentInfo = { + wants: [ + { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility" + } + ], + operationType: wantAgent.OperationType.START_ABILITY, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] + }; + + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + backgroundTaskManager.startBackgroundRunning(this.context, + backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback) + }); + } +}; +``` + ## backgroundTaskManager.startBackgroundRunning8+ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> @@ -209,6 +249,9 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want | Promise\ | 使用Promise形式返回结果。 | **示例**： + +FA模型示例： + ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -228,13 +271,45 @@ let wantAgentInfo = { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { + backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => { console.info("Operation startBackgroundRunning succeeded"); }).catch((err) => { console.error("Operation startBackgroundRunning failed Cause: " + err); }); }); +``` + +Stage模型示例： + +```ts +import Ability from '@ohos.application.Ability' +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import wantAgent from '@ohos.wantAgent'; +export default class MainAbility extends Ability { + onCreate(want, launchParam) { + let wantAgentInfo = { + wants: [ + { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility" + } + ], + operationType: wantAgent.OperationType.START_ABILITY, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] + }; + + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + backgroundTaskManager.startBackgroundRunning(this.context, + backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => { + console.info("Operation startBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation startBackgroundRunning failed Cause: " + err); + }); + }); + } +}; ``` ## backgroundTaskManager.stopBackgroundRunning8+ @@ -252,6 +327,9 @@ stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): vo | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | **示例**： + +FA模型示例： + ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -268,6 +346,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac ``` +Stage模型示例： + +```ts +import Ability from '@ohos.application.Ability' +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +function callback(err, data) { + if (err) { + console.error("Operation stopBackgroundRunning failed Cause: " + err); + } else { + console.info("Operation stopBackgroundRunning succeeded"); + } +} + +export default class MainAbility extends Ability { + onCreate(want, launchParam) { + backgroundTaskManager.stopBackgroundRunning(this.context, callback); + } +}; +``` + ## backgroundTaskManager.stopBackgroundRunning8+ stopBackgroundRunning(context: Context): Promise<void> @@ -287,6 +386,9 @@ stopBackgroundRunning(context: Context): Promise<void> | Promise\ | 使用Promise形式返回结果。 | **示例**： + +FA模型示例： + ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -299,11 +401,30 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() ``` +Stage模型示例： + +```ts +import Ability from '@ohos.application.Ability' +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +export default class MainAbility extends Ability { + onCreate(want, launchParam) { + backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { + console.info("Operation stopBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation stopBackgroundRunning failed Cause: " + err); + }); + } +}; +``` + ## backgroundTaskManager.applyEfficiencyResources9+ applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): boolean -向系统申请能效资源，使用boolean形式返回结果。 +向系统申请或释放能效资源，使用boolean形式返回结果。 +通过EfficiencyResourcesRequest参数中的isApply变量，设置是申请还是释放。 +应用使用此接口，需要向应用中心申请获得相应特权。 进程和它所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。 **系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply @@ -328,6 +449,7 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; let request = { resourceTypes: backgroundTaskManager.ResourceType.CPU, + // 如果将isApply置为false，则表示释放资源 isApply: true, timeOut: 0, reason: "apply", @@ -343,6 +465,7 @@ console.info("result of applyEfficiencyResources is: " + res) resetAllEfficiencyResources(): void 释放所有已经申请的资源。 +应用使用此接口，需要向应用中心申请获得相应特权。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply @@ -353,7 +476,7 @@ resetAllEfficiencyResources(): void ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; -backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +backgroundTaskManager.resetAllEfficiencyResources(); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md b/zh-cn/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md index 3072cd0b3855380720e646a73c9cfb0aeb9e38fc..e5460e4565189b78098c79ff7eaaf4820ecdd65d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md @@ -1,6 +1,6 @@ -# ShortcutInfo - +# ShortcutInfo(deprecated) +> 从API version 9开始不再维护，建议使用[ShortcutInfo](js-apis-bundleManager-shortcutInfo.md)替代 > **说明：** > @@ -12,9 +12,9 @@ -## ShortcutWant +## ShortcutWant(deprecated) -快捷方式所指向的目标信息。 +> 从API version 9开始不再维护，建议使用[ShortcutWant](js-apis-bundleManager-shortcutInfo.md)替代 **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework @@ -26,9 +26,10 @@ | targetModule9+ | string | 是 | 否 | 快捷方式的目标模块 | | targetClass | string | 是 | 否 | 快捷方式所需的目标类 | -## ShortcutInfo +## ShortcutInfo(deprecated) + +> 从API version 9开始不再维护，建议使用[ShortcutInfo](js-apis-bundleManager-shortcutInfo.md)替代。 -快捷方式属性信息。 **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework diff --git a/zh-cn/application-dev/reference/apis/js-apis-bundleManager-shortcutInfo.md b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-shortcutInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..64632e0107e5766cac4eab9ca44e0b8344c0365f --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-shortcutInfo.md @@ -0,0 +1,38 @@ +# ShortcutInfo + +应用配置文件中定义的快捷方式信息，FA模型配置在[config.json](../../quick-start/package-structure.md)文件中进行配置，Stage模型配置参考[shortcuts对象内部结构](../../quick-start/stage-structure.md#shortcuts对象内部结构) + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +本模块接口为系统接口。 + +## ShortcutWant + +**系统能力:** SystemCapability.BundleManager.BundleFramework.Launcher + +**系统接口：** 此接口为系统接口。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------------- | ------ | ---- | ---- | -------------------- | +| targetBundle | string | 是 | 否 | 快捷方式的目标bundleName | +| targetModule | string | 是 | 否 | 快捷方式的目标moduleName | +| targetAbility | string | 是 | 否 | 快捷方式所需的目标abilityName | + +## ShortcutInfo + +**系统能力:** SystemCapability.BundleManager.BundleFramework.Launcher + + **系统接口：** 此接口为系统接口。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ----------------------- | ------------------------------------------ | ---- | ---- | ---------------------------- | +| id | string | 是 | 否 | 快捷方式所属应用程序的Id | +| bundleName | string | 是 | 否 | 包含快捷方式的包名称 | +| moduleName | string | 是 | 否 | 快捷方式的模块名 | +| hostAbility | string | 是 | 否 | 快捷方式的本地Ability名称 | +| icon | string | 是 | 否 | 快捷方式的图标 | +| iconId | number | 是 | 否 | 快捷方式的图标Id | +| label | string | 是 | 否 | 快捷方式的标签 | +| labelId | number | 是 | 否 | 快捷方式的标签Id | +| wants | Array\<[ShortcutWant](#shortcutwant)> | 是 | 否 | 快捷方式所需要的信息 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-device-manager.md b/zh-cn/application-dev/reference/apis/js-apis-device-manager.md index a6f6fa765108af8a4db7b5b195fbe0bd9f678654..3b7ed92b83cddfb82a351e6482904a35e61d5f74 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-device-manager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-device-manager.md @@ -35,13 +35,24 @@ createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 参数名 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ------------------------------------ | | bundleName | string | 是 | 指示应用程序的包名。 | | callback | AsyncCallback<[DeviceManager](#devicemanager)> | 是 | DeviceManager实例创建时调用的回调，返回设备管理器对象实例。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | +| 11600102 | Failed to obtain the service. | + +**示例：** + ```js try { deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => { @@ -209,7 +220,6 @@ createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager 设备管理实例，用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前，需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。 - ### release release(): void @@ -218,7 +228,16 @@ release(): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js try { dmInstance.release(); @@ -227,7 +246,6 @@ release(): void } ``` - ### getTrustedDeviceListSync getTrustedDeviceListSync(): Array<DeviceInfo> @@ -236,12 +254,22 @@ getTrustedDeviceListSync(): Array<DeviceInfo> **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 返回值： +**返回值：** + | 名称 | 说明 | | -------------------------------------- | --------- | | Array<[DeviceInfo](#deviceinfo)> | 返回可信设备列表。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js try { var deviceInfoList = dmInstance.getTrustedDeviceListSync(); @@ -250,7 +278,6 @@ getTrustedDeviceListSync(): Array<DeviceInfo> } ``` - ### getTrustedDeviceList8+ getTrustedDeviceList(callback:AsyncCallback<Array<DeviceInfo>>): void @@ -259,12 +286,22 @@ getTrustedDeviceList(callback:AsyncCallback<Array<DeviceInfo>>): voi **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------- | | callback | AsyncCallback<Array<[DeviceInfo](#deviceinfo)>> | 是 | 获取所有可信设备列表的回调，返回设备信息。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js try { dmInstance.getTrustedDeviceList((err, data) => { @@ -287,22 +324,28 @@ getTrustedDeviceList(): Promise<Array<DeviceInfo>> **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 返回值： +**返回值：** + | 类型 | 说明 | | ---------------------------------------- | --------------------- | | Promise<Array<[DeviceInfo](#deviceinfo)>> | Promise实例，用于获取异步返回结果。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js - try { - dmInstance.getTrustedDeviceList().then((data) => { - console.log('get trusted device info: ' + JSON.stringify(data)); - }).catch((err) => { - console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message); - }); - } catch (err) { + dmInstance.getTrustedDeviceList().then((data) => { + console.log('get trusted device info: ' + JSON.stringify(data)); + }).catch((err) => { console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message); - } + }); ``` ### getLocalDeviceInfoSync8+ @@ -313,12 +356,22 @@ getLocalDeviceInfoSync(): [DeviceInfo](#deviceinfo) **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 返回值： - | 名称 | 说明 | - | -------------------------------------- | --------- | - | Array<[DeviceInfo](#deviceinfo)> | 返回本地设备列表。 | +**返回值：** + + | 名称 | 说明 | + | ------------------------- | ---------------- | + | [DeviceInfo](#deviceinfo) | 返回本地设备列表。 | + +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** -- 示例： ```js try { var deviceInfo = dmInstance.getLocalDeviceInfoSync(); @@ -327,7 +380,6 @@ getLocalDeviceInfoSync(): [DeviceInfo](#deviceinfo) } ``` - ### getLocalDeviceInfo8+ getLocalDeviceInfo(callback:AsyncCallback<DeviceInfo>): void @@ -336,12 +388,22 @@ getLocalDeviceInfo(callback:AsyncCallback<DeviceInfo>): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------- | | callback | AsyncCallback<[DeviceInfo](#deviceinfo)> | 是 | 获取本地设备信息。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js try { dmInstance.getLocalDeviceInfo((err, data) => { @@ -364,22 +426,28 @@ getLocalDeviceInfo(): Promise<DeviceInfo> **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 返回值： +**返回值：** + | 类型 | 说明 | | ---------------------------------------- | --------------------- | | Promise<[DeviceInfo](#deviceinfo)> | Promise实例，用于获取异步返回结果。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| ------- | --------------------------------------------------------------- | +| 11600101| Failed to execute the function. | + +**示例：** + ```js - try { - dmInstance.getLocalDeviceInfo().then((data) => { - console.log('get local device info: ' + JSON.stringify(data)); - }).catch((err) => { - console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message); - }); - } catch (err) { + dmInstance.getLocalDeviceInfo().then((data) => { + console.log('get local device info: ' + JSON.stringify(data)); + }).catch((err) => { console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message); - } + }); ``` ### startDeviceDiscovery8+ @@ -390,12 +458,23 @@ startDeviceDiscovery(subscribeInfo: SubscribeInfo): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： - | 名称 | 参数类型 | 必填 | 说明 | +**参数：** + + | 名称 | 参数类型 | 必填 | 说明 | | ------------- | ------------------------------- | ---- | ----- | - | subscribeInfo | [SubscribeInfo](#subscribeinfo) | 是 | 发现信息。 | + | subscribeInfo | [SubscribeInfo](#subscribeinfo) | 是 | 发现信息。| + +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | +| 11600104 | Discovery invalid. | + +**示例：** -- 示例： ```js // 生成发现标识，随机数确保每次调用发现接口的标识不一致 var subscribeId = Math.floor(Math.random() * 10000 + 1000); @@ -423,13 +502,24 @@ startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： - | 名称 | 参数类型 | 必填 | 说明 | - | ------------- | ------------------------------- | ---- | ----- | +**参数：** + + | 名称 | 参数类型 | 必填 | 说明 | + | ------------- | ------------------------------- | ---- | ----- | | subscribeInfo | [SubscribeInfo](#subscribeinfo) | 是 | 发现信息。 | - | filterOptions | string | 否 | 发现设备过滤信息。| + | filterOptions | string | 否 | 发现设备过滤信息。| + +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | +| 11600104 | Discovery invalid. | + +**示例：** -- 示例： ```js // 生成发现标识，随机数确保每次调用发现接口的标识不一致 var subscribeId = Math.floor(Math.random() * 10000 + 1000); @@ -457,7 +547,7 @@ startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void console.error("startDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message); } ``` - + ### stopDeviceDiscovery stopDeviceDiscovery(subscribeId: number): void @@ -466,12 +556,22 @@ stopDeviceDiscovery(subscribeId: number): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | ----------- | ------ | ---- | ----- | | subscribeId | number | 是 | 发现标识。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js // 入参需要和startDeviceDiscovery接口传入的subscribeId配对使用 try { @@ -489,12 +589,23 @@ publishDeviceDiscovery(publishInfo: PublishInfo): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | ------------- | ------------------------------- | ---- | ----- | | publishInfo | [PublishInfo](#publishinfo) | 是 | 发布设备发现信息。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | +| 11600105 | Publish invalid. | + +**示例：** + ```js // 生成发布标识，随机数确保每次调用发布接口的标识不一致 var publishId = Math.floor(Math.random() * 10000 + 1000); @@ -519,12 +630,22 @@ unPublishDeviceDiscovery(publishId: number): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | ----------- | -------- | ---- | ----- | | publishId | number | 是 | 发布标识。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js // 入参需要和publishDeviceDiscovery接口传入的publishId配对使用 try { @@ -542,14 +663,25 @@ authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: Async **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ------- | | deviceInfo | [DeviceInfo](#deviceinfo) | 是 | 设备信息。 | | authParam | [AuthParam](#authparam) | 是 | 认证参数。 | | callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | 是 | 认证结果回调。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | +| 11600103 | Authentication invalid. | + +**示例：** + ```js // 认证的设备信息，可以从发现的结果中获取 var deviceInfo ={ @@ -567,8 +699,8 @@ authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: Async console.error("authenticateDevice errCode:" + err.code + ",errMessage:" + err.message); return; } - console.info(TAG + "authenticateDevice result:" + JSON.stringify(data)); - token = data.pinToken; + console.info("authenticateDevice result:" + JSON.stringify(data)); + let token = data.pinToken; }); } catch (err) { console.error("authenticateDevice errCode:" + err.code + ",errMessage:" + err.message); @@ -583,12 +715,22 @@ unAuthenticateDevice(deviceInfo: DeviceInfo): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | ---------- | ------------------------- | ---- | ----- | | deviceInfo | [DeviceInfo](#deviceinfo) | 是 | 设备信息。 | -- 示例： +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** + ```js try { dmInstance.unAuthenticateDevice(deviceInfo); @@ -597,7 +739,6 @@ unAuthenticateDevice(deviceInfo: DeviceInfo): void } ``` - ### verifyAuthInfo verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void @@ -606,13 +747,23 @@ verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, le **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ------- | | authInfo | [AuthInfo](#authinfo) | 是 | 认证信息。 | - | authInfo | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 | + | callback | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 | + +**错误码：** + +以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md) + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------------- | +| 11600101 | Failed to execute the function. | + +**示例：** -- 示例： ```js let authInfo = { "authType": 1, @@ -625,13 +776,104 @@ verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, le console.error("verifyAuthInfo errCode:" + err.code + ",errMessage:" + err.message); return; } - console.info(TAG + "verifyAuthInfo result:" + JSON.stringify(data)); + console.info("verifyAuthInfo result:" + JSON.stringify(data)); }); } catch (err) { console.error("verifyAuthInfo errCode:" + err.code + ",errMessage:" + err.message); } ``` +### setUserOperation9+ + +setUserOperation(operateAction: number, params: string): void; + +设置用户ui操作行为。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +**参数：** + + | 名称 | 参数类型 | 必填 | 说明 | + | ------------- | --------------- | ---- | ------------------- | + | operateAction | number | 是 | 用户操作动作。 | + | params | string | 是 | 表示用户的输入参数。 | + +**示例：** + + ```js + try { + /* + operateAction = 0 - 允许授权 + operateAction = 1 - 取消授权 + operateAction = 2 - 授权框用户操作超时 + operateAction = 3 - 取消pin码框展示 + operateAction = 4 - 取消pin码输入框展示 + operateAction = 5 - pin码输入框确定操作 + */ + let operation = 0; + this.dmInstance.setUserOperation(operation, "extra") + } catch (err) { + console.error("setUserOperation errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + +### on('uiStateChange')9+ + +on(type: 'uiStateChange', callback: Callback<{ param: string}>): void; + +ui状态变更回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +**参数：** + + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | ------------------------------------ | ---- | ------------------------------ | + | type | string | 是 | 注册的设备管理器 ui 状态回调，以便在状态改变时通知应用。 | + | callback | Callback<{ param: string}> | 是 | 指示要注册的设备管理器 ui 状态回调，返回ui状态。 | + +**示例：** + + ```js + try { + dmInstance.on('uiStateChange', (data) => { + console.log("uiStateChange executed, dialog closed" + JSON.stringify(data)) + var tmpStr = JSON.parse(data.param) + this.isShow = tmpStr.verifyFailed + console.log("uiStateChange executed, dialog closed" + this.isShow) + if (!this.isShow) { + this.destruction() + } + }); + } catch (err) { + console.error("uiStateChange errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + +### off('uiStateChange')9+ + +off(type: 'uiStateChange', callback?: Callback<{ param: string}>): void; + +取消ui状态变更回调 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +**参数：** + + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | ------------------------------------- | ---- | ------------------------------ | + | type | string | 是 | 取消注册的设备管理器 ui 状态回调。 | + | callback | Callback<{ param: string}> | 是 | 指示要取消注册的设备管理器 ui 状态，返回UI状态。 | + +**示例：** + + ```js + try { + dmInstance.off('uiStateChange'); + } catch (err) { + console.error("uiStateChange errCode:" + err.code + ",errMessage:" + err.message); + } + ``` ### on('deviceStateChange') @@ -641,13 +883,15 @@ on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ------------------------------ | | type | string | 是 | 注册设备状态回调，固定为deviceStateChange。 | | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | 是 | 指示要注册的设备状态回调，返回设备状态和设备信息。 | -- 示例： +**示例：** + ```js try { dmInstance.on('deviceStateChange', (data) => { @@ -658,7 +902,6 @@ on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange } ``` - ### off('deviceStateChange') off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void @@ -667,13 +910,15 @@ off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChang **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------------- | | type | string | 是 | 根据应用程序的包名取消注册设备状态回调。 | | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo)  }> | 是 | 指示要取消注册的设备状态回调，返回设备状态和设备信息。 | -- 示例： +**示例：** + ```js try { dmInstance.off('deviceStateChange', (data) => { @@ -684,7 +929,6 @@ off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChang } ``` - ### on('deviceFound') on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void @@ -693,13 +937,15 @@ on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: Dev **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | -------------------------- | | type | string | 是 | 注册设备发现回调，以便在发现周边设备时通知应用程序。 | | callback | Callback<{ subscribeId: number, device: DeviceInfo }> | 是 | 注册设备发现的回调方法。 | -- 示例： +**示例：** + ```js try { dmInstance.on('deviceFound', (data) => { @@ -718,13 +964,15 @@ off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: D **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------------- | | type | string | 是 | 取消注册设备发现回调。 | | callback | Callback<{ subscribeId: number, device: [DeviceInfo](#deviceinfo) }> | 是 | 指示要取消注册的设备发现回调，返回设备状态和设备信息。 | -- 示例： +**示例：** + ```js try { dmInstance.off('deviceFound', (data) => { @@ -743,13 +991,15 @@ on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: nu **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ------------------------------ | | type | string | 是 | 注册设备发现失败回调，以便在发现周边设备失败时通知应用程序。 | | callback | Callback<{ subscribeId: number, reason: number }> | 是 | 注册设备发现失败的回调方法。 | -- 示例： +**示例：** + ```js try { dmInstance.on('discoverFail', (data) => { @@ -768,13 +1018,15 @@ off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ----------------- | | type | string | 是 | 取消注册设备发现失败回调。 | | callback | Callback<{ subscribeId: number, reason: number }> | 是 | 指示要取消注册的设备发现失败回调。 | -- 示例： +**示例：** + ```js try { dmInstance.off('discoverFail', (data) => { @@ -793,13 +1045,16 @@ on(type: 'publishSuccess', callback: Callback<{ publishId: number }>): voi **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | -------------------------- | | type | string | 是 | 注册发布设备成功回调，以便将发布成功时通知应用程序。 | | callback | Callback<{ publishId: number }> | 是 | 注册设备发布成功的回调方法。 | -- 示例： + +**示例：** + ```js try { dmInstance.on('publishSuccess', (data) => { @@ -818,13 +1073,15 @@ off(type: 'publishSuccess', callback?: Callback<{ publishId: number }>): v **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------------- | | type | string | 是 | 取消注册设备发布成功回调。 | | callback | Callback<{ publishId: number }> | 是 | 指示要取消注册的设备发布成功回调。 | -- 示例： +**示例：** + ```js try { dmInstance.off('publishSuccess', (data) => { @@ -843,13 +1100,15 @@ on(type: 'publishFail', callback: Callback<{ publishId: number, reason: numbe **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ------------------------------ | | type | string | 是 | 注册设备发布失败回调，以便在发布设备失败时通知应用程序。 | | callback | Callback<{ publishId: number, reason: number }> | 是 | 注册设备发布失败的回调方法。 | -- 示例： +**示例：** + ```js try { dmInstance.on('publishFail', (data) => { @@ -868,13 +1127,15 @@ off(type: 'publishFail', callback?: Callback<{ publishId: number, reason: num **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ----------------- | | type | string | 是 | 取消注册设备发布失败回调。 | | callback | Callback<{ publishId: number, reason: number }> | 是 | 指示要取消注册设备发布失败回调。 | -- 示例： +**示例：** + ```js try { dmInstance.off('publishFail', (data) => { @@ -893,13 +1154,15 @@ on(type: 'serviceDie', callback: () => void): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ----------------------- | ---- | ---------------------------------------- | | type | string | 是 | 注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序。 | | callback | () => void | 是 | 注册serviceDie的回调方法。 | -- 示例： +**示例：** + ```js try { dmInstance.on("serviceDie", () => { @@ -910,7 +1173,6 @@ on(type: 'serviceDie', callback: () => void): void } ``` - ### off('serviceDie') off(type: 'serviceDie', callback?: () => void): void @@ -919,13 +1181,15 @@ off(type: 'serviceDie', callback?: () => void): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager -- 参数： +**参数：** + | 名称 | 参数类型 | 必填 | 说明 | | -------- | ----------------------- | ---- | ---------------------------------------- | | type | string | 是 | 取消注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序。 | | callback | () => void | 否 | 取消注册serviceDie的回调方法。 | -- 示例： +**示例：** + ```js try { dmInstance.off("serviceDie", () => { diff --git a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md index 6b99171e10220d85932ad78e8f3b33bc48c4aa1a..42794c93059d0ecefe69c2ad8438cb44350afaef 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md +++ b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @@ -23,7 +23,7 @@ ## 导入模块 -``` +```js import bundleState from '@ohos.bundleState' ``` @@ -31,7 +31,7 @@ import bundleState from '@ohos.bundleState' isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void -判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，使用Callback形式返回。 +判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，查询其他应用空闲状态，需要申请权限ohos.permission.BUNDLE_ACTIVE_INFO，使用Callback形式返回。 **系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup @@ -44,7 +44,7 @@ isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void **示例**： - ``` + ```js bundleState.isIdleState("com.ohos.camera", (err, res) => { if (err) { console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); @@ -58,7 +58,7 @@ isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void isIdleState(bundleName: string): Promise<boolean> -判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，使用Promise形式返回。 +判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，查询其他应用空闲状态，需要申请权限ohos.permission.BUNDLE_ACTIVE_INFO，使用Promise形式返回。 **系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup @@ -88,7 +88,7 @@ isIdleState(bundleName: string): Promise<boolean> queryAppUsagePriorityGroup(): Promise<number> -查询当前应用的优先级分组。使用Promise形式返回其应用分组。 +查询当前应用的优先级分组。使用Promise形式返回其应用分组，分组信息参考[GroupType](#grouptype)。 **系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup @@ -112,7 +112,7 @@ bundleState.queryAppUsagePriorityGroup().then( res => { queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void -查询当前应用的优先级分组。使用callback形式返回其应用分组。 +查询当前应用的优先级分组。使用callback形式返回其应用分组，分组信息参考[GroupType](#grouptype)。 **系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup @@ -150,8 +150,8 @@ queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<Bun | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | | callback | AsyncCallback<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | 是 | 指定的callback回调方法。返回指定起始和结束时间内应用使用时长统计信息。 | **示例**： @@ -188,8 +188,8 @@ queryBundleStateInfos(begin: number, end: number): Promise<BundleActiveInfoRe | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | **返回值**： @@ -230,14 +230,14 @@ queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: num | 参数名 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ---------------------------------------- | | byInterval | [IntervalType](#intervaltype) | 是 | 查询类型。 | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | | callback | AsyncCallback<Array<[BundleStateInfo](#bundlestateinfo)>> | 是 | 指定的callback回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | **示例**： ```js - bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { + bundleState.queryBundleStateInfoByInterval(bundleState.IntervalType.BY_OPTIMIZED, 0, 20000000000000, (err, res) => { if (err) { console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); } else { @@ -267,8 +267,8 @@ queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: num | 参数名 | 类型 | 必填 | 说明 | | ---------- | ----------------------------- | ---- | ----- | | byInterval | [IntervalType](#intervaltype) | 是 | 查询类型。 | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | **返回值**： @@ -279,7 +279,7 @@ queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: num **示例**： ```js - bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000).then( res => { + bundleState.queryBundleStateInfoByInterval(bundleState.IntervalType.BY_OPTIMIZED, 0, 20000000000000).then( res => { console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.'); for (let i = 0; i < res.length; i++) { console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise number : ' + (i + 1)); @@ -306,8 +306,8 @@ queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback<A | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | | callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询所有应用的事件集合。 | **示例**： @@ -342,8 +342,8 @@ queryBundleActiveStates(begin: number, end: number): Promise<Array<BundleA | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | **返回值**： @@ -377,8 +377,8 @@ queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallba | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | | callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | **示例**： @@ -409,8 +409,8 @@ queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array< | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | **返回值**： @@ -884,8 +884,8 @@ queryBundleActiveEventStates(begin: number, end: number): Promise<Array<Bu | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | **返回值**： @@ -920,8 +920,8 @@ queryBundleActiveEventStates(begin: number, end: number, callback: AsyncCallback | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | | callback | AsyncCallback<Array<[BundleActiveEventState](#bundleactiveeventstate9)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | **示例**： @@ -953,8 +953,8 @@ queryAppNotificationNumber(begin: number, end: number): Promise<Array<Bund | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | **返回值**： @@ -989,8 +989,8 @@ queryAppNotificationNumber(begin: number, end: number, callback: AsyncCallback&l | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | +| begin | number | 是 | 起始时间，单位毫秒。 | +| end | number | 是 | 结束时间，单位毫秒。 | | callback | AsyncCallback<Array<[BundleActiveEventState](#bundleactiveeventstate9)>> | 是 | 指定的callback回调方法。返回通过指定起始和结束时间查询所有应用的通知次数信息。 | **示例**： diff --git a/zh-cn/application-dev/reference/apis/js-apis-distributed-account.md b/zh-cn/application-dev/reference/apis/js-apis-distributed-account.md index d9e03d2412cc526c7401b0994979428f073ca95d..5d62db3f113c60af609aa15ce4aa6990fb079ab3 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-distributed-account.md +++ b/zh-cn/application-dev/reference/apis/js-apis-distributed-account.md @@ -7,7 +7,7 @@ ## 导入模块 - + ```js import account_distributedAccount from '@ohos.account.distributedAccount'; ``` @@ -40,7 +40,7 @@ getDistributedAccountAbility(): DistributedAccountAbility getOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void -获取分布式帐号信息，使用callback回调异步返回结果。 +获取分布式帐号信息，使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount @@ -50,7 +50,15 @@ getOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): voi | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | 是 | 获取分布式帐号信息的回调。 | + | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | 是 | 回调参数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 201 | permission denied. | + | 401 | the parameter check failed. | + | 12300001 | system service exception. | **示例：** ```js @@ -70,7 +78,7 @@ getOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): voi getOsAccountDistributedInfo(): Promise<DistributedInfo> -获取分布式帐号信息，使用Promise方式异步返回结果。 +获取分布式帐号信息。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount @@ -80,7 +88,15 @@ getOsAccountDistributedInfo(): Promise<DistributedInfo> | 类型 | 说明 | | -------- | -------- | - | Promise<[DistributedInfo](#distributedinfo)> | Promise实例，用于获取异步返回结果。 | + | Promise<[DistributedInfo](#distributedinfo)> | Promise对象。返回分布式帐号信息对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 201 | permission denied. | + | 401 | the parameter check failed. | + | 12300001 | system service exception. | **示例：** ```js @@ -100,7 +116,7 @@ getOsAccountDistributedInfo(): Promise<DistributedInfo> queryOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void -获取分布式帐号信息，使用callback回调异步返回结果。 +获取分布式帐号信息。使用callback异步回调。 > **说明：** 从API version 9开始废弃，建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9) > > 从 API version 7开始支持。 @@ -113,7 +129,7 @@ queryOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): v | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | 是 | 获取分布式帐号信息的回调。 | + | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | 是 | 回调函数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 | **示例：** ```js @@ -129,7 +145,7 @@ queryOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): v queryOsAccountDistributedInfo(): Promise<DistributedInfo> -获取分布式帐号信息，使用Promise方式异步返回结果。 +获取分布式帐号信息。使用Promise异步回调。 > **说明：** 从API version 9开始废弃，建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9-1) > > 从 API version 7开始支持。 @@ -142,7 +158,7 @@ queryOsAccountDistributedInfo(): Promise<DistributedInfo> | 类型 | 说明 | | -------- | -------- | - | Promise<[DistributedInfo](#distributedinfo)> | Promise实例，用于获取异步返回结果。 | + | Promise<[DistributedInfo](#distributedinfo)> | Promise对象。返回分布式帐号信息对象。 | **示例：** ```js @@ -159,7 +175,7 @@ queryOsAccountDistributedInfo(): Promise<DistributedInfo> setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void -更新分布式帐号信息，使用callback回调异步返回结果。 +更新分布式帐号信息。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount @@ -170,7 +186,16 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallbac | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 | - | callback | AsyncCallback<void> | 是 | 更新分布式帐号信息的回调。 | + | callback | AsyncCallback<void> | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 201 | permission denied. | + | 401 | the parameter check failed. | + | 12300001 | system service exception. | + | 12300002 | invalid accountInfo. | **示例：** ```js @@ -189,7 +214,7 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallbac setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> -更新分布式帐号信息，使用Promise方式异步返回结果。 +更新分布式帐号信息。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount @@ -205,7 +230,16 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> | 类型 | 说明 | | -------- | -------- | - | Promise<void> | Promise实例，用于获取异步返回结果。 | + | Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + + | 错误码ID | 错误信息| + | ------- | -------| + | 201 | permission denied. | + | 401 | the parameter check failed. | + | 12300001 | system service exception. | + | 12300002 | invalid accountInfo. | **示例：** ```js @@ -225,7 +259,7 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void -更新分布式帐号信息，使用callback回调异步返回结果。 +更新分布式帐号信息。使用callback异步回调。 > **说明：** 从API version 9开始废弃，建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9) > > 从 API version 7开始支持。 @@ -239,7 +273,7 @@ updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCall | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 | - | callback | AsyncCallback<void> | 是 | 更新分布式帐号信息的回调。 | + | callback | AsyncCallback<void> | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 | **示例：** ```js @@ -254,7 +288,7 @@ updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCall updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> -更新分布式帐号信息，使用Promise方式异步返回结果。 +更新分布式帐号信息。使用Promise异步回调。 > **说明：** 从API version 9开始废弃，建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9-1) > > 从 API version 7开始支持。 @@ -272,7 +306,7 @@ updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> | 类型 | 说明 | | -------- | -------- | - | Promise<void> | Promise实例，用于获取异步返回结果。 | + | Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js diff --git a/zh-cn/application-dev/reference/apis/js-apis-distributedMissionManager.md b/zh-cn/application-dev/reference/apis/js-apis-distributedMissionManager.md index 28e346734f8157fcd47ddbd815f089bf52baaa5f..589acab75c3572a816b91095edeac82ed06fb051 100755 --- a/zh-cn/application-dev/reference/apis/js-apis-distributedMissionManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-distributedMissionManager.md @@ -48,7 +48,7 @@ registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback, console.log('NotifyNetDisconnect state ' + JSON.stringify(state)); } var parameter = { - deviceId: remoteDeviceId + deviceId: "" }; var options = { notifyMissionsChanged: NotifyMissionsChanged, @@ -104,7 +104,7 @@ registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback): console.log('NotifyNetDisconnect state ' + JSON.stringify(state)); } var parameter = { - deviceId: remoteDeviceId + deviceId: "" }; var options = { notifyMissionsChanged: NotifyMissionsChanged, @@ -145,7 +145,7 @@ unRegisterMissionListener(parameter: MissionDeviceInfo, callback: AsyncCallback& ```ts var parameter = { - deviceId: remoteDeviceId + deviceId: "" }; try { distributedMissionManager.unRegisterMissionListener(parameter, (error) => { @@ -186,7 +186,7 @@ unRegisterMissionListener(parameter: MissionDeviceInfo): Promise<void> ```ts var parameter = { - deviceId: remoteDeviceId + deviceId: "" }; try { distributedMissionManager.unRegisterMissionListener(parameter) @@ -221,7 +221,7 @@ startSyncRemoteMissions(parameter: MissionParameter, callback: AsyncCallback< ```ts var parameter = { - deviceId: remoteDeviceId, + deviceId: "", fixConflict: false, tag: 0 }; @@ -263,7 +263,7 @@ startSyncRemoteMissions(parameter: MissionParameter): Promise<void> ```ts var parameter = { - deviceId: remoteDeviceId, + deviceId: "", fixConflict: false, tag: 0 }; @@ -300,7 +300,7 @@ stopSyncRemoteMissions(parameter: MissionDeviceInfo, callback: AsyncCallback< ```ts var parameter = { - deviceId: remoteDeviceId + deviceId: "" }; try { distributedMissionManager.stopSyncRemoteMissions(parameter, (error) => { @@ -340,7 +340,7 @@ stopSyncRemoteMissions(parameter: MissionDeviceInfo): Promise<void> ```ts var parameter = { - deviceId: remoteDeviceId + deviceId: "" }; try { distributedMissionManager.stopSyncRemoteMissions(parameter) @@ -376,10 +376,10 @@ continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback, callba ```ts var parameter = { - srcDeviceId: localDeviceId, - dstDeviceId: remoteDeviceId, - missionId: remoteMissionId, - wantParams: {"key": "value"} + srcDeviceId: "", + dstDeviceId: "", + missionId: 1, + wantParam: {"key": "value"} }; function OnContinueDone(resultCode) { console.log('OnContinueDone resultCode: ' + JSON.stringify(resultCode)); @@ -426,10 +426,10 @@ continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback): Promi ```ts var parameter = { - srcDeviceId: localDeviceId, - dstDeviceId: remoteDeviceId, - missionId: remoteMissionId, - wantParams: {"key": "value"} + srcDeviceId: "", + dstDeviceId: "", + missionId: 1, + wantParam: {"key": "value"} }; function OnContinueDone(resultCode) { console.log('OnContinueDone resultCode: ' + JSON.stringify(resultCode)); @@ -501,8 +501,8 @@ continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback): Promi | -------- | ------ | ---- | ---- | ------- | | srcDeviceId | string | 是 | 是 | 表示任务迁移源设备ID。 | | dstDeviceId | string | 是 | 是 | 表示任务迁移目标设备ID。 | -| missionId | string | 是 | 是 | 表示任务ID。 | -| wantParams | {[key: string]: any} | 是 | 是 | 表示扩展参数。 | +| missionId | number | 是 | 是 | 表示任务ID。 | +| wantParam | {[key: string]: any} | 是 | 是 | 表示扩展参数。 | ## ContinueCallback diff --git a/zh-cn/application-dev/reference/apis/js-apis-faultLogger.md b/zh-cn/application-dev/reference/apis/js-apis-faultLogger.md index c08edb1e7bb45081b84d82818a31f528bd97491d..0f302eb0e6eccd14e73db49b92686113e443e290 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-faultLogger.md +++ b/zh-cn/application-dev/reference/apis/js-apis-faultLogger.md @@ -39,10 +39,12 @@ import faultLogger from '@ohos.faultLogger' | summary | string | 故障的概要 | | fullLog | string | 故障日志全文 | -## faultLogger.querySelfFaultLog +## faultLogger.querySelfFaultLog(deprecated) querySelfFaultLog(faultType: FaultType, callback: AsyncCallback<Array<FaultLogInfo>>) : void +> **说明：** 从 API Version 9 开始废弃，建议使用[faultLogger.query](#faultloggerquery9)替代。 + 获取当前进程故障信息，该方法通过回调方式获取故障信息数组，故障信息数组内最多上报10份故障信息。 **系统能力：** SystemCapability.HiviewDFX.Hiview.FaultLogger @@ -79,10 +81,12 @@ function queryFaultLogCallback(error, value) { faultLogger.querySelfFaultLog(faultLogger.FaultType.JS_CRASH, queryFaultLogCallback); ``` -## faultLogger.querySelfFaultLog +## faultLogger.querySelfFaultLog(deprecated) querySelfFaultLog(faultType: FaultType) : Promise<Array<FaultLogInfo>> +> **说明：** 从 API Version 9 开始废弃，建议使用[faultLogger.query](#faultloggerquery9-1)替代。 + 获取当前进程故障信息，该方法通过Promise方式返回故障信息数组，故障信息数组内最多上报10份故障信息。 **系统能力：** SystemCapability.HiviewDFX.Hiview.FaultLogger @@ -106,18 +110,125 @@ async function getLog() { let value = await faultLogger.querySelfFaultLog(faultLogger.FaultType.JS_CRASH); if (value) { console.info("value length is " + value.length); - let len = value.length; - for (let i = 0; i < len; i++) { - console.info("log: " + i); - console.info("Log pid: " + value[i].pid); - console.info("Log uid: " + value[i].uid); - console.info("Log type: " + value[i].type); - console.info("Log timestamp: " + value[i].timestamp); - console.info("Log reason: " + value[i].reason); - console.info("Log module: " + value[i].module); - console.info("Log summary: " + value[i].summary); - console.info("Log text: " + value[i].fullLog); - } + let len = value.length; + for (let i = 0; i < len; i++) { + console.info("log: " + i); + console.info("Log pid: " + value[i].pid); + console.info("Log uid: " + value[i].uid); + console.info("Log type: " + value[i].type); + console.info("Log timestamp: " + value[i].timestamp); + console.info("Log reason: " + value[i].reason); + console.info("Log module: " + value[i].module); + console.info("Log summary: " + value[i].summary); + console.info("Log text: " + value[i].fullLog); + } + } +} +``` + +## faultLogger.query9+ + +query(faultType: FaultType, callback: AsyncCallback<Array<FaultLogInfo>>) : void + +获取当前进程故障信息，该方法通过回调方式获取故障信息数组，故障信息数组内最多上报10份故障信息。 + +**系统能力：** SystemCapability.HiviewDFX.Hiview.FaultLogger + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| faultType | [FaultType](#faulttype) | 是 | 输入要查询的故障类型。 | +| callback | AsyncCallbackArray<Array<[FaultLogInfo](#faultloginfo)>> | 是 | 回调函数，在回调函数中获取故障信息数组。
- value拿到故障信息数组；value为undefined表示获取过程中出现异常，error返回错误提示字符串 + +**错误码：** + +以下错误码的详细介绍参见[ohos.faultLogger错误码](../errorcodes/errorcode-faultlogger.md)。 + +| 错误码ID | 错误信息（此处仅提供错误抛出的关键信息） | +| --- | --- | +| 10600001 | The service is not running or broken | + +**示例：** + +```js +function queryFaultLogCallback(error, value) { + if (error) { + console.info('error is ' + error); + } else { + console.info("value length is " + value.length); + let len = value.length; + for (let i = 0; i < len; i++) { + console.info("log: " + i); + console.info("Log pid: " + value[i].pid); + console.info("Log uid: " + value[i].uid); + console.info("Log type: " + value[i].type); + console.info("Log timestamp: " + value[i].timestamp); + console.info("Log reason: " + value[i].reason); + console.info("Log module: " + value[i].module); + console.info("Log summary: " + value[i].summary); + console.info("Log text: " + value[i].fullLog); + } + } +} +try { + faultLogger.query(faultLogger.FaultType.JS_CRASH, queryFaultLogCallback); +} catch (err) { + console.error(`code: ${err.code}, message: ${err.message}`); +} +``` + +## faultLogger.query9+ + +query(faultType: FaultType) : Promise<Array<FaultLogInfo>> + +获取当前进程故障信息，该方法通过Promise方式返回故障信息数组，故障信息数组内最多上报10份故障信息。 + +**系统能力：** SystemCapability.HiviewDFX.Hiview.FaultLogger + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| faultType | [FaultType](#faulttype) | 是 | 输入要查询的故障类型。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<Array<[FaultLogInfo](#faultloginfo)>> | Promise实例，可以在其then()方法中获取故障信息实例，也可以使用await。
- value拿到故障信息数组；value为undefined表示获取过程中出现异常 | + +**错误码：** + +以下错误码的详细介绍参见[ohos.faultLogger错误码](../errorcodes/errorcode-faultlogger.md)。 + +| 错误码ID | 错误信息（此处仅提供错误抛出的关键信息） | +| --- | --- | +| 10600001 | The service is not running or broken | + +**示例：** + +```js +async function getLog() { + try { + let value = await faultLogger.query(faultLogger.FaultType.JS_CRASH); + if (value) { + console.info("value length is " + value.length); + let len = value.length; + for (let i = 0; i < len; i++) { + console.info("log: " + i); + console.info("Log pid: " + value[i].pid); + console.info("Log uid: " + value[i].uid); + console.info("Log type: " + value[i].type); + console.info("Log timestamp: " + value[i].timestamp); + console.info("Log reason: " + value[i].reason); + console.info("Log module: " + value[i].module); + console.info("Log summary: " + value[i].summary); + console.info("Log text: " + value[i].fullLog); + } + } + } catch (err) { + console.error(`code: ${err.code}, message: ${err.message}`); } } ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md b/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md index 64bcef93dbd8f297263d84e1f00c7278c0b68430..390623519f0c1ce48914d21867c28effcbb67a07 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md @@ -3,7 +3,8 @@ 本模块提供了应用事件打点能力，包括对打点数据的落盘，以及对打点功能的管理配置。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> - 本模块接口从API version 9开始废弃，建议使用新接口[@ohos.hiviewdfx.hiAppEvent](js-apis-hiviewdfx-hiappevent.md)替代。 +> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 @@ -16,13 +17,9 @@ import hiAppEvent from '@ohos.hiAppEvent'; 开发者在使用应用事件打点功能前，需要首先了解应用事件相关的参数规格定义。 -**事件领域** - -事件领域为string类型，字符串非空且长度在32个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头。 - **事件名称** -事件名称为string类型，字符串非空且长度在48个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头。 +事件名称为string类型，字符串非空且长度在48个字符以内，有效的字符是0-9、a-z、下划线，只能以小写字母开头，不能以下划线结尾。 **事件类型** @@ -32,7 +29,7 @@ import hiAppEvent from '@ohos.hiAppEvent'; 事件参数为object类型，key为事件的参数名称，value为事件的参数值，其规格定义如下： -- 参数名为string类型，字符串非空且长度在16个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头或结尾； +- 参数名为string类型，字符串非空且长度在16个字符以内，有效的字符是0-9、a-z、下划线，只能以小写字母开头，不能以下划线结尾； - 参数值支持string、number、boolean、Array类型； - 参数值为string类型时，其长度需在8*1024个字符以内，超出会做截断处理； - 参数值为Array类型时，Array中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理； @@ -46,20 +43,10 @@ import hiAppEvent from '@ohos.hiAppEvent'; - 返回值大于0，表示事件校验存在异常参数，在忽略异常参数后将事件落盘到事件文件； - 返回值小于0，表示事件校验失败，不将事件落盘到事件文件。 -**订阅回调** - -开发者在调用事件订阅方法后，可以在订阅回调函数中对订阅数据进行处理，其入参定义如下： - -- curRow：返回的订阅事件数量； -- curSize：返回的订阅事件数据大小，单位为byte； -- holder：返回的订阅事件数据持有者，可以通过其对订阅事件进行处理。 - -## hiAppEvent.write(deprecated) +## hiAppEvent.write write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void -> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9)替代。 - 应用事件打点方法，将事件写入到当天的事件文件中，使用callback方式作为异步回调。 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent @@ -89,12 +76,10 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str ``` -## hiAppEvent.write(deprecated) +## hiAppEvent.write write(eventName: string, eventType: EventType, keyValues: object): Promise<void> -> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9-1)替代。 - 应用事件打点方法，将事件写入到当天的事件文件中，使用Promise方式作为异步回调。 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent @@ -126,97 +111,6 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str }); ``` -## hiAppEvent.write9+ - -write(info: [AppEventInfo](#appeventinfo9), callback: AsyncCallback<void>): void - -应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用callback方式作为异步回调。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------ | ---- | -------------- | -| info | [AppEventInfo](#appeventinfo9) | 是 | 应用事件对象。 | -| callback | AsyncCallback<void> | 否 | 事件回调函数。 | - -**示例：** - -```js -hiAppEvent.write({ - domain: "test_domain", - name: "test_event", - eventType: hiAppEvent.EventType.FAULT, - params: { - int_data: 100, - str_data: "strValue" - } -}, (err, value) => { - if (err) { - // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入 - console.error(`failed to write event because ${err.code}`); - return; - } - - // 事件写入正常 - console.log(`success to write event: ${value}`); -}); -``` - -## hiAppEvent.write9+ - -write(info: [AppEventInfo](#appeventinfo9)): Promise<void> - -应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用Promise方式作为异步回调。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------------------------ | ---- | -------------- | -| info | [AppEventInfo](#appeventinfo9) | 是 | 应用事件对象。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------------------------------------------------------ | -| Promise<void> | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 | - -**示例：** - -```js -hiAppEvent.write({ - domain: "test_domain", - name: "test_event", - eventType: hiAppEvent.EventType.FAULT, - params: { - int_data: 100, - str_data: "strValue" - } -}).then((value) => { - // 事件写入正常 - console.log(`success to write event: ${value}`); -}).catch((err) => { - // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入 - console.error(`failed to write event because ${err.code}`); -}); -``` - -## AppEventInfo9+ - -此接口提供了应用事件信息的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ---------- | -| domain | string | 是 | 事件领域。 | -| name | string | 是 | 事件名称。 | -| eventType | [EventType](#eventtype) | 是 | 事件类型。 | -| params | object | 是 | 事件参数。 | - ## hiAppEvent.configure configure(config: ConfigOption): boolean @@ -262,225 +156,6 @@ hiAppEvent.configure({ | disable | boolean | 否 | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | | maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | -## hiAppEvent.addWatcher9+ - -addWatcher(watcher: [Watcher](#watcher9)): [AppEventPackageHolder](#appeventpackageholder9) - -添加应用事件订阅者。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------------------- | ---- | ---------------- | -| watcher | [Watcher](#watcher9) | 是 | 应用事件订阅者。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------------------------ | ------------------------------------ | -| [AppEventPackageHolder](#appeventpackageholder9) | 订阅数据持有者，订阅失败时返回null。 | - -**示例：** - -```js -// 1. 如果订阅者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 -hiAppEvent.addWatcher({ - name: "watcher1", - appEventFilters: [ - { - domain: "domain_test1", - eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] - } - ], - triggerCondition: { - row: 10, - size: 1000, - timeOut: 1 - }, - onTrigger: function (curRow, curSize, holder) { - if (holder == null) { - console.error("holder is null"); - return; - } - let eventPkg = null; - while ((eventPkg = holder.takeNext()) != null) { - console.info(`eventPkg.packageId=${eventPkg.packageId}`); - console.info(`eventPkg.row=${eventPkg.row}`); - console.info(`eventPkg.size=${eventPkg.size}`); - for (const eventInfo of eventPkg.data) { - console.info(`eventPkg.data=${eventInfo}`); - } - } - } -}); - -// 2. 如果订阅者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 -let holder = hiAppEvent.addWatcher({ - name: "watcher2", -}); -if (holder != null) { - let eventPkg = null; - while ((eventPkg = holder.takeNext()) != null) { - console.info(`eventPkg.packageId=${eventPkg.packageId}`); - console.info(`eventPkg.row=${eventPkg.row}`); - console.info(`eventPkg.size=${eventPkg.size}`); - for (const eventInfo of eventPkg.data) { - console.info(`eventPkg.data=${eventInfo}`); - } - } -} -``` - -## hiAppEvent.removeWatcher9+ - -removeWatcher(watcher: [Watcher](#watcher9)): void - -移除应用事件订阅者。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------------------- | ---- | ---------------- | -| watcher | [Watcher](#watcher9) | 是 | 应用事件订阅者。 | - -**示例：** - -```js -// 1. 定义一个应用事件订阅者 -let watcher = { - name: "watcher1", -} - -// 2. 开始订阅事件 -hiAppEvent.addWatcher(watcher); - -// 3. 取消订阅事件 -hiAppEvent.removeWatcher(watcher); -``` - -## Watcher9+ - -此接口提供了应用事件订阅者的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- | -| name | string | 是 | 订阅者名称，用于唯一标识订阅者。 | -| triggerCondition | [TriggerCondition](#triggercondition9) | 否 | 订阅回调触发条件。 | -| appEventFilters | [AppEventFilter](#appeventfilter9)[] | 否 | 订阅过滤条件。 | -| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder9)) => void | 否 | 订阅回调函数 。 | - -## TriggerCondition9+ - -此接口提供了订阅者回调触发条件的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| ------- | -------- | ---- | -------------------------------------- | -| row | number | 否 | 满足触发回调的事件总数。 | -| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 | -| timeOut | number | 否 | 满足触发回调的定时时长，单位为30s。 | - -## AppEventFilter9+ - -此接口提供了订阅者过滤应用事件的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| ---------- | ------------------------- | ---- | ------------------------ | -| domain | string | 是 | 需要订阅的事件领域。 | -| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | - -## AppEventPackageHolder9+ - -订阅数据持有者类，用于对订阅事件进行处理。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -### constructor9+ - -constructor(watcherName: string); - -类构造函数，在添加订阅时会被系统自动调用来创建一个订阅数据持有者对象并返回给开发者。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -let holder = hiAppEvent.addWatcher({ - name: "watcher", -}); -``` - -### setSize9+ - -setSize(size: number): void - -设置每次取出的应用事件包的数据大小阈值，单位为byte，默认值为512*1024。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -let holder = hiAppEvent.addWatcher({ - name: "watcher", -}); -holder.setSize(1000); -``` - -### takeNext9+ - -takeNext(): [AppEventPackage](#appeventpackage9) - -根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -let holder = hiAppEvent.addWatcher({ - name: "watcher", -}); -let eventPkg = holder.takeNext(); -``` - -## AppEventPackage9+ - -此接口提供了订阅返回的应用事件包的参数定义。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 说明 | -| --------- | -------- | ------------------------------ | -| packageId | number | 事件包ID，从0开始自动递增。 | -| row | number | 事件包的事件数量。 | -| size | number | 事件包的数据大小，单位为byte。 | -| data | string[] | 事件包的事件信息。 | - -## hiAppEvent.clearData9+ - -clearData(): void - -应用打点数据清理方法，将应用存储在本地的打点数据进行清除。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -hiAppEvent.clearData(); -``` - ## EventType diff --git a/zh-cn/application-dev/reference/apis/js-apis-hichecker.md b/zh-cn/application-dev/reference/apis/js-apis-hichecker.md index 7184fe39bc326ad85a0587dbe5514cecbaf1dbbf..e313f50d33679e7324a72ef46aef7ae53badf860 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hichecker.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hichecker.md @@ -26,11 +26,103 @@ import hichecker from '@ohos.hichecker'; | RULE_THREAD_CHECK_SLOW_PROCESS | bigint | 检测规则，检测是否有耗时函数被调用。 | | RULE_CHECK_ABILITY_CONNECTION_LEAK | bigint | 检测规则，检测是否发生ability泄露。 | +## hichecker.addCheckRule9+ -## hichecker.addRule +addCheckRule(rule: bigint): void + +添加一条或多条规则到系统，系统根据添加的规则进行检测或反馈。 + +**系统能力：** SystemCapability.HiviewDFX.HiChecker + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| rule | bigint | 是 | 需要添加的规则。 | + +**示例：** + +```js +try { + // 添加一条规则 + hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG);} + // 添加多条规则 + hichecker.addCheckRule( + hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); +catch (err) { + console.error(`code: ${err.code}, message: ${err.message}`); +} +``` + +## hichecker.removeCheckRule9+ + +removeCheckRule(rule: bigint): void + +删除一条或多条规则，删除的规则后续将不再生效。 + +**系统能力：** SystemCapability.HiviewDFX.HiChecker + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| rule | bigint | 是 | 需要删除的规则。 | + +**示例：** + +```js +try { + // 删除一条规则 + hichecker.removeCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); + // 删除多条规则 + hichecker.removeCheckRule( + hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); +catch (err) { + console.error(`code: ${err.code}, message: ${err.message}`); +} +``` + +## hichecker.containsCheckRule9+ + +containsCheckRule(rule: bigint): boolean + +当前已添加的规则集中是否包含了某一个特定的规则，如果传入的规则级别为线程级别，则仅在当前线程中进行查询。 + +**系统能力：** SystemCapability.HiviewDFX.HiChecker + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| rule | bigint | 是 | 需要查询的规则。 | + +**返回值：** + +| 类型 | 说明 | +| ------- | ---------------------------------------------------------- | +| boolean | 查询结果，true 表示规则已添加，false 表示规则未添加。 | + +**示例：** + +```js +try { + // 添加一条规则 + hichecker.addCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); + + // 查询是否包含 + hichecker.containsCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); // return true; + hichecker.containsCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // return false; +catch (err) { + console.error(`code: ${err.code}, message: ${err.message}`); +} +``` + +## hichecker.addRule(deprecated) addRule(rule: bigint): void +> **说明：** 从 API Version 9 开始废弃，建议使用[hichecker.addCheckRule](#hicheckeraddcheckrule9)替代。 + 添加一条或多条规则到系统，系统根据添加的规则进行检测或反馈。 **系统能力：** SystemCapability.HiviewDFX.HiChecker @@ -52,10 +144,12 @@ hichecker.addRule( hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); ``` -## hichecker.removeRule +## hichecker.removeRule(deprecated) removeRule(rule: bigint): void +> **说明：** 从 API Version 9 开始废弃，建议使用[hichecker.removeCheckRule](#hicheckerremovecheckrule9)替代。 + 删除一条或多条规则，删除的规则后续将不再生效。 **系统能力：** SystemCapability.HiviewDFX.HiChecker @@ -101,10 +195,12 @@ hichecker.addRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); hichecker.getRule(); // return 1n; ``` -## hichecker.contains +## hichecker.contains(deprecated) contains(rule: bigint): boolean +> **说明：** 从 API Version 9 开始废弃，建议使用[hichecker.containsCheckRule](#hicheckercontainscheckrule9)替代。 + 当前已添加的规则集中是否包含了某一个特定的规则，如果传入的规则级别为线程级别，则仅在当前线程中进行查询。 **系统能力：** SystemCapability.HiviewDFX.HiChecker diff --git a/zh-cn/application-dev/reference/apis/js-apis-hidebug.md b/zh-cn/application-dev/reference/apis/js-apis-hidebug.md index d6bdbe5f37e074f8f5cb1611ae8ea5454de65eb9..2d81b2b7faef6ee269588dcadf9889bf59ce6da2 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hidebug.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hidebug.md @@ -162,10 +162,12 @@ getCpuUsage(): number let cpuUsage = hidebug.getCpuUsage(); ``` -## hidebug.startProfiling +## hidebug.startProfiling(deprecated) startProfiling(filename : string) : void +> **说明：** 从 API Version 9 开始废弃，建议使用[hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9)替代。 + 启动虚拟机Profiling方法跟踪，`startProfiling()`方法的调用需要与`stopProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。 **系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug @@ -188,10 +190,12 @@ hidebug.stopProfiling(); -## hidebug.stopProfiling +## hidebug.stopProfiling(deprecated) stopProfiling() : void +> **说明：** 从 API Version 9 开始废弃，建议使用[hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9)替代。 + 停止虚拟机Profiling方法跟踪，`stopProfiling()`方法的调用需要与`startProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。 **系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug @@ -206,10 +210,12 @@ hidebug.startProfiling("cpuprofiler-20220216"); hidebug.stopProfiling(); ``` -## hidebug.dumpHeapData +## hidebug.dumpHeapData(deprecated) dumpHeapData(filename : string) : void +> **说明：** 从 API Version 9 开始废弃，建议使用[hidebug.dumpJsHeapData](#hidebugdumpjsheapdata9)替代。 + 虚拟机堆导出。 **系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug @@ -228,11 +234,11 @@ hidebug.dumpHeapData("heap-20220216"); ## hidebug.getServiceDump9+ -getServiceDump(serviceid : number) : string +getServiceDump(serviceid : number, fd : number, args : Array) : void 获取系统服务信息。 -此接口为系统接口，三方应用不可用。 +**需要权限**: ohos.permission.DUMP **系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug @@ -241,16 +247,115 @@ getServiceDump(serviceid : number) : string | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | ------------------------------------------------------------ | | serviceid | number | 是 | 基于该用户输入的service id获取系统服务信息。| +| fd | number | 是 | 文件描述符，该接口会往该fd中写入数据。| +| args | Array | 是 | 系统服务的Dump接口所对应的参数列表。| -**返回值：** -| 类型 | 说明 | -| ------ | -------------------------- | -| string | 返回dump的service信息文件的绝对路径。 | +**示例：** + +```js +import fileio from '@ohos.fileio' +import hidebug from '@ohos.hidebug' +import featureAbility from '@ohos.ability.featureAbility' + +let context = featureAbility.getContext(); +context.getFilesDir().then((data) => { + var path = data + "/serviceInfo.txt" + console.info("output path: " + path) + let fd = fileio.openSync(path, 0o102, 0o666) + var serviceId = 10 + var args = new Array("allInfo") + try { + hidebug.getServiceDump(serviceId, fd, args) + } catch (error) { + console.info(error.code) + console.info(error.message) + } + fileio.closeSync(fd); +}) +``` + +## hidebug.startJsCpuProfiling9+ + +startJsCpuProfiling(filename : string) : void + +启动虚拟机Profiling方法跟踪，`startJsCpuProfiling()`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。 + +**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filename | string | 是 | 用户自定义的profiling文件名，根据传入的`filename`，将在应用的`files`目录生成`filename.json`文件。 | + +**示例：** + +```js +import hidebug from '@ohos.hidebug' + +try { + hidebug.startJsCpuProfiling("cpu_profiling"); + ... + hidebug.stopJsCpuProfiling(); +} catch (error) { + console.info(error.code) + console.info(error.message) +} +``` + +## hidebug.stopJsCpuProfiling9+ + +stopJsCpuProfiling() : void + +停止虚拟机Profiling方法跟踪，`startJsCpuProfiling()`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。 + +**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filename | string | 是 | 用户自定义的profiling文件名，根据传入的`filename`，将在应用的`files`目录生成`filename.json`文件。 | + +**示例：** + +```js +import hidebug from '@ohos.hidebug' + +try { + hidebug.startJsCpuProfiling("cpu_profiling"); + ... + hidebug.stopJsCpuProfiling(); +} catch (error) { + console.info(error.code) + console.info(error.message) +} +``` + +## hidebug.dumpJsHeapData9+ + +dumpJsHeapData(filename : string) : void + +虚拟机堆导出。 + +**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filename | string | 是 | 用户自定义的虚拟机堆文件名，根据传入的`filename`，将在应用的`files`目录生成`filename.heapsnapshot`文件。 | **示例：** ```js -let serviceId = 10; -let pathName = hidebug.getServiceDump(serviceId); +import hidebug from '@ohos.hidebug' + +try { + hidebug.dumpJsHeapData("heapData"); +} catch (error) { + console.info(error.code) + console.info(error.message) +} ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-hisysevent.md b/zh-cn/application-dev/reference/apis/js-apis-hisysevent.md index 1895a0eb1687b281cd3f8fe211f26f850f284f9d..94dd6d732addadbf1f5757c5bc5e6c56bd304de8 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hisysevent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hisysevent.md @@ -55,6 +55,21 @@ write(info: SysEventInfo, callback: AsyncCallback<void>): void | info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 | | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。
- 0表示事件校验成功，事件正常异步写入事件文件；
- 正值表示事件打点存在异常，但可以正常写入；
- 负值表示事件打点失败。 | +**错误码：** + +以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------------------------------------------- | +| 11200001 | Invalid event domain. | +| 11200002 | Invalid event name. | +| 11200003 | Abnormal environment. | +| 11200004 | Length of the event is over limit. | +| 11200051 | Invalid event parameter. | +| 11200052 | Size of the event parameter of the string type is over limit. | +| 11200053 | Count of event parameters is over limit. | +| 11200054 | Count of event parameter of the array type is over limit. | + **示例：** ```js @@ -101,6 +116,21 @@ write(info: SysEventInfo): Promise<void> | ------------------- | ------------------------------------------------------------ | | Promise<void> | Promise实例，可以在其then()、catch()方法中分别对系统事件写入成功、写入异常的回调进行处理。 | +**错误码：** + +以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------------------------------- | +| 11200001 | Invalid event domain. | +| 11200002 | Invalid event name. | +| 11200003 | Abnormal environment. | +| 11200004 | Length of the event is over limit. | +| 11200051 | Invalid event parameter. | +| 11200052 | Size of the event parameter of the string type is over limit. | +| 11200053 | Count of event parameters is over limit. | +| 11200054 | Count of event parameter of the array type is over limit. | + **示例：** ```js @@ -171,7 +201,7 @@ try { ## hiSysEvent.addWatcher -addWatcher(watcher: Watcher): number +addWatcher(watcher: Watcher): void 订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。 @@ -185,6 +215,15 @@ addWatcher(watcher: Watcher): number | ------ | ----------------------------- | ---- | ------------------------ | | watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 | +**错误码：** + +以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ----------------------------------- | +| 11200101 | Count of watchers is over limit. | +| 11200102 | Count of watch rules is over limit. | + **示例：** ```js @@ -213,7 +252,7 @@ try { ## hiSysEvent.removeWatcher -removeWatcher(watcher: Watcher): number +removeWatcher(watcher: Watcher): void 取消订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。 @@ -224,9 +263,17 @@ removeWatcher(watcher: Watcher): number **参数：** | 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------- | ---- | ------------------------ | +| ------ | ------------- | ---- | ------------------------- | | watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 | +**错误码：** + +以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------- | +| 11200201 | The watcher does not exist. | + **示例：** ```js @@ -247,7 +294,7 @@ let watcher = { } } try { - let ret = hiSysEvent.addWatcher(watcher) + hiSysEvent.addWatcher(watcher) hiSysEvent.removeWatcher(watcher) } catch (error) { console.error(`error code: ${error.code}, error msg: ${error.message}`); @@ -290,7 +337,7 @@ try { ## hiSysEvent.query -query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): number +query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void 查询系统事件。 @@ -306,6 +353,17 @@ query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): number | rules | [QueryRule](#queryrule)[] | 是 | 查询规则数组，每次查询可配置多个查询规则。 | | querier | [Querier](#querier) | 是 | 查询者对象，包含查询结果及结束的相关回调。 | +**错误码：** + +以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------- | +| 11200301 | Count of query rules is over limit. | +| 11200302 | Invalid query rule. | +| 11200303 | Count of concurrent queriers is over limit. | +| 11200304 | Query frequency is over limit. | + **示例：** ```js diff --git a/zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md b/zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md new file mode 100644 index 0000000000000000000000000000000000000000..ed292c7470817d3eabed6dd4715f6cf07a06bd7b --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md @@ -0,0 +1,473 @@ +# 应用事件打点 + +本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +```js +import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; +``` + +## hiAppEvent.write + +write(info: [AppEventInfo](#appeventinfo), callback: AsyncCallback<void>): void + +应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用callback方式作为异步回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | +| callback | AsyncCallback<void> | 是 | 打点回调函数。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------- | +| 11100001 | Function is disabled. | +| 11101001 | Invalid event domain. | +| 11101002 | Invalid event name. | +| 11101003 | Invalid number of event parameters. | +| 11101004 | Invalid string length of the event parameter. | +| 11101005 | Invalid event parameter name. | +| 11101006 | Invalid array length of the event parameter. | + +**示例：** + +```js +hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" + } +}, (err) => { + if (err) { + console.error(`code: ${err.code}, message: ${err.message}`); + return; + } + console.log(`success to write event`); +}); +``` + +## hiAppEvent.write + +write(info: [AppEventInfo](#appeventinfo)): Promise<void> + +应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用Promise方式作为异步回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | Promise对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------- | +| 11100001 | Function is disabled. | +| 11101001 | Invalid event domain. | +| 11101002 | Invalid event name. | +| 11101003 | Invalid number of event parameters. | +| 11101004 | Invalid string length of the event parameter. | +| 11101005 | Invalid event parameter name. | +| 11101006 | Invalid array length of the event parameter. | + +**示例：** + +```js +hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" + } +}).then(() => { + console.log(`success to write event`); +}).catch((err) => { + console.error(`code: ${err.code}, message: ${err.message}`); +}); +``` + +## AppEventInfo + +此接口提供了应用事件信息的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | ---------- | +| domain | string | 是 | 事件领域。 | +| name | string | 是 | 事件名称。 | +| eventType | [EventType](#eventtype) | 是 | 事件类型。 | +| params | object | 是 | 事件参数。 | + +## hiAppEvent.configure + +configure(config: [ConfigOption](configoption)): void + +应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ------------------------ | +| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | -------------------------------- | +| 11103001 | Invalid max storage quota value. | + +**示例：** + +```js +// 配置打点开关为关闭状态 +hiAppEvent.configure({ + disable: true +}); + +// 配置文件目录存储配额为100M +hiAppEvent.configure({ + maxStorage: '100M' +}); +``` + +## ConfigOption + +此接口提供了对应用事件打点功能的配置选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------- | ---- | ------------------------------------------------------------ | +| disable | boolean | 否 | 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。 | +| maxStorage | string | 否 | 打点数据存放目录的配额大小，默认值为“10M”。
在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。 | + +## hiAppEvent.addWatcher + +addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpackageholder) + +添加应用事件观察者方法，可用于订阅应用事件。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | -------------------- | ---- | ---------------- | +| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------ | ------------------------------------ | +| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者，订阅失败时返回null。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------- | +| 11102001 | Invalid watcher name. | +| 11102002 | Invalid filtering event domain. | +| 11102003 | Invalid row value. | +| 11102004 | Invalid size value. | +| 11102005 | Invalid timeout value. | + +**示例：** + +```js +// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 +hiAppEvent.addWatcher({ + name: "watcher1", + appEventFilters: [ + { + domain: "test_domain", + eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] + } + ], + triggerCondition: { + row: 10, + size: 1000, + timeOut: 1 + }, + onTrigger: function (curRow, curSize, holder) { + if (holder == null) { + console.error("holder is null"); + return; + } + let eventPkg = null; + while ((eventPkg = holder.takeNext()) != null) { + console.info(`eventPkg.packageId=${eventPkg.packageId}`); + console.info(`eventPkg.row=${eventPkg.row}`); + console.info(`eventPkg.size=${eventPkg.size}`); + for (const eventInfo of eventPkg.data) { + console.info(`eventPkg.data=${eventInfo}`); + } + } + } +}); + +// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 +let holder = hiAppEvent.addWatcher({ + name: "watcher2", +}); +if (holder != null) { + let eventPkg = null; + while ((eventPkg = holder.takeNext()) != null) { + console.info(`eventPkg.packageId=${eventPkg.packageId}`); + console.info(`eventPkg.row=${eventPkg.row}`); + console.info(`eventPkg.size=${eventPkg.size}`); + for (const eventInfo of eventPkg.data) { + console.info(`eventPkg.data=${eventInfo}`); + } + } +} +``` + +## hiAppEvent.removeWatcher + +removeWatcher(watcher: [Watcher](#watcher)): void + +移除应用事件观察者方法，可用于取消订阅应用事件。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | -------------------- | ---- | ---------------- | +| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------- | +| 11102001 | Invalid watcher name. | + +**示例：** + +```js +// 1. 定义一个应用事件观察者 +let watcher = { + name: "watcher1", +} + +// 2. 添加一个应用事件观察者来订阅事件 +hiAppEvent.addWatcher(watcher); + +// 3. 移除该应用事件观察者以取消订阅事件 +hiAppEvent.removeWatcher(watcher); +``` + +## Watcher + +此接口提供了应用事件观察者的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| name | string | 是 | 观察者名称，用于唯一标识观察者。 | +| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件，需要与回调函数一同传入才会生效。 | +| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件，在需要对订阅事件进行过滤时传入。 | +| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数，需要与回调触发条件一同传入才会生效，函数入参说明如下：
curRow：在本次回调触发时的订阅事件总数量；
curSize：在本次回调触发时的订阅事件总大小，单位为byte；
holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 | + +## TriggerCondition + +此接口提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| ------- | -------- | ---- | -------------------------------------- | +| row | number | 否 | 满足触发回调的事件总数量。 | +| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 | +| timeOut | number | 否 | 满足触发回调的超时时长，单位为30s。 | + +## AppEventFilter + +此接口提供了过滤应用事件的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | ------------------------ | +| domain | string | 是 | 需要订阅的事件领域。 | +| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | + +## AppEventPackageHolder + +订阅数据持有者类，用于对订阅事件进行处理。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +### constructor + +constructor(watcherName: string) + +类构造函数，在添加应用事件观察者时，会由系统自动调用来创建一个该观察者对应的订阅数据持有者对象，并返回给开发者。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------- | ---- | ------------------------ | +| watcherName | string | 是 | 观察者名称。 | + +**示例：** + +```js +let holder = hiAppEvent.addWatcher({ + name: "watcher", +}); +``` + +### setSize + +setSize(size: number): void + +设置每次取出的应用事件包的数据大小阈值。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------------- | +| size | number | 是 | 数据大小阈值，单位为byte，默认值为512*1024。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 11104001 | Invalid size value. | + +**示例：** + +```js +let holder = hiAppEvent.addWatcher({ + name: "watcher", +}); +holder.setSize(1000); +``` + +### takeNext + +takeNext(): [AppEventPackage](#appeventpackage) + +根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**示例：** + +```js +let holder = hiAppEvent.addWatcher({ + name: "watcher", +}); +let eventPkg = holder.takeNext(); +``` + +## AppEventPackage + +此接口提供了订阅返回的应用事件包的参数定义。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 说明 | +| --------- | -------- | ------------------------------ | +| packageId | number | 事件包ID，从0开始自动递增。 | +| row | number | 事件包的事件数量。 | +| size | number | 事件包的事件大小，单位为byte。 | +| data | string[] | 事件包的事件信息。 | + +## hiAppEvent.clearData + +clearData(): void + +应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**示例：** + +```js +hiAppEvent.clearData(); +``` + + +## EventType + +事件类型枚举。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 默认值 | 说明 | +| --------- | ------ | -------------- | +| FAULT | 1 | 故障类型事件。 | +| STATISTIC | 2 | 统计类型事件。 | +| SECURITY | 3 | 安全类型事件。 | +| BEHAVIOR | 4 | 行为类型事件。 | + + +## Event + +此接口提供了所有预定义事件的事件名称常量。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------------------------- | -------- | ---- | ---- | -------------------- | +| USER_LOGIN | string | 是 | 否 | 用户登录事件。 | +| USER_LOGOUT | string | 是 | 否 | 用户登出事件。 | +| DISTRIBUTED_SERVICE_START | string | 是 | 否 | 分布式服务启动事件。 | + + +## Param + +此接口提供了所有预定义参数的参数名称常量。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------------------------------- | -------- | ---- | ---- | ------------------ | +| USER_ID | string | 是 | 否 | 用户自定义ID。 | +| DISTRIBUTED_SERVICE_NAME | string | 是 | 否 | 分布式服务名称。 | +| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 否 | 分布式服务实例ID。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-huks.md b/zh-cn/application-dev/reference/apis/js-apis-huks.md index 6e5a68a050a6095fbe08600ad2065957bf715343..ee703cf1686bba0bef5f11d287da62e6cc9b02e6 100755 --- a/zh-cn/application-dev/reference/apis/js-apis-huks.md +++ b/zh-cn/application-dev/reference/apis/js-apis-huks.md @@ -12,2299 +12,2467 @@ HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成 ```js import huks from '@ohos.security.huks' ``` -## HuksErrorCode(deprecated) - -表示错误码的枚举。 - -**系统能力**：SystemCapability.Security.Huks - -| 名称 | 值 | 说明 | -| -------------------------- | ----- | ---- | -| HUKS_SUCCESS | 0 |表示成功。| -| HUKS_FAILURE | -1 |表示失败。| -| HUKS_ERROR_BAD_STATE | -2 |表示错误的状态。| -| HUKS_ERROR_INVALID_ARGUMENT | -3 |表示无效的数据。| -| HUKS_ERROR_NOT_SUPPORTED | -4 |表示不支持。| -| HUKS_ERROR_NO_PERMISSION | -5 |表示没有许可。| -| HUKS_ERROR_INSUFFICIENT_DATA | -6 |表示数据不足。| -| HUKS_ERROR_BUFFER_TOO_SMALL | -7 |表示缓冲区太小。| -| HUKS_ERROR_INSUFFICIENT_MEMORY | -8 |表示内存不足。| -| HUKS_ERROR_COMMUNICATION_FAILURE | -9 |表示通讯失败。| -| HUKS_ERROR_STORAGE_FAILURE | -10 |表示存储故障。| -| HUKS_ERROR_HARDWARE_FAILURE | -11 |表示硬件故障。| -| HUKS_ERROR_ALREADY_EXISTS | -12 |表示已经存在。| -| HUKS_ERROR_NOT_EXIST | -13 |表示不存在。| -| HUKS_ERROR_NULL_POINTER | -14 |表示空指针。| -| HUKS_ERROR_FILE_SIZE_FAIL | -15 |表示文件大小失败。| -| HUKS_ERROR_READ_FILE_FAIL | -16 |表示读取文件失败。| -| HUKS_ERROR_INVALID_PUBLIC_KEY | -17 |表示无效的公钥。| -| HUKS_ERROR_INVALID_PRIVATE_KEY | -18 |表示无效的私钥。| -| HUKS_ERROR_INVALID_KEY_INFO | -19 |表示无效的密钥信息。| -| HUKS_ERROR_HASH_NOT_EQUAL | -20 |表示哈希不相等。| -| HUKS_ERROR_MALLOC_FAIL | -21 |表示MALLOC 失败。| -| HUKS_ERROR_WRITE_FILE_FAIL | -22 |表示写文件失败。| -| HUKS_ERROR_REMOVE_FILE_FAIL | -23 |表示删除文件失败。| -| HUKS_ERROR_OPEN_FILE_FAIL | -24 |表示打开文件失败。| -| HUKS_ERROR_CLOSE_FILE_FAIL | -25 |表示关闭文件失败。| -| HUKS_ERROR_MAKE_DIR_FAIL | -26 |表示创建目录失败。| -| HUKS_ERROR_INVALID_KEY_FILE | -27 |表示无效的密钥文件。| -| HUKS_ERROR_IPC_MSG_FAIL | -28 |表示IPC 信息失败。| -| HUKS_ERROR_REQUEST_OVERFLOWS | -29 |表示请求溢出。| -| HUKS_ERROR_PARAM_NOT_EXIST | -30 |表示参数不存在。| -| HUKS_ERROR_CRYPTO_ENGINE_ERROR | -31 |表示CRYPTO ENGINE错误。| -| HUKS_ERROR_COMMUNICATION_TIMEOUT | -32 |表示通讯超时。| -| HUKS_ERROR_IPC_INIT_FAIL | -33 |表示IPC 初始化失败。| -| HUKS_ERROR_IPC_DLOPEN_FAIL | -34 |表示IPC DLOPEN 失败。| -| HUKS_ERROR_EFUSE_READ_FAIL | -35 |表示EFUSE 读取失败。| -| HUKS_ERROR_NEW_ROOT_KEY_MATERIAL_EXIST | -36 |表示存在新的根密钥材料。| -| HUKS_ERROR_UPDATE_ROOT_KEY_MATERIAL_FAIL | -37 |表示更新根密钥材料失败。| -| HUKS_ERROR_VERIFICATION_FAILED | -38 |表示验证证书链失败。| -| HUKS_ERROR_GET_USERIAM_SECINFO_FAILED9+ | -40 |表示获取当前用户安全属性信息失败。| -| HUKS_ERROR_GET_USERIAM_AUTHINFO_FAILED9+ | -41 |表示获取当前用户认证信息失败。| -| HUKS_ERROR_USER_AUTH_TYPE_NOT_SUPPORT9+ | -42 |表示不支持当前用户认证类型的访问控制。| -| HUKS_ERROR_KEY_AUTH_FAILED9+ | -43 |表示安全访问控制认证失败。| -| HUKS_ERROR_DEVICE_NO_CREDENTIAL9+ | -44 |表示设备当前未录入凭据。| -| HUKS_ERROR_CHECK_GET_ALG_FAIL | -100 |表示检查获取 ALG 失败。| -| HUKS_ERROR_CHECK_GET_KEY_SIZE_FAIL | -101 |表示检查获取密钥大小失败。| -| HUKS_ERROR_CHECK_GET_PADDING_FAIL | -102 |表示检查获取填充失败。| -| HUKS_ERROR_CHECK_GET_PURPOSE_FAIL | -103 |表示检查获取目的失败。| -| HUKS_ERROR_CHECK_GET_DIGEST_FAIL | -104 |表示检查获取摘要失败。| -| HUKS_ERROR_CHECK_GET_MODE_FAIL | -105 |表示检查获取模式失败。| -| HUKS_ERROR_CHECK_GET_NONCE_FAIL | -106 |表示检查获取随机数失败。| -| HUKS_ERROR_CHECK_GET_AAD_FAIL | -107 |表示检查获取 AAD 失败。| -| HUKS_ERROR_CHECK_GET_IV_FAIL | -108 |表示检查 GET IV 失败。| -| HUKS_ERROR_CHECK_GET_AE_TAG_FAIL | -109 |表示检查获取 AE 标记失败。| -| HUKS_ERROR_CHECK_GET_SALT_FAIL | -110 |表示检查获取SALT失败。| -| HUKS_ERROR_CHECK_GET_ITERATION_FAIL | -111 |表示检查获取迭代失败。| -| HUKS_ERROR_INVALID_ALGORITHM | -112 |表示无效的算法。| -| HUKS_ERROR_INVALID_KEY_SIZE | -113 |表示无效的密钥大小。| -| HUKS_ERROR_INVALID_PADDING | -114 |表示无效的填充。| -| HUKS_ERROR_INVALID_PURPOSE | -115 |表示无效的目的。| -| HUKS_ERROR_INVALID_MODE | -116 |表示无效模式。| -| HUKS_ERROR_INVALID_DIGEST | -117 |表示无效的摘要。| -| HUKS_ERROR_INVALID_SIGNATURE_SIZE | -118 |表示签名大小无效。| -| HUKS_ERROR_INVALID_IV | -119 |表示无效的 IV。| -| HUKS_ERROR_INVALID_AAD | -120 |表示无效的 AAD。| -| HUKS_ERROR_INVALID_NONCE | -121 |表示无效的随机数。| -| HUKS_ERROR_INVALID_AE_TAG | -122 |表示无效的 AE 标签。| -| HUKS_ERROR_INVALID_SALT | -123 |表示无效SALT。| -| HUKS_ERROR_INVALID_ITERATION | -124 |表示无效的迭代。| -| HUKS_ERROR_INVALID_OPERATION | -125 |表示无效操作。| -| HUKS_ERROR_INVALID_WRAPPED_FORMAT9+ | -126 |表示导入加密密钥时，密钥格式错误。| -| HUKS_ERROR_INVALID_USAGE_OF_KEY9+ | -127 |表示导入加密密钥时，密钥用途错误。| -| HUKS_ERROR_INTERNAL_ERROR | -999 |表示内部错误。| -| HUKS_ERROR_UNKNOWN_ERROR | -1000 |表示未知错误。| -## HuksExceptionErrCode9+ +## HuksParam -表示错误码的枚举以及对应的错误信息， 错误码表示错误类型，错误信息展示错误详情。 +调用接口使用的options中的properties数组中的param。 **系统能力**：SystemCapability.Security.Huks -| 类型 | 名称 | 说明 | 错误码 | -| ------------------------- | ---------------------------------------------- | --------------------------- | -------- | -| 权限 | HUKS_ERR_CODE_PERMISSION_FAIL | 权限错误导致失败。 | 201 | -| 参数 | HUKS_ERR_CODE_ILLEGAL_ARGUMENT | 参数错误导致失败。 | 401 | -| 不支持的API | HUKS_ERR_CODE_NOT_SUPPORTED_API | 不支持的API。 | 801 | -| 不支持的功能/特性 | HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED | 不支持的功能/特性。 | 12000001 | -| 缺少密钥算法参数 | HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT | 缺少密钥算法参数。 | 12000002 | -| 无效密钥算法参数 | HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT | 无效密钥算法参数。 | 12000003 | -| 文件 | HUKS_ERR_CODE_FILE_OPERATION_FAIL | 文件操作失败。 | 12000004 | -| 通信 | HUKS_ERR_CODE_COMMUNICATION_FAIL | 通信失败。 | 12000005 | -| 算法库操作失败 | HUKS_ERR_CODE_CRYPTO_FAIL | 算法库操作失败。 | 12000006 | -| 密钥访问失败-密钥访问失效 | HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED | 密钥访问失败-密钥访问失效。 | 12000007 | -| 密钥访问失败-密钥认证失败 | HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED | 密钥访问失败-密钥认证失败。 | 12000008 | -| 密钥访问失败-密钥访问超时 | HUKS_ERR_CODE_KEY_AUTH_TIME_OUT | 密钥访问失败-密钥访问超时。 | 12000009 | -| 密钥操作会话数已达上限 | HUKS_ERR_CODE_SESSION_LIMIT | 密钥操作会话数已达上限。 | 12000010 | -| 目标对象不存在 | HUKS_ERR_CODE_ITEM_NOT_EXIST | 目标对象不存在。 | 12000011 | -| 外部错误 | HUKS_ERR_CODE_EXTERNAL_ERROR | 外部错误。 | 12000012 | -| 缺失所需凭据 | HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST | 缺失所需凭据。 | 12000013 | -| 内存不足 | HUKS_ERR_CODE_INSUFFICIENT_MEMORY | 内存不足。 | 12000014 | -| 调用其他系统服务失败 | HUKS_ERR_CODE_CALL_SERVICE_FAILED | 调用其他系统服务失败。 | 12000015 | - -错误信息： - -| 类型 | 错误码 | ERROR MESSAGE | 错误信息 | -| ------------------------- | -------- | ------------------------------------------------------------ | ----------------------------------------- | -| 权限 | 201 | Check permission failed. User should request permission first. | 表示没有许可。 | -| 参数 | 401 | Argument is invalid. User should make sure using the correct value. | 表示无效的参数。 | -| 参数 | 401 | Input data is not sufficient. | 表示数据不足。 | -| 参数 | 401 | The buffer is too small. | 表示缓冲区太小。 | -| 参数 | 401 | Parameter is null. User should make sure using the correct value. | 表示空指针。 | -| 参数 | 401 | Public key is invalid. | 表示无效的公钥。 | -| 参数 | 401 | Key info is invalid. | 表示无效的密钥信息。 | -| 参数 | 401 | Queried param does not exist. | 表示参数不存在。 | -| 参数 | 401 | Root key material already exists. | 表示存在新的根密钥材料。 | -| 参数 | 401 | The format of wrapped key data is invalid. | 表示导入加密密钥时，密钥格式错误。 | -| 参数 | 401 | Check get auth type failed. User should add auth type in paramset. | 表示获取身份验证类型失败。 | -| 参数 | 401 | Check get challenge type failed. User should add challenge type in paramset. | 表示获取挑战值类型失败。 | -| 参数 | 401 | Check get access type failed. User should add access type in paramset. | 表示获取访问类型失败。 | -| 参数 | 401 | Check get auth token failed. User should add auth token in paramset. | 表示获取身份验证令牌失败。 | -| 参数 | 401 | Time out param is invalid. User should make sure using the correct value. | 表示超时参数无效 | -| 参数 | 401 | Auth type param is invalid. User should make sure using the correct value. | 表示身份验证类型参数无效。 | -| 参数 | 401 | Challenge type param is invalid. User should make sure using the correct value. | 表示挑战值类型参数无效。 | -| 参数 | 401 | Access type param is invalid. User should make sure using the correct value. | 表示访问类型参数无效。 | -| 参数 | 401 | Auth token param is invalid. User should make sure using the correct value. | 表示身份验证令牌参数无效。 | -| 参数 | 401 | Secure sign type param is invalid. User should make sure using the correct value. | 表示安全符号类型参数无效。 | -| 不支持的API | 801 | This api is not supported in current device. | 不支持的API。 | -| 不支持的功能/特性 | 12000001 | Feature is not support. Please make sure using the correct combination of params. | 功能特性不支持，请输入正确的参数组合。 | -| 不支持的功能/特性 | 12000001 | This user auth type is not supported in current device. | 表示不支持当前用户认证类型的访问控制。 | -| 缺少密钥算法参数 | 12000002 | Check get algorithm failed. User should add algorithm in paramset. | 表示检查获取 ALG 失败。 | -| 缺少密钥算法参数 | 12000002 | Check get key size failed. User should add key size in paramset. | 表示检查获取密钥大小失败。 | -| 缺少密钥算法参数 | 12000002 | Check get padding failed. User should add padding in paramset. | 表示检查获取填充失败。 | -| 缺少密钥算法参数 | 12000002 | Check get purpose failed. User should add purpose in paramset. | 表示检查获取目的失败。 | -| 缺少密钥算法参数 | 12000002 | Check get digest failed. User should add digest in paramset. | 表示检查获取摘要失败。 | -| 缺少密钥算法参数 | 12000002 | Check get mode failed. User should add mode in paramset. | 表示检查获取模式失败。 | -| 缺少密钥算法参数 | 12000002 | Check get nonce failed. User should add nonce in paramset. | 表示检查获取随机数失败。 | -| 缺少密钥算法参数 | 12000002 | Check get aad failed. User should add AAD in paramset. | 表示检查获取 AAD 失败。 | -| 缺少密钥算法参数 | 12000002 | Check get iv failed. User should add iv in paramset. | 表示检查 GET IV 失败。 | -| 缺少密钥算法参数 | 12000002 | Check get aead failed. User should add aead in paramset. | 表示检查获取 AE 标记失败。 | -| 缺少密钥算法参数 | 12000002 | Check get salt failed. User should add salt in paramset. | 表示检查获取SALT失败。 | -| 缺少密钥算法参数 | 12000002 | Check get iteration failed. User should add iteration in paramset. | 表示检查获取迭代失败。 | -| 无效密钥算法参数 | 12000003 | Algorithm param is invalid. User should make sure using the correct value. | 表示无效的算法。 | -| 无效密钥算法参数 | 12000003 | Key size param is invalid. User should make sure using the correct value. | 表示无效的密钥大小。 | -| 无效密钥算法参数 | 12000003 | Padding param is invalid. User should make sure using the correct value. | 表示无效的填充。 | -| 无效密钥算法参数 | 12000003 | Purpose param is invalid. User should make sure using the correct value. | 表示无效的目的。 | -| 无效密钥算法参数 | 12000003 | Mode param is invalid. User should make sure using the correct value. | 表示无效模式。 | -| 无效密钥算法参数 | 12000003 | Digest param is invalid. User should make sure using the correct value. | 表示无效的摘要。 | -| 无效密钥算法参数 | 12000003 | Signture size param is invalid. User should make sure using the correct value. | 表示签名大小无效。 | -| 无效密钥算法参数 | 12000003 | IV param is invalid. User should make sure using the correct value. | 表示无效的 IV。 | -| 无效密钥算法参数 | 12000003 | AAD param is invalid. User should make sure using the correct value. | 表示无效的 AAD。 | -| 无效密钥算法参数 | 12000003 | Nonce param is invalid. User should make sure using the correct value. | 表示无效的随机数。 | -| 无效密钥算法参数 | 12000003 | AE param is invalid. User should make sure using the correct value. | 表示无效的 AE 标签。 | -| 无效密钥算法参数 | 12000003 | Salt param is invalid. User should make sure using the correct value. | 表示无效SALT。 | -| 无效密钥算法参数 | 12000003 | Iteration param is invalid. User should make sure using the correct value. | 表示无效的迭代。 | -| 无效密钥算法参数 | 12000003 | Purpose param is invalid. User should make sure using the correct value. | 表示导入加密密钥时，密钥用途错误。 | -| 文件 | 12000004 | Storage space is insufficient. | 表示存储故障。 | -| 文件 | 12000004 | The value of file size is unexpected. | 表示文件大小失败。 | -| 文件 | 12000004 | Read file failed. | 表示读取文件失败。 | -| 文件 | 12000004 | Write file failed. | 表示写文件失败。 | -| 文件 | 12000004 | Remove file failed. | 表示删除文件失败。 | -| 文件 | 12000004 | Open file failed. | 表示打开文件失败。 | -| 文件 | 12000004 | Close file failed. | 表示关闭文件失败。 | -| 文件 | 12000004 | Make directory failed. | 表示创建目录失败。 | -| 文件 | 12000004 | Read key from file failed, for key fi哦呜le is invalid. | 表示无效的密钥文件。 | -| 通信 | 12000005 | Get message from IPC failed. | 表示IPC 信息失败。 | -| 通信 | 12000005 | IPC communication time out. | 表示通讯超时。 | -| 通信 | 12000005 | IPC init failed. | 表示IPC 初始化失败。 | -| 通信 | 12000005 | IPC async call failed. | IPC异步调用失败。 | -| 算法库操作失败 | 12000006 | Errors occured in crypto engine. | 表示CRYPTO ENGINE错误。 | -| 密钥访问失败-密钥访问失效 | 12000007 | This credential is already invalidated permanently. | 密钥访问失败-密钥访问失效 | -| 密钥访问失败-密钥认证失败 | 12000008 | Verify authtoken failed. | 密钥访问失败-密钥认证失败 | -| 密钥访问失败-密钥访问超时 | 12000009 | This authtoken is already timeout. | 密钥访问失败-密钥访问超时 | -| 密钥操作会话数已达上限 | 12000010 | The number of sessions has reached limit. | 密钥操作会话数已达上限。 | -| 目标对象不存在 | 12000011 | Queried entity does not exist. | 表示不存在。 | -| 外部错误 | 12000012 | General error. | 一般错误。 | -| 外部错误 | 12000012 | System error. | 系统错误。 | -| 外部错误 | 12000012 | System external error. | 表示系统外部错误。 | -| 缺失所需凭据 | 12000013 | Queried credential does not exist. | 查询的凭据不存在。 | -| 内存不足 | 12000014 | Memory is insufficient. | 表示内存不足。 | -| 内存不足 | 12000014 | Malloc failed. | 表示MALLOC 失败。 | -| 调用其他系统服务失败 | 12000015 | Calling useriam to get sec info failed. | 访问useriam获取当前用户安全属性信息失败。 | -| 调用其他系统服务失败 | 12000015 | Calling useriam to get auth info failed. | 访问useriam获取当前用户认证信息失败。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------------- | ---- | ------------ | +| tag | [HuksTag](#hukstag) | 是 | 标签。 | +| value | boolean\|number\|bigint\|Uint8Array | 是 | 标签对应值。 | -## HuksKeyPurpose +## HuksOptions -表示密钥用途。 +调用接口使用的options。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ------------------------ | ---- | -------------------------------- | -| HUKS_KEY_PURPOSE_ENCRYPT | 1 | 表示密钥用于对明文进行加密操作。 | -| HUKS_KEY_PURPOSE_DECRYPT | 2 | 表示密钥用于对密文进行解密操作。 | -| HUKS_KEY_PURPOSE_SIGN | 4 | 表示密钥用于对数据进行签名。 | -| HUKS_KEY_PURPOSE_VERIFY | 8 | 表示密钥用于验证签名后的数据。 | -| HUKS_KEY_PURPOSE_DERIVE | 16 | 表示密钥用于派生密钥。 | -| HUKS_KEY_PURPOSE_WRAP | 32 | 表示密钥用于加密导出。 | -| HUKS_KEY_PURPOSE_UNWRAP | 64 | 表示密钥加密导入。 | -| HUKS_KEY_PURPOSE_MAC | 128 | 表示密钥用于生成mac消息验证码。 | -| HUKS_KEY_PURPOSE_AGREE | 256 | 表示密钥用于进行密钥协商。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ----------------- | ---- | ------------------------ | +| properties | Array\<[HuksParam](#huksparam)> | 否 | 属性，用于存HuksParam的数组。 | +| inData | Uint8Array | 否 | 输入数据。 | -## HuksKeyDigest +## HuksSessionHandle9+ -表示摘要算法。 +huks Handle结构体。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ---------------------- | ---- | ---------------------------------------- | -| HUKS_DIGEST_NONE | 0 | 表示无摘要算法。 | -| HUKS_DIGEST_MD5 | 1 | 表示MD5摘要算法。 | -| HUKS_DIGEST_SM39+ | 2 | 表示SM3摘要算法。 | -| HUKS_DIGEST_SHA1 | 10 | 表示SHA1摘要算法。 | -| HUKS_DIGEST_SHA224 | 11 | 表示SHA224摘要算法。 | -| HUKS_DIGEST_SHA256 | 12 | 表示SHA256摘要算法。 | -| HUKS_DIGEST_SHA384 | 13 | 表示SHA384摘要算法。 | -| HUKS_DIGEST_SHA512 | 14 | 表示SHA512摘要算法。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------- | ---- | ---------------------------------------------------- | +| handle | number | 是 | 表示handle值。 | +| challenge | Uint8Array | 否 | 表示[init](#huksinit)操作之后获取到的challenge信息。 | -## HuksKeyPadding +## HuksReturnResult9+ -表示补齐算法。 +调用接口返回的result。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ---------------------- | ---- | ---------------------------------------- | -| HUKS_PADDING_NONE | 0 | 表示不使用补齐算法。 | -| HUKS_PADDING_OAEP | 1 | 表示使用OAEP补齐算法。 | -| HUKS_PADDING_PSS | 2 | 表示使用PSS补齐算法。 | -| HUKS_PADDING_PKCS1_V1_5 | 3 | 表示使用PKCS1_V1_5补齐算法。 | -| HUKS_PADDING_PKCS5 | 4 | 表示使用PKCS5补齐算法。 | -| HUKS_PADDING_PKCS7 | 5 | 表示使用PKCS7补齐算法。 | -## HuksCipherMode -表示加密模式。 +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | ---------------- | +| outData | Uint8Array | 否 | 表示输出数据。 | +| properties | Array\<[HuksParam](#huksparam)> | 否 | 表示属性信息。 | +| certChains | Array\ | 否 | 表示证书链数据。 | -**系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ------------- | ---- | --------------------- | -| HUKS_MODE_ECB | 1 | 表示使用ECB加密模式。 | -| HUKS_MODE_CBC | 2 | 表示使用CBC加密模式。 | -| HUKS_MODE_CTR | 3 | 表示使用CTR加密模式。 | -| HUKS_MODE_OFB | 4 | 表示使用OFB加密模式。 | -| HUKS_MODE_CCM | 31 | 表示使用CCM加密模式。 | -| HUKS_MODE_GCM | 32 | 表示使用GCM加密模式。 | +## huks.generateKeyItem9+ -## HuksKeySize +generateKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -表示密钥长度。 +生成密钥，使用Callback回调异步返回结果。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ---------------------------------- | ---- | ------------------------------------------ | -| HUKS_RSA_KEY_SIZE_512 | 512 | 表示使用RSA算法的密钥长度为512bit。 | -| HUKS_RSA_KEY_SIZE_768 | 768 | 表示使用RSA算法的密钥长度为768bit。 | -| HUKS_RSA_KEY_SIZE_1024 | 1024 | 表示使用RSA算法的密钥长度为1024bit。 | -| HUKS_RSA_KEY_SIZE_2048 | 2048 | 表示使用RSA算法的密钥长度为2048bit。 | -| HUKS_RSA_KEY_SIZE_3072 | 3072 | 表示使用RSA算法的密钥长度为3072bit。 | -| HUKS_RSA_KEY_SIZE_4096 | 4096 | 表示使用RSA算法的密钥长度为4096bit。 | -| HUKS_ECC_KEY_SIZE_224 | 224 | 表示使用ECC算法的密钥长度为224bit。 | -| HUKS_ECC_KEY_SIZE_256 | 256 | 表示使用ECC算法的密钥长度为256bit。 | -| HUKS_ECC_KEY_SIZE_384 | 384 | 表示使用ECC算法的密钥长度为384bit。 | -| HUKS_ECC_KEY_SIZE_521 | 521 | 表示使用ECC算法的密钥长度为521bit。 | -| HUKS_AES_KEY_SIZE_128 | 128 | 表示使用AES算法的密钥长度为128bit。 | -| HUKS_AES_KEY_SIZE_192 | 196 | 表示使用AES算法的密钥长度为196bit。 | -| HUKS_AES_KEY_SIZE_256 | 256 | 表示使用AES算法的密钥长度为256bit。 | -| HUKS_AES_KEY_SIZE_512 | 512 | 表示使用AES算法的密钥长度为512bit。 | -| HUKS_CURVE25519_KEY_SIZE_256 | 256 | 表示使用CURVE25519算法的密钥长度为256bit。 | -| HUKS_DH_KEY_SIZE_2048 | 2048 | 表示使用DH算法的密钥长度为2048bit。 | -| HUKS_DH_KEY_SIZE_3072 | 3072 | 表示使用DH算法的密钥长度为3072bit。 | -| HUKS_DH_KEY_SIZE_4096 | 4096 | 表示使用DH算法的密钥长度为4096bit。 | -| HUKS_SM2_KEY_SIZE_2569+ | 256 | 表示SM2算法的密钥长度为256bit。 | -| HUKS_SM4_KEY_SIZE_1289+ | 128 | 表示SM4算法的密钥长度为128bit。 | +**参数：** -## HuksKeyAlg +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | +| callback | AsyncCallback\ | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | -表示密钥使用的算法。 +**示例：** -**系统能力**：SystemCapability.Security.Huks +```js +/* 以生成ECC256密钥为例 */ +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 +}; +let options = { + properties: properties +}; +try { + huks.generateKeyItem(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: generateKeyItem key success`); + } + }); +} catch (error) { + console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +} +``` -| 名称 | 值 | 说明 | -| ------------------------- | ---- | --------------------- | -| HUKS_ALG_RSA | 1 | 表示使用RSA算法。 | -| HUKS_ALG_ECC | 2 | 表示使用ECC算法。 | -| HUKS_ALG_DSA | 3 | 表示使用DSA算法。 | -| HUKS_ALG_AES | 20 | 表示使用AES算法。 | -| HUKS_ALG_HMAC | 50 | 表示使用HMAC算法。 | -| HUKS_ALG_HKDF | 51 | 表示使用HKDF算法。 | -| HUKS_ALG_PBKDF2 | 52 | 表示使用PBKDF2算法。 | -| HUKS_ALG_ECDH | 100 | 表示使用ECDH算法。 | -| HUKS_ALG_X25519 | 101 | 表示使用X25519算法。 | -| HUKS_ALG_ED25519 | 102 | 表示使用ED25519算法。 | -| HUKS_ALG_DH | 103 | 表示使用DH算法。 | -| HUKS_ALG_SM29+ | 150 | 表示使用SM2算法。 | -| HUKS_ALG_SM39+ | 151 | 表示使用SM3算法。 | -| HUKS_ALG_SM49+ | 152 | 表示使用SM4算法。 | +## huks.generateKeyItem9+ -## HuksKeyGenerateType +generateKeyItem(keyAlias: string, options: HuksOptions) : Promise\ -表示生成密钥的类型。 +生成密钥，使用Promise方式异步返回结果。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ------------------------------ | ---- | ---------------- | -| HUKS_KEY_GENERATE_TYPE_DEFAULT | 0 | 默认生成的密钥。 | -| HUKS_KEY_GENERATE_TYPE_DERIVE | 1 | 派生生成的密钥。 | -| HUKS_KEY_GENERATE_TYPE_AGREE | 2 | 协商生成的密钥。 | +**参数：** -## HuksKeyFlag +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------ | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | -表示密钥的产生方式。 +**示例：** -**系统能力**：SystemCapability.Security.Huks +```js +/* 以生成ECC256密钥为例 */ +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 +}; +let options = { + properties: properties +}; +try { + huks.generateKeyItem(keyAlias, options) + .then((data) => { + console.info(`promise: generateKeyItem success`); + }) + .catch(error => { + console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); +} catch (error) { + console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +} +``` -| 名称 | 值 | 说明 | -| -------------------------- | ---- | ------------------------------------ | -| HUKS_KEY_FLAG_IMPORT_KEY | 1 | 表示通过导入公钥接口导入的密钥。 | -| HUKS_KEY_FLAG_GENERATE_KEY | 2 | 表示通过生成密钥接口生成的密钥。 | -| HUKS_KEY_FLAG_AGREE_KEY | 3 | 表示通过生成密钥协商接口生成的密钥。 | -| HUKS_KEY_FLAG_DERIVE_KEY | 4 | 表示通过生成密钥派生接口生成的密钥。 | +## huks.deleteKeyItem9+ -## HuksKeyStorageType +deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -表示密钥存储方式。 +删除密钥，使用Callback回调异步返回结果。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ----------------------- | ---- | ------------------------------ | -| HUKS_STORAGE_TEMP | 0 | 表示通过本地直接管理密钥。 | -| HUKS_STORAGE_PERSISTENT | 1 | 表示通过HUKS service管理密钥。 | +**参数：** -## HuksSendType +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\ | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | -表示发送Tag的方式。 +**示例：** -**系统能力**：SystemCapability.Security.Huks +```js +/* 此处options选择emptyOptions传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +try { + huks.deleteKeyItem(keyAlias, emptyOptions, function (error, data) { + if (error) { + console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: deleteKeyItem key success`); + } + }); +} catch (error) { + console.error(`callback: deleteKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +} +``` -| 名称 | 值 | 说明 | -| -------------------- | ---- | ----------------- | -| HUKS_SEND_TYPE_ASYNC | 0 | 表示异步发送TAG。 | -| HUKS_SEND_TYPE_SYNC | 1 | 表示同步发送TAG。 | +## huks.deleteKeyItem9+ -## HuksUnwrapSuite9+ +deleteKeyItem(keyAlias: string, options: HuksOptions) : Promise\ -表示导入加密密钥的算法套件。 +删除密钥，使用Promise方式异步返回结果。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ---------------------------------------------- | ---- | ----------------------------------------------------- | -| HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING | 1 | 导入加密密钥时，X25519密钥协商后使用AES-256 GCM加密。 | -| HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING | 2 | 导入加密密钥时，ECDH密钥协商后使用AES-256 GCM加密。 | +**参数：** -## HuksImportKeyType9+ +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------------------------------- | +| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -表示导入密钥的密钥类型，默认为导入公钥，导入对称密钥时不需要该字段。 +**示例：** -**系统能力**：SystemCapability.Security.Huks +```js +/* 此处options选择emptyOptions传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +try { + huks.deleteKeyItem(keyAlias, emptyOptions) + .then ((data) => { + console.info(`promise: deleteKeyItem key success`); + }) + .catch(error => { + console.error(`promise: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); +} catch (error) { + console.error(`promise: deleteKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +} +``` -| 名称 | 值 | 说明 | -| ------------------------- | ---- | ------------------------------ | -| HUKS_KEY_TYPE_PUBLIC_KEY | 0 | 表示导入的密钥类型为公钥。 | -| HUKS_KEY_TYPE_PRIVATE_KEY | 1 | 表示导入的密钥类型为私钥。 | -| HUKS_KEY_TYPE_KEY_PAIR | 2 | 表示导入的密钥类型为公私钥对。 | +## huks.getSdkVersion -## HuksUserAuthType9+ +getSdkVersion(options: HuksOptions) : string -表示用户认证类型。 +获取当前系统sdk版本。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ------------------------------- | ---- | ------------------------- | -| HUKS_USER_AUTH_TYPE_FINGERPRINT | 1 | 表示用户认证类型为指纹。 | -| HUKS_USER_AUTH_TYPE_FACE | 2 | 表示用户认证类型为人脸 。 | -| HUKS_USER_AUTH_TYPE_PIN | 4 | 表示用户认证类型为PIN码。 | - -## HuksAuthAccessType9+ - -表示安全访问控制类型。 +**参数：** -**系统能力**：SystemCapability.Security.Huks +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ---------- | ---- | ------------------------- | +| options | [HuksOptions](#huksoptions) | 是 | 空对象，用于存放sdk版本。 | -| 名称 | 值 | 说明 | -| --------------------------------------- | ---- | ------------------------------------------------ | -| HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | 1 | 表示安全访问控制类型为清除密码后密钥无效。 | -| HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | 2 | 表示安全访问控制类型为新录入生物特征后密钥无效。 | +**返回值：** -## HuksChallengeType9+ +| 类型 | 说明 | +| ------ | ------------- | +| string | 返回sdk版本。 | -表示密钥使用时生成challenge的类型。 +**示例：** -**系统能力**：SystemCapability.Security.Huks +```js +/* 此处options选择emptyOptions传空 */ +let emptyOptions = { + properties: [] +}; +let result = huks.getSdkVersion(emptyOptions); +``` -| 名称 | 值 | 说明 | -| ------------------------------- | ---- | ------------------------------ | -| HUKS_CHALLENGE_TYPE_NORMAL | 0 | 表示challenge为普通类型，默认32字节。 | -| HUKS_CHALLENGE_TYPE_CUSTOM | 1 | 表示challenge为用户自定义类型。支持使用多个密钥仅一次认证。 | -| HUKS_CHALLENGE_TYPE_NONE | 2 | 表示免challenge类型。 | +## huks.importKeyItem9+ -## HuksChallengePosition9+ +importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -表示challenge类型为用户自定义类型时，生成的challenge有效长度仅为8字节连续的数据，且仅支持4种位置 。 +导入明文密钥，使用Callback方式回调异步返回结果 。 **系统能力**：SystemCapability.Security.Huks -| 名称 | 值 | 说明 | -| ------------------------------- | ---- | ------------------------------ | -| HUKS_CHALLENGE_POS_0 | 0 | 表示0~7字节为当前密钥的有效challenge。 | -| HUKS_CHALLENGE_POS_1 | 1 | 表示8~15字节为当前密钥的有效challenge。 | -| HUKS_CHALLENGE_POS_2 | 2 | 表示16~23字节为当前密钥的有效challenge。 | -| HUKS_CHALLENGE_POS_3 | 3 | 表示24~31字节为当前密钥的有效challenge。 | +**参数：** -## HuksSecureSignType9+ +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | +| callback | AsyncCallback\ | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | -表示生成或导入密钥时，指定该密钥的签名类型。 +**示例：** -**系统能力**：SystemCapability.Security.Huks +```js +/* 以导入AES256密钥为例 */ +let plainTextSize32 = makeRandomArr(32); +function makeRandomArr(size) { + let arr = new Uint8Array(size); + for (let i = 0; i < size; i++) { + arr[i] = Math.floor(Math.random() * 10); + } + return arr; +}; +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +let options = { + properties: properties, + inData: plainTextSize32 +}; +try { + huks.importKeyItem(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: importKeyItem success`); + } + }); +} catch (error) { + console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +} +``` -| 名称 | 值 | 说明 | -| ------------------------------ | ---- | ------------------------------------------------------------ | -| HUKS_SECURE_SIGN_WITH_AUTHINFO | 1 | 表示签名类型为携带认证信息。生成或导入密钥时指定该字段，则在使用密钥进行签名时，对待签名的数据添加认证信息后进行签名。 | +## huks.importKeyItem9+ -## HuksTagType +importKeyItem(keyAlias: string, options: HuksOptions) : Promise\ -表示Tag的数据类型。 +导入明文密钥，使用Promise方式异步返回结果。 **系统能力**：SystemCapability.Security.Huks +**参数：** -| 名称 | 值 | 说明 | -| --------------------- | ------- | --------------------------------------- | -| HUKS_TAG_TYPE_INVALID | 0 << 28 | 表示非法的Tag类型。 | -| HUKS_TAG_TYPE_INT | 1 << 28 | 表示该Tag的数据类型为int类型的number。 | -| HUKS_TAG_TYPE_UINT | 2 << 28 | 表示该Tag的数据类型为uint类型的number。 | -| HUKS_TAG_TYPE_ULONG | 3 << 28 | 表示该Tag的数据类型为bigint。 | -| HUKS_TAG_TYPE_BOOL | 4 << 28 | 表示该Tag的数据类型为boolean。 | -| HUKS_TAG_TYPE_BYTES | 5 << 28 | 表示该Tag的数据类型为Uint8Array。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------------------------------- | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | -## HuksTag +**示例：** -表示调用参数的Tag。 +```js +/* 以导入AES128为例 */ +let plainTextSize32 = makeRandomArr(32); -**系统能力**：SystemCapability.Security.Huks +function makeRandomArr(size) { + let arr = new Uint8Array(size); + for (let i = 0; i < size; i++) { + arr[i] = Math.floor(Math.random() * 10); + } + return arr; +}; -| 名称 | 值 | 说明 | -| -------------------------------------------- | ---------------------------------------- | -------------------------------------- | -| HUKS_TAG_INVALID | HuksTagType.HUKS_TAG_TYPE_INVALID \| 0 | 表示非法的Tag。 | -| HUKS_TAG_ALGORITHM | HUKS_TAG_TYPE_UINT \| 1 | 表示算法的Tag。 | -| HUKS_TAG_PURPOSE | HuksTagType.HUKS_TAG_TYPE_UINT \| 2 | 表示密钥用途的Tag。 | -| HUKS_TAG_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 3 | 表示密钥长度的Tag。 | -| HUKS_TAG_DIGEST | HuksTagType.HUKS_TAG_TYPE_UINT \| 4 | 表示摘要算法的Tag。 | -| HUKS_TAG_PADDING | HuksTagType.HUKS_TAG_TYPE_UINT \| 5 | 表示补齐算法的Tag。 | -| HUKS_TAG_BLOCK_MODE | HuksTagType.HUKS_TAG_TYPE_UINT \| 6 | 表示加密模式的Tag。 | -| HUKS_TAG_KEY_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 7 | 表示密钥类型的Tag。 | -| HUKS_TAG_ASSOCIATED_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 8 | 表示附加身份验证数据的Tag。 | -| HUKS_TAG_NONCE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 9 | 表示密钥加解密的字段。 | -| HUKS_TAG_IV | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10 | 表示密钥初始化的向量。 | -| HUKS_TAG_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 11 | 表示密钥派生时的info。 | -| HUKS_TAG_SALT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 12 | 表示密钥派生时的盐值。 | -| HUKS_TAG_PWD | HuksTagType.HUKS_TAG_TYPE_BYTES \| 13 | 表示密钥派生时的password。 | -| HUKS_TAG_ITERATION | HuksTagType.HUKS_TAG_TYPE_UINT \| 14 | 表示密钥派生时的迭代次数。 | -| HUKS_TAG_KEY_GENERATE_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 15 | 表示生成密钥类型的Tag。 | -| HUKS_TAG_DERIVE_MAIN_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 16 | 表示密钥派生时的主密钥。 | -| HUKS_TAG_DERIVE_FACTOR | HuksTagType.HUKS_TAG_TYPE_BYTES \| 17 | 表示密钥派生时的派生因子。 | -| HUKS_TAG_DERIVE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 18 | 表示密钥派生时的算法类型。 | -| HUKS_TAG_AGREE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 19 | 表示密钥协商时的算法类型。 | -| HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 20 | 表示密钥协商时的公钥别名。 | -| HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 21 | 表示密钥协商时的私钥别名。 | -| HUKS_TAG_AGREE_PUBLIC_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 22 | 表示密钥协商时的公钥。 | -| HUKS_TAG_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 23 | 表示密钥别名。 | -| HUKS_TAG_DERIVE_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 24 | 表示派生密钥的大小。 | -| HUKS_TAG_IMPORT_KEY_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 25 | 表示导入的密钥类型。 | -| HUKS_TAG_UNWRAP_ALGORITHM_SUITE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 26 | 表示导入加密密钥的套件。 | -| HUKS_TAG_ACTIVE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 201 | 预留。 | -| HUKS_TAG_ORIGINATION_EXPIRE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 202 | 预留。 | -| HUKS_TAG_USAGE_EXPIRE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 203 | 预留。 | -| HUKS_TAG_CREATION_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 204 | 预留。 | -| HUKS_TAG_ALL_USERS | ksTagType.HUKS_TAG_TYPE_BOOL \| 301 | 预留。 | -| HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | 预留。 | -| HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | 预留。 | -| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | 表示用户认证类型。从[HuksUserAuthType](#huksuserauthtype9)中选择，需要与安全访问控制类型同时设置。支持同时指定两种用户认证类型，如：安全访问控制类型指定为HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL时，密钥访问认证类型可以指定以下三种： HKS_USER_AUTH_TYPE_FACE 、HKS_USER_AUTH_TYPE_FINGERPRINT、HKS_USER_AUTH_TYPE_FACE \| HKS_USER_AUTH_TYPE_FINGERPRINT | -| HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | 预留。 | -| HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | 预留。 | -| HUKS_TAG_KEY_AUTH_ACCESS_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 307 | 表示安全访问控制类型。从[HuksAuthAccessType](#huksauthaccesstype9)中选择，需要和用户认证类型同时设置。 | -| HUKS_TAG_KEY_SECURE_SIGN_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 308 | 表示生成或导入密钥时，指定该密钥的签名类型。 | -| HUKS_TAG_CHALLENGE_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 309 | 表示密钥使用时生成的challenge类型。从[HuksChallengeType](#hukschallengetype9)中选择 | -| HUKS_TAG_CHALLENGE_POS9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 310 | 表示challenge类型为用户自定义类型时，huks产生的challenge有效长度仅为8字节连续的数据。从[HuksChallengePosition](#hukschallengeposition9)中选择。 | -| HUKS_TAG_ATTESTATION_CHALLENGE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 501 | 表示attestation时的挑战值。 | -| HUKS_TAG_ATTESTATION_APPLICATION_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 502 | 表示attestation时拥有该密钥的application的Id。 | -| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | 表示设备的品牌。 | -| HUKS_TAG_ATTESTATION_ID_DEVICE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 504 | 表示设备的设备ID。 | -| HUKS_TAG_ATTESTATION_ID_PRODUCT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 505 | 表示设备的产品名。 | -| HUKS_TAG_ATTESTATION_ID_SERIAL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 506 | 表示设备的SN号。 | -| HUKS_TAG_ATTESTATION_ID_IMEI | HuksTagType.HUKS_TAG_TYPE_BYTES \| 507 | 表示设备的IMEI号。 | -| HUKS_TAG_ATTESTATION_ID_MEID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 508 | 表示设备的MEID号。 | -| HUKS_TAG_ATTESTATION_ID_MANUFACTURER | HuksTagType.HUKS_TAG_TYPE_BYTES \| 509 | 表示设备的制造商。 | -| HUKS_TAG_ATTESTATION_ID_MODEL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 510 | 表示设备的型号。 | -| HUKS_TAG_ATTESTATION_ID_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 511 | 表示attestation时的密钥别名。 | -| HUKS_TAG_ATTESTATION_ID_SOCID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 512 | 表示设备的SOCID。 | -| HUKS_TAG_ATTESTATION_ID_UDID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 513 | 表示设备的UDID。 | -| HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 514 | 表示attestation时的安全凭据。 | -| HUKS_TAG_ATTESTATION_ID_VERSION_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 515 | 表示attestation时的版本号。 | -| HUKS_TAG_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1001 | 表示是否使用生成key时传入的别名的Tag。 | -| HUKS_TAG_KEY_STORAGE_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1002 | 表示密钥存储方式的Tag。 | -| HUKS_TAG_IS_ALLOWED_WRAP | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1003 | 预留。 | -| HUKS_TAG_KEY_WRAP_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1004 | 预留。 | -| HUKS_TAG_KEY_AUTH_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1005 | 预留。 | -| HUKS_TAG_KEY_ROLE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1006 | 预留。 | -| HUKS_TAG_KEY_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1007 | 表示密钥标志的Tag。 | -| HUKS_TAG_IS_ASYNCHRONIZED | HuksTagType.HUKS_TAG_TYPE_UINT \| 1008 | 预留。 | -| HUKS_TAG_SECURE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1009 | 预留。 | -| HUKS_TAG_SECURE_KEY_UUID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1010 | 预留。 | -| HUKS_TAG_KEY_DOMAIN | HuksTagType.HUKS_TAG_TYPE_UINT \| 1011 | 预留。 | -| HUKS_TAG_PROCESS_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10001 | 表示进程名称的Tag。 | -| HUKS_TAG_PACKAGE_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10002 | 预留。 | -| HUKS_TAG_ACCESS_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10003 | 预留。 | -| HUKS_TAG_USES_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10004 | 预留。 | -| HUKS_TAG_CRYPTO_CTX | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10005 | 预留。 | -| HUKS_TAG_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10006 | 预留。 | -| HUKS_TAG_KEY_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10007 | 表示密钥版本的Tag。 | -| HUKS_TAG_PAYLOAD_LEN | HuksTagType.HUKS_TAG_TYPE_UINT \| 10008 | 预留。 | -| HUKS_TAG_AE_TAG | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10009 | 预留。 | -| HUKS_TAG_IS_KEY_HANDLE | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10010 | 预留。 | -| HUKS_TAG_OS_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10101 | 表示操作系统版本的Tag。 | -| HUKS_TAG_OS_PATCHLEVEL | HuksTagType.HUKS_TAG_TYPE_UINT \| 10102 | 表示操作系统补丁级别的Tag。 | -| HUKS_TAG_SYMMETRIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20001 | 预留。 | -| HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20002 | 预留。 | -| HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20003 | 预留。 | - -## huks.generateKey(deprecated) - -generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -生成密钥，使用Callback回调异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其余结果请参考HuksResult进行错误码查询。 | - -**示例：** - -```js -/* 以生成RSA512密钥为例 */ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_OAEP -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 -}; -var options = { - properties: properties -}; -huks.generateKey(keyAlias, options, function (err, data){}); -``` - -## huks.generateKey(deprecated) - -generateKey(keyAlias: string, options: HuksOptions) : Promise\ - -生成密钥，使用Promise方式异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9-1)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------ | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | - -**返回值**：（可选，如不涉及可删除） - -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 以生成ECC256密钥为例 */ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_ECC -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 -}; -var options = { - properties: properties -}; -var result = huks.generateKey(keyAlias, options); -``` - -## huks.generateKeyItem9+ - -generateKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -生成密钥，使用Callback回调异步返回结果。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | -| callback | AsyncCallback\ | 是 | 不返回err值时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -/* 以生成ECC256密钥为例 */ -var keyAlias = 'keyAlias'; -var properties = new Array(); +/*第一步：生成密钥*/ +let keyAlias = 'keyAlias'; +let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_ECC + value: huks.HuksKeyAlg.HUKS_ALG_AES }; properties[1] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128 }; properties[2] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: - huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | - huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT }; properties[3] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 }; -var options = { - properties: properties +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +let huksoptions = { + properties: properties, + inData: plainTextSize32 }; try { - huks.generateKeyItem(keyAlias, options, function (error, data) { - if (error) { - console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: generateKeyItem key success`); - } - }); + huks.importKeyItem(keyAlias, huksoptions) + .then ((data) => { + console.info(`promise: importKeyItem success`); + }) + .catch(error => { + console.error(`promise: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); } catch (error) { - console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` -## huks.generateKeyItem9+ +## huks.attestKeyItem9+ -generateKeyItem(keyAlias: string, options: HuksOptions) : Promise\ +attestKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -生成密钥，使用Promise方式异步返回结果。 +获取密钥证书，使用Callback方式回调异步返回结果 。 **系统能力**：SystemCapability.Security.Huks -**参数：** +**参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------ | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，存放待获取证书密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于获取证书时指定所需参数与数据。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 以生成ECC256密钥为例 */ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_ECC -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: - huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | - huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 -}; -var options = { - properties: properties -}; -try { - huks.generateKeyItem(keyAlias, options) - .then((data) => { - console.info(`promise: generateKeyItem success`); - }) - .catch(error => { - console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); -} catch (error) { - console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); -} -``` - -## huks.deleteKey(deprecated) - -deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -删除密钥，使用Callback回调异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9)替代。 - -**系统能力**：SystemCapability.Security.Huks +let securityLevel = stringToUint8Array('sec_level'); +let challenge = stringToUint8Array('challenge_data'); +let versionInfo = stringToUint8Array('version_info'); +let keyAliasString = "key attest"; -**参数：** +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + let tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | -------------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +async function generateKey(alias) { + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, + value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PSS + }; + properties[6] = { + tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, + value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT + }; + properties[7] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB + }; + let options = { + properties: properties + }; -**示例：** + try { + huks.generateKeyItem(alias, options, function (error, data) { + if (error) { + console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: generateKeyItem success`); + } + }); + } catch (error) { + console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} -```js -/* 此处options选择emptyOptions传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -huks.deleteKey(keyAlias, emptyOptions, function (err, data) {}); +async function attestKey() { + let aliasString = keyAliasString; + let aliasUint8 = stringToUint8Array(aliasString); + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, + value: securityLevel + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, + value: challenge + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, + value: versionInfo + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, + value: aliasUint8 + }; + let options = { + properties: properties + }; + await generateKey(aliasString); + try { + huks.attestKeyItem(aliasString, options, function (error, data) { + if (error) { + console.error(`callback: attestKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: attestKeyItem success`); + } + }); + } catch (error) { + console.error(`callback: attestKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} ``` -## huks.deleteKey(deprecated) - -deleteKey(keyAlias: string, options: HuksOptions) : Promise\ +## huks.attestKeyItem9+ -删除密钥，使用Promise方式异步返回结果。 +attestKeyItem(keyAlias: string, options: HuksOptions) : Promise\ -> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9-1)替代。 +获取密钥证书，使用Promise方式异步返回结果 。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ----------------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------ | +| keyAlias | string | 是 | 密钥别名，存放待获取证书密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于获取证书时指定所需参数与数据。 | **返回值：** -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +| 类型 | 说明 | +| ---------------------------------------------- | --------------------------------------------- | +| Promise<[HuksReturnResult](#huksreturnresult)> | Promise对象。不返回err值时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -var result = huks.deleteKey(keyAlias, emptyOptions); -``` - -## huks.deleteKeyItem9+ - -deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -删除密钥，使用Callback回调异步返回结果。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** +let securityLevel = stringToUint8Array('sec_level'); +let challenge = stringToUint8Array('challenge_data'); +let versionInfo = stringToUint8Array('version_info'); +let keyAliasString = "key attest"; -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\ | 是 | 不返回err值时表示接口使用成功，其他时为错误。 | +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + let tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} -**示例：** +async function generateKey(alias) { + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, + value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PSS + }; + properties[6] = { + tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, + value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT + }; + properties[7] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB + }; + let options = { + properties: properties + }; -```js -/* 此处options选择emptyOptions传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -try { - huks.deleteKeyItem(keyAlias, emptyOptions, function (error, data) { - if (error) { - console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: deleteKeyItem key success`); - } - }); -} catch (error) { - console.error(`callback: deleteKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + try { + await huks.generateKeyItem(alias, options) + .then((data) => { + console.info(`promise: generateKeyItem success`); + }) + .catch(error => { + console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } } -``` - -## huks.deleteKeyItem9+ -deleteKeyItem(keyAlias: string, options: HuksOptions) : Promise\ - -删除密钥，使用Promise方式异步返回结果。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ----------------------------------- | -| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | - -**示例：** - -```js -/* 此处options选择emptyOptions传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -try { - huks.deleteKeyItem(keyAlias, emptyOptions) - .then ((data) => { - console.info(`promise: deleteKeyItem key success`); - }) - .catch(error => { - console.error(`promise: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); -} catch (error) { - console.error(`promise: deleteKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); +async function attestKey() { + let aliasString = keyAliasString; + let aliasUint8 = stringToUint8Array(aliasString); + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, + value: securityLevel + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, + value: challenge + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, + value: versionInfo + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, + value: aliasUint8 + }; + let options = { + properties: properties + }; + await generateKey(aliasString); + try { + await huks.attestKeyItem(aliasString, options) + .then ((data) => { + console.info(`promise: attestKeyItem success`); + }) + .catch(error => { + console.error(`promise: attestKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: attestKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } } ``` -## huks.getSdkVersion +## huks.importWrappedKeyItem9+ -getSdkVersion(options: HuksOptions) : string +importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -获取当前系统sdk版本。 +导入加密密钥，使用Callback方式回调异步返回结果 。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ---------- | ---- | ------------------------- | -| options | [HuksOptions](#huksoptions) | 是 | 空对象，用于存放sdk版本。 | - -**返回值：** - -| 类型 | 说明 | -| ------ | ------------- | -| string | 返回sdk版本。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------------- | --------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，存放待导入密钥的别名。 | +| wrappingKeyAlias | string | 是 | 密钥别名，对应密钥用于解密加密的密钥数据。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的加密的密钥数据。 | +| callback | AsyncCallback\ | 是 | 回调函数。不返回err值时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions传空 */ -var emptyOptions = { - properties: [] -}; -var result = huks.getSdkVersion(emptyOptions); -``` - -## huks.importKey(deprecated) - -importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -导入明文密钥，使用Callback方式回调异步返回结果 。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9)替代。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | ------------------------------------------------- | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +import huks from '@ohos.security.huks'; -**示例：** +let exportWrappingKey; +let alias1 = "importAlias"; +let alias2 = "wrappingKeyAlias"; -```js -/* 以导入AES256密钥为例 */ -var plainTextSize32 = makeRandomArr(32); -function makeRandomArr(size) { - var arr = new Uint8Array(size); - for (var i = 0; i < size; i++) { - arr[i] = Math.floor(Math.random() * 10); +async function TestGenFunc(alias, options) { + try { + await genKey(alias, options) + .then((data) => { + console.info(`callback: generateKeyItem success`); + }) + .catch(error => { + console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } - return arr; -}; -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: -huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB -}; -var options = { - properties: properties, - inData: plainTextSize32 -}; -huks.importKey(keyAlias, options, function (err, data){}); -``` +} -## huks.importKey(deprecated) +function genKey(alias, options) { + return new Promise((resolve, reject) => { + try { + huks.generateKeyItem(alias, options, function (error, data) { + if (error) { + reject(error); + } else { + resolve(data); + } + }); + } catch (error) { + throw(error); + } + }); +} -importKey(keyAlias: string, options: HuksOptions) : Promise\ +async function TestExportFunc(alias, options) { + try { + await exportKey(alias, options) + .then ((data) => { + console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); + exportWrappingKey = data.outData; + }) + .catch(error => { + console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} -导入明文密钥，使用Promise方式异步返回结果。 +function exportKey(alias, options) : Promise { + return new Promise((resolve, reject) => { + try { + huks.exportKeyItem(alias, options, function (error, data) { + if (error) { + reject(error); + } else { + resolve(data); + } + }); + } catch (error) { + throw(error); + } + }); +} -> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9-1)替代。 +async function TestImportWrappedFunc(alias, wrappingAlias, options) { + try { + await importWrappedKey(alias, wrappingAlias, options) + .then ((data) => { + console.info(`callback: importWrappedKeyItem success`); + }) + .catch(error => { + console.error(`callback: importWrappedKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`callback: importWrappedKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} -**系统能力**：SystemCapability.Security.Huks +function importWrappedKey(alias, wrappingAlias, options) { + return new Promise((resolve, reject) => { + try { + huks.importWrappedKeyItem(alias, wrappingAlias, options, function (error, data) { + if (error) { + reject(error); + } else { + resolve(data); + } + }); + } catch (error) { + throw(error); + } + }); +} -**参数：** +async function TestImportWrappedKeyFunc( + alias, + wrappingAlias, + genOptions, + importOptions +) { + await TestGenFunc(wrappingAlias, genOptions); + await TestExportFunc(wrappingAlias, genOptions); -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------------ | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | + /* 以下操作不需要调用HUKS接口，此处不给出具体实现。 + * 假设待导入的密钥为keyA + * 1.生成ECC公私钥keyB，公钥为keyB_pub, 私钥为keyB_pri + * 2.使用keyB_pri和wrappingAlias密钥中获取的公钥进行密钥协商，协商出共享密钥share_key + * 3.随机生成密钥kek，用于加密keyA，采用AES-GCM加密，加密过程中需要记录：nonce1、aad1、加密后的密文keyA_enc、加密后的tag1。 + * 4.使用share_key加密kek，采用AES-GCM加密，加密过程中需要记录：nonce2、aad2、加密后的密文kek_enc、加密后的tag2。 + * 5.拼接importOptions.inData字段，满足以下格式: + * keyB_pub的长度（4字节） + keyB_pub的数据 + aad2的长度（4字节） + aad2的数据 + + * nonce2的长度（4字节） + nonce2的数据 + tag2的长度（4字节） + tag2的数据 + + * kek_enc的长度（4字节） + kek_enc的数据 + aad1的长度（4字节） + aad1的数据 + + * nonce1的长度（4字节） + nonce1的数据 + tag1的长度（4字节） + tag1的数据 + + * keyA长度占用的内存长度（4字节） + keyA的长度 + keyA_enc的长度（4字节） + keyA_enc的数据 + */ + let inputKey = new Uint8Array([0x02, 0x00, 0x00, 0x00]); + importOptions.inData = inputKey; + await TestImportWrappedFunc(alias, wrappingAlias, importOptions); +} -**返回值：** +function makeGenerateOptions() { + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_UNWRAP + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_IMPORT_KEY_TYPE, + value: huks.HuksImportKeyType.HUKS_KEY_TYPE_KEY_PAIR, + }; + let options = { + properties: properties + }; + return options; +}; -| 类型 | 说明 | -| ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresult)> | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +function makeImportOptions() { + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_CBC + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_UNWRAP_ALGORITHM_SUITE, + value: huks.HuksUnwrapSuite.HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING + }; + let options = { + properties: properties + }; + return options; +}; + +function huksImportWrappedKey() { + let genOptions = makeGenerateOptions(); + let importOptions = makeImportOptions(); + TestImportWrappedKeyFunc( + alias1, + alias2, + genOptions, + importOptions + ); +} +``` + +## huks.importWrappedKeyItem9+ + +importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions) : Promise\ + +导入加密密钥，使用Promise方式异步返回结果。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------------- | --------------------------- | ---- | --------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，存放待导入密钥的别名。 | +| wrappingKeyAlias | string | 是 | 密钥别名，对应密钥用于解密加密的密钥数据。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的加密的密钥数据。 | **示例：** ```js -/* 以导入AES128为例 */ -var plainTextSize32 = makeRandomArr(32); - -function makeRandomArr(size) { - var arr = new Uint8Array(size); - for (var i = 0; i < size; i++) { - arr[i] = Math.floor(Math.random() * 10); +/* 处理流程与callback类似，主要差异点为如下函数： */ +async function TestImportWrappedFunc(alias, wrappingAlias, options) { + try { + await huks.importWrappedKeyItem(alias, wrappingAlias, options) + .then ((data) => { + console.info(`promise: importWrappedKeyItem success`); + }) + .catch(error => { + console.error(`promise: importWrappedKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: importWrappedKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } - return arr; -}; - -/*第一步：生成密钥*/ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB -}; -var huksoptions = { - properties: properties, - inData: plainTextSize32 -}; -var result = huks.importKey(keyAlias, huksoptions); +} ``` -## huks.importKeyItem9+ +## huks.exportKeyItem9+ -importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +exportKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -导入明文密钥，使用Callback方式回调异步返回结果 。 +导出密钥，使用Callback方式回调异步返回的结果。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | -| callback | AsyncCallback\ | 是 | 不返回err值时表示接口使用成功，其他时为错误。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | **示例：** ```js -/* 以导入AES256密钥为例 */ -var plainTextSize32 = makeRandomArr(32); -function makeRandomArr(size) { - var arr = new Uint8Array(size); - for (var i = 0; i < size; i++) { - arr[i] = Math.floor(Math.random() * 10); - } - return arr; -}; -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: - huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB -}; -var options = { - properties: properties, - inData: plainTextSize32 +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] }; try { - huks.importKeyItem(keyAlias, options, function (error, data) { + huks.exportKeyItem(keyAlias, emptyOptions, function (error, data) { if (error) { - console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); + console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); } else { - console.info(`callback: importKeyItem success`); + console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); } }); } catch (error) { - console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` -## huks.importKeyItem9+ +## huks.exportKeyItem9+ -importKeyItem(keyAlias: string, options: HuksOptions) : Promise\ +exportKeyItem(keyAlias: string, options: HuksOptions) : Promise\ -导入明文密钥，使用Promise方式异步返回结果。 +导出密钥，使用Promise方式回调异步返回的结果。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ----------------------------------- | -| keyAlias | string | 是 | 密钥别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -**示例：** +**返回值：** -```js -/* 以导入AES128为例 */ -var plainTextSize32 = makeRandomArr(32); +| 类型 | 说明 | +| ---------------------------------------------- | ------------------------------------------------------------ | +| Promise<[HuksReturnResult](#huksreturnresult)> | Promise对象。不返回err值时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | -function makeRandomArr(size) { - var arr = new Uint8Array(size); - for (var i = 0; i < size; i++) { - arr[i] = Math.floor(Math.random() * 10); - } - return arr; -}; +**示例：** -/*第一步：生成密钥*/ -var keyAlias = 'keyAlias'; -var properties = new Array(); -properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES -}; -properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128 -}; -properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT -}; -properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 -}; -properties[4] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB -}; -var huksoptions = { - properties: properties, - inData: plainTextSize32 +```js +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] }; try { - huks.importKeyItem(keyAlias, huksoptions) + huks.exportKeyItem(keyAlias, emptyOptions) .then ((data) => { - console.info(`promise: importKeyItem success`); + console.info(`promise: exportKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { - console.error(`promise: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); }); } catch (error) { - console.error(`promise: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + console.error(`promise: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` -## huks.attestKeyItem9+ +## huks.getKeyItemProperties9+ -attestKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +getKeyItemProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -获取密钥证书，使用Callback方式回调异步返回结果 。 +获取密钥属性，使用Callback回调异步返回结果。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，存放待获取证书密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于获取证书时指定所需参数与数据。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 不返回err值时表示接口使用成功，其他时为错误。 | - -**示例：** - -```js -let securityLevel = stringToUint8Array('sec_level'); -let challenge = stringToUint8Array('challenge_data'); -let versionInfo = stringToUint8Array('version_info'); -let keyAliasString = "key attest"; - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -async function generateKey(alias) { - let properties = new Array(); - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, - value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - properties[5] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_PSS - }; - properties[6] = { - tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, - value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT - }; - properties[7] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB - }; - let options = { - properties: properties - }; +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | - try { - huks.generateKeyItem(alias, options, function (error, data) { - if (error) { - console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: generateKeyItem success`); - } - }); - } catch (error) { - console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} +**示例：** -async function attestKey() { - let aliasString = keyAliasString; - let aliasUint8 = stringToUint8Array(aliasString); - let properties = new Array(); - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, - value: securityLevel - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, - value: challenge - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, - value: versionInfo - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, - value: aliasUint8 - }; - let options = { - properties: properties - }; - await generateKey(aliasString); - try { - huks.attestKeyItem(aliasString, options, function (error, data) { - if (error) { - console.error(`callback: attestKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: attestKeyItem success`); - } - }); - } catch (error) { - console.error(`callback: attestKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } +```js +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +try { + huks.getKeyItemProperties(keyAlias, emptyOptions, function (error, data) { + if (error) { + console.error(`callback: getKeyItemProperties failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: getKeyItemProperties success, data = ${JSON.stringify(data)}`); + } + }); +} catch (error) { + console.error(`callback: getKeyItemProperties input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` -## huks.attestKeyItem9+ +## huks.getKeyItemProperties9+ -attestKeyItem(keyAlias: string, options: HuksOptions) : Promise\ +getKeyItemProperties(keyAlias: string, options: HuksOptions) : Promise\ -获取密钥证书，使用Promise方式异步返回结果 。 +获取密钥属性，使用Promise回调异步返回结果。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------ | -| keyAlias | string | 是 | 密钥别名，存放待获取证书密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于获取证书时指定所需参数与数据。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------------------- | --------------------------------------------- | -| Promise<[HuksReturnResult](#huksreturnresult)> | 不返回err值时表示接口使用成功，其他时为错误。 | +| 类型 | 说明 | +| ----------------------------------------------- | ------------------------------------------------------------ | +| Promise\<[HuksReturnResult](#huksreturnresult)> | Promise对象。不返回err值时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | **示例：** ```js -let securityLevel = stringToUint8Array('sec_level'); -let challenge = stringToUint8Array('challenge_data'); -let versionInfo = stringToUint8Array('version_info'); -let keyAliasString = "key attest"; - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -async function generateKey(alias) { - let properties = new Array(); - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, - value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - properties[5] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_PSS - }; - properties[6] = { - tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, - value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT - }; - properties[7] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB - }; - let options = { - properties: properties - }; - - try { - await huks.generateKeyItem(alias, options) - .then((data) => { - console.info(`promise: generateKeyItem success`); - }) - .catch(error => { - console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} - -async function attestKey() { - let aliasString = keyAliasString; - let aliasUint8 = stringToUint8Array(aliasString); - let properties = new Array(); - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, - value: securityLevel - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, - value: challenge - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, - value: versionInfo - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, - value: aliasUint8 - }; - let options = { - properties: properties - }; - await generateKey(aliasString); - try { - await huks.attestKeyItem(aliasString, options) - .then ((data) => { - console.info(`promise: attestKeyItem success`); - }) - .catch(error => { - console.error(`promise: attestKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: attestKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +try { + huks.getKeyItemProperties(keyAlias, emptyOptions) + .then ((data) => { + console.info(`promise: getKeyItemProperties success, data = ${JSON.stringify(data)}`); + }) + .catch(error => { + console.error(`promise: getKeyItemProperties failed, code: ${error.code}, msg: ${error.message}`); + }); +} catch (error) { + console.error(`promise: getKeyItemProperties input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` -## huks.importWrappedKeyItem9+ +## huks.isKeyItemExist9+ -importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +isKeyItemExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -导入加密密钥，使用Callback方式回调异步返回结果 。 +判断密钥是否存在，使用Callback回调异步返回结果 。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------------- | --------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，存放待导入密钥的别名。 | -| wrappingKeyAlias | string | 是 | 密钥别名，对应密钥用于解密加密的密钥数据。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的加密的密钥数据。 | -| callback | AsyncCallback\ | 是 | 不返回err值时表示接口使用成功，其他时为错误。 | - +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------- | +| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\ | 是 | 回调函数。FALSE代表密钥不存在，TRUE代表密钥存在。 | + **示例：** ```js -import huks from '@ohos.security.huks'; - -var exportWrappingKey; -var alias1 = "importAlias"; -var alias2 = "wrappingKeyAlias"; - -async function TestGenFunc(alias, options) { - try { - await genKey(alias, options) - .then((data) => { - console.info(`callback: generateKeyItem success`); - }) - .catch(error => { - console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} - -function genKey(alias, options) { - return new Promise((resolve, reject) => { - try { - huks.generateKeyItem(alias, options, function (error, data) { - if (error) { - reject(error); - } else { - resolve(data); - } - }); - } catch (error) { - throw(error); +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +try { + huks.isKeyItemExist(keyAlias, emptyOptions, function (error, data) { + if (error) { + console.info(`callback: isKeyItemExist success, data = ${JSON.stringify(data)}`); + } else { + console.error(`callback: isKeyItemExist failed, code: ${error.code}, msg: ${error.message}`); } }); +} catch (error) { + console.error(`promise: isKeyItemExist input arg invalid, code: ${error.code}, msg: ${error.message}`); } +``` -async function TestExportFunc(alias, options) { - try { - await exportKey(alias, options) - .then ((data) => { - console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); - exportWrappingKey = data.outData; - }) - .catch(error => { - console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} +## huks.isKeyItemExist9+ -function exportKey(alias, options) : Promise { - return new Promise((resolve, reject) => { - try { - huks.exportKeyItem(alias, options, function (error, data) { - if (error) { - reject(error); - } else { - resolve(data); - } - }); - } catch (error) { - throw(error); - } - }); -} +isKeyItemExist(keyAlias: string, options: HuksOptions) : Promise\ -async function TestImportWrappedFunc(alias, wrappingAlias, options) { - try { - await importWrappedKey(alias, wrappingAlias, options) - .then ((data) => { - console.info(`callback: importWrappedKeyItem success`); - }) - .catch(error => { - console.error(`callback: importWrappedKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`callback: importWrappedKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} +判断密钥是否存在，使用Promise回调异步返回结果 。 -function importWrappedKey(alias, wrappingAlias, options) { - return new Promise((resolve, reject) => { - try { - huks.importWrappedKeyItem(alias, wrappingAlias, options, function (error, data) { - if (error) { - reject(error); - } else { - resolve(data); - } - }); - } catch (error) { - throw(error); - } - }); -} +**系统能力**：SystemCapability.Security.Huks -async function TestImportWrappedKeyFunc( - alias, - wrappingAlias, - genOptions, - importOptions -) { - await TestGenFunc(wrappingAlias, genOptions); - await TestExportFunc(wrappingAlias, genOptions); +**参数：** - /* 以下操作不需要调用HUKS接口，此处不给出具体实现。 - * 假设待导入的密钥为keyA - * 1.生成ECC公私钥keyB，公钥为keyB_pub, 私钥为keyB_pri - * 2.使用keyB_pri和wrappingAlias密钥中获取的公钥进行密钥协商，协商出共享密钥share_key - * 3.随机生成密钥kek，用于加密keyA，采用AES-GCM加密，加密过程中需要记录：nonce1、aad1、加密后的密文keyA_enc、加密后的tag1。 - * 4.使用share_key加密kek，采用AES-GCM加密，加密过程中需要记录：nonce2、aad2、加密后的密文kek_enc、加密后的tag2。 - * 5.拼接importOptions.inData字段，满足以下格式: - * keyB_pub的长度（4字节） + keyB_pub的数据 + aad2的长度（4字节） + aad2的数据 + - * nonce2的长度（4字节） + nonce2的数据 + tag2的长度（4字节） + tag2的数据 + - * kek_enc的长度（4字节） + kek_enc的数据 + aad1的长度（4字节） + aad1的数据 + - * nonce1的长度（4字节） + nonce1的数据 + tag1的长度（4字节） + tag1的数据 + - * keyA长度占用的内存长度（4字节） + keyA的长度 + keyA_enc的长度（4字节） + keyA_enc的数据 - */ - var inputKey = new Uint8Array([0x02, 0x00, 0x00, 0x00]); - importOptions.inData = inputKey; - await TestImportWrappedFunc(alias, wrappingAlias, importOptions); -} +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------ | +| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -function makeGenerateOptions() { - var properties = new Array(); - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_ECC - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_UNWRAP - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_IMPORT_KEY_TYPE, - value: huks.HuksImportKeyType.HUKS_KEY_TYPE_KEY_PAIR, - }; - var options = { - properties: properties - }; - return options; -}; +**返回值：** -function makeImportOptions() { - var properties = new Array(); - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_AES - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_CBC - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_NONE - }; - properties[5] = { - tag: huks.HuksTag.HUKS_TAG_UNWRAP_ALGORITHM_SUITE, - value: huks.HuksUnwrapSuite.HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING - }; - var options = { - properties: properties - }; - return options; +| 类型 | 说明 | +| ----------------- | --------------------------------------- | +| Promise\ | Promise对象。FALSE代表密钥不存在，TRUE代表密钥存在。 | + +**示例：** + +```js +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] }; +try { + huks.isKeyItemExist(keyAlias, emptyOptions) + .then ((data) => { + console.info(`promise: isKeyItemExist success, data = ${JSON.stringify(data)}`); + }) + .catch(error => { + console.error(`promise: isKeyItemExist failed, code: ${error.code}, msg: ${error.message}`); + }); +} catch (error) { + console.error(`promise: isKeyItemExist input arg invalid, code: ${error.code}, msg: ${error.message}`); +} +``` + +## huks.initSession9+ + +initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +initSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------- | ---- | ---------------------------------------------------- | +| keyAlias | string | 是 | Init操作密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | Init操作的参数集合。 | +| callback | AsyncCallback\<[HuksSessionHandle](#hukssessionhandle)> | 是 | 回调函数。将Init操作操作返回的handle添加到密钥管理系统的回调。 | + + +## huks.initSession9+ + +initSession(keyAlias: string, options: HuksOptions) : Promise\ + +initSession操作密钥接口，使用Promise方式异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | ------------------------------------------------ | +| keyAlias | string | 是 | Init操作密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | Init参数集合。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksSessionHandle](#hukssessionhandle)> | Promise对象。将Init操作返回的handle添加到密钥管理系统的回调。 | + +## huks.updateSession9+ + +updateSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +updateSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Update的参数集合。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | + + +## huks.updateSession9+ + +updateSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void + +updateSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | +| token | Uint8Array | 是 | Update操作的token。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | + +## huks.updateSession9+ + +updateSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ + +uupdateSession操作密钥接口，使用Promise方式异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ---------------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | +| token | Uint8Array | 否 | Update操作的token。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise<[HuksReturnResult](#huksreturnresult)> | Promise对象。将Update操作的结果添加到密钥管理系统的回调。 | + +## huks.finishSession9+ + +finishSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +finishSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | +| token | Uint8Array | 是 | Finish操作的token。 | +| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | + +## huks.finishSession9+ + +finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void + +finishSession操作密钥接口，使用Callback回调异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | +| token | Uint8Array | 是 | Finish操作的token。 | +| callback | AsyncCallback\<[HuksReturnResult](#huksreturnresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | + + +## huks.finishSession9+ + +finishSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ + +finishSession操作密钥接口，使用Promise方式异步返回结果。huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------------- | ---- | ----------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish操作的参数集合。 | +| token | Uint8Array | 否 | Finish操作的token。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksReturnResult](#huksreturnresult)> | Promise对象，用于获取异步返回结果。 | + + +## huks.abortSession9+ + +abortSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +abort操作密钥接口，使用Callback回调异步返回结果 。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | +| callback | AsyncCallback\ | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 | + +**示例：** + +```js +/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 + * huks.initSession和huks.updateSession + * 以及huks.finishSession操作中的任一阶段发生错误时， + * 都需要调用huks.abortSession来终止密钥的使用。 + * + * 以下以RSA1024密钥的callback功能使用为例 + */ +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + let tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +let keyAlias = "HuksDemoRSA"; +let properties = new Array(); +let options = { + properties: properties, + inData: new Uint8Array(0) +}; +let handle; +async function generateKey() { + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5 + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + + try { + await huks.generateKeyItem(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: generateKeyItem success`); + } + }); + } catch (error) { + console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksInit() { + console.log('enter huksInit'); + try { + huks.initSession(keyAlias, options, function (error, data) { + if (error) { + console.error(`callback: initSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: initSession success, data = ${JSON.stringify(data)}`); + handle = data.handle; + } + }); + } catch (error) { + console.error(`callback: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksUpdate() { + console.log('enter huksUpdate'); + options.inData = stringToUint8Array("huksHmacTest"); + try { + huks.updateSession(handle, options, function (error, data) { + if (error) { + console.error(`callback: updateSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: updateSession success, data = ${JSON.stringify(data)}`); + } + }); + } catch (error) { + console.error(`callback: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksFinish() { + console.log('enter huksFinish'); + options.inData = new Uint8Array(0); + try { + huks.finishSession(handle, options, function (error, data) { + if (error) { + console.error(`callback: finishSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: finishSession success, data = ${JSON.stringify(data)}`); + } + }); + } catch (error) { + console.error(`callback: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksAbort() { + console.log('enter huksAbort'); + try { + huks.abortSession(handle, options, function (error, data) { + if (error) { + console.error(`callback: abortSession failed, code: ${error.code}, msg: ${error.message}`); + } else { + console.info(`callback: abortSession success`); + } + }); + } catch (error) { + console.error(`callback: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} +``` + +## huks.abortSession9+ + +abortSession(handle: number, options: HuksOptions) : Promise\; + +abort操作密钥接口，使用Promise方式异步返回结果。 + +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | --------------------------- | ---- | ------------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | + +**返回值**： + +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\ | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 | + +**示例：** + +```js +/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 + * huks.initSession和huks.updateSession + * 以及huks.finishSession操作中的任一阶段发生错误时， + * 都需要调用huks.abortSession来终止密钥的使用。 + * + * 以下以RSA1024密钥的callback功能使用为例 + */ +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + let tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +let keyAlias = "HuksDemoRSA"; +let properties = new Array(); +let options = { + properties: properties, + inData: new Uint8Array(0) +}; +let handle; +async function generateKey() { + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5 + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + + try { + await huks.generateKeyItem(keyAlias, options) + .then((data) => { + console.info(`promise: generateKeyItem success`); + }) + .catch(error => { + console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksInit() { + console.log('enter huksInit'); + try { + await huks.initSession(keyAlias, options) + .then ((data) => { + console.info(`promise: initSession success, data = ${JSON.stringify(data)}`); + handle = data.handle; + }) + .catch(error => { + console.error(`promise: initSession key failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksUpdate() { + console.log('enter huksUpdate'); + options.inData = stringToUint8Array("huksHmacTest"); + try { + await huks.updateSession(handle, options) + .then ((data) => { + console.info(`promise: updateSession success, data = ${JSON.stringify(data)}`); + }) + .catch(error => { + console.error(`promise: updateSession failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksFinish() { + console.log('enter huksFinish'); + options.inData = new Uint8Array(0); + try { + await huks.finishSession(handle, options) + .then ((data) => { + console.info(`promise: finishSession success, data = ${JSON.stringify(data)}`); + }) + .catch(error => { + console.error(`promise: finishSession failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} + +async function huksAbort() { + console.log('enter huksAbort'); + try { + await huks.abortSession(keyAlias, options) + .then ((data) => { + console.info(`promise: abortSession success`); + }) + .catch(error => { + console.error(`promise: abortSession failed, code: ${error.code}, msg: ${error.message}`); + }); + } catch (error) { + console.error(`promise: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + } +} +``` + + +## HuksExceptionErrCode9+ + +表示错误码的枚举以及对应的错误信息， 错误码表示错误类型，错误信息展示错误详情。 + +关于错误码的具体信息，可在[错误码参考文档](../errorcodes/errorcode-huks.md)中查看。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 说明 | 错误码 | +| ---------------------------------------------- | --------------------------- | -------- | +| HUKS_ERR_CODE_PERMISSION_FAIL | 权限错误导致失败。 | 201 | +| HUKS_ERR_CODE_ILLEGAL_ARGUMENT | 参数错误导致失败。 | 401 | +| HUKS_ERR_CODE_NOT_SUPPORTED_API | 不支持的API。 | 801 | +| HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED | 不支持的功能/特性。 | 12000001 | +| HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT | 缺少密钥算法参数。 | 12000002 | +| HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT | 无效密钥算法参数。 | 12000003 | +| HUKS_ERR_CODE_FILE_OPERATION_FAIL | 文件操作失败。 | 12000004 | +| HUKS_ERR_CODE_COMMUNICATION_FAIL | 通信失败。 | 12000005 | +| HUKS_ERR_CODE_CRYPTO_FAIL | 算法库操作失败。 | 12000006 | +| HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED | 密钥访问失败-密钥访问失效。 | 12000007 | +| HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED | 密钥访问失败-密钥认证失败。 | 12000008 | +| HUKS_ERR_CODE_KEY_AUTH_TIME_OUT | 密钥访问失败-密钥访问超时。 | 12000009 | +| HUKS_ERR_CODE_SESSION_LIMIT | 密钥操作会话数已达上限。 | 12000010 | +| HUKS_ERR_CODE_ITEM_NOT_EXIST | 目标对象不存在。 | 12000011 | +| HUKS_ERR_CODE_EXTERNAL_ERROR | 外部错误。 | 12000012 | +| HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST | 缺失所需凭据。 | 12000013 | +| HUKS_ERR_CODE_INSUFFICIENT_MEMORY | 内存不足。 | 12000014 | +| HUKS_ERR_CODE_CALL_SERVICE_FAILED | 调用其他系统服务失败。 | 12000015 | + +## HuksKeyPurpose + +表示密钥用途。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ------------------------ | ---- | -------------------------------- | +| HUKS_KEY_PURPOSE_ENCRYPT | 1 | 表示密钥用于对明文进行加密操作。 | +| HUKS_KEY_PURPOSE_DECRYPT | 2 | 表示密钥用于对密文进行解密操作。 | +| HUKS_KEY_PURPOSE_SIGN | 4 | 表示密钥用于对数据进行签名。 | +| HUKS_KEY_PURPOSE_VERIFY | 8 | 表示密钥用于验证签名后的数据。 | +| HUKS_KEY_PURPOSE_DERIVE | 16 | 表示密钥用于派生密钥。 | +| HUKS_KEY_PURPOSE_WRAP | 32 | 表示密钥用于加密导出。 | +| HUKS_KEY_PURPOSE_UNWRAP | 64 | 表示密钥加密导入。 | +| HUKS_KEY_PURPOSE_MAC | 128 | 表示密钥用于生成mac消息验证码。 | +| HUKS_KEY_PURPOSE_AGREE | 256 | 表示密钥用于进行密钥协商。 | + +## HuksKeyDigest + +表示摘要算法。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ---------------------- | ---- | ---------------------------------------- | +| HUKS_DIGEST_NONE | 0 | 表示无摘要算法。 | +| HUKS_DIGEST_MD5 | 1 | 表示MD5摘要算法。 | +| HUKS_DIGEST_SM39+ | 2 | 表示SM3摘要算法。 | +| HUKS_DIGEST_SHA1 | 10 | 表示SHA1摘要算法。 | +| HUKS_DIGEST_SHA224 | 11 | 表示SHA224摘要算法。 | +| HUKS_DIGEST_SHA256 | 12 | 表示SHA256摘要算法。 | +| HUKS_DIGEST_SHA384 | 13 | 表示SHA384摘要算法。 | +| HUKS_DIGEST_SHA512 | 14 | 表示SHA512摘要算法。 | + +## HuksKeyPadding + +表示补齐算法。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ---------------------- | ---- | ---------------------------------------- | +| HUKS_PADDING_NONE | 0 | 表示不使用补齐算法。 | +| HUKS_PADDING_OAEP | 1 | 表示使用OAEP补齐算法。 | +| HUKS_PADDING_PSS | 2 | 表示使用PSS补齐算法。 | +| HUKS_PADDING_PKCS1_V1_5 | 3 | 表示使用PKCS1_V1_5补齐算法。 | +| HUKS_PADDING_PKCS5 | 4 | 表示使用PKCS5补齐算法。 | +| HUKS_PADDING_PKCS7 | 5 | 表示使用PKCS7补齐算法。 | + +## HuksCipherMode + +表示加密模式。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ------------- | ---- | --------------------- | +| HUKS_MODE_ECB | 1 | 表示使用ECB加密模式。 | +| HUKS_MODE_CBC | 2 | 表示使用CBC加密模式。 | +| HUKS_MODE_CTR | 3 | 表示使用CTR加密模式。 | +| HUKS_MODE_OFB | 4 | 表示使用OFB加密模式。 | +| HUKS_MODE_CCM | 31 | 表示使用CCM加密模式。 | +| HUKS_MODE_GCM | 32 | 表示使用GCM加密模式。 | + +## HuksKeySize + +表示密钥长度。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ---------------------------------- | ---- | ------------------------------------------ | +| HUKS_RSA_KEY_SIZE_512 | 512 | 表示使用RSA算法的密钥长度为512bit。 | +| HUKS_RSA_KEY_SIZE_768 | 768 | 表示使用RSA算法的密钥长度为768bit。 | +| HUKS_RSA_KEY_SIZE_1024 | 1024 | 表示使用RSA算法的密钥长度为1024bit。 | +| HUKS_RSA_KEY_SIZE_2048 | 2048 | 表示使用RSA算法的密钥长度为2048bit。 | +| HUKS_RSA_KEY_SIZE_3072 | 3072 | 表示使用RSA算法的密钥长度为3072bit。 | +| HUKS_RSA_KEY_SIZE_4096 | 4096 | 表示使用RSA算法的密钥长度为4096bit。 | +| HUKS_ECC_KEY_SIZE_224 | 224 | 表示使用ECC算法的密钥长度为224bit。 | +| HUKS_ECC_KEY_SIZE_256 | 256 | 表示使用ECC算法的密钥长度为256bit。 | +| HUKS_ECC_KEY_SIZE_384 | 384 | 表示使用ECC算法的密钥长度为384bit。 | +| HUKS_ECC_KEY_SIZE_521 | 521 | 表示使用ECC算法的密钥长度为521bit。 | +| HUKS_AES_KEY_SIZE_128 | 128 | 表示使用AES算法的密钥长度为128bit。 | +| HUKS_AES_KEY_SIZE_192 | 196 | 表示使用AES算法的密钥长度为196bit。 | +| HUKS_AES_KEY_SIZE_256 | 256 | 表示使用AES算法的密钥长度为256bit。 | +| HUKS_AES_KEY_SIZE_512 | 512 | 表示使用AES算法的密钥长度为512bit。 | +| HUKS_CURVE25519_KEY_SIZE_256 | 256 | 表示使用CURVE25519算法的密钥长度为256bit。 | +| HUKS_DH_KEY_SIZE_2048 | 2048 | 表示使用DH算法的密钥长度为2048bit。 | +| HUKS_DH_KEY_SIZE_3072 | 3072 | 表示使用DH算法的密钥长度为3072bit。 | +| HUKS_DH_KEY_SIZE_4096 | 4096 | 表示使用DH算法的密钥长度为4096bit。 | +| HUKS_SM2_KEY_SIZE_2569+ | 256 | 表示SM2算法的密钥长度为256bit。 | +| HUKS_SM4_KEY_SIZE_1289+ | 128 | 表示SM4算法的密钥长度为128bit。 | + +## HuksKeyAlg + +表示密钥使用的算法。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ------------------------- | ---- | --------------------- | +| HUKS_ALG_RSA | 1 | 表示使用RSA算法。 | +| HUKS_ALG_ECC | 2 | 表示使用ECC算法。 | +| HUKS_ALG_DSA | 3 | 表示使用DSA算法。 | +| HUKS_ALG_AES | 20 | 表示使用AES算法。 | +| HUKS_ALG_HMAC | 50 | 表示使用HMAC算法。 | +| HUKS_ALG_HKDF | 51 | 表示使用HKDF算法。 | +| HUKS_ALG_PBKDF2 | 52 | 表示使用PBKDF2算法。 | +| HUKS_ALG_ECDH | 100 | 表示使用ECDH算法。 | +| HUKS_ALG_X25519 | 101 | 表示使用X25519算法。 | +| HUKS_ALG_ED25519 | 102 | 表示使用ED25519算法。 | +| HUKS_ALG_DH | 103 | 表示使用DH算法。 | +| HUKS_ALG_SM29+ | 150 | 表示使用SM2算法。 | +| HUKS_ALG_SM39+ | 151 | 表示使用SM3算法。 | +| HUKS_ALG_SM49+ | 152 | 表示使用SM4算法。 | + +## HuksKeyGenerateType + +表示生成密钥的类型。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ------------------------------ | ---- | ---------------- | +| HUKS_KEY_GENERATE_TYPE_DEFAULT | 0 | 默认生成的密钥。 | +| HUKS_KEY_GENERATE_TYPE_DERIVE | 1 | 派生生成的密钥。 | +| HUKS_KEY_GENERATE_TYPE_AGREE | 2 | 协商生成的密钥。 | + +## HuksKeyFlag + +表示密钥的产生方式。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| -------------------------- | ---- | ------------------------------------ | +| HUKS_KEY_FLAG_IMPORT_KEY | 1 | 表示通过导入公钥接口导入的密钥。 | +| HUKS_KEY_FLAG_GENERATE_KEY | 2 | 表示通过生成密钥接口生成的密钥。 | +| HUKS_KEY_FLAG_AGREE_KEY | 3 | 表示通过生成密钥协商接口生成的密钥。 | +| HUKS_KEY_FLAG_DERIVE_KEY | 4 | 表示通过生成密钥派生接口生成的密钥。 | + +## HuksKeyStorageType + +表示密钥存储方式。 + +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ----------------------- | ---- | ------------------------------ | +| HUKS_STORAGE_TEMP | 0 | 表示通过本地直接管理密钥。 | +| HUKS_STORAGE_PERSISTENT | 1 | 表示通过HUKS service管理密钥。 | + +## HuksSendType + +表示发送Tag的方式。 -function huksImportWrappedKey() { - var genOptions = makeGenerateOptions(); - var importOptions = makeImportOptions(); - TestImportWrappedKeyFunc( - alias1, - alias2, - genOptions, - importOptions - ); -} -``` +**系统能力**：SystemCapability.Security.Huks -## huks.importWrappedKeyItem9+ +| 名称 | 值 | 说明 | +| -------------------- | ---- | ----------------- | +| HUKS_SEND_TYPE_ASYNC | 0 | 表示异步发送TAG。 | +| HUKS_SEND_TYPE_SYNC | 1 | 表示同步发送TAG。 | -importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions) : Promise\ +## HuksUnwrapSuite9+ -导入加密密钥，使用Promise方式异步返回结果。 +表示导入加密密钥的算法套件。 **系统能力**：SystemCapability.Security.Huks -**参数：** +| 名称 | 值 | 说明 | +| ---------------------------------------------- | ---- | ----------------------------------------------------- | +| HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING | 1 | 导入加密密钥时，X25519密钥协商后使用AES-256 GCM加密。 | +| HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING | 2 | 导入加密密钥时，ECDH密钥协商后使用AES-256 GCM加密。 | -| 参数名 | 类型 | 必填 | 说明 | -| ---------------- | --------------------------- | ---- | --------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，存放待导入密钥的别名。 | -| wrappingKeyAlias | string | 是 | 密钥别名，对应密钥用于解密加密的密钥数据。 | -| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的加密的密钥数据。 | +## HuksImportKeyType9+ -**示例：** +表示导入密钥的密钥类型，默认为导入公钥，导入对称密钥时不需要该字段。 -```js -/* 处理流程与callback类似，主要差异点为如下函数： */ -async function TestImportWrappedFunc(alias, wrappingAlias, options) { - try { - await huks.importWrappedKeyItem(alias, wrappingAlias, options) - .then ((data) => { - console.info(`promise: importWrappedKeyItem success`); - }) - .catch(error => { - console.error(`promise: importWrappedKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: importWrappedKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } -} -``` +**系统能力**：SystemCapability.Security.Huks -## huks.exportKey(deprecated) +| 名称 | 值 | 说明 | +| ------------------------- | ---- | ------------------------------ | +| HUKS_KEY_TYPE_PUBLIC_KEY | 0 | 表示导入的密钥类型为公钥。 | +| HUKS_KEY_TYPE_PRIVATE_KEY | 1 | 表示导入的密钥类型为私钥。 | +| HUKS_KEY_TYPE_KEY_PAIR | 2 | 表示导入的密钥类型为公私钥对。 | -exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +## HuksUserAuthType9+ -导出密钥，使用Callback方式回调异步返回的结果。 +表示用户认证类型。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9)替代。 +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ------------------------------- | ---- | ------------------------- | +| HUKS_USER_AUTH_TYPE_FINGERPRINT | 1 | 表示用户认证类型为指纹。 | +| HUKS_USER_AUTH_TYPE_FACE | 2 | 表示用户认证类型为人脸 。 | +| HUKS_USER_AUTH_TYPE_PIN | 4 | 表示用户认证类型为PIN码。 | + +## HuksAuthAccessType9+ + +表示安全访问控制类型。 **系统能力**：SystemCapability.Security.Huks -**参数：** +| 名称 | 值 | 说明 | +| --------------------------------------- | ---- | ------------------------------------------------ | +| HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | 1 | 表示安全访问控制类型为清除密码后密钥无效。 | +| HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | 2 | 表示安全访问控制类型为新录入生物特征后密钥无效。 | -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | +## HuksChallengeType9+ -**示例：** +表示密钥使用时生成challenge的类型。 -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -huks.exportKey(keyAlias, emptyOptions, function (err, data){}); -``` +**系统能力**：SystemCapability.Security.Huks -## huks.exportKey(deprecated) +| 名称 | 值 | 说明 | +| ------------------------------- | ---- | ------------------------------ | +| HUKS_CHALLENGE_TYPE_NORMAL | 0 | 表示challenge为普通类型，默认32字节。 | +| HUKS_CHALLENGE_TYPE_CUSTOM | 1 | 表示challenge为用户自定义类型。支持使用多个密钥仅一次认证。 | +| HUKS_CHALLENGE_TYPE_NONE | 2 | 表示免challenge类型。 | -exportKey(keyAlias: string, options: HuksOptions) : Promise\ +## HuksChallengePosition9+ -导出密钥，使用Promise方式回调异步返回的结果。 +表示challenge类型为用户自定义类型时，生成的challenge有效长度仅为8字节连续的数据，且仅支持4种位置 。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9-1))替代。 +**系统能力**：SystemCapability.Security.Huks + +| 名称 | 值 | 说明 | +| ------------------------------- | ---- | ------------------------------ | +| HUKS_CHALLENGE_POS_0 | 0 | 表示0~7字节为当前密钥的有效challenge。 | +| HUKS_CHALLENGE_POS_1 | 1 | 表示8~15字节为当前密钥的有效challenge。 | +| HUKS_CHALLENGE_POS_2 | 2 | 表示16~23字节为当前密钥的有效challenge。 | +| HUKS_CHALLENGE_POS_3 | 3 | 表示24~31字节为当前密钥的有效challenge。 | + +## HuksSecureSignType9+ + +表示生成或导入密钥时，指定该密钥的签名类型。 **系统能力**：SystemCapability.Security.Huks -**参数：** +| 名称 | 值 | 说明 | +| ------------------------------ | ---- | ------------------------------------------------------------ | +| HUKS_SECURE_SIGN_WITH_AUTHINFO | 1 | 表示签名类型为携带认证信息。生成或导入密钥时指定该字段，则在使用密钥进行签名时，对待签名的数据添加认证信息后进行签名。 | -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +## HuksTagType -**返回值：** +表示Tag的数据类型。 -| 类型 | 说明 | -| ----------------------------------- | ------------------------------------------------------------ | -| Promise\<[HuksResult](#huksresult)> | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | +**系统能力**：SystemCapability.Security.Huks -**示例：** +| 名称 | 值 | 说明 | +| --------------------- | ------- | --------------------------------------- | +| HUKS_TAG_TYPE_INVALID | 0 << 28 | 表示非法的Tag类型。 | +| HUKS_TAG_TYPE_INT | 1 << 28 | 表示该Tag的数据类型为int类型的number。 | +| HUKS_TAG_TYPE_UINT | 2 << 28 | 表示该Tag的数据类型为uint类型的number。 | +| HUKS_TAG_TYPE_ULONG | 3 << 28 | 表示该Tag的数据类型为bigint。 | +| HUKS_TAG_TYPE_BOOL | 4 << 28 | 表示该Tag的数据类型为boolean。 | +| HUKS_TAG_TYPE_BYTES | 5 << 28 | 表示该Tag的数据类型为Uint8Array。 | -```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] -}; -var result = huks.exportKey(keyAlias, emptyOptions); -``` +## HuksTag -## huks.exportKeyItem9+ +表示调用参数的Tag。 -exportKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +**系统能力**：SystemCapability.Security.Huks -导出密钥，使用Callback方式回调异步返回的结果。 +| 名称 | 值 | 说明 | +| -------------------------------------------- | ---------------------------------------- | -------------------------------------- | +| HUKS_TAG_INVALID | HuksTagType.HUKS_TAG_TYPE_INVALID \| 0 | 表示非法的Tag。 | +| HUKS_TAG_ALGORITHM | HUKS_TAG_TYPE_UINT \| 1 | 表示算法的Tag。 | +| HUKS_TAG_PURPOSE | HuksTagType.HUKS_TAG_TYPE_UINT \| 2 | 表示密钥用途的Tag。 | +| HUKS_TAG_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 3 | 表示密钥长度的Tag。 | +| HUKS_TAG_DIGEST | HuksTagType.HUKS_TAG_TYPE_UINT \| 4 | 表示摘要算法的Tag。 | +| HUKS_TAG_PADDING | HuksTagType.HUKS_TAG_TYPE_UINT \| 5 | 表示补齐算法的Tag。 | +| HUKS_TAG_BLOCK_MODE | HuksTagType.HUKS_TAG_TYPE_UINT \| 6 | 表示加密模式的Tag。 | +| HUKS_TAG_KEY_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 7 | 表示密钥类型的Tag。 | +| HUKS_TAG_ASSOCIATED_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 8 | 表示附加身份验证数据的Tag。 | +| HUKS_TAG_NONCE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 9 | 表示密钥加解密的字段。 | +| HUKS_TAG_IV | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10 | 表示密钥初始化的向量。 | +| HUKS_TAG_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 11 | 表示密钥派生时的info。 | +| HUKS_TAG_SALT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 12 | 表示密钥派生时的盐值。 | +| HUKS_TAG_PWD | HuksTagType.HUKS_TAG_TYPE_BYTES \| 13 | 表示密钥派生时的password。 | +| HUKS_TAG_ITERATION | HuksTagType.HUKS_TAG_TYPE_UINT \| 14 | 表示密钥派生时的迭代次数。 | +| HUKS_TAG_KEY_GENERATE_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 15 | 表示生成密钥类型的Tag。 | +| HUKS_TAG_DERIVE_MAIN_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 16 | 表示密钥派生时的主密钥。 | +| HUKS_TAG_DERIVE_FACTOR | HuksTagType.HUKS_TAG_TYPE_BYTES \| 17 | 表示密钥派生时的派生因子。 | +| HUKS_TAG_DERIVE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 18 | 表示密钥派生时的算法类型。 | +| HUKS_TAG_AGREE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 19 | 表示密钥协商时的算法类型。 | +| HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 20 | 表示密钥协商时的公钥别名。 | +| HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 21 | 表示密钥协商时的私钥别名。 | +| HUKS_TAG_AGREE_PUBLIC_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 22 | 表示密钥协商时的公钥。 | +| HUKS_TAG_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 23 | 表示密钥别名。 | +| HUKS_TAG_DERIVE_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 24 | 表示派生密钥的大小。 | +| HUKS_TAG_IMPORT_KEY_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 25 | 表示导入的密钥类型。 | +| HUKS_TAG_UNWRAP_ALGORITHM_SUITE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 26 | 表示导入加密密钥的套件。 | +| HUKS_TAG_ACTIVE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 201 | 预留。 | +| HUKS_TAG_ORIGINATION_EXPIRE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 202 | 预留。 | +| HUKS_TAG_USAGE_EXPIRE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 203 | 预留。 | +| HUKS_TAG_CREATION_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 204 | 预留。 | +| HUKS_TAG_ALL_USERS | ksTagType.HUKS_TAG_TYPE_BOOL \| 301 | 预留。 | +| HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | 预留。 | +| HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | 预留。 | +| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | 表示用户认证类型。从[HuksUserAuthType](#huksuserauthtype9)中选择，需要与安全访问控制类型同时设置。支持同时指定两种用户认证类型，如：安全访问控制类型指定为HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL时，密钥访问认证类型可以指定以下三种： HKS_USER_AUTH_TYPE_FACE 、HKS_USER_AUTH_TYPE_FINGERPRINT、HKS_USER_AUTH_TYPE_FACE \| HKS_USER_AUTH_TYPE_FINGERPRINT | +| HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | 预留。 | +| HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | 预留。 | +| HUKS_TAG_KEY_AUTH_ACCESS_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 307 | 表示安全访问控制类型。从[HuksAuthAccessType](#huksauthaccesstype9)中选择，需要和用户认证类型同时设置。 | +| HUKS_TAG_KEY_SECURE_SIGN_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 308 | 表示生成或导入密钥时，指定该密钥的签名类型。 | +| HUKS_TAG_CHALLENGE_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 309 | 表示密钥使用时生成的challenge类型。从[HuksChallengeType](#hukschallengetype9)中选择 | +| HUKS_TAG_CHALLENGE_POS9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 310 | 表示challenge类型为用户自定义类型时，huks产生的challenge有效长度仅为8字节连续的数据。从[HuksChallengePosition](#hukschallengeposition9)中选择。 | +| HUKS_TAG_ATTESTATION_CHALLENGE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 501 | 表示attestation时的挑战值。 | +| HUKS_TAG_ATTESTATION_APPLICATION_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 502 | 表示attestation时拥有该密钥的application的Id。 | +| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | 表示设备的品牌。 | +| HUKS_TAG_ATTESTATION_ID_DEVICE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 504 | 表示设备的设备ID。 | +| HUKS_TAG_ATTESTATION_ID_PRODUCT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 505 | 表示设备的产品名。 | +| HUKS_TAG_ATTESTATION_ID_SERIAL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 506 | 表示设备的SN号。 | +| HUKS_TAG_ATTESTATION_ID_IMEI | HuksTagType.HUKS_TAG_TYPE_BYTES \| 507 | 表示设备的IMEI号。 | +| HUKS_TAG_ATTESTATION_ID_MEID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 508 | 表示设备的MEID号。 | +| HUKS_TAG_ATTESTATION_ID_MANUFACTURER | HuksTagType.HUKS_TAG_TYPE_BYTES \| 509 | 表示设备的制造商。 | +| HUKS_TAG_ATTESTATION_ID_MODEL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 510 | 表示设备的型号。 | +| HUKS_TAG_ATTESTATION_ID_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 511 | 表示attestation时的密钥别名。 | +| HUKS_TAG_ATTESTATION_ID_SOCID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 512 | 表示设备的SOCID。 | +| HUKS_TAG_ATTESTATION_ID_UDID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 513 | 表示设备的UDID。 | +| HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 514 | 表示attestation时的安全凭据。 | +| HUKS_TAG_ATTESTATION_ID_VERSION_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 515 | 表示attestation时的版本号。 | +| HUKS_TAG_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1001 | 表示是否使用生成key时传入的别名的Tag。 | +| HUKS_TAG_KEY_STORAGE_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1002 | 表示密钥存储方式的Tag。 | +| HUKS_TAG_IS_ALLOWED_WRAP | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1003 | 预留。 | +| HUKS_TAG_KEY_WRAP_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1004 | 预留。 | +| HUKS_TAG_KEY_AUTH_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1005 | 预留。 | +| HUKS_TAG_KEY_ROLE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1006 | 预留。 | +| HUKS_TAG_KEY_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1007 | 表示密钥标志的Tag。 | +| HUKS_TAG_IS_ASYNCHRONIZED | HuksTagType.HUKS_TAG_TYPE_UINT \| 1008 | 预留。 | +| HUKS_TAG_SECURE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1009 | 预留。 | +| HUKS_TAG_SECURE_KEY_UUID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1010 | 预留。 | +| HUKS_TAG_KEY_DOMAIN | HuksTagType.HUKS_TAG_TYPE_UINT \| 1011 | 预留。 | +| HUKS_TAG_PROCESS_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10001 | 表示进程名称的Tag。 | +| HUKS_TAG_PACKAGE_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10002 | 预留。 | +| HUKS_TAG_ACCESS_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10003 | 预留。 | +| HUKS_TAG_USES_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10004 | 预留。 | +| HUKS_TAG_CRYPTO_CTX | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10005 | 预留。 | +| HUKS_TAG_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10006 | 预留。 | +| HUKS_TAG_KEY_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10007 | 表示密钥版本的Tag。 | +| HUKS_TAG_PAYLOAD_LEN | HuksTagType.HUKS_TAG_TYPE_UINT \| 10008 | 预留。 | +| HUKS_TAG_AE_TAG | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10009 | 预留。 | +| HUKS_TAG_IS_KEY_HANDLE | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10010 | 预留。 | +| HUKS_TAG_OS_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10101 | 表示操作系统版本的Tag。 | +| HUKS_TAG_OS_PATCHLEVEL | HuksTagType.HUKS_TAG_TYPE_UINT \| 10102 | 表示操作系统补丁级别的Tag。 | +| HUKS_TAG_SYMMETRIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20001 | 预留。 | +| HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20002 | 预留。 | +| HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20003 | 预留。 | + +## huks.generateKey(deprecated) + +generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +生成密钥，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9)替代。 **系统能力**：SystemCapability.Security.Huks -**参数：** +**参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其余结果请参考HuksResult进行错误码查询。 | **示例：** ```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] +/* 以生成RSA512密钥为例 */ +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512 }; -try { - huks.exportKeyItem(keyAlias, emptyOptions, function (error, data) { - if (error) { - console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); - } - }); -} catch (error) { - console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); -} +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_OAEP +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 +}; +let options = { + properties: properties +}; +huks.generateKey(keyAlias, options, function (err, data){}); ``` -## huks.exportKeyItem9+ +## huks.generateKey(deprecated) -exportKeyItem(keyAlias: string, options: HuksOptions) : Promise\ +generateKey(keyAlias: string, options: HuksOptions) : Promise\ -导出密钥，使用Promise方式回调异步返回的结果。 +生成密钥，使用Promise方式异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.generateKeyItem9+](#huksgeneratekeyitem9-1)替代。 **系统能力**：SystemCapability.Security.Huks -**参数：** +**参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | -------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------ | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于存放生成key所需TAG。 | -**返回值：** +**返回值**： -| 类型 | 说明 | -| ---------------------------------------------- | ------------------------------------------------------------ | -| Promise<[HuksReturnResult](#huksreturnresult)> | 不返回err值时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] +/* 以生成ECC256密钥为例 */ +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC }; -try { - huks.exportKeyItem(keyAlias, emptyOptions) - .then ((data) => { - console.info(`promise: exportKeyItem success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); -} catch (error) { - console.error(`promise: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); -} +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 +}; +let options = { + properties: properties +}; +let result = huks.generateKey(keyAlias, options); ``` -## huks.getKeyProperties(deprecated) -getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +## huks.deleteKey(deprecated) -获取密钥属性，使用Callback回调异步返回结果。 +deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9)替代。 +删除密钥，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | -------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { +/* 此处options选择emptyOptions传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { properties: [] }; -huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){}); +huks.deleteKey(keyAlias, emptyOptions, function (err, data) {}); ``` -## huks.getKeyProperties(deprecated) +## huks.deleteKey(deprecated) -getKeyProperties(keyAlias: string, options: HuksOptions) : Promise\ +deleteKey(keyAlias: string, options: HuksOptions) : Promise\ -获取密钥属性，使用Promise回调异步返回结果。 +删除密钥，使用Promise方式异步返回结果。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1)替代。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.deleteKeyItem9+](#huksdeletekeyitem9-1)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ----------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名，应为生成key时传入的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | **返回值：** -| 类型 | 说明 | -| ------------------ | ------------------------------------------------------------ | -| Promise\<[HuksResult](#huksoptions)> | errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { +/* 此处options选择emptyOptions传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { properties: [] }; -var result = huks.getKeyProperties(keyAlias, emptyOptions); +let result = huks.deleteKey(keyAlias, emptyOptions); ``` -## huks.getKeyItemProperties9+ -getKeyItemProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +## huks.importKey(deprecated) -获取密钥属性，使用Callback回调异步返回结果。 +importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +导入明文密钥，使用Callback方式回调异步返回结果 。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | ------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] +/* 以导入AES256密钥为例 */ +let plainTextSize32 = makeRandomArr(32); +function makeRandomArr(size) { + let arr = new Uint8Array(size); + for (let i = 0; i < size; i++) { + arr[i] = Math.floor(Math.random() * 10); + } + return arr; }; -try { - huks.getKeyItemProperties(keyAlias, emptyOptions, function (error, data) { - if (error) { - console.error(`callback: getKeyItemProperties failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: getKeyItemProperties success, data = ${JSON.stringify(data)}`); - } - }); -} catch (error) { - console.error(`callback: getKeyItemProperties input arg invalid, code: ${error.code}, msg: ${error.message}`); -} +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: +huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +let options = { + properties: properties, + inData: plainTextSize32 +}; +huks.importKey(keyAlias, options, function (err, data){}); ``` -## huks.getKeyItemProperties9+ +## huks.importKey(deprecated) -getKeyItemProperties(keyAlias: string, options: HuksOptions) : Promise\ +importKey(keyAlias: string, options: HuksOptions) : Promise\ -获取密钥属性，使用Promise回调异步返回结果。 +导入明文密钥，使用Promise方式异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.importKeyItem9+](#huksimportkeyitem9-1)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | -------------------------------------------- | -| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------ | +| keyAlias | string | 是 | 密钥别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 用于导入时所需TAG和需要导入的密钥。 | **返回值：** -| 类型 | 说明 | -| ----------------------------------------------- | ------------------------------------------------------------ | -| Promise\<[HuksReturnResult](#huksreturnresult)> | 不返回err值时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** ```js -/* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] +/* 以导入AES128为例 */ +let plainTextSize32 = makeRandomArr(32); + +function makeRandomArr(size) { + let arr = new Uint8Array(size); + for (let i = 0; i < size; i++) { + arr[i] = Math.floor(Math.random() * 10); + } + return arr; }; -try { - huks.getKeyItemProperties(keyAlias, emptyOptions) - .then ((data) => { - console.info(`promise: getKeyItemProperties success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: getKeyItemProperties failed, code: ${error.code}, msg: ${error.message}`); - }); -} catch (error) { - console.error(`promise: getKeyItemProperties input arg invalid, code: ${error.code}, msg: ${error.message}`); -} + +/*第一步：生成密钥*/ +let keyAlias = 'keyAlias'; +let properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value:huks.HuksKeyPadding.HUKS_PADDING_PKCS7 +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +let huksoptions = { + properties: properties, + inData: plainTextSize32 +}; +let result = huks.importKey(keyAlias, huksoptions); ``` -## huks.isKeyExist(deprecated) -isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +## huks.exportKey(deprecated) + +exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +导出密钥，使用Callback方式回调异步返回的结果。 -判断密钥是否存在，使用Callback回调异步返回结果 。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| keyAlias | string | 是 | 所需查找的密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\ | 是 | FALSE代表密钥不存在，TRUE代表密钥存在。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | **示例：** ```js /* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { +let keyAlias = 'keyAlias'; +let emptyOptions = { properties: [] }; -huks.isKeyExist(keyAlias, emptyOptions, function (err, data){}); +huks.exportKey(keyAlias, emptyOptions, function (err, data){}); ``` -## huks.isKeyExist(deprecated) +## huks.exportKey(deprecated) -isKeyExist(keyAlias: string, options: HuksOptions) : Promise\ +exportKey(keyAlias: string, options: HuksOptions) : Promise\ -判断密钥是否存在，使用Promise回调异步返回结果 。 +导出密钥，使用Promise方式回调异步返回的结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.exportKeyItem9+](#huksexportkeyitem9-1))替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | -------------------------------- | -| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | | options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | **返回值：** -| 类型 | 说明 | -| ----------------- | --------------------------------------- | -| Promise\ | FALSE代表密钥不存在，TRUE代表密钥存在。 | +| 类型 | 说明 | +| ----------------------------------- | ------------------------------------------------------------ | +| Promise\<[HuksResult](#huksresult)> | Promise对象。返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥。 | **示例：** ```js /* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { +let keyAlias = 'keyAlias'; +let emptyOptions = { properties: [] }; -var result = huks.isKeyExist(keyAlias, emptyOptions); +let result = huks.exportKey(keyAlias, emptyOptions); ``` -## huks.isKeyItemExist9+ -isKeyItemExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void +## huks.getKeyProperties(deprecated) -判断密钥是否存在，使用Callback回调异步返回结果 。 +getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +获取密钥属性，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------- | -| keyAlias | string | 是 | 所需查找的密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -| callback | AsyncCallback\ | 是 | FALSE代表密钥不存在，TRUE代表密钥存在。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | **示例：** ```js /* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] }; -try { - huks.isKeyItemExist(keyAlias, emptyOptions, function (error, data) { - if (error) { - console.info(`callback: isKeyItemExist success, data = ${JSON.stringify(data)}`); - } else { - console.error(`callback: isKeyItemExist failed, code: ${error.code}, msg: ${error.message}`); - } - }); -} catch (error) { - console.error(`promise: isKeyItemExist input arg invalid, code: ${error.code}, msg: ${error.message}`); -} +huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){}); ``` -## huks.isKeyItemExist9+ +## huks.getKeyProperties(deprecated) -isKeyItemExist(keyAlias: string, options: HuksOptions) : Promise\ +getKeyProperties(keyAlias: string, options: HuksOptions) : Promise\ -判断密钥是否存在，使用Promise回调异步返回结果 。 +获取密钥属性，使用Promise回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------ | -| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | 密钥别名，应与所用密钥生成时使用的别名相同。 | | options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | **返回值：** -| 类型 | 说明 | -| ----------------- | --------------------------------------- | -| Promise\ | FALSE代表密钥不存在，TRUE代表密钥存在。 | +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise\<[HuksResult](#huksoptions)> | Promise对象。errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。properties：返回值为生成密钥时所需参数。 | **示例：** ```js /* 此处options选择emptyOptions来传空 */ -var keyAlias = 'keyAlias'; -var emptyOptions = { - properties: [] +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] }; -try { - huks.isKeyItemExist(keyAlias, emptyOptions) - .then ((data) => { - console.info(`promise: isKeyItemExist success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: isKeyItemExist failed, code: ${error.code}, msg: ${error.message}`); - }); -} catch (error) { - console.error(`promise: isKeyItemExist input arg invalid, code: ${error.code}, msg: ${error.message}`); -} +let result = huks.getKeyProperties(keyAlias, emptyOptions); ``` -## huks.init(deprecated) - -init(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -init操作密钥接口，使用Callback回调异步返回结果 。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 - -系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| keyAlias | string | 是 | Init操作密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | Init操作的参数集合。 | -| callback | AsyncCallback\<[HuksHandle](#hukshandle)> | 是 | 将Init操作操作返回的handle添加到密钥管理系统的回调。 | - -## huks.init(deprecated) +## huks.isKeyExist(deprecated) -init(keyAlias: string, options: HuksOptions) : Promise\ +isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -init操作密钥接口，使用Promise方式异步返回结果。 +判断密钥是否存在，使用Callback回调异步返回结果 。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.isKeyItemExist9+](#huksiskeyitemexist9)替代。 -系统能力**：SystemCapability.Security.Huks +**系统能力**：SystemCapability.Security.Huks **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------- | ---- | ------------------------------------- | -| keyAlias | string | 是 | Init操作密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | Init参数集合。 | -| promise | Promise\<[HuksHandle](#hukshandle)> | 是 | 将Init操作返回的handle添加到密钥管理系统的回调。 | - -## huks.initSession9+ - -initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void - -initSession操作密钥接口，使用Callback回调异步返回结果 。 - -系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ---------------------------------------------------- | -| keyAlias | string | 是 | Init操作密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | Init操作的参数集合。 | -| callback | AsyncCallback\<[HuksSessionHandle](#hukssessionhandle)> | 是 | 将Init操作操作返回的handle添加到密钥管理系统的回调。 | - - -## huks.initSession9+ - -initSession(keyAlias: string, options: HuksOptions) : Promise\ - -initSession操作密钥接口，使用Promise方式异步返回结果。 - -系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------- | ---- | ------------------------------------------------ | -| keyAlias | string | 是 | Init操作密钥的别名。 | -| options | [HuksOptions](#huksoptions) | 是 | Init参数集合。 | -| promise | Promise\<[HuksSessionHandle](#hukssessionhandle)> | 是 | 将Init操作返回的handle添加到密钥管理系统的回调。 | - -## huks.update(deprecated) - -update(handle: number, options: HuksOptions, callback: AsyncCallback\) : void - -update操作密钥接口，使用Callback回调异步返回结果 。 - -**系统能力**：SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Update的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 将Update操作的结果添加到密钥管理系统的回调。 | - -## huks.update(deprecated) - -update(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void - -update操作密钥接口，使用Callback回调异步返回结果 。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9)替代。 - -**系统能力**： SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| token | Uint8Array | 否 | Update操作的token。 | -| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 将Update操作的结果添加到密钥管理系统的回调。 | - -## huks.update(deprecated) - -update(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ - -update操作密钥接口，使用Promise方式异步返回结果。 - -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-1)替代。 - -**系统能力**： SystemCapability.Security.Huks - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ----------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| token | Uint8Array | 否 | Update操作的token。 | -| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | -| promise | Promise\<[HuksResult](#huksresult)> | 是 | 将Update操作的结果添加到密钥管理系统的回调。 | - -## huks.updateSession9+ - -updateSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void - -updateSession操作密钥接口，使用Callback回调异步返回结果 。 - -**系统能力**：SystemCapability.Security.Huks +| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | +| callback | AsyncCallback\ | 是 | 回调函数。FALSE代表密钥不存在，TRUE代表密钥存在。 | -**参数：** +**示例：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Update的参数集合。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 将Update操作的结果添加到密钥管理系统的回调。 | +```js +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +huks.isKeyExist(keyAlias, emptyOptions, function (err, data){}); +``` +## huks.isKeyExist(deprecated) -## huks.updateSession9+ +isKeyExist(keyAlias: string, options: HuksOptions) : Promise\ -updateSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void +判断密钥是否存在，使用Promise回调异步返回结果 。 -updateSession操作密钥接口，使用Callback回调异步返回结果 。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.isKeyItemExist9+](#huksiskeyitemexist9-1)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | -| token | Uint8Array | 是 | Update操作的token。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 将Update操作的结果添加到密钥管理系统的回调。 | - -## huks.updateSession9+ - -updateSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | -------------------------------- | +| keyAlias | string | 是 | 所需查找的密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | 空对象（此处传空即可）。 | -uupdateSession操作密钥接口，使用Promise方式异步返回结果。 +**返回值：** -**系统能力**：SystemCapability.Security.Huks +| 类型 | 说明 | +| ----------------- | --------------------------------------- | +| Promise\ | Promise对象。FALSE代表密钥不存在，TRUE代表密钥存在。 | -**参数：** +**示例：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ---------------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Update操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | -| token | Uint8Array | 否 | Update操作的token。 | -| promise | Promise<[HuksReturnResult](#huksreturnresult)> | 是 | 将Update操作的结果添加到密钥管理系统的回调。 | +```js +/* 此处options选择emptyOptions来传空 */ +let keyAlias = 'keyAlias'; +let emptyOptions = { + properties: [] +}; +let result = huks.isKeyExist(keyAlias, emptyOptions); +``` -## huks.finish(deprecated) +## huks.init(deprecated) -finish(handle: number, options: HuksOptions, callback: AsyncCallback\) : void +init(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void -finish操作密钥接口，使用Callback回调异步返回结果 。 +init操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.finishSession9+](#huksfinishsession9)替代。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 **系统能力**：SystemCapability.Security.Huks @@ -2312,18 +2480,18 @@ finish操作密钥接口，使用Callback回调异步返回结果 。 | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 将Finish操作的结果添加到密钥管理系统的回调。 | +| keyAlias | string | 是 | Init操作密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | Init操作的参数集合。 | +| callback | AsyncCallback\<[HuksHandle](#hukshandle)> | 是 | 回调函数。将Init操作操作返回的handle添加到密钥管理系统的回调。 | -## huks.finish(deprecated) +## huks.init(deprecated) -finish(handle: number, options: HuksOptions) : Promise\ +init(keyAlias: string, options: HuksOptions) : Promise\ -finish操作密钥接口，使用Promise方式异步返回结果。 +init操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksfinishsession9-1)替代。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.initSession9+](#huksinitsession9-1)替代。 **系统能力**：SystemCapability.Security.Huks @@ -2331,180 +2499,85 @@ finish操作密钥接口，使用Promise方式异步返回结果。 | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish操作的参数集合。 | -| promise | Promise\<[HuksResult](#huksresult)> | 是 | promise实例，用于获取异步返回结果。 | - -## huks.finishSession9+ - -finishSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void +| keyAlias | string | 是 | Init操作密钥的别名。 | +| options | [HuksOptions](#huksoptions) | 是 | Init参数集合。 | -finishSession操作密钥接口，使用Callback回调异步返回结果 。 +**返回值**： -**系统能力**：SystemCapability.Security.Huks +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksHandle](#hukshandle)> | Promise对象。将Init操作返回的handle添加到密钥管理系统的回调。 | -**参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | -| token | Uint8Array | 是 | Finish操作的token。 | -| callback | AsyncCallback<[HuksReturnResult](#huksreturnresult)> | 是 | 将Finish操作的结果添加到密钥管理系统的回调。 | +## huks.update(deprecated) -## huks.finishSession9+ +update(handle: number, options: HuksOptions, callback: AsyncCallback\) : void -finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void +update操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 -finishSession操作密钥接口，使用Callback回调异步返回结果 。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------------------- | ---- | -------------------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | -| token | Uint8Array | 是 | Finish操作的token。 | -| callback | AsyncCallback\<[HuksReturnResult](#huksreturnresult)> | 是 | 将Finish操作的结果添加到密钥管理系统的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Update的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | +## huks.update(deprecated) -## huks.finishSession9+ +update(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void -finishSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ +update操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 -finishSession操作密钥接口，使用Promise方式异步返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-1)替代。 -**系统能力**：SystemCapability.Security.Huks +**系统能力**： SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ----------------------------------------------- | ---- | ----------------------------------- | -| handle | number | 是 | Finish操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Finish操作的参数集合。 | -| token | Uint8Array | 否 | Finish操作的token。 | -| promise | Promise\<[HuksReturnResult](#huksreturnresult)> | 是 | promise实例，用于获取异步返回结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| token | Uint8Array | 否 | Update操作的token。 | +| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Update操作的结果添加到密钥管理系统的回调。 | -## huks.abort(deprecated) +## huks.update(deprecated) -abort(handle: number, options: HuksOptions, callback: AsyncCallback\) : void +update(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ -abort操作密钥接口，使用Callback回调异步返回结果 。 +update操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 -> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9)替代。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksupdatesession9-2)替代。 -**系统能力**：SystemCapability.Security.Huks +**系统能力**： SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 将Abort操作的结果添加到密钥管理系统的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------- | ---- | -------------------------------------------- | +| handle | number | 是 | Update操作的handle。 | +| token | Uint8Array | 否 | Update操作的token。 | +| options | [HuksOptions](#huksoptions) | 是 | Update操作的参数集合。 | -**示例：** +**返回值**： -```js -/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update - * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 - * - * 以下以RSA1024密钥的callback操作使用为例 - */ -var keyalias = "HuksDemoRSA"; -var properties = new Array(); -var options = { - properties: properties, - inData: new Uint8Array(0) -}; -var handle; -var resultMessage = ""; -async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_OAEP - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - huks.generateKey(keyalias, options); -} -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} -async function huksInit() { - await huks.init(keyalias, options).then((data) => { - console.log(`test init data: ${JSON.stringify(data)}`); - handle = data.handle; - }).catch((err) => { - console.log("test init err information: " + JSON.stringify(err)) - }) -} -async function huksUpdate() { - options.inData = stringToUint8Array("huksHmacTest"); - await huks.update(handle, options).then((data) => { - if (data.errorCode === 0) { - resultMessage += "update success!"; - } else { - resultMessage += "update fail!"; - } - }); - console.log(resultMessage); -} -function huksFinish() { - options.inData = stringToUint8Array("HuksDemoHMAC"); - huks.finish(handle, options).then((data) => { - if (data.errorCode === 0) { - resultMessage = "finish success!"; - } else { - resultMessage = "finish fail errorCode: " + data.errorCode; - } - }).catch((err) => { - resultMessage = "finish fail， catch errorMessage:" + JSON.stringify(err) - }); - console.log(resultMessage); -} -async function huksAbort() { - huks.abort(handle, options).then((data) => { - if (data.errorCode === 0) { - resultMessage = "abort success!"; - } else { - resultMessage = "abort fail errorCode: " + data.errorCode; - } - }).catch((err) => { - resultMessage = "abort fail， catch errorMessage:" + JSON.stringify(err) - }); - console.log(resultMessage); -} -``` +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。将Update操作的结果添加到密钥管理系统的回调。 | -## huks.abort(deprecated) -abort(handle: number, options: HuksOptions) : Promise\; +## huks.finish(deprecated) -abort操作密钥接口，使用Promise方式异步返回结果。 +finish(handle: number, options: HuksOptions, callback: AsyncCallback\) : void -> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9-1)替代。 +finish操作密钥接口，使用Callback回调异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.finishSession9+](#huksfinishsession9)替代。 **系统能力**：SystemCapability.Security.Huks @@ -2512,420 +2585,268 @@ abort操作密钥接口，使用Promise方式异步返回结果。 | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -| promise | Promise\<[HuksResult](#huksresult)> | 是 | 将Abort操作的结果添加到密钥管理系统的回调。 | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Finish操作的结果添加到密钥管理系统的回调。 | -**示例：** -```js -/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update - * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 - * - * 以下以RSA1024密钥的promise操作使用为例 - */ -var keyalias = "HuksDemoRSA"; -var properties = new Array(); -var options = { - properties: properties, - inData: new Uint8Array(0) -}; -var handle; -var resultMessage = ""; -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} +## huks.finish(deprecated) -async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_OAEP - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - huks.generateKey(keyalias, options, function (err, data) { }); -} -async function huksInit() { - return new Promise((resolve, reject) => { - huks.init(keyalias, options, async function (err, data) { - if (data.errorCode === 0) { - resultMessage = "init success!" - handle = data.handle; - } else { - resultMessage = "init fail errorCode: " + data.errorCode - } - }); - }); -} +finish(handle: number, options: HuksOptions) : Promise\ -async function huksUpdate() { - options.inData = stringToUint8Array("huksHmacTest"); - new Promise((resolve, reject) => { - huks.update(handle, options, function (err, data) { - if (data.errorCode === 0) { - resultMessage += "update success!"; - } else { - resultMessage += "update fail!"; - } - }); - }); - console.log(resultMessage); +finish操作密钥接口，使用Promise方式异步返回结果。huks.init, huks.update, huks.finish为三段式接口，需要一起使用。 -} +> **说明：** 从API Version 9开始废弃，建议使用[huks.updateSession9+](#huksfinishsession9-1)替代。 -async function huksFinish() { - options.inData = stringToUint8Array("0"); - new Promise((resolve, reject) => { - huks.finish(handle, options, function (err, data) { - if (data.errorCode === 0) { - resultMessage = "finish success!"; - } else { - resultMessage = "finish fail errorCode: " + data.errorCode; - } - }); - }); -} +**系统能力**：SystemCapability.Security.Huks + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Finish操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Finish操作的参数集合。 | -function huksAbort() { - new Promise((resolve, reject) => { - huks.abort(handle, options, function (err, data) { - console.log(`Huks_Demo hmac huksAbort1 data ${JSON.stringify(data)}`); - console.log(`Huks_Demo hmac huksAbort1 err ${JSON.stringify(err)}`); - }); - }); -} -``` +**返回值**： -## huks.abortSession9+ +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象，用于获取异步返回结果。 | -abortSession(handle: number, options: HuksOptions, callback: AsyncCallback\) : void -abort操作密钥接口，使用Callback回调异步返回结果 。 +## huks.abort(deprecated) + +abort(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +abort操作密钥接口，使用Callback回调异步返回结果。 + +> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9)替代。 **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -| callback | AsyncCallback\ | 是 | 将Abort操作的结果添加到密钥管理系统的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | 是 | 回调函数。将Abort操作的结果添加到密钥管理系统的回调。 | **示例：** ```js -/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 - * huks.initSession和huks.updateSession - * 以及huks.finishSession操作中的任一阶段发生错误时， - * 都需要调用huks.abortSession来终止密钥的使用。 +/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update + * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 * - * 以下以RSA1024密钥的callback功能使用为例 + * 以下以RSA1024密钥的callback操作使用为例 */ -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -var keyAlias = "HuksDemoRSA"; -var properties = new Array(); -var options = { - properties: properties, - inData: new Uint8Array(0) +let keyalias = "HuksDemoRSA"; +let properties = new Array(); +let options = { + properties: properties, + inData: new Uint8Array(0) }; -var handle; +let handle; +let resultMessage = ""; async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5 - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - properties[5] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB, - } - - try { - await huks.generateKeyItem(keyAlias, options, function (error, data) { - if (error) { - console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: generateKeyItem success`); - } - }); - } catch (error) { - console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_OAEP + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + huks.generateKey(keyalias, options); +} +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + let tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; } - async function huksInit() { - console.log('enter huksInit'); - try { - huks.initSession(keyAlias, options, function (error, data) { - if (error) { - console.error(`callback: initSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: initSession success, data = ${JSON.stringify(data)}`); - handle = data.handle; - } - }); - } catch (error) { - console.error(`callback: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } + await huks.init(keyalias, options).then((data) => { + console.log(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.log("test init err information: " + JSON.stringify(err)) + }) } - async function huksUpdate() { - console.log('enter huksUpdate'); options.inData = stringToUint8Array("huksHmacTest"); - try { - huks.updateSession(handle, options, function (error, data) { - if (error) { - console.error(`callback: updateSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: updateSession success, data = ${JSON.stringify(data)}`); - } - }); - } catch (error) { - console.error(`callback: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } + await huks.update(handle, options).then((data) => { + if (data.errorCode === 0) { + resultMessage += "update success!"; + } else { + resultMessage += "update fail!"; + } + }); + console.log(resultMessage); } - -async function huksFinish() { - console.log('enter huksFinish'); - options.inData = new Uint8Array(0); - try { - huks.finishSession(handle, options, function (error, data) { - if (error) { - console.error(`callback: finishSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: finishSession success, data = ${JSON.stringify(data)}`); - } - }); - } catch (error) { - console.error(`callback: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); +function huksFinish() { + options.inData = stringToUint8Array("HuksDemoHMAC"); + huks.finish(handle, options).then((data) => { + if (data.errorCode === 0) { + resultMessage = "finish success!"; + } else { + resultMessage = "finish fail errorCode: " + data.errorCode; } + }).catch((err) => { + resultMessage = "finish fail， catch errorMessage:" + JSON.stringify(err) + }); + console.log(resultMessage); } - async function huksAbort() { - console.log('enter huksAbort'); - try { - huks.abortSession(handle, options, function (error, data) { - if (error) { - console.error(`callback: abortSession failed, code: ${error.code}, msg: ${error.message}`); - } else { - console.info(`callback: abortSession success`); - } - }); - } catch (error) { - console.error(`callback: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); + huks.abort(handle, options).then((data) => { + if (data.errorCode === 0) { + resultMessage = "abort success!"; + } else { + resultMessage = "abort fail errorCode: " + data.errorCode; } + }).catch((err) => { + resultMessage = "abort fail， catch errorMessage:" + JSON.stringify(err) + }); + console.log(resultMessage); } ``` -## huks.abortSession9+ +## huks.abort(deprecated) -abortSession(handle: number, options: HuksOptions) : Promise\; +abort(handle: number, options: HuksOptions) : Promise\; abort操作密钥接口，使用Promise方式异步返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[huks.abortSession9+](#huksabortsession9-1)替代。 + **系统能力**：SystemCapability.Security.Huks **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | --------------------------- | ---- | ------------------------------------------- | -| handle | number | 是 | Abort操作的handle。 | -| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -| promise | Promise\ | 是 | 将Abort操作的结果添加到密钥管理系统的回调。 | - -**示例：** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| handle | number | 是 | Abort操作的handle。 | +| options | [HuksOptions](#huksoptions) | 是 | Abort操作的参数集合。 | -```js -/* huks.initSession, huks.updateSession, huks.finishSession为三段式接口，需要一起使用，当 - * huks.initSession和huks.updateSession - * 以及huks.finishSession操作中的任一阶段发生错误时， - * 都需要调用huks.abortSession来终止密钥的使用。 - * - * 以下以RSA1024密钥的callback功能使用为例 - */ -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} +**返回值**： -var keyAlias = "HuksDemoRSA"; -var properties = new Array(); -var options = { - properties: properties, - inData: new Uint8Array(0) -}; -var handle; -async function generateKey() { - properties[0] = { - tag: huks.HuksTag.HUKS_TAG_ALGORITHM, - value: huks.HuksKeyAlg.HUKS_ALG_RSA - }; - properties[1] = { - tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, - value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 - }; - properties[2] = { - tag: huks.HuksTag.HUKS_TAG_PURPOSE, - value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT - }; - properties[3] = { - tag: huks.HuksTag.HUKS_TAG_PADDING, - value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5 - }; - properties[4] = { - tag: huks.HuksTag.HUKS_TAG_DIGEST, - value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 - }; - properties[5] = { - tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, - value: huks.HuksCipherMode.HUKS_MODE_ECB, - } +| 类型 | 说明 | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise对象。将Abort操作的结果添加到密钥管理系统的回调。 | - try { - await huks.generateKeyItem(keyAlias, options) - .then((data) => { - console.info(`promise: generateKeyItem success`); - }) - .catch(error => { - console.error(`promise: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); - } +**示例：** + +```js +/* huks.init, huks.update, huks.finish为三段式接口，需要一起使用，当huks.init和huks.update + * 以及huks.finish操作中的任一阶段发生错误时，都需要调用huks.abort来终止密钥的使用。 + * + * 以下以RSA1024密钥的promise操作使用为例 + */ +let keyalias = "HuksDemoRSA"; +let properties = new Array(); +let options = { + properties: properties, + inData: new Uint8Array(0) +}; +let handle; +let resultMessage = ""; +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + let tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; } +async function generateKey() { + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_OAEP + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + huks.generateKey(keyalias, options, function (err, data) { }); +} async function huksInit() { - console.log('enter huksInit'); - try { - await huks.initSession(keyAlias, options) - .then ((data) => { - console.info(`promise: initSession success, data = ${JSON.stringify(data)}`); - handle = data.handle; - }) - .catch(error => { - console.error(`promise: initSession key failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: initSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } + return new Promise((resolve, reject) => { + huks.init(keyalias, options, async function (err, data) { + if (data.errorCode === 0) { + resultMessage = "init success!" + handle = data.handle; + } else { + resultMessage = "init fail errorCode: " + data.errorCode + } + }); + }); } async function huksUpdate() { - console.log('enter huksUpdate'); options.inData = stringToUint8Array("huksHmacTest"); - try { - await huks.updateSession(handle, options) - .then ((data) => { - console.info(`promise: updateSession success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: updateSession failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: updateSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } + new Promise((resolve, reject) => { + huks.update(handle, options, function (err, data) { + if (data.errorCode === 0) { + resultMessage += "update success!"; + } else { + resultMessage += "update fail!"; + } + }); + }); + console.log(resultMessage); + } async function huksFinish() { - console.log('enter huksFinish'); - options.inData = new Uint8Array(0); - try { - await huks.finishSession(handle, options) - .then ((data) => { - console.info(`promise: finishSession success, data = ${JSON.stringify(data)}`); - }) - .catch(error => { - console.error(`promise: finishSession failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: finishSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } + options.inData = stringToUint8Array("0"); + new Promise((resolve, reject) => { + huks.finish(handle, options, function (err, data) { + if (data.errorCode === 0) { + resultMessage = "finish success!"; + } else { + resultMessage = "finish fail errorCode: " + data.errorCode; + } + }); + }); } -async function huksAbort() { - console.log('enter huksAbort'); - try { - await huks.abortSession(keyAlias, options) - .then ((data) => { - console.info(`promise: abortSession success`); - }) - .catch(error => { - console.error(`promise: abortSession failed, code: ${error.code}, msg: ${error.message}`); - }); - } catch (error) { - console.error(`promise: abortSession input arg invalid, code: ${error.code}, msg: ${error.message}`); - } +function huksAbort() { + new Promise((resolve, reject) => { + huks.abort(handle, options, function (err, data) { + console.log(`Huks_Demo hmac huksAbort1 data ${JSON.stringify(data)}`); + console.log(`Huks_Demo hmac huksAbort1 err ${JSON.stringify(err)}`); + }); + }); } ``` -## HuksParam - -调用接口使用的options中的properties数组中的param。 - -**系统能力**：SystemCapability.Security.Huks - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ----------------------------------- | ---- | ------------ | -| tag | [HuksTag](#hukstag) | 是 | 标签。 | -| value | boolean\|number\|bigint\|Uint8Array | 是 | 标签对应值。 | - -## HuksOptions - -调用接口使用的options。 - -**系统能力**：SystemCapability.Security.Huks - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ----------------- | ---- | ------------------------ | -| properties | Array\<[HuksParam](#huksparam)> | 否 | 属性，用于存HuksParam的数组。 | -| inData | Uint8Array | 否 | 输入数据。 | ## HuksHandle(deprecated) @@ -2939,16 +2860,6 @@ huks Handle结构体。 | handle | number | 是 | 表示handle值。 | | token | Uint8Array | 否 | 表示[init](#huksinit)操作之后获取到的challenge信息。 | -## HuksSessionHandle9+ - -huks Handle结构体。 - -**系统能力**：SystemCapability.Security.Huks - -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ---------- | ---- | ---------------------------------------------------- | -| handle | number | 是 | 表示handle值。 | -| challenge | Uint8Array | 否 | 表示[init](#huksinit)操作之后获取到的challenge信息。 | ## HuksResult(deprecated) @@ -2965,16 +2876,86 @@ huks Handle结构体。 | properties | Array\<[HuksParam](#huksparam)> | 否 | 表示属性信息。 | | certChains | Array\ | 否 | 表示证书链数据。 | -## HuksReturnResult9+ - -调用接口返回的result。 -**系统能力**：SystemCapability.Security.Huks +## HuksErrorCode(deprecated) +表示错误码的枚举。 +**系统能力**：SystemCapability.Security.Huks -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------------------- | ---- | ---------------- | -| outData | Uint8Array | 否 | 表示输出数据。 | -| properties | Array\<[HuksParam](#huksparam)> | 否 | 表示属性信息。 | -| certChains | Array\ | 否 | 表示证书链数据。 | \ No newline at end of file +| 名称 | 值 | 说明 | +| -------------------------- | ----- | ---- | +| HUKS_SUCCESS | 0 |表示成功。| +| HUKS_FAILURE | -1 |表示失败。| +| HUKS_ERROR_BAD_STATE | -2 |表示错误的状态。| +| HUKS_ERROR_INVALID_ARGUMENT | -3 |表示无效的数据。| +| HUKS_ERROR_NOT_SUPPORTED | -4 |表示不支持。| +| HUKS_ERROR_NO_PERMISSION | -5 |表示没有许可。| +| HUKS_ERROR_INSUFFICIENT_DATA | -6 |表示数据不足。| +| HUKS_ERROR_BUFFER_TOO_SMALL | -7 |表示缓冲区太小。| +| HUKS_ERROR_INSUFFICIENT_MEMORY | -8 |表示内存不足。| +| HUKS_ERROR_COMMUNICATION_FAILURE | -9 |表示通讯失败。| +| HUKS_ERROR_STORAGE_FAILURE | -10 |表示存储故障。| +| HUKS_ERROR_HARDWARE_FAILURE | -11 |表示硬件故障。| +| HUKS_ERROR_ALREADY_EXISTS | -12 |表示已经存在。| +| HUKS_ERROR_NOT_EXIST | -13 |表示不存在。| +| HUKS_ERROR_NULL_POINTER | -14 |表示空指针。| +| HUKS_ERROR_FILE_SIZE_FAIL | -15 |表示文件大小失败。| +| HUKS_ERROR_READ_FILE_FAIL | -16 |表示读取文件失败。| +| HUKS_ERROR_INVALID_PUBLIC_KEY | -17 |表示无效的公钥。| +| HUKS_ERROR_INVALID_PRIVATE_KEY | -18 |表示无效的私钥。| +| HUKS_ERROR_INVALID_KEY_INFO | -19 |表示无效的密钥信息。| +| HUKS_ERROR_HASH_NOT_EQUAL | -20 |表示哈希不相等。| +| HUKS_ERROR_MALLOC_FAIL | -21 |表示MALLOC 失败。| +| HUKS_ERROR_WRITE_FILE_FAIL | -22 |表示写文件失败。| +| HUKS_ERROR_REMOVE_FILE_FAIL | -23 |表示删除文件失败。| +| HUKS_ERROR_OPEN_FILE_FAIL | -24 |表示打开文件失败。| +| HUKS_ERROR_CLOSE_FILE_FAIL | -25 |表示关闭文件失败。| +| HUKS_ERROR_MAKE_DIR_FAIL | -26 |表示创建目录失败。| +| HUKS_ERROR_INVALID_KEY_FILE | -27 |表示无效的密钥文件。| +| HUKS_ERROR_IPC_MSG_FAIL | -28 |表示IPC 信息失败。| +| HUKS_ERROR_REQUEST_OVERFLOWS | -29 |表示请求溢出。| +| HUKS_ERROR_PARAM_NOT_EXIST | -30 |表示参数不存在。| +| HUKS_ERROR_CRYPTO_ENGINE_ERROR | -31 |表示CRYPTO ENGINE错误。| +| HUKS_ERROR_COMMUNICATION_TIMEOUT | -32 |表示通讯超时。| +| HUKS_ERROR_IPC_INIT_FAIL | -33 |表示IPC 初始化失败。| +| HUKS_ERROR_IPC_DLOPEN_FAIL | -34 |表示IPC DLOPEN 失败。| +| HUKS_ERROR_EFUSE_READ_FAIL | -35 |表示EFUSE 读取失败。| +| HUKS_ERROR_NEW_ROOT_KEY_MATERIAL_EXIST | -36 |表示存在新的根密钥材料。| +| HUKS_ERROR_UPDATE_ROOT_KEY_MATERIAL_FAIL | -37 |表示更新根密钥材料失败。| +| HUKS_ERROR_VERIFICATION_FAILED | -38 |表示验证证书链失败。| +| HUKS_ERROR_GET_USERIAM_SECINFO_FAILED9+ | -40 |表示获取当前用户安全属性信息失败。| +| HUKS_ERROR_GET_USERIAM_AUTHINFO_FAILED9+ | -41 |表示获取当前用户认证信息失败。| +| HUKS_ERROR_USER_AUTH_TYPE_NOT_SUPPORT9+ | -42 |表示不支持当前用户认证类型的访问控制。| +| HUKS_ERROR_KEY_AUTH_FAILED9+ | -43 |表示安全访问控制认证失败。| +| HUKS_ERROR_DEVICE_NO_CREDENTIAL9+ | -44 |表示设备当前未录入凭据。| +| HUKS_ERROR_CHECK_GET_ALG_FAIL | -100 |表示检查获取 ALG 失败。| +| HUKS_ERROR_CHECK_GET_KEY_SIZE_FAIL | -101 |表示检查获取密钥大小失败。| +| HUKS_ERROR_CHECK_GET_PADDING_FAIL | -102 |表示检查获取填充失败。| +| HUKS_ERROR_CHECK_GET_PURPOSE_FAIL | -103 |表示检查获取目的失败。| +| HUKS_ERROR_CHECK_GET_DIGEST_FAIL | -104 |表示检查获取摘要失败。| +| HUKS_ERROR_CHECK_GET_MODE_FAIL | -105 |表示检查获取模式失败。| +| HUKS_ERROR_CHECK_GET_NONCE_FAIL | -106 |表示检查获取随机数失败。| +| HUKS_ERROR_CHECK_GET_AAD_FAIL | -107 |表示检查获取 AAD 失败。| +| HUKS_ERROR_CHECK_GET_IV_FAIL | -108 |表示检查 GET IV 失败。| +| HUKS_ERROR_CHECK_GET_AE_TAG_FAIL | -109 |表示检查获取 AE 标记失败。| +| HUKS_ERROR_CHECK_GET_SALT_FAIL | -110 |表示检查获取SALT失败。| +| HUKS_ERROR_CHECK_GET_ITERATION_FAIL | -111 |表示检查获取迭代失败。| +| HUKS_ERROR_INVALID_ALGORITHM | -112 |表示无效的算法。| +| HUKS_ERROR_INVALID_KEY_SIZE | -113 |表示无效的密钥大小。| +| HUKS_ERROR_INVALID_PADDING | -114 |表示无效的填充。| +| HUKS_ERROR_INVALID_PURPOSE | -115 |表示无效的目的。| +| HUKS_ERROR_INVALID_MODE | -116 |表示无效模式。| +| HUKS_ERROR_INVALID_DIGEST | -117 |表示无效的摘要。| +| HUKS_ERROR_INVALID_SIGNATURE_SIZE | -118 |表示签名大小无效。| +| HUKS_ERROR_INVALID_IV | -119 |表示无效的 IV。| +| HUKS_ERROR_INVALID_AAD | -120 |表示无效的 AAD。| +| HUKS_ERROR_INVALID_NONCE | -121 |表示无效的随机数。| +| HUKS_ERROR_INVALID_AE_TAG | -122 |表示无效的 AE 标签。| +| HUKS_ERROR_INVALID_SALT | -123 |表示无效SALT。| +| HUKS_ERROR_INVALID_ITERATION | -124 |表示无效的迭代。| +| HUKS_ERROR_INVALID_OPERATION | -125 |表示无效操作。| +| HUKS_ERROR_INVALID_WRAPPED_FORMAT9+ | -126 |表示导入加密密钥时，密钥格式错误。| +| HUKS_ERROR_INVALID_USAGE_OF_KEY9+ | -127 |表示导入加密密钥时，密钥用途错误。| +| HUKS_ERROR_INTERNAL_ERROR | -999 |表示内部错误。| +| HUKS_ERROR_UNKNOWN_ERROR | -1000 |表示未知错误。| \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-osAccount.md b/zh-cn/application-dev/reference/apis/js-apis-osAccount.md index 45c3e9c87a3161561339636e34067a4e8a24745d..b8c557185193c2f1ca58fcd399d54a2a69d5a7b1 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-osAccount.md +++ b/zh-cn/application-dev/reference/apis/js-apis-osAccount.md @@ -1,6 +1,6 @@ # 系统帐号管理 -本模块提供管理系统帐号的一些基础能力，包括系统帐号的添加、删除、查询、设置、订阅、启动等功能，提供系统帐号数据落盘的能力。 +本模块提供管理系统帐号的基础能力，包括系统帐号的添加、删除、查询、设置、订阅、启动等功能。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -16,15 +16,15 @@ import account_osAccount from '@ohos.account.osAccount'; getAccountManager(): AccountManager -获取系统帐号能力的实例。 +获取系统帐号管理对象。 **系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| --------------------------------- | ------------------------ | -| [AccountManager](#accountmanager) | 获取系统帐号能力的实例。 | +| 类型 | 说明 | +| --------------------------------- | ---------------- | +| [AccountManager](#accountmanager) | 系统帐号管理对象。 | **示例：** ```js @@ -33,27 +33,27 @@ getAccountManager(): AccountManager ## OsAccountType -枚举，系统帐号类型。 +表示系统帐号类型的枚举。 -**系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount。 +**系统能力：** SystemCapability.Account.OsAccount。 | 参数 | 默认值 | 说明 | -| ------ | ------ | ------------ | +| ------ | ------ | ----------- | | ADMIN | 0 | 管理员帐号。 | | NORMAL | 1 | 普通帐号。 | | GUEST | 2 | 访客帐号。 | ## AccountManager -管理系统帐号能力的类。 +系统帐号管理类。 ### activateOsAccount activateOsAccount(localId: number, callback: AsyncCallback<void>): void -激活指定系统帐号，使用callback回调异步返回结果。 +激活指定系统帐号。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION @@ -61,10 +61,18 @@ activateOsAccount(localId: number, callback: AsyncCallback<void>): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | -------------------- | -| localId | number | 是 | 要激活的系统帐号ID。 | -| callback | AsyncCallback<void> | 是 | 回调结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当帐号激活成功时，err为null，否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | **示例：** 激活ID为100的系统帐号 ```js @@ -72,10 +80,14 @@ activateOsAccount(localId: number, callback: AsyncCallback<void>): void let localId = 100; try { accountManager.activateOsAccount(localId, (err)=>{ - console.log('activateOsAccount err:' + JSON.stringify(err)); + if (err) { + console.log("activateOsAccount failed, error:" + JSON.stringify(err)); + } else { + console.log("activateOsAccount successfully"); + } }); - } catch (e) { - console.log('activateOsAccount exception:' + JSON.stringify(e)); + } catch (err) { + console.log("activateOsAccount exception:" + JSON.stringify(err)); } ``` @@ -83,9 +95,9 @@ activateOsAccount(localId: number, callback: AsyncCallback<void>): void activateOsAccount(localId: number): Promise<void> -激活指定系统帐号，使用Promise方式异步返回结果。 +激活指定系统帐号。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION @@ -95,13 +107,21 @@ activateOsAccount(localId: number): Promise<void> | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | -------------------- | -| localId | number | 是 | 要激活的系统帐号ID。 | +| localId | number | 是 | 系统帐号ID。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :---------------------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :------------------ | :----------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | **示例：** 激活ID为100的系统帐号 ```js @@ -109,240 +129,332 @@ activateOsAccount(localId: number): Promise<void> let localId = 100; try { accountManager.activateOsAccount(localId).then(() => { - console.log('activateOsAccount success'); + console.log('activateOsAccount successfully'); }).catch((err) => { - console.log('activateOsAccount err:' + JSON.stringify(err)); + console.log('activateOsAccount failed, err:' + JSON.stringify(err)); }); } catch (e) { console.log('activateOsAccount exception:' + JSON.stringify(e)); } ``` -### isMultiOsAccountEnabled9+ +### checkMultiOsAccountEnabled9+ -isMultiOsAccountEnabled(callback: AsyncCallback<boolean>): void +checkMultiOsAccountEnabled(callback: AsyncCallback<boolean>): void -判断是否支持多系统帐号，使用callback回调异步返回结果。 +判断是否支持多系统帐号。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | --------------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调结果，支持多系统帐号则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------ | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示支持多系统帐号；返回false表示不支持。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.isMultiOsAccountEnabled((err, isEnabled) => { - console.log('isMultiOsAccountEnabled err: ' + JSON.stringify(err)); - console.log('isMultiOsAccountEnabled isEnabled: ' + isEnabled); + accountManager.checkMultiOsAccountEnabled((err, isEnalbed) => { + if (err) { + console.log("checkMultiOsAccountEnabled failed, error: " + JSON.stringify(err)); + } else { + console.log("checkMultiOsAccountEnabled successfully, isEnabled: " + isEnabled); + } }); - } catch (e) { - console.log('isMultiOsAccountEnabled exception: ' + JSON.stringify(e)); + } catch (err) { + console.log("checkMultiOsAccountEnabled exception: " + JSON.stringify(err)); } ``` -### isMultiOsAccountEnabled9+ +### checkMultiOsAccountEnabled9+ -isMultiOsAccountEnabled(): Promise<boolean> +checkMultiOsAccountEnabled(): Promise<boolean> -判断是否支持多系统帐号，使用Promise方式异步返回结果。 +判断是否支持多系统帐号。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，支持多系统帐号则返回true，否则返回false。 | +| 类型 | 说明 | +| :--------------------- | :--------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示支持多系统帐号；返回false表示不支持。 | **示例：** ```js try { let accountManager = account_osAccount.getAccountManager(); - accountManager.isMultiOsAccountEnabled().then((isEnabled) => { - console.log('isMultiOsAccountEnabled, isEnabled: ' + isEnabled); + accountManager.checkMultiOsAccountEnabled().then((isEnabled) => { + console.log('checkMultiOsAccountEnabled successfully, isEnabled: ' + isEnabled); }).catch((err) => { - console.log('isMultiOsAccountEnabled err: ' + JSON.stringify(err)); + console.log('checkMultiOsAccountEnabled failed, error: ' + JSON.stringify(err)); }); - } catch (e) { - console.log('isMultiOsAccountEnabled exception: ' + JSON.stringify(e)); + } catch (err) { + console.log('checkMultiOsAccountEnabled exception: ' + JSON.stringify(err)); } ``` -### isMultiOsAccountEnable(deprecated) +### checkOsAccountActivated9+ -isMultiOsAccountEnable(callback: AsyncCallback<boolean>): void +checkOsAccountActivated(localId: number, callback: AsyncCallback<boolean>): void -判断是否支持多系统帐号，使用callback回调异步返回结果。 +判断指定系统帐号是否处于激活状态。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[isMultiOsAccountEnabled](#ismultiosaccountenabled9) -> -> 从 API version 7开始支持。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | --------------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调结果，支持多系统帐号则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------ | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示帐号已激活；返回false表示帐号未激活。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 判断ID为100的系统帐号是否处于激活状态 ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isMultiOsAccountEnable((err, isEnabled) => { - console.log('isMultiOsAccountEnable err: ' + JSON.stringify(err)); - console.log('isMultiOsAccountEnable isEnabled: ' + isEnabled); - }); + let osLocalId = 100; + try { + accountManager.checkOsAccountActivated(osLocalId, (err, isActivated)=>{ + if (err) { + console.log('checkOsAccountActivated failed, error:' + JSON.stringify(err)); + } else { + console.log('checkOsAccountActivated successfully, isActivated:' + isActivated); + } + }); + } catch (err) { + console.log('checkOsAccountActivated exception:' + JSON.stringify(err)); + } ``` -### isMultiOsAccountEnable(deprecated) +### checkOsAccountActivated9+ -isMultiOsAccountEnable(): Promise<boolean> +checkOsAccountActivated(localId: number): Promise<boolean> -判断是否支持多系统帐号，使用Promise方式异步返回结果。 +判断指定系统帐号是否处于激活状态。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[isMultiOsAccountEnabled](#ismultiosaccountenabled9-1) -> -> 从 API version 7开始支持。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | --------------------------------- | +| localId | number | 是 | 系统帐号ID。 | + **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，支持多系统帐号则返回true，否则返回false。 | +| 类型 | 说明 | +| ---------------------- | ---------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示帐号已激活；返回false表示帐号未激活。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 判断ID为100的系统帐号是否处于激活状态 ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isMultiOsAccountEnable().then((isEnabled) => { - console.log('isMultiOsAccountEnable, isEnabled: ' + isEnabled); - }).catch((err) => { - console.log('isMultiOsAccountEnable err: ' + JSON.stringify(err)); - }); + let localId = 100; + try { + accountManager.checkOsAccountActivated(localId).then((isActivated) => { + console.log('checkOsAccountActivated successfully, isActivated: ' + isActivated); + }).catch((err) => { + console.log('checkOsAccountActivated failed, error: ' + JSON.stringify(err)); + }); + } catch (err) { + console.log('checkOsAccountActivated exception:' + JSON.stringify(err)); + } ``` -### isOsAccountActivated9+ +### checkConstraintEnabled9+ -isOsAccountActivated(localId: number, callback: AsyncCallback<boolean>): void +checkConstraintEnabled(localId: number, constraint: string, callback: AsyncCallback<boolean>): void -判断指定系统帐号是否处于激活状态，使用callback回调异步返回结果。 +判断指定系统帐号是否具有指定约束。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ------------------------------------------------- | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<boolean> | 是 | 回调结果，处于激活状态则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------- | ---- | ----------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示已使能指定的约束；返回false表示未使能指定的约束。 | -**示例：** 判断ID为100的系统帐号是否处于激活状态 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 ```js let accountManager = account_osAccount.getAccountManager(); - let osLocalId = 100; + let localId = 100; + let constraint = "constraint.wifi"; try { - accountManager.isOsAccountActivated(osLocalId, (err, isActive)=>{ - console.log('isOsAccountActivated err:' + JSON.stringify(err)); - console.log('isOsAccountActivated isActive:' + isActive); + accountManager.checkConstraintEnabled(localId, constraint, (err, isEnabled)=>{ + if (err) { + console.log("checkConstraintEnabled failed, error: " + JSON.stringify(err)); + } else { + console.log("checkConstraintEnabled successfully, isEnabled: " + isEnabled); + } }); - } catch (e) { - console.log('isOsAccountActivated exception:' + JSON.stringify(e)); + } catch (err) { + console.log("checkConstraintEnabled exception: " + JSON.stringify(err)); } ``` -### isOsAccountActivated9+ +### checkConstraintEnabled9+ -isOsAccountActivated(localId: number): Promise<boolean> +checkConstraintEnabled(localId: number, constraint: string): Promise<boolean> -判断指定系统帐号是否处于激活状态，使用Promise方式异步返回结果。 +判断指定系统帐号是否具有指定约束。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ---------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，处于激活状态则返回true，否则返回false。 | +| 类型 | 说明 | +| --------------------- | --------------------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示已使能指定的约束；返回false表示未使能指定的约束。 | -**示例：** 判断ID为100的系统帐号是否处于激活状态 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 ```js let accountManager = account_osAccount.getAccountManager(); - let osLocalId = 100; + let localId = 100; + let constraint = "constraint.wifi"; try { - accountManager.isOsAccountActivated(osLocalId).then((isActive) => { - console.log('isOsAccountActivated, isActive: ' + isActive); + accountManager.checkConstraintEnabled(localId, constraint).then((isEnabled) => { + console.log("checkConstraintEnabled successfully, isEnabled: " + isEnabled); }).catch((err) => { - console.log('isOsAccountActivated err: ' + JSON.stringify(err)); + console.log("checkConstraintEnabled failed, error: " + JSON.stringify(err)); }); - } catch (e) { - console.log('isOsAccountActivated exception:' + JSON.stringify(e)); + } catch (err) { + console.log("checkConstraintEnabled exception: " + JSON.stringify(err)); } ``` -### isOsAccountActived(deprecated) - -isOsAccountActived(localId: number, callback: AsyncCallback<boolean>): void - -判断指定系统帐号是否处于激活状态，使用callback回调异步返回结果。 +### checkOsAccountTestable9+ -> **说明：** 从API version 9开始废弃, 建议使用[isOsAccountActivated](#isosaccountactivated9) -> -> 从 API version 7开始支持。 +checkOsAccountTestable(callback: AsyncCallback<boolean>): void -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS +检查当前系统帐号是否为测试帐号。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ------------------------------------------------- | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<boolean> | 是 | 回调结果，处于激活状态则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | --------------------------------------------------------------------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前帐号为测试帐号；返回false表示当前帐号非测试帐号。 | -**示例：** 判断ID为100的系统帐号是否处于激活状态 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let osLocalId = 100; - accountManager.isOsAccountActived(osLocalId, (err, isActive)=>{ - console.log('isOsAccountActived err:' + JSON.stringify(err)); - console.log('isOsAccountActived isActive:' + isActive); - }); + try { + accountManager.checkOsAccountTestable((err, isTestable) => { + if (err) { + console.log("checkOsAccountTestable failed, error: " + JSON.stringify(err)); + } else { + console.log("checkOsAccountTestable successfully, isTestable: " + isTestable); + } + }); + } catch (err) { + console.log("checkOsAccountTestable error: " + JSON.stringify(err)); + } ``` -### isOsAccountActived(deprecated) +### checkOsAccountTestable9+ -isOsAccountActived(localId: number): Promise<boolean> +checkOsAccountTestable(): Promise<boolean> -判断指定系统帐号是否处于激活状态，使用Promise方式异步返回结果。 +检查当前系统帐号是否为测试帐号。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃, 建议使用[isOsAccountActivated](#isosaccountactivated9-1) -> -> 从 API version 7开始支持。 +**系统能力：** SystemCapability.Account.OsAccount + +**返回值：** + +| 类型 | 说明 | +| ---------------------- | ------------------------------------------------------------------------ | +| Promise<boolean> | Promise对象。返回true表示当前帐号为测试帐号；返回false表示当前帐号非测试帐号。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** + + ```js + let accountManager = account_osAccount.getAccountManager(); + try { + accountManager.checkOsAccountTestable().then((isTestable) => { + console.log("checkOsAccountTestable successfully, isTestable: " + isTestable); + }).catch((err) => { + console.log("checkOsAccountTestable failed, error: " + JSON.stringify(err)); + }); + } catch (err) { + console.log('checkOsAccountTestable exception: ' + JSON.stringify(err)); + } + ``` + +### checkOsAccountVerified9+ + +checkOsAccountVerified(callback: AsyncCallback<boolean>): void + +检查当前系统帐号是否已验证。使用callback异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -350,109 +462,128 @@ isOsAccountActived(localId: number): Promise<boolean> **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前帐号已验证；返回false表示当前帐号未验证。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，处于激活状态则返回true，否则返回false。 | +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | -**示例：** 判断ID为100的系统帐号是否处于激活状态 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let osLocalId = 100; - accountManager.isOsAccountActived(osLocalId).then((isActive) => { - console.log('isOsAccountActived, isActive: ' + isActive); - }).catch((err) => { - console.log('isOsAccountActived err: ' + JSON.stringify(err)); - }); + try { + accountManager.checkOsAccountVerified((err, isVerified) => { + if (err) { + console.log("checkOsAccountVerified failed, error: " + JSON.stringify(err)); + } else { + console.log("checkOsAccountVerified successfully, isVerified: " + isVerified); + } + }); + } catch (err) { + console.log("checkOsAccountVerified exception: " + JSON.stringify(err)); + } ``` -### isConstraintEnabled9+ +### checkOsAccountVerified9+ -isConstraintEnabled(localId: number, constraint: string, callback: AsyncCallback<boolean>): void +checkOsAccountVerified(localId: number, callback: AsyncCallback<boolean>): void -判断指定系统帐号是否具有指定约束，使用callback回调异步返回结果。 +检查指定系统帐号是否已验证。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ---------------------------- | ---- | ------------------------------------------------- | -| localId | number | 是 | 指定的系统帐号ID。 | -| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | -| callback | AsyncCallback<boolean> | 是 | 回调结果，具有指定约束则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------------- | +| localId | number | 否 | 系统帐号ID。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示指定帐号已验证；返回false表示指定帐号未验证。 | -**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; try { - accountManager.isConstraintEnabled(localId, 'constraint.wifi', (err, isEnabled)=>{ - console.log('isConstraintEnabled err:' + JSON.stringify(err)); - console.log('isConstraintEnabled isEnabled:' + isEnabled); + accountManager.checkOsAccountVerified(localId, (err, result) => { + if (err) { + console.log("checkOsAccountVerified failed, error: " + JSON.stringify(err)); + } else { + console.log("checkOsAccountVerified successfully, isVerified: " + isVerified); + } }); - } catch (e) { - console.log('isConstraintEnabled exception:' + JSON.stringify(e)); + } catch (err) { + console.log("checkOsAccountVerified exception: " + err); } ``` -### isConstraintEnabled9+ +### checkOsAccountVerified9+ -isConstraintEnabled(localId: number, constraint: string): Promise<boolean> +checkOsAccountVerified(localId?: number): Promise<boolean> -判断指定系统帐号是否具有指定约束，使用Promise方式异步返回结果。 +检查指定系统帐号是否已验证。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ------------------------------------- | -| localId | number | 是 | 指定的系统帐号ID。 | -| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | --------------------------------------------------------------- | +| localId | number | 否 | 系统帐号ID。不填则检查当前系统帐号是否已验证。 | **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，具有指定约束则返回true，否则返回false。 | +| 类型 | 说明 | +| ---------------------- | ----------------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示指定帐号已验证；返回false表示指定帐号未验证。 | -**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; try { - accountManager.isConstraintEnabled(localId, 'constraint.wifi').then((isEnabled) => { - console.log('isConstraintEnabled, isEnabled: ' + isEnabled); + accountManager.checkOsAccountVerified(localId).then((isVerified) => { + console.log("checkOsAccountVerified successfully, isVerified: " + isVerified); }).catch((err) => { - console.log('isConstraintEnabled err: ' + JSON.stringify(err)); + console.log("checkOsAccountVerified failed, error: " + JSON.stringify(err)); }); - } catch (e) { - console.log('isConstraintEnabled exception:' + JSON.stringify(e)); + } catch (err) { + console.log('checkOsAccountVerified exception: ' + JSON.stringify(e)); } ``` -### isOsAccountConstraintEnable(deprecated) +### removeOsAccount -isOsAccountConstraintEnable(localId: number, constraint: string, callback: AsyncCallback<boolean>): void +removeOsAccount(localId: number, callback: AsyncCallback<void>): void -判断指定系统帐号是否具有指定约束，使用callback回调异步返回结果。 +删除指定系统帐号。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[isConstraintEnabled](#isconstraintenabled9) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -460,32 +591,46 @@ isOsAccountConstraintEnable(localId: number, constraint: string, callback: Async **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ---------------------------- | ---- | ------------------------------------------------- | -| localId | number | 是 | 指定的系统帐号ID。 | -| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | -| callback | AsyncCallback<boolean> | 是 | 回调结果，具有指定约束则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<void> | 是 | 回调函数。如果删除帐号成功，err为null，否则为错误对象。 | -**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - accountManager.isOsAccountConstraintEnable(localId, 'constraint.wifi', (err, isConstraintEnabled)=>{ - console.log('isOsAccountConstraintEnable err:' + JSON.stringify(err)); - console.log('isOsAccountConstraintEnable isConstraintEnabled:' + isConstraintEnabled); - }); + let accountName = "testAccountName"; + try { + accountManager.createOsAccount(accountName, account_osAccount.OsAccountType.NORMAL, (err, osAccountInfo) => { + accountManager.removeOsAccount(osAccountInfo.localId, (err)=>{ + if (err) { + console.log("removeOsAccount failed, error: " + JSON.stringify(err)); + } else { + console.log("removeOsAccount successfully"); + } + }); + }); + } catch (err) { + console.log('removeOsAccount exception:' + JSON.stringify(err)); + } ``` -### isOsAccountConstraintEnable(deprecated) +### removeOsAccount -isOsAccountConstraintEnable(localId: number, constraint: string): Promise<boolean> +removeOsAccount(localId: number): Promise<void> -判断指定系统帐号是否具有指定约束，使用Promise方式异步返回结果。 +删除指定系统帐号。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[isConstraintEnabled](#isconstraintenabled9-1) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -493,344 +638,445 @@ isOsAccountConstraintEnable(localId: number, constraint: string): Promise<boo **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ------------------------------------- | -| localId | number | 是 | 指定的系统帐号ID。 | -| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | --------------------------------- | +| localId | number | 是 | 系统帐号ID。 | **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，具有指定约束则返回true，否则返回false。 | +| 类型 | 说明 | +| ------------------- | ------------------------------------ | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | -**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - accountManager.isOsAccountConstraintEnable(localId, 'constraint.wifi').then((isConstraintEnabled) => { - console.log('isOsAccountConstraintEnable, isConstraintEnabled: ' + isConstraintEnabled); - }).catch((err) => { - console.log('isOsAccountConstraintEnable err: ' + JSON.stringify(err)); - }); + let accountName = "testAccountName"; + try { + accountManager.createOsAccount(accountName, account_osAccount.OsAccountType.NORMAL, (err, osAccountInfo)=>{ + accountManager.removeOsAccount(osAccountInfo.localId).then(() => { + console.log("removeOsAccount successfully"); + }).catch((err) => { + console.log("removeOsAccount failed, error: " + JSON.stringify(err)); + }); + }); + } catch (err) { + console.log("removeOsAccount exception: " + JSON.stringify(err)); + } ``` -### isTestable9+ +### setOsAccountConstraints + +setOsAccountConstraints(localId: number, constraints: Array<string>, enable: boolean,callback: AsyncCallback<void>): void + +为指定系统帐号设置/删除约束。使用callback异步回调。 -isTestable(callback: AsyncCallback<boolean>): void +**系统接口：** 此接口为系统接口。 -检查当前系统帐号是否为测试帐号，使用callback回调异步返回结果。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ----------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调结果，是测试帐号则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------------------------- | ---- | ----------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| constraints | Array<string> | 是 | 待设置/删除的[约束](#系统帐号约束列表)列表。 | +| enable | boolean | 是 | 设置(true)/删除(false) | +| callback | AsyncCallback<void> | 是 | 回调函数。如果设置成功，err为null，否则为错误对象。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** 给ID为100的系统帐号设置禁止使用Wi-Fi的约束 ```js let accountManager = account_osAccount.getAccountManager(); + let localId = 100; + let constraint = "constraint.wifi"; try { - accountManager.isTestable((err, isTest) => { - console.log('isTestable err: ' + JSON.stringify(err)); - console.log('isTestable isTest: ' + isTest); + accountManager.setOsAccountConstraints(localId, [constraint], true, (err) => { + if (err) { + console.log("setOsAccountConstraints failed, error:" + JSON.stringify(err)); + } else { + console.log("setOsAccountConstraints successfully"); + } }); - } catch (e) { - console.log('isTestable exception: ' + JSON.stringify(e)); + } catch (err) { + console.log("setOsAccountConstraints exception: " + JSON.stringify(err)); } ``` -### isTestable9+ +### setOsAccountConstraints + +setOsAccountConstraints(localId: number, constraints: Array<string>, enable: boolean): Promise<void> + +为指定系统帐号设置/删除约束。使用Promise异步回调。 -isTestable(): Promise<boolean> +**系统接口：** 此接口为系统接口。 -检查当前系统帐号是否为测试帐号，使用Promise方式异步返回结果。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------------------- | ---- | -------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| constraints | Array<string> | 是 | 待设置/删除的[约束](#系统帐号约束列表)列表。 | +| enable | boolean | 是 | 设置(true)/删除(false)。 | + **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，是测试帐号则返回true，否则返回false。 | +| 类型 | 说明 | +| :------------------ | :----------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** 删除ID为100的系统帐号的禁止使用Wi-Fi的约束 ```js let accountManager = account_osAccount.getAccountManager(); + let localId = 100; try { - accountManager.isTestable().then((isTest) => { - console.log('isTestable, isTest: ' + isTest); + accountManager.setOsAccountConstraints(localId, ['constraint.location.set'], false).then(() => { + console.log('setOsAccountConstraints succsuccessfully'); }).catch((err) => { - console.log('isTestable err: ' + JSON.stringify(err)); + console.log('setOsAccountConstraints failed, error: ' + JSON.stringify(err)); }); - } catch (e) { - console.log('isTestable exception: ' + JSON.stringify(e)); + } catch (err) { + console.log('setOsAccountConstraints exception:' + JSON.stringify(err)); } ``` -### isTestOsAccount(deprecated) +### setOsAccountName -isTestOsAccount(callback: AsyncCallback<boolean>): void +setOsAccountName(localId: number, localName: string, callback: AsyncCallback<void>): void -检查当前系统帐号是否为测试帐号，使用callback回调异步返回结果。 +设置指定系统帐号的帐号名。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[isTestable](#istestable9) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ----------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调结果，是测试帐号则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| :-------- | ------------------------- | ---- | ----------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| localName | string | 是 | 帐号名，最大长度为1024。 | +| callback | AsyncCallback<void> | 是 | 回调函数。如果设置成功，err为null，否则为错误对象。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid parameters. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** 将ID为100的系统帐号的帐号名设置成demoName ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isTestOsAccount((err, isTest) => { - console.log('isTestOsAccount err: ' + JSON.stringify(err)); - console.log('isTestOsAccount isTest: ' + isTest); - }); + let localId = 100; + let name = "demoName"; + try { + accountManager.setOsAccountName(localId, name, (err) => { + if (err) { + console.log("setOsAccountName failed, error: " + JSON.stringify(err)); + } else { + console.log("setOsAccountName successfully"); + } + }); + } catch (err) { + console.log('setOsAccountName exception:' + JSON.stringify(err)); + } ``` -### isTestOsAccount(deprecated) +### setOsAccountName -isTestOsAccount(): Promise<boolean> +setOsAccountName(localId: number, localName: string): Promise<void> -检查当前系统帐号是否为测试帐号，使用Promise方式异步返回结果。 +设置指定系统帐号的帐号名。使用Promise异步调用。 -> **说明：** 从API version 9开始废弃，建议使用[isTestable](#istestable9-1) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | --------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| localName | string | 是 | 帐号名，最大长度为1024。 | + **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，是测试帐号则返回true，否则返回false。 | +| 类型 | 说明 | +| :------------------ | :----------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** 将ID为100的系统帐号的帐号名设置成demoName ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isTestOsAccount().then((isTest) => { - console.log('isTestOsAccount, isTest: ' + isTest); - }).catch((err) => { - console.log('isTestOsAccount err: ' + JSON.stringify(err)); - }); + let localId = 100; + let name = 'testName'; + try { + accountManager.setOsAccountName(localId, name).then(() => { + console.log('setOsAccountName successfully'); + }).catch((err) => { + console.log('setOsAccountName failed, error: ' + JSON.stringify(err)); + }); + } catch (err) { + console.log('setOsAccountName exception:' + JSON.stringify(err)); + } ``` -### isVerified9+ +### getOsAccountCount9+ -isVerified(callback: AsyncCallback<boolean>): void +getOsAccountCount(callback: AsyncCallback<number>): void -检查当前系统帐号是否已验证，使用callback回调异步返回结果。 +获取已创建的系统帐号数量。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调结果，已验证则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------------------------------------- | +| callback | AsyncCallback<number> | 是 | 回调函数。当获取成功时，err为null，data为已创建的系统帐号的数量；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.isVerified((err, isVeri) => { - console.log('isVerified err: ' + JSON.stringify(err)); - console.log('isVerified isVeri: ' + isVeri); + accountManager.getOsAccountCount((err, count) => { + if (err) { + console.log("getOsAccountCount failed, error: " + JSON.stringify(err)); + } else { + console.log("getOsAccountCount successfully, count: " + count); + } }); - } catch (e) { - console.log('isVerified exception: ' + JSON.stringify(e)); + } catch (err) { + console.log("getOsAccountCount exception: " + JSON.stringify(err)); } ``` -### isVerified9+ +### getOsAccountCount9+ -isOsAccountVerified(localId: number, callback: AsyncCallback<boolean>): void +getOsAccountCount(): Promise<number> -检查指定系统帐号是否已验证，使用callback回调异步返回结果。 +获取已创建的系统帐号数量。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount -**参数：** +**返回值：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ------------------------------------------- | -| localId | number | 否 | 指定的系统帐号ID。 | -| callback | AsyncCallback<boolean> | 是 | 回调结果，已验证则返回true，否则返回false。 | +| 类型 | 说明 | +| --------------------- | -------------------------------------- | +| Promise<number> | Promise对象，返回已创建的系统帐号的数量。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.isVerified((err, isVeri) => { - console.log('isVerified err: ' + JSON.stringify(err)); - console.log('isVerified isVeri: ' + isVeri); + accountManager.getOsAccountCount().then((count) => { + console.log("getOsAccountCount successfully, count: " + count); + }).catch((err) => { + console.log("getOsAccountCount failed, error: " + JSON.stringify(err)); }); - } catch (e) { - console.log('isVerified exception: ' + JSON.stringify(e)); + } catch(err) { + console.log('getOsAccountCount exception:' + JSON.stringify(err)); } ``` -### isVerified9+ - -isOsAccountVerified(localId?: number): Promise<boolean> +### queryOsAccountLocalIdFromProcess9+ -检查指定系统帐号是否已验证，使用Promise方式异步返回结果。 +queryOsAccountLocalIdFromProcess(callback: AsyncCallback<number>): void -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS +获取当前进程所属的系统帐号ID，使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------ | -| localId | number | 否 | 指定的系统帐号ID。 | - -**返回值：** - -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，已验证则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ---------------------------------------------------------------------------- | +| callback | AsyncCallback<number> | 是 | 回调函数。当获取成功时，err为null，data为当前进程所属的系统帐号ID；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.isVerified().then((isVeri) => { - console.log('isVerified, isVeri: ' + isVeri); - }).catch((err) => { - console.log('isVerified err: ' + JSON.stringify(err)); + accountManager.queryOsAccountLocalIdFromProcess((err, localId) => { + if (err) { + console.log("queryOsAccountLocalIdFromProcess failed, error: " + JSON.stringify(err)); + } else { + console.log("queryOsAccountLocalIdFromProcess successfully, localId: " + localId); + } }); - } catch (e) { - console.log('isVerified exception: ' + JSON.stringify(e)); + } catch (err) { + console.log("queryOsAccountLocalIdFromProcess exception: " + JSON.stringify(err)); } ``` -### isOsAccountVerified(deprecated) - -isOsAccountVerified(callback: AsyncCallback<boolean>): void +### queryOsAccountLocalIdFromProcess9+ -检查当前系统帐号是否已验证，使用callback回调异步返回结果。 +queryOsAccountLocalIdFromProcess(): Promise<number> -> **说明：** 从API version 9开始废弃，建议使用[isVerified](#isverified9) -> -> 从 API version 7开始支持。 +获取当前进程所属的系统帐号ID，使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount -**参数：** +**返回值：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ------------------------------------------- | -| callback | AsyncCallback<boolean> | 是 | 回调结果，已验证则返回true，否则返回false。 | +| 类型 | 说明 | +| :-------------------- | :--------------------------------------- | +| Promise<number> | Promise对象，返回当前进程所属的系统帐号ID。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isOsAccountVerified((err, isVerified) => { - console.log('isOsAccountVerified err: ' + JSON.stringify(err)); - console.log('isOsAccountVerified isVerified: ' + isVerified); - }); + try { + accountManager.queryOsAccountLocalIdFromProcess().then((localId) => { + console.log("queryOsAccountLocalIdFromProcess successfully, localId: " + localId); + }).catch((err) => { + console.log("queryOsAccountLocalIdFromProcess failed, error: " + JSON.stringify(err)); + }); + } catch (err) { + console.log('queryOsAccountLocalIdFromProcess exception: ' + JSON.stringify(err)); + } ``` -### isOsAccountVerified(deprecated) - -isOsAccountVerified(localId: number, callback: AsyncCallback<boolean>): void - -检查指定系统帐号是否已验证，使用callback回调异步返回结果。 +### queryOsAccountLocalIdFromUid9+ -> **说明：** 从API version 9开始废弃，建议使用[isVerified](#isverified9-1) -> -> 从 API version 7开始支持。 +queryOsAccountLocalIdFromUid(uid: number, callback: AsyncCallback<number>): void -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS +根据uid查询对应的系统帐号ID，使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------- | ---- | ------------------------------------------- | -| localId | number | 否 | 指定的系统帐号ID。 | -| callback | AsyncCallback<boolean> | 是 | 回调结果，已验证则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------------------------------- | +| uid | number | 是 | 进程uid。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果查询成功，err为null，data为对应的系统帐号ID；否则为错误对象。 | -**示例：** + +**错误码：** + +| 错误码ID | 错误信息 | +| 12300002 | Invalid uid. | + +**示例：** 查询值为12345678的uid所属的系统帐号的帐号ID ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isOsAccountVerified((err, isVerified) => { - console.log('isOsAccountVerified err: ' + JSON.stringify(err)); - console.log('isOsAccountVerified isVerified: ' + isVerified); - }); + let uid = 12345678; + try { + accountManager.queryOsAccountLocalIdFromUid(uid, (err, localId) => { + if (err) { + console.log("queryOsAccountLocalIdFromUid failed, error: " + JSON.stringify(err)); + } + console.log("queryOsAccountLocalIdFromUid successfully, localId: " + localId); + }); + } catch (err) { + console.log("queryOsAccountLocalIdFromUid exception: " + JSON.stringify(err)); + } ``` -### isOsAccountVerified(deprecated) - -isOsAccountVerified(localId?: number): Promise<boolean> - -检查指定系统帐号是否已验证，使用Promise方式异步返回结果。 +### queryOsAccountLocalIdFromUid9+ -> **说明：** 从API version 9开始废弃，建议使用[isVerified](#isverified9-2) -> -> 从 API version 7开始支持。 +queryOsAccountLocalIdFromUid(uid: number): Promise<number> -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS +根据uid查询对应的系统帐号ID，使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------ | -| localId | number | 否 | 指定的系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | --------- | +| uid | number | 是 | 进程uid。 | **返回值：** -| 类型 | 说明 | -| :--------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，已验证则返回true，否则返回false。 | +| 类型 | 说明 | +| --------------------- | --------------------------------------- | +| Promise<number> | Promise对象，返回指定uid对应的系统帐号ID。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| 12300002 | Invalid uid. | + +**示例：** 查询值为12345678的uid所属的系统帐号ID ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.isOsAccountVerified().then((isVerified) => { - console.log('isOsAccountVerified, isVerified: ' + isVerified); - }).catch((err) => { - console.log('isOsAccountVerified err: ' + JSON.stringify(err)); - }); + let uid = 12345678; + try { + accountManager.queryOsAccountLocalIdFromUid(uid).then((localId) => { + console.log("queryOsAccountLocalIdFromUid successfully, localId: " + localId); + }).catch((err) => { + console.log("queryOsAccountLocalIdFromUid failed, error: " + JSON.stringify(err)); + }); + } catch (err) { + console.log('queryOsAccountLocalIdFromUid exception: ' + JSON.stringify(err)); + } ``` -### removeOsAccount - -removeOsAccount(localId: number, callback: AsyncCallback<void>): void +### queryOsAccountLocalIdFromDomain9+ -删除指定系统帐号，使用callback回调异步返回结果。 +getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo, callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +根据域帐号信息，获取与其关联的系统帐号ID。使用callback异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -838,33 +1084,34 @@ removeOsAccount(localId: number, callback: AsyncCallback<void>): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | -------------------- | -| localId | number | 是 | 要删除的系统帐号ID。 | -| callback | AsyncCallback<void> | 是 | 回调结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | --------------------------------------- | ---- | -------------------------------------------------------------------------- | +| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果查询成功，err为null，data为域帐号关联的系统帐号ID；否则为错误对象。 | **示例：** ```js + let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; let accountManager = account_osAccount.getAccountManager(); try { - accountManager.createOsAccount('testAccountName', account_osAccount.OsAccountType.NORMAL, (err, osAccountInfo) => { - accountManager.removeOsAccount(osAccountInfo.localId, (err)=>{ - console.log('removeOsAccount err:' + JSON.stringify(err)); - }); + accountManager.queryOsAccountLocalIdFromDomain(domainInfo, (err, localId) => { + if (err) { + console.log("queryOsAccountLocalIdFromDomain failed, error: " + JSON.stringify(err)); + } else { + console.log("queryOsAccountLocalIdFromDomain successfully, localId: " + localId); + } }); - } catch (e) { - console.log('removeOsAccount exception:' + JSON.stringify(e)); + } catch (err) { + console.log('queryOsAccountLocalIdFromDomain exception: ' + JSON.stringify(err)); } ``` -### removeOsAccount - -removeOsAccount(localId: number): Promise<void> +### queryOsAccountLocalIdFromDomain9+ -删除指定系统帐号，使用Promise方式异步返回结果。 +queryOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo): Promise<number> -此接口为系统接口，三方应用不支持调用。 +根据域帐号信息，获取与其关联的系统帐号的帐号ID。使用Promise异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -872,117 +1119,101 @@ removeOsAccount(localId: number): Promise<void> **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | -------------------- | -| localId | number | 是 | 要删除的系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | --------------------------------------- | ---- | ------------ | +| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :---------------------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :------------------------------------- | +| Promise<number> | Promise对象，返回域帐号关联的系统帐号ID。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); + let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; try { - accountManager.createOsAccount('testAccountName', account_osAccount.OsAccountType.NORMAL, (err, osAccountInfo)=>{ - accountManager.removeOsAccount(osAccountInfo.localId).then(() => { - console.log('removeOsAccount Success'); - }).catch(() => { - console.log('removeOsAccount err: ' + JSON.stringify(err)); - }); + accountManager.queryOsAccountLocalIdFromDomain(domainInfo).then((localId) => { + console.log("queryOsAccountLocalIdFromDomain successfully, localId: " + localId); + }).catch((err) => { + console.log("queryOsAccountLocalIdFromDomain failed, error: " + JSON.stringify(err)); }); - } catch (e) { - console.log('removeOsAccount exception:' + JSON.stringify(e)); + } catch (err) { + console.log("queryOsAccountLocalIdFromDomain exception: " + JSON.stringify(err)); } ``` -### setOsAccountConstraints - -setOsAccountConstraints(localId: number, constraints: Array<string>, enable: boolean,callback: AsyncCallback<void>): void +### queryMaxOsAccountNumber -为指定系统帐号设置/删除约束，使用callback回调异步返回结果。 +queryMaxOsAccountNumber(callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +查询允许创建的系统帐号的最大数量。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ------------------------- | ---- | -------------------------------------------- | -| localId | number | 是 | 系统帐号ID。 | -| constraints | Array<string> | 是 | 待设置/删除的[约束](#系统帐号约束列表)列表。 | -| enable | boolean | 是 | 设置(true)/删除(false) | -| callback | AsyncCallback<void> | 是 | 回调结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------------------------------------------- | +| callback | AsyncCallback<number> | 是 | 回调函数，如果查询成功，err为null，data为允许创建的系统帐号的最大数量；否则为错误对象。 | -**示例：** 给ID为100的系统帐号设置禁止使用Wi-Fi的约束 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; try { - accountManager.setOsAccountConstraints(localId, ['constraint.wifi'], true, (err)=>{ - console.log('setOsAccountConstraints err:' + JSON.stringify(err)); + accountManager.queryMaxOsAccountNumber((err, maxCnt) => { + if (err) { + console.log('queryMaxOsAccountNumber failed, error:' + JSON.stringify(err)); + } else { + console.log('queryMaxOsAccountNumber successfully, maxCnt:' + maxCnt); + } }); - } catch (e) { - console.log('setOsAccountConstraints exception:' + JSON.stringify(e)); + } catch (err) { + console.log('queryMaxOsAccountNumber exception:' + JSON.stringify(err)); } ``` -### setOsAccountConstraints - -setOsAccountConstraints(localId: number, constraints: Array<string>, enable: boolean): Promise<void> +### queryMaxOsAccountNumber -为指定系统帐号设置/删除约束，使用Promise方式异步返回结果。 +queryMaxOsAccountNumber(): Promise<number> -此接口为系统接口，三方应用不支持调用。 +查询允许创建的系统帐号的最大数量。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ------------------- | ---- | -------------------------------------------- | -| localId | number | 是 | 系统帐号ID。 | -| constraints | Array<string> | 是 | 待设置/删除的[约束](#系统帐号约束列表)列表。 | -| enable | boolean | 是 | 设置(true)/删除(false)。 | - **返回值：** -| 类型 | 说明 | -| :------------------ | :---------------------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| --------------------- | ------------------------------------------- | +| Promise<number> | Promise对象，返回允许创建的系统帐号的最大数量。 | -**示例：** 删除ID为100的系统帐号的禁止使用Wi-Fi的约束 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; try { - accountManager.setOsAccountConstraints(localId, ['constraint.location.set'], false).then(() => { - console.log('setOsAccountConstraints Success'); + accountManager.queryMaxOsAccountNumber().then((maxCnt) => { + console.log('queryMaxOsAccountNumber successfully, maxCnt: ' + maxCnt); }).catch((err) => { - console.log('setOsAccountConstraints err: ' + JSON.stringify(err)); + console.log('queryMaxOsAccountNumber failed, error: ' + JSON.stringify(err)); }); - } catch (e) { - console.log('setOsAccountConstraints exception:' + JSON.stringify(e)); + } catch (err) { + console.log('queryMaxOsAccountNumber exception:' + JSON.stringify(err)); } ``` -### setOsAccountName - -setOsAccountName(localId: number, localName: string, callback: AsyncCallback<void>): void +### getOsAccountConstraints9+ -设置指定系统帐号的帐号名，使用callback回调异步返回结果。 +getOsAccountConstraints(localId: number, callback: AsyncCallback<Array<string>>): void -此接口为系统接口，三方应用不支持调用。 +获取指定系统帐号的全部约束。使用callback异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -990,34 +1221,41 @@ setOsAccountName(localId: number, localName: string, callback: AsyncCallback< **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| :-------- | ------------------------- | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | -| localName | string | 是 | 帐号名。 | -| callback | AsyncCallback<void> | 是 | 回调结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | -------------------------------------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<Array<string>> | 是 | 回调函数，如果获取成功，err为null，data为该系统帐号的全部[约束](#系统帐号约束列表)；否则为错误对象。 | -**示例：** 将ID为100的系统帐号的帐号名设置成demoName +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 获取ID为100的系统帐号的全部约束 ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; - let newName = 'demoName'; try { - accountManager.setOsAccountName(localId, newName, (err)=>{ - console.debug('setOsAccountName err:' + JSON.stringify(err)); + accountManager.getOsAccountConstraints(localId, (err, constraints) => { + if (err) { + console.log("getOsAccountConstraints failed, err: " + JSON.stringify(err)); + } else { + console.log("getOsAccountConstraints successfully, constraints: " + JSON.stringify(constraints)); + } }); - } catch (e) { - console.log('setOsAccountName exception:' + JSON.stringify(e)); + } catch (err) { + console.log('getOsAccountConstraints exception:' + JSON.stringify(err)); } ``` -### setOsAccountName - -setOsAccountName(localId: number, localName: string): Promise<void> +### getOsAccountConstraints9+ -设置指定系统帐号的帐号名，使用Promise方式异步返回结果。 +getOsAccountConstraints(localId: number): Promise<Array<string>> -此接口为系统接口，三方应用不支持调用。 +获取指定系统帐号的全部约束。使用Promise异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -1025,481 +1263,539 @@ setOsAccountName(localId: number, localName: string): Promise<void> **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | -| localName | string | 是 | 帐号名。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------ | +| localId | number | 是 | 系统帐号ID。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :---------------------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| ---------------------------------- | ---------------------------------------------------------- | +| Promise<Array<string>> | Promise对象，返回指定系统帐号的全部[约束](#系统帐号约束列表)。 | -**示例：** 将ID为100的系统帐号的帐号名设置成demoName +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 获取ID为100的系统帐号的全部约束 ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; - let nameLimit = 'demoName'; try { - accountManager.setOsAccountName(localId, nameLimit).then(() => { - console.log('setOsAccountName Success'); + accountManager.getOsAccountConstraints(localId).then((constraints) => { + console.log('getOsAccountConstraints, constraints: ' + constraints); }).catch((err) => { - console.log('setOsAccountName err: ' + JSON.stringify(err)); + console.log('getOsAccountConstraints err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('setOsAccountName exception:' + JSON.stringify(e)); + console.log('getOsAccountConstraints exception:' + JSON.stringify(e)); } ``` -### getOsAccountCount9+ +### queryAllCreatedOsAccounts -getOsAccountCount(callback: AsyncCallback<number>): void +queryAllCreatedOsAccounts(callback: AsyncCallback<Array<OsAccountInfo>>): void -获取已创建的系统帐号数量，使用callback回调异步返回结果。 +查询已创建的所有系统帐号的信息列表。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS + **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------ | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是已创建的系统帐号的数量。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------- | +| callback | AsyncCallback<Array<[OsAccountInfo](#osaccountinfo)>> | 是 | 回调函数。如果查询成功，err为null，data为已创建的所有系统帐号的信息列表；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.getOsAccountCount((err, accountCnt)=>{ - console.log('obtains the number of all os accounts created err:' + JSON.stringify(err)); - console.log('obtains the number of all os accounts created accountCnt:' + accountCnt); + accountManager.queryAllCreatedOsAccounts((err, accountArr)=>{ + console.log('queryAllCreatedOsAccounts err:' + JSON.stringify(err)); + console.log('queryAllCreatedOsAccounts accountArr:' + JSON.stringify(accountArr)); }); } catch (e) { - console.log('obtains the number of all os accounts created exception:' + JSON.stringify(e)); + console.log('queryAllCreatedOsAccounts exception:' + JSON.stringify(e)); } ``` -### getOsAccountCount9+ +### queryAllCreatedOsAccounts -getOsAccountCount(): Promise<number> +queryAllCreatedOsAccounts(): Promise<Array<OsAccountInfo>> -获取已创建的系统帐号数量，使用Promise方式异步返回结果。 +查询已创建的所有系统帐号的信息列表。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS + **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是已创建的系统帐号的数量。 | +| 类型 | 说明 | +| ----------------------------------------------------------- | --------------------------------------------- | +| Promise<Array<[OsAccountInfo](#osaccountinfo)>> | Promise对象，返回已创建的所有系统帐号的信息列表。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.getOsAccountCount().then((accountCnt) => { - console.log('getOsAccountCount, accountCnt: ' + accountCnt); + accountManager.queryAllCreatedOsAccounts().then((accountArr) => { + console.log('queryAllCreatedOsAccounts, accountArr: ' + JSON.stringify(accountArr)); }).catch((err) => { - console.log('getOsAccountCount err: ' + JSON.stringify(err)); + console.log('queryAllCreatedOsAccounts err: ' + JSON.stringify(err)); }); - } catch(e) { - console.log('getOsAccountCount exception: ' + JSON.stringify(e)); + } catch (e) { + console.log('queryAllCreatedOsAccounts exception:' + JSON.stringify(e)); } ``` -### getCreatedOsAccountsCount(deprecated) - -getCreatedOsAccountsCount(callback: AsyncCallback<number>): void - -获取已创建的系统帐号数量，使用callback回调异步返回结果。 +### getActivatedOsAccountIds9+ -> **说明：** 从API version 9开始废弃，建议使用[getOsAccountCount](#getosaccountcount9) -> -> 从 API version 7开始支持。 +getActivatedOsAccountIds(callback: AsyncCallback<Array<number>>): void -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +查询当前处于激活状态的系统帐号的ID列表。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------ | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是已创建的系统帐号的数量。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------------------------------ | +| callback | AsyncCallback<Array<number>> | 是 | 回调函数。如果查询成功，err为null，data为当前处于激活状态的系统帐号的ID列表；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getCreatedOsAccountsCount((err, accountCnt)=>{ - console.log('obtains the number of all os accounts created err:' + JSON.stringify(err)); - console.log('obtains the number of all os accounts created accountCnt:' + accountCnt); - }); + try { + accountManager.getActivatedOsAccountIds((err, idArray)=>{ + console.log('getActivatedOsAccountIds err:' + JSON.stringify(err)); + console.log('getActivatedOsAccountIds idArray length:' + idArray.length); + for(let i=0;i(deprecated) - -getCreatedOsAccountsCount(): Promise<number> - -获取已创建的系统帐号数量，使用Promise方式异步返回结果。 +### getActivatedOsAccountIds9+ -> **说明：** 从API version 9开始废弃，建议使用[getOsAccountCount](#getosaccountcount9-1) -> -> 从 API version 7开始支持。 +getActivatedOsAccountIds(): Promise<Array<number>> -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +查询当前处于激活状态的系统帐号的ID列表。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是已创建的系统帐号的数量。 | +| 类型 | 说明 | +| :--------------------------------- | :------------------------------------------------ | +| Promise<Array<number>> | Promise对象，返回当前处于激活状态的系统帐号的ID列表。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getCreatedOsAccountsCount().then((accountCnt) => { - console.log('getCreatedOsAccountsCount, accountCnt: ' + accountCnt); - }).catch((err) => { - console.log('getCreatedOsAccountsCount err: ' + JSON.stringify(err)); - }); + try { + accountManager.getActivatedOsAccountIds().then((idArray) => { + console.log('getActivatedOsAccountIds, idArray: ' + idArray); + }).catch((err) => { + console.log('getActivatedOsAccountIds err: ' + JSON.stringify(err)); + }); + } catch (e) { + console.log('getActivatedOsAccountIds exception:' + JSON.stringify(e)); + } ``` -### queryOsAccountLocalIdFromProcess9+ +### createOsAccount -queryOsAccountLocalIdFromProcess(callback: AsyncCallback<number>): void +createOsAccount(localName: string, type: OsAccountType, callback: AsyncCallback<OsAccountInfo>): void -获取当前进程所属的系统帐号的帐号ID，使用callback回调异步返回结果。 +创建一个系统帐号。使用callback异步回调。 + +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | -------------------------------------------------- | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是当前进程所属的系统帐号的帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| :-------- | ---------------------------------------------------- | ---- | --------------------------------------------------------------------------- | +| localName | string | 是 | 创建的系统帐号的名称。 | +| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | +| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调函数。如果创建成功，err为null，data为新创建的系统帐号的信息；否则为错误对象。 | + +**错误码：** +| 错误码ID | 错误信息 | +| 12300002 | Invalid localName or type. | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.queryOsAccountLocalIdFromProcess((err, accountID) => { - console.log('queryOsAccountLocalIdFromProcess err: ' + JSON.stringify(err)); - console.log('queryOsAccountLocalIdFromProcess accountID: ' + accountID); + accountManager.createOsAccount('testName', account_osAccount.OsAccountType.NORMAL, (err, osAccountInfo)=>{ + console.log('createOsAccount err:' + JSON.stringify(err)); + console.log('createOsAccount osAccountInfo:' + JSON.stringify(osAccountInfo)); }); } catch (e) { - console.log('queryOsAccountLocalIdFromProcess exception: ' + JSON.stringify(e)); + console.log('createOsAccount exception:' + JSON.stringify(e)); } ``` -### queryOsAccountLocalIdFromProcess9+ +### createOsAccount -queryOsAccountLocalIdFromProcess(): Promise<number> +createOsAccount(localName: string, type: OsAccountType): Promise<OsAccountInfo> -获取当前进程所属的系统帐号的帐号ID，使用Promise方式异步返回结果。 +创建一个系统帐号。使用Promise异步回调。 + +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------- | ---- | ---------------------- | +| localName | string | 是 | 创建的系统帐号的名称。 | +| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | + **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是当前进程所属的系统帐号的帐号ID。 | +| 类型 | 说明 | +| ---------------------------------------------- | ------------------------------------- | +| Promise<[OsAccountInfo](#osaccountinfo)> | Promis对象，返回新创建的系统帐号的信息。 | + +**错误码：** +| 错误码ID | 错误信息 | +| 12300002 | Invalid localName or type. | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.queryOsAccountLocalIdFromProcess().then((accountID) => { - console.log('queryOsAccountLocalIdFromProcess, accountID: ' + accountID); + accountManager.createOsAccount('testAccountName', account_osAccount.OsAccountType.NORMAL).then((accountInfo) => { + console.log('createOsAccount, accountInfo: ' + JSON.stringify(accountInfo)); }).catch((err) => { - console.log('queryOsAccountLocalIdFromProcess err: ' + JSON.stringify(err)); + console.log('createOsAccount err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('queryOsAccountLocalIdFromProcess exception: ' + JSON.stringify(e)); + console.log('createOsAccount exception:' + JSON.stringify(e)); } ``` -### getOsAccountLocalIdFromProcess(deprecated) +### createOsAccountForDomain8+ -getOsAccountLocalIdFromProcess(callback: AsyncCallback<number>): void +createOsAccountForDomain(type: OsAccountType, domainInfo: DomainAccountInfo, callback: AsyncCallback<OsAccountInfo>): void -获取当前进程所属的系统帐号的帐号ID，使用callback回调异步返回结果。 +根据域帐号信息，创建一个系统帐号并将其与域帐号关联。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromProcess](#queryosaccountlocalidfromprocess9) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | -------------------------------------------------- | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是当前进程所属的系统帐号的帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| :--------- | ---------------------------------------------------- | ---- | -------------------------------------------------------------------------- | +| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | +| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | +| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调函数。如果创建成功，err为null，data为新创建的系统帐号的信息；否则为错误对象。 | + +**错误码：** +| 错误码ID | 错误信息 | +| 12300002 | Invalid type or domainInfo. | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getOsAccountLocalIdFromProcess((err, accountID) => { - console.log('getOsAccountLocalIdFromProcess err: ' + JSON.stringify(err)); - console.log('getOsAccountLocalIdFromProcess accountID: ' + accountID); - }); + let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; + try { + accountManager.createOsAccountForDomain(account_osAccount.OsAccountType.NORMAL, domainInfo, (err, osAccountInfo)=>{ + console.log('createOsAccountForDomain err:' + JSON.stringify(err)); + console.log('createOsAccountForDomain osAccountInfo:' + JSON.stringify(osAccountInfo)); + }); + } catch (e) { + console.log('createOsAccountForDomain exception:' + JSON.stringify(e)); + } ``` -### getOsAccountLocalIdFromProcess(deprecated) +### createOsAccountForDomain8+ -getOsAccountLocalIdFromProcess(): Promise<number> +createOsAccountForDomain(type: OsAccountType, domainInfo: DomainAccountInfo): Promise<OsAccountInfo> -获取当前进程所属的系统帐号的帐号ID，使用Promise方式异步返回结果。 +根据传入的域帐号信息，创建与其关联的系统帐号。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromProcess](#queryosaccountlocalidfromprocess9-1) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------------------- | ---- | -------------------- | +| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | +| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | + **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是当前进程所属的系统帐号的帐号ID。 | +| 类型 | 说明 | +| ---------------------------------------------- | -------------------------------------- | +| Promise<[OsAccountInfo](#osaccountinfo)> | Promise对象，返回新创建的系统帐号的信息。 | + +**错误码：** +| 错误码ID | 错误信息 | +| 12300002 | Invalid type or domainInfo. | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getOsAccountLocalIdFromProcess().then((accountID) => { - console.log('getOsAccountLocalIdFromProcess, accountID: ' + accountID); - }).catch((err) => { - console.log('getOsAccountLocalIdFromProcess err: ' + JSON.stringify(err)); - }); + let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; + try { + accountManager.createOsAccountForDomain(account_osAccount.OsAccountType.NORMAL, domainInfo).then((accountInfo) => { + console.log('createOsAccountForDomain, account info: ' + JSON.stringify(accountInfo)); + }).catch((err) => { + console.log('createOsAccountForDomain err: ' + JSON.stringify(err)); + }); + } catch (e) { + console.log('createOsAccountForDomain exception:' + JSON.stringify(e)); + } ``` -### queryOsAccountLocalIdFromUid9+ +### getCurrentOsAccount9+ -queryOsAccountLocalIdFromUid(uid: number, callback: AsyncCallback<number>): void +getCurrentOsAccount(callback: AsyncCallback<OsAccountInfo>): void -从进程uid中获取该uid所属的系统帐号的帐号ID，使用callback回调异步返回结果。 +查询当前进程所属的系统帐号的信息。使用callback异步回调。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------------- | -| uid | number | 是 | 进程uid。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是uid所属的系统帐号的帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | +| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调函数。如果查询成功，err为null，data为当前进程所属的系统帐号信息；否则为错误对象。 | -**示例：** 查询值为12345678的uid所属的系统帐号的帐号ID +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let uid = 12345678; try { - accountManager.queryOsAccountLocalIdFromUid(uid, (err, accountID) => { - console.log('queryOsAccountLocalIdFromUid err: ' + JSON.stringify(err)); - console.log('queryOsAccountLocalIdFromUid: ' + accountID); + accountManager.getCurrentOsAccount((err, curAccountInfo)=>{ + console.log('getCurrentOsAccount err:' + JSON.stringify(err)); + console.log('getCurrentOsAccount curAccountInfo:' + JSON.stringify(curAccountInfo)); }); } catch (e) { - console.log('queryOsAccountLocalIdFromUid exception: ' + JSON.stringify(e)); + console.log('getCurrentOsAccount exception:' + JSON.stringify(e)); } ``` -### queryOsAccountLocalIdFromUid9+ - -queryOsAccountLocalIdFromUid(uid: number): Promise<number> +### getCurrentOsAccount9+ -从进程uid中获取该uid所属的系统帐号的帐号ID，使用Promise方式异步返回结果。 +getCurrentOsAccount(): Promise<OsAccountInfo> -**系统能力：** SystemCapability.Account.OsAccount +查询当前进程所属的系统帐号的信息。使用Promise异步回调。 -**参数：** +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | --------- | -| uid | number | 是 | 进程uid。 | +**系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是uid所属的系统帐号的帐号ID。 | +| 类型 | 说明 | +| ---------------------------------------------- | ----------------------------------------- | +| Promise<[OsAccountInfo](#osaccountinfo)> | Promise对象，返回当前进程所属的系统帐号信息。 | -**示例：** 查询值为12345678的uid所属的系统帐号的帐号ID +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let uid = 12345678; try { - accountManager.queryOsAccountLocalIdFromUid(uid).then((accountID) => { - console.log('queryOsAccountLocalIdFromUid: ' + accountID); + accountManager.getCurrentOsAccount().then((accountInfo) => { + console.log('getCurrentOsAccount, accountInfo: ' + JSON.stringify(accountInfo)); }).catch((err) => { - console.log('queryOsAccountLocalIdFromUid err: ' + JSON.stringify(err)); + console.log('getCurrentOsAccount err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('queryOsAccountLocalIdFromUid exception: ' + JSON.stringify(e)); + console.log('getCurrentOsAccount exception:' + JSON.stringify(e)); } ``` -### getOsAccountLocalIdFromUid(deprecated) +### queryOsAccountById -getOsAccountLocalIdFromUid(uid: number, callback: AsyncCallback<number>): void +queryOsAccountById(localId: number, callback: AsyncCallback<OsAccountInfo>): void -从进程uid中获取该uid所属的系统帐号的帐号ID，使用callback回调异步返回结果。 +查询指定系统帐号的信息。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromUid](#queryosaccountlocalidfromuid9) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | --------------------------------------------- | -| uid | number | 是 | 进程uid。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是uid所属的系统帐号的帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------------------ | +| localId | number | 是 | 要查询的系统帐号的ID。 | +| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调函数。如果查询成功，err为null，data为查到的系统帐号的信息；否则为错误对象。 | -**示例：** 查询值为12345678的uid所属的系统帐号的帐号ID +**错误码：** +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 查询ID为100的系统帐号信息 ```js let accountManager = account_osAccount.getAccountManager(); - let uid = 12345678; - accountManager.getOsAccountLocalIdFromUid(uid, (err, accountID) => { - console.log('getOsAccountLocalIdFromUid err: ' + JSON.stringify(err)); - console.log('getOsAccountLocalIdFromUid: ' + accountID); - }); + let localId = 100; + try { + accountManager.queryOsAccountById(localId, (err, accountInfo)=>{ + console.log('queryOsAccountById err:' + JSON.stringify(err)); + console.log('queryOsAccountById accountInfo:' + JSON.stringify(accountInfo)); + }); + } catch (e) { + console.log('queryOsAccountById exception:' + JSON.stringify(e)); + } ``` -### getOsAccountLocalIdFromUid(deprecated) +### queryOsAccountById -getOsAccountLocalIdFromUid(uid: number): Promise<number> +queryOsAccountById(localId: number): Promise<OsAccountInfo> -从进程uid中获取该uid所属的系统帐号的帐号ID，使用Promise方式异步返回结果。 +查询指定系统帐号的信息。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromUid](#queryosaccountlocalidfromuid9-1) -> -> 从 API version 7开始支持。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | --------- | -| uid | number | 是 | 进程uid。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | -------------------- | +| localId | number | 是 | 要查询的系统帐号的ID | **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是uid所属的系统帐号的帐号ID。 | +| 类型 | 说明 | +| ---------------------------------------------- | ------------------------------------ | +| Promise<[OsAccountInfo](#osaccountinfo)> | Promise对象，返回查到的系统帐号的信息。 | -**示例：** 查询值为12345678的uid所属的系统帐号的帐号ID +**错误码：** +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 查询ID为100的系统帐号信息 ```js let accountManager = account_osAccount.getAccountManager(); - let uid = 12345678; - accountManager.getOsAccountLocalIdFromUid(uid).then((accountID) => { - console.log('getOsAccountLocalIdFromUid: ' + accountID); - }).catch((err) => { - console.log('getOsAccountLocalIdFromUid err: ' + JSON.stringify(err)); - }); + let localId = 100; + try { + accountManager.queryOsAccountById(localId).then((accountInfo) => { + console.log('queryOsAccountById, accountInfo: ' + JSON.stringify(accountInfo)); + }).catch((err) => { + console.log('queryOsAccountById err: ' + JSON.stringify(err)); + }); + } catch (e) { + console.log('queryOsAccountById exception:' + JSON.stringify(e)); + } ``` -### queryOsAccountLocalIdFromDomain9+ - -getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo, callback: AsyncCallback<number>): void +### getOsAccountType9+ -根据域帐号信息，获取与其关联的系统帐号的帐号ID。 +getOsAccountType(callback: AsyncCallback<OsAccountType>): void -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.MANAGE_LOCAL_ACCOUNTS or ohos.permission.GET_LOCAL_ACCOUNTS +查询当前进程所属的系统帐号的帐号类型。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------------------------- | ---- | -------------------------------------------- | -| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是和域帐号关联的系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------------- | +| callback | AsyncCallback<[OsAccountType](#osaccounttype)> | 是 | 回调函数。如果查询成功，err为null，data为当前进程所属的系统帐号的帐号类型；否则为错误对象。 | **示例：** ```js - let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; let accountManager = account_osAccount.getAccountManager(); try { - accountManager.queryOsAccountLocalIdFromDomain(domainInfo, (err, accountID) => { - console.log('queryOsAccountLocalIdFromDomain: ' + JSON.stringify(err)); - console.log('queryOsAccountLocalIdFromDomain: ' + accountID); + accountManager.getOsAccountType((err, accountType) => { + console.log('getOsAccountType err: ' + JSON.stringify(err)); + console.log('getOsAccountType accountType: ' + accountType); }); } catch (e) { - console.log('queryOsAccountLocalIdFromDomain: ' + JSON.stringify(e)); + console.log('getOsAccountType exception: ' + JSON.stringify(e)); } ``` -### queryOsAccountLocalIdFromDomain9+ - -queryOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo): Promise<number> +### getOsAccountType9+ -根据域帐号信息，获取与其关联的系统帐号的帐号ID，使用Promise方式异步返回结果。 +getOsAccountType(): Promise<OsAccountType> -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.MANAGE_LOCAL_ACCOUNTS or ohos.permission.GET_LOCAL_ACCOUNTS +查询当前进程所属的系统帐号的帐号类型。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------------------------- | ---- | ------------ | -| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | - **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是和域帐号关联的系统帐号ID。 | +| 类型 | 说明 | +| ---------------------------------------------- | ----------------------------------------------- | +| Promise<[OsAccountType](#osaccounttype)> | Promise对象，返回当前进程所属的系统帐号的帐号类型。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; try { - accountManager.queryOsAccountLocalIdFromDomain(domainInfo).then((accountID) => { - console.log('queryOsAccountLocalIdFromDomain: ' + accountID); + accountManager.getOsAccountType().then((accountType) => { + console.log('getOsAccountType, accountType: ' + accountType); }).catch((err) => { - console.log('queryOsAccountLocalIdFromDomain err: ' + JSON.stringify(err)); + console.log('getOsAccountType err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('queryOsAccountLocalIdFromDomain exception: ' + JSON.stringify(e)); + console.log('getOsAccountType exception: ' + JSON.stringify(e)); } ``` -### getOsAccountLocalIdFromDomain(deprecated) - -getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo, callback: AsyncCallback<number>): void +### queryDistributedVirtualDeviceId9+ -根据域帐号信息，获取与其关联的系统帐号的帐号ID。 +queryDistributedVirtualDeviceId(callback: AsyncCallback<string>): void -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromDomain](#queryosaccountlocalidfromdomain9) -> -> 从 API version 8开始支持。 +获取分布式虚拟设备ID。使用callback异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -1507,160 +1803,195 @@ getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo, callback: AsyncCall **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------------------------- | ---- | -------------------------------------------- | -| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是和域帐号关联的系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------------------------------- | +| callback | AsyncCallback<string> | 是 | 回调函数。如果获取成功，err为null，data为分布式虚拟设备ID；否则为错误对象。 | **示例：** ```js - let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; let accountManager = account_osAccount.getAccountManager(); - accountManager.getOsAccountLocalIdFromDomain(domainInfo, (err, accountID) => { - console.log('getOsAccountLocalIdFromDomain: ' + JSON.stringify(err)); - console.log('getOsAccountLocalIdFromDomain: ' + accountID); - }); + try { + accountManager.queryDistributedVirtualDeviceId((err, virtualID) => { + console.log('queryDistributedVirtualDeviceId err: ' + JSON.stringify(err)); + console.log('queryDistributedVirtualDeviceId virtualID: ' + virtualID); + }); + } catch (e) { + console.log('queryDistributedVirtualDeviceId exception: ' + JSON.stringify(e)); + } ``` -### getOsAccountLocalIdFromDomain(deprecated) - -getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo): Promise<number> +### queryDistributedVirtualDeviceId9+ -根据域帐号信息，获取与其关联的系统帐号的帐号ID，使用Promise方式异步返回结果。 +queryDistributedVirtualDeviceId(): Promise<string> -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromDomain](#queryosaccountlocalidfromdomain9-1) -> -> 从 API version 8开始支持。 +获取分布式虚拟设备ID。使用Promise异步回调。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------------------------- | ---- | ------------ | -| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | - **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是和域帐号关联的系统帐号ID。 | +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| Promise<string> | Promise对象，返回分布式虚拟设备ID。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; - accountManager.getOsAccountLocalIdFromDomain(domainInfo).then((accountID) => { - console.log('getOsAccountLocalIdFromDomain: ' + accountID); - }).catch((err) => { - console.log('getOsAccountLocalIdFromDomain err: ' + JSON.stringify(err)); - }); + try { + accountManager.queryDistributedVirtualDeviceId().then((virtualID) => { + console.log('queryDistributedVirtualDeviceId, virtualID: ' + virtualID); + }).catch((err) => { + console.log('queryDistributedVirtualDeviceId err: ' + JSON.stringify(err)); + }); + } catch (e) { + console.log('queryDistributedVirtualDeviceId exception: ' + JSON.stringify(e)); + } ``` -### queryMaxOsAccountNumber +### getOsAccountProfilePhoto -queryMaxOsAccountNumber(callback: AsyncCallback<number>): void +getOsAccountProfilePhoto(localId: number, callback: AsyncCallback<string>): void -查询允许创建的系统帐号的最大数量，使用callback回调异步返回结果。 +获取指定系统帐号的头像信息。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------------ | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是允许创建的系统帐号的最大数量。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<string> | 是 | 回调函数。如果获取成功，err为null，data为指定系统帐号的头像信息；否则为错误对象。 | -**示例：** +**错误码：** +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 获取ID为100的系统帐号的头像 ```js let accountManager = account_osAccount.getAccountManager(); + let localId = 100; try { - accountManager.queryMaxOsAccountNumber((err, maxCnt)=>{ - console.log('queryMaxOsAccountNumber err:' + JSON.stringify(err)); - console.log('queryMaxOsAccountNumber maxCnt:' + maxCnt); + accountManager.getOsAccountProfilePhoto(localId, (err, photo)=>{ + console.log('getOsAccountProfilePhoto err:' + JSON.stringify(err)); + console.log('get photo:' + photo + ' by localId: ' + localId); }); } catch (e) { - console.log('queryMaxOsAccountNumber exception:' + JSON.stringify(e)); + console.log('getOsAccountProfilePhoto exception:' + JSON.stringify(e)); } ``` -### queryMaxOsAccountNumber +### getOsAccountProfilePhoto -queryMaxOsAccountNumber(): Promise<number> +getOsAccountProfilePhoto(localId: number): Promise<string> -查询允许创建的系统帐号的最大数量，使用Promise方式异步返回结果。 +获取指定系统帐号的头像信息。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------ | +| localId | number | 是 | 系统帐号ID。 | + **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是允许创建的系统帐号的最大数量。 | +| 类型 | 说明 | +| --------------------- | -------------------------------------- | +| Promise<string> | Promise对象，返回指定系统帐号的头像信息。 | -**示例：** +**错误码：** +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 获取ID为100的系统帐号的头像 ```js let accountManager = account_osAccount.getAccountManager(); + let localId = 100; try { - accountManager.queryMaxOsAccountNumber().then((maxCnt) => { - console.log('queryMaxOsAccountNumber, maxCnt: ' + maxCnt); + accountManager.getOsAccountProfilePhoto(localId).then((photo) => { + console.log('getOsAccountProfilePhoto: ' + photo); }).catch((err) => { - console.log('queryMaxOsAccountNumber err: ' + JSON.stringify(err)); + console.log('getOsAccountProfilePhoto err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('queryMaxOsAccountNumber exception:' + JSON.stringify(e)); + console.log('getOsAccountProfilePhoto exception:' + JSON.stringify(e)); } ``` -### getOsAccountConstraints9+ +### setOsAccountProfilePhoto -getOsAccountConstraints(localId: number, callback: AsyncCallback<Array<string>>): void +setOsAccountProfilePhoto(localId: number, photo: string, callback: AsyncCallback<void>): void + +为指定系统帐号设置头像信息。使用callback异步回调。 -获取指定系统帐号的全部约束，使用callback回调异步返回结果。 +**系统接口：** 此接口为系统接口。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<Array<string>> | 是 | 回调结果，返回的是该系统帐号的全部[约束](#系统帐号约束列表)。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------ | +| localId | number | 是 | 系统帐号ID。 | +| photo | string | 是 | 头像信息。 | +| callback | AsyncCallback<void> | 是 | 回调结果。 | + +**错误码：** +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | -**示例：** 获取ID为100的系统帐号的全部约束 +**示例：** 给ID为100的系统帐号设置头像 ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; + let photo = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA0AAAAPCAYAAAA/I0V3AAAAAXNSR0IArs4c6QAAAARnQU1BAA'+ + 'Cxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACwSURBVDhPvZLBDYMwDEV/ugsXRjAT0EHCOuFIBwkbdIRewi6unbiAyoGgSn1SFH85+Y'+ + 'q/4ljARW62X+LHS8uIzjm4dXUYF+utzBikB52Jo5e5iEPKqpACk7R9NM2RvWm5tIkD2czLCUFNKLD6IjdMHFHDzws285MgGrT0xCtp3WOKHo'+ + '+7q0mP0DZW9pNmoEFUzrQjp5cCnaen2kSJXLFD8ghbXyZCMQf/8e8Ns1XVAG/XAgqKzVnJFAAAAABJRU5ErkJggg==' try { - accountManager.getOsAccountConstraints(localId, (err, constraints)=>{ - console.log('getOsAccountConstraints err:' + JSON.stringify(err)); - console.log('getOsAccountConstraints:' + JSON.stringify(constraints)); + accountManager.setOsAccountProfilePhoto(localId, photo, (err)=>{ + console.log('setOsAccountProfilePhoto err:' + JSON.stringify(err)); }); } catch (e) { - console.log('getOsAccountConstraints exception:' + JSON.stringify(e)); + console.log('setOsAccountProfilePhoto exception:' + JSON.stringify(e)); } ``` -### getOsAccountConstraints9+ +### setOsAccountProfilePhoto -getOsAccountConstraints(localId: number): Promise<Array<string>> +setOsAccountProfilePhoto(localId: number, photo: string): Promise<void> + +为指定系统帐号设置头像信息。使用Promise异步回调。 -获取指定系统帐号的全部约束，使用Promise方式异步返回结果。 +**系统接口：** 此接口为系统接口。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount @@ -1669,291 +2000,339 @@ getOsAccountConstraints(localId: number): Promise<Array<string>> | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ------------ | | localId | number | 是 | 系统帐号ID。 | +| photo | string | 是 | 头像信息。 | **返回值：** -| 类型 | 说明 | -| :--------------------------------- | :----------------------------------------------------------- | -| Promise<Array<string>> | Promise实例，用于获取异步返回结果，返回的是该系统帐号的全部[约束](#系统帐号约束列表)。 | +| 类型 | 说明 | +| :------------------ | :----------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | -**示例：** 获取ID为100的系统帐号的全部约束 +**错误码：** +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | +| 12300004 | Restricted Account. | + +**示例：** 给ID为100的系统帐号设置头像 ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; + let photo = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA0AAAAPCAYAAAA/I0V3AAAAAXNSR0IArs4c6QAAAARnQU1BAA'+ + 'Cxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACwSURBVDhPvZLBDYMwDEV/ugsXRjAT0EHCOuFIBwkbdIRewi6unbiAyoGgSn1SFH85+Y'+ + 'q/4ljARW62X+LHS8uIzjm4dXUYF+utzBikB52Jo5e5iEPKqpACk7R9NM2RvWm5tIkD2czLCUFNKLD6IjdMHFHDzws285MgGrT0xCtp3WOKHo'+ + '+7q0mP0DZW9pNmoEFUzrQjp5cCnaen2kSJXLFD8ghbXyZCMQf/8e8Ns1XVAG/XAgqKzVnJFAAAAABJRU5ErkJggg==' try { - accountManager.getOsAccountConstraints(localId).then((constraints) => { - console.log('getOsAccountConstraints, constraints: ' + constraints); + accountManager.setOsAccountProfilePhoto(localId, photo).then(() => { + console.log('setOsAccountProfilePhoto success'); }).catch((err) => { - console.log('getOsAccountConstraints err: ' + JSON.stringify(err)); + console.log('setOsAccountProfilePhoto err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('getOsAccountConstraints exception:' + JSON.stringify(e)); + console.log('setOsAccountProfilePhoto exception:' + JSON.stringify(e)); } ``` -### getOsAccountAllConstraints(deprecated) - -getOsAccountAllConstraints(localId: number, callback: AsyncCallback<Array<string>>): void - -获取指定系统帐号的全部约束，使用callback回调异步返回结果。 +### queryOsAccountLocalIdBySerialNumber9+ -> **说明：** 从API version 9开始废弃，建议使用[getOsAccountConstraints](#getosaccountconstraints9) -> -> 从 API version 7开始支持。 +queryOsAccountLocalIdBySerialNumber(serialNumber: number, callback: AsyncCallback<number>): void -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +通过SN码查询与其关联的系统帐号的帐号ID。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<Array<string>> | 是 | 回调结果，返回的是该系统帐号的全部[约束](#系统帐号约束列表)。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------- | ---- | ---------------------------------------------------------------------------- | +| serialNumber | number | 是 | 帐号SN码。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果成功，err为null，data为与SN码关联的系统帐号的帐号ID；否则为错误对象。 | -**示例：** 获取ID为100的系统帐号的全部约束 +**错误码：** +| 错误码ID | 错误信息 | +| 12300002 | Invalid serialNumber. | + +**示例：** 查询与SN码12345关联的系统帐号的ID ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - accountManager.getOsAccountAllConstraints(localId, (err, constraints)=>{ - console.log('getOsAccountAllConstraints err:' + JSON.stringify(err)); - console.log('getOsAccountAllConstraints:' + JSON.stringify(constraints)); - }); + let serialNumber = 12345; + try { + accountManager.queryOsAccountLocalIdBySerialNumber(serialNumber, (err, localId)=>{ + console.log('ger localId err:' + JSON.stringify(err)); + console.log('get localId:' + localId + ' by serialNumber: ' + serialNumber); + }); + } catch (e) { + console.log('ger localId exception:' + JSON.stringify(e)); + } ``` -### getOsAccountAllConstraints(deprecated) - -getOsAccountAllConstraints(localId: number): Promise<Array<string>> - -> **说明：** 从API version 9开始废弃，建议使用[getOsAccountConstraints](#getosaccountconstraints9-1) -> -> 从 API version 7开始支持。 +### queryOsAccountLocalIdBySerialNumber9+ -获取指定系统帐号的全部约束，使用Promise方式异步返回结果。 +queryOsAccountLocalIdBySerialNumber(serialNumber: number): Promise<number> -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +通过SN码查询与其关联的系统帐号的帐号ID。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ------ | ---- | ---------- | +| serialNumber | number | 是 | 帐号SN码。 | **返回值：** -| 类型 | 说明 | -| :--------------------------------- | :----------------------------------------------------------- | -| Promise<Array<string>> | Promise实例，用于获取异步返回结果，返回的是该系统帐号的全部[约束](#系统帐号约束列表)。 | +| 类型 | 说明 | +| :-------------------- | :------------------- ----------------------- | +| Promise<number> | Promise对象，返回与SN码关联的系统帐号的帐号ID。 | -**示例：** 获取ID为100的系统帐号的全部约束 +**错误码：** +| 错误码ID | 错误信息 | +| 12300002 | Invalid serialNumber. | + +**示例：** 查询与SN码12345关联的系统帐号的ID ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - accountManager.getOsAccountAllConstraints(localId).then((constraints) => { - console.log('getOsAccountAllConstraints, constraints: ' + constraints); - }).catch((err) => { - console.log('getOsAccountAllConstraints err: ' + JSON.stringify(err)); - }); + let serialNumber = 12345; + try { + accountManager.queryOsAccountLocalIdBySerialNumber(serialNumber).then((localId) => { + console.log('queryOsAccountLocalIdBySerialNumber localId: ' + localId); + }).catch((err) => { + console.log('queryOsAccountLocalIdBySerialNumber err: ' + JSON.stringify(err)); + }); + } catch (e) { + console.log('queryOsAccountLocalIdBySerialNumber exception: ' + JSON.stringify(e)); + } ``` -### queryAllCreatedOsAccounts - -queryAllCreatedOsAccounts(callback: AsyncCallback<Array<OsAccountInfo>>): void +### querySerialNumberByOsAccountLocalId9+ -查询已创建的所有系统帐号的信息列表，使用callback回调异步返回结果。 +querySerialNumberByOsAccountLocalId(localId: number, callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +通过系统帐号ID获取与该系统帐号关联的SN码。使用callback异步回调。 **系统能力：** SystemCapability.Account.OsAccount -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS - **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------- | -| callback | AsyncCallback<Array<[OsAccountInfo](#osaccountinfo)>> | 是 | 回调结果，返回的是已创建的所有系统帐号的信息列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果获取成功，err为null，data为与该系统帐号关联的SN码；否则为错误对象。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 获取ID为100的系统帐号关联的SN码 ```js let accountManager = account_osAccount.getAccountManager(); + let localId = 100; try { - accountManager.queryAllCreatedOsAccounts((err, accountArr)=>{ - console.log('queryAllCreatedOsAccounts err:' + JSON.stringify(err)); - console.log('queryAllCreatedOsAccounts accountArr:' + JSON.stringify(accountArr)); + accountManager.querySerialNumberByOsAccountLocalId(localId, (err, serialNumber)=>{ + console.log('ger serialNumber err:' + JSON.stringify(err)); + console.log('get serialNumber:' + serialNumber + ' by localId: ' + localId); }); } catch (e) { - console.log('queryAllCreatedOsAccounts exception:' + JSON.stringify(e)); + console.log('ger serialNumber exception:' + JSON.stringify(e)); } ``` -### queryAllCreatedOsAccounts - -queryAllCreatedOsAccounts(): Promise<Array<OsAccountInfo>> +### querySerialNumberByOsAccountLocalId9+ -查询已创建的所有系统帐号的信息列表，使用Promise方式异步返回结果。 +querySerialNumberByOsAccountLocalId(localId: number): Promise<number> -此接口为系统接口，三方应用不支持调用。 +通过系统帐号ID获取与该系统帐号关联的SN码。使用Promise异步回调。 **系统能力：** SystemCapability.Account.OsAccount -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ----------- | +| localId | number | 是 | 系统帐号ID。 | **返回值：** -| 类型 | 说明 | -| :---------------------------------------------------------- | :----------------------------------------------------------- | -| Promise<Array<[OsAccountInfo](#osaccountinfo)>> | Promise实例，用于获取异步返回结果，返回的是已创建的所有系统帐号的信息列表。 | +| 类型 | 说明 | +| :-------------------- | :------------------------------------- | +| Promise<number> | Promise对象，返回与该系统帐号关联的SN码。 | -**示例：** +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 12300002 | Invalid localId. | +| 12300003 | Account not exists. | + +**示例：** 获取ID为100的系统帐号关联的SN码 ```js let accountManager = account_osAccount.getAccountManager(); + let localId = 100; try { - accountManager.queryAllCreatedOsAccounts().then((accountArr) => { - console.log('queryAllCreatedOsAccounts, accountArr: ' + JSON.stringify(accountArr)); + accountManager.querySerialNumberByOsAccountLocalId(localId).then((serialNumber) => { + console.log('querySerialNumberByOsAccountLocalId serialNumber: ' + serialNumber); }).catch((err) => { - console.log('queryAllCreatedOsAccounts err: ' + JSON.stringify(err)); + console.log('querySerialNumberByOsAccountLocalId err: ' + JSON.stringify(err)); }); } catch (e) { - console.log('queryAllCreatedOsAccounts exception:' + JSON.stringify(e)); + console.log('querySerialNumberByOsAccountLocalId exception:' + JSON.stringify(e)); } ``` -### getActivatedOsAccountIds9+ +### on -getActivatedOsAccountIds(callback: AsyncCallback<Array<number>>): void +on(type: 'activate' | 'activating', name: string, callback: Callback<number>): void + +订阅系统帐号的变动信息。使用callback异步回调。 -查询当前处于激活状态的系统帐号的ID列表，使用callback回调异步返回结果。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ------------------------------------------------------ | -| callback | AsyncCallback<Array<number>> | 是 | 回调结果，返回的是当前处于激活状态的系统帐号的ID列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------- | ---- | ------------------------------------------------------------ | +| type | 'activate' \| 'activating' | 是 | 订阅类型，activate表示订阅的是帐号已激活完成的事件，activating表示订阅的是帐号正在激活的事件。 | +| name | string | 是 | 订阅名称，可自定义，要求非空且长度不超过1024字节。 | +| callback | Callback<number> | 是 | 订阅系统帐号变动信息的回调，表示当前事件对应的系统帐号ID。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); + function onCallback(receiveLocalId){ + console.log('receive localId:' + receiveLocalId); + } try { - accountManager.getActivatedOsAccountIds((err, idArray)=>{ - console.log('getActivatedOsAccountIds err:' + JSON.stringify(err)); - console.log('getActivatedOsAccountIds idArray length:' + idArray.length); - for(let i=0;i9+ +### off -getActivatedOsAccountIds(): Promise<Array<number>> +off(type: 'activate' | 'activating', name: string, callback?: Callback<number>): void + +取消订阅系统帐号的变动信息。使用callback异步回调。 -查询当前处于激活状态的系统帐号的ID列表，使用Promise方式异步返回结果。 +**系统接口：** 此接口为系统接口。 + +**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION **系统能力：** SystemCapability.Account.OsAccount -**返回值：** +**参数：** -| 类型 | 说明 | -| :--------------------------------- | :----------------------------------------------------------- | -| Promise<Array<number>> | Promise实例，用于获取异步返回结果，返回的是当前处于激活状态的系统帐号的ID列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------- | ---- | ------------------------------------------------------------ | +| type | 'activate' \| 'activating' | 是 | 取消订阅类型，activate表示取消订阅帐号已激活完成的事件，activating取消订阅帐号正在激活的事件。 | +| name | string | 是 | 订阅名称，可自定义，，要求非空且长度不超过1024字节，需要与订阅接口传入的值保持一致。 | +| callback | Callback<number> | 否 | 取消订阅系统帐号变化的回调，默认返回0。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); + function offCallback(){ + console.log('off enter') + } try { - accountManager.getActivatedOsAccountIds().then((idArray) => { - console.log('getActivatedOsAccountIds, idArray: ' + idArray); - }).catch((err) => { - console.log('getActivatedOsAccountIds err: ' + JSON.stringify(err)); - }); + accountManager.off('activating', 'osAccountOnOffNameA', offCallback); } catch (e) { - console.log('getActivatedOsAccountIds exception:' + JSON.stringify(e)); + console.log('off exception:' + JSON.stringify(e)); } ``` -### queryActivatedOsAccountIds(deprecated) +### getBundleIdFromUid9+ -queryActivatedOsAccountIds(callback: AsyncCallback<Array<number>>): void +getBundleIdFromUid(uid: number, callback: AsyncCallback<number>): void; -查询当前处于激活状态的系统帐号的ID列表，使用callback回调异步返回结果。 +通过uid查询对应的bundleId，使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[getActivatedOsAccountIds](#getactivatedosaccountids9) -> -> 从 API version 8开始支持。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ------------------------------------------------------ | -| callback | AsyncCallback<Array<number>> | 是 | 回调结果，返回的是当前处于激活状态的系统帐号的ID列表。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------------------------------------------ | +| uid | number | 是 | 进程uid。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果查询成功，err为null，data为与uid对应的bundleId；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.queryActivatedOsAccountIds((err, idArray)=>{ - console.log('queryActivatedOsAccountIds err:' + JSON.stringify(err)); - console.log('queryActivatedOsAccountIds idArray length:' + idArray.length); - for(let i=0;i { + console.info('getBundleIdFromUid errInfo:' + JSON.stringify(err)); + console.info('getBundleIdFromUid bundleId:' + JSON.stringify(bundleId)); + }); + } catch (e) { + console.info('getBundleIdFromUid exception:' + JSON.stringify(e)); + } ``` +### getBundleIdFromUid9+ -### queryActivatedOsAccountIds(deprecated) - -queryActivatedOsAccountIds(): Promise<Array<number>> +getBundleIdFromUid(uid: number): Promise<number>; -> **说明：** 从API version 9开始废弃，建议使用[getActivatedOsAccountIds](#getactivatedosaccountids9-1) -> -> 从 API version 8开始支持。 +通过uid查询对应的bundleId，使用Promis异步回调。 -查询当前处于激活状态的系统帐号的ID列表，使用Promise方式异步返回结果。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------ | +| uid | number | 是 | 进程uid。 | + **返回值：** -| 类型 | 说明 | -| :--------------------------------- | :----------------------------------------------------------- | -| Promise<Array<number>> | Promise实例，用于获取异步返回结果，返回的是当前处于激活状态的系统帐号的ID列表。 | +| 类型 | 说明 | +| --------------------- | ------------------------------------ | +| Promise<number> | Promise对象，返回与uid对应的bundleId。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.queryActivatedOsAccountIds().then((idArray) => { - console.log('queryActivatedOsAccountIds, idArray: ' + idArray); - }).catch((err) => { - console.log('queryActivatedOsAccountIds err: ' + JSON.stringify(err)); - }); - ``` - -### createOsAccount + let testUid = 1000000; + try { + accountManager.getBundleIdFromUid(testUid).then((result) => { + console.info('getBundleIdFromUid bundleId:' + JSON.stringify(result)); + }).catch((err)=>{ + console.info('getBundleIdFromUid errInfo:' + JSON.stringify(err)); + }); + } catch (e) { + console.info('getBundleIdFromUid exception:' + JSON.stringify(e)); + } + ``` -createOsAccount(localName: string, type: OsAccountType, callback: AsyncCallback<OsAccountInfo>): void +### isMainOsAccount9+ + +isMainOsAccount(callback: AsyncCallback<boolean>): void; -创建一个系统帐号，使用callback回调异步返回结果。 +查询当前进程是否处于主用户，使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -1961,73 +2340,62 @@ createOsAccount(localName: string, type: OsAccountType, callback: AsyncCallback& **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| :-------- | ---------------------------------------------------- | ---- | ------------------------------------------ | -| localName | string | 是 | 创建的系统帐号的名称。 | -| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | -| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调结果，返回的是新创建的系统帐号的信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ----------------------------------------------------------------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回true表示当前帐号为主帐号，返回false表示当前帐号非主帐号。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.createOsAccount('testName', account_osAccount.OsAccountType.NORMAL, (err, osAccountInfo)=>{ - console.log('createOsAccount err:' + JSON.stringify(err)); - console.log('createOsAccount osAccountInfo:' + JSON.stringify(osAccountInfo)); + accountManager.isMainOsAccount((err,result)=>{ + console.info('isMainOsAccount errInfo:' + JSON.stringify(err)); + console.info('isMainOsAccount result:' + JSON.stringify(result)); }); } catch (e) { - console.log('createOsAccount exception:' + JSON.stringify(e)); + console.info('isMainOsAccount exception:' + JSON.stringify(e)); } ``` +### isMainOsAccount9+ -### createOsAccount - -createOsAccount(localName: string, type: OsAccountType): Promise<OsAccountInfo> +isMainOsAccount(): Promise<boolean>; -创建一个系统帐号，使用Promise方式异步返回结果。 +查询当前进程是否处于主用户，使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------------------------------- | ---- | ---------------------- | -| localName | string | 是 | 创建的系统帐号的名称。 | -| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | - **返回值：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountInfo](#osaccountinfo)> | Promise实例，用于获取异步返回结果，返回的是新创建的系统帐号的信息。 | +| 类型 | 说明 | +| ---------------------- | --------------------------------------------------------------------- | +| Promise<boolean> | Promise对象，返回true表示当前帐号为主帐号，返回false表示当前帐号非主帐号。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); try { - accountManager.createOsAccount('testAccountName', account_osAccount.OsAccountType.NORMAL).then((accountInfo) => { - console.log('createOsAccount, accountInfo: ' + JSON.stringify(accountInfo)); - }).catch((err) => { - console.log('createOsAccount err: ' + JSON.stringify(err)); + accountManager.isMainOsAccount().then((result) => { + console.info('isMainOsAccount result:' + JSON.stringify(result)); + }).catch((err)=>{ + console.info('isMainOsAccount errInfo:' + JSON.stringify(err)); }); } catch (e) { - console.log('createOsAccount exception:' + JSON.stringify(e)); + console.info('isMainOsAccount exception:' + JSON.stringify(e)); } ``` +### queryOsAccountConstraintSourceTypes9+ -### createOsAccountForDomain8+ - -createOsAccountForDomain(type: OsAccountType, domainInfo: DomainAccountInfo, callback: AsyncCallback<OsAccountInfo>): void +queryOsAccountConstraintSourceTypes(localId: number, constraint: string, callback: AsyncCallback<Array<ConstraintSourceTypeInfo>>): void; -根据域帐号信息，创建一个系统帐号并将其与域帐号关联，使用callback回调异步返回结果。 +查询指定系统帐号的指定约束来源信息，使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -2035,34 +2403,33 @@ createOsAccountForDomain(type: OsAccountType, domainInfo: DomainAccountInfo, cal **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| :--------- | ---------------------------------------------------- | ---- | ------------------------------------------ | -| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | -| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | -| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调结果，返回的是新创建的系统帐号的信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------- | ---- | ------------------------------------------------------------ | +| localId | number | 是 | 要查询的系统帐号ID | +| constraint | string | 是 | 要查询的[约束](#系统帐号约束列表)名称 | +| callback | AsyncCallback<Array<[ConstraintSourceTypeInfo](#constraintsourcetypeinfo)>> | 是 | 回调函数。如果成功，err为null，data为指定系统帐号的指定[约束](#系统帐号约束列表)来源信息；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; try { - accountManager.createOsAccountForDomain(account_osAccount.OsAccountType.NORMAL, domainInfo, (err, osAccountInfo)=>{ - console.log('createOsAccountForDomain err:' + JSON.stringify(err)); - console.log('createOsAccountForDomain osAccountInfo:' + JSON.stringify(osAccountInfo)); + accountManager.queryOsAccountConstraintSourceTypes(100, 'constraint.wifi',(err,sourceTypeInfos)=>{ + console.info('queryOsAccountConstraintSourceType errInfo:' + JSON.stringify(err)); + console.info('queryOsAccountConstraintSourceType sourceTypeInfos:' + JSON.stringify(sourceTypeInfos)); }); } catch (e) { - console.log('createOsAccountForDomain exception:' + JSON.stringify(e)); + console.info('queryOsAccountConstraintSourceType exception:' + JSON.stringify(e)); } ``` -### createOsAccountForDomain8+ +### queryOsAccountConstraintSourceTypes9+ -createOsAccountForDomain(type: OsAccountType, domainInfo: DomainAccountInfo): Promise<OsAccountInfo> +queryOsAccountConstraintSourceTypes(localId: number, constraint: string): Promise<Array<ConstraintSourceTypeInfo>>; -根据传入的域帐号信息，创建与其关联的系统帐号，使用Promise方式异步返回结果。 +查询指定系统帐号的指定约束来源信息，使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS @@ -2070,293 +2437,310 @@ createOsAccountForDomain(type: OsAccountType, domainInfo: DomainAccountInfo): Pr **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------------------------- | ---- | ---------------------- | -| type | [OsAccountType](#osaccounttype) | 是 | 创建的系统帐号的类型。 | -| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------ | +| localId | number | 是 | 要查询的系统帐号ID | +| constraint | string | 是 | 要查询的[约束](#系统帐号约束列表)名称 | **返回值：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountInfo](#osaccountinfo)> | Promise实例，用于获取异步返回结果，返回的是新创建的系统帐号的信息。 | +| 类型 | 说明 | +| :-------------------- | :----------------------------------------------------------- | +| Promise<Array<[ConstraintSourceTypeInfo](#constraintsourcetypeinfo)>> | Promise对象，返回指定系统帐号的指定[约束](#系统帐号约束列表)来源信息。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; try { - accountManager.createOsAccountForDomain(account_osAccount.OsAccountType.NORMAL, domainInfo).then((accountInfo) => { - console.log('createOsAccountForDomain, account info: ' + JSON.stringify(accountInfo)); - }).catch((err) => { - console.log('createOsAccountForDomain err: ' + JSON.stringify(err)); + accountManager.queryOsAccountConstraintSourceTypes(100, 'constraint.wifi').then((result) => { + console.info('queryOsAccountConstraintSourceType sourceTypeInfos:' + JSON.stringify(result)); + }).catch((err)=>{ + console.info('queryOsAccountConstraintSourceType errInfo:' + JSON.stringify(err)); }); } catch (e) { - console.log('createOsAccountForDomain exception:' + JSON.stringify(e)); + console.info('queryOsAccountConstraintSourceType exception:' + JSON.stringify(e)); } ``` -### getCurrentOsAccount9+ +### isMultiOsAccountEnable(deprecated) -getCurrentOsAccount(callback: AsyncCallback<OsAccountInfo>): void +isMultiOsAccountEnable(callback: AsyncCallback<boolean>): void -查询当前进程所属的系统帐号的信息，使用callback回调异步返回结果。 +判断是否支持多系统帐号。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[checkMultiOsAccountEnabled](#checkmultiosaccountenabled9) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | -| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调结果，返回的是当前进程所属的系统帐号信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------ | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示支持多系统帐号；返回false表示不支持。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.getCurrentOsAccount((err, curAccountInfo)=>{ - console.log('getCurrentOsAccount err:' + JSON.stringify(err)); - console.log('getCurrentOsAccount curAccountInfo:' + JSON.stringify(curAccountInfo)); - }); - } catch (e) { - console.log('getCurrentOsAccount exception:' + JSON.stringify(e)); - } + accountManager.isMultiOsAccountEnable((err, isEnalbed) => { + if (err) { + console.log("isMultiOsAccountEnable failed, error: " + JSON.stringify(err)); + } else { + console.log("isMultiOsAccountEnable successfully, isEnabled: " + isEnabled); + } + }); ``` -### getCurrentOsAccount9+ +### isMultiOsAccountEnable(deprecated) -getCurrentOsAccount(): Promise<OsAccountInfo> +isMultiOsAccountEnable(): Promise<boolean> -查询当前进程所属的系统帐号的信息，使用Promise方式异步返回结果。 +判断是否支持多系统帐号。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[checkMultiOsAccountEnabled](#checkmultiosaccountenabled9-1) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountInfo](#osaccountinfo)> | Promise实例，用于获取异步返回结果，返回的是当前进程所属的系统帐号信息。 | +| 类型 | 说明 | +| :--------------------- | :--------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示支持多系统帐号；返回false表示不支持。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.getCurrentOsAccount().then((accountInfo) => { - console.log('getCurrentOsAccount, accountInfo: ' + JSON.stringify(accountInfo)); - }).catch((err) => { - console.log('getCurrentOsAccount err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('getCurrentOsAccount exception:' + JSON.stringify(e)); - } + accountManager.isMultiOsAccountEnable().then((isEnabled) => { + console.log('isMultiOsAccountEnable successfully, isEnabled: ' + isEnabled); + }).catch((err) => { + console.log('isMultiOsAccountEnable failed, error: ' + JSON.stringify(err)); + }); ``` -### queryCurrentOsAccount(deprecated) -queryCurrentOsAccount(callback: AsyncCallback<OsAccountInfo>): void +### isOsAccountActived(deprecated) -查询当前进程所属的系统帐号的信息，使用callback回调异步返回结果。 +isOsAccountActived(localId: number, callback: AsyncCallback<boolean>): void -> **说明：** 从API version 9开始废弃，建议使用[getCurrentOsAccount](#getcurrentosaccount9) +判断指定系统帐号是否处于激活状态。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃, 建议使用[checkOsAccountActivated](#checkosaccountactivated9) > > 从 API version 7开始支持。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | -| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调结果，返回的是当前进程所属的系统帐号信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------ | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示帐号已激活；返回false表示帐号未激活。 | -**示例：** +**示例：** 判断ID为100的系统帐号是否处于激活状态 ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.queryCurrentOsAccount((err, curAccountInfo)=>{ - console.log('queryCurrentOsAccount err:' + JSON.stringify(err)); - console.log('queryCurrentOsAccount curAccountInfo:' + JSON.stringify(curAccountInfo)); + let localId = 100; + accountManager.isOsAccountActived(localId, (err, isActived) => { + if (err) { + console.log('isOsAccountActived failed, err:' + JSON.stringify(err)); + } else { + console.log('isOsAccountActived successfully, isActived:' + isActived); + } }); ``` -### queryCurrentOsAccount(deprecated) +### isOsAccountActived(deprecated) -queryCurrentOsAccount(): Promise<OsAccountInfo> +isOsAccountActived(localId: number): Promise<boolean> -查询当前进程所属的系统帐号的信息，使用Promise方式异步返回结果。 +判断指定系统帐号是否处于激活状态。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[getCurrentOsAccount](#getcurrentosaccount9-1) +> **说明：** 从API version 9开始废弃, 建议使用[checkOsAccountActivated](#checkosaccountactivated9-1) > > 从 API version 7开始支持。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | --------------------------------- | +| localId | number | 是 | 系统帐号ID。 | + **返回值：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountInfo](#osaccountinfo)> | Promise实例，用于获取异步返回结果，返回的是当前进程所属的系统帐号信息。 | +| 类型 | 说明 | +| --------------------- | ----------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示帐号已激活；返回false表示帐号未激活。 | -**示例：** +**示例：** 判断ID为100的系统帐号是否处于激活状态 ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.queryCurrentOsAccount().then((accountInfo) => { - console.log('queryCurrentOsAccount, accountInfo: ' + JSON.stringify(accountInfo)); + let localId = 100; + accountManager.isOsAccountActived(localId).then((isActived) => { + console.log('isOsAccountActived successfully, isActived: ' + isActived); }).catch((err) => { - console.log('queryCurrentOsAccount err: ' + JSON.stringify(err)); + console.log('isOsAccountActived failed, error: ' + JSON.stringify(err)); }); ``` -### queryOsAccountById +### isOsAccountConstraintEnable(deprecated) -queryOsAccountById(localId: number, callback: AsyncCallback<OsAccountInfo>): void +isOsAccountConstraintEnable(localId: number, constraint: string, callback: AsyncCallback<boolean>): void -查询指定系统帐号的信息，使用callback回调异步返回结果。 +判断指定系统帐号是否具有指定约束。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +> **说明：** 从API version 9开始废弃，建议使用[checkConstraintEnabled](#checkconstraintenabled9) +> +> 从 API version 7开始支持。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ---------------------------------------- | -| localId | number | 是 | 要查询的系统帐号的ID | -| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调结果，返回的是查到的系统帐号的信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------- | ---- | ----------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示已使能指定的约束；返回false表示未使能指定的约束。 | -**示例：** 查询ID为100的系统帐号信息 +**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; - try { - accountManager.queryOsAccountById(localId, (err, accountInfo)=>{ - console.log('queryOsAccountById err:' + JSON.stringify(err)); - console.log('queryOsAccountById accountInfo:' + JSON.stringify(accountInfo)); - }); - } catch (e) { - console.log('queryOsAccountById exception:' + JSON.stringify(e)); - } + let constraint = "constraint.wifi"; + accountManager.isOsAccountConstraintEnable(localId, constraint, (err, isEnabled) => { + if (err) { + console.log("isOsAccountConstraintEnable failed, error:" + JSON.stringify(err)); + } else { + console.log("isOsAccountConstraintEnable successfully, isEnabled:" + isEnabled); + } + }); ``` -### queryOsAccountById +### isOsAccountConstraintEnable(deprecated) -queryOsAccountById(localId: number): Promise<OsAccountInfo> +isOsAccountConstraintEnable(localId: number, constraint: string): Promise<boolean> -查询指定系统帐号的信息，使用Promise方式异步返回结果。 +判断指定系统帐号是否具有指定约束。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +> **说明：** 从API version 9开始废弃，建议使用[checkConstraintEnabled](#checkconstraintenabled9-1) +> +> 从 API version 7开始支持。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | -------------------- | -| localId | number | 是 | 要查询的系统帐号的ID | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ---------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| constraint | string | 是 | 指定的[约束](#系统帐号约束列表)名称。 | **返回值：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountInfo](#osaccountinfo)> | Promise实例，用于获取异步返回结果，返回的是查到的系统帐号的信息。 | +| 类型 | 说明 | +| ---------------------- | --------------------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示已使能指定的约束；返回false表示未使能指定的约束。 | -**示例：** 查询ID为100的系统帐号信息 +**示例：** 判断ID为100的系统帐号是否有禁止使用Wi-Fi的约束 ```js let accountManager = account_osAccount.getAccountManager(); let localId = 100; - try { - accountManager.queryOsAccountById(localId).then((accountInfo) => { - console.log('queryOsAccountById, accountInfo: ' + JSON.stringify(accountInfo)); - }).catch((err) => { - console.log('queryOsAccountById err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('queryOsAccountById exception:' + JSON.stringify(e)); - } + let constraint = "constraint.wifi"; + accountManager.isOsAccountConstraintEnable(localId, constraint).then((isEnabled) => { + console.log("isOsAccountConstraintEnable successfully, isEnabled: " + isEnabled); + }).catch((err) => { + console.log("isOsAccountConstraintEnable err: " + JSON.stringify(err)); + }); ``` -### getOsAccountType9+ +### isTestOsAccount(deprecated) -getOsAccountType(callback: AsyncCallback<OsAccountType>): void +isTestOsAccount(callback: AsyncCallback<boolean>): void -查询当前进程所属的系统帐号的帐号类型，使用callback回调异步返回结果。 +检查当前系统帐号是否为测试帐号。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃，建议使用[checkOsAccountTestable](#checkosaccounttestable9) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------------- | -| callback | AsyncCallback<[OsAccountType](#osaccounttype)> | 是 | 回调结果，返回的是当前进程所属的系统帐号的帐号类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | --------------------------------------------------------------------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前帐号为测试帐号；返回false表示当前帐号非测试帐号。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.getOsAccountType((err, accountType) => { - console.log('getOsAccountType err: ' + JSON.stringify(err)); - console.log('getOsAccountType accountType: ' + accountType); - }); - } catch (e) { - console.log('getOsAccountType exception: ' + JSON.stringify(e)); - } + accountManager.isTestOsAccount((err, isTestable) => { + if (err) { + console.log("isTestOsAccount failed, error: " + JSON.stringify(err)); + } else { + console.log("isTestOsAccount successfully, isTestable: " + isTestable); + } + }); ``` -### getOsAccountType9+ +### isTestOsAccount(deprecated) -getOsAccountType(): Promise<OsAccountType> +isTestOsAccount(): Promise<boolean> + +检查当前系统帐号是否为测试帐号。使用Promise异步回调。 -查询当前进程所属的系统帐号的帐号类型，使用Promise方式异步返回结果。 +> **说明：** 从API version 9开始废弃，建议使用[checkOsAccountTestable](#checkosaccounttestable9-1) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountType](#osaccounttype)> | Promise实例，用于获取异步返回结果，返回的是当前进程所属的系统帐号的帐号类型。 | +| 类型 | 说明 | +| ---------------------- | ------------------------------------------------------------------------ | +| Promise<boolean> | Promise对象。返回true表示当前帐号为测试帐号；返回false表示当前帐号非测试帐号。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.getOsAccountType().then((accountType) => { - console.log('getOsAccountType, accountType: ' + accountType); - }).catch((err) => { - console.log('getOsAccountType err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('getOsAccountType exception: ' + JSON.stringify(e)); - } + accountManager.isTestOsAccount().then((isTestable) => { + console.log("isTestOsAccount successfully, isTestable: " + isTestable); + }).catch((err) => { + console.log("isTestOsAccount failed, error: " + JSON.stringify(err)); + }); ``` -### getOsAccountTypeFromProcess(deprecated) +### isOsAccountVerified(deprecated) -getOsAccountTypeFromProcess(callback: AsyncCallback<OsAccountType>): void +isOsAccountVerified(callback: AsyncCallback<boolean>): void -查询当前进程所属的系统帐号的帐号类型，使用callback回调异步返回结果。 +检查当前系统帐号是否已验证。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[getOsAccountType](#getosaccounttype9) +> **说明：** 从API version 9开始废弃，建议使用[checkOsAccountVerified](#checkosaccountverified9) > > 从 API version 7开始支持。 @@ -2364,871 +2748,807 @@ getOsAccountTypeFromProcess(callback: AsyncCallback<OsAccountType>): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------------- | -| callback | AsyncCallback<[OsAccountType](#osaccounttype)> | 是 | 回调结果，返回的是当前进程所属的系统帐号的帐号类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------------- | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示指定帐号已验证；返回false表示指定帐号未验证。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getOsAccountTypeFromProcess((err, accountType) => { - console.log('getOsAccountTypeFromProcess err: ' + JSON.stringify(err)); - console.log('getOsAccountTypeFromProcess accountType: ' + accountType); + accountManager.isOsAccountVerified((err, isVerified) => { + if (err) { + console.log("isOsAccountVerified failed, error: " + JSON.stringify(err)); + } else { + console.log("isOsAccountVerified successfully, isVerified: " + isVerified); + } }); ``` -### getOsAccountTypeFromProcess(deprecated) +### isOsAccountVerified(deprecated) -getOsAccountTypeFromProcess(): Promise<OsAccountType> +isOsAccountVerified(localId: number, callback: AsyncCallback<boolean>): void -查询当前进程所属的系统帐号的帐号类型，使用Promise方式异步返回结果。 +检查指定系统帐号是否已验证。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[getOsAccountType](#getosaccounttype9-1) +> **说明：** 从API version 9开始废弃，建议使用[checkOsAccountVerified](#checkosaccountverified9-1) > > 从 API version 7开始支持。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + **系统能力：** SystemCapability.Account.OsAccount -**返回值：** +**参数：** -| 类型 | 说明 | -| :--------------------------------------------- | :----------------------------------------------------------- | -| Promise<[OsAccountType](#osaccounttype)> | Promise实例，用于获取异步返回结果，返回的是当前进程所属的系统帐号的帐号类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------------- | +| localId | number | 否 | 系统帐号ID。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示指定帐号已验证；返回false表示指定帐号未验证。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getOsAccountTypeFromProcess().then((accountType) => { - console.log('getOsAccountTypeFromProcess, accountType: ' + accountType); - }).catch((err) => { - console.log('getOsAccountTypeFromProcess err: ' + JSON.stringify(err)); + let localId = 100; + accountManager.isOsAccountVerified(localId, (err, isVerified) => { + if (err) { + console.log("isOsAccountVerified failed, error: " + JSON.stringify(err)); + } else { + console.log("isOsAccountVerified successfully, isVerified: " + isVerified); + } }); ``` -### queryDistributedVirtualDeviceId9+ +### isOsAccountVerified(deprecated) -queryDistributedVirtualDeviceId(callback: AsyncCallback<string>): void +isOsAccountVerified(localId?: number): Promise<boolean> -获取分布式虚拟设备ID，使用callback回调异步返回结果。 +检查指定系统帐号是否已验证。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS or ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[checkOsAccountVerified](#checkosaccountverified9-2) +> +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------ | -| callback | AsyncCallback<string> | 是 | 回调结果，返回的是分布式虚拟设备ID。 | - -**示例：** - - ```js - let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.queryDistributedVirtualDeviceId((err, virtualID) => { - console.log('queryDistributedVirtualDeviceId err: ' + JSON.stringify(err)); - console.log('queryDistributedVirtualDeviceId virtualID: ' + virtualID); - }); - } catch (e) { - console.log('queryDistributedVirtualDeviceId exception: ' + JSON.stringify(e)); - } - ``` - -### queryDistributedVirtualDeviceId9+ - -queryDistributedVirtualDeviceId(): Promise<string> - -获取分布式虚拟设备ID，使用Promise方式异步返回结果。 - -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS - -**系统能力：** SystemCapability.Account.OsAccount +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------------------------------------------------------- | +| localId | number | 否 | 系统帐号ID。不填则检查当前系统帐号是否已验证。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果，返回的是分布式虚拟设备ID。 | +| 类型 | 说明 | +| ---------------------- | ----------------------------------------------------------------- | +| Promise<boolean> | Promise对象。返回true表示指定帐号已验证；返回false表示指定帐号未验证。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.queryDistributedVirtualDeviceId().then((virtualID) => { - console.log('queryDistributedVirtualDeviceId, virtualID: ' + virtualID); - }).catch((err) => { - console.log('queryDistributedVirtualDeviceId err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('queryDistributedVirtualDeviceId exception: ' + JSON.stringify(e)); - } + accountManager.isOsAccountVerified(localId).then((isVerified) => { + console.log("isOsAccountVerified successfully, isVerified: " + isVerified); + }).catch((err) => { + console.log("isOsAccountVerified failed, error: " + JSON.stringify(err)); + }); ``` -### getDistributedVirtualDeviceId(deprecated) +### getCreatedOsAccountsCount(deprecated) -getDistributedVirtualDeviceId(callback: AsyncCallback<string>): void +getCreatedOsAccountsCount(callback: AsyncCallback<number>): void -获取分布式虚拟设备ID，使用callback回调异步返回结果。 +获取已创建的系统帐号数量。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryDistributedVirtualDeviceId](#querydistributedvirtualdeviceid9) +> **说明：** 从API version 9开始废弃，建议使用[getOsAccountCount](#getosaccountcount9) > > 从 API version 7开始支持。 -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 或 ohos.permission.MANAGE_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------ | -| callback | AsyncCallback<string> | 是 | 回调结果，返回的是分布式虚拟设备ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | -------------------------------------------------------------------------- | +| callback | AsyncCallback<number> | 是 | 回调函数。当获取成功时，err为null，data为已创建的系统帐号的数量；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getDistributedVirtualDeviceId((err, virtualID) => { - console.log('getDistributedVirtualDeviceId err: ' + JSON.stringify(err)); - console.log('getDistributedVirtualDeviceId virtualID: ' + virtualID); + accountManager.getCreatedOsAccountsCount((err, count)=>{ + if (err) { + console.log("getCreatedOsAccountsCount failed, error: " + JSON.stringify(err)); + } else { + console.log("getCreatedOsAccountsCount successfully, count: " + count); + } }); ``` -### getDistributedVirtualDeviceId(deprecated) +### getCreatedOsAccountsCount(deprecated) -getDistributedVirtualDeviceId(): Promise<string> +getCreatedOsAccountsCount(): Promise<number> -获取分布式虚拟设备ID，使用Promise方式异步返回结果。 +获取已创建的系统帐号数量，使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryDistributedVirtualDeviceId](#querydistributedvirtualdeviceid9-1) +> **说明：** 从API version 9开始废弃，建议使用[getOsAccountCount](#getosaccountcount9-1) > > 从 API version 7开始支持。 -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 或 ohos.permission.MANAGE_LOCAL_ACCOUNTS +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果，返回的是分布式虚拟设备ID。 | +| 类型 | 说明 | +| --------------------- | -------------------------------------- | +| Promise<number> | Promise对象，返回已创建的系统帐号的数量。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - accountManager.getDistributedVirtualDeviceId().then((virtualID) => { - console.log('getDistributedVirtualDeviceId, virtualID: ' + virtualID); + accountManager.getCreatedOsAccountsCount().then((count) => { + console.log("getCreatedOsAccountsCount successfully, count: " + count); }).catch((err) => { - console.log('getDistributedVirtualDeviceId err: ' + JSON.stringify(err)); + console.log("getCreatedOsAccountsCount failed, error: " + JSON.stringify(err)); }); ``` -### getOsAccountProfilePhoto - -getOsAccountProfilePhoto(localId: number, callback: AsyncCallback<string>): void +### getOsAccountLocalIdFromProcess(deprecated) -获取指定系统帐号的头像信息，使用callback回调异步返回结果。 +getOsAccountLocalIdFromProcess(callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +获取当前进程所属的系统帐号ID，使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromProcess](#queryosaccountlocalidfromprocess9) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ---------------------------------------- | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<string> | 是 | 回调结果，返回的是该系统帐号的头像信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ---------------------------------------------------------------------------- | +| callback | AsyncCallback<number> | 是 | 回调函数。当获取成功时，err为null，data为当前进程所属的系统帐号ID；否则为错误对象。 | -**示例：** 获取ID为100的系统帐号的头像 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - try { - accountManager.getOsAccountProfilePhoto(localId, (err, photo)=>{ - console.log('getOsAccountProfilePhoto err:' + JSON.stringify(err)); - console.log('get photo:' + photo + ' by localId: ' + localId); - }); - } catch (e) { - console.log('getOsAccountProfilePhoto exception:' + JSON.stringify(e)); - } + accountManager.getOsAccountLocalIdFromProcess((err, localId) => { + if (err) { + console.log("getOsAccountLocalIdFromProcess failed, error: " + JSON.stringify(err)); + } else { + console.log("getOsAccountLocalIdFromProcess successfully, localId: " + localId); + } + }); ``` -### getOsAccountProfilePhoto - -getOsAccountProfilePhoto(localId: number): Promise<string> +### getOsAccountLocalIdFromProcess(deprecated) -获取指定系统帐号的头像信息，使用Promise方式异步返回结果。 +getOsAccountLocalIdFromProcess(): Promise<number> -此接口为系统接口，三方应用不支持调用。 +获取当前进程所属的系统帐号ID，使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromProcess](#queryosaccountlocalidfromprocess9-1) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | - **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<string> | Promise实例，用于获取异步返回结果，返回的是该系统帐号的头像信息。 | +| 类型 | 说明 | +| :-------------------- | :--------------------------------------- | +| Promise<number> | Promise对象，返回当前进程所属的系统帐号ID。 | -**示例：** 获取ID为100的系统帐号的头像 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - try { - accountManager.getOsAccountProfilePhoto(localId).then((photo) => { - console.log('getOsAccountProfilePhoto: ' + photo); - }).catch((err) => { - console.log('getOsAccountProfilePhoto err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('getOsAccountProfilePhoto exception:' + JSON.stringify(e)); - } + accountManager.getOsAccountLocalIdFromProcess().then((localId) => { + console.log('getOsAccountLocalIdFromProcess successfully, localId: ' + localId); + }).catch((err) => { + console.log('getOsAccountLocalIdFromProcess failed, error: ' + JSON.stringify(err)); + }); ``` -### setOsAccountProfilePhoto - -setOsAccountProfilePhoto(localId: number, photo: string, callback: AsyncCallback<void>): void +### getOsAccountLocalIdFromUid(deprecated) -为指定系统帐号设置头像信息，使用callback回调异步返回结果。 +getOsAccountLocalIdFromUid(uid: number, callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +根据uid查询对应的系统帐号ID。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromUid](#queryosaccountlocalidfromuid9) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | -| photo | string | 是 | 头像信息。 | -| callback | AsyncCallback<void> | 是 | 回调结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------------------------------- | +| uid | number | 是 | 进程uid。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果查询成功，err为null，data为对应的系统帐号ID；否则为错误对象。 | -**示例：** 给ID为100的系统帐号设置头像 +**示例：** 查询值为12345678的uid所属的系统帐号ID ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - let photo = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA0AAAAPCAYAAAA/I0V3AAAAAXNSR0IArs4c6QAAAARnQU1BAA'+ - 'Cxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACwSURBVDhPvZLBDYMwDEV/ugsXRjAT0EHCOuFIBwkbdIRewi6unbiAyoGgSn1SFH85+Y'+ - 'q/4ljARW62X+LHS8uIzjm4dXUYF+utzBikB52Jo5e5iEPKqpACk7R9NM2RvWm5tIkD2czLCUFNKLD6IjdMHFHDzws285MgGrT0xCtp3WOKHo'+ - '+7q0mP0DZW9pNmoEFUzrQjp5cCnaen2kSJXLFD8ghbXyZCMQf/8e8Ns1XVAG/XAgqKzVnJFAAAAABJRU5ErkJggg==' - try { - accountManager.setOsAccountProfilePhoto(localId, photo, (err)=>{ - console.log('setOsAccountProfilePhoto err:' + JSON.stringify(err)); - }); - } catch (e) { - console.log('setOsAccountProfilePhoto exception:' + JSON.stringify(e)); - } + let uid = 12345678; + accountManager.getOsAccountLocalIdFromUid(uid, (err, localId) => { + if (err) { + console.log("getOsAccountLocalIdFromUid failed, error: " + JSON.stringify(err)); + } else { + console.log("getOsAccountLocalIdFromUid successfully, localId: " + localId); + } + }); ``` -### setOsAccountProfilePhoto - -setOsAccountProfilePhoto(localId: number, photo: string): Promise<void> +### getOsAccountLocalIdFromUid(deprecated) -为指定系统帐号设置头像信息，使用Promise方式异步返回结果。 +getOsAccountLocalIdFromUid(uid: number): Promise<number> -此接口为系统接口，三方应用不支持调用。 +根据uid查询对应的系统帐号ID，使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromUid](#queryosaccountlocalidfromuid9-1) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | -| photo | string | 是 | 头像信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | --------- | +| uid | number | 是 | 进程uid。 | **返回值：** -| 类型 | 说明 | -| :------------------ | :---------------------------------- | -| Promise<void> | Promise实例，用于获取异步返回结果。 | +| 类型 | 说明 | +| :-------------------- | :----------------------------------- | +| Promise<number> | Promise对象，返回uid对应的系统帐号ID。 | -**示例：** 给ID为100的系统帐号设置头像 +**示例：** 查询值为12345678的uid所属的系统帐号ID ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - let photo = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA0AAAAPCAYAAAA/I0V3AAAAAXNSR0IArs4c6QAAAARnQU1BAA'+ - 'Cxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACwSURBVDhPvZLBDYMwDEV/ugsXRjAT0EHCOuFIBwkbdIRewi6unbiAyoGgSn1SFH85+Y'+ - 'q/4ljARW62X+LHS8uIzjm4dXUYF+utzBikB52Jo5e5iEPKqpACk7R9NM2RvWm5tIkD2czLCUFNKLD6IjdMHFHDzws285MgGrT0xCtp3WOKHo'+ - '+7q0mP0DZW9pNmoEFUzrQjp5cCnaen2kSJXLFD8ghbXyZCMQf/8e8Ns1XVAG/XAgqKzVnJFAAAAABJRU5ErkJggg==' - try { - accountManager.setOsAccountProfilePhoto(localId, photo).then(() => { - console.log('setOsAccountProfilePhoto success'); - }).catch((err) => { - console.log('setOsAccountProfilePhoto err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('setOsAccountProfilePhoto exception:' + JSON.stringify(e)); - } + let uid = 12345678; + accountManager.getOsAccountLocalIdFromUid(uid).then((localId) => { + console.log("getOsAccountLocalIdFromUid successfully, localId: " + localId); + }).catch((err) => { + console.log("getOsAccountLocalIdFromUid failed, error: " + JSON.stringify(err)); + }); ``` -### queryOsAccountLocalIdBySerialNumber9+ +### getOsAccountLocalIdFromDomain(deprecated) -queryOsAccountLocalIdBySerialNumber(serialNumber: number, callback: AsyncCallback<number>): void +getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo, callback: AsyncCallback<number>): void + +根据域帐号信息，获取与其关联的系统帐号的帐号ID。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromDomain](#queryosaccountlocalidfromdomain9) +> +> 从 API version 8开始支持。 -通过SN码查询与其关联的系统帐号的帐号ID，使用callback回调异步返回结果。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------------ | --------------------------- | ---- | ------------------------------------------------ | -| serialNumber | number | 是 | 帐号SN码。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是与SN码关联的系统帐号的帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | --------------------------------------- | ---- | --------------------------------------------------------------------------- | +| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | +| callback | AsyncCallback<number> | 是 | 回调函数，如果获取成功，err为null，data为域帐号关联的系统帐号ID；否则为错误对象。 | -**示例：** 查询与SN码12345关联的系统帐号的ID +**示例：** ```js + let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; let accountManager = account_osAccount.getAccountManager(); - let serialNumber = 12345; - try { - accountManager.queryOsAccountLocalIdBySerialNumber(serialNumber, (err, localId)=>{ - console.log('ger localId err:' + JSON.stringify(err)); - console.log('get localId:' + localId + ' by serialNumber: ' + serialNumber); - }); - } catch (e) { - console.log('ger localId exception:' + JSON.stringify(e)); - } + accountManager.getOsAccountLocalIdFromDomain(domainInfo, (err, localId) => { + if (err) { + console.log("getOsAccountLocalIdFromDomain failed, error: " + JSON.stringify(err)); + } else { + console.log("getOsAccountLocalIdFromDomain successfully, localId: " + localId); + } + }); ``` -### queryOsAccountLocalIdBySerialNumber9+ +### getOsAccountLocalIdFromDomain(deprecated) -queryOsAccountLocalIdBySerialNumber(serialNumber: number): Promise<number> +getOsAccountLocalIdFromDomain(domainInfo: DomainAccountInfo): Promise<number> + +根据域帐号信息，获取与其关联的系统帐号的帐号ID。使用Promise异步回调。 + +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdFromDomain](#queryosaccountlocalidfromdomain9-1) +> +> 从 API version 8开始支持。 -通过SN码查询与其关联的系统帐号的帐号ID，使用Promise方式异步返回结果。 +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------------ | ------ | ---- | ---------- | -| serialNumber | number | 是 | 帐号SN码。 | +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | --------------------------------------- | ---- | ------------ | +| domainInfo | [DomainAccountInfo](#domainaccountinfo8) | 是 | 域帐号信息。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是与SN码关联的系统帐号的帐号ID。 | +| 类型 | 说明 | +| :-------------------- | :------------------------------------- | +| Promise<number> | Promise对象，返回域帐号关联的系统帐号ID。 | -**示例：** 查询与SN码12345关联的系统帐号的ID +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let serialNumber = 12345; - try { - accountManager.queryOsAccountLocalIdBySerialNumber(serialNumber).then((localId) => { - console.log('queryOsAccountLocalIdBySerialNumber localId: ' + localId); - }).catch((err) => { - console.log('queryOsAccountLocalIdBySerialNumber err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('queryOsAccountLocalIdBySerialNumber exception: ' + JSON.stringify(e)); - } + let domainInfo = {domain: 'testDomain', accountName: 'testAccountName'}; + accountManager.getOsAccountLocalIdFromDomain(domainInfo).then((localId) => { + console.log('getOsAccountLocalIdFromDomain successfully, localId: ' + localId); + }).catch((err) => { + console.log('getOsAccountLocalIdFromDomain failed, error: ' + JSON.stringify(err)); + }); ``` -### getOsAccountLocalIdBySerialNumber(deprecated) +### getOsAccountAllConstraints(deprecated) -getOsAccountLocalIdBySerialNumber(serialNumber: number, callback: AsyncCallback<number>): void +getOsAccountAllConstraints(localId: number, callback: AsyncCallback<Array<string>>): void -通过SN码查询与其关联的系统帐号的帐号ID，使用callback回调异步返回结果。 +获取指定系统帐号的全部约束。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdBySerialNumber](#queryosaccountlocalidbyserialnumber9) +> **说明：** 从API version 9开始废弃，建议使用[getOsAccountConstraints](#getosaccountconstraints9) > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------------ | --------------------------- | ---- | ------------------------------------------------ | -| serialNumber | number | 是 | 帐号SN码。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是与SN码关联的系统帐号的帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<Array<string>> | 是 | 回调函数。如果获取成功，err为null，data为指定系统帐号的全部[约束](#系统帐号约束列表)；否则为错误对象。 | -**示例：** 查询与SN码12345关联的系统帐号的ID +**示例：** 获取ID为100的系统帐号的全部约束 ```js let accountManager = account_osAccount.getAccountManager(); - let serialNumber = 12345; - accountManager.getOsAccountLocalIdBySerialNumber(serialNumber, (err, localId)=>{ - console.log('ger localId err:' + JSON.stringify(err)); - console.log('get localId:' + localId + ' by serialNumber: ' + serialNumber); + let localId = 100; + accountManager.getOsAccountAllConstraints(localId, (err, constraints)=>{ + console.log('getOsAccountAllConstraints err:' + JSON.stringify(err)); + console.log('getOsAccountAllConstraints:' + JSON.stringify(constraints)); }); ``` -### getOsAccountLocalIdBySerialNumber(deprecated) - -getOsAccountLocalIdBySerialNumber(serialNumber: number): Promise<number> +### getOsAccountAllConstraints(deprecated) -通过SN码查询与其关联的系统帐号的帐号ID，使用Promise方式异步返回结果。 +getOsAccountAllConstraints(localId: number): Promise<Array<string>> -> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdBySerialNumber](#queryosaccountlocalidbyserialnumber9-1) +> **说明：** 从API version 9开始废弃，建议使用[getOsAccountConstraints](#getosaccountconstraints9-1) > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 + +获取指定系统帐号的全部约束。使用Promise异步回调。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------------ | ------ | ---- | ---------- | -| serialNumber | number | 是 | 帐号SN码。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------ | +| localId | number | 是 | 系统帐号ID。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是与SN码关联的系统帐号的帐号ID。 | +| 类型 | 说明 | +| :--------------------------------- | :----------------------------------------------------------- | +| Promise<Array<string>> | Promise对象，返回指定系统帐号的全部[约束](#系统帐号约束列表)。 | -**示例：** 查询与SN码12345关联的系统帐号的ID +**示例：** 获取ID为100的系统帐号的全部约束 ```js let accountManager = account_osAccount.getAccountManager(); - let serialNumber = 12345; - accountManager.getOsAccountLocalIdBySerialNumber(serialNumber).then((localId) => { - console.log('getOsAccountLocalIdBySerialNumber localId: ' + localId); + let localId = 100; + accountManager.getOsAccountAllConstraints(localId).then((constraints) => { + console.log('getOsAccountAllConstraints, constraints: ' + constraints); }).catch((err) => { - console.log('getOsAccountLocalIdBySerialNumber err: ' + JSON.stringify(err)); + console.log('getOsAccountAllConstraints err: ' + JSON.stringify(err)); }); ``` -### querySerialNumberByOsAccountLocalId9+ +### queryActivatedOsAccountIds(deprecated) -querySerialNumberByOsAccountLocalId(localId: number, callback: AsyncCallback<number>): void +queryActivatedOsAccountIds(callback: AsyncCallback<Array<number>>): void + +查询当前处于激活状态的系统帐号的ID列表。使用callback异步回调。 -通过系统帐号ID获取与该系统帐号关联的SN码，使用callback回调异步返回结果。 +> **说明：** 从API version 9开始废弃，建议使用[getActivatedOsAccountIds](#getactivatedosaccountids9) +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------ | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是与该系统帐号关联的SN码。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------------------------------ | +| callback | AsyncCallback<Array<number>> | 是 | 回调函数。如果查询成功，err为null，data为当前处于激活状态的系统帐号的ID列表；否则为错误对象。 | -**示例：** 获取ID为100的系统帐号关联的SN码 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - try { - accountManager.querySerialNumberByOsAccountLocalId(localId, (err, serialNumber)=>{ - console.log('ger serialNumber err:' + JSON.stringify(err)); - console.log('get serialNumber:' + serialNumber + ' by localId: ' + localId); - }); - } catch (e) { - console.log('ger serialNumber exception:' + JSON.stringify(e)); - } + accountManager.queryActivatedOsAccountIds((err, idArray)=>{ + console.log('queryActivatedOsAccountIds err:' + JSON.stringify(err)); + console.log('queryActivatedOsAccountIds idArray length:' + idArray.length); + for(let i=0;i9+ - -querySerialNumberByOsAccountLocalId(localId: number): Promise<number> +### queryActivatedOsAccountIds(deprecated) -通过系统帐号ID获取与该系统帐号关联的SN码，使用Promise方式异步返回结果。 +queryActivatedOsAccountIds(): Promise<Array<number>> -**系统能力：** SystemCapability.Account.OsAccount +> **说明：** 从API version 9开始废弃，建议使用[getActivatedOsAccountIds](#getactivatedosaccountids9-1) +> +> 从 API version 8开始支持。 -**参数：** +查询当前处于激活状态的系统帐号的ID列表。使用Promise异步回调。 -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | +**系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是与该系统帐号关联的SN码。 | +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------------------- | +| Promise<Array<number>> | Promise对象，返回当前处于激活状态的系统帐号的ID列表。 | -**示例：** 获取ID为100的系统帐号关联的SN码 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - try { - accountManager.querySerialNumberByOsAccountLocalId(localId).then((serialNumber) => { - console.log('querySerialNumberByOsAccountLocalId serialNumber: ' + serialNumber); - }).catch((err) => { - console.log('querySerialNumberByOsAccountLocalId err: ' + JSON.stringify(err)); - }); - } catch (e) { - console.log('querySerialNumberByOsAccountLocalId exception:' + JSON.stringify(e)); - } + accountManager.queryActivatedOsAccountIds().then((idArray) => { + console.log('queryActivatedOsAccountIds, idArray: ' + idArray); + }).catch((err) => { + console.log('queryActivatedOsAccountIds err: ' + JSON.stringify(err)); + }); ``` -### getSerialNumberByOsAccountLocalId(deprecated) +### queryCurrentOsAccount(deprecated) -getSerialNumberByOsAccountLocalId(localId: number, callback: AsyncCallback<number>): void +queryCurrentOsAccount(callback: AsyncCallback<OsAccountInfo>): void -通过系统帐号ID获取与该系统帐号关联的SN码，使用callback回调异步返回结果。 +查询当前进程所属的系统帐号的信息。使用callback异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[querySerialNumberByOsAccountLocalId](#queryserialnumberbyosaccountlocalid9) +> **说明：** 从API version 9开始废弃，建议使用[getCurrentOsAccount](#getcurrentosaccount9) > -> 从 API version 8开始支持。 +> 从 API version 7开始支持。 + +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------- | ---- | ------------------------------------------ | -| localId | number | 是 | 系统帐号ID。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是与该系统帐号关联的SN码。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | +| callback | AsyncCallback<[OsAccountInfo](#osaccountinfo)> | 是 | 回调函数。如果查询成功，err为null，data为当前进程所属的系统帐号信息；否则为错误对象。 | -**示例：** 获取ID为100的系统帐号关联的SN码 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - accountManager.getSerialNumberByOsAccountLocalId(localId, (err, serialNumber)=>{ - console.log('ger serialNumber err:' + JSON.stringify(err)); - console.log('get serialNumber:' + serialNumber + ' by localId: ' + localId); + accountManager.queryCurrentOsAccount((err, curAccountInfo)=>{ + console.log('queryCurrentOsAccount err:' + JSON.stringify(err)); + console.log('queryCurrentOsAccount curAccountInfo:' + JSON.stringify(curAccountInfo)); }); ``` -### getSerialNumberByOsAccountLocalId(deprecated) +### queryCurrentOsAccount(deprecated) -getSerialNumberByOsAccountLocalId(localId: number): Promise<number> +queryCurrentOsAccount(): Promise<OsAccountInfo> -通过系统帐号ID获取与该系统帐号关联的SN码，使用Promise方式异步返回结果。 +查询当前进程所属的系统帐号的信息。使用Promise异步回调。 -> **说明：** 从API version 9开始废弃，建议使用[querySerialNumberByOsAccountLocalId](#queryserialnumberbyosaccountlocalid9-1) +> **说明：** 从API version 9开始废弃，建议使用[getCurrentOsAccount](#getcurrentosaccount9-1) > -> 从 API version 8开始支持。 - -**系统能力：** SystemCapability.Account.OsAccount +> 从 API version 7开始支持。 -**参数：** +**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 系统帐号ID。 | +**系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是与该系统帐号关联的SN码。 | +| 类型 | 说明 | +| ---------------------------------------------- | ------------------------------------------ | +| Promise<[OsAccountInfo](#osaccountinfo)> | Promise对象，返回当前进程所属的系统帐号信息。 | -**示例：** 获取ID为100的系统帐号关联的SN码 +**示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let localId = 100; - accountManager.getSerialNumberByOsAccountLocalId(localId).then((serialNumber) => { - console.log('getSerialNumberByOsAccountLocalId serialNumber: ' + serialNumber); + accountManager.queryCurrentOsAccount().then((accountInfo) => { + console.log('queryCurrentOsAccount, accountInfo: ' + JSON.stringify(accountInfo)); }).catch((err) => { - console.log('getSerialNumberByOsAccountLocalId err: ' + JSON.stringify(err)); + console.log('queryCurrentOsAccount err: ' + JSON.stringify(err)); }); ``` -### on - -on(type: 'activate' | 'activating', name: string, callback: Callback<number>): void +### getOsAccountTypeFromProcess(deprecated) -订阅系统帐号的变动信息，使用callback回调异步返回结果。 +getOsAccountTypeFromProcess(callback: AsyncCallback<OsAccountType>): void -此接口为系统接口，三方应用不支持调用。 +查询当前进程所属的系统帐号的帐号类型。使用callback异步回调。 -**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION +> **说明：** 从API version 9开始废弃，建议使用[getOsAccountType](#getosaccounttype9) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------- | ---- | ------------------------------------------------------------ | -| type | 'activate' \| 'activating' | 是 | 订阅类型，activate表示订阅的是帐号已激活完成的事件，activating表示订阅的是帐号正在激活的事件。 | -| name | string | 是 | 订阅名称，可自定义，要求非空且长度不超过1024字节。 | -| callback | Callback<number> | 是 | 订阅系统帐号变动信息的回调，表示当前事件对应的系统帐号ID。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------- | ---- | ---------------------------------------------------- | +| callback | AsyncCallback<[OsAccountType](#osaccounttype)> | 是 | 回调函数。如果查询成功，err为null，data为当前进程所属的系统帐号的帐号类型；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - function onCallback(receiveLocalId){ - console.log('receive localId:' + receiveLocalId); - } - try { - accountManager.on('activating', 'osAccountOnOffNameA', onCallback); - } catch (e) { - console.log('receive localId exception:' + JSON.stringify(e)); - } + accountManager.getOsAccountTypeFromProcess((err, accountType) => { + console.log('getOsAccountTypeFromProcess err: ' + JSON.stringify(err)); + console.log('getOsAccountTypeFromProcess accountType: ' + accountType); + }); ``` -### off - -off(type: 'activate' | 'activating', name: string, callback?: Callback<number>): void +### getOsAccountTypeFromProcess(deprecated) -取消订阅系统帐号的变动信息，使用callback回调异步返回结果。 +getOsAccountTypeFromProcess(): Promise<OsAccountType> -此接口为系统接口，三方应用不支持调用。 +查询当前进程所属的系统帐号的帐号类型。使用Promise异步回调。 -**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION +> **说明：** 从API version 9开始废弃，建议使用[getOsAccountType](#getosaccounttype9-1) +> +> 从 API version 7开始支持。 **系统能力：** SystemCapability.Account.OsAccount -**参数：** +**返回值：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------- | ---- | ------------------------------------------------------------ | -| type | 'activate' \| 'activating' | 是 | 取消订阅类型，activate表示取消订阅帐号已激活完成的事件，activating取消订阅帐号正在激活的事件。 | -| name | string | 是 | 订阅名称，可自定义，，要求非空且长度不超过1024字节，需要与订阅接口传入的值保持一致。 | -| callback | Callback<number> | 否 | 取消订阅系统帐号变化的回调，默认返回0。 | +| 类型 | 说明 | +| ---------------------------------------------- | ----------------------------------------------- | +| Promise<[OsAccountType](#osaccounttype)> | Promise对象，返回当前进程所属的系统帐号的帐号类型。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - function offCallback(){ - console.log('off enter') - } - try { - accountManager.off('activating', 'osAccountOnOffNameA', offCallback); - } catch (e) { - console.log('off exception:' + JSON.stringify(e)); - } + accountManager.getOsAccountTypeFromProcess().then((accountType) => { + console.log('getOsAccountTypeFromProcess, accountType: ' + accountType); + }).catch((err) => { + console.log('getOsAccountTypeFromProcess err: ' + JSON.stringify(err)); + }); ``` -### getBundleIdFromUid9+ +### getDistributedVirtualDeviceId(deprecated) -getBundleIdFromUid(uid: number, callback: AsyncCallback<number>): void; +getDistributedVirtualDeviceId(callback: AsyncCallback<string>): void -通过uid查询对应的bundleId。 +获取分布式虚拟设备ID。使用callback异步回调。 + +> **说明：** 从API version 9开始废弃，建议使用[queryDistributedVirtualDeviceId](#querydistributedvirtualdeviceid9) +> +> 从 API version 7开始支持。 -此接口为系统接口，三方应用不支持调用。 +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------- | ---- | ------------------------------------------------------------ | -| uid | number | 是 | 进程uid。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回的是与uid对应的bundleId。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------------------------------- | +| callback | AsyncCallback<string> | 是 | 回调函数。如果获取成功，err为null，data为分布式虚拟设备ID；否则为错误对象。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let testUid = 1000000; - try { - accountManager.getBundleIdFromUid(testUid, (err, bundleId) => { - console.info('getBundleIdFromUid errInfo:' + JSON.stringify(err)); - console.info('getBundleIdFromUid bundleId:' + JSON.stringify(bundleId)); - }); - } catch (e) { - console.info('getBundleIdFromUid exception:' + JSON.stringify(e)); - } + accountManager.getDistributedVirtualDeviceId((err, virtualID) => { + console.log('getDistributedVirtualDeviceId err: ' + JSON.stringify(err)); + console.log('getDistributedVirtualDeviceId virtualID: ' + virtualID); + }); ``` -### getBundleIdFromUid9+ -getBundleIdFromUid(uid: number): Promise<number>; +### getDistributedVirtualDeviceId(deprecated) -通过uid查询对应的bundleId。 +getDistributedVirtualDeviceId(): Promise<string> -此接口为系统接口，三方应用不支持调用。 +获取分布式虚拟设备ID。使用Promise异步回调。 -**系统能力：** SystemCapability.Account.OsAccount +> **说明：** 从API version 9开始废弃，建议使用[queryDistributedVirtualDeviceId](#querydistributedvirtualdeviceid9-1) +> +> 从 API version 7开始支持。 -**参数：** +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| uid | number | 是 | 进程uid。 | +**系统能力：** SystemCapability.Account.OsAccount **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回的是与uid对应的bundleId。 | +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| Promise<string> | Promise对象，返回分布式虚拟设备ID。 | **示例：** ```js let accountManager = account_osAccount.getAccountManager(); - let testUid = 1000000; - try { - accountManager.getBundleIdFromUid(testUid).then((result) => { - console.info('getBundleIdFromUid bundleId:' + JSON.stringify(result)); - }).catch((err)=>{ - console.info('getBundleIdFromUid errInfo:' + JSON.stringify(err)); - }); - } catch (e) { - console.info('getBundleIdFromUid exception:' + JSON.stringify(e)); - } + accountManager.getDistributedVirtualDeviceId().then((virtualID) => { + console.log('getDistributedVirtualDeviceId, virtualID: ' + virtualID); + }).catch((err) => { + console.log('getDistributedVirtualDeviceId err: ' + JSON.stringify(err)); + }); ``` -### isMainOsAccount9+ - -isMainOsAccount(callback: AsyncCallback<boolean>): void; +### getOsAccountLocalIdBySerialNumber(deprecated) -查询当前进程是否处于主用户。 +getOsAccountLocalIdBySerialNumber(serialNumber: number, callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +通过SN码查询与其关联的系统帐号的帐号ID。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdBySerialNumber](#queryosaccountlocalidbyserialnumber9) +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback<boolean> | 是 | 回调结果，返回的是当前进程是否处于主用户，是则返回true，否则返回false。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------- | ---- | -------------------------------------------------------------------------------- | +| serialNumber | number | 是 | 帐号SN码。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果查询成功，err为null，data为与SN码关联的系统帐号的帐号ID；否则为错误对象。 | -**示例：** +**示例：** 查询与SN码12345关联的系统帐号的ID ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.isMainOsAccount((err,result)=>{ - console.info('isMainOsAccount errInfo:' + JSON.stringify(err)); - console.info('isMainOsAccount result:' + JSON.stringify(result)); - }); - } catch (e) { - console.info('isMainOsAccount exception:' + JSON.stringify(e)); - } + let serialNumber = 12345; + accountManager.getOsAccountLocalIdBySerialNumber(serialNumber, (err, localId)=>{ + console.log('ger localId err:' + JSON.stringify(err)); + console.log('get localId:' + localId + ' by serialNumber: ' + serialNumber); + }); ``` -### isMainOsAccount9+ -isMainOsAccount(): Promise<boolean>; +### getOsAccountLocalIdBySerialNumber(deprecated) -查询当前进程是否处于主用户。 +getOsAccountLocalIdBySerialNumber(serialNumber: number): Promise<number> -此接口为系统接口，三方应用不支持调用。 +通过SN码查询与其关联的系统帐号的帐号ID。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[queryOsAccountLocalIdBySerialNumber](#queryosaccountlocalidbyserialnumber9-1) +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.OsAccount +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ------ | ---- | ---------- | +| serialNumber | number | 是 | 帐号SN码。 | + **返回值：** | 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<boolean> | Promise实例，用于获取异步返回结果，回调结果，返回的是当前进程是否处于主用户，是则返回true，否则返回false。 | +| --------------------- | -------------------------------------------- | +| Promise<number> | Promise对象，返回与SN码关联的系统帐号的帐号ID。 | -**示例：** +**示例：** 查询与SN码12345关联的系统帐号的ID ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.isMainOsAccount().then((result) => { - console.info('isMainOsAccount result:' + JSON.stringify(result)); - }).catch((err)=>{ - console.info('isMainOsAccount errInfo:' + JSON.stringify(err)); - }); - } catch (e) { - console.info('isMainOsAccount exception:' + JSON.stringify(e)); - } + let serialNumber = 12345; + accountManager.getOsAccountLocalIdBySerialNumber(serialNumber).then((localId) => { + console.log('getOsAccountLocalIdBySerialNumber localId: ' + localId); + }).catch((err) => { + console.log('getOsAccountLocalIdBySerialNumber err: ' + JSON.stringify(err)); + }); ``` -### queryOsAccountConstraintSourceTypes9+ -queryOsAccountConstraintSourceTypes(localId: number, constraint: string, callback: AsyncCallback<Array<ConstraintSourceTypeInfo>>): void; +### getSerialNumberByOsAccountLocalId(deprecated) -查询指定系统帐号的指定约束来源信息。 +getSerialNumberByOsAccountLocalId(localId: number, callback: AsyncCallback<number>): void -此接口为系统接口，三方应用不支持调用。 +通过系统帐号ID获取与该系统帐号关联的SN码。使用callback异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[querySerialNumberByOsAccountLocalId](#queryserialnumberbyosaccountlocalid9) +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------- | ---- | ------------------------------------------------------------ | -| localId | number | 是 | 要查询的系统帐号ID | -| constraint | string | 是 | 要查询的[约束](#系统帐号约束列表)名称 | -| callback | AsyncCallback<Array<[ConstraintSourceTypeInfo](#constraintsourcetypeinfo)>> | 是 | 回调结果，返回的是指定系统帐号的指定[约束](#系统帐号约束列表)来源信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | --------------------------------------------------------------------------- | +| localId | number | 是 | 系统帐号ID。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果获取成功，err为null，data为与该系统帐号关联的SN码；否则为错误对象。 | -**示例：** +**示例：** 获取ID为100的系统帐号关联的SN码 ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.queryOsAccountConstraintSourceTypes(100, 'constraint.wifi',(err,sourceTypeInfos)=>{ - console.info('queryOsAccountConstraintSourceType errInfo:' + JSON.stringify(err)); - console.info('queryOsAccountConstraintSourceType sourceTypeInfos:' + JSON.stringify(sourceTypeInfos)); - }); - } catch (e) { - console.info('queryOsAccountConstraintSourceType exception:' + JSON.stringify(e)); - } + let localId = 100; + accountManager.getSerialNumberByOsAccountLocalId(localId, (err, serialNumber)=>{ + console.log('ger serialNumber err:' + JSON.stringify(err)); + console.log('get serialNumber:' + serialNumber + ' by localId: ' + localId); + }); ``` -### queryOsAccountConstraintSourceTypes9+ - -queryOsAccountConstraintSourceTypes(localId: number, constraint: string): Promise<Array<ConstraintSourceTypeInfo>>; +### getSerialNumberByOsAccountLocalId(deprecated) -查询指定系统帐号的指定约束来源信息。 +getSerialNumberByOsAccountLocalId(localId: number): Promise<number> -此接口为系统接口，三方应用不支持调用。 +通过系统帐号ID获取与该系统帐号关联的SN码。使用Promise异步回调。 -**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.GET_LOCAL_ACCOUNTS +> **说明：** 从API version 9开始废弃，建议使用[querySerialNumberByOsAccountLocalId](#queryserialnumberbyosaccountlocalid9-1) +> +> 从 API version 8开始支持。 **系统能力：** SystemCapability.Account.OsAccount **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------ | -| localId | number | 是 | 要查询的系统帐号ID | -| constraint | string | 是 | 要查询的[约束](#系统帐号约束列表)名称 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ----------- | +| localId | number | 是 | 系统帐号ID。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :----------------------------------------------------------- | -| Promise<Array<[ConstraintSourceTypeInfo](#constraintsourcetypeinfo)>> | Promise实例，用于获取异步返回结果，返回的是指定系统帐号的指定[约束](#系统帐号约束列表)来源信息。 | +| 类型 | 说明 | +| --------------------- | -------------------------------------- | +| Promise<number> | Promise对象，返回与该系统帐号关联的SN码。 | -**示例：** +**示例：** 获取ID为100的系统帐号关联的SN码 ```js let accountManager = account_osAccount.getAccountManager(); - try { - accountManager.queryOsAccountConstraintSourceTypes(100, 'constraint.wifi').then((result) => { - console.info('queryOsAccountConstraintSourceType sourceTypeInfos:' + JSON.stringify(result)); - }).catch((err)=>{ - console.info('queryOsAccountConstraintSourceType errInfo:' + JSON.stringify(err)); - }); - } catch (e) { - console.info('queryOsAccountConstraintSourceType exception:' + JSON.stringify(e)); - } + let localId = 100; + accountManager.getSerialNumberByOsAccountLocalId(localId).then((serialNumber) => { + console.log('getSerialNumberByOsAccountLocalId serialNumber: ' + serialNumber); + }).catch((err) => { + console.log('getSerialNumberByOsAccountLocalId err: ' + JSON.stringify(err)); + }); ``` ## UserAuth8+ 用户认证类。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### constructor8+ @@ -3236,7 +3556,7 @@ constructor() 创建用户认证的实例。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Account.OsAccount @@ -3252,7 +3572,7 @@ getVersion(): number; 返回版本信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3275,7 +3595,7 @@ getAvailableStatus(authType: AuthType, authTrustLevel: AuthTrustLevel): number; 检查身份认证功能是否可用。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3311,9 +3631,9 @@ getAvailableStatus(authType: AuthType, authTrustLevel: AuthTrustLevel): number; getProperty(request: GetPropertyRequest, callback: AsyncCallback<ExecutorProperty>): void; -基于指定的请求信息获取属性，使用callback回调异步返回结果。 +基于指定的请求信息获取属性。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3324,7 +3644,7 @@ getProperty(request: GetPropertyRequest, callback: AsyncCallback<ExecutorProp | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------------------------- | ---- | ---------------------------------- | | request | [GetPropertyRequest](#getpropertyrequest8) | 是 | 请求信息，包括认证类型和属性类型列表。 | -| callback | AsyncCallback<[ExecutorProperty](#executorproperty8)> | 是 | 回调结果，返回的是调用者属性。 | +| callback | AsyncCallback<[ExecutorProperty](#executorproperty8)> | 是 | 回调函数。如果获取成功，err为null，data为执行器属性信息；否则为错误对象。 | **示例：** ```js @@ -3352,9 +3672,9 @@ getProperty(request: GetPropertyRequest, callback: AsyncCallback<ExecutorProp getProperty(request: GetPropertyRequest): Promise<ExecutorProperty>; -基于指定的请求信息获取属性，使用Promise方式异步返回结果。 +基于指定的请求信息获取属性。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3370,7 +3690,7 @@ getProperty(request: GetPropertyRequest): Promise<ExecutorProperty>; | 类型 | 说明 | | :---------------------------------------------------------------- | :-------------------------------------------------- | -| Promise<[ExecutorProperty](#executorproperty8)> | Promise实例，用于获取异步返回结果，返回的是调用者属性。 | +| Promise<[ExecutorProperty](#executorproperty8)> | Promise对象，返回执行者属性信息。 | **示例：** ```js @@ -3399,9 +3719,9 @@ getProperty(request: GetPropertyRequest): Promise<ExecutorProperty>; setProperty(request: SetPropertyRequest, callback: AsyncCallback<number>): void; -设置可用于初始化算法的属性，使用callback回调异步返回结果。 +设置可用于初始化算法的属性。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3412,7 +3732,7 @@ setProperty(request: SetPropertyRequest, callback: AsyncCallback<number>): | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ---------------------------------------------------------------------- | | request | [SetPropertyRequest](#setpropertyrequest8)| 是 | 请求信息，包括认证类型和要设置的密钥值。 | -| callback | AsyncCallback<number> | 是 | 回调结果，返回一个[数值](#resultcode8)，指示属性设置是否成功。 | +| callback | AsyncCallback<number> | 是 | 回调函数。如果设置成功，err为null，data为一个[数值](#resultcode8)，指示属性设置是否成功；否则为错误对象。 | **示例：** ```js @@ -3436,9 +3756,9 @@ setProperty(request: SetPropertyRequest, callback: AsyncCallback<number>): setProperty(request: SetPropertyRequest): Promise<number>; -设置可用于初始化算法的属性，使用Promise方式异步返回结果。 +设置可用于初始化算法的属性。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3446,15 +3766,15 @@ setProperty(request: SetPropertyRequest): Promise<number>; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------ | ---- | ---------------------------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------ | ---- | ---------------------------------------- | | request | [SetPropertyRequest](#setpropertyrequest8) | 是 | 请求信息，包括身份验证类型和要设置的密钥值。 | **返回值：** -| 类型 | 说明 | -| :-------------------- | :-------------------------------------------------------------------------------------------- | -| Promise<number> | Promise实例，用于获取异步返回结果，返回一个[数值](#resultcode8)，指示属性设置是否成功。 | +| 类型 | 说明 | +| :-------------------- | :------------------------------------------------------------ | +| Promise<number> | Promise对象，返回一个[数值](#resultcode8)，指示属性设置是否成功。 | **示例：** ```js @@ -3479,9 +3799,9 @@ setProperty(request: SetPropertyRequest): Promise<number>; auth(challenge: Uint8Array, authType: AuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array; -执行认证，使用callback回调异步返回结果。 +执行认证。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3491,10 +3811,10 @@ auth(challenge: Uint8Array, authType: AuthType, authTrustLevel: AuthTrustLevel, | 参数名 | 类型 | 必填 | 说明 | | --------------- | ---------------------------------------------------- | --- | ------------------------------------ | -| challenge | Uint8Array | 是 | 指示挑战值，挑战值为一个随机数，用于提升安全性。| +| challenge | Uint8Array | 是 | 指示挑战值，挑战值为一个随机数，用于提升安全性。| | authType | [AuthType](#authtype8) | 是 | 指示认证类型。 | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 指示认证结果的信任级别。 | -| callback | [IUserAuthCallback](#iuserauthcallback8) | 是 | 回调结果，返回的是结果和所获取的信息。 | +| callback | [IUserAuthCallback](#iuserauthcallback8) | 是 | 回调对象，返回认证结果。 | **返回值：** @@ -3525,9 +3845,9 @@ auth(challenge: Uint8Array, authType: AuthType, authTrustLevel: AuthTrustLevel, authUser(userId: number, challenge: Uint8Array, authType: AuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array; -执行用户认证，使用callback回调异步返回结果。 +执行用户认证。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3541,7 +3861,7 @@ authUser(userId: number, challenge: Uint8Array, authType: AuthType, authTrustLev | challenge | Uint8Array | 是 | 指示挑战值，挑战值为一个随机数，用于提升安全性。 | | authType | [AuthType](#authtype8) | 是 | 指示认证类型。 | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 指示认证结果的信任级别。 | -| callback | [IUserAuthCallback](#iuserauthcallback8) | 是 | 回调结果，返回的是结果和所获取的信息。 | +| callback | [IUserAuthCallback](#iuserauthcallback8) | 是 | 回调对象，返回认证结果。 | **返回值：** @@ -3575,7 +3895,7 @@ cancelAuth(contextID: Uint8Array): void; 取消特定的认证。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3609,7 +3929,7 @@ cancelAuth(contextID: Uint8Array): void; Pin码认证功能基类。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### constructor8+ @@ -3617,7 +3937,7 @@ constructor() 创建Pin码认证的实例。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Account.OsAccount @@ -3632,7 +3952,7 @@ registerInputer(inputer: IInputer): boolean; 注册输入器。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3672,7 +3992,7 @@ unregisterInputer(): void; 卸载输入器。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3688,7 +4008,7 @@ unregisterInputer(): void; 获取用户身份管理类。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### constructor8+ @@ -3696,7 +4016,7 @@ constructor() 创建用户认证的实例。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Account.OsAccount @@ -3709,9 +4029,9 @@ constructor() openSession(callback: AsyncCallback<Uint8Array>): void; -打开会话，启动IDM操作以获取挑战值，使用callback回调异步返回结果。 +打开会话，启动IDM操作以获取挑战值。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3719,9 +4039,9 @@ openSession(callback: AsyncCallback<Uint8Array>): void; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------------- | ---- | -------------------------------- | -| callback | AsyncCallback<Uint8Array> | 是 | 回调结果，返回的是挑战值，非0即成功，为0则失败。| +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------- | ---- | -------------------------------------------------------------- | +| callback | AsyncCallback<Uint8Array> | 是 | 回调函数。如果打开会话成功，err为null，data为挑战值；否则为错误对象。| **示例：** ```js @@ -3740,9 +4060,9 @@ openSession(callback: AsyncCallback<Uint8Array>): void; openSession(): Promise<Uint8Array>; -打开会话，启动IDM操作以获取挑战值，使用Promise方式异步返回结果。 +打开会话，启动IDM操作以获取挑战值。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3750,9 +4070,9 @@ openSession(): Promise<Uint8Array>; **返回值：** -| 类型 | 说明 | -| :------------------------ | :------------------------------------------------------- | -| Promise<Uint8Array> | Promise实例，用于获取异步返回结果，返回的是挑战值，非0即成功，为0则失败。| +| 类型 | 说明 | +| :------------------------ | ----------------------- | +| Promise<Uint8Array> | Promise对象，返回挑战值。 | **示例：** ```js @@ -3772,9 +4092,9 @@ openSession(): Promise<Uint8Array>; addCredential(credentialInfo: CredentialInfo, callback: IIdmCallback): void; -添加凭据，添加用户凭据信息，传入凭据添加方法和凭据信息（凭据类型，子类，如果添加用户的非密码凭据，则传入密码身份验证令牌），并获取结果/获取信息，使用callback回调异步返回结果。 +添加凭据，添加用户凭据信息，传入凭据添加方法和凭据信息（凭据类型，子类，如果添加用户的非密码凭据，则传入密码身份验证令牌），并获取结果/获取信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3782,10 +4102,10 @@ addCredential(credentialInfo: CredentialInfo, callback: IIdmCallback): void; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------------- | ------------------------------------------------ | --- | -------------------------------- | -| credentialInfo | [CredentialInfo](#credentialinfo8) | 是 | 指示凭据信息。 | -| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调结果，返回的是结果和获取信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------------- | ------------------------------ ----- | --- | ---------------------------- | +| credentialInfo | [CredentialInfo](#credentialinfo8) | 是 | 指示凭据信息。 | +| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调对象，返回添加凭据的结果。 | **示例：** ```js @@ -3820,9 +4140,9 @@ addCredential(credentialInfo: CredentialInfo, callback: IIdmCallback): void; updateCredential(credentialInfo: CredentialInfo, callback: IIdmCallback): void; -更新凭据，使用callback回调异步返回结果。 +更新凭据。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3830,10 +4150,10 @@ updateCredential(credentialInfo: CredentialInfo, callback: IIdmCallback): void; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| --------------- | ------------------------------------------------- | --- | -------------------------------- | -| credentialInfo | [CredentialInfo](#credentialinfo8) | 是 | 指示凭据信息。 | -| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调结果，返回的是结果和获取信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------------- | ------------------------------------- | --- | ------------------------- | +| credentialInfo | [CredentialInfo](#credentialinfo8) | 是 | 指示凭据信息。 | +| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调对象，返回更新凭据的结果。 | **示例：** ```js @@ -3877,9 +4197,9 @@ updateCredential(credentialInfo: CredentialInfo, callback: IIdmCallback): void; closeSession(): void; -关闭会话，结束IDM操作 +关闭会话，结束IDM操作。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3897,7 +4217,7 @@ cancel(challenge: Uint8Array): void; 根据挑战值取消条目。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3927,7 +4247,7 @@ delUser(token: Uint8Array, callback: IIdmCallback): void; 删除具有身份验证令牌的用户，使用callback方式异步返回结果。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3935,10 +4255,10 @@ delUser(token: Uint8Array, callback: IIdmCallback): void; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------ | --- | ------------------------- | -| token | Uint8Array | 是 | 身份验证令牌。 | -| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调结果，返回的是删除结果。| +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------ | --- | ------------------------- | +| token | Uint8Array | 是 | 身份验证令牌。 | +| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调对象，返回删除用户的结果。| **示例：** ```js @@ -3960,9 +4280,9 @@ delUser(token: Uint8Array, callback: IIdmCallback): void; delCred(credentialId: Uint8Array, token: Uint8Array, callback: IIdmCallback): void; -删除用户凭据信息，使用callback方式异步返回结果。 +删除用户凭据信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -3971,10 +4291,10 @@ delCred(credentialId: Uint8Array, token: Uint8Array, callback: IIdmCallback): vo **参数：** | 参数名 | 类型 | 必填 | 说明 | -| --------------- | ----------------------------------------------- | --- | ---------------------------| -| credentialId | Uint8Array | 是 | 凭证索引。 | -| token | Uint8Array | 是 | 身份验证令牌。 | -| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调结果，返回的是删除结果。 | +| --------------- | ----------------------------------- | --- | ---------------------------| +| credentialId | Uint8Array | 是 | 凭证索引。 | +| token | Uint8Array | 是 | 身份验证令牌。 | +| callback | [IIdmCallback](#iidmcallback8) | 是 | 回调对象，返回删除凭据的结果。 | **示例：** ```js @@ -3997,9 +4317,9 @@ delCred(credentialId: Uint8Array, token: Uint8Array, callback: IIdmCallback): vo getAuthInfo(callback: AsyncCallback<Array<EnrolledCredInfo>>): void; -获取认证信息，使用callback回调异步返回结果。 +获取认证信息。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4007,9 +4327,9 @@ getAuthInfo(callback: AsyncCallback<Array<EnrolledCredInfo>>): void; **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------------------------------------- | ---- | -------------------------------------------------- | -| callback | AsyncCallback<Array<[EnrolledCredInfo](#enrolledcredinfo8)>> | 是 | 回调结果，返回的是当前用户指定类型的所有已注册凭据信息。| +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------------------ | ---- | --------------------------------------------- | +| callback | AsyncCallback<Array<[EnrolledCredInfo](#enrolledcredinfo8)>> | 是 | 回调函数。如果成功，err为null，data为当前用户指定类型的所有已注册凭据信息；否则为错误对象。| **示例：** @@ -4029,9 +4349,9 @@ getAuthInfo(callback: AsyncCallback<Array<EnrolledCredInfo>>): void; getAuthInfo(authType: AuthType, callback: AsyncCallback<Array<EnrolledCredInfo>>): void; -获取指定类型的认证信息，使用callback回调异步返回结果。 +获取指定类型的认证信息。使用callback异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4042,7 +4362,12 @@ getAuthInfo(authType: AuthType, callback: AsyncCallback<Array<EnrolledCred | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------------------- | ---- | -------------------------------------------------- | | authType | [AuthType](#authtype8) | 是 | 认证类型。 | -| callback | AsyncCallback<Array<[EnrolledCredInfo](#enrolledcredinfo8)>> | 是 | 回调结果，返回的是当前用户指定类型的所有已注册凭据信息。| +| callback | AsyncCallback<Array<[EnrolledCredInfo](#enrolledcredinfo8)>> | 是 | 回调函数，如果获取成功，err为null，data为当前用户指定类型的所有已注册凭据信息；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| 12300015 | Unsupported authType. | **示例：** ```js @@ -4061,9 +4386,9 @@ getAuthInfo(authType: AuthType, callback: AsyncCallback<Array<EnrolledCred getAuthInfo(authType?: AuthType): Promise<Array<EnrolledCredInfo>>; -获取认证信息，使用Promise方式异步返回结果。 +获取认证信息。使用Promise异步回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4073,13 +4398,18 @@ getAuthInfo(authType?: AuthType): Promise<Array<EnrolledCredInfo>>; | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------- | ---- | -------- | -| authType | [AuthType](#authtype8) | 否 | 认证类型。| +| authType | [AuthType](#authtype8) | 否 | 认证类型。| **返回值：** -| 类型 | 说明 | -| :------------------------------------------- | :------------------------------------------------------------------------ | -| Promise<Array<[EnrolledCredInfo](#enrolledcredinfo8)>> | Promise实例，用于获取异步返回结果，返回的是当前用户指定类型的所有已注册凭据信息。| +| 类型 | 说明 | +| :------------------------------------------- | :------------------------------------------------------------ ---------- | +| Promise<Array<[EnrolledCredInfo](#enrolledcredinfo8)>> | Promise对象，返回当前用户指定类型的所有已注册凭据信息。| + +**错误码：** + +| 错误码ID | 错误信息 | +| 12300015 | Unsupported authType. | **示例：** ```js @@ -4099,13 +4429,13 @@ getAuthInfo(authType?: AuthType): Promise<Array<EnrolledCredInfo>>; 密码数据回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### onSetData8+ onSetData: (pinSubType: AuthSubType, data: Uint8Array) => void; -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 通知设置数据。 @@ -4115,7 +4445,7 @@ onSetData: (pinSubType: AuthSubType, data: Uint8Array) => void; | 参数名 | 类型 | 必填 | 说明 | | ---------- | ---------------------------------------- | ---- | ----------------------------------------------- | -| pinSubType | [AuthSubType](#authsubtype8) | 是 | 用于认证的凭据子类型。 | +| pinSubType | [AuthSubType](#authsubtype8) | 是 | 用于认证的凭据子类型。 | | data | Uint8Array | 是 | 要设置的数据是凭据，用来在认证、添加、修改凭据操作。 | **示例：** @@ -4137,7 +4467,7 @@ onSetData: (pinSubType: AuthSubType, data: Uint8Array) => void; 密码输入框回调。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### onGetData8+ @@ -4145,7 +4475,7 @@ onGetData: (pinSubType: AuthSubType, callback: IInputData) => void; 通知获取数据。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4175,17 +4505,17 @@ onGetData: (pinSubType: AuthSubType, callback: IInputData) => void; ## IUserAuthCallback8+ -用户认证回调。 +表示用户认证回调类。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### onResult8+ onResult: (result: number, extraInfo: AuthResult) => void; -身份认证结果代码通过回调返回。 +身份认证结果回调函数，返回结果码和认证结果信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4210,9 +4540,9 @@ onResult: (result: number, extraInfo: AuthResult) => void; onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; -在身份验证期间，TipsCode通过回调返回。 +身份认证信息获取回调函数。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4241,17 +4571,17 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## IIdmCallback8+ -身份管理回调。 +表示身份管理回调类。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 ### onResult8+ onResult: (result: number, extraInfo: RequestResult) => void; -身份认证结果代码通过回调返回。 +身份管理操作结果回调函数，返回结果码和请求结果信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4276,9 +4606,9 @@ onResult: (result: number, extraInfo: RequestResult) => void; onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; -在身份验证期间，TipsCode通过回调返回。 +身份管理信息获取回调函数。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.Account.OsAccount @@ -4309,7 +4639,7 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; 提供获取属性请求的信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4322,7 +4652,7 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; 提供设置属性请求的信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4336,7 +4666,7 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; 提供执行器的属性。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4349,9 +4679,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## AuthResult8+ -指示认证结果的信息。 +表示认证结果的信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4363,9 +4693,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## CredentialInfo8+ -指示凭证信息。 +表示凭证信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4377,9 +4707,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## RequestResult8+ -指示请求结果的信息。 +表示请求结果的信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4389,9 +4719,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## EnrolledCredInfo8+ -指示已注册凭据的信息。 +表示已注册凭据的信息。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4404,9 +4734,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## GetPropertyType8+ -枚举，指示要获取的属性类型。 +表示要获取的属性类型的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4418,9 +4748,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## SetPropertyType8+ -枚举，指示要设置的属性类型。 +表示要设置的属性类型的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4430,9 +4760,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## AuthType8+ -枚举，指示身份验证的凭据类型。 +表示身份验证的凭据类型的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4443,9 +4773,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## AuthSubType8+ -枚举，指示用于认证的凭据子类型。 +表示用于认证的凭据子类型的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4459,9 +4789,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## AuthTrustLevel8+ -枚举，指示认证结果的受信任级别。 +表示认证结果的受信任级别的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4474,9 +4804,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## Module8+ -枚举，表示获取信息的模块。 +表示获取信息的模块的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4486,9 +4816,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## ResultCode8+ -枚举，指示身份验证结果代码。 +表示身份验证结果码。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4508,9 +4838,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## FaceTipsCode8+ -枚举，指示人脸验证过程中提示代码。 +表示人脸验证过程中提示的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4530,9 +4860,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## FingerprintTips8+ -枚举，指示指纹身份验证过程中提示代码。 +表示指纹身份验证过程中提示的枚举。 -此接口为系统接口，三方应用不支持调用。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount @@ -4547,7 +4877,7 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## OsAccountInfo -系统帐号信息。 +表示系统帐号信息。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount。 @@ -4569,7 +4899,7 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## DomainAccountInfo8+ -域帐号信息。 +表示域帐号信息。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount。 @@ -4648,9 +4978,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## ConstraintSourceTypeInfo9+ -约束来源类型信息。 +表示约束来源类型信息。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount。 @@ -4661,9 +4991,9 @@ onAcquireInfo?: (module: number, acquire: number, extraInfo: any) => void; ## ConstraintSourceType9+ -枚举，约束来源类型。 +表示约束来源类型的枚举。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-particleAbility.md b/zh-cn/application-dev/reference/apis/js-apis-particleAbility.md index bfea0a61c68f384b4317ff43d4a7e60b81c3ea6d..3baf08fd65d5c60b7ae4950bbb4622c3a553465e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-particleAbility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-particleAbility.md @@ -203,7 +203,7 @@ startBackgroundRunning(id: number, request: NotificationRequest, callback: Async | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | id | number | 是 | 长时任务通知id号 | - | request | NotificationRequest | 是 | 通知参数，用于显示通知栏的信息 | + | request | [NotificationRequest](js-apis-notification.md#notificationrequest) | 是 | 通知参数，用于显示通知栏的信息 | | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | **示例**： @@ -215,7 +215,7 @@ import wantAgent from '@ohos.wantAgent'; function callback(err, data) { if (err) { - console.error("Operation failed Cause: " + err); + console.error("Operation failed cause: " + JSON.stringify(err)); } else { console.info("Operation succeeded"); } @@ -267,7 +267,7 @@ startBackgroundRunning(id: number, request: NotificationRequest): Promise<voi | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | id | number | 是 | 长时任务通知id号 | -| request | NotificationRequest | 是 | 通知参数，用于显示通知栏的信息 | +| request | [NotificationRequest](js-apis-notification.md#notificationrequest) | 是 | 通知参数，用于显示通知栏的信息 | **返回值：** @@ -311,7 +311,7 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { particleAbility.startBackgroundRunning(id, request).then(() => { console.info("Operation succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation failed cause: " + JSON.stringify(err)); }); }); @@ -338,7 +338,7 @@ import particleAbility from '@ohos.ability.particleAbility'; function callback(err, data) { if (err) { - console.error("Operation failed Cause: " + err); + console.error("Operation failed cause: " + JSON.stringify(err)); } else { console.info("Operation succeeded"); } @@ -370,7 +370,7 @@ import particleAbility from '@ohos.ability.particleAbility'; particleAbility.cancelBackgroundRunning().then(() => { console.info("Operation succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation failed cause: " + JSON.stringify(err)); }); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-privacyManager.md b/zh-cn/application-dev/reference/apis/js-apis-privacyManager.md index 27194b10e072fb54ef5f7ed0b672606ff08a9d0d..038b1311f6fefab47e05daca0673c006cd410d86 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-privacyManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-privacyManager.md @@ -102,7 +102,7 @@ import privacyManager from '@ohos.privacyManager'; let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId try { - privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (data, err) => { + privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (err, data) => { if (err) { console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`); } else { @@ -310,7 +310,7 @@ import privacyManager from '@ohos.privacyManager'; let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId try { - privacyManager.startUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (data, err) => { + privacyManager.startUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (err, data) => { if (err) { console.log(`startUsingPermission fail, err->${JSON.stringify(err)}`); } else { @@ -407,7 +407,7 @@ import privacyManager from '@ohos.privacyManager'; let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId try { - privacyManager.stopUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (data, err) => { + privacyManager.stopUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (err, data) => { if (err) { console.log(`stopUsingPermission fail, err->${JSON.stringify(err)}`); } else { diff --git a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md index 8e0d56e259370626ab8ae9ee807f3863b0871210..6a2c1cea64c78d772e7bd40058d450396f4e7a10 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @@ -13,7 +13,7 @@ ## 导入模块 -``` +```js import reminderAgent from'@ohos.reminderAgent'; ``` @@ -91,7 +91,7 @@ cancelReminder(reminderId: number, callback: AsyncCallback<void>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| reminderId | number | 是 | 目标reminder的id号。 | +| reminderId | number | 是 | 目标reminder的id号，[publishReminder](#reminderagentpublishreminder)方法调用成功后获得。 | | callback | AsyncCallback<void> | 是 | 异步回调。 | **示例**： @@ -115,7 +115,7 @@ cancelReminder(reminderId: number): Promise<void> | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| reminderId | number | 是 | 目标reminder的id号。 | +| reminderId | number | 是 | 目标reminder的id号，[publishReminder](#reminderagentpublishreminder)方法调用成功后获得。 | **返回值**： @@ -455,10 +455,10 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | 名称 | 参数类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| reminderType | ReminderType | 是 | 指明提醒类型。 | -| actionButton | [ActionButton?, ActionButton?] | 否 | 弹出的提醒通知栏中显示的按钮（参数可选，支持0/1/2个按钮）。 | -| wantAgent | WantAgent | 否 | 点击通知后需要跳转的目标ability信息。 | -| maxScreenWantAgent | MaxScreenWantAgent | 否 | 提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框。 | +| reminderType | [ReminderType](#remindertype) | 是 | 指明提醒类型。 | +| actionButton | [ActionButton](#actionbutton) | 否 | 弹出的提醒通知栏中显示的按钮（参数可选，支持0/1/2个按钮）。 | +| wantAgent | [WantAgent](#wantagent) | 否 | 点击通知后需要跳转的目标ability信息。 | +| maxScreenWantAgent | [MaxScreenWantAgent](#maxscreenwantagent) | 否 | 提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框。 | | ringDuration | number | 否 | 指明响铃时长。 | | snoozeTimes | number | 否 | 指明延迟提醒次数。 | | timeInterval | number | 否 | 执行延迟提醒间隔。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-request.md b/zh-cn/application-dev/reference/apis/js-apis-request.md index 1ba8a552f29850c589f0f192910fd6e7bb740ee7..c379b82a1b868a981002f162727565e9eb3dd773 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-request.md +++ b/zh-cn/application-dev/reference/apis/js-apis-request.md @@ -33,6 +33,7 @@ var config = { 在开发stage模型下的应用程序时，不涉及属性标识 "cleartextTraffic"。 +下载服务器需要支持http协议的header方法，能够通过content-length获取下载数据大小，否则下载任务失败，可通过[on('fail')7+)](#onfail7)查看失败原因。 ## 常量 @@ -53,6 +54,8 @@ var config = { | ERROR_INSUFFICIENT_SPACE7+ | number | 是 | 否 | 存储空间不足。 | | ERROR_TOO_MANY_REDIRECTS7+ | number | 是 | 否 | 网络重定向过多导致的错误。 | | ERROR_UNHANDLED_HTTP_CODE7+ | number | 是 | 否 | 无法识别的HTTP代码。 | +| ERROR_OFFLINE9+ | number | 是 | 否 | 网络未连接。 | +| ERROR_UNSUPPORTED_NETWORK_TYPE9+ | number | 是 | 否 | 网络类型不匹配。 | | ERROR_UNKNOWN7+ | number | 是 | 否 | 未知错误。 | | PAUSED_QUEUED_FOR_WIFI7+ | number | 是 | 否 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 | | PAUSED_UNKNOWN7+ | number | 是 | 否 | 未知原因导致暂停下载。 | @@ -73,6 +76,8 @@ upload(config: UploadConfig): Promise<UploadTask> 此接口仅可在FA模型下使用 +> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile9+](#requestuploadfile9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Upload @@ -116,6 +121,8 @@ upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void 此接口仅可在FA模型下使用 +> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile9+](#requestuploadfile9-1)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Upload @@ -152,6 +159,8 @@ upload(context: BaseContext, config: UploadConfig): Promise<UploadTask> 上传，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile9+](#requestuploadfile9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Upload @@ -195,6 +204,8 @@ upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<Up 上传，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile9+](#requestuploadfile9-1)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Upload @@ -227,6 +238,103 @@ upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<Up }); ``` + +## request.uploadFile9+ + +uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> + +上传，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| context | BaseContext | 是 | 基于应用程序的上下文。 | +| config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | + + +**返回值：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<[UploadTask](#uploadtask)> | 返回上传任务。 | + +**错误码：** +以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。 + +| 错误码ID | 错误码信息 | +| -------- | -------- | +| 13400002 | Bad file path. | + +**示例：** + + ```js + let uploadTask; + let uploadConfig = { + url: 'https://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }, + data: { name: "name123", value: "123" }, + }; + request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { + uploadTask = data; + }).catch((err) => { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + }); + ``` + + +## request.uploadFile9+ + +uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void + +上传，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| context | BaseContext | 是 | 基于应用程序的上下文。 | +| config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | +| callback | AsyncCallback<[UploadTask](#uploadtask)> | 否 | 回调函数，异步返回UploadTask对象。 | + +**错误码：** +以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。 + +| 错误码ID | 错误码信息 | +| -------- | -------- | +| 13400002 | Bad file path. | + +**示例：** + + ```js + let uploadTask; + let uploadConfig = { + url: 'https://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + }; + request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { + if (err) { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + return; + } + uploadTask = data; + }); + ``` + + ## UploadTask 上传任务，使用下列方法前，需要先获取UploadTask对象。 @@ -455,6 +563,8 @@ remove(): Promise<boolean> 移除上传的任务，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[delete9+](#delete9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Upload @@ -486,6 +596,8 @@ remove(callback: AsyncCallback<boolean>): void 移除上传的任务，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[delete9+](#delete9-1)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Upload @@ -513,6 +625,70 @@ remove(callback: AsyncCallback<boolean>): void ``` +### delete9+ + +delete(): Promise<boolean> + +移除上传的任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +**返回值：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | + +**示例：** + + ```js + uploadTask.delete().then((result) => { + if (result) { + console.info('Upload task removed successfully. '); + } else { + console.error('Failed to remove the upload task. '); + } + }).catch((err) => { + console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); + }); + ``` + + +### delete9+ + +delete(callback: AsyncCallback<boolean>): void + +移除上传的任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Upload + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | + +**示例：** + + ```js + uploadTask.delete((err, result) => { + if (err) { + console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Upload task removed successfully.'); + } else { + console.error('Failed to remove the upload task.'); + } + }); + ``` + + ## UploadConfig **需要权限**：ohos.permission.INTERNET @@ -543,21 +719,21 @@ remove(callback: AsyncCallback<boolean>): void **需要权限**：ohos.permission.INTERNET -**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download +**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 | 名称 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| filename | string | 否 | multipart提交时，请求头中的文件名。 | -| name | string | 否 | multipart提交时，表单项目的名称，缺省为file。 | +| filename | string | 是 | multipart提交时，请求头中的文件名。 | +| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 | | uri | string | 是 | 文件的本地存储路径。
支持“dataability”和“internal”两种协议类型，但“internal”仅支持临时目录，示例：
dataability:///com.domainname.dataability.persondata/person/10/file.txt
internal://cache/path/to/file.txt | -| type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | +| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | ## RequestData **需要权限**：ohos.permission.INTERNET -**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download +**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 | 名称 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | @@ -571,6 +747,8 @@ download(config: DownloadConfig): Promise<DownloadTask> 下载，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile9+](#requestdownloadfile9)替代。 + 此接口仅可在FA模型下使用 **需要权限**：ohos.permission.INTERNET @@ -607,6 +785,8 @@ download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): v 下载，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile9+](#requestdownloadfile9-1)替代。 + 此接口仅可在FA模型下使用 **需要权限**：ohos.permission.INTERNET @@ -640,6 +820,8 @@ download(context: BaseContext, config: DownloadConfig): Promise<DownloadTask& 下载，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile9+](#requestdownloadfile9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -675,6 +857,8 @@ download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&l 下载，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile9+](#requestdownloadfile9-1)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -700,6 +884,94 @@ download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&l downloadTask = data; }); ``` + + +## request.downloadFile9+ + +downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> + +下载，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| context | BaseContext | 是 | 基于应用程序的上下文。 | +| config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | + +**返回值：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | + +**错误码：** +以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。 + +| 错误码ID | 错误码信息 | +| -------- | -------- | +| 13400001 | File operation error. | +| 13400002 | Bad file path. | +| 13400003 | Task manager service error. | + +**示例：** + + ```js + let downloadTask; + request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { + downloadTask = data; + }).catch((err) => { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + }) + ``` + + +## request.downloadFile9+ + +downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; + +下载，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| context | BaseContext | 是 | 基于应用程序的上下文。 | +| config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | +| callback | AsyncCallback<[DownloadTask](#downloadtask)> | 否 | 下载接口的回调函数。 | + +**错误码：** +以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。 + +| 错误码ID | 错误码信息 | +| -------- | -------- | +| 13400001 | File operation error. | +| 13400002 | Bad file path. | +| 13400003 | Task manager service error. | + +**示例：** + + ```js + let downloadTask; + request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', + filePath: 'xxx/xxxxx.hap'}, (err, data) => { + if (err) { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + return; + } + downloadTask = data; + }); + ``` + + ## DownloadTask 下载任务。 @@ -899,6 +1171,8 @@ remove(): Promise<boolean> 移除下载的任务，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[delete9+](#delete9-2)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -930,6 +1204,8 @@ remove(callback: AsyncCallback<boolean>): void 移除下载的任务，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[delete9+](#delete9-3)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -963,6 +1239,8 @@ query(): Promise<DownloadInfo> 查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 +> **说明：** 从API Version 9开始废弃，建议使用[getTaskInfo9+](#gettaskinfo9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -989,6 +1267,8 @@ query(callback: AsyncCallback<DownloadInfo>): void 查询下载的任务，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[getTaskInfo9+](#gettaskinfo9-1)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -1018,6 +1298,8 @@ queryMimeType(): Promise<string> 查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[getTaskMimeType9+](#gettaskmimetype9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -1045,6 +1327,8 @@ queryMimeType(callback: AsyncCallback<string>): void; 查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[getTaskMimeType9+](#gettaskmimetype9-1)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -1074,6 +1358,8 @@ pause(): Promise<void> 暂停下载任务，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[suspend9+](#suspend9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -1103,6 +1389,8 @@ pause(): Promise<void> pause(callback: AsyncCallback<void>): void +> **说明：** 从API Version 9开始废弃，建议使用[suspend9+](#suspend9-1)替代。 + 暂停下载任务，异步方法，使用callback形式返回结果。 **需要权限**：ohos.permission.INTERNET @@ -1138,6 +1426,8 @@ resume(): Promise<void> 重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 +> **说明：** 从API Version 9开始废弃，建议使用[restore9+](#restore9)替代。 + **需要权限**：ohos.permission.INTERNET **系统能力**: SystemCapability.MiscServices.Download @@ -1168,6 +1458,8 @@ resume(): Promise<void> resume(callback: AsyncCallback<void>): void +> **说明：** 从API Version 9开始废弃，建议使用[restore9+](#restore9-1)替代。 + 重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 **需要权限**：ohos.permission.INTERNET @@ -1197,6 +1489,310 @@ resume(callback: AsyncCallback<void>): void ``` +### delete9+ + +delete(): Promise<boolean> + +移除下载的任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**返回值：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<boolean> | 移除任务是否成功。 | + +**示例：** + + ```js + downloadTask.delete().then((result) => { + if (result) { + console.info('Download task removed.'); + } else { + console.error('Failed to remove the download task.'); + } + }).catch ((err) => { + console.error('Failed to remove the download task.'); + }); + ``` + + +### delete9+ + +delete(callback: AsyncCallback<boolean>): void + +移除下载的任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | + +**示例：** + + ```js + downloadTask.delete((err, result)=>{ + if(err) { + console.error('Failed to remove the download task.'); + return; + } + if (result) { + console.info('Download task removed.'); + } else { + console.error('Failed to remove the download task.'); + } + }); + ``` + + +### getTaskInfo9+ + +getTaskInfo(): Promise<DownloadInfo> + +查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** +| 类型 | 说明 | +| -------- | -------- | +| Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | + +**示例：** + + ```js + downloadTask.getTaskInfo().then((downloadInfo) => { + console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) + }) .catch((err) => { + console.error('Failed to query the download task. Cause:' + err) + }); + ``` + + +### getTaskInfo9+ + +query(callback: AsyncCallback<DownloadInfo>): void + +查询下载的任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | + +**示例：** + + ```js + downloadTask.getTaskInfo((err, downloadInfo)=>{ + if(err) { + console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); + } else { + console.info('download query success. data:'+ JSON.stringify(downloadInfo)); + } + }); + ``` + + +### getTaskMimeType9+ + +getTaskMimeType(): Promise<string> + +查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**返回值：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<string> | 查询下载任务的MimeType。 | + +**示例：** + + ```js + downloadTask.getTaskMimeType().then((data) => { + console.info('Download task queried. Data:' + JSON.stringify(data)); + }).catch((err) => { + console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) + }); + ``` + + +### getTaskMimeType9+ + +getTaskMimeType(callback: AsyncCallback<string>): void; + +查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | + +**示例：** + + ```js + downloadTask.getTaskMimeType((err, data)=>{ + if(err) { + console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); + } else { + console.info('Download task queried. data:' + JSON.stringify(data)); + } + }); + ``` + + +### suspend9+ + +suspend(): Promise<void> + +暂停下载任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**返回值：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<void> | 暂停下载任务是否成功。 | + +**示例：** + + ```js + downloadTask.suspend().then((result) => { + if (result) { + console.info('Download task paused. '); + } else { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); + } + }).catch((err) => { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); + }); + ``` + + +### suspend9+ + +suspend(callback: AsyncCallback<void>): void + +暂停下载任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | 是 | 暂停下载任务的回调函数。 | + +**示例：** + + ```js + downloadTask.suspend((err, result)=>{ + if(err) { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Download task paused. '); + } else { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); + } + }); + ``` + + +### restore9+ + +restore(): Promise<void> + +重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 类型 | 说明 | + | -------- | -------- | +| Promise<void> | 重新启动暂停的下载任务是否成功。 | + +**示例：** + + ```js + downloadTask.restore().then((result) => { + if (result) { + console.info('Download task resumed.') + } else { + console.error('Failed to resume the download task. '); + } + console.info('Download task resumed.') + }).catch((err) => { + console.error('Failed to resume the download task. Cause:' + err); + }); + ``` + + +### restore9+ + +restore(callback: AsyncCallback<void>): void + +重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**: SystemCapability.MiscServices.Download + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | 是 | 重新启动暂停的下载任务的回调函数。 | + +**示例：** + + ```js + downloadTask.restore((err, result)=>{ + if (err) { + console.error('Failed to resume the download task. Cause:' + err); + return; + } + if (result) { + console.info('Download task resumed.'); + } else { + console.error('Failed to resume the download task.'); + } + }); + ``` + + ## DownloadConfig **需要权限**：ohos.permission.INTERNET diff --git a/zh-cn/application-dev/reference/apis/js-apis-sensor.md b/zh-cn/application-dev/reference/apis/js-apis-sensor.md index 90c18d897092a30423a010bb41096440571f9964..de9ec2ae2b856bbf0f36bb7a98e41d90f0f584b1 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-sensor.md +++ b/zh-cn/application-dev/reference/apis/js-apis-sensor.md @@ -340,7 +340,7 @@ try { on(type: SensorId.HALL, callback: Callback<HallResponse>, options?: Options): void -订阅心率传感器数据。 +订阅霍尔传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor @@ -446,7 +446,7 @@ try { } ``` -### LINEAR_ACCELERATION9+ +### LINEAR_ACCELEROMETER9+ on(type: SensorId.LINEAR_ACCELEROMETER, callback: Callback<LinearAccelerometerResponse>, options?: Options): void @@ -799,7 +799,7 @@ try { on(type: SensorId.WEAR_DETECTION, callback: Callback<WearDetectionResponse>, options?: Options): void -订阅磨损检测传感器数据。 +订阅佩戴检测传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor @@ -1255,7 +1255,7 @@ try { } ``` -### LINEAR_ACCELERATION9+ +### LINEAR_ACCELEROMETER9+ once(type: SensorId.LINEAR_ACCELEROMETER, callback: Callback<LinearAccelerometerResponse>): void @@ -1603,7 +1603,7 @@ try { once(type: SensorId.WEAR_DETECTION, callback: Callback<WearDetectionResponse>): void -订阅一次磨损检测传感器数据。 +订阅一次佩戴检测传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor @@ -2244,7 +2244,7 @@ try { off(type: SensorId.WEAR_DETECTION, callback?: Callback<WearDetectionResponse>): void -取消订阅磨损检测传感器数据。 +取消订阅佩戴检测传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor @@ -3637,7 +3637,7 @@ on(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback<Line 监听线性加速度传感器的数据变化。如果多次调用该接口，仅最后一次调用生效。 -从API version 9 开始不再维护，建议使用[sensor.on.LINEAR_ACCELEROMETER](#linear_accelerometer9)代替。 +从API version 9 开始不再维护，建议使用[sensor.on.LINEAR_ACCELEROMETER](#linear_accelerometer9)代替。 **需要权限**：ohos.permission.ACCELEROMETER @@ -3651,36 +3651,6 @@ on(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback<Line | callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 是 | 注册线性加速度传感器的回调函数，上报的数据类型为LinearAccelerometerResponse。 | | options | [Options](#options) | 否 | 可选参数列表，设置上报频率，默认值为200000000ns。 | -### LINEAR_ACCELEROMETER9+ - -on(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback<LinearAccelerometerResponse>, - options?: Options): void - -监听线性加速度传感器的数据变化。如果多次调用该接口，仅最后一次调用生效。 - -**需要权限**：ohos.permission.ACCELEROMETER - -**系统能力**：SystemCapability.Sensors.Sensor - -**参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorType](#sensortype) | 是 | 要订阅的线性加速度传感器类型为SENSOR_TYPE_ID_LINEAR_ACCELEROMETER。 | -| callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 是 | 注册线性加速度传感器的回调函数，上报的数据类型为LinearAccelerometerResponse。 | -| options | [Options](#options) | 否 | 可选参数列表，设置上报频率，默认值为200000000ns。 | - -**示例：** - - ```js - sensor.on(sensor.SensorType.SENSOR_TYPE_ID_LINEAR_ACCELEROMETER,function(data){ - console.info('X-coordinate component: ' + data.x); - console.info('Y-coordinate component: ' + data.y); - console.info('Z-coordinate component: ' + data.z); - }, - {interval: 10000000} - ); - ``` - ### ACCELEROMETER_UNCALIBRATED(deprecated) on(type: SensorType.SENSOR_TYPE_ID_ACCELEROMETER_UNCALIBRATED,callback: Callback<AccelerometerUncalibratedResponse>, options?: Options): void @@ -4157,7 +4127,7 @@ on(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback: Callback<HeartRateRe 监听心率传感器数据变化一次。 -从API version 9 开始不再维护，建议使用[sensor.on.HEART_BEAT_RATE](#heart_beat_rate9)代替。 +从API version 9 开始不再维护，建议使用[sensor.on.HEART_RATE](#heart_rate9)代替。 **需要权限**：ohos.permission.HEALTH_DATA @@ -4170,34 +4140,6 @@ on(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback: Callback<HeartRateRe | type | [SensorType](#sensortype) | 是 | 要订阅的心率传感器类型为SENSOR_TYPE_ID_HEART_RATE。 | | callback | Callback<[HeartRateResponse](#heartrateresponse)> | 是 | 注册一次心率传感器的回调函数，上报的数据类型为HeartRateResponse。 | -### HEART_BEAT_RATE9+ - -on(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback: Callback<HeartRateResponse>, - options?: Options): void - -监听心率传感器数据变化一次。 - -**需要权限**：ohos.permission.HEALTH_DATA - -**系统能力**：SystemCapability.Sensors.Sensor - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorType](#sensortype) | 是 | 要订阅的心率传感器类型为SENSOR_TYPE_ID_HEART_BEAT_RATE。 | -| callback | Callback<[HeartRateResponse](#heartrateresponse)> | 是 | 注册一次心率传感器的回调函数，上报的数据类型为HeartRateResponse。 | - -**示例：** - -```js -sensor.on(sensor.SensorType.SENSOR_TYPE_ID_HEART_BEAT_RATE,function(data){ - console.info("Heart rate: " + data.heartRate); -}, - {interval: 10000000} -); -``` - ### ROTATION_VECTOR(deprecated) on(type: SensorType.SENSOR_TYPE_ID_ROTATION_VECTOR,callback: Callback<RotationVectorResponse>,options?: Options): void @@ -4292,7 +4234,7 @@ once(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback<Li 监听线性加速度传感器数据变化一次。 -从API version 9 开始不再维护，建议使用[sensor.once.LINEAR_ACCELEROMETER](#linear_accelerometer9)代替。 +从API version 9 开始不再维护，建议使用[sensor.once.LINEAR_ACCELEROMETER](#linear_accelerometer9-1)代替。 **需要权限**：ohos.permission.ACCELERATION @@ -4305,33 +4247,6 @@ once(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback<Li | type | [SensorType](#sensortype) | 是 | 线性加速度传感器类型为SENSOR_TYPE_ID_LINEAR_ACCELERATION。 | | callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 是 | 注册一次线性加速度传感器的回调函数，上报的数据类型为LinearAccelerometerResponse。 | -### LINEAR_ACCELEROMETER9+ - -once(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback<LinearAccelerometerResponse>): void - -订阅一次线性加速度传感器数据。 - -**需要权限**：ohos.permission.ACCELERATION - -**系统能力**：SystemCapability.Sensors.Sensor - -**参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorType](#sensortype) | 是 | 线性加速度传感器类型为SENSOR_TYPE_ID_LINEAR_ACCELEROMETER。 | -| callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 是 | 注册一次线性加速度传感器的回调函数，上报的数据类型为LinearAccelerometerResponse。 | - -**示例：** - - ```js - sensor.once(sensor.SensorType.SENSOR_TYPE_ID_LINEAR_ACCELEROMETER, function(data) { - console.info('X-coordinate component: ' + data.x); - console.info('Y-coordinate component: ' + data.y); - console.info('Z-coordinate component: ' + data.z); - } - ); - ``` - ### ACCELEROMETER_UNCALIBRATED(deprecated) once(type: SensorType.SENSOR_TYPE_ID_ACCELEROMETER_UNCALIBRATED,callback: Callback<AccelerometerUncalibratedResponse>): void @@ -4800,7 +4715,7 @@ once(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback: Callback<HeartRate 监听心率传感器数据变化一次。 -从API version 9 开始不再维护，建议使用[sensor.once.HEART_BEAT_RATE](#heart_beat_rate9)代替。 +从API version 9 开始不再维护，建议使用[sensor.once.HEART_RATE](#heart_rate9-1)代替。 **需要权限**：ohos.permission.HEART_RATE @@ -4813,32 +4728,6 @@ once(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback: Callback<HeartRate | type | [SensorType](#sensortype) | 是 | 心率传感器类型为SENSOR_TYPE_ID_HEART_RATE。 | | callback | Callback<[HeartRateResponse](#heartrateresponse)> | 是 | 注册一次心率传感器的回调函数，上报的数据类型为HeartRateResponse。 | -### HEART_BEAT_RATE9+ - -once(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback: Callback<HeartRateResponse>): void - -订阅一次心率传感器数据。 - -**需要权限**：ohos.permission.HEART_RATE - -**系统能力**：SystemCapability.Sensors.Sensor - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorType](#sensortype) | 是 | 心率传感器类型为SENSOR_TYPE_ID_HEART_BEAT_RATE。 | -| callback | Callback<[HeartRateResponse](#heartrateresponse)> | 是 | 注册一次心率传感器的回调函数，上报的数据类型为HeartRateResponse。 | - -**示例：** - - ```js - sensor.once(sensor.SensorType.SENSOR_TYPE_ID_HEART_BEAT_RATE, function(data) { - console.info("Heart rate: " + data.heartRate); - } - ); - ``` - ### WEAR_DETECTION(deprecated) once(type: SensorType.SENSOR_TYPE_ID_WEAR_DETECTION, callback: Callback<WearDetectionResponse>): void @@ -5127,7 +5016,7 @@ off(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback?: Callback<HeartRate 取消订阅传感器数据。 -从API version 9 开始不再维护，建议使用[sensor.off.HEART_BEAT_RATE](#heart_beat_rate9)代替。 +从API version 9 开始不再维护，建议使用[sensor.off.HEART_RATE](#heart_rate9-2)代替。 **需要权限**：ohos.permission.HEALTH_DATA @@ -5140,32 +5029,6 @@ off(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback?: Callback<HeartRate | type | [SensorType](#sensortype) | 是 | 要取消订阅的心率传感器类型为SENSOR_TYPE_ID_HEART_RATE。 | | callback | Callback<[HeartRateResponse](#heartrateresponse)> | 是 | 取消注册一次心率传感器的回调函数，上报的数据类型为HeartRateResponse。 | -### HEART_BEAT_RATE9+ - -off(type: SensorType.SENSOR_TYPE_ID_HEART_RATE, callback?: Callback<HeartRateResponse>): void - -取消订阅传感器数据。 - -**需要权限**：ohos.permission.HEALTH_DATA - -**系统能力**：SystemCapability.Sensors.Sensor - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorType](#sensortype) | 是 | 要取消订阅的心率传感器类型为SENSOR_TYPE_ID_HEART_BEAT_RATE。 | -| callback | Callback<[HeartRateResponse](#heartrateresponse)> | 是 | 取消注册一次心率传感器的回调函数，上报的数据类型为HeartRateResponse。 | - -**示例：** - -```js -function callback(data) { - console.info("Heart rate: " + data.heartRate); -} -sensor.off(sensor.SensorType.SENSOR_TYPE_ID_HEART_BEAT_RATE, callback); -``` - ### HUMIDITY(deprecated) off(type: SensorType.SENSOR_TYPE_ID_HUMIDITY, callback?: Callback<HumidityResponse>): void @@ -5198,7 +5061,7 @@ off(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION, callback?: Callback< 取消订阅传感器数据。 -从API version 9 开始不再维护，建议使用[sensor.off.LINEAR_ACCELEROMETER](#linear_accelerometer9)代替。 +从API version 9 开始不再维护，建议使用[sensor.off.LINEAR_ACCELEROMETER](#linear_accelerometer9-2)代替。 **需要权限**：ohos.permission.ACCELEROMETER @@ -5211,34 +5074,6 @@ off(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION, callback?: Callback< | type | [SensorType](#sensortype) | 是 | 要取消订阅的线性加速度传感器类型为SENSOR_TYPE_ID_LINEAR_ACCELERATION。 | | callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 是 | 取消注册性加速度传感器的回调函数，上报的数据类型为LinearAccelerometerResponse。 | -### LINEAR_ACCELEROMETER9+ - -off(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback?:Callback<LinearAccelerometerResponse>): void - -取消订阅传感器数据。 - -**需要权限**：ohos.permission.ACCELEROMETER - -**系统能力**：SystemCapability.Sensors.Sensor - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorType](#sensortype) | 是 | 要取消订阅的线性加速度传感器类型为SENSOR_TYPE_ID_LINEAR_ACCELEROMETER。 | -| callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 是 | 取消注册性加速度传感器的回调函数，上报的数据类型为LinearAccelerometerResponse。 | - -**示例：** - -```js -function callback(data) { - console.info('X-coordinate component: ' + data.x); - console.info('Y-coordinate component: ' + data.y); - console.info('Z-coordinate component: ' + data.z); -} -sensor.off(sensor.SensorType.SENSOR_TYPE_ID_LINEAR_ACCELEROMETER, callback); -``` - ### MAGNETIC_FIELD(deprecated) off(type: SensorType.SENSOR_TYPE_ID_MAGNETIC_FIELD, callback?: Callback<MagneticFieldResponse>): void diff --git a/zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md b/zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md new file mode 100644 index 0000000000000000000000000000000000000000..0c20c4b3b4aa03f528d7d8b7a23f6887a95c34cf --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md @@ -0,0 +1,862 @@ +# USB管理 + +本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。 + +> **说明：** +> +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +> 从API version 9开始，该接口不再维护，推荐使用新接口[`@ohos.usbV9`](js-apis-usb.md)。 + +## 导入模块 + +```js +import usb from "@ohos.usb"; +``` + +## usb.getDevices + +getDevices(): Array<Readonly<USBDevice>> + +获取USB设备列表。 + +**系统能力：** SystemCapability.USB.USBManager + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------------------- | ------- | +| Array<Readonly<[USBDevice](#usbdevice)>> | 设备信息列表。 | + +**示例：** + +```js +let devicesList = usb.getDevices(); +console.log(`devicesList = ${JSON.stringify(devicesList)}`); +//devicesList 返回的数据结构 +//此处提供一个简单的示例，如下 +[ + { + name: "1-1", + serial: "", + manufacturerName: "", + productName: "", + version: "", + vendorId: 7531, + productId: 2, + clazz: 9, + subclass: 0, + protocol: 1, + devAddress: 1, + busNum: 1, + configs: [ + { + id: 1, + attributes: 224, + isRemoteWakeup: true, + isSelfPowered: true, + maxPower: 0, + name: "1-1", + interfaces: [ + { + id: 0, + protocol: 0, + clazz: 9, + subclass: 0, + alternateSetting: 0, + name: "1-1", + endpoints: [ + { + address: 129, + attributes: 3, + interval: 12, + maxPacketSize: 4, + direction: 128, + number: 1, + type: 3, + interfaceId: 0, + }, + ], + }, + ], + }, + ], + }, +] +``` + +## usb.connectDevice + +connectDevice(device: USBDevice): Readonly<USBDevicePipe> + +打开USB设备。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| device | [USBDevice](#usbdevice) | 是 | USB设备信息。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | + +**示例：** + +```js +let devicepipe= usb.connectDevice(device); +console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); +``` + +## usb.hasRight + +hasRight(deviceName: string): boolean + +判断是否有权访问该设备。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。 | + +**示例：** + +```js +let devicesName="1-1"; +let bool = usb.hasRight(devicesName); +console.log(bool); +``` + +## usb.requestRight + +requestRight(deviceName: string): Promise<boolean> + +请求软件包的临时权限以访问设备。使用Promise异步回调。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<boolean> | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。 | + +**示例：** + +```js +let devicesName="1-1"; +usb.requestRight(devicesName).then((ret) => { + console.log(`requestRight = ${JSON.stringify(ret)}`); +}); +``` + +## usb.claimInterface + +claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number + +注册通信接口。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引。 | +| force | boolean | 否 | 可选参数，是否强制获取。默认值为false ，表示不强制获取。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 注册通信接口成功返回0；注册通信接口失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.claimInterface(devicepipe, interfaces); +console.log(`claimInterface = ${ret}`); +``` + +## usb.releaseInterface + +releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number + +释放注册过的通信接口。 + +需要调用[usb.claimInterface](#usbclaiminterface)先获取接口，才能使用此方法释放接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 释放接口成功返回0；释放接口失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.releaseInterface(devicepipe, interfaces); +console.log(`releaseInterface = ${ret}`); +``` + +## usb.setConfiguration + +setConfiguration(pipe: USBDevicePipe, config: USBConfig): number + +设置设备配置。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及config；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| config | [USBConfig](#usbconfig) | 是 | 用于确定需要设置的配置。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.setConfiguration(devicepipe, config); +console.log(`setConfiguration = ${ret}`); +``` + +## usb.setInterface + +setInterface(pipe: USBDevicePipe, iface: USBInterface): number + +设置设备接口。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数；调用[usb.claimInterface](#usbclaiminterface)注册通信接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------------------------------- | --- | ------------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.setInterface(devicepipe, interfaces); +console.log(`setInterface = ${ret}`); +``` + +## usb.getRawDescriptor + +getRawDescriptor(pipe: USBDevicePipe): Uint8Array + +获取原始的USB描述符。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Uint8Array | 返回获取的原始数据；失败返回undefined。 | + +**示例：** + +```js +let ret = usb.getRawDescriptor(devicepipe); +``` + +## usb.getFileDescriptor + +getFileDescriptor(pipe: USBDevicePipe): number + +获取文件描述符。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | -------------------- | +| number | 返回设备对应的文件描述符；失败返回-1。 | + +**示例：** + +```js +let ret = usb.getFileDescriptor(devicepipe); +``` + +## usb.controlTransfer + +controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise<number> + +控制传输。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | +| contrlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数。 | +| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | + +**示例：** + +```js +usb.controlTransfer(devicepipe, USBControlParams).then((ret) => { + console.log(`controlTransfer = ${JSON.stringify(ret)}`); +}) +``` + +## usb.bulkTransfer + +bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise<number> + +批量传输。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息列表以及endpoint；再调用[usb.requestRight](#usbrequestright)获取设备请求权限；然后调用[usb.connectDevice](#usbconnectdevice)接口得到返回数据devicepipe之后，再次获取接口[usb.claimInterface](#usbclaiminterface)；再调用usb.bulkTransfer接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | +| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口。 | +| buffer | Uint8Array | 是 | 用于写入或读取的缓冲区。 | +| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。| + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | + +**示例：** + +```js +//usb.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。 +//把获取到的设备对象作为参数传入usb.connectDevice;当usb.connectDevice接口成功返回之后； +//才可以调用第三个接口usb.claimInterface.当usb.claimInterface 调用成功以后,再调用该接口。 +usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => { + console.log(`bulkTransfer = ${JSON.stringify(ret)}`); +}); +``` + +## usb.closePipe + +closePipe(pipe: USBDevicePipe): number + +关闭设备消息控制通道。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.closePipe(devicepipe); +console.log(`closePipe = ${ret}`); +``` + +## usb.usbFunctionsFromString9+ + +usbFunctionsFromString(funcs: string): number + +在设备模式下，将字符串形式的USB功能列表转化为数字掩码。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------- | +| funcs | string | 是 | 字符串形式的功能列表。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------ | +| number | 转化后的数字掩码。 | + +**示例：** + +```js +let funcs = "acm"; +let ret = usb.usbFunctionsFromString(funcs); +``` + +## usb.usbFunctionsToString9+ + +usbFunctionsToString(funcs: FunctionType): string + +在设备模式下，将数字掩码形式的USB功能列表转化为字符串。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | ----------------- | +| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------------ | +| string | 转化后的字符串形式的功能列表。 | + +**示例：** + +```js +let funcs = ACM | ECM; +let ret = usb.usbFunctionsToString(funcs); +``` + +## usb.setCurrentFunctions9+ + +setCurrentFunctions(funcs: FunctionType): Promise\ + +在设备模式下，设置当前的USB功能列表。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | ----------------- | +| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise\ | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 | + +**示例：** + +```js +let funcs = HDC; +let ret = usb.setCurrentFunctions(funcs); +``` + +## usb.getCurrentFunctions9+ + +getCurrentFunctions(): FunctionType + +在设备模式下，获取当前的USB功能列表的数字组合掩码。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**返回值：** + +| 类型 | 说明 | +| ------------------------------ | --------------------------------- | +| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 | + +**示例：** + +```js +let ret = usb.getCurrentFunctions(); +``` + +## usb.getPorts9+ + +getPorts(): Array\ + +获取所有物理USB端口描述信息。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | --------------------- | +| [Array\](#usbport9) | USB端口描述信息列表。 | + +**示例：** + +```js +let ret = usb.getPorts(); +``` + +## usb.getSupportedModes9+ + +getSupportedModes(portId: number): PortModeType + +获取指定的端口支持的模式列表的组合掩码。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------- | +| portId | number | 是 | 端口号。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------ | -------------------------- | +| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 | + +**示例：** + +```js +let ret = usb.getSupportedModes(0); +``` + +## usb.setPortRoles9+ + +setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\ + +设置指定的端口支持的角色模式，包含充电角色、数据传输角色。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | -------------------------------- | ---- | ---------------- | +| portId | number | 是 | 端口号。 | +| powerRole | [PowerRoleType](#powerroletype9) | 是 | 充电的角色。 | +| dataRole | [DataRoleType](#dataroletype9) | 是 | 数据传输的角色。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise\ | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 | + +**示例：** + +```js +let ret = usb.getSupportedModes(0); +``` + +## USBEndpoint + +通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ------------- | ------------------------------------------- | ------------- | +| address | number | 端点地址。 | +| attributes | number | 端点属性。 | +| interval | number | 端点间隔。 | +| maxPacketSize | number | 端点最大数据包大小。 | +| direction | [USBRequestDirection](#usbrequestdirection) | 端点的方向。 | +| number | number | 端点号。 | +| type | number | 端点类型。 | +| interfaceId | number | 端点所属的接口的唯一标识。 | + +## USBInterface + +一个[USBConfig](#usbconfig)中可以含有多个USBInterface，每个USBInterface提供一个功能。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------------- | ---------------------------------------- | --------------------- | +| id | number | 接口的唯一标识。 | +| protocol | number | 接口的协议。 | +| clazz | number | 设备类型。 | +| subClass | number | 设备子类。 | +| alternateSetting | number | 在同一个接口中的多个描述符中进行切换设置。 | +| name | string | 接口名称。 | +| endpoints | Array<[USBEndpoint](#usbendpoint)> | 当前接口所包含的端点。 | + +## USBConfig + +USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| -------------- | ------------------------------------------------ | --------------- | +| id | number | 配置的唯一标识。 | +| attributes | number | 配置的属性。 | +| maxPower | number | 最大功耗，以毫安为单位。 | +| name | string | 配置的名称，可以为空。 | +| isRemoteWakeup | boolean | 检查当前配置是否支持远程唤醒。 | +| isSelfPowered | boolean | 检查当前配置是否支持独立电源。 | +| interfaces | Array <[USBInterface](#usbinterface)> | 配置支持的接口属性。 | + +## USBDevice + +USB设备信息。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------------- | ------------------------------------ | ---------- | +| busNum | number | 总线地址。 | +| devAddress | number | 设备地址。 | +| serial | string | 序列号。 | +| name | string | 设备名字。 | +| manufacturerName | string | 产商信息。 | +| productName | string | 产品信息。 | +| version | string | 版本。 | +| vendorId | number | 厂商ID。 | +| productId | number | 产品ID。 | +| clazz | number | 设备类。 | +| subClass | number | 设备子类。 | +| protocol | number | 设备协议码。 | +| configs | Array<[USBConfig](#usbconfig)> | 设备配置描述符信息。 | + +## USBDevicePipe + +USB设备消息传输通道，用于确定设备。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------- | ------ | ----- | +| busNum | number | 总线地址。 | +| devAddress | number | 设备地址。 | + +## USBControlParams + +控制传输参数。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ------- | ----------------------------------------------- | ---------------- | +| request | number | 请求类型。 | +| target | [USBRequestTargetType](#usbrequesttargettype) | 请求目标类型。 | +| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 请求控制类型。 | +| value | number | 请求参数。 | +| index | number | 请求参数value对应的索引值。 | +| data | Uint8Array | 用于写入或读取的缓冲区。 | + +## USBPort9+ + +USB设备端口。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| -------------- | -------------------------------- | ----------------------------------- | +| id | number | USB端口唯一标识。 | +| supportedModes | [PortModeType](#portmodetype9) | USB端口所支持的模式的数字组合掩码。 | +| status | [USBPortStatus](#usbportstatus9) | USB端口角色。 | + +## USBPortStatus9+ + +USB设备端口角色信息。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------------- | -------- | ---------------------- | +| currentMode | number | 当前的USB模式。 | +| currentPowerRole | number | 当前设备充电模式。 | +| currentDataRole | number | 当前设备数据传输模式。 | + +## USBRequestTargetType + +请求目标类型。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ---------------------------- | ---- | ------ | +| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 | +| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 | +| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 | +| USB_REQUEST_TARGET_OTHER | 3 | 其他。 | + +## USBControlRequestType + +控制请求类型。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------------------------- | ---- | ------ | +| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 | +| USB_REQUEST_TYPE_CLASS | 1 | 类。 | +| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 | + +## USBRequestDirection + +请求方向。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| --------------------------- | ---- | ------------------------ | +| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | +| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | + +## FunctionType9+ + +USB设备侧功能。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------------ | ---- | ---------- | +| NONE | 0 | 没有功能。 | +| ACM | 1 | acm功能。 | +| ECM | 2 | ecm功能。 | +| HDC | 4 | hdc功能。 | +| MTP | 8 | 暂不支持。 | +| PTP | 16 | 暂不支持。 | +| RNDIS | 32 | 暂不支持。 | +| MIDI | 64 | 暂不支持。 | +| AUDIO_SOURCE | 128 | 暂不支持。 | +| NCM | 256 | 暂不支持。 | + +## PortModeType9+ + +USB端口模式类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| --------- | ---- | ---------------------------------------------------- | +| NONE | 0 | 无。 | +| UFP | 1 | 数据上行，需要外部供电。 | +| DFP | 2 | 数据下行，对外提供电源。 | +| DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 | +| NUM_MODES | 4 | 当前不支持。 | + +## PowerRoleType9+ + +电源角色类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------ | ---- | ---------- | +| NONE | 0 | 无。 | +| SOURCE | 1 | 外部供电。 | +| SINK | 2 | 内部供电。 | + +## DataRoleType9+ + +数据角色类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------ | ---- | ------------ | +| NONE | 0 | 无。 | +| HOST | 1 | 主设备角色。 | +| DEVICE | 2 | 从设备角色。 | + diff --git a/zh-cn/application-dev/reference/apis/js-apis-usb.md b/zh-cn/application-dev/reference/apis/js-apis-usb.md index 5e0aee35a77720f3510a1438876cc0f46ac9d200..ffa8e471f0e279279714c637cc16ecdd0f4a96f7 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-usb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-usb.md @@ -1,22 +1,22 @@ # USB管理 -本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。 +本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。 > **说明：** > -> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 ```js -import usb from "@ohos.usb"; +import usb from "@ohos.usbV9"; ``` ## usb.getDevices getDevices(): Array<Readonly<USBDevice>> -获取USB设备列表。 +获取接入主设备的USB设备列表。如果没有设备接入，那么将会返回一个空的列表。 **系统能力：** SystemCapability.USB.USBManager @@ -89,7 +89,7 @@ connectDevice(device: USBDevice): Readonly<USBDevicePipe> 打开USB设备。 -需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。 +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)请求使用该设备的权限。 **系统能力：** SystemCapability.USB.USBManager @@ -105,10 +105,26 @@ connectDevice(device: USBDevice): Readonly<USBDevicePipe> | -------- | -------- | | Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | +**错误码：** + +以下错误码的详细介绍参见[USB错误码](../errorcodes/errcode-usb.md)。 + +| 错误码ID | 错误信息 | +| -------- | -------- | +| 14400001 |Permission denied. Need call requestRight to get permission. | + **示例：** ```js -let devicepipe= usb.connectDevice(device); +let devicesList = usb.getDevices(); +if (devicesList.length == 0) { + console.log(`device list is empty`); + return; +} + +let device = devicesList[0]; +usb.requestRight(device.name); +let devicepipe = usb.connectDevice(device); console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); ``` @@ -169,6 +185,70 @@ usb.requestRight(devicesName).then((ret) => { }); ``` +## usb.removeRight + +removeRight(deviceName: string): boolean; + +移除软件包访问设备的权限。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | 返回权限移除结果。返回true表示权限移除成功；返回false则表示权限移除失败。 | + +**示例：** + +```js +let devicesName="1-1"; +if (usb.removeRight(devicesName) { + console.log(`Succeed in removing right`); +} +``` + +## usb.addRight + +addRight(bundleName: string, deviceName: string): boolean; + +添加软件包访问设备的权限。 + +[requestRight](#usbrequestright)的会触发弹框请求用户授权；addRight不会触发弹框，而是直接添加软件包访问设备的权限。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | +| bundleName | string | 是 | 软件包名称。| + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | 返回权限添加结果。返回true表示权限添加成功；返回false则表示权限添加失败。 | + +**示例：** + +```js +let devicesName = "1-1"; +let bundleName = "com.example.hello"; +if (usb.addRight(bundleName, devicesName) { + console.log(`Succeed in adding right`); +} +``` + ## usb.claimInterface claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number @@ -443,7 +523,7 @@ let ret = usb.closePipe(devicepipe); console.log(`closePipe = ${ret}`); ``` -## usb.usbFunctionsFromString9+ +## usb.usbFunctionsFromString usbFunctionsFromString(funcs: string): number @@ -472,7 +552,7 @@ let funcs = "acm"; let ret = usb.usbFunctionsFromString(funcs); ``` -## usb.usbFunctionsToString9+ +## usb.usbFunctionsToString usbFunctionsToString(funcs: FunctionType): string @@ -486,7 +566,7 @@ usbFunctionsToString(funcs: FunctionType): string | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------ | ---- | ----------------- | -| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | +| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | **返回值：** @@ -501,7 +581,7 @@ let funcs = ACM | ECM; let ret = usb.usbFunctionsToString(funcs); ``` -## usb.setCurrentFunctions9+ +## usb.setCurrentFunctions setCurrentFunctions(funcs: FunctionType): Promise\ @@ -515,7 +595,7 @@ setCurrentFunctions(funcs: FunctionType): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------ | ---- | ----------------- | -| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | +| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | **返回值：** @@ -530,7 +610,7 @@ let funcs = HDC; let ret = usb.setCurrentFunctions(funcs); ``` -## usb.getCurrentFunctions9+ +## usb.getCurrentFunctions getCurrentFunctions(): FunctionType @@ -544,7 +624,7 @@ getCurrentFunctions(): FunctionType | 类型 | 说明 | | ------------------------------ | --------------------------------- | -| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 | +| [FunctionType](#functiontype) | 当前的USB功能列表的数字组合掩码。 | **示例：** @@ -552,7 +632,7 @@ getCurrentFunctions(): FunctionType let ret = usb.getCurrentFunctions(); ``` -## usb.getPorts9+ +## usb.getPorts getPorts(): Array\ @@ -566,7 +646,7 @@ getPorts(): Array\ | 类型 | 说明 | | ----------------------------- | --------------------- | -| [Array\](#usbport9) | USB端口描述信息列表。 | +| [Array\](#usbport) | USB端口描述信息列表。 | **示例：** @@ -574,7 +654,7 @@ getPorts(): Array\ let ret = usb.getPorts(); ``` -## usb.getSupportedModes9+ +## usb.getSupportedModes getSupportedModes(portId: number): PortModeType @@ -594,7 +674,7 @@ getSupportedModes(portId: number): PortModeType | 类型 | 说明 | | ------------------------------ | -------------------------- | -| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 | +| [PortModeType](#portmodetype) | 支持的模式列表的组合掩码。 | **示例：** @@ -602,7 +682,7 @@ getSupportedModes(portId: number): PortModeType let ret = usb.getSupportedModes(0); ``` -## usb.setPortRoles9+ +## usb.setPortRoles setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\ @@ -617,8 +697,8 @@ setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): | 参数名 | 类型 | 必填 | 说明 | | --------- | -------------------------------- | ---- | ---------------- | | portId | number | 是 | 端口号。 | -| powerRole | [PowerRoleType](#powerroletype9) | 是 | 充电的角色。 | -| dataRole | [DataRoleType](#dataroletype9) | 是 | 数据传输的角色。 | +| powerRole | [PowerRoleType](#powerroletype) | 是 | 充电的角色。 | +| dataRole | [DataRoleType](#dataroletype) | 是 | 数据传输的角色。 | **返回值：** @@ -729,7 +809,7 @@ USB设备消息传输通道，用于确定设备。 | index | number | 请求参数value对应的索引值。 | | data | Uint8Array | 用于写入或读取的缓冲区。 | -## USBPort9+ +## USBPort USB设备端口。 @@ -740,10 +820,10 @@ USB设备端口。 | 名称 | 参数类型 | 说明 | | -------------- | -------------------------------- | ----------------------------------- | | id | number | USB端口唯一标识。 | -| supportedModes | [PortModeType](#portmodetype9) | USB端口所支持的模式的数字组合掩码。 | -| status | [USBPortStatus](#usbportstatus9) | USB端口角色。 | +| supportedModes | [PortModeType](#portmodetype) | USB端口所支持的模式的数字组合掩码。 | +| status | [USBPortStatus](#usbportstatus) | USB端口角色。 | -## USBPortStatus9+ +## USBPortStatus USB设备端口角色信息。 @@ -793,7 +873,7 @@ USB设备端口角色信息。 | USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | | USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | -## FunctionType9+ +## FunctionType USB设备侧功能。 @@ -814,7 +894,7 @@ USB设备侧功能。 | AUDIO_SOURCE | 128 | 暂不支持。 | | NCM | 256 | 暂不支持。 | -## PortModeType9+ +## PortModeType USB端口模式类型。 @@ -830,7 +910,7 @@ USB端口模式类型。 | DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 | | NUM_MODES | 4 | 当前不支持。 | -## PowerRoleType9+ +## PowerRoleType 电源角色类型。 @@ -844,7 +924,7 @@ USB端口模式类型。 | SOURCE | 1 | 外部供电。 | | SINK | 2 | 内部供电。 | -## DataRoleType9+ +## DataRoleType 数据角色类型。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-window.md b/zh-cn/application-dev/reference/apis/js-apis-window.md index 0d28afc2ae1bc5b80f25077a4b9fa2837df5ec9f..126504770692cb365ca69305bb4cf6896ad3481b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-window.md +++ b/zh-cn/application-dev/reference/apis/js-apis-window.md @@ -66,12 +66,12 @@ import window from '@ohos.window'; **系统能力：** SystemCapability.WindowManager.WindowManager.Core -| 名称 | 值 | 说明 | -|----------------------------------|-----| ----------------- | -| TYPE_SYSTEM | 0 | 表示系统默认区域。| -| TYPE_CUTOUT | 1 | 表示刘海屏区域。 | -| TYPE_SYSTEM_GESTURE9+ | 2 | 表示手势区域。 | -| TYPE_KEYBOARD9+ | 3 | 表示软键盘区域。 | +| 名称 | 值 | 说明 | +| -------------------------------- | ---- | ------------------------------------------------------------ | +| TYPE_SYSTEM | 0 | 表示系统默认区域。一般包括状态栏、导航栏和Dock栏，各设备系统定义可能不同。 | +| TYPE_CUTOUT | 1 | 表示刘海屏区域。 | +| TYPE_SYSTEM_GESTURE9+ | 2 | 表示手势区域。 | +| TYPE_KEYBOARD9+ | 3 | 表示软键盘区域。 | ## WindowMode7+ @@ -108,14 +108,14 @@ import window from '@ohos.window'; **系统能力：** SystemCapability.WindowManager.WindowManager.Core -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------------------------------------- | -------- | ---- | ---- | ------------------------------------------------------------ | -| statusBarColor | string | 否 | 是 | 状态栏背景颜色，为十六进制RGB或ARGB颜色，不区分大小写，例如`#00FF00`或`#FF00FF00`。 | -| isStatusBarLightIcon7+ | boolean | 否 | 是 | 状态栏图标是否为高亮状态。true表示高亮；false表示不高亮。 | -| statusBarContentColor8+ | string | 否 | 是 | 状态栏文字颜色。 | -| navigationBarColor | string | 否 | 是 | 导航栏背景颜色，为十六进制RGB或ARGB颜色，不区分大小写，例如`#00FF00`或`#FF00FF00`。 | -| isNavigationBarLightIcon7+ | boolean | 否 | 是 | 导航栏图标是否为高亮状态。true表示高亮；false表示不高亮。 | -| navigationBarContentColor8+ | string | 否 | 是 | 导航栏文字颜色。 | +| 名称 | 参数类型 | 可读 | 可写 | 必填 | 说明 | +| -------------------------------------- | -------- | ---- | ---- | ---- | ------------------------------------------------------------ | +| statusBarColor | string | 否 | 是 | 否 | 状态栏背景颜色，为十六进制RGB或ARGB颜色，不区分大小写，例如`#00FF00`或`#FF00FF00`。默认值：`#0x66000000`。 | +| isStatusBarLightIcon7+ | boolean | 否 | 是 | 否 | 状态栏图标是否为高亮状态。true表示高亮；false表示不高亮。默认值：false。 | +| statusBarContentColor8+ | string | 否 | 是 | 否 | 状态栏文字颜色。当设置此属性后， `isStatusBarLightIcon`属性设置无效。默认值：`0xE5FFFFFF。` | +| navigationBarColor | string | 否 | 是 | 否 | 导航栏背景颜色，为十六进制RGB或ARGB颜色，不区分大小写，例如`#00FF00`或`#FF00FF00`。默认值：`#0x66000000。` | +| isNavigationBarLightIcon7+ | boolean | 否 | 是 | 否 | 导航栏图标是否为高亮状态。true表示高亮；false表示不高亮。默认值：false。 | +| navigationBarContentColor8+ | string | 否 | 是 | 否 | 导航栏文字颜色。当设置此属性后， `isNavigationBarLightIcon`属性设置无效。默认值：`#0xE5FFFFFF。` | ## Orientation9+ @@ -2082,9 +2082,6 @@ setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: let SystemBarProperties={ statusBarColor: '#ff00ff', navigationBarColor: '#00ff00', - //以下两个属性从API Version7开始支持 - isStatusBarLightIcon: true, - isNavigationBarLightIcon:false, //以下两个属性从API Version8开始支持 statusBarContentColor:'#ffffff', navigationBarContentColor:'#00ffff' @@ -2137,9 +2134,6 @@ setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise& let SystemBarProperties={ statusBarColor: '#ff00ff', navigationBarColor: '#00ff00', - //以下两个属性从API Version7开始支持 - isStatusBarLightIcon: true, - isNavigationBarLightIcon:false, //以下两个属性从API Version8开始支持 statusBarContentColor:'#ffffff', navigationBarContentColor:'#00ffff' @@ -2339,7 +2333,7 @@ loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | 是 | 设置加载页面的路径。 | -| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | 是 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | +| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | 是 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** @@ -2390,7 +2384,7 @@ loadContent(path: string, storage: LocalStorage): Promise<void> | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | 是 | 设置加载页面的路径。 | -| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | 是 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | +| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | 是 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | **返回值：** @@ -4878,9 +4872,6 @@ setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: Async let SystemBarProperties={ statusBarColor: '#ff00ff', navigationBarColor: '#00ff00', - //以下两个属性从API Version7开始支持 - isStatusBarLightIcon: true, - isNavigationBarLightIcon:false, //以下两个属性从API Version8开始支持 statusBarContentColor:'#ffffff', navigationBarContentColor:'#00ffff' @@ -4924,9 +4915,6 @@ setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<voi let SystemBarProperties={ statusBarColor: '#ff00ff', navigationBarColor: '#00ff00', - //以下两个属性从API Version7开始支持 - isStatusBarLightIcon: true, - isNavigationBarLightIcon:false, //以下两个属性从API Version8开始支持 statusBarContentColor:'#ffffff', navigationBarContentColor:'#00ffff' @@ -6197,7 +6185,7 @@ loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | 是 | 设置加载页面的路径。 | -| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | 是 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | +| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | 是 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** @@ -6249,7 +6237,7 @@ loadContent(path: string, storage?: LocalStorage): Promise<void> | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | 是 | 设置加载页面的路径。 | -| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | 否 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | +| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | 否 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。 | **返回值：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md b/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md index a44870846919ed0e03521ea7a00ee1d41fdf7dec..bce80283f00a928ce65c96c45d783ee3717b608c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md +++ b/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md @@ -53,7 +53,7 @@ startWork(work: WorkInfo): boolean mykey3: 1.5 } } - var res = workScheduler.startWork(workInfo); + let res = workScheduler.startWork(workInfo); console.info(`workschedulerLog res: ${res}`); ``` @@ -94,7 +94,7 @@ stopWork(work: WorkInfo, needCancel?: boolean): boolean mykey3: 1.5 } } - var res = workScheduler.stopWork(workInfo, false); + let res = workScheduler.stopWork(workInfo, false); console.info(`workschedulerLog res: ${res}`); ``` diff --git a/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md b/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md index 5a93f3765cf30296e045b64f86f25ddf4b8fa4cc..f75b98a10733627de2d38e4ab22950deeff3d749 100644 --- a/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md +++ b/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md @@ -98,6 +98,7 @@ - [ColumnSplit](ts-container-columnsplit.md) - [Counter](ts-container-counter.md) - [Flex](ts-container-flex.md) + - [FlowItem](ts-container-flowitem.md) - [GridContainer](ts-container-gridcontainer.md) - [GridCol](ts-container-gridcol.md) - [GridRow](ts-container-gridrow.md) @@ -118,6 +119,7 @@ - [Swiper](ts-container-swiper.md) - [Tabs](ts-container-tabs.md) - [TabContent](ts-container-tabcontent.md) + - [WaterFlow](ts-container-waterflow.md) - 媒体组件 - [Video](ts-media-components-video.md) - 绘制组件 @@ -132,12 +134,12 @@ - 画布组件 - [Canvas](ts-components-canvas-canvas.md) - [CanvasRenderingContext2D对象](ts-canvasrenderingcontext2d.md) - - [OffscreenCanvasRenderingContext2D对象](ts-offscreencanvasrenderingcontext2d.md) - - [Lottie](ts-components-canvas-lottie.md) - - [Path2D对象](ts-components-canvas-path2d.md) - [CanvasGradient对象](ts-components-canvas-canvasgradient.md) - [ImageBitmap对象](ts-components-canvas-imagebitmap.md) - [ImageData对象](ts-components-canvas-imagedata.md) + - [OffscreenCanvasRenderingContext2D对象](ts-offscreencanvasrenderingcontext2d.md) + - [Path2D对象](ts-components-canvas-path2d.md) + - [Lottie](ts-components-canvas-lottie.md) - 动画 diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/grid-autofill.png b/zh-cn/application-dev/reference/arkui-ts/figures/grid-autofill.png deleted file mode 100644 index c45eee033be4548744fd84bbcb5ba29d17868e69..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/grid-autofill.png and /dev/null differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/waterflow.gif b/zh-cn/application-dev/reference/arkui-ts/figures/waterflow.gif new file mode 100644 index 0000000000000000000000000000000000000000..8c4010c17b302a8617508bbeb037a0dddf220882 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/waterflow.gif differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872492.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872492.png index 5d649492978121a484c2a7a55d4548384c919149..c564bb26b539f1e48acbdb7f2aeeca8df4e4e798 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872492.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872492.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872498.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872498.png index 801bf97495213f41c2b196b2f170af85b156dd5b..6c136313fe0c8774d1209a398d16ecc4b58c2bcd 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872498.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001193872498.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032458.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032458.png index 50726d3e461d7a5dbfec674899fee603aaf41bee..a07986a04b7477eec14c81d08e442d7b332dab83 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032458.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032458.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032462.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032462.png index d3db21e0e3da6d8663f59b2ddabd9e50d6eb1e6a..3d93b0a0a8f5d0b527d407e450a4a13a1de991ab 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032462.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032462.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032480.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032480.png index 5d649492978121a484c2a7a55d4548384c919149..5c0a336a56d0e5a186bd235cd25f9f5e5e7e644f 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032480.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032480.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032666.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032666.png new file mode 100644 index 0000000000000000000000000000000000000000..2b9bc96da366d53da784c92620a69f602f7bff14 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194032666.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192436.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192436.png index e3b4b42aecaef72ed4a08b3566a895b3f9b12343..27556ea43f7c2ecc65b9425e243ea593f02b08ec 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192436.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192436.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192440.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192440.png index 138e011909c2d4738f3cd9671a79ea0c37cb5b87..2a5c5649cc0716abc024aa3656924a456216a4c2 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192440.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194192440.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352436.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352436.png index 4fb651372a67eca9de3848baa6b66cac0ee9f173..00097d258d585ec8ad981703c5b265679e867133 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352436.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352436.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712471.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712471.png index 8c06945a1790bb0a741b330fe0a9170dd2a3a92d..81710c1186a0c0448d70a443db66c09a4e46d395 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712471.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712471.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238832389.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238832389.png index 2eed5759714b99dc039faab67acdfe6d67bfc6ac..5c75654b85d596a346fa5d793ca84991fe859a86 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238832389.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238832389.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238952377.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238952377.png index eb03ebe25132eb551b633d052cdfc984eda432ee..abc9a5667500a749dbceee88aef4caebf5d9df18 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238952377.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238952377.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777778.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777778.png new file mode 100644 index 0000000000000000000000000000000000000000..19e99b9ef490fff79e64e33192c97c1a39c6edf9 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777778.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777779.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777779.png new file mode 100644 index 0000000000000000000000000000000000000000..4558b332925757d97d70ee57182c260804629346 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777779.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777780.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777780.png new file mode 100644 index 0000000000000000000000000000000000000000..9b35e8e0fc4bb514584813b79e8889cfe65649a7 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777780.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777781.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777781.png new file mode 100644 index 0000000000000000000000000000000000000000..9e0a95f73b1aec44e6bccd6750a1c9f2815178ee Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777781.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md b/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md index a7d649f25f4546fcc44d145429b7a0f25f2ac07e..de1aaccb15c26e4ff9f7c225b22f4af295f3cfc2 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md @@ -1,12 +1,12 @@ # CanvasRenderingContext2D对象 +使用RenderingContext在Canvas组件上进行绘制，绘制对象可以是矩形、文本、图片等。 + > **说明：** > > 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -使用RenderingContext在Canvas组件上进行绘制，绘制对象可以是矩形、文本、图片等。 - ## 接口 @@ -723,6 +723,7 @@ strokeRect(x: number, y: number, w: number, h: number): void struct StrokeRect { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -766,6 +767,7 @@ clearRect(x: number, y: number, w: number, h: number): void struct ClearRect { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -774,8 +776,8 @@ clearRect(x: number, y: number, w: number, h: number): void .backgroundColor('#ffffff') .onReady(() =>{ this.context.fillStyle = 'rgb(0,0,255)' - this.context.fillRect(0,0,500,500) - this.context.clearRect(20,20,150,100) + this.context.fillRect(20,20,200,200) + this.context.clearRect(30,30,150,100) }) } .width('100%') @@ -811,6 +813,7 @@ fillText(text: string, x: number, y: number, maxWidth?: number): void struct FillText { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -855,6 +858,7 @@ strokeText(text: string, x: number, y: number, maxWidth?:number): void struct StrokeText { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -923,6 +927,7 @@ measureText(text: string): TextMetrics struct MeasureText { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -975,6 +980,8 @@ stroke(path?: Path2D): void .onReady(() =>{ this.context.moveTo(25, 25) this.context.lineTo(25, 105) + this.context.lineTo(75, 105) + this.context.lineTo(75, 25) this.context.strokeStyle = 'rgb(0,0,255)' this.context.stroke() }) @@ -1437,7 +1444,7 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number .backgroundColor('#ffff00') .onReady(() =>{ this.context.beginPath() - this.context.ellipse(200, 200, 50, 100, Math.PI * 0.25, Math.PI * 0.5, Math.PI) + this.context.ellipse(200, 200, 50, 100, Math.PI * 0.25, Math.PI * 0.5, Math.PI * 2) this.context.stroke() }) } @@ -1618,11 +1625,11 @@ clip(fillRule?: CanvasFillRule): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.context.rect(0, 0, 200, 200) + this.context.rect(0, 0, 100, 200) this.context.stroke() this.context.clip() this.context.fillStyle = "rgb(255,0,0)" - this.context.fillRect(0, 0, 150, 150) + this.context.fillRect(0, 0, 200, 200) }) } .width('100%') @@ -1636,7 +1643,7 @@ clip(fillRule?: CanvasFillRule): void clip(path: Path2D, fillRule?: CanvasFillRule): void -对封闭路径进行填充。该接口为空接口。 +设置当前路径为剪切路径 **参数:** @@ -1646,6 +1653,38 @@ clip(path: Path2D, fillRule?: CanvasFillRule): void | fillRule | CanvasFillRule | 否 | "nonzero" | 指定要剪切对象的规则。
可选参数为："nonzero", "evenodd"。 | +**示例:** + + ```ts + // xxx.ets +@Entry +@Component +struct Clip { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let region = new Path2D(); + region.rect(80,10,20,130); + region.rect(40,50,100,50); + this.context.clip(region,"evenodd") + this.context.fillStyle = "rgb(255,0,0)" + this.context.fillRect(0, 0, this.context.width, this.context.height) + }) + } + .width('100%') + .height('100%') + } +} + ``` + + ![zh-cn_image_000000127777779](figures/zh-cn_image_000000127777779.png) + ### filter @@ -1753,9 +1792,10 @@ scale(x: number, y: number): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.context.strokeRect(10, 10, 25, 25) + this.context.lineWidth = 3 + this.context.strokeRect(30, 30, 50, 50) this.context.scale(2, 2) // Scale to 200% - this.context.strokeRect(10, 10, 25, 25) + this.context.strokeRect(30, 30, 50, 50) }) } .width('100%') @@ -1985,7 +2025,7 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: createImageData(sw: number, sh: number): ImageData -创建新的ImageData 对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 +创建新的ImageData 对象，请参考[ImageData](ts-components-canvas-imagedata.md)。 **参数：** @@ -1995,23 +2035,21 @@ createImageData(sw: number, sh: number): ImageData | sh | number | 是 | 0 | ImageData的高度。 | -### createImageData - createImageData(imageData: ImageData): ImageData -创建新的ImageData 对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 +创建新的ImageData 对象，请参考[ImageData](ts-components-canvas-imagedata.md)。 **参数：** | 参数 | 类型 | 必填 | 默认 | 描述 | | --------- | ---------------------------------------- | ---- | ---- | ----------------- | -| imagedata | [ImageData](ts-components-canvas-imagebitmap.md) | 是 | null | 复制现有的ImageData对象。 | +| imagedata | [ImageData](ts-components-canvas-imagedata.md) | 是 | null | 复制现有的ImageData对象。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | -------------- | -| [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象。 | +| [ImageData](ts-components-canvas-imagedata.md) | 新的ImageData对象。 | ### getPixelMap @@ -2039,7 +2077,7 @@ getPixelMap(sx: number, sy: number, sw: number, sh: number): PixelMap getImageData(sx: number, sy: number, sw: number, sh: number): ImageData -以当前canvas指定区域内的像素创建[ImageData](ts-components-canvas-imagebitmap.md)对象。 +以当前canvas指定区域内的像素创建[ImageData](ts-components-canvas-imagedata.md)对象。 **参数：** @@ -2054,7 +2092,39 @@ getImageData(sx: number, sy: number, sw: number, sh: number): ImageData | 类型 | 说明 | | ---------------------------------------- | -------------- | -| [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象。 | +| [ImageData](ts-components-canvas-imagedata.md) | 新的ImageData对象。 | + + +**示例：** + + ```ts + // xxx.ets +@Entry +@Component +struct GetImageData { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context.drawImage(this.img,0,0,130,130); + var imagedata = this.context.getImageData(50,50,130,130); + this.context.putImageData(imagedata,150,150); + }) + } + .width('100%') + .height('100%') + } +} + ``` + + ![zh-cn_image_000000127777780](figures/zh-cn_image_000000127777780.png) ### putImageData @@ -2063,13 +2133,13 @@ putImageData(imageData: ImageData, dx: number, dy: number): void putImageData(imageData: ImageData, dx: number, dy: number, dirtyX: number, dirtyY: number, dirtyWidth: number, dirtyHeight: number): void -使用[ImageData](ts-components-canvas-imagebitmap.md)数据填充新的矩形区域。 +使用[ImageData](ts-components-canvas-imagedata.md)数据填充新的矩形区域。 **参数：** | 参数 | 类型 | 必填 | 默认值 | 描述 | | ----------- | ---------------------------------------- | ---- | ------------ | ----------------------------- | -| imagedata | [ImageData](ts-components-canvas-imagebitmap.md) | 是 | null | 包含像素值的ImageData对象。 | +| imagedata | [ImageData](ts-components-canvas-imagedata.md) | 是 | null | 包含像素值的ImageData对象。 | | dx | number | 是 | 0 | 填充区域在x轴方向的偏移量。 | | dy | number | 是 | 0 | 填充区域在y轴方向的偏移量。 | | dirtyX | number | 否 | 0 | 源图像数据矩形裁切范围左上角距离源图像左上角的x轴偏移量。 | @@ -2144,6 +2214,7 @@ setLineDash(segments: number[]): void .onReady(() =>{ this.context.arc(100, 75, 50, 0, 6.28) this.context.setLineDash([10,20]) + this.context.stroke() }) } .width('100%') @@ -2167,24 +2238,34 @@ getLineDash(): number[] | -------- | ------------------------ | | number[] | 返回数组，该数组用来描述线段如何交替和间距长度。 | + **示例：** ```ts // xxx.ets - @Entry - @Component - struct GetLineDash { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { +@Entry +@Component +struct CanvasGetLineDash { + @State message: string = 'Hello World' + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(()=>{ + console.error('before getlinedash clicked') + let res = this.context.getLineDash() + console.error(JSON.stringify(res)) + }) Canvas(this.context) .width('100%') .height('100%') .backgroundColor('#ffff00') - .onReady(() =>{ - var grad = this.context.createLinearGradient(50,0, 300,100) + .onReady(() => { this.context.arc(100, 75, 50, 0, 6.28) this.context.setLineDash([10,20]) this.context.stroke(); @@ -2192,10 +2273,13 @@ getLineDash(): number[] }) } .width('100%') - .height('100%') } + .height('100%') } +} ``` +![zh-cn_image_000000127777778](figures/zh-cn_image_000000127777778.png) + ### imageSmoothingQuality @@ -2222,7 +2306,7 @@ transferFromImageBitmap(bitmap: ImageBitmap): void | 参数 | 类型 | 描述 | | ------ | ---------------------------------------- | ------------------ | -| bitmap | [ImageData](ts-components-canvas-imagebitmap.md) | 待显示的ImageBitmap对象。 | +| bitmap | [ImageBitmap](ts-components-canvas-imagebitmap.md) | 待显示的ImageBitmap对象。 | **示例：** @@ -2230,7 +2314,7 @@ transferFromImageBitmap(bitmap: ImageBitmap): void // xxx.ets @Entry @Component - struct PutImageData { + struct TransferFromImageBitmap { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) @@ -2259,7 +2343,8 @@ transferFromImageBitmap(bitmap: ImageBitmap): void } } ``` - ![zh-cn_image_000000127777773](figures/zh-cn_image_000000127777773.png) + ![zh-cn_image_0000001238952387](figures/zh-cn_image_0000001238952387.png) + ### toDataURL @@ -2330,7 +2415,11 @@ restore(): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.context.restore() + this.context.save(); // save the default state + this.context.fillStyle = "green"; + this.context.fillRect(20, 20, 100, 100); + this.context.restore(); // restore to the default state + this.context.fillRect(150, 75, 100, 100); }) } .width('100%') @@ -2338,6 +2427,7 @@ restore(): void } } ``` + ![zh-cn_image_000000127777781](figures/zh-cn_image_000000127777781.png) ### save @@ -2363,14 +2453,19 @@ save(): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.context.save() - }) + this.context.save(); // save the default state + this.context.fillStyle = "green"; + this.context.fillRect(20, 20, 100, 100); + this.context.restore(); // restore to the default state + this.context.fillRect(150, 75, 100, 100); + }) } .width('100%') .height('100%') } } ``` + ![zh-cn_image_000000127777781](figures/zh-cn_image_000000127777781.png) ### createLinearGradient diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md index 1df79983e2e4560e438b22fe63e65952917e5fe8..d8d8bf52419bc243d81b7e3f47598560bc3851e0 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md @@ -1,9 +1,13 @@ # Canvas -> **说明：** 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 - 提供画布组件，用于自定义绘制图形。 +> **说明：** +> +> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 + + + ## 权限列表 无 @@ -18,9 +22,9 @@ Canvas(context?: CanvasRenderingContext2D) **参数：** - | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | - | ------- | ---------------------------------------- | ---- | ---- | ---------------------------- | - | context | [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md) | 否 | - | 见CanvasRenderingContext2D对象。 | +| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | +| ------- | ---------------------------------------- | ---- | ---- | ---------------------------- | +| context | [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md) | 否 | - | 见CanvasRenderingContext2D对象。 | ## 属性 @@ -34,7 +38,8 @@ Canvas(context?: CanvasRenderingContext2D) | ----------------------------- | ---- | -------------------- | | onReady(event: () => void) | 无 | Canvas组件初始化完成时的事件回调，该事件之后Canvas组件宽高确定且可获取，可使用Canvas相关API进行绘制。 | -## 示例 + +**示例：** ```ts // xxx.ets @@ -50,8 +55,8 @@ struct CanvasExample { .width('100%') .height('100%') .backgroundColor('#ffff00') - .onReady(() =>{ - this.context.fillRect(0,30,100,100) + .onReady(() => { + this.context.fillRect(0, 30, 100, 100) }) } .width('100%') @@ -59,3 +64,4 @@ struct CanvasExample { } } ``` + ![zh-cn_image_0000001194032666](figures/zh-cn_image_0000001194032666.png) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md index df4ed8fcbe5e254392cfaeb77d38167b2d9c1dd9..191b9ffab8e744a75626d610f1ade17d89d61025 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md @@ -1,11 +1,12 @@ # CanvasGradient对象 +渐变对象。 + > **说明：** +> > 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -渐变对象。 - ## addColorStop @@ -13,13 +14,16 @@ addColorStop(offset: number, color: string): void 设置渐变断点值，包括偏移和颜色。 -- 参数 + +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------ | ------ | ---- | --------- | ---------------------------- | | offset | number | 是 | 0 | 设置渐变点距离起点的位置占总体长度的比例，范围为0到1。 | | color | string | 是 | '#ffffff' | 设置渐变的颜色。 | -- 示例 + +**示例：** ```ts // xxx.ets @@ -48,10 +52,6 @@ addColorStop(offset: number, color: string): void .height('100%') }} ``` - - - - ![zh-cn_image_0000001194032516](figures/zh-cn_image_0000001194032516.png) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md index e2f3f510bef985abf5c868223bf71f477219ea80..12063d494b68b2c694ec35090730d4625a81e620 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md @@ -1,11 +1,12 @@ # ImageBitmap对象 +ImageBitmap对象可以存储canvas渲染的像素数据。 + > **说明：** +> > 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -ImageBitmap对象可以存储canvas渲染的像素数据。 - ## 属性 @@ -14,6 +15,36 @@ ImageBitmap对象可以存储canvas渲染的像素数据。 | width | number | ImageBitmap的像素宽度。 | | height | number | ImageBitmap的像素高度。 | +**示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct ImageExample { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private img:ImageBitmap = new ImageBitmap("common/images/example.jpg"); + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context.drawImage( this.img,0,0,500,500,0,0,400,200); + }) + } + .width('100%') + .height('100%') + } + } + ``` + + ![zh-cn_image_0000001194352442](figures/zh-cn_image_0000001194352442.png) + + ## 方法 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md index d1df7c7a5ec2294b75c43ee390e0cfb3ccfad0ff..00ca2d47e15d1efc2e71777f11fef69a70e1eeb7 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md @@ -1,11 +1,12 @@ # ImageData对象 +ImageData对象可以存储canvas渲染的像素数据。 + > **说明：** +> > 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -ImageData对象可以存储canvas渲染的像素数据。 - ## 属性 @@ -15,3 +16,34 @@ ImageData对象可以存储canvas渲染的像素数据。 | height | number | 矩形区域实际像素高度。 | | data | Uint8ClampedArray | 一维数组，保存了相应的颜色数据，数据值范围为0到255。 | +**示例：** + + ```ts + // xxx.ets +@Entry +@Component +struct Translate { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context.drawImage(this.img,0,0,130,130); + var imagedata = this.context.getImageData(50,50,130,130); + this.context.putImageData(imagedata,150,150); + }) + } + .width('100%') + .height('100%') + } +} + ``` + + ![zh-cn_image_000000127777780](figures/zh-cn_image_000000127777780.png) + diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md index 7db2042a6b73a48a5b80283dc533a83a9d3f20b9..c7e75844c0510121776eff37d1688f11ee83f6aa 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md @@ -3,13 +3,10 @@ 提供Lottie动画。 > **说明：** +> > 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - ## 导入模块 @@ -32,7 +29,8 @@ path: string, container: object, render: string, loop: boolean, autoplay: boolea 加载动画，须提前声明Animator('__lottie_ets')对象，并在Canvas完成布局后调用。可配合Canvas组件生命周期接口使用，比如onAppear()与onPageShow()。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | -------------- | --------------------------- | ---- | ---------------------------------------- | | path | string | 是 | hap包内动画资源文件路径，仅支持json格式。示例：path: "common/lottie/data.json" | @@ -50,12 +48,13 @@ destroy(name: string): void 销毁动画，页面退出时，必须调用。可配合Canvas组件生命周期接口使用，比如onDisappear()与onPageHide()。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 被指定的动画名，同loadAnimation接口参数name, 缺省时销毁所有动画。 | -- 示例 +**示例：** ```ts // xxx.ets import lottie from '@ohos/lottieETS' @@ -130,12 +129,14 @@ play(name: string): void 播放指定动画。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 被指定的动画名, 同loadAnimation接口参数name，缺省时播放所有动画。 | -- 示例 +**示例：** + ```ts lottie.play(this.animateName) ``` @@ -147,12 +148,14 @@ pause(name: string): void 暂停指定动画，下次调用lottie.play()从当前帧开始。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 被指定的动画名，同loadAnimation接口入参name，缺省时暂停所有动画。 | -- 示例 +**示例：** + ```ts lottie.pause(this.animateName) ``` @@ -164,12 +167,14 @@ togglePause(name: string): void 暂停或播放指定动画，等效于lottie.play()与lottie.pause()切换调用。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 被指定的动画名，同loadAnimation接口参数name，缺省时停止所有动画。 | -- 示例 +**示例：** + ```ts lottie.togglePause(this.animateName) ``` @@ -181,12 +186,14 @@ stop(name: string): void 停止指定动画，下次调用lottie.play()从第一帧开始。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | ---------------------------------------- | | name | string | 是 | 被指定的动画名，同loadAnimation接口参数name，缺省时停止所有动画。 | -- 示例 +**示例：** + ```ts lottie.stop(this.animateName) ``` @@ -198,13 +205,15 @@ setSpeed(speed: number, name: string): void 设置指定动画播放速度。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ----- | ------ | ---- | ---------------------------------------- | | speed | number | 是 | 值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0/-1.0正常速度播放。 | | name | string | 是 | 被指定的动画，同loadAnimation接口参数name，缺省时停止所有动画。 | -- 示例 +**示例：** + ```ts lottie.setSpeed(5, this.animateName) ``` @@ -216,13 +225,15 @@ setDirection(direction: AnimationDirection, name: string): void 设置指定动画播放顺序。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | --------- | ------------------ | ---- | ---------------------------------------- | | direction | AnimationDirection | 是 | 1为正向，-1为反向; 当设置为反向时，从当前播放进度开始回播直到首帧，loop值为true时可无限倒放；speed<0叠加时也是倒放。
AnimationDirection：1 \| -1 | | name | string | 是 | 被指定的动画名，同loadAnimation接口参数name，缺省时设置所有动画方向。 | -- 示例 +**示例：** + ```ts lottie.setDirection(-1, this.animateName) ``` @@ -262,12 +273,14 @@ play(name?: string): void 播放动画。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | --------------- | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts this.animateItem.play() ``` @@ -279,12 +292,14 @@ destroy(name?: string): void 销毁动画。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | --------------- | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts this.animateItem.destroy() ``` @@ -296,12 +311,14 @@ pause(name?: string): void 暂停动画，下次调用play接口从当前帧开始播放。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | --------------- | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts this.animateItem.pause() ``` @@ -313,12 +330,14 @@ togglePause(name?: string): void 暂停或播放动画，等效于play接口与pause接口之间轮换调用。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | --------------- | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts this.animateItem.togglePause() ``` @@ -330,12 +349,14 @@ stop(name?: string): void 停止动画，下次调用play接口从第一帧开始播放。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------ | ---- | --------------- | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts this.animateItem.stop() ``` @@ -347,12 +368,14 @@ setSpeed(speed: number): void 设置动画播放速度。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ----- | ------ | ---- | ---------------------------------------- | | speed | number | 是 | 值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0 \| -1.0正常速度播放。 | -- 示例 +**示例：** + ```ts this.animateItem.setSpeed(5); ``` @@ -364,12 +387,14 @@ setDirection(direction: AnimationDirection): void 设置动画播放顺序。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | --------- | ------------------ | ---- | ---------------------------------------- | | direction | AnimationDirection | 是 | 1为正向，-1为反向; 当设置为反向时，从当前播放进度开始回播直到首帧，loop值为true时可无限倒放；speed<0叠加时也是倒放。
AnimationDirection：1 \| -1。 | -- 示例 +**示例：** + ```ts this.animateItem.setDirection(-1) ``` @@ -381,14 +406,16 @@ goToAndStop(value: number, isFrame?: boolean): void 设置动画停止在指定帧或时间进度。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ------- | ------- | ---- | ---------------------------------------- | | value | number | 是 | 帧号(值大于等于0)或时间进度(ms)。 | | isFrame | boolean | 否 | true: 按指定帧控制，false:按指定时间控制，缺省默认false。 | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts // 按帧号控制 this.animateItem.goToAndStop(25, true) @@ -403,14 +430,16 @@ goToAndPlay(value: number, isFrame: boolean, name?: string): void 设置动画从指定帧或时间进度开始播放。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ------- | ------- | ---- | ---------------------------------------- | | value | number | 是 | 帧号(值大于等于0)或时间进度(ms) | | isFrame | boolean | 是 | true：按指定帧控制， false：按指定时间控制，缺省默认false。 | | name | string | 否 | 被指定的动画名，缺省默认为空。 | -- 示例 +**示例：** + ```ts // 按帧号控制 this.animateItem.goToAndPlay(25, true) @@ -425,13 +454,15 @@ playSegments(segments: AnimationSegment | AnimationSegment[], forceFlag: boolean 设置动画仅播放指定片段。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | --------- | ---------------------------------------- | ---- | ---------------------------------------- | | segments | AnimationSegment = [number, number] \| AnimationSegment[] | 是 | 片段或片段列表；
如果片段列表全部播放完毕后，下轮循环播放仅播放最后一个片段 | | forceFlag | boolean | 是 | true：即时生效播放，false：延迟到下轮循环播放再生效 | -- 示例 +**示例：** + ```ts // 指定播放片段 this.animateItem.playSegments([10, 20], false) @@ -446,12 +477,14 @@ resetSegments(forceFlag: boolean): void 重置动画播放片段，播放全帧。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | --------- | ------- | ---- | ------------------------------ | | forceFlag | boolean | 是 | true：即时生效播放，false：延迟到下轮循环播放再生效 | -- 示例 +**示例：** + ```ts this.animateItem.resetSegments(true) ``` @@ -463,7 +496,8 @@ resize(): void 刷新动画布局。 -- 示例 +**示例：** + ```ts this.animateItem.resize() ``` @@ -475,12 +509,14 @@ setSubframe(useSubFrame: boolean): void 设置属性currentFrame的精度显示浮点数。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ------------ | ------- | ---- | ---------------------------------------- | | useSubFrames | boolean | 是 | currentFrame属性默认显示浮点数，该接口参数将影响currentFrame属性的精度。
true：属性currentFrame显示浮点。
false：属性currentFrame去浮点数显示整数。 | -- 示例 +**示例：** + ```ts this.animateItem.setSubframe(false) ``` @@ -492,12 +528,14 @@ getDuration(inFrames?: boolean): void 获取动画单次完整播放的时间(与播放速度无关)或帧数, 与Lottie.loadAnimation接口入参initialSegment有关。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | -------- | ------- | ---- | ---------------------------------------- | | inFrames | boolean | 否 | true：获取帧数， false：获取时间(单位ms)，缺省默认false。 | -- 示例 +**示例：** + ```ts this.animateItem.getDuration(true) ``` @@ -509,13 +547,15 @@ addEventListener<T = any>(name: AnimationEventName, callback: AnimationEve 添加侦听事件, 事件完成后会触发指定回调函数。返回可删除该侦听事件的函数对象。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | -------- | ------------------------------- | ---- | ---------------------------------------- | | name | AnimationEventName | 是 | 指定动画事件类型，Lottie内置动画事件类型AnimationEventName：
'enterFrame'、'loopComplete'、'complete'、'segmentStart'、'destroy'、'config_ready'、'data_ready'、'DOMLoaded'、'error'、'data_failed'、'loaded_images' | | callback | AnimationEventCallback<T> | 是 | 用户自定义回调函数 | -- 示例 +**示例：** + ```ts private callbackItem: any = function() { console.log("grunt loopComplete") @@ -533,13 +573,15 @@ removeEventListener<T = any>(name: AnimationEventName, callback?: Animatio 删除侦听事件。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | -------- | ------------------------------- | ---- | ---------------------------------------- | | name | AnimationEventName | 是 | 指定动画事件类型，Lottie内置动画事件类型AnimationEventName：
'enterFrame'、'loopComplete'、'complete'、'segmentStart'、'destroy'、'config_ready'、'data_ready'、'DOMLoaded'、'error'、'data_failed'、'loaded_images' | | callback | AnimationEventCallback<T> | 否 | 用户自定义回调函数；缺省为空时，删除此事件的所有回调函数。 | -- 示例 +**示例：** + ```ts this.animateItem.removeEventListener('loopComplete', this.animateName) ``` @@ -551,13 +593,15 @@ triggerEvent<T = any>(name: AnimationEventName, args: T): void 直接触发指定事件的所有已设置的回调函数。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 描述 | | ---- | ------------------ | ---- | --------- | | name | AnimationEventName | 是 | 指定动画事件类型 | | args | any | 是 | 用户自定义回调参数 | -- 示例 +**示例：** + ```ts private triggerCallBack: any = function(item) { console.log("trigger loopComplete, name:" + item.name) diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md index 63004c2e78848e356e474a5ee4b38d13f6162c66..b37d56db73e7684aac0cb0c40b206f1d910d3bd6 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md @@ -1,11 +1,12 @@ # Path2D对象 +路径对象，支持通过对象的接口进行路径的描述，并通过Canvas的stroke接口进行绘制。 + > **说明：** +> > 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -路径对象，支持通过对象的接口进行路径的描述，并通过Canvas的stroke接口进行绘制。 - ## addPath @@ -225,7 +226,8 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, .backgroundColor('#ffff00') .onReady(() =>{ this.path2Db.moveTo(10, 10) - this.path2Db.bezierCurveTo(20, 100, 200, 100, 200, 20);this.context.stroke(this.path2Db) + this.path2Db.bezierCurveTo(20, 100, 200, 100, 200, 20) + this.context.stroke(this.path2Db) }) } .width('100%') @@ -319,7 +321,8 @@ arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.path2Db.arc(100, 75, 50, 0, 6.28);this.context.stroke(this.path2Db) + this.path2Db.arc(100, 75, 50, 0, 6.28) + this.context.stroke(this.path2Db) }) } .width('100%') @@ -407,7 +410,7 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -415,7 +418,7 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.path2Db.ellipse(200, 200, 50, 100, Math.PI * 0.25, Math.PI * 0.5, Math.PI) + this.path2Db.ellipse(200, 200, 50, 100, 0, Math.PI * 1, Math.PI*2) this.context.stroke(this.path2Db) }) } @@ -461,7 +464,8 @@ rect(x: number, y: number, w: number, h: number): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.path2Db.rect(20, 20, 100, 100);this.context.stroke(this.path2Db) + this.path2Db.rect(20, 20, 100, 100); + this.context.stroke(this.path2Db) }) } .width('100%') diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md index 39484c97aeb6e66ec401a9a7efcaf56a1a886220..9d90b27886e63a7126717f3672fa77effbfe7e01 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md @@ -20,8 +20,8 @@ AlphabetIndexer(value: {arrayValue: Array<string>, selected: number}) | 参数名 | 参数类型 | 必填 | 参数描述 | | -------- | -------- | -------- | -------- | -| arrayValue | Array<string> | 是 | 字母索引字符串数组。 | -| selected | number | 是 | 初始选中项索引值。 | +| arrayValue | Array<string> | 是 | 字母索引字符串数组，不可设置为空。 | +| selected | number | 是 | 初始选中项索引值，若超出索引值范围，则取默认值0。 | ## 属性 @@ -29,19 +29,19 @@ AlphabetIndexer(value: {arrayValue: Array<string>, selected: number}) | 名称 | 参数类型 | 描述 | | ----------------------- | --------------- | ----------------------------------------------------------- | -| color | [ResourceColor](ts-types.md#resourcecolor) | 设置文字颜色。 | -| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项文字颜色。 | -| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗文字颜色。 | -| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项背景颜色。 | -| popupBackground | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗背景色。 | -| usingPopup | boolean | 设置是否使用提示弹窗。 | -| selectedFont | [Font](ts-types.md#font) | 设置选中项文字样式。 | -| popupFont | [Font](ts-types.md#font) | 设置提示弹窗字体样式。 | -| font | [Font](ts-types.md#font) | 设置字母索引条默认字体样式。 | -| itemSize | string \| number | 设置字母索引条字母区域大小，字母区域为正方形，即正方形边长。 | -| alignStyle | IndexerAlign | 设置字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。
默认值：IndexerAlign.Right | -| selected | number | 设置选中项索引值。 | -| popupPosition | [Position](ts-types.md#position8) | 设置弹出窗口相对于索引器条上边框中点的位置。 | +| color | [ResourceColor](ts-types.md#resourcecolor) | 设置文字颜色。
默认值：0x99000000。 | +| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项文字颜色。
默认值：0xFF254FF7。 | +| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗文字颜色。
默认值：0xFF254FF7。 | +| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项背景颜色。
默认值：0x1F0A59F7。 | +| popupBackground | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗背景色。
默认值：0xFFF1F3F5。 | +| usingPopup | boolean | 设置是否使用提示弹窗。
默认值：false。 | +| selectedFont | [Font](ts-types.md#font) | 设置选中项文字样式。
默认值：
{
fontSize:10,
fontStyle:FontStyle.Normal,
fontWeight:FontWeight.Normal,
fontFamily:HarmonyOS Sans
} | +| popupFont | [Font](ts-types.md#font) | 设置提示弹窗字体样式。
默认值：
{
fontSize:10,
fontStyle:FontStyle.Normal,
fontWeight:FontWeight.Normal,
fontFamily:HarmonyOS Sans
} | +| font | [Font](ts-types.md#font) | 设置字母索引条默认字体样式。
默认值：
{
fontSize:10,
fontStyle:FontStyle.Normal,
fontWeight:FontWeight.Normal,
fontFamily:HarmonyOS Sans
} | +| itemSize | string \| number | 设置字母索引条字母区域大小，字母区域为正方形，即正方形边长。
默认值：24.0。 | +| alignStyle | IndexerAlign | 设置字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。
默认值:IndexerAlign.Right。 | +| selected | number | 设置选中项索引值。
默认值：0。 | +| popupPosition | [Position](ts-types.md#position8) | 设置弹出窗口相对于索引器条上边框中点的位置。
默认值：{x:96.0, y:48.0}。 | ## IndexerAlign枚举说明 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md new file mode 100644 index 0000000000000000000000000000000000000000..2c2ed70cdd5e019db511e5235305e5fd2b91b67d --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md @@ -0,0 +1,31 @@ +# FlowItem + + +[瀑布流组件](ts-container-waterflow.md)的子组件，用来展示瀑布流具体item。 + + +> **说明：** +> +> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 + + +## 子组件 + + +支持单个子组件。 + + +## 接口 + +FlowItem() + +使用该接口来创建瀑布流子组件。 + + +## 属性 + +无 + +## 示例 + +详见[瀑布流组件示例](ts-container-waterflow.md#示例)。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-grid.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-grid.md index d129eb383470472e841cc263483bc136ee63c31e..0f6a52a9b060be178339cc7c8002606484bccd23 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-grid.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-grid.md @@ -27,8 +27,8 @@ Grid(scroller?: Scroller) | 名称 | 参数类型 | 描述 | | -------- | -------- | -------- | -| columnsTemplate | string | 设置当前网格布局列的数量，不设置时默认1列。
例如, '1fr 1fr 2fr' 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。并支持[auto-fill](#auto-fill说明)。
默认值：'1fr' | -| rowsTemplate | string | 设置当前网格布局行的数量，不设置时默认1行。
例如, '1fr 1fr 2fr'是将父组件分三行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。并支持[auto-fill](#auto-fill说明)。
默认值：'1fr' | +| columnsTemplate | string | 设置当前网格布局列的数量，不设置时默认1列。
例如, '1fr 1fr 2fr' 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。
默认值：'1fr' | +| rowsTemplate | string | 设置当前网格布局行的数量，不设置时默认1行。
例如, '1fr 1fr 2fr'是将父组件分三行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。
默认值：'1fr' | | columnsGap | Length | 设置列与列的间距。
默认值：0 | | rowsGap | Length | 设置行与行的间距。
默认值：0 | | scrollBar | [BarState](ts-appendix-enums.md#barstate) | 设置滚动条状态。
默认值：BarState.Off | @@ -65,16 +65,6 @@ Grid(scroller?: Scroller) | onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | 拖拽离开网格元素时触发。
- event: 见[ItemDragInfo对象说明](#itemdraginfo对象说明)。
- itemIndex: 拖拽离开的网格元素索引值。 | | onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | 绑定该事件的网格元素可作为拖拽释放目标，当在网格元素内停止拖拽时触发。
- event: 见[ItemDragInfo对象说明](#itemdraginfo对象说明)。
- itemIndex: 拖拽起始位置。
- insertIndex: 拖拽插入位置。
- isSuccess: 是否成功释放。 | -## auto-fill说明 - -Grid的columnsTemplate、rowsTemplate属性的auto-fill仅支持以下格式： - -```css -repeat(auto-fill, track-size) -``` - -其中repeat、auto-fill为关键字。track-size为行高或者列宽，支持的单位包括px、vp、%或有效数字，track-size至少包括一个有效行高或者列宽。 - ## ItemDragInfo对象说明 | 名称 | 类型 | 描述 | @@ -144,51 +134,4 @@ struct GridExample { } ``` -![zh-cn_image_0000001219744183](figures/zh-cn_image_0000001219744183.gif) - -**auto-fill示例** - -```ts -// grid-autofill.ets -@Entry -@Component -struct Index { - @State gridItemWidth: string = "100%" - @State gridItemHeight: string = "100%" - @State gridWidth: string = "100%" - @State gridHeight: string = "100%" - @State itemList: string[] = [] - build() { - Column() { - Grid() { - ForEach(this.itemList, (item) => { - GridItem() { - Text(item.toString()) - .fontSize(16) - .width('100%') - .textAlign(TextAlign.Center) - } - .width(this.gridItemWidth) - .height(this.gridItemHeight) - .backgroundColor(0xF9CF93) - }, item => item) - } - .columnsGap(1) - .rowsGap(1) - .border({ width: 4, color: 0xffdb7093, style: BorderStyle.Dashed, radius: 5 }) - .width(this.gridWidth) - .height(this.gridHeight) - .columnsTemplate("15% repeat(auto-fill, 10% 50px 20%) 50px") - .rowsTemplate("150px repeat(auto-fill, 20% 25%)") - }.margin(5) - } - - aboutToAppear() { - for(var i = 1; i < 50; i++) { - this.itemList.push(i.toString()) - } - } -} -``` - -![grid-autofill](figures/grid-autofill.png) \ No newline at end of file +![zh-cn_image_0000001219744183](figures/zh-cn_image_0000001219744183.gif) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md new file mode 100644 index 0000000000000000000000000000000000000000..4ca95460bcf93cc1c07c5ea44f8de0f412d43f86 --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md @@ -0,0 +1,264 @@ +# WaterFlow + + +瀑布流容器，由“行”和“列”分割的单元格所组成，通过容器自身的排列规则，将不同大小的“项目”自上而下，如瀑布般紧密布局。 + + +> **说明：** +> +> 该组件从API Version 9 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 + + +## 子组件 + + +包含[FlowItem](ts-container-flowitem.md)子组件。 + + +## 接口 + + +WaterFlow(options?: {footer?: CustomBuilder, scroller?: Scroller}) + +**参数：** + + | 参数名 | 参数类型 | 必填 | 参数描述 | + | ---------- | ----------------------------------------------- | ------ | -------------------------------------------- | + | footer | [CustomBuilder](ts-types.md#custombuilder8) | 否 | 设置WaterFlow尾部组件。 | + | scroller | [Scroller](ts-container-scroll.md#scroller) | 否 | 可滚动组件的控制器，与可滚动组件绑定。 | + + +## 属性 + + +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 名称 | 参数类型 | 描述 | +| -------- | -------- | -------- | +| columnsTemplate | string | 设置当前瀑布流组件布局列的数量，不设置时默认1列。
例如, '1fr 1fr 2fr' 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。并支持[auto-fill](#auto-fill说明)。
默认值：'1fr' | +| rowsTemplate | string | 设置当前瀑布流组件布局行的数量，不设置时默认1行。
例如, '1fr 1fr 2fr'是将父组件分三行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。并支持[auto-fill](#auto-fill说明)。
默认值：'1fr' | +| itemConstraintSize | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 设置约束尺寸，子组件布局时，进行尺寸范围限制。 | +| columnsGap | Length |设置列与列的间距。
默认值：0| +| rowsGap | Length |设置行与行的间距。
默认值：0| +| layoutDirection | [FlexDirection](ts-appendix-enums.md#flexdirection) |设置布局的主轴方向。| + + +## 事件 + + +除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： + + +| 名称 | 功能描述 | +| -------- | -------- | +| onReachStart(event: () => void) | 瀑布流组件到达起始位置时触发。 | +| onReachEnd(event: () => void) | 瀑布流组件到底末尾位置时触发。 | + + +## auto-fill说明 + +WaterFlow的columnsTemplate、rowsTemplate属性的auto-fill仅支持以下格式： + +```css +repeat(auto-fill, track-size) +``` + +其中repeat、auto-fill为关键字。track-size为行高或者列宽，支持的单位包括px、vp、%或有效数字，track-size至少包括一个有效行高或者列宽。 + + +## 示例 + + +```ts +// WaterFlowDataSource.ets + +// 实现IDataSource接口的对象，用于瀑布流组件加载数据 +export class WaterFlowDataSource implements IDataSource { + + private dataArray: number[] = [] + private listeners: DataChangeListener[] = [] + + constructor() { + for (let i = 0; i <= 100; i++) { + this.dataArray.push(i); + } + } + + // 获取索引对应的数据 + public getData(index: number): any { + return this.dataArray[index] + } + + // 通知控制器数据重新加载 + notifyDataReload(): void { + this.listeners.forEach(listener => { + listener.onDataReloaded() + }) + } + + // 通知控制器数据增加 + notifyDataAdd(index: number): void { + this.listeners.forEach(listener => { + listener.onDataAdded(index) + }) + } + + // 通知控制器数据变化 + notifyDataChange(index: number): void { + this.listeners.forEach(listener => { + listener.onDataChanged(index) + }) + } + + // 通知控制器数据删除 + notifyDataDelete(index: number): void { + this.listeners.forEach(listener => { + listener.onDataDeleted(index) + }) + } + + // 通知控制器数据位置变化 + notifyDataMove(from: number, to: number): void { + this.listeners.forEach(listener => { + listener.onDataMoved(from, to) + }) + } + + // 获取数据总数 + public totalCount(): number { + return this.dataArray.length + } + + // 注册改变数据的控制器 + registerDataChangeListener(listener: DataChangeListener): void { + if (this.listeners.indexOf(listener) < 0) { + this.listeners.push(listener) + } + } + + // 注销改变数据的控制器 + unregisterDataChangeListener(listener: DataChangeListener): void { + const pos = this.listeners.indexOf(listener); + if (pos >= 0) { + this.listeners.splice(pos, 1) + } + } + + // 增加数据 + public Add1stItem(): void { + this.dataArray.splice(0, 0, this.dataArray.length) + this.notifyDataAdd(0) + } + + // 在数据尾部增加一个元素 + public AddLastItem(): void { + this.dataArray.splice(this.dataArray.length, 0, this.dataArray.length) + this.notifyDataAdd(this.dataArray.length-1) + } + + // 在指定索引位置增加一个元素 + public AddItem(index: number): void { + this.dataArray.splice(index, 0, this.dataArray.length) + this.notifyDataAdd(index) + } + + // 删除第一个元素 + public Delete1stItem(): void { + this.dataArray.splice(0, 1) + this.notifyDataDelete(0) + } + + // 删除第二个元素 + public Delete2ndItem(): void { + this.dataArray.splice(1, 1) + this.notifyDataDelete(1) + } + + // 删除最后一个元素 + public DeleteLastItem(): void { + this.dataArray.splice(-1, 1) + this.notifyDataDelete(this.dataArray.length) + } + + // 重新加载数据 + public Reload(): void { + this.dataArray.splice(1, 1); + this.dataArray.splice(3, 2); + this.notifyDataReload(); + } +} +``` + +```ts +// WaterflowDemo.ets +import { WaterFlowDataSource } from './WaterFlowDataSource' + +@Entry +@Component +struct WaterflowDemo { + @State minSize: number = 50 + @State maxSize: number = 100 + @State fontSize: number = 24 + @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F] + scroller: Scroller = new Scroller(); + datasource: WaterFlowDataSource = new WaterFlowDataSource(); + + // 计算flow item宽/高 + getSize() { + let ret = Math.floor(Math.random() * this.maxSize) + return (ret > this.minSize ? ret : this.minSize) + } + + @Builder itemFoot() { + Column() { + Text(`Footer`) + .fontSize(10) + .backgroundColor(Color.Red) + .width(50) + .height(50) + .align(Alignment.Center) + .margin({ top: 2 }) + } + } + + build() { + Column({ space: 2 }) { + WaterFlow({ footer: this.itemFoot, scroller: this.scroller }) { + LazyForEach(this.datasource, (item: number) => { + FlowItem() { + Column() { + Text("N" + item).fontSize(12).height('16') + Image('res/waterFlowTest(' + item % 5 + ').jpg') + .objectFit(ImageFit.Fill) + } + } + .width(this.getSize()) + .height(this.getSize()) + .backgroundColor(this.colors[item % 5]) + }, item => item) + } + .columnsTemplate("1fr 1fr 1fr 1fr") + .itemConstraintSize({ + minWidth: 0, + maxWidth: '100%', + minHeight: 0, + maxHeight: '100%' + }) + .columnsGap(10) + .rowsGap(5) + .onReachStart(() => { + console.info("onReachStart") + }) + .onReachEnd(() => { + console.info("onReachEnd") + }) + .backgroundColor(0xFAEEE0) + .width('100%') + .height('80%') + .layoutDirection(FlexDirection.Column) + } + } +} +``` + +![zh-cn_image_WaterFlow.gif](figures/waterflow.gif) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md index 709e897f90d1940b5388b18c148592a0e1f74361..c6634faf732e678e7609827cb81606410f185645 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md @@ -21,11 +21,10 @@ Shape(value?: PixelMap) -**参数：** - -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| -------- | -------- | -------- | -------- | -------- | -| value | PixelMap | 否 | - | 绘制目标，可将图形绘制在指定的PixelMap对象中，若未设置，则在当前绘制目标中进行绘制。 | +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | value | [PixelMap](../apis/js-apis-image.md#pixelmap7) | 否 | - | 绘制目标，可将图形绘制在指定的PixelMap对象中，若未设置，则在当前绘制目标中进行绘制。 | ## 属性 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md b/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md index 9a0caa9f125ab28009166ecebd0cf9d7dccc8eea..b84eef2a7be0bd0d10328d952c856d1b9dc35774 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md @@ -1,11 +1,12 @@ # OffscreenCanvasRenderingContext2D对象 +使用OffscreenCanvasRenderingContext2D在Canvas上进行离屏绘制，绘制对象可以是矩形、文本、图片等。离屏绘制是指将需要绘制的内容先绘制在缓存区，然后将其转换成图片，一次性绘制到canvas上，加快了绘制速度。 + > **说明：** +> > 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -使用OffscreenCanvasRenderingContext2D在Canvas上进行离屏绘制，绘制对象可以是矩形、文本、图片等。离屏绘制是指将需要绘制的内容先绘制在缓存区，然后将其转换成图片，一次性绘制到canvas上，加快了绘制速度。 - ## 接口 @@ -41,7 +42,6 @@ OffscreenCanvasRenderingContext2D(width: number, height: number, setting: Render | [shadowOffsetX](#shadowoffsetx) | number | 设置绘制阴影时和原有对象的水平偏移值。 | | [shadowOffsetY](#shadowoffsety) | number | 设置绘制阴影时和原有对象的垂直偏移值。 | | [imageSmoothingEnabled](#imagesmoothingenabled) | boolean | 用于设置绘制图片时是否进行图像平滑度调整，true为启用，false为不启用。
- 默认值：true。 | -| imageSmoothingQuality | string | 用于设置图像平滑度，支持如下三种类型：'low', 'medium', 'high'。
- 默认值：'low'。 | > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > fillStyle、shadowColor与 strokeStyle 中string类型格式为 'rgb(255, 255, 255)'，'rgba(255, 255, 255, 1.0)'，'\#FFFFFF'。 @@ -572,8 +572,7 @@ struct ShadowColor { this.offContext.shadowColor = 'rgb(0,0,255)' this.offContext.fillStyle = 'rgb(255,0,0)' this.offContext.fillRect(30, 30, 100, 100) - var image = this.offContext.transferToImageBitmap -() + var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) } @@ -739,7 +738,7 @@ fillRect(x: number, y: number, w: number, h: number): void } ``` - ![zh-cn_image_0000001238832407](figures/zh-cn_image_0000001238832407.png) + ![zh-cn_image_0000001194192436](figures/zh-cn_image_0000001194192436.png) ### strokeRect @@ -767,6 +766,7 @@ strokeRect(x: number, y: number, w: number, h: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -785,7 +785,7 @@ strokeRect(x: number, y: number, w: number, h: number): void } ``` - ![zh-cn_image_0000001238712441](figures/zh-cn_image_0000001238712441.png) + ![zh-cn_image_0000001194352436](figures/zh-cn_image_0000001194352436.png) ### clearRect @@ -813,6 +813,7 @@ clearRect(x: number, y: number, w: number, h: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -821,8 +822,8 @@ clearRect(x: number, y: number, w: number, h: number): void .backgroundColor('#ffff00') .onReady(() =>{ this.offContext.fillStyle = 'rgb(0,0,255)' - this.offContext.fillRect(0,0,500,500) - this.offContext.clearRect(20,20,150,100) + this.offContext.fillRect(20,20,200,200) + this.offContext.clearRect(30,30,150,100) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -833,7 +834,7 @@ clearRect(x: number, y: number, w: number, h: number): void } ``` - ![zh-cn_image_0000001194192458](figures/zh-cn_image_0000001194192458.png) + ![zh-cn_image_0000001238952377](figures/zh-cn_image_0000001238952377.png) ### fillText @@ -861,6 +862,7 @@ fillText(text: string, x: number, y: number, maxWidth?: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -880,7 +882,7 @@ fillText(text: string, x: number, y: number, maxWidth?: number): void } ``` - ![zh-cn_image_0000001194352454](figures/zh-cn_image_0000001194352454.png) + ![zh-cn_image_0000001194032458](figures/zh-cn_image_0000001194032458.png) ### strokeText @@ -908,6 +910,7 @@ strokeText(text: string, x: number, y: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -976,6 +979,7 @@ measureText(text: string): TextMetrics private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1012,7 +1016,7 @@ stroke(path?: Path2D): void | path | [Path2D](ts-components-canvas-path2d.md) | 否 | null | 需要绘制的Path2D。 | **示例：** - + ```ts // xxx.ets @Entry @@ -1021,6 +1025,7 @@ stroke(path?: Path2D): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1030,6 +1035,8 @@ stroke(path?: Path2D): void .onReady(() =>{ this.offContext.moveTo(25, 25) this.offContext.lineTo(25, 105) + this.offContext.lineTo(75, 105) + this.offContext.lineTo(75, 25) this.offContext.strokeStyle = 'rgb(0,0,255)' this.offContext.stroke() var image = this.offContext.transferToImageBitmap() @@ -1042,7 +1049,7 @@ stroke(path?: Path2D): void } ``` - ![zh-cn_image_0000001239032427](figures/zh-cn_image_0000001239032427.png) + ![zh-cn_image_0000001238832389](figures/zh-cn_image_0000001238832389.png) ### beginPath @@ -1061,6 +1068,7 @@ beginPath(): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1110,6 +1118,7 @@ moveTo(x: number, y: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1157,6 +1166,7 @@ lineTo(x: number, y: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1197,6 +1207,7 @@ closePath(): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1253,6 +1264,7 @@ createPattern(image: ImageBitmap, repetition: string | null): CanvasPattern | nu private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private img:ImageBitmap = new ImageBitmap("common/images/icon.jpg") private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1303,6 +1315,7 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1352,6 +1365,7 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1403,6 +1417,7 @@ arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1452,6 +1467,7 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1512,7 +1528,7 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number .backgroundColor('#ffff00') .onReady(() =>{ this.offContext.beginPath() - this.offContext.ellipse(200, 200, 50, 100, Math.PI * 0.25, Math.PI * 0.5, Math.PI) + this.offContext.ellipse(200, 200, 50, 100, Math.PI * 0.25, Math.PI * 0.5, Math.PI * 2) this.offContext.stroke() var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) @@ -1524,7 +1540,7 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number } ``` - ![zh-cn_image_0000001238832411](figures/zh-cn_image_0000001238832411.png) + ![zh-cn_image_0000001194192440](figures/zh-cn_image_0000001194192440.png) ### rect @@ -1552,6 +1568,7 @@ rect(x: number, y: number, w: number, h: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1576,11 +1593,15 @@ rect(x: number, y: number, w: number, h: number): void ### fill -fill(): void +fill(fillRule?: CanvasFillRule): void 对封闭路径进行填充。 - **示例：** +**参数:** + +| 参数 | 类型 | 必填 | 默认值 | 描述 | +| -------- | -------------- | ---- | --------- | ---------------------------------------- | +| fillRule | CanvasFillRule | 否 | "nonzero" | 指定要填充对象的规则。
可选参数为："nonzero", "evenodd"。 | ```ts // xxx.ets @@ -1590,6 +1611,7 @@ fill(): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1612,12 +1634,73 @@ fill(): void ![zh-cn_image_0000001194192462](figures/zh-cn_image_0000001194192462.png) +fill(path: Path2D, fillRule?: CanvasFillRule): void + +对封闭路径进行填充。 + +**参数:** + +| 参数 | 类型 | 必填 | 默认值 | 描述 | +| -------- | -------------- | ---- | --------- | ---------------------------------------- | +| path | Path2D | 是 | | Path2D填充路径。 | +| fillRule | CanvasFillRule | 否 | "nonzero" | 指定要填充对象的规则。
可选参数为："nonzero", "evenodd"。 | + + +**示例:** + +```ts +// xxx.ets +@Entry +@Component +struct Fill { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let region = new Path2D(); + region.moveTo(30, 90); + region.lineTo(110, 20); + region.lineTo(240, 130); + region.lineTo(60, 130); + region.lineTo(190, 20); + region.lineTo(270, 90); + region.closePath(); + // Fill path + this.offContext.fillStyle = 'green'; + this.offContext.fill(region, "evenodd"); + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } +} +``` + + ![zh-cn_image_000000127777775](figures/zh-cn_image_000000127777775.png) + + + ### clip -clip(): void +clip(fillRule?: CanvasFillRule): void 设置当前路径为剪切路径。 +**参数:** + +| 参数 | 类型 | 必填 | 默认值 | 描述 | +| -------- | -------------- | ---- | --------- | ---------------------------------------- | +| fillRule | CanvasFillRule | 否 | "nonzero" | 指定要剪切对象的规则。
可选参数为："nonzero", "evenodd"。 | + **示例：** ```ts @@ -1628,6 +1711,7 @@ clip(): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1635,11 +1719,11 @@ clip(): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.offContext.rect(0, 0, 200, 200) + this.offContext.rect(0, 0, 100, 200) this.offContext.stroke() this.offContext.clip() this.offContext.fillStyle = "rgb(255,0,0)" - this.offContext.fillRect(0, 0, 150, 150) + this.offContext.fillRect(0, 0, 200, 200) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -1650,7 +1734,90 @@ clip(): void } ``` - ![zh-cn_image_0000001194352458](figures/zh-cn_image_0000001194352458.png) + ![zh-cn_image_0000001194032462](figures/zh-cn_image_0000001194032462.png) + + +clip(path:Path2D, fillRule?: CanvasFillRule): void + +设置封闭路径为剪切路径。 + +**参数:** + +| 参数 | 类型 | 必填 | 默认值 | 描述 | +| -------- | -------------- | ---- | --------- | ---------------------------------------- | +| path | Path2D | 是 | | Path2D剪切路径。 | +| fillRule | CanvasFillRule | 否 | "nonzero" | 指定要剪切对象的规则。
可选参数为："nonzero", "evenodd"。 | + + **示例：** + + ```ts + // xxx.ets +@Entry +@Component +struct Clip { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let region = new Path2D(); + region.rect(80,10,20,130); + region.rect(40,50,100,50); + this.offContext.clip(region,"evenodd") + this.offContext.fillStyle = "rgb(255,0,0)" + this.offContext.fillRect(0, 0, 600, 600) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } +} + ``` + + ![zh-cn_image_000000127777779](figures/zh-cn_image_000000127777779.png) + + + +### filter + +filter(filter: string): void + +为Canvas图形设置各类滤镜效果。该接口为空接口。 + +**参数:** + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| ------ | ------ | ---- | ---- | ------------ | +| filter | string | 是 | - | 接受各类滤镜效果的函数。 | + + +### getTransform + +getTransform(): Matrix2D + +获取当前被应用到上下文的转换矩阵。该接口为空接口。 + + +### resetTransform + +resetTransform(): void + +使用单位矩阵重新设置当前变形。该接口为空接口。 + + +### direction + +direction(direction: CanvasDirection): void + +绘制文本时，描述当前文本方向的属性。该接口为空接口。 ### rotate @@ -1675,6 +1842,7 @@ rotate(angle: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1720,6 +1888,7 @@ scale(x: number, y: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1727,9 +1896,10 @@ scale(x: number, y: number): void .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.offContext.strokeRect(10, 10, 25, 25) + this.offContext.lineWidth = 3 + this.offContext.strokeRect(30, 30, 50, 50) this.offContext.scale(2, 2) // Scale to 200% - this.offContext.strokeRect(10, 10, 25, 25) + this.offContext.strokeRect(30, 30, 50, 50) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -1740,7 +1910,7 @@ scale(x: number, y: number): void } ``` - ![zh-cn_image_0000001194032484](figures/zh-cn_image_0000001194032484.png) + ![zh-cn_image_0000001193872498](figures/zh-cn_image_0000001193872498.png) ### transform @@ -1777,6 +1947,7 @@ transform方法对应一个变换矩阵，想对一个图形进行变化的时 private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1832,6 +2003,7 @@ setTransform方法使用的参数和transform()方法相同，但setTransform() private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1880,6 +2052,7 @@ translate(x: number, y: number): void private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1934,7 +2107,7 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: // xxx.ets @Entry @Component - struct Index { + struct DrawImage { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private img:ImageBitmap = new ImageBitmap("common/images/icon.jpg") @@ -1964,7 +2137,7 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: createImageData(sw: number, sh: number): ImageData -根据宽高创建ImageData对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 +根据宽高创建ImageData对象，请参考[ImageData](ts-components-canvas-imagedata.md)。 **参数：** @@ -1974,23 +2147,21 @@ createImageData(sw: number, sh: number): ImageData | sh | number | 是 | 0 | ImageData的高度。 | -### createImageData - createImageData(imageData: ImageData): ImageData -根据已创建的ImageData对象创建新的ImageData对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 +根据已创建的ImageData对象创建新的ImageData对象，请参考[ImageData](ts-components-canvas-imagedata.md)。 **参数：** | 参数 | 类型 | 必填 | 默认 | 描述 | | --------- | ---------------------------------------- | ---- | ---- | ---------------- | -| imagedata | [ImageData](ts-components-canvas-imagebitmap.md) | 是 | null | 被复制的ImageData对象。 | +| imagedata | [ImageData](ts-components-canvas-imagedata.md) | 是 | null | 被复制的ImageData对象。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | -| [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象 | +| [ImageData](ts-components-canvas-imagedata.md) | 新的ImageData对象 | ### getPixelMap @@ -2018,7 +2189,7 @@ getPixelMap(sx: number, sy: number, sw: number, sh: number): PixelMap getImageData(sx: number, sy: number, sw: number, sh: number): ImageData -以当前canvas指定区域内的像素创建[ImageData](ts-components-canvas-imagebitmap.md)对象。 +以当前canvas指定区域内的像素创建[ImageData](ts-components-canvas-imagedata.md)对象。 **参数：** @@ -2033,7 +2204,42 @@ getImageData(sx: number, sy: number, sw: number, sh: number): ImageData | 类型 | 说明 | | ---------------------------------------- | ------------- | -| [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象 | +| [ImageData](ts-components-canvas-imagedata.md) | 新的ImageData对象 | + + +**示例：** + + ```ts + // xxx.ets +@Entry +@Component +struct GetImageData { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.drawImage(this.img,0,0,130,130); + var imagedata = this.offContext.getImageData(50,50,130,130); + this.offContext.putImageData(imagedata,150,150); + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } +} + ``` + + ![zh-cn_image_000000127777780](figures/zh-cn_image_000000127777780.png) ### putImageData @@ -2042,7 +2248,7 @@ putImageData(imageData: Object, dx: number, dy: number): void putImageData(imageData: Object, dx: number, dy: number, dirtyX: number, dirtyY: number, dirtyWidth?: number, dirtyHeight: number): void -使用[ImageData](ts-components-canvas-imagebitmap.md)数据填充新的矩形区域。 +使用[ImageData](ts-components-canvas-imagedata.md)数据填充新的矩形区域。 **参数：** @@ -2153,21 +2359,29 @@ getLineDash(): number[] ```ts // xxx.ets - @Entry - @Component - struct GetLineDash { +@Entry +@Component +struct OffscreenCanvasGetLineDash { + @State message: string = 'Hello World' private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(()=>{ + console.error('before getlinedash clicked') + let res = this.offContext.getLineDash() + console.error(JSON.stringify(res)) + }) Canvas(this.context) .width('100%') .height('100%') .backgroundColor('#ffff00') - .onReady(() =>{ - var grad = this.context.createLinearGradient(50,0, 300,100) + .onReady(() => { this.offContext.arc(100, 75, 50, 0, 6.28) this.offContext.setLineDash([10,20]) this.offContext.stroke(); @@ -2177,53 +2391,14 @@ getLineDash(): number[] }) } .width('100%') - .height('100%') } + .height('100%') } +} ``` +![zh-cn_image_000000127777778](figures/zh-cn_image_000000127777778.png) -### transferFromImageBitmap - -transferFromImageBitmap(bitmap: ImageBitmap): void - -显示给定的ImageBitmap对象。 - -**参数：** - -| 参数 | 类型 | 描述 | -| ------ | ---------------------------------------- | ------------------ | -| bitmap | [ImageData](ts-components-canvas-imagebitmap.md) | 待显示的ImageBitmap对象。 | - -**示例：** - - ```ts - // xxx.ets - @Entry - @Component - struct GetLineDash { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.fillRect(0, 0, 200, 200) - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) - } - .width('100%') - .height('100%') - } - } - ``` - ![zh-cn_image_000000127777773](figures/zh-cn_image_000000127777773.png) ### toDataURL @@ -2247,7 +2422,7 @@ toDataURL(type?: string, quality?: number): string **示例：** ```ts - // xxx.ets +// xxx.ets @Entry @Component struct ToDataURL { @@ -2272,6 +2447,19 @@ struct ToDataURL { ``` +### imageSmoothingQuality + +imageSmoothingQuality(quality: imageSmoothingQuality) + +用于设置图像平滑度。该接口为空接口。 + + **参数：** + +| 参数 | 类型 | 描述 | +| ------- | --------------------- | ---------------------------------------- | +| quality | imageSmoothingQuality | 支持如下三种类型：'low', 'medium', 'high'。 | + + ### transferToImageBitmap transferToImageBitmap(): ImageBitmap @@ -2282,7 +2470,7 @@ transferToImageBitmap(): ImageBitmap | 类型 | 说明 | | ---------------------------------------- | --------------- | -| [ImageData](ts-components-canvas-imagebitmap.md) | 存储离屏画布上渲染的像素数据。 | +| [ImageBitmap](ts-components-canvas-imagebitmap.md) | 存储离屏画布上渲染的像素数据。 | **示例：** @@ -2291,10 +2479,11 @@ transferToImageBitmap(): ImageBitmap // xxx.ets @Entry @Component - struct CanvasExample { + struct PutImageData { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -2302,7 +2491,14 @@ transferToImageBitmap(): ImageBitmap .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - this.offContext.restore() + var imageData = this.offContext.createImageData(100, 100) + for (var i = 0; i < imageData.data.length; i += 4) { + imageData.data[i + 0] = 255 + imageData.data[i + 1] = 0 + imageData.data[i + 2] = 255 + imageData.data[i + 3] = 255 + } + this.offContext.putImageData(imageData, 10, 10) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -2312,6 +2508,7 @@ transferToImageBitmap(): ImageBitmap } } ``` +![zh-cn_image_0000001238952387](figures/zh-cn_image_0000001238952387.png) ### restore @@ -2323,29 +2520,35 @@ restore(): void ```ts // xxx.ets - @Entry - @Component - struct CanvasExample { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.restore() - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) - } - .width('100%') - .height('100%') +@Entry +@Component +struct CanvasExample { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.save(); // save the default state + this.offContext.fillStyle = "green"; + this.offContext.fillRect(20, 20, 100, 100); + this.offContext.restore(); // restore to the default state + this.offContext.fillRect(150, 75, 100, 100); + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) } + .width('100%') + .height('100%') } +} ``` +![zh-cn_image_000000127777781](figures/zh-cn_image_000000127777781.png) ### save @@ -2358,29 +2561,35 @@ save(): void ```ts // xxx.ets - @Entry - @Component - struct CanvasExample { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.save() - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) +@Entry +@Component +struct CanvasExample { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.save(); // save the default state + this.offContext.fillStyle = "green"; + this.offContext.fillRect(20, 20, 100, 100); + this.offContext.restore(); // restore to the default state + this.offContext.fillRect(150, 75, 100, 100); + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) }) - } - .width('100%') - .height('100%') } + .width('100%') + .height('100%') } +} ``` +![zh-cn_image_000000127777781](figures/zh-cn_image_000000127777781.png) ### createLinearGradient diff --git a/zh-cn/application-dev/reference/errorcodes/errcode-hiviewdfx-hiappevent.md b/zh-cn/application-dev/reference/errorcodes/errcode-hiviewdfx-hiappevent.md new file mode 100644 index 0000000000000000000000000000000000000000..c36645d3d21788f24bddabcf644ca4f438bb8cab --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errcode-hiviewdfx-hiappevent.md @@ -0,0 +1,278 @@ +# 应用事件打点错误码 + +## 11100001 打点功能被关闭 + +**错误信息** + +Function is disabled. + +**错误描述** + +在调用write接口进行应用事件打点时，由于打点功能未开启，系统将忽略相关事件。 + +**可能原因** + +应用事件打点功能被关闭了。 + +**处理步骤** +调用配置接口开启打点功能。 + + ```js + hiAppEvent.configure({ + disable: false + }); + ``` + +## 11101001 非法的事件领域名称 +**错误信息** + +Invalid event domain. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件领域名称，系统将忽略相关事件。 + +**可能原因** + +传入的事件领域名称不符合以下规则： + +- 事件领域名称只包含数字、小写字母、下划线字符。 +- 事件领域名称以小写字母开头，不以下划线结尾。 +- 事件领域名称非空且长度不超过32个字符。 + +**处理步骤** +传入合法的事件领域名称。 + +## 11101002 非法的事件名称 + +**错误信息** + +Invalid event name. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件名称，系统将忽略相关事件。 + +**可能原因** + +传入的事件名称不符合以下规则： + +- 事件名称只包含数字、小写字母、下划线字符。 +- 事件名称以小写字母开头，不以下划线结尾。 +- 事件名称非空且长度不超过48个字符。 + +**处理步骤** + +传入合法的事件名称。 + +## 11101003 非法的事件参数数量 + +**错误信息** + +Invalid number of event parameters. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件参数数量，额外的事件参数将被丢弃。 + +**可能原因** + +传入的事件参数数量超过32个。 + +**处理步骤** + +传入合法数量的事件参数。 + +## 11101004 非法的事件参数字符串长度 + +**错误信息** + +Invalid string length of the event parameter. + +**错误描述** + +在调用write接口进行应用事件打点时，由于事件参数值传入了超长的字符串，超出长度的字符将被丢弃。 + +**可能原因** + +传入的事件参数值中的字符串长度超过8*1024个字符。 + +**处理步骤** + +传入合法字符串长度的事件参数值。 + +## 11101005 非法的事件参数名称 + +**错误信息** + +Invalid event parameter name. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件参数名称，系统将忽略相关事件参数。 + +**可能原因** + +传入的事件名称不符合以下规则： + +- 事件名称只包含数字、小写字母、下划线字符。 +- 事件名称以小写字母开头，不以下划线结尾。 +- 事件名称非空且长度不超过16个字符。 + +**处理步骤** + +传入合法的事件参数名称。 + +## 11101006 非法的事件参数数组长度 + +**错误信息** + +Invalid array length of the event parameter. + +**错误描述** + +在调用write接口进行应用事件打点时，由于事件参数值传入了超出长度的数组，额外的数组元素将被丢弃。 + +**可能原因** + +传入的事件参数值中的数组长度超过100。 + +**处理步骤** + +传入合法长度数组的事件参数值。 + +## 11102001 非法的观察者名称 + +**错误信息** + +Invalid watcher name. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于传入了非法的观察者名称，系统将忽略此次订阅。 + +**可能原因** + +传入的观察者名称不符合以下规则： + +- 观察者名称只包含数字、小写字母、下划线字符。 +- 观察者名称以小写字母开头，不以下划线结尾。 +- 观察者名称非空且长度不超过32个字符。 + +**处理步骤** + +传入合法的观察者名称。 + +## 11102002 非法的过滤事件领域 + +**错误信息** + +Invalid filtering event domain. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于传入了非法的过滤事件领域，系统将忽略此次订阅。 + +**可能原因** + +传入的过滤事件领域名称不符合以下规则： + +- 事件领域名称只包含数字、小写字母、下划线字符。 +- 事件领域名称以小写字母开头，不以下划线结尾。 +- 事件领域名称非空且长度不超过32个字符。 + +**处理步骤** + +传入合法的过滤事件领域名称。 + +## 11102003 非法的条数值 + +**错误信息** + +Invalid row value. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于回调触发条件传入了非法的事件个数值，系统将忽略此次订阅。 + +**可能原因** + +传入的回调触发条件中的条数值为负数。 + +**处理步骤** + +传入自然数值的条数值。 + +## 11102004 非法的大小值 + +**错误信息** + +Invalid size value. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于回调触发条件传入了非法的事件大小值，系统将忽略此次订阅。 + +**可能原因** + +传入的回调触发条件中的大小值为负数。 + +**处理步骤** + +传入自然数值的大小值。 + +## 11102005 非法的超时值 + +**错误信息** + +Invalid timeout value. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于回调触发条件传入了非法的超时值，系统将忽略此次订阅。 + +**可能原因** + +传入的回调触发条件中的超时值为负数。 + +**处理步骤** + +传入自然数值的超时值。 + +## 11103001 非法的最大存储配额值 + +**错误信息** + +Invalid max storage quota value. + +**错误描述** + +在调用configure接口进行打点配置时，由于传入了非法的最大存储配额值，系统将忽略此次配置。 + +**可能原因** + +传入的最大存储配额值字符串不符合以下规则： + +- 最大存储配额值以数字开头，以大小单位（单位字符支持[b|k|kb|m|mb|g|gb|t|tb]，不区分大小写）结尾，且不包含其他字符。 + +**处理步骤** + +传入合法的最大存储配额值字符串。 + +## 11104001 非法的事件包大小值 + +**错误信息** + +Invalid size value. + +**错误描述** + +在调用setSize接口对每次取出的事件包大小阈值进行设置时，由于传入了非法的事件包大小值，系统将忽略此次设置。 + +**可能原因** + +传入的事件包大小值为负数。 + +**处理步骤** + +传入自然数值的事件包大小。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errcode-usb.md b/zh-cn/application-dev/reference/errorcodes/errcode-usb.md new file mode 100644 index 0000000000000000000000000000000000000000..4a7910cc0b9a9074c002185ab880e9a3030a91ac --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errcode-usb.md @@ -0,0 +1,19 @@ +# USB服务错误码 + +## 14400001 连接USB设备被拒绝 + +**错误信息** + +Permission denied. Need call requestRight to get permission. + +**错误描述** + +当调用USB模块部分接口时，如果没有相关权限，会报此错误码。 + +**可能原因** + +没有获取到设备的使用权限。 + +**处理步骤** + +调用requestRight方法申请设备的使用权限。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-device-manager.md b/zh-cn/application-dev/reference/errorcodes/errorcode-device-manager.md new file mode 100644 index 0000000000000000000000000000000000000000..1884284f55f3636e0b366820dffa7d48a225da72 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-device-manager.md @@ -0,0 +1,71 @@ +# 设备管理错误码 + +## 11600101 服务调用异常 + +**错误信息** + +Failed to execute the function. + +**可能原因** + +服务内部调用异常。 + +**处理步骤** + +重新调用接口再次触发调用。 + +## 11600102 获取服务失败 + +**错误信息** + +Failed to obtain the service. + +**可能原因** + +服务未启动或者服务启动失败。 + +**处理步骤** + +检查服务是否正常启动，重新获取服务。 + +## 11600103 认证业务不可用 + +**错误信息** + +Authentication invalid. + +**可能原因** + +上一次认证业务未结束。 + +**处理步骤** + +等待上一次认证业务结束，重新发起认证调用。 + +## 11600104 发现业务不可用 + +**错误信息** + +Discovery invalid. + +**可能原因** + +上一次发现业务未结束。 + +**处理步骤** + +等待上一次发现业务结束，重新发起发现调用。 + +## 11600105 发布业务不可用 + +**错误信息** + +Publish invalid. + +**可能原因** + +上一次发布业务未结束。 + +**处理步骤** + +等待上一次发布业务结束，重新发起发布调用。 diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-faultlogger.md b/zh-cn/application-dev/reference/errorcodes/errorcode-faultlogger.md new file mode 100644 index 0000000000000000000000000000000000000000..397279658180123ee8d4b8989810ff549e29b6bd --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-faultlogger.md @@ -0,0 +1,19 @@ +# faultlogger 错误码 + +## 10600001 服务未启动或故障 + +**错误信息** + +The service is not running or broken. + +**错误描述** + +服务未启动/故障。 + +**可能原因** + +hiview服务未启动。 + +**处理步骤** + +不应该发生的场景，考虑重试。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-hisysevent.md b/zh-cn/application-dev/reference/errorcodes/errorcode-hisysevent.md new file mode 100644 index 0000000000000000000000000000000000000000..0d573cf63851c5a46fffafb7c43b9b132947d7a6 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-hisysevent.md @@ -0,0 +1,284 @@ +# 系统事件错误码 + +## 1120001 非法的事件领域 + +**错误信息** + +Invalid event domain. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入了非法的事件领域名称，系统将忽略此次系统事件打点。 + +**可能原因** + +1.系统事件领域名称长度超过16个字符； +2.系统事件领域名称包含特殊字符； +3.系统事件领域名称为空。 + +**处理步骤** + +检查系统事件领域名称是否合法。 + +## 1120002 非法的事件名称 + +**错误信息** + +Invalid event name. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入了非法的事件名称，系统将忽略此次系统事件打点。 + +**可能原因** + +1.系统事件名称长度超过32个字符； +2.系统事件名称包含特殊字符； +3.系统事件名称为空。 + +**处理步骤** + +检查系统事件名称是否合法。 + +## 11200003 环境异常 + +**错误信息** + +Abnormal environment. + +**错误描述** + +在调用write接口进行系统事件打点时，由于环境异常，系统将忽略此次系统事件打点。 + +**可能原因** + +1.hiview服务未成功启动； +2.hiview服务socket异常。 + +**处理步骤** + +尝试重新调用write接口进行打点。 + +## 11200004 事件长度超过限制 + +**错误信息** + +Length of the event is over limit. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入的事件总长度超过限制，系统将忽略此次系统事件打点。 + +**可能原因** + +系统事件总长度超过384K。 + +**处理步骤** + +检查系统事件总长度是否大于384K。 + +## 11200051 非法的事件参数 + +**错误信息** + +Invalid event parameter. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入了非法的参数名称，系统将忽略此次系统事件打点。 + +**可能原因** + +1.系统事件参数名称长度超过32个字符； +2.系统事件参数名称包含特殊字符； +3.系统事件参数名为空。 + +**处理步骤** + +检查系统事件参数名称是否合法。 + +## 11200052 字符串类型的事件参数值的长度超过限制 + +**错误信息** + +Size of the event parameter of the string type is over limit. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入了长度超限的字符串类型参数，系统将忽略此次系统事件打点。 + +**可能原因** + +字符串类型的参数值的长度超过256K。 + +**处理步骤** + +检查系统事件中字符串类型的参数值的长度是否超过256K。 + +## 11200053 事件参数的数量超过限制 + +**错误信息** + +Count of event parameters is over limit. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入的事件参数数量超过限制，系统将将忽略此次系统事件打点。 + +**可能原因** + +系统事件的参数数量超过128个。 + +**处理步骤** + +检查系统事件的参数数量是否超过了128个。 + + +## 11200054 数组类型的事件参数值的长度超过限制 + +**错误信息** + +Count of event parameter of the array type is over limit. + +**错误描述** + +在调用write接口进行系统事件打点时，由于传入了长度超过限制的数组类型的参数，系统将忽略此次系统事件打点。 + +**可能原因** + +系统事件中有数组类型的参数值的长度超过100。 + +**处理步骤** + +检查数组类型的参数值的长度是否超过100. + +## 11200101 事件监听者的数量超过限制 + +**错误信息** + +Count of watchers is over limit. + +**错误描述** + +在调用addWatcher接口添加系统事件监听者时，由于添加的监听者数量超过限制，系统将拒绝此系统事件监听者的添加。 + +**可能原因** + +hiview服务已添加30个系统事件监听者，无法添加新的系统事件监听者。 + +**处理步骤** + +检查已成功添加的系统事件监听者数量是否超过了30个。 + +## 11200102 事件监听者包含的监听规则数量超过限制 + +**错误信息** + +Count of watch rules is over limit. + +**错误描述** + +在调用addWatcher接口添加系统事件监听者时，由于该系统事件监听者包含的监听规则数量超过限制，系统将拒绝此系统事件监听者的添加。 + +**可能原因** + +系统事件监听者包含的监听规则的数量超过20个。 + +**处理步骤** + +检查系统事件监听者包含的监听规则数量是否超过20个。 + +## 11200201 事件监听者不存在 + +**错误信息** + +The watcher does not exist. + +**错误描述** + +在调用removeWatcher移除系统事件监听者时，由于该系统事件监听者不在监听队列，系统将拒绝此系统事件监听者的移除。 + +**可能原因** + +1.尝试移除的系统事件监听者为空； +2.尝试移除的系统事件监听者没有被成功添加过。 + +**处理步骤** + +检查移除的系统事件监听者是否为空，或者是否成功添加过此系统事件监听者。 + +## 11200301 查询规则的数量超过限制 + +**错误信息** + +Count of query rules is over limit. + +**错误描述** + +在调用query接口查询系统事件时，由于传入的查询规则数量超限，系统将忽略此次系统事件的查询。 + +**可能原因** + +查询规则个数超过10个。 + +**处理步骤** + +检查查询规则数量是否超过10个。 + + +## 11200302 非法的查询规则 + +**错误信息** + +Invalid query rule. + + +**错误描述** + +在调用query接口查询系统事件时，由于传入了非法的查询规则，系统将忽略此次系统事件的查询。 + +**可能原因** + +1.查询规则中的事件领域名称长度超过16个字符或者事件名称长度超过32个字符； +2.查询规则中的事件领域名称或者事件名称包含特殊字符； +3.查询规则中的事件领域名称或者事件名称为空。 + +**处理步骤** + +检查查询规则中配置的事件领域名称及事件名称是否合法。 + +## 11200303 并发查询的数量超过限制 + +**错误信息** + +Count of concurrent queriers is over limit. + +**错误描述** + +在调用query接口查询系统事件时，由于在同一时间点并发查询的数量超过限制，系统将忽略此次系统事件的查询。 + +**可能原因** + +并发查询的数量超过4个。 + +**处理步骤** + +检查在同一时间点是否有4个以上的查询操作。 + +## 11200304 查询频率超过限制 + +**错误信息** + +Query frequency is over limit. + +**错误描述** + +在调用query接口查询系统事件时，由于查询频率超过限制，系统将忽略此次系统事件的查询。 + +**可能原因** + +查询频率超过1次/秒。 + +**处理步骤** + +检查是否在1秒内进行1次以上的查询。 diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-hiviewdfx-hidebug.md b/zh-cn/application-dev/reference/errorcodes/errorcode-hiviewdfx-hidebug.md new file mode 100644 index 0000000000000000000000000000000000000000..4c843b8bbde55cd2fe27b1d4a47c10126a023c0f --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-hiviewdfx-hidebug.md @@ -0,0 +1,20 @@ +# Hidebug错误码 + + +## 11400101 系统服务获取失败 + +**错误信息** + +ServiceId is invalid, systemAbility is not exist. + +**错误描述** +当前serviceId未查询到对应的系统服务。 + +**可能原因** + +当前serviceId未查询到对应的系统服务。 + +**处理步骤** + +传入正确的系统服务id。 + diff --git a/zh-cn/application-dev/reference/errorcodes/errorcodes-request.md b/zh-cn/application-dev/reference/errorcodes/errorcodes-request.md new file mode 100644 index 0000000000000000000000000000000000000000..2f7063b797dea8ff1f61361128ef7105252b8172 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcodes-request.md @@ -0,0 +1,55 @@ +# 上传下载错误码 + +## 13400001 文件操作异常 + +**错误信息** + +File operation error. + +**错误描述** + +在调用uploadFile或downloadFile接口时，文件权限不足或操作失败。 + +**可能原因** + +该错误码表示文件操作异常，可能原因文件权限不足。 + +**处理步骤** + +请检查文件权限是否合理。 + +## 13400002 文件路径异常 + +**错误信息** + +Bad file path. + +**错误描述** + +在调用uploadFile或downloadFile接口时，文件路径不合法。 + +**可能原因** + +该错误码表示文件路径异常，可能原因文件路径错误。 + +**处理步骤** + +请检查上传下载的文件路径是否正确。 + +## 13400003 服务异常 + +**错误信息** + +Task manager service error. + +**错误描述** + +在调用downloadFile接口时，下载任务后台服务失败。 + +**可能原因** + +该错误码表示服务异常，，可能原因任务创建失败 + +**处理步骤** + +请检查任务配置是否正确。 diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-button.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-button.md index 85c5e3f991f074293020d6c8bda91d552e128f76..e2f30cc43202e020269f86c48ce063e8c0288207 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-button.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-button.md @@ -18,7 +18,7 @@ | 名称 | 类型 | 默认值 | 必填 | 描述 | | -------- | -------- | -------- | -------- | -------- | -| type | string | - | 否 | 不支持动态修改。如果该属性缺省，展示类胶囊型按钮，不同于胶囊类型，四边圆角可以通过border-radius分别指定，如果需要设置该属性，可选值如下：
- "capsule"：胶囊型按钮，带圆角按钮，有背景色和文本。
- "circle"：圆形按钮，支持放置图标。
- "text"：文本按钮，仅包含文本显示。 | +| type | string | capsule | 否 | 不支持动态修改。如果该属性缺省，展示类胶囊型按钮，不同于胶囊类型，四边圆角可以通过border-radius分别指定，如果需要设置该属性，可选值如下：
- "capsule"：胶囊型按钮，带圆角按钮，有背景色和文本。
- "circle"：圆形按钮，支持放置图标。
- "text"：文本按钮，仅包含文本显示。 | | value | string | - | 否 | button的文本值，circle类型不生效。 | | icon | string | - | 否 | button的图标路径，图标格式为jpg，png和svg。 | | placement | string | end | 否 | 仅在type属性为缺省时生效，设置图标位于文本的位置，可选值为：
- "start"：图标位于文本起始处。
- "end"：图标位于文本结束处。
- "top"：图标位于文本上方。
- "bottom"：图标位于文本下方。 | diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-chart.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-chart.md index b33a056112da8b5298eb5cd3a79eefb458deeda7..42fab229cffde0dc14d0e99ff49bb00b0f91b6b2 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-chart.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-chart.md @@ -16,14 +16,14 @@ 除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| ----------------- | ---------------------------------- | ---- | ---- | ---------------------------------------- | -| type | string | line | 否 | 设置图表类型（不支持动态修改），可选项有：
- bar：柱状图。
- line：线形图。
- gauge：量规图。
- progress：进度类圆形图表。
- loading：加载类圆形图表。
- rainbow：占比类圆形图表。 | -| options | ChartOptions | - | 否 | 图表参数设置，柱状图和线形图必须设置参数设置，量规图不生效。可以设置x轴、y轴的最小值、最大值、刻度数、是否显示，线条宽度、是否平滑等。（不支持动态修改） | -| datasets | Array\ | - | 否 | 数据集合，柱状图和线形图必须设置数据集合，量规图不生效。可以设置多条数据集及其背景色。 | -| segments | DataSegment \| Array\ | | 否 | 进度类、加载类和占比类圆形图表使用的数据结构。
DataSegment针对进度类和加载类圆形图表使用，Array\针对占比类图标使用，DataSegment最多9个。 | -| effects | boolean | true | 否 | 是否开启占比类、进度类圆形图表特效。 | -| animationduration | number | 3000 | 否 | 设置占比类圆形图表展开动画时长，单位为ms。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ----------------- | ---------------------------------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | line | 否 | 设置图表类型（不支持动态修改），可选项有：
- bar：柱状图。
- line：线形图。
- gauge：量规图。
- progress：进度类圆形图表。
- loading：加载类圆形图表。
- rainbow：占比类圆形图表。 | +| options | ChartOptions | - | 否 | 图表参数设置，用于设置x轴、y轴的最小值、最大值、刻度数、是否显示，线条宽度、是否平滑等。（不支持动态修改）,量规图不生效。 | +| datasets | Array\ | - | 否 | 数据集合，用于设置多条数据集及其背景色，量规图不生效。 | +| segments | DataSegment \| Array\ | | 否 | 进度类、加载类和占比类圆形图表使用的数据结构。
DataSegment针对进度类和加载类圆形图表使用，Array\针对占比类图标使用，DataSegment最多9个。 | +| effects | boolean | true | 否 | 是否开启占比类、进度类圆形图表特效。 | +| animationduration | number | 3000 | 否 | 设置占比类圆形图表展开动画时长，单位为ms。 | **表1** ChartOptions diff --git a/zh-cn/application-dev/security/accesstoken-guidelines.md b/zh-cn/application-dev/security/accesstoken-guidelines.md index 45cd9279b55872bed403e2b1ce8e3e74a34a591e..408d90afdf1bcfb3883f8dd74dde5a1d1222306c 100644 --- a/zh-cn/application-dev/security/accesstoken-guidelines.md +++ b/zh-cn/application-dev/security/accesstoken-guidelines.md @@ -171,5 +171,5 @@ 针对访问控制，有以下相关实例可供参考： -- [`AbilityAccessCtrl`：访问权限控制（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Safety/AbilityAccessCtrl) -- [为应用添加运行时权限（eTS）（API 9）](https://gitee.com/openharmony/codelabs/tree/master/Ability/AccessPermission) \ No newline at end of file +- [`AbilityAccessCtrl`：访问权限控制（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Safety/AbilityAccessCtrl) +- [为应用添加运行时权限（ArkTS）（API 9）](https://gitee.com/openharmony/codelabs/tree/master/Ability/AccessPermission) \ No newline at end of file diff --git a/zh-cn/application-dev/security/cryptoFramework-guidelines.md b/zh-cn/application-dev/security/cryptoFramework-guidelines.md index 368108ba13572fde86046d1e30febc4dae2551ed..734dcf92c03846e7755e29005c5fd9914d5a3195 100644 --- a/zh-cn/application-dev/security/cryptoFramework-guidelines.md +++ b/zh-cn/application-dev/security/cryptoFramework-guidelines.md @@ -100,7 +100,7 @@ function testGenerateAesKey() { 示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2） -1. 获取RSA二进制密钥数据封装成DataBlob对象，按keysize(32位) 、nsize(keysize/8)、 esize(e实际长度)、dsize(keysize/8)、nval(大数n的二进制数据)、eval(大数e的二进制数据)和dval(大数d的二进制数据)拼接形成。 +1. 获取RSA二进制密钥数据封装成DataBlob对象，按keysize(32位的密钥位数) 、nsize(32位，值为keysize/8)、 esize(32位的大数e的实际长度，单位Byte)、dsize(32位，值位keysize/8)、nval(大数n的二进制数据)、eval(大数e的二进制数据)和dval(大数d的二进制数据)拼接形成。 2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 ```javascript @@ -649,7 +649,7 @@ function signMessageCallback() { } function verifyMessageCallback() { - let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25"); + let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); verifyer.init(globalKeyPair.pubKey, function (err, data) { verifyer.update(input1, function(err, data) { verifyer.verify(input2, SignMessageBlob, function(err, data) { @@ -875,15 +875,6 @@ function doMdByCallback(algName) { ```javascript import cryptoFramework from "@ohos.security.cryptoFramework" -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpArray = new Uint8Array(arr); - return tmpArray; -} - let globalKeyPair; function ecdhPromise() { diff --git a/zh-cn/application-dev/security/huks-guidelines.md b/zh-cn/application-dev/security/huks-guidelines.md index ad21dacc614d44fe52b4829ebe8cdef4d5e7ff6d..be627e670fcd7250d050e319c31179d5830f2b0c 100644 --- a/zh-cn/application-dev/security/huks-guidelines.md +++ b/zh-cn/application-dev/security/huks-guidelines.md @@ -625,7 +625,7 @@ struct Index { | ------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------- | ----------- | | HUKS_ALG_SM4 （支持长度： HUKS_SM4_KEY_SIZE_128） | HUKS_KEY_PURPOSE_ENCRYPT HUKS_KEY_PURPOSE_DECRYPT | 【非必选】 | HUKS_PADDING_NONE | HUKS_MODE_CTR HUKS_MODE_ECB HUKS_MODE_CBC | 【必选】 | | HUKS_ALG_SM4 （支持长度： HUKS_SM4_KEY_SIZE_128） | HUKS_KEY_PURPOSE_ENCRYPT HUKS_KEY_PURPOSE_DECRYPT | 【非必选】 | HUKS_PADDING_PKCS7 | HUKS_MODE_ECB HUKS_MODE_CBC | 【必选】 | -| HUKS_ALG_RSA （支持长度： HUKS_SM4_KEY_SIZE_512 HUKS_SM4_KEY_SIZE_768 HUKS_SM4_KEY_SIZE_1024 HUKS_SM4_KEY_SIZE_2048 HUKS_SM4_KEY_SIZE_3072 HUKS_SM4_KEY_SIZE_4096） | HUKS_KEY_PURPOSE_ENCRYPT HUKS_KEY_PURPOSE_DECRYPT | HUKS_DIGEST_SHA1 HUKS_DIGEST_SHA224 HUKS_DIGEST_SHA256 HUKS_DIGEST_SHA384 HUKS_DIGEST_SHA512 | HUKS_PADDING_NONE HUKS_PADDING_PKCS1_V1_5 HUKS_PADDING_OAEP | HUKS_MODE_ECB | 【非必选】 | +| HUKS_ALG_RSA （支持长度： HUKS_RSA_KEY_SIZE_512 HUKS_RSA_KEY_SIZE_768 HUKS_RSA_KEY_SIZE_1024 HUKS_RSA_KEY_SIZE_2048 HUKS_RSA_KEY_SIZE_3072 HUKS_RSA_KEY_SIZE_4096） | HUKS_KEY_PURPOSE_ENCRYPT HUKS_KEY_PURPOSE_DECRYPT | HUKS_DIGEST_SHA1 HUKS_DIGEST_SHA224 HUKS_DIGEST_SHA256 HUKS_DIGEST_SHA384 HUKS_DIGEST_SHA512 | HUKS_PADDING_NONE HUKS_PADDING_PKCS1_V1_5 HUKS_PADDING_OAEP | HUKS_MODE_ECB | 【非必选】 | | HUKS_ALG_ALGORITHM | HUKS_TAG_PURPOSE | HUKS_TAG_PADDING | HUKS_TAG_BLOCK_MODE | HUKS_TAG_IV | HUKS_TAG_NONCE | HUKS_TAG_ASSOCIATED_DATA | HUKS_TAG_AE_TAG | | ------------------------------------------------------------ | ------------------------ | ------------------------------------- | ---------------------------- | ----------- | -------------- | ------------------------ | --------------- | diff --git a/zh-cn/application-dev/security/permission-list.md b/zh-cn/application-dev/security/permission-list.md index 93151a0c682a67f4d0f661cc0f4c0ac51d3fae34..4173342f15e987ded3dfcbddf12d775707cfd2ae 100644 --- a/zh-cn/application-dev/security/permission-list.md +++ b/zh-cn/application-dev/security/permission-list.md @@ -148,4 +148,5 @@ | ohos.permission.ACCESS_CERT_MANAGER_INTERNAL | system_basic | system_grant | FALSE | 允许应用进行证书及凭据的安装、卸载、启用、禁用等操作。 | | ohos.permission.ACCESS_CERT_MANAGER | normal | system_grant | FALSE | 允许应用进行私有凭据的相关操作、查询证书状态等操作。 | | ohos.permission.ACCESS_PUSH_SERVICE | system_basic | system_grant | TRUE | 允许应用访问推送服务的Ability。 | -| ohos.permission.RECEIVER_STARTUP_COMPLETED | system_basic | system_grant | FALSE | 允许应用订阅开机广播。 | \ No newline at end of file +| ohos.permission.RECEIVER_STARTUP_COMPLETED | system_basic | system_grant | FALSE | 允许应用订阅开机广播。 | +| ohos.permission.MANAGE_CAMERA_CONFIG | system_basic | system_grant | FALSE | 允许应用进行全局相机开关等操作。 | \ No newline at end of file diff --git a/zh-cn/application-dev/task-management/Readme-CN.md b/zh-cn/application-dev/task-management/Readme-CN.md index 994e21697c55f18fd58df906939975cca4f694d8..2674843279061115a0ab11b494dd9b6556e27bff 100644 --- a/zh-cn/application-dev/task-management/Readme-CN.md +++ b/zh-cn/application-dev/task-management/Readme-CN.md @@ -2,12 +2,11 @@ - 后台任务 - [后台任务概述](background-task-overview.md) - - [后台任务开发指导](background-task-dev-guide.md) - -- 延迟任务调度 - - [延迟任务调度概述](work-scheduler-overview.md) - - [延迟任务调度开发指导](work-scheduler-dev-guide.md) + - [短时任务开发指导](transient-task-dev-guide.md) + - [长时任务开发指导](continuous-task-dev-guide.md) + - [延迟任务开发指导](work-scheduler-dev-guide.md) + - [申请能效资源开发指导](efficiency-resources-apply-dev-guide.md) - 后台代理提醒 - [后台代理提醒开发概述](background-agent-scheduled-reminder-overview.md) - - [后台代理提醒开发指导](background-agent-scheduled-reminder-guide.md) \ No newline at end of file + - [后台代理提醒开发指导](background-agent-scheduled-reminder-guide.md) diff --git a/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md index 918b5d918adfdb6eb2bd908435793ed66bf28357..4362b733b63c2d67fd302ebcedd2c9f695c56846 100644 --- a/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md +++ b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md @@ -24,159 +24,168 @@ reminderAgentManager：封装了发布、取消提醒类通知的方法。 ## 开发步骤 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > > 1. 应用需要配置权限：ohos.permission.PUBLISH_AGENT_REMINDER。 > > 2. 应用需要申请通知弹窗：[Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8)。 - -1. 定义一个提醒代理。 - - 倒计时实例定义： - ```js - import reminderAgentManager from '@ohos.reminderAgentManager'; - import notification from '@ohos.notification'; - export default { - // eTS工程： - let timer : reminderAgentManager.ReminderRequestTimer = { - reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, - triggerTimeInSeconds: 10, - actionButton: [ - { - title: "close", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - } - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION - } - } - ``` - - 日历实例定义： - - ```js - // eTS工程： - let calendar : reminderAgentManager.ReminderRequestCalendar = { - reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, - dateTime: { - year: 2050, - month: 7, - day: 30, - hour: 11, - minute: 14, - second: 30 - }, - repeatMonths: [1], - repeatDays: [1], - actionButton: [ - { - title: "close", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION - } - ``` - - 闹钟实例定义： - - ```js - // eTS工程： - let alarm : reminderAgentManager.ReminderRequestAlarm = { - reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, +> 只有用户授权后，提醒代理的功能才能使用。 + +1、定义目标提醒代理。 + +2、发布相应的提醒代理。 + +```ts +import reminderAgentManager from '@ohos.reminderAgentManager'; +import notification from '@ohos.notification'; + +// 倒计时实例定义： +let timer : reminderAgentManager.ReminderRequestTimer = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, + triggerTimeInSeconds: 10, + actionButton: [ + { + title: "close", + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + } + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION +} + +// 日历实例定义： +let calendar : reminderAgentManager.ReminderRequestCalendar = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, + dateTime: { + year: 2050, + month: 7, + day: 30, hour: 11, minute: 14, - daysOfWeek: [0], - actionButton: [ - { - title: "close", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" + second: 30 + }, + repeatMonths: [1], + repeatDays: [1], + actionButton: [ + { + title: "close", + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: "snooze", + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + ringDuration: 5, + snoozeTimes: 2, + timeInterval: 5, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + snoozeContent: "remind later", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION +} + +// 闹钟实例定义： +let alarm : reminderAgentManager.ReminderRequestAlarm = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, + hour: 11, + minute: 14, + daysOfWeek: [0], + actionButton: [ + { + title: "close", + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" + { + title: "snooze", + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + ringDuration: 5, + snoozeTimes: 2, + timeInterval: 5, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + snoozeContent: "remind later", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION +} + +@Entry +@Component +struct Index { + @State message: string = 'test' + + publishReminder() { + try { + reminderAgentManager.publishReminder(this.timer).then(res => { + console.log("publishReminder promise reminderId:" + res); + }).catch(err => { + console.log("publishReminder err code:" + err.code + " message:" + err.message); + }) + } catch (error) { + console.log("publishReminder code:" + error.code + " message:" + error.message); + }; + } + + build() { + Row() { + Column() { + Text("Index") + .fontSize(50) + .fontWeight(FontWeight.Bold) + + Button() { Text('倒计时提醒代理').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) + .margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40) + .onClick(() => { + // 示例通过按钮控制提醒代理的发布 + this.publishReminder(); + }) + + } + .width('100%') } - ``` - -2. 发布倒计时提醒。 - ```js - startTimer() { - try { - reminderAgent.publishReminder(this.timer).then(res => { - console.log("publishReminder promise reminderId:" + res); - }).catch(err => { - console.log("publishReminder err code:" + err.code + " message:" + err.message); - }) - } catch (error) { - console.log("publishReminder code:" + error.code + " message:" + error.message); - }; - } - ``` - - HML页面： - ```html -
- -
- ``` + .height('100%') + } +} +``` ## 相关实例 基于后台代理提醒开发，有以下相关实例可供参考： -- [`AlarmClock`：后台代理提醒（eTS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/Notification/AlarmClock) +- [`AlarmClock`：后台代理提醒（ArkTS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/Notification/AlarmClock) -- [`FlipClock`：翻页时钟（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/CompleteApps/FlipClock) +- [`FlipClock`：翻页时钟（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/CompleteApps/FlipClock) -- [闹钟应用（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/CommonEventAndNotification/AlarmClock) \ No newline at end of file +- [闹钟应用（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/CommonEventAndNotification/AlarmClock) \ No newline at end of file diff --git a/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md index d31a74e423230d965ccda41153480ae2348f945f..a7da0fe1e9b46e5ccb379677a57e0da65cad36f7 100644 --- a/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md +++ b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md @@ -1,3 +1,12 @@ # 后台代理提醒概述 -开发者在应用开发时，可以调用后台代理提醒类ReminderRequest去创建定时提醒，包括倒计时、日历、闹钟三种提醒类型。使用后台代理提醒能力后，应用可以被冻结或退出，计时和弹出提醒的功能将被后台系统服务代理。 +OpenHarmony设计了相关的后台活动规范。三方应用退后台后如果没有执行相关的后台任务，会被挂起。而对于某些应用，可能需要在某些指定的时刻，处理一些工作。如购物类应用，可能需要在某些时间点，提醒用户有抢购活动可以参加。此类功能通常的实现是应用使用定时器，在时间达到后，由系统拉起应用，执行相关的任务。但是给应用开放了定时器的功能，可能会造成这个机制被滥用，导致后台被挂起的应用频繁地用定时器唤醒。为了避免恶意的后台活动，同时满足应用的业务诉求，设计了后台代理提醒功能。 +开发者在应用开发时，使用后台代理提醒能力后，应用可以被挂起或退出，计时和弹出提醒的功能将被后台系统服务代理。避免的应用被频繁唤醒的问题，有助于降低功耗。 + +## 提醒实例类型 + +- **倒计时类型**：基于倒计时的提醒功能，适用于短时的计时提醒业务。 + +- **日历类型**：基于日历的提醒功能，适用于较长时间的提醒业务。 + +- **闹钟类型**：基于时钟的提醒功能，应用可以使用此功能，实现闹钟相关的业务。 diff --git a/zh-cn/application-dev/task-management/background-task-overview.md b/zh-cn/application-dev/task-management/background-task-overview.md index a045739051f012c791ca6b093c0afc362ebd7749..c24d818516a8d473bca665304c4d8851f2b531f2 100644 --- a/zh-cn/application-dev/task-management/background-task-overview.md +++ b/zh-cn/application-dev/task-management/background-task-overview.md @@ -1,26 +1,32 @@ # 后台任务概述 -后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。同时，应用可以申请能效资源，保证自己在一段时间内不会被挂起，或者在挂起状态能够正常使用一些资源，例如公共事件、计时器等。 +后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。 +针对应用或业务模块处于后台（无可见界面）时，有需要继续执行或者后续执行的业务，可基于业务类型，申请[短时任务](#短时任务)延迟挂起或者[长时任务](#长时任务)避免进入挂起状态；使用[延迟调度任务](#延迟任务)，执行对实时性要求不高的任务；同时针对特权应用，如果需要更加灵活的配置，可以申请[能效资源](#申请能效资源)。 ## 后台任务类型 -本文描述的后台任务特指应用或业务模块处于后台（无可见界面）时，有需要继续执行或者后续执行的业务。OpenHarmony将后台任务分为三种类型，并执行不同的处理： +OpenHarmony将后台任务分为四种类型，并提供了一个资源申请的扩展功能： - **1. 无后台业务** ：应用或业务模块退到后台后，无任务需要处理。 + **无后台业务** ：应用或业务模块退到后台后，无任务需要处理。 - **2. 短时任务** ：应用或业务模块退到后台后，如果有紧急不可推迟且短时间能完成的任务，如应用退后台要进行数据压缩，不可中断，则使用短时任务申请延迟进入挂起（Suspend）状态。 + **短时任务** ：应用或业务模块退到后台后，如果有紧急不可推迟且短时间能完成的任务，如应用退后台要进行数据压缩，不可中断，则使用短时任务申请延迟进入挂起（Suspend）状态。 - **3. 长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 + **长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 - **4. 能效资源** ：能效资源包括CPU资源、WORK_SCHEDULER资源、软件资源(COMMON_EVENT, TIMER)、硬件资源(GPS, BLUETOOTH)。如果应用或者进程申请了能效资源，那么根据能效资源的类型会拥有相应的特权，例如申请了CPU资源的可以不被挂起，申请了WORK_SCHEDULER后延时任务可以拥有更长的执行时间。 + **延迟任务** ：延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性不高的任务。当满足设定条件的时候，任务会被放入待调度队列，当系统空闲时调度该任务。 + **能效资源** ：能效资源包括CPU资源、WORK_SCHEDULER资源、软件资源(COMMON_EVENT, TIMER)、硬件资源(GPS, BLUETOOTH)。如果应用或者进程申请了能效资源，那么根据能效资源的类型会拥有相应的特权，例如申请了CPU资源的可以不被挂起，申请了WORK_SCHEDULER后延时任务可以拥有更长的执行时间。 + +## 最佳后台任务选择 + +![后台任务选择](public_sys-resources/bgtask_choice.png) ## 短时任务 退到后台的应用有不可中断且短时间能完成的任务时，可以使用短时任务机制。该机制允许应用在后台短时间内完成任务，保障应用业务运行不受后台生命周期管理的影响。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 短时任务仅针对应用的临时任务提供资源使用生命周期保障，限制单次最大使用时长为3分钟，全天使用配额默认为10分钟（具体时长系统根据应用场景和系统状态智能调整）。 @@ -63,9 +69,44 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业 - 长时任务是为了真正在后台长时间执行某个任务，如果一个应用申请了长时任务，但在实际运行过程中，并未真正运行或执行此类任务时，也会被系统检测到并被挂起（Suspend）。 - 一个Ability同一时刻只能申请运行一个长时任务。 -## 能效资源申请 -能效资源可以分为四种，CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLOOTOOTH,AUDIO)。 -应用或进程申请能效资源后能够获得相应特权，例如：申请CPU资源后可以不被挂起；申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加；申请软件、硬件资源后，相关资源在挂起状态下不被代理。 +## 延迟任务 +延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性要求不高的任务，比如设备空闲时候做一次数据学习等场景。当应用申请延迟任务的时候，任务会被放入待调度队列，系统会根据当前状态，如内存、功耗、温度等统一决策最优的调度时机。同时支持任务的持久化，应用退出或者设备重启，设置的任务同样能够被触发。 + +### 延迟任务调度约束 + +延迟调度任务的使用需要遵从如下约束和规则： + +- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[申请能效资源](efficiency-resources-apply-dev-guide.md)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。 +- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。对于通过能效资源接口申请了WORK_SCHEDULER资源的应用，在资源的有效期内，它的延迟任务执行频率不受限制。 + + | 应用分组 | 延迟任务执行频率约束 | + | --------------------|------------------------- | + | 活跃 | 最小间隔2小时 | + | 每日使用 | 最小间隔4小时 | + | 经常使用 | 最小间隔24小时 | + | 不经常使用 | 最小间隔48小时 | + | 受限分组 | 禁止 | + | 未使用分组 | 禁止 | + | [能效资源豁免分组](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9) | 执行频率不受限制 | + +- **WorkInfo设置参数约束** + + - workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。 + + - 至少要设置一个满足的条件。 + + - 重复任务时间间隔至少20分钟，当设置重复任务时间间隔时，必须设置始终重复和重复次数中的一个。 + + - 携带参数信息支持number、string、bool三种类型。 + +## 申请能效资源 +能效资源可以分为四种：CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLUETOOTH,AUDIO)。 + +应用或进程申请能效资源后能够获得相应特权： + * 申请CPU资源后可以不被挂起，直到任务完成。 + * 申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加 + * 申请COMMON_EVENT资源后，应用在后台处于挂起状态时，仍然能够接收到系统公共事件，申请TIMER资源后，应用能够使用定时器执行精确定时任务、 + * 申请硬件资源后，应用在后台被挂起后，依然能够被相关服务唤醒，执行相应的任务。 **表1** 能效资源种类 @@ -84,3 +125,4 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业 - 能效资源申请或者释放可以由进程或者应用发起，由应用发起的资源释放会释放属于它的同类型的所有资源，包括进程申请的资源。例如应用申请了CPU资源,进程申请了CPU和WORK_SCHEDULER资源，当应用释放CPU资源的时候，会将进程的CPU资源一同释放，同时不同类型的WORK_SCHEDULER资源不受影响。由进程发起的资源释放对应用申请的资源没有影响，例如当应用和进程同时申请了CPU，进程发起了CPU资源释放，应用的CPU资源不会被释放。 - 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源，在超时时不会释放资源。例如应用首先申请了10s的CPU资源，然后在第5s的时候申请了持久的CPU资源，那么资源会变成持久的，非持久的CPU资源记录会被持久化的CPU资源记录覆盖，到了第10s的时候资源不会被释放，如果在第8s的时候提前释放了资源，那么会将CPU资源释放，无法单独释放其中非持久的或者持久的CPU资源。 - WORK_SCHEDULER资源只能由应用申请和释放，不能由进程申请和释放。 +- 需要使用能效资源的应用，需要向应用中心提出申请，获取相应的特权。 diff --git a/zh-cn/application-dev/task-management/background-task-dev-guide.md b/zh-cn/application-dev/task-management/continuous-task-dev-guide.md similarity index 50% rename from zh-cn/application-dev/task-management/background-task-dev-guide.md rename to zh-cn/application-dev/task-management/continuous-task-dev-guide.md index b279133c7705c8940cddf4721847b00b50156daa..15a57a485a12c2048f55a2dc10cffc8abe1c9f9b 100644 --- a/zh-cn/application-dev/task-management/background-task-dev-guide.md +++ b/zh-cn/application-dev/task-management/continuous-task-dev-guide.md @@ -1,89 +1,9 @@ -# 后台任务开发指导 - -## 场景介绍 - -应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。如果应用需要更加灵活的配置，可以申请能效资源。常见的使用能效资源的场景有：1.应用保证自己在一个时间段内不被挂起，直到任务完成；2.应用处于挂起状态时仍然需要系统的资源，例如闹钟需要计时器资源；3.延时任务需要不受到执行频率的限制，并且拥有更长的执行时间。 - -在挂起时如果需要单独的某种资源不被代理或者需要更长的延时任务执行时间，可以申请所需的能效资源。 - -## 短时任务 - -### 接口说明 - -**表1** 短时任务主要接口 - -| 接口名 | 描述 | -| ---------------------------------------- | ---------------------------------------- | -| requestSuspendDelay(reason: string, callback: Callback<void>): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | 后台应用申请延迟挂起。
延迟挂起时间一般情况下默认值为180000，低电量时默认值为60000。 | -| getRemainingDelayTime(requestId: number): Promise<number> | 获取应用程序进入挂起状态前的剩余时间。
使用Promise形式返回。 | -| cancelSuspendDelay(requestId: number): void | 取消延迟挂起。 | - - -### 开发步骤 - - -1. 申请延迟挂起 - - ```js - import backgroundTaskManager from '@ohos.backgroundTaskManager'; - - let myReason = 'test requestSuspendDelay'; - let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { - console.info("Request suspension delay will time out."); - }); - - var id = delayInfo.requestId; - console.info("requestId is: " + id); - ``` - - -2. 获取进入挂起前的剩余时间 - - ```js - backgroundTaskManager.getRemainingDelayTime(id).then( res => { - console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); - }).catch( err => { - console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); - }); - ``` - - -3. 取消延迟挂起 - - ```js - backgroundTaskManager.cancelSuspendDelay(id); - ``` - - -### 开发实例 +## 长时任务 -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; -let myReason = 'test requestSuspendDelay'; - -// 申请延迟挂起 -let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { - console.info("Request suspension delay will time out."); -}); - -// 打印延迟挂起信息 -var id = delayInfo.requestId; -var time = delayInfo.actualDelayTime; -console.info("The requestId is: " + id); -console.info("The actualDelayTime is: " + time); - -// 获取应用程序进入挂起状态前的剩余时间 -backgroundTaskManager.getRemainingDelayTime(id).then( res => { - console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); -}).catch( err => { - console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); -}); - -// 取消延迟挂起 -backgroundTaskManager.cancelSuspendDelay(id); -``` +### 场景说明 -## 长时任务 +如果应用需要在后台长时间执行用户可感知的任务，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 +长时任务在后台执行没有时间限制。为了避免该机制被滥用，系统只允许申请有限个数的长时任务类型，同时会有相应的通知提示与长时任务相关联，使用户可感知，并且系统会添加相应的校验机制，确保应用是的确在执行相应的长时任务。 ### 权限 @@ -120,146 +40,35 @@ ohos.permission.KEEP_BACKGROUND_RUNNING 基于FA模型： -1. 新建Api Version 8的工程后，在工程目录中右键选择“new” -> “Ability” -> “Service Ability” 快速创建Service Ability组件。并在config.json文件中配置长时任务权限、后台模式类型，其中Ability类型为“service”。 - - ``` - "module": { - "package": "com.example.myapplication", - "abilities": [ - { - "backgroundModes": [ - "dataTransfer", - "location" - ], // 后台模式类型 - "type": "service" // ability类型为service - } - ], - "reqPermissions": [ - { - "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限 - } - ] - } - ``` - -2. 申请长时任务。 - - ```js - import backgroundTaskManager from '@ohos.backgroundTaskManager'; - import featureAbility from '@ohos.ability.featureAbility'; - import wantAgent from '@ohos.wantAgent'; - - let wantAgentInfo = { - wants: [ - { - bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility" - } - ], - operationType: wantAgent.OperationType.START_ABILITY, - requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] - }; - - // 通过wantAgent模块的getWantAgent方法获取WantAgent对象 - wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { - console.info("Operation startBackgroundRunning succeeded"); - }).catch((err) => { - console.error("Operation startBackgroundRunning failed Cause: " + err); - }); - }); - ``` - -3. 停止长时任务。 - - ```js - import backgroundTaskManager from '@ohos.backgroundTaskManager'; - import featureAbility from '@ohos.ability.featureAbility'; - - backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { - console.info("Operation stopBackgroundRunning succeeded"); - }).catch((err) => { - console.error("Operation stopBackgroundRunning failed Cause: " + err); - }); +基于FA的Service Ability使用，参考[ServiceAbility开发指导](../ability/fa-serviceability.md)。 - ``` +当不需要与后台执行的长时任务交互时，可以采用startAbility()方法启动Service Ability。并在Service Ability的onStart回调方法中，调用长时任务的申请接口，声明此服务需要在后台长时运行。当任务执行完，再调用长时任务取消接口，及时释放资源。 -基于Stage模型： +当需要与后台执行的长时任务交互时（如播放音乐等）。可以采用connectAbility()方法启动并连接Service Ability。在获取到服务的代理对象后，与服务进行通信，控制长时任务的申请和取消。 -1. 新建Api Version 9的工程后，在工程目录中右键选择“New” -> “Ability” 快速创建Ability组件。并在module.json5文件中配置长时任务权限、后台模式类型。 +1、新建Api Version 8的工程后，在工程目录中右键选择“new” -> “Ability” -> “Service Ability” 快速创建Service Ability组件。并在config.json文件中配置长时任务权限、后台模式类型，其中Ability类型为“service”。 - ``` - "module": { - "abilities": [ +``` +"module": { + "package": "com.example.myapplication", + "abilities": [ { - "backgroundModes": [ + "backgroundModes": [ "dataTransfer", "location" - ], // 后台模式类型 + ], // 后台模式类型 + "type": "service" // ability类型为service } - ], - "requestPermissions": [ + ], + "reqPermissions": [ { - "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限 + "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限 } - ] - } - ``` - -2. 申请长时任务。 - - ```ts - import backgroundTaskManager from '@ohos.backgroundTaskManager'; - import wantAgent from '@ohos.wantAgent'; - - let wantAgentInfo = { - wants: [ - { - bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility" - } - ], - operationType: wantAgent.OperationType.START_ABILITY, - requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] - }; - - // 通过wantAgent模块的getWantAgent方法获取WantAgent对象 - wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(this.context, - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { - console.info("Operation startBackgroundRunning succeeded"); - }).catch((err) => { - console.error("Operation startBackgroundRunning failed Cause: " + err); - }); - }); - ``` - -3. 停止长时任务。 - - ```ts - import backgroundTaskManager from '@ohos.backgroundTaskManager'; - - backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { - console.info("Operation stopBackgroundRunning succeeded"); - }).catch((err) => { - console.error("Operation stopBackgroundRunning failed Cause: " + err); - }); - - ``` - - -### 开发实例 - -基于FA模型： - -基于FA的Service Ability使用，参考[ServiceAbility开发指导](../ability/fa-serviceability.md)。 - -当不需要与后台执行的长时任务交互时，可以采用startAbility()方法启动Service Ability。并在Service Ability的onStart回调方法中，调用长时任务的申请接口，声明此服务需要在后台长时运行。当任务执行完，再调用长时任务取消接口，及时释放资源。 + ] +} +``` -当需要与后台执行的长时任务交互时（如播放音乐等）。可以采用connectAbility()方法启动并连接Service Ability。在获取到服务的代理对象后，与服务进行通信，控制长时任务的申请和取消。 +2、在Service Ability调用长时任务的申请和取消接口。 ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; @@ -367,13 +176,117 @@ export default { 基于Stage模型： Stage模型的相关信息参考[Stage模型综述](../ability/stage-brief.md)。 -当应用需要在后台执行长时任务时，可以通过Call的方式在后台创建并运行Ability。使用方式参考[Call调用开发指导](../ability/stage-call.md)。 + +1、新建Api Version 9的工程后，在工程目录中右键选择“New” -> “Ability” 快速创建Ability组件。并在module.json5文件中配置长时任务权限、后台模式类型。 + +``` +"module": { + "abilities": [ + { + "backgroundModes": [ + "dataTransfer", + "location" + ], // 后台模式类型 + } + ], + "requestPermissions": [ + { + "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限 + } + ] +} +``` + +2、在应用内执行长时任务时，由于元能力启动管控规则限制，不支持同应用通过startAbilityByCall的形式在后台创建并运行Ability。可以直接在page中，执行相应的代码。Stage模型的Ability使用参考[Ability开发指导](../ability/stage-ability.md)。 + +```ts +import wantAgent from '@ohos.wantAgent'; +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +@Entry +@Component +struct Index { + @State message: string = 'test' + // 通过getContext方法，来获取page所在的Ability上下文。 + private context: any = getContext(this) + + startContinuousTask() { + let wantAgentInfo = { + // 点击通知后，将要执行的动作列表 + wants: [ + { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility", + } + ], + // 点击通知后，动作类型 + operationType: wantAgent.OperationType.START_ABILITY, + // 使用者自定义的一个私有值 + requestCode: 0, + // 点击通知后，动作执行属性 + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] + }; + + // 通过wantAgent模块的getWantAgent方法获取WantAgent对象 + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + backgroundTaskManager.startBackgroundRunning(this.context, + backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { + console.info("Operation startBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation startBackgroundRunning failed Cause: " + err); + }); + }); + } + + stopContinuousTask() { + backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { + console.info("Operation stopBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation stopBackgroundRunning failed Cause: " + err); + }); + } + + build() { + Row() { + Column() { + Text("Index") + .fontSize(50) + .fontWeight(FontWeight.Bold) + + Button() { Text('申请长时任务').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) + .margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40) + .onClick(() => { + // 通过按钮申请长时任务 + this.startContinuousTask(); + + // 此处执行具体的长时任务逻辑，如放音等。 + }) + + Button() { Text('取消长时任务').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) + .margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40) + .onClick(() => { + // 此处结束具体的长时任务的执行 + + // 通过按钮取消长时任务 + this.stopContinuousTask(); + }) + } + .width('100%') + } + .height('100%') + } +} +``` + +3、当需要跨设备或者跨应用在后台执行长时任务时，可以通过Call的方式在后台创建并运行Ability。使用方式参考[Call调用开发指导](../ability/stage-call.md)。 ```ts import Ability from '@ohos.application.Ability' import backgroundTaskManager from '@ohos.backgroundTaskManager'; import wantAgent from '@ohos.wantAgent'; +const MSG_SEND_METHOD: string = 'CallSendMsg' + let mContext = null; function startContinuousTask() { @@ -382,7 +295,7 @@ function startContinuousTask() { wants: [ { bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility" + abilityName: "com.example.myapplication.MainAbility", } ], // 点击通知后，动作类型 @@ -436,15 +349,16 @@ class MySequenceable { function sendMsgCallback(data) { console.info('BgTaskAbility funcCallBack is called ' + data) - let receivedData = new Mysequenceable(0, "") + let receivedData = new MySequenceable(0, "") data.readSequenceable(receivedData) console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`) + // 可以根据Caller端发送的序列化数据的str值，执行不同的方法。 if (receivedData.str === 'start_bgtask') { startContinuousTask() } else if (receivedData.str === 'stop_bgtask') { stopContinuousTask(); } - return new Mysequenceable(10, "Callee test"); + return new MySequenceable(10, "Callee test"); } export default class BgTaskAbility extends Ability { @@ -467,7 +381,7 @@ export default class BgTaskAbility extends Ability { onWindowStageCreate(windowStage) { console.info("[Demo] BgTaskAbility onWindowStageCreate") - windowStage.loadContent("pages/second").then((data)=> { + windowStage.loadContent("pages/index").then((data)=> { console.info(`load content succeed with data ${JSON.stringify(data)}`) }).catch((error)=>{ console.error(`load content failed with error ${JSON.stringify(error)}`) @@ -488,95 +402,8 @@ export default class BgTaskAbility extends Ability { }; ``` -## 能效资源申请 - -### 接口说明 - -**表1** 能效资源申请主要接口 - -| 接口名 | 描述 | -| ---------------------------------------- | ---------------------------------------- | -| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | 申请能效资源。 | -| resetAllEfficiencyResources():void | 释放申请的能效资源。 | - - -### 开发步骤 - - -1. 申请能效资源 - -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; - -let request = { - resourceTypes: backgroundTaskManager.ResourceType.CPU, - isApply: true, - timeOut: 0, - reason: "apply", - isPersist: true, - isProcess: true, -}; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); -``` - -2. 释放申请的部分资源 - -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; - -let request = { - resourceTypes: backgroundTaskManager.ResourceType.CPU, - isApply: false, - timeOut: 0, - reason: "reset", -}; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); -``` - -3. 释放申请的所有资源 - -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; - -backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); -``` - -### 开发实例 - -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; - -// 申请能效资源 -let request = { - resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT | - backgroundTaskManager.ResourceType.TIMER, - isApply: true, - timeOut: 0, - reason: "apply", - isPersist: true, - isProcess: true, -}; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); - -// 释放部分资源 -request = { - resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT, - isApply: false, - timeOut: 0, - reason: "reset", -}; -res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); - -// 释放全部资源 -backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); -``` - ## 相关实例 基于后台任务管理，有以下相关实例可供参考： -- [`BackgroundTaskManager`：后台任务管理（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ResourcesSchedule/BackgroundTaskManager) \ No newline at end of file +- [`BackgroundTaskManager`：后台任务管理（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ResourcesSchedule/BackgroundTaskManager) \ No newline at end of file diff --git a/zh-cn/application-dev/task-management/efficiency-resources-apply-dev-guide.md b/zh-cn/application-dev/task-management/efficiency-resources-apply-dev-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..ebdd94a0c1a20876b854d16a19725ad854c773f2 --- /dev/null +++ b/zh-cn/application-dev/task-management/efficiency-resources-apply-dev-guide.md @@ -0,0 +1,53 @@ +## 申请能效资源 + +### 场景说明 + +在实际的系统中，存在一些重要性高的系统应用，虽然此类应用相比普通应用具有一定的特权，但为了进一步平衡系统的功耗开销，这些应用同样需要支持在后台可被挂起。但对于系统特权应用，为了避免挂起后重要功能受到影响，提供了独立的能效资源申请接口，使这些特权应用可以在后台执行一些特殊的任务和使用特定的系统资源，例如在被挂起期间如果仍然希望能够收到系统公共事件，可以使用能效资源接口向系统申请使用公共事件资源。 + +对于需要升级为特权应用的，开发者需要合理评估自己的业务诉求，向应用中心提出申请。 + +### 接口说明 + +**表1** 申请能效资源主要接口 + +| 接口名 | 描述 | +| ---------------------------------------- | ---------------------------------------- | +| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | 申请能效资源。 | +| resetAllEfficiencyResources():void | 释放申请的能效资源。 | + + +### 开发步骤 + +1、当特权应用需要在后台使用特殊资源时。向系统申请目标资源。 + +2、当资源使用完毕，需要及时释放。支持释放部分资源或全部资源。 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +// 申请能效资源 +let request = { + resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT | + backgroundTaskManager.ResourceType.TIMER, + isApply: true, + timeOut: 0, + reason: "apply", + isPersist: true, + isProcess: true, +}; +let res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("the result of request is: " + res); + +// 释放部分资源 +request = { + resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT, + isApply: false, + timeOut: 0, + reason: "reset", +}; +res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("the result of request is: " + res); + +// 释放全部资源 +backgroundTaskManager.resetAllEfficiencyResources(); +``` diff --git a/zh-cn/application-dev/task-management/public_sys-resources/bgtask_choice.png b/zh-cn/application-dev/task-management/public_sys-resources/bgtask_choice.png new file mode 100644 index 0000000000000000000000000000000000000000..4f1fd6eefab0302ba4f936828adefbedf8f6c1f8 Binary files /dev/null and b/zh-cn/application-dev/task-management/public_sys-resources/bgtask_choice.png differ diff --git a/zh-cn/application-dev/task-management/transient-task-dev-guide.md b/zh-cn/application-dev/task-management/transient-task-dev-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..d27a88e576e312626e1c810ab9b90253b1223408 --- /dev/null +++ b/zh-cn/application-dev/task-management/transient-task-dev-guide.md @@ -0,0 +1,84 @@ +## 短时任务 + +### 场景说明 + +当应用退到后台默认有6到12秒的运行时长，超过该时间后，系统会将应用置为挂起状态。对于绝大多数应用，6到12秒的时间，足够执行一些重要的任务，但如果应用需要更多的时间，可以通过短时任务接口，扩展应用的执行时间。 +建议不要等到应用退后台后，才调用requestSuspendDelay方法申请延迟挂起，而是应该在执行任何的耗时操作前，都应该调用该接口，向系统申明扩展应用的执行时间。 +当应用在前台时，使用requestSuspendDelay方法，不会影响应用的短时任务配额。 + +由于每个应用每天的短时任务配额时间有限，当执行完耗时任务后，应当及时取消延迟挂起的申请。 + +一些典型的耗时任务有，需要保存一些状态数据到本地数据库，需要打开和处理一个大型文件，需要同步一些数据到应用的云端服务器等。 + + +### 接口说明 + + +**表1** 短时任务主要接口 + +| 接口名 | 描述 | +| ---------------------------------------- | ---------------------------------------- | +| requestSuspendDelay(reason: string, callback: Callback<void>): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | 后台应用申请延迟挂起。
延迟挂起时间一般情况下默认值为180000，低电量时默认值为60000。 | +| getRemainingDelayTime(requestId: number): Promise<number> | 获取应用程序进入挂起状态前的剩余时间。
使用Promise形式返回。 | +| cancelSuspendDelay(requestId: number): void | 取消延迟挂起。 | + + +### 开发步骤 + +1、当应用需要开始执行一个耗时的任务时。调用短时任务申请接口，并且在任务执行完后，调用短时任务取消接口。 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +let delayInfo; +let id; + +// 申请延迟挂起 +function requestSuspendDelay() { + let myReason = 'test requestSuspendDelay'; + delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { + console.info("Request suspension delay will time out."); + // 此回调函数执行，表示应用的延迟挂起申请即将超时，应用需要执行一些清理和标注工作。 + }); + + id = delayInfo.requestId; + console.info("requestId is: " + id); +} + +// 获取进入挂起前的剩余时间 +function getRemainingDelayTime() { + let delayTime = 0; + backgroundTaskManager.getRemainingDelayTime(id).then((res) => { + console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); + delayTime = res; + }).catch((err) => { + console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); + }); + return delayTime; +} + +// 取消延迟挂起 +function cancelSuspendDelay() { + backgroundTaskManager.cancelSuspendDelay(id); +} + +function performingLongRunningTask() { + // 在执行具体的耗时任务前，调用短时任务申请接口。向系统申请延迟挂起，延长应用的后台执行时间。 + requestSuspendDelay(); + + // 通过剩余时间查询接口，获取可用时间配额。 + let delayTime = getRemainingDelayTime(); + + if (delayTime < 0) { // 如果时间配置少于一定的大小，考虑取消此次耗时操作。 + // 处理短时任务配额时间不够的场景 + + cancelSuspendDelay(); + return; + } + + // 此处执行具体的耗时任务。 + + // 耗时任务执行完，调用短时任务取消接口，避免配额浪费。 + cancelSuspendDelay(); +} +``` diff --git a/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md b/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md index 300086d76e88216b98d0e7f67b0a112ec95b7913..789001234202aa2ddc3a6c303a51883cfcea5eca 100644 --- a/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md +++ b/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md @@ -2,7 +2,7 @@ ## 场景介绍 -应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时间。延迟任务调度约束见[延迟任务调度概述](./work-scheduler-overview.md)。 +应用要执行对实时性要求不高的任务或持久性任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时间。延迟任务调度约束见[延迟任务调度约束](./background-task-overview.md#延迟任务调度约束)。 ## 接口说明 @@ -34,7 +34,7 @@ isLastWorkTimeOut(workId: number): Promise\;| 获取上次任务是否 **表2** WorkInfo包含参数 -> **说明：** WorkInfo设置参数约束见[延迟任务调度概述](./work-scheduler-overview.md) +> **说明：** WorkInfo设置参数约束见[延迟任务调度约束](./background-task-overview.md#延迟任务调度约束) 参数名| 类型 |描述 ---------------------------------------------------------|-----------------------------------------|--------------------------------------------------------- @@ -61,141 +61,114 @@ onWorkStop(work: WorkInfo): void | 延迟调度任务结束回调 ### 开发步骤 -**开发对应的Extension** - - import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; - - export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { - onWorkStart(workInfo) { - console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); - } - onWorkStop(workInfo) { - console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); - } - } +1、开发对应的ExtensionAbility，用于回调执行具体的延迟任务。关于ExtensionAbility的介绍，参考[ExtensionAbility机制](../ability/stage-brief.md#extensionability机制)。 +```ts +import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; -**注册延迟任务** - - import workScheduler from '@ohos.workScheduler'; - - let workInfo = { - workId: 1, - batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, - isRepeat: false, - isPersisted: true, - bundleName: "com.example.myapplication", - abilityName: "MyExtension", - parameters: { - mykey0: 1, - mykey1: "string value", - mykey2: true, - mykey3: 1.5 - } +export default class MyExtension extends WorkSchedulerExtensionAbility { + onWorkStart(workInfo) { + console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); } - var res = workScheduler.startWork(workInfo); - console.info("workschedulerLog res:" + res); - - -**取消延迟任务** - - - import workScheduler from '@ohos.workScheduler'; - - let workInfo = { - workId: 1, - batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, - isRepeat: false, - isPersisted: true, - bundleName: "com.example.myapplication", - abilityName: "MyExtension", - parameters: { - mykey0: 1, - mykey1: "string value", - mykey2: true, - mykey3: 1.5 - } + onWorkStop(workInfo) { + console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); } - var res = workScheduler.stopWork(workInfo, false); - console.info("workschedulerLog res:" + res); - - -**获取指定延迟任务** +} +``` -1.Callback写法 - workScheduler.getWorkStatus(50, (err, res) => { - if (err) { - console.info('workschedulerLog getWorkStatus failed, because:' + err.code); - } else { - for (let item in res) { - console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]); - } - } - }); +2、注册延迟任务 +```ts +import workScheduler from '@ohos.workScheduler'; -2.Promise写法 +let workInfo = { + workId: 1, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension", + parameters: { + mykey0: 1, + mykey1: "string value", + mykey2: true, + mykey3: 1.5 + } +} +var res = workScheduler.startWork(workInfo); +console.info("workschedulerLog res:" + res); +``` - workScheduler.getWorkStatus(50).then((res) => { - for (let item in res) { - console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); - } - }).catch((err) => { - console.info('workschedulerLog getWorkStatus failed, because:' + err.code); - }) +3、取消延迟任务 -**获取所有延迟任务** +```ts +import workScheduler from '@ohos.workScheduler'; -1.Callback写法 +let workInfo = { + workId: 1, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension", + parameters: { + mykey0: 1, + mykey1: "string value", + mykey2: true, + mykey3: 1.5 + } +} +var res = workScheduler.stopWork(workInfo, false); +console.info("workschedulerLog res:" + res); +``` - workScheduler.obtainAllWorks((err, res) =>{ - if (err) { - console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); - } else { - console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); - } - }); -2.Promise写法 +4、获取指定延迟任务 - workScheduler.obtainAllWorks().then((res) => { - console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); - }).catch((err) => { - console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); - }) +```ts +workScheduler.getWorkStatus(50).then((res) => { + for (let item in res) { + console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); + } +}).catch((err) => { + console.info('workschedulerLog getWorkStatus failed, because:' + err.code); +}) +``` -**停止并清除任务** - let res = workScheduler.stopAndClearWorks(); - console.info("workschedulerLog res:" + res); +5、获取所有延迟任务 -**判断上次执行是否超时** +```ts +workScheduler.obtainAllWorks().then((res) => { + console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); +}).catch((err) => { + console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); +}) +``` -1.Callback写法 +6、停止并清除任务 - workScheduler.isLastWorkTimeOut(500, (err, res) =>{ - if (err) { - console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code); - } else { - console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); - } - }); +```ts +let res = workScheduler.stopAndClearWorks(); +console.info("workschedulerLog res:" + res); +``` -2.Promise写法 +7、判断上次执行是否超时 - workScheduler.isLastWorkTimeOut(500) - .then(res => { - console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); - }) - .catch(err => { - console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code); - }); - }) +```ts +workScheduler.isLastWorkTimeOut(500) + .then(res => { + console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); + }) + .catch(err => { + console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code); + }); +``` ## 相关实例 基于延迟任务调度，有以下相关实例可供参考： -- [`WorkScheduler`：延迟任务调度（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ResourcesSchedule/WorkScheduler) \ No newline at end of file +- [`WorkScheduler`：延迟任务调度（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/ResourcesSchedule/WorkScheduler) \ No newline at end of file diff --git a/zh-cn/application-dev/task-management/work-scheduler-overview.md b/zh-cn/application-dev/task-management/work-scheduler-overview.md deleted file mode 100644 index da6a08d7881862a29ac15069cabfe5c47cbe77d9..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/task-management/work-scheduler-overview.md +++ /dev/null @@ -1,34 +0,0 @@ -# 延迟任务调度概述 - -延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性不高的任务。当满足设定条件的时候，任务会被放入待调度队列，当系统空闲时调度该任务。 - -## 使用说明 - -应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时机。 - -## 延迟任务调度约束 - -延迟调度任务的使用需要遵从如下约束和规则： - -- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[能效资源申请接口](background-task-overview.md#能效资源申请)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。 -- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。对于通过能效资源接口申请了WORK_SCHEDULER资源的应用，在资源的有效期内，它的延迟任务执行频率不受限制。 - -应用分组 | 延迟任务执行频率约束 ---------------------|------------------------- -活跃 | 最小间隔2小时 -每日使用 | 最小间隔4小时 -经常使用 | 最小间隔24小时 -不经常使用 | 最小间隔48小时 -受限分组 | 禁止 -未使用分组 | 禁止 -[能效资源豁免分组](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9) | 执行频率不受限制 - -- **WorkInfo设置参数约束** - -（1） workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。 - -（2）至少要设置一个满足的条件。 - -（3）重复任务时间间隔至少20分钟，当设置重复任务时间间隔时，必须设置始终重复和重复次数中的一个。 - -（4）携带参数信息支持number、string、bool三种类型。 \ No newline at end of file diff --git a/zh-cn/application-dev/telephony/cellular-network-signal-info.md b/zh-cn/application-dev/telephony/cellular-network-signal-info.md index 8c308e38578da07e19b7fe129fa0af7f47db0ca4..2e37ff8134208b978720953229ee445d8cd922e6 100644 --- a/zh-cn/application-dev/telephony/cellular-network-signal-info.md +++ b/zh-cn/application-dev/telephony/cellular-network-signal-info.md @@ -53,4 +53,4 @@ radio模块提供了获取当前网络信号信息的方法。observer模块为 ## 相关实例 针对蜂窝网络数据开发，有以下相关实例可供参考： -- [`MobileNetwork`：蜂窝数据（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/MobileNetwork) \ No newline at end of file +- [`MobileNetwork`：蜂窝数据（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/MobileNetwork) \ No newline at end of file diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_00000011.gif b/zh-cn/application-dev/ui/figures/zh-cn_image_00000011.gif new file mode 100644 index 0000000000000000000000000000000000000000..9dd23bf2e649eb1e9c7a71281a8f26dcd90d6f26 Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_00000011.gif differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001176075554.gif b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001176075554.gif index 7d8da86f2f1cf71ca9bc5d6cb65564bb64ae5fd1..16e7ff213bd5caf5a9802001d3ced2996c66e0bc 100644 Binary files a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001176075554.gif and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001176075554.gif differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001227701867.gif b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001227701867.gif index 9e313e1e87059572aa036b06881381da7b070641..0cbcaa3ff368a2a2ad63c8729acc0f66ae874437 100644 Binary files a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001227701867.gif and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001227701867.gif differ diff --git a/zh-cn/application-dev/ui/ts-resource-access.md b/zh-cn/application-dev/ui/ts-resource-access.md index 5ab95b5eba3fbf1a325dea0b9f6fdd7a10ba6193..a2ea1141108398203160e8fa752d1cc4727c5889 100644 --- a/zh-cn/application-dev/ui/ts-resource-access.md +++ b/zh-cn/application-dev/ui/ts-resource-access.md @@ -151,4 +151,4 @@ plural.json文件的内容如下： 针对访问应用资源，有以下相关实例可供参考： -- [`ResourceManager`：资源管理器（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/ResourceManager) +- [`ResourceManager`：资源管理器（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/common/ResourceManager) diff --git a/zh-cn/application-dev/ui/ui-js-building-ui-event.md b/zh-cn/application-dev/ui/ui-js-building-ui-event.md index 9c09ebb86f3b0a6177307deb7d7cd6b5ebca2bc2..e1aa990223059ba6190c147f6753e5fc48de85d7 100755 --- a/zh-cn/application-dev/ui/ui-js-building-ui-event.md +++ b/zh-cn/application-dev/ui/ui-js-building-ui-event.md @@ -48,16 +48,18 @@ longpress：用户在相同位置长时间保持与屏幕接触。 ```css /* xxx.css */ .container { + width: 100%; + height: 100%; flex-direction: column; justify-content: center; align-items: center; } .text-container { - margin-top: 10px; + margin-top: 30px; flex-direction: column; - width: 750px; - height: 50px; - background-color: #09ba07; + width: 600px; + height: 70px; + background-color: #0000FF; } .text-style { width: 100%; @@ -99,3 +101,5 @@ export default { }, } ``` + +![zh-cn_image_00000011](figures/zh-cn_image_00000011.gif) \ No newline at end of file diff --git a/zh-cn/application-dev/ui/ui-js-components-canvas.md b/zh-cn/application-dev/ui/ui-js-components-canvas.md index c46363421b6eddd6b9c6376feb171017c0f39126..9410a9d4ceda10a4fd7cb2169ca71afe7ec51a6c 100644 --- a/zh-cn/application-dev/ui/ui-js-components-canvas.md +++ b/zh-cn/application-dev/ui/ui-js-components-canvas.md @@ -118,8 +118,6 @@ import prompt from '@system.prompt'; export default { data:{ dataURL:null, - antialia: false, - porc:'open', }, onShow(){ let el = this.$refs.canvas1; diff --git a/zh-cn/application-dev/ui/ui-js-components-marquee.md b/zh-cn/application-dev/ui/ui-js-components-marquee.md index f711b61e755f78da710ee8d41f987845a4b78fe8..f755e9807c056a25788fb999e9826f9c80f8bf67 100644 --- a/zh-cn/application-dev/ui/ui-js-components-marquee.md +++ b/zh-cn/application-dev/ui/ui-js-components-marquee.md @@ -79,7 +79,7 @@ marquee通过color和font-weight属性设置跑马灯中文本的颜色、字体
- It's a racing lamp + Life is a journey, not the destination.
@@ -128,7 +128,9 @@ button{ // xxx.js export default { private: { - loopval: -1, scroll: 10, isleft: "left", + loopval: -1, + scroll: 10, + isleft: "left", }, onInit(){ }, @@ -163,7 +165,7 @@ export default {
- It's a racing lamp + Life is a journey, not the destination.
diff --git a/zh-cn/application-dev/ui/ui-js-components-search.md b/zh-cn/application-dev/ui/ui-js-components-search.md index 5c712126e14d8c24c396dd84808e4bdcae395564..85bd2730eec8c3f7a8391c608f9f42f179407ed4 100644 --- a/zh-cn/application-dev/ui/ui-js-components-search.md +++ b/zh-cn/application-dev/ui/ui-js-components-search.md @@ -62,7 +62,7 @@ ## 添加样式 -通过color、placeholder和caret-color样式来设置搜索框的文本颜色、提示文本颜色和光标颜色。 +通过color、placeholder-color和caret-color样式来设置搜索框的文本颜色、提示文本颜色和光标颜色。 ```html @@ -84,7 +84,9 @@ background-color: #F1F3F5; } search{ - color: black; placeholder-color: black; caret-color: red; + color: black; + placeholder-color: black; + caret-color: red; } ``` diff --git a/zh-cn/application-dev/ui/ui-ts-components-web.md b/zh-cn/application-dev/ui/ui-ts-components-web.md index 6a72cc647601e6f072b59a61b58805df0d16c0b8..6f4acc31caca52b4bab2e97e9913922dd86904fa 100644 --- a/zh-cn/application-dev/ui/ui-ts-components-web.md +++ b/zh-cn/application-dev/ui/ui-ts-components-web.md @@ -198,6 +198,6 @@ struct WebComponent { 针对Web开发，有以下相关实例可供参考： -- [`Web`：Web（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ETSUI/Web) +- [`Web`：Web（ArkTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/ETSUI/Web) -- [Web组件加载本地H5小程序（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/WebComponent) \ No newline at end of file +- [Web组件加载本地H5小程序（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/WebComponent) \ No newline at end of file diff --git a/zh-cn/application-dev/windowmanager/application-window-stage.md b/zh-cn/application-dev/windowmanager/application-window-stage.md index 661d379df7f0e29626aab080c37eeb092a68a67a..51b969f34e611a7a23ee8f115389590737b11a11 100644 --- a/zh-cn/application-dev/windowmanager/application-window-stage.md +++ b/zh-cn/application-dev/windowmanager/application-window-stage.md @@ -396,4 +396,4 @@ class MainAbility extends Ability { 针对window开发（Stage模型），有以下相关实例可供参考： -- [`Window`：窗口（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Graphics/Window) \ No newline at end of file +- [`Window`：窗口（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Graphics/Window) \ No newline at end of file diff --git a/zh-cn/device-dev/driver/driver-peripherals-usb-des.md b/zh-cn/device-dev/driver/driver-peripherals-usb-des.md index bdb313049f79ebdcb397c7668b35cff66ecaa9cb..c7dc8513b9e69d1dc158868e95350200c7952c6c 100644 --- a/zh-cn/device-dev/driver/driver-peripherals-usb-des.md +++ b/zh-cn/device-dev/driver/driver-peripherals-usb-des.md @@ -36,51 +36,51 @@ USB驱动模型Host侧开放的API接口功能，参考USB Host驱动模型图 | int32_t UsbInitHostSdk(struct UsbSession \*\*session); | USB主机端驱动开发工具包初始化 | | int32_t UsbExitHostSdk(const struct UsbSession
\*session); | USB主机端驱动开发工具包退出 | | const struct UsbInterface \*UsbClaimInterface(const
struct UsbSession \*session, uint8_t busNum, uint8_t
usbAddr, uint8_t interfaceIndex); | 获取USB接口对象 | -| int UsbReleaseInterface(const struct UsbInterface
\*interfaceObj); | 释放USB接口对象 | -| int UsbAddOrRemoveInterface(const struct UsbSession
\*session, uint8_t busNum, uint8_t usbAddr, uint8_t
interfaceIndex, UsbInterfaceStatus status); | 增加移除接口 | +| int32_t UsbReleaseInterface(const struct UsbInterface
\*interfaceObj); | 释放USB接口对象 | +| int32_t UsbAddOrRemoveInterface(const struct UsbSession
\*session, uint8_t busNum, uint8_t usbAddr, uint8_t
interfaceIndex, UsbInterfaceStatus status); | 增加移除接口 | | UsbInterfaceHandle \*UsbOpenInterface(const struct
UsbInterface \*interfaceObj); | 打开USB对象接口 | | int32_t UsbCloseInterface(const UsbInterfaceHandle
\*interfaceHandle); | 关闭USB接口对象 | | int32_t UsbSelectInterfaceSetting(const
UsbInterfaceHandle \*interfaceHandle, uint8_t
settingIndex, struct UsbInterface \*\*interfaceObj); | 设置可选配置 | | int32_t UsbGetPipeInfo(const UsbInterfaceHandle
\*interfaceHandle, uint8_t settingIndex, uint8_t pipeId,
struct UsbPipeInfo \*pipeInfo); | 获取指定可选设置的管道信息 | | int32_t UsbClearInterfaceHalt(const
UsbInterfaceHandle \*interfaceHandle, uint8_t
pipeAddress); | 清除指定索引的管道状态 | -| struct UsbRequest \*UsbAllocRequest(const
UsbInterfaceHandle \*interfaceHandle, int isoPackets
, int length); | 分配请求对象 | -| int UsbFreeRequest(const struct UsbRequest
\*request); | 释放请求对象 | -| int UsbSubmitRequestAsync(const struct UsbRequest
\*request); | 发送异步请求 | +| struct UsbRequest \*UsbAllocRequest(const
UsbInterfaceHandle \*interfaceHandle, int32_t isoPackets
, int32_t length); | 分配请求对象 | +| int32_t UsbFreeRequest(const struct UsbRequest
\*request); | 释放请求对象 | +| int32_t UsbSubmitRequestAsync(const struct UsbRequest
\*request); | 发送异步请求 | | int32_t UsbFillRequest(const struct UsbRequest
\*request, const UsbInterfaceHandle \*interfaceHandle,
const struct UsbRequestParams \*params); | 填充请求 | -| sint UsbCancelRequest(const struct UsbRequest
\*request); | 取消异步请求 | -| int UsbSubmitRequestSync(const struct UsbRequest
\*request); | 发送同步请求 | +| int32_t UsbCancelRequest(const struct UsbRequest
\*request); | 取消异步请求 | +| int32_t UsbSubmitRequestSync(const struct UsbRequest
\*request); | 发送同步请求 | **表2** usb_raw_api.h | 接口名称 | 功能描述 | | -------- | -------- | -| int UsbRawInit(struct UsbSession \*\*session); | USB驱动开发工具包专家模式初始化 | -| int UsbRawExit(const struct UsbSession \*session); | USB驱动开发工具包专家模式退出 | +| int32_t UsbRawInit(struct UsbSession \*\*session); | USB驱动开发工具包专家模式初始化 | +| int32_t UsbRawExit(const struct UsbSession \*session); | USB驱动开发工具包专家模式退出 | | UsbRawHandle \*UsbRawOpenDevice(const struct
UsbSession \*session, uint8_t busNum, uint8_t
usbAddr); | 打开USB设备对象 | -| int UsbRawCloseDevice(const UsbRawHandle
\*devHandle); | 关闭USB设备对象 | -| int UsbRawSendControlRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbControlRequestData
\*requestData); | 执行同步控制传输 | -| int UsbRawSendBulkRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步批量传输 | -| int UsbRawSendInterruptRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步中断传输 | -| int UsbRawGetConfigDescriptor(const UsbRawDevice
\*rawDev, uint8_t configIndex, struct
UsbRawConfigDescriptor \*\*config); | 获取给定设备指定ID的设备配置描述符 | +| int32_t UsbRawCloseDevice(const UsbRawHandle
\*devHandle); | 关闭USB设备对象 | +| int32_t UsbRawSendControlRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbControlRequestData
\*requestData); | 执行同步控制传输 | +| int32_t UsbRawSendBulkRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步批量传输 | +| int32_t UsbRawSendInterruptRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步中断传输 | +| int32_t UsbRawGetConfigDescriptor(const UsbRawDevice
\*rawDev, uint8_t configIndex, struct
UsbRawConfigDescriptor \*\*config); | 获取给定设备指定ID的设备配置描述符 | | void UsbRawFreeConfigDescriptor(const struct
UsbRawConfigDescriptor \*config); | 释放配置描述符内存空间 | -| int UsbRawGetConfiguration(const UsbRawHandle
\*devHandle, int \*config); | 获取当前激活配置 | -| int UsbRawSetConfiguration(const UsbRawHandle
\*devHandle, int config); | 设置当前激活配置 | -| int UsbRawGetDescriptor(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawDescriptorParam \*param, const unsigned char
\*data); | 获取描述符信息 | +| int32_t UsbRawGetConfiguration(const UsbRawHandle
\*devHandle, int32_t \*config); | 获取当前激活配置 | +| int32_t UsbRawSetConfiguration(const UsbRawHandle
\*devHandle, int32_t config); | 设置当前激活配置 | +| int32_t UsbRawGetDescriptor(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawDescriptorParam \*param, const unsigned char
\*data); | 获取描述符信息 | | UsbRawDevice \*UsbRawGetDevice(const UsbRawHandle
\*devHandle); | 由设备句柄获取设备指针 | -| int UsbRawGetDeviceDescriptor(const UsbRawDevice
\*rawDev, struct
UsbDeviceDescriptor \*desc); | 获取给定设备的USB设备描述符 | -| int UsbRawClaimInterface(const UsbRawHandle
\*devHandle, int
interfaceNumber); | 声明给定设备句柄上的接口 | -| int UsbRawReleaseInterface(const UsbRawHandle
\*devHandle, in
t interfaceNumber); | 释放之前声明的接口 | -| int UsbRawResetDevice(const UsbRawHandle
\*devHandle); | 复位设备 | -| struct UsbRawRequest \*UsbRawAllocRequest(const
UsbRawHandle
\*devHandle, int isoPackets, int length); | 分配一个带有指定数量的同步包描述符的传输请求 | -| int UsbRawFreeRequest(const struct UsbRawRequest
\*request); | 释放之前分配的传输请求 | -| int UsbRawFillBulkRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充批量传输请求所需信息 | -| int UsbRawFillControlSetup(const unsigned char \*setup,
const struct UsbControlRequestData \*requestData); | 填充控制传输设置包所需信息 | -| int UsbRawFillControlRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充控制传输请求所需信息 | -| int UsbRawFillInterruptRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充中断传输请求所需信息 | -| int UsbRawFillIsoRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充同步传输（Isochronous Transfers）请求所需信息 | -| int UsbRawSubmitRequest(const struct UsbRawRequest
\*request); | 提交一个传输请求 | -| int UsbRawCancelRequest(const struct UsbRawRequest
\*request); | 取消一个传输请求 | -| int UsbRawHandleRequests(const UsbRawHandle
\*devHandle); | 传输请求事件完成处理 | +| int32_t UsbRawGetDeviceDescriptor(const UsbRawDevice
\*rawDev, struct
UsbDeviceDescriptor \*desc); | 获取给定设备的USB设备描述符 | +| int32_t UsbRawClaimInterface(const UsbRawHandle
\*devHandle, int32_t
interfaceNumber); | 声明给定设备句柄上的接口 | +| int32_t UsbRawReleaseInterface(const UsbRawHandle
\*devHandle, in
t interfaceNumber); | 释放之前声明的接口 | +| int32_t UsbRawResetDevice(const UsbRawHandle
\*devHandle); | 复位设备 | +| struct UsbRawRequest \*UsbRawAllocRequest(const
UsbRawHandle
\*devHandle, int32_t isoPackets, int32_t length); | 分配一个带有指定数量的同步包描述符的传输请求 | +| int32_t UsbRawFreeRequest(const struct UsbRawRequest
\*request); | 释放之前分配的传输请求 | +| int32_t UsbRawFillBulkRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充批量传输请求所需信息 | +| int32_t UsbRawFillControlSetup(const unsigned char \*setup,
const struct UsbControlRequestData \*requestData); | 填充控制传输设置包所需信息 | +| int32_t UsbRawFillControlRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充控制传输请求所需信息 | +| int32_t UsbRawFillInterruptRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充中断传输请求所需信息 | +| int32_t UsbRawFillIsoRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充同步传输（Isochronous Transfers）请求所需信息 | +| int32_t UsbRawSubmitRequest(const struct UsbRawRequest
\*request); | 提交一个传输请求 | +| int32_t UsbRawCancelRequest(const struct UsbRawRequest
\*request); | 取消一个传输请求 | +| int32_t UsbRawHandleRequests(const UsbRawHandle
\*devHandle); | 传输请求事件完成处理 | USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型图。 @@ -89,19 +89,19 @@ USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型 | 接口名称 | 功能描述 | | -------- | -------- | | const struct UsbFnDevice \*UsbFnCreateDevice(const
char \*udcName, const struct UsbFnDescriptorData
\*descriptor); | 创建USB设备 | -| int UsbFnRemoveDevice(struct UsbFnDevice
\*fnDevice); | 删除USB设备 | +| int32_t UsbFnRemoveDevice(struct UsbFnDevice
\*fnDevice); | 删除USB设备 | | const struct UsbFnDevice \*UsbFnGetDevice(const char
\*udcName); | 获取USB设备 | **表4** usbfn_interface.h | 接口名称 | 功能描述 | | -------- | -------- | -| int UsbFnStartRecvInterfaceEvent(struct
UsbFnInterface \*interface, uint32_t eventMask,
UsbFnEventCallback callback, void \*context); | 开始接受Event事件 | -| int UsbFnStopRecvInterfaceEvent(struct
UsbFnInterface \*interface); | 停止接受Event事件 | +| int32_t UsbFnStartRecvInterfaceEvent(struct
UsbFnInterface \*interface, uint32_t eventMask,
UsbFnEventCallback callback, void \*context); | 开始接受Event事件 | +| int32_t UsbFnStopRecvInterfaceEvent(struct
UsbFnInterface \*interface); | 停止接受Event事件 | | UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface \*interface); | 打开一个接口 | -| int UsbFnCloseInterface(UsbFnInterfaceHandle handle); | 关闭一个接口 | -| int UsbFnGetInterfacePipeInfo(struct UsbFnInterface
\*interface, uint8_t pipeId, struct UsbFnPipeInfo \*info); | 获取管道信息 | -| int UsbFnSetInterfaceProp(const struct UsbFnInterface
\*interface, const char \*name, const char \*value); | 设置自定义属性 | +| int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle); | 关闭一个接口 | +| int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface
\*interface, uint8_t pipeId, struct UsbFnPipeInfo \*info); | 获取管道信息 | +| int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface
\*interface, const char \*name, const char \*value); | 设置自定义属性 | **表5** usbfn_request.h @@ -109,10 +109,10 @@ USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型 | -------- | -------- | | struct UsbFnRequest
\*UsbFnAllocCtrlRequest(UsbFnInterfaceHandle handle,
uint32_t len); | 申请一个控制请求 | | struct UsbFnRequest \*UsbFnAllocRequest(UsbFnInterfaceHandle handle,
uint8_t pipe, uint32_t len); | 申请一个数据请求 | -| int UsbFnFreeRequest(struct UsbFnRequest \*req); | 释放一个请求 | -| int UsbFnSubmitRequestAsync(struct UsbFnRequest
\*req); | 发送异步请求 | -| int UsbFnSubmitRequestSync(struct UsbFnRequest
\*req, uint32_t timeout); | 发送同步请求 | -| int UsbFnCancelRequest(struct UsbFnRequest \*req); | 取消请求 | +| int32_t UsbFnFreeRequest(struct UsbFnRequest \*req); | 释放一个请求 | +| int32_t UsbFnSubmitRequestAsync(struct UsbFnRequest
\*req); | 发送异步请求 | +| int32_t UsbFnSubmitRequestSync(struct UsbFnRequest
\*req, uint32_t timeout); | 发送同步请求 | +| int32_t UsbFnCancelRequest(struct UsbFnRequest \*req); | 取消请求 | ## 开发步骤 @@ -218,6 +218,9 @@ root { } } } +``` + +```cpp #include "usb_serial.h" #include "hdf_base.h" @@ -236,10 +239,10 @@ static struct UsbRequest *g_ctrlCmdRequest = NULL; static bool g_acmReleaseFlag = false; static uint8_t *g_acmReadBuffer = NULL; ... -static int SerialCtrlMsg(struct AcmDevice *acm, uint8_t request, +static int32_t SerialCtrlMsg(struct AcmDevice *acm, uint8_t request, uint16_t value, void *buf, uint16_t len) { - int ret; + int32_t ret; uint16_t index = acm->intPipe->interfaceId; struct UsbControlParams controlParams; struct UsbRequestParams params; @@ -299,7 +302,7 @@ static struct UsbPipeInfo *EnumePipe(const struct AcmDevice *acm, uint8_t interfaceIndex, UsbPipeType pipeType, UsbPipeDirection pipeDirection) { uint8_t i; - int ret; + int32_t ret; struct UsbInterfaceInfo *info = NULL; UsbInterfaceHandle *interfaceHandle = NULL; if (pipeType == USB_PIPE_TYPE_CONTROL) @@ -408,11 +411,11 @@ error: return HDF_FAILURE; } ... -static int AcmAllocReadRequests(struct AcmDevice *acm) +static int32_t AcmAllocReadRequests(struct AcmDevice *acm) { - int ret; + int32_t ret; struct UsbRequestParams readParams; - for (int i = 0; i < ACM_NR; i++) { + for (int32_t i = 0; i < ACM_NR; i++) { acm->readReq[i] = UsbAllocRequest(InterfaceIdToHandle(acm, acm->dataInPipe->interfaceId), 0, acm->readSize); // 分配待发送的readReq IO Request对象 if (!acm->readReq[i]) { HDF_LOGE("readReq request failed"); @@ -441,9 +444,9 @@ error: return HDF_ERR_MALLOC_FAIL; } -static int AcmAllocNotifyRequest(struct AcmDevice *acm) +static int32_t AcmAllocNotifyRequest(struct AcmDevice *acm) { - int ret; + int32_t ret; struct UsbRequestParams intParams = {}; acm->notifyReq = UsbAllocRequest(InterfaceIdToHandle(acm, acm->intPipe->interfaceId), 0, acm->intSize); // 分配待发送的中断IO Request对象 if (!acm->notifyReq) { @@ -474,7 +477,7 @@ error: static void AcmReleaseInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { if (acm->iface[i]) { UsbReleaseInterface(acm->iface[i]); acm->iface[i] = NULL; @@ -488,7 +491,7 @@ static void AcmReleaseInterfaces(struct AcmDevice *acm) static int32_t AcmClaimInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { acm->iface[i] = GetUsbInterfaceById((const struct AcmDevice *)acm, acm->interfaceIndex[i]); // 获取UsbInterface接口对象 if (acm->iface[i] == NULL) { HDF_LOGE("%s: interface%d is null", __func__, acm->interfaceIndex[i]); @@ -511,7 +514,7 @@ static int32_t AcmClaimInterfaces(struct AcmDevice *acm) static void AcmCloseInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { if (acm->devHandle[i]) { UsbCloseInterface(acm->devHandle[i]); acm->devHandle[i] = NULL; @@ -525,7 +528,7 @@ static void AcmCloseInterfaces(struct AcmDevice *acm) static int32_t AcmOpenInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { if (acm->iface[i]) { acm->devHandle[i] = UsbOpenInterface(acm->iface[i]); // 打开获取到的UsbInterface接口对象 if (acm->devHandle[i] == NULL) { @@ -606,7 +609,7 @@ static int32_t AcmAllocRequests(struct AcmDevice *acm) return HDF_ERR_MALLOC_FAIL; } - for (int i = 0; i < ACM_NW; i++) { + for (int32_t i = 0; i < ACM_NW; i++) { struct AcmWb *snd = &(acm->wb[i]); snd->request = UsbAllocRequest(InterfaceIdToHandle(acm, acm->dataOutPipe->interfaceId), 0, acm->writeSize); //分配待发送的IO Request对象 snd->instance = acm; @@ -789,7 +792,7 @@ HDF_INIT(g_usbSerialDriverEntry); ### Host RAW API驱动开发 -``` +```cpp root { module = "usb_pnp_device"; usb_pnp_config { @@ -836,7 +839,9 @@ root { } } } +``` +```cpp #include "usb_serial_rawapi.h" #include #include "osal_mem.h" @@ -858,11 +863,11 @@ struct OsalMutex g_stopIoLock; static bool g_rawAcmReleaseFlag = false; ...... -static int UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDescriptor **config) +static int32_t UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDescriptor **config) { UsbRawDevice *dev = NULL; - int activeConfig; - int ret; + int32_t activeConfig; + int32_t ret; if (devHandle == NULL) { HDF_LOGE("%s:%d devHandle is NULL", @@ -893,9 +898,9 @@ static int UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDe return HDF_SUCCESS; } ... -static int UsbAllocWriteRequests(struct AcmDevice *acm) +static int32_t UsbAllocWriteRequests(struct AcmDevice *acm) { - int i; + int32_t i; for (i = 0; i < ACM_NW; i++) { struct AcmWb *snd = &acm->wb[i]; @@ -965,13 +970,13 @@ error: return HDF_FAILURE; } ... -static int UsbAllocReadRequests(struct AcmDevice *acm) +static int32_t UsbAllocReadRequests(struct AcmDevice *acm) { struct UsbRawFillRequestData reqData; - int size = acm->dataInEp->maxPacketSize; - int ret; + int32_t size = acm->dataInEp->maxPacketSize; + int32_t ret; - for (int i = 0; i < ACM_NR; i++) { + for (int32_t i = 0; i < ACM_NR; i++) { acm->readReq[i] = UsbRawAllocRequest(acm->devHandle, 0, size); if (!acm->readReq[i]) { HDF_LOGE("readReq request failed"); @@ -996,11 +1001,11 @@ static int UsbAllocReadRequests(struct AcmDevice *acm) return HDF_SUCCESS; } ... -static int UsbAllocNotifyRequest(struct AcmDevice *acm) +static int32_t UsbAllocNotifyRequest(struct AcmDevice *acm) { struct UsbRawFillRequestData fillRequestData; - int size = acm->notifyEp->maxPacketSize; - int ret; + int32_t size = acm->notifyEp->maxPacketSize; + int32_t ret; acm->notifyReq = UsbRawAllocRequest(acm->devHandle, 0, size); if (!acm->notifyReq) { @@ -1226,9 +1231,8 @@ HDF_INIT(g_usbSerialRawDriverEntry); USB ACM设备核心代码路径为drivers\peripheral\usb\gadget\function\acm\cdcacm.c。其使用示例如下所示，首先根据描述符创建设备，然后获取接口，打开接口，获取Pipe信息，接收Event事件，接着进行USB通信（读写等），设备卸载时候，关闭接口，停止Event接收，删除设备。 - -``` 1、创建设备 +```cpp static int32_t AcmCreateFuncDevice(struct UsbAcmDevice *acm, struct DeviceResourceIface *iface) { @@ -1251,7 +1255,9 @@ if (useHcs == 0) { } ... } +``` 2、获取接口，打开接口，获取Pipe信息 +```cpp static int32_t AcmParseEachPipe(struct UsbAcmDevice *acm, struct UsbAcmInterface *iface) { ... @@ -1277,8 +1283,11 @@ static int32_t AcmParseEachIface(struct UsbAcmDevice *acm, struct UsbFnDevice *f } return HDF_SUCCESS; } +``` + 3、接收Event事件 -static int32_t AcmAllocCtrlRequests(struct UsbAcmDevice *acm, int num) +```cpp +static int32_t AcmAllocCtrlRequests(struct UsbAcmDevice *acm, int32_t num) { ... req = UsbFnCtrlRequestAlloc(acm->ctrlIface.handle, @@ -1292,7 +1301,9 @@ static int32_t AcmDriverInit(struct HdfDeviceObject *device) ret = UsbFnInterfaceStartRecvEvent(acm->ctrlIface.fn, 0xff, UsbAcmEventCallback, acm); ... } +``` 4、进行USB通信（读写等） +```cpp static int32_t AcmSendNotifyRequest(struct UsbAcmDevice *acm, uint8_t type, uint16_t value, void *data, uint32_t length) { @@ -1301,7 +1312,9 @@ static int32_t AcmSendNotifyRequest(struct UsbAcmDevice *acm, uint8_t type, ret = UsbFnRequestSubmitAsync(req); ... } +``` 5、关闭接口，停止Event接收，删除设备 +```cpp static int32_t AcmReleaseFuncDevice(struct UsbAcmDevice *acm) { int32_t ret; diff --git a/zh-cn/device-dev/faqs/faqs-startup.md b/zh-cn/device-dev/faqs/faqs-startup.md index 9db1d8a011326bf14d1a272f5703656899f0b3d7..d1c02d9d674dc1a9202a1bbca80bca265cf1a614 100644 --- a/zh-cn/device-dev/faqs/faqs-startup.md +++ b/zh-cn/device-dev/faqs/faqs-startup.md @@ -191,6 +191,42 @@ OpenHarmony-3.0-LTS 设备进入hdc shell下， 执行sandbox -s service_name命令，模拟当前服务进入沙盒场景， 通过 ls 等shell命令查看当前服务沙盒目录。具体参考[沙盒命令](../subsystems/subsys-boot-init-plugin.md) +### Bootevent部分事件的ready阶段的时间戳为0 + +**现象描述** + +Bootevent手动模式下，开机完成之后在执行dump_service all bootevent命令后有部分事件的ready阶段的时间戳为0。 + +**可能原因** + +1. 服务没有发送bootevent事件。 +2. 服务发送bootevent事件， 但是没有相关权限。 + +**解决方法** + +1. 服务配置了bootevent，但是没有发送该bootevent事件，请相关服务在代码中发送该bootevent事件。 +2. 在代码中已经执行到设置bootevent的操作，但是ready的状态就是为零，此时请检查服务是否有设置bootevent参数的权限。 + +### A/B分区启动过程因只烧写原始分区导致的无法启动 + +**现象描述** + +烧写完成后系统无法正常启动，并且可以在串口日志中找到类似如下打印： + +``` +wait for file:/dev/block/platform/fe310000.sdhci/by-name/system_b failed after 5 second. +Mount /dev/block/platform/fe310000.sdhci/by-name/system_b to /usr failed 2 +``` + +**可能原因** + +当前系统已经支持了A/B分区启动，根据日志可知本次启动尝试挂载了带"_b"后缀的system分区，即本次启动从B分区启动，但是并没有找到设备，导致挂载失败。这种情况是由于当前misc分区中的active slot值被设置为了2（B分区），但是并没有烧写对应B分区导致的。 + +**解决方法** + +1. 可以清空misc分区（使用空misc镜像烧写对应分区），将其中的active slot值擦除，再次启动即可从默认分区启动。 +2. 使用配置了B分区的分区表将system_b和vendor_b镜像烧写到开发板中，再次启动即可从对应B分区正常启动。 + ## Appspawn应用孵化常见问题 ### 设备启动中，appspawn启动失败 @@ -221,11 +257,15 @@ OpenHarmony-3.0-LTS 1. 冷启动状态未打开。 2. 冷启动命令参数输入错误。 +3. socket请求超时。 +4. selinux打开。 **解决办法** -1. 冷启动不使能， 通过param get appspawn.cold.boot命令查看状态，如果冷启动状态是false, 通过param set appspawn.cold.boot true 命令打开冷启动状态。 +1. 冷启动不使能， 通过param get startup.appspawn.cold.boot命令查看状态，如果冷启动状态是0, 通过param set startup.appspawn.cold.boot 1 命令打开冷启动状态。 2. 冷启动命令参数不正确， 查看并确认冷启动参数。 +3. 设置超时时间>3秒，执行 param set persist.appspawn.client.timeout 5 命令。 +4. 关闭selinux, 执行 setenforce 0 命令。 ### 应用沙盒创建失败 diff --git a/zh-cn/device-dev/kernel/figures/zh-cn_image-20220930141628922.png b/zh-cn/device-dev/kernel/figures/zh-cn_image-20220930141628922.png index 4a959db1206c500c0ee61e1548ffa4c94565d104..f4c4e437a0089ac5ba3371f531694daac4b36703 100644 Binary files a/zh-cn/device-dev/kernel/figures/zh-cn_image-20220930141628922.png and b/zh-cn/device-dev/kernel/figures/zh-cn_image-20220930141628922.png differ diff --git a/zh-cn/device-dev/subsystems/Readme-CN.md b/zh-cn/device-dev/subsystems/Readme-CN.md index 3aca6a69afabb10c047aed0b228025b0f4c283b4..901db72406063e38d4675440075e1b915d050bc3 100644 --- a/zh-cn/device-dev/subsystems/Readme-CN.md +++ b/zh-cn/device-dev/subsystems/Readme-CN.md @@ -82,6 +82,8 @@ - [系统参数](subsys-boot-init-sysparam.md) - [沙盒管理](subsys-boot-init-sandbox.md) - [插件](subsys-boot-init-plugin.md) + - [组件化启动](subsys-boot-init-sub-unit.md) + - [init运行日志规范化](subsys-boot-init-log.md) - [appspawn应用孵化组件](subsys-boot-appspawn.md) - [bootstrap服务启动组件](subsys-boot-bootstrap.md) - [常见问题](subsys-boot-faqs.md) diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-log.md b/zh-cn/device-dev/subsystems/subsys-boot-init-log.md new file mode 100644 index 0000000000000000000000000000000000000000..f7e67b7d31bee1e67f7957ca9182d6748528e7dc --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-log.md @@ -0,0 +1,74 @@ +# init运行时日志规范化 +## 概述 +### 功能简介 +日志的基本功能就是记录init启动中的关键节点，以及定位故障问题。 +- 基于日志可以定位故障问题，可以查看各子系统启动时长，命令执行时长等。 +- 可以查看不同模块的日志tag，如param、uevent、module等。 +- 输出关键阶段日志，如第一阶段启动日志、required partition设备节点、uevent创建日志、服务启动日志等。 +- 日志等级可控，根据需要输出不同级别日志，目前日志级别分为INIT_DEBUG, +INIT_INFO,INIT_WARN,INIT_ERROR,INIT_FATAL。 + +### 基本概念 + +init日志根据OpenHarmony版本不同实现方式不同。 +- 对于OpenHarmony标准版本，init日志采用内核的dmesg log实现。 +- 对于OpenHarmony liteos L1版本init日志采用hilog接口实现。 +- 对于OpenHarmony liteos L0版本init日志采用printf接口实现。 + +### 约束与限制 +无 + +## 开发指导 +### 场景介绍 +init log主要应用在init的启动过程中，启动相关模块（param、ueventd、module等）中，以及对外提供的begetutils接口中。 + +### 接口说明 + +**表1** log接口说明 + | 接口 | 接口格式和示例 | 说明 | + | -------- | -------- | -------- | + | INIT_LOGV | INIT_LOGV("Add %s to job %s", service->name, jobName); | 输出debug log。 | + | INIT_LOGI | INIT_LOGI("Start init first stage."); | 输出info log。 | + | INIT_LOGW | INIT_LOGW("initialize signal handler failed"); | 输出warning log。 | + | INIT_LOGE | INIT_LOGE("Failed to format other opt"); | 输出err log。 | + | INIT_LOGF | INIT_LOGF("Failed to init system"); | 输出fatal log。 | + | INIT_ERROR_CHECK | INIT_ERROR_CHECK(ctx != NULL, return NULL, "Failed to get cmd args "); | 判断 ctx != NULL 不成立的情况下输出log，同时执行 return NULL。 | + | INIT_INFO_CHECK | INIT_INFO_CHECK(sockopt != NULL, return SERVICE_FAILURE, "Failed to malloc for service %s", service->name); | 判断 sockopt != NULL 不成立的情况下输出log，同时执行 return SERVICE_FAILURE。 | + | INIT_WARNING_CHECK | INIT_WARNING_CHECK(argsCount <= SPACES_CNT_IN_CMD_MAX, argsCount = SPACES_CNT_IN_CMD_MAX, "Too much arguments for command, max number is %d", SPACES_CNT_IN_CMD_MAX); | 判断 argsCount <= SPACES_CNT_IN_CMD_MAX 不成立的情况下输出log，同时执行 argsCount = SPACES_CNT_IN_CMD_MAX。 | + | INIT_CHECK | INIT_CHECK(arg != NULL, return NULL); | 判断arg != NULL 不成立的情况下执行 return NULL。 | + | INIT_CHECK_RETURN_VALUE | INIT_CHECK_RETURN_VALUE(errno == 0, -1); | 判断errno == 0 不成立的情况下执行 return -1。 | + | INIT_CHECK_ONLY_RETURN | INIT_CHECK_ONLY_RETURN(cmd != NULL); | 判断cmd != NULL 不成立的情况下执行 return。 | + | INIT_CHECK_ONLY_ELOG | INIT_CHECK_ONLY_ELOG(execv(argv[0], argv) == 0, "execv %s failed! err %d.", argv[0], errno); | 判断execv(argv[0], argv) == 0 不成立的情况下只打印log "execv %s failed! err %d."。 | + +### 开发实例 + + 1. 调用接口打印日志 + + 例如在 //base/startup/init/services/init/standard/init.c中调用接口INIT_LOGI("Start init first stage.")打印日志。 + ```c + void SystemPrepare(void) + { + MountBasicFs(); + CreateDeviceNode(); + LogInit(); + // Make sure init log always output to /dev/kmsg. + EnableDevKmsg(); + INIT_LOGI("Start init first stage."); + // Only ohos normal system support + // two stages of init. + // If we are in updater mode, only one stage of init. + if (InUpdaterMode() == 0) { + StartInitSecondStage(); + } + } + ``` + 通过dmesg可以查看打印的log，"Start init first stage."。 + + 2. 通过命令设置日志等级 + + 通过命令begetctl setloglevel level，其中level对应log的等级0~4，即INIT_DEBUG，INIT_INFO，INIT_WARN，INIT_ERROR，INIT_FATAL。 + + 设置完成之后init的g_logLevel等级立即生效，上述log接口中log等级大于等于g_logLevel才会打印日志。例如：begetctl setloglevel 3，即设置log等级为INIT_ERROR，则上述的log接口中只有INIT_LOGE、INIT_LOGF才会打印log。 + + 系统重启之后在init.cfg中"load_persist_params "命令之后生效设置的log等级。 + diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-plugin.md b/zh-cn/device-dev/subsystems/subsys-boot-init-plugin.md index 69e3b2dc032c90905ea40f8475c3bb6acf56f545..0612e4eb70e19f00940c20f890f60b87f9c3b10b 100644 --- a/zh-cn/device-dev/subsystems/subsys-boot-init-plugin.md +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-plugin.md @@ -59,6 +59,8 @@ bootchart和bootevent只支持标准系统， begetctl 支持小型系统和标 | modulectl uninstall moduleName | 卸载动态插件，例如：
modulectl uninstall bootchart | 无 | | modulectl install moduleName | 安装动态插件，例如：
modulectl install bootchart | 无 | | modulectl list | 动态插件列表，例如：
begetctl modulectl list | 无 | +| setloglevel level | 设置log等级为info，例如：
begetctl setloglevel 1 | log等级设置范围0~4 | +| getloglevel | 获取当前init的log等级，例如：
begetctl getloglevel | 无 | | bootevent disable | 关闭bootevent插件功能，例如：
bootevent disable | 无 | | bootevent enable | 开启bootevent插件功能，例如：
begetctl 关闭bootevent插件功能 | 无 | | dump_service parameter_service trigger | 命令行展示所有trigger信息，例如：
begetctl dump_service parameter_service trigger | 无 | @@ -67,16 +69,6 @@ bootchart和bootevent只支持标准系统， begetctl 支持小型系统和标 | dump api | 命令行展示init接口信息，例如：
begetctl dump api | 无 | -### 接口说明 - - **表1** 接口介绍 -| 函数 | 函数解释 | -| ---------- | ---------- | -| void PluginExecCmdByName(const char *name, const char *cmdContent) | 通过名称启动插件。 | -| void PluginExecCmdByCmdIndex(int index, const char *cmdContent) | 通过标志启动插件。 | -| int PluginExecCmd(const char *name, int argc, const char **argv) | 命令启动插件。 | -| int AddCmdExecutor(const char *cmdName, CmdExecutor execCmd) | 添加安装插件命令。 | - ### 开发步骤 新增一个插件， 以bootchart为例： 1. 安装so文件， 定义单独文件，实现下面函数。 diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-sandbox.md b/zh-cn/device-dev/subsystems/subsys-boot-init-sandbox.md index 0fd7c44f7e6fbe995fe8d26dd0cf13da5e1942a2..bfb9ad418ce7b7268ad2aabee9a8fc790f195e50 100644 --- a/zh-cn/device-dev/subsystems/subsys-boot-init-sandbox.md +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-sandbox.md @@ -23,6 +23,7 @@ | src-path | 需要mount的目录/文件路径 | | sandbox-path | 沙盒里面需要挂载至的目录/文件 | | sandbox-flags | mount的挂载标志位, 缺省"bind rec"标志位 | + | ignore | 是否忽略mount失败，设置为1 则忽略失败，继续往下执行 | | target-name | 需要link的目录 | | link-name | 沙盒内link后的目录 | @@ -43,13 +44,13 @@ bool InitSandboxWithName(const char *name); // 解析JSON至结构体 typedef struct { - mountlist_t *mounts; // 待 mount 的目录 - mountlist_t *fileMounts; // 待 mount 的文件 - linklist_t *links; // 待 link 的目录 - char *rootPath; // 沙盒的根路径 -> /mnt/sandbox/system|vendor|xxx - char name[MAX_BUFFER_LEN]; // 沙盒名称，system沙盒、chipset沙盒等 - bool isCreated; // 沙盒创建标志 - int ns; // namespace + ListNode pathMountsHead; // sandbox mount_path list head + ListNode fileMountsHead; // sandbox mount_file list head + ListNode linksHead; // sandbox symbolic link list head + char *rootPath; // /mnt/sandbox/system|vendor|xxx + char name[MAX_BUFFER_LEN]; // name of sandbox. i.e system, chipset etc. + bool isCreated; // sandbox already created or not + int ns; // namespace } sandbox_t; ``` ### 开发步骤 diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-sub-unit.md b/zh-cn/device-dev/subsystems/subsys-boot-init-sub-unit.md new file mode 100644 index 0000000000000000000000000000000000000000..06e7419723eae6063f99cda96bfa6101c0e241d9 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-sub-unit.md @@ -0,0 +1,120 @@ +# 组件化启动 +## 概述 +### 功能简介 +构建四个基础组件镜像，提供相应的组件化目录，包括： +- 系统组件：system +- 产品通用配置组件：sys_prod +- 芯片组件：chipset +- 产品硬件配置组件：chip_prod; + +确保系统参数以及启动脚本都可以按照组件的优先级进行扫描初始化; +完成系统组件和芯片组件的独立编译构建。 +### 基本概念 +- 基础组件 + + system：系统组件文件系统挂载点，与芯片及硬件无关的平台业务； + sys_prod：对系统组件的能力扩展以及能力定制，承载产品级差异能力，存放产品相关的配置文件； + chipset：芯片组件文件系统挂载点，为系统组件提供统一的硬件抽象服务,相同的芯片平台可统一一份芯片组件; + chip_prod：单板外设特有硬件能力以及产品级硬件差异配置, 存放芯片相关的配置文件。 + +- 组件化编译构建 + + 通过"target_cpu" 指定系统组件的指令集；通过"inherit" 继承base、headless或者rich等通用组件集合；最后通过"subsystems" 定义该形态更多的部件。 + +- 系统参数以及启动脚本按照组件的优先级进行扫描初始化 + + 系统参数以及启动脚本包括：服务的cfg配置文件、param文件、沙盒json配置文件以及module插件化库文件等。相关文件优先级顺序是 /system < /chipset < /sys_prod < /chip_prod，即优先级高的配置文件将取代、更新低优先级配置。 + + +### 约束与限制 +对于标准版本和小型系统都支持组件化编译构建，以及系统参数以及启动脚本按照组件的优先级进行扫描初始化。 + +## 开发指导 +### 场景介绍 +组件化启动主要是满足厂家、硬件平台通过模块化的组合快速实现产品开发。以下以rk3568产品为例介绍组件化启动。 + +### rk3568产品的组件化构建编译 +//vendor/hihope/rk3568/config.json 配置文件实现构建此产品需要的组件，如下所示： + + { + "product_name": "rk3568", + "device_company": "rockchip", + ... + "target_cpu": "arm", + ... + "inherit": [ "productdefine/common/inherit/rich.json", "productdefine/common/inherit/chipset_common.json" ], + "subsystems": [ + { + "subsystem": "security", + "components": [ + { + "component": "selinux", + "features": [] + } + ] + } + ... + } + +从中可以看出产品名称、芯片厂家、支持的指令集等；inherit指出依赖的通用组件；subsystems指出通用组件以外的部件。 +//productdefine/common/inherit/rich.json 如下所示配置系统组件完整的部件；系统组件还可以包括base.json(所有产品都要包含的最小部件集合列表)、headless.json(没有ui界面的产品支持应用安装管理的最小部件集合)。 + + { + "version": "3.0", + "subsystems": [ + { + "subsystem": "arkui", + "components": [ + { + "component": "ace_engine", + "features": [] + }, + { + "component": "napi", + "features": [] + } + ] + }, + { + "subsystem": "account", + "components": [ + { + "component": "os_account", + "features": [] + } + ] + }, + ... + } + +### 系统参数根据优先级扫描初始化 +对于服务的cfg配置文件优先级是/system/etc < /system/etc/init < /chipset/etc，即优先级高的配置文件将取代、更新低优先级配置。例如/system/etc/init/camera_service.cfg， + + { + "services" : [{ + "name" : "camera_service", + "path" : ["/system/bin/sa_main", "/system/profile/camera_service.xml"], + "uid" : "cameraserver", + "gid" : ["system", "shell"], + "secon" : "u:r:camera_service:s0", + "permission" : ["ohos.permission.GET_SENSITIVE_PERMISSIONS"], + "permission_acls" : ["ohos.permission.GET_SENSITIVE_PERMISSIONS"] + }] + } + +同时存在/chipset/etc/camera_B_service.cfg + + { + "services" : [{ + "name" : "camera_service", + "path" : ["/system/bin/sa_main", "/system/profile/camera_B_service.xml"], + "uid" : "cameraserver", + "gid" : ["system", "shell"], + "secon" : "u:r:camera_service:s0", + "permission" : ["ohos.permission.GET_SENSITIVE_PERMISSIONS"], + "permission_acls" : ["ohos.permission.GET_SENSITIVE_PERMISSIONS"], + "disabled" : 1 + }] + } + +那么根据优先级的要求，camera_service服务"path"属性将会被优先级高的["/system/bin/sa_main", "/system/profile/camera_B_service.xml"]取代，同时增加"disabled"属性。