HarmonyOS 项目 API 使用注意事项总结

1.手动导包的重要性：

* 自动导包（Alt + 回车）并不总是有效，某些包需要手动输入。例如：

import fs from '@ohos.file.fs' ; // 需手动输入

2.使用 @Kit：

* 从 API 12 开始，使用 @Kit 替代 @ohos。许多论坛资料仍使用 @ohos，可能导致功能不显示。例如：

要把

import hilog from '@ohos.hilog' ; import deviceInfo from '@ohos.deviceInfo' ;

改为
import { hilog } from '@kit.PerformanceAnalysisKit' ; import { deviceInfo } from '@kit.BasicServicesKit' ;

* 新建 API 12 项目时，查找资料时遇到 @ohos，请参考官方文档确认对应的 @Kit 版本。

3.注意手机版本：

* Beta 1 和 Beta 3 之间差异显著，尽管代码在 API 12 下不报错，但在真机上可能会出现错误。确保真机版本升级到 Beta 3 以上，官方文档可能未提供相关提示。

常用 API 导入示例

// 日志系统 import { hilog } from '@kit.PerformanceAnalysisKit' ; // Web 控制能力 import { webview } from '@kit.ArkWeb' ; // 图片处理 import { image } from '@kit.ImageKit' ; // 相册管理 import { photoAccessHelper } from '@kit.MediaLibraryKit' ; // 呼叫管理 import { call } from '@kit.TelephonyKit' ; // 资源管理 import { resourceManager } from '@kit.LocalizationKit' ; // 分享功能 import { systemShare } from '@kit.ShareKit' ; // 用户首选项 import { preferences } from '@kit.ArkData' ; // 事件处理 import { emitter } from '@kit.BasicServicesKit' ; // 文件操作 import { fileIo as fs } from '@kit.CoreFileKit' ; // 网络连接管理 import { connection } from '@kit.NetworkKit' ; // 扫码功能 import { scanBarcode } from '@kit.ScanKit' ; // 设备信息 import { deviceInfo } from '@kit.BasicServicesKit' ; // 剪贴板管理 import { pasteboard } from '@kit.BasicServicesKit' ; // 窗口管理 import { window } from '@kit.ArkUI' ; // 动画插值曲线 import { curves } from '@kit.ArkUI' ; // 组件内容封装 import { ComponentContent } from '@kit.ArkUI' ; // 提示框 import { promptAction } from '@kit.ArkUI' ; // 路由管理 import { router } from '@kit.ArkUI' ; // 页签型标题栏 import { TabTitleBar } from '@kit.ArkUI' ;

// @ohos全面替换 @kit //hilog日志系统，使应用/服务可以按照指定级别、标识和格式字符串输出日志内容，帮助开发者了解应用/服务的运行状态，更好地调试程序。 import { hilog } from '@kit.PerformanceAnalysisKit' ; //@ohos.web.webview提供web控制能力，Web组件提供网页显示的能力。访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考声明权限。 import { webview } from '@kit.ArkWeb' ; //本模块提供图片处理效果，包括通过属性创建PixelMap、读取图像像素数据、读取区域内的图片数据等。 import { image } from '@kit.ImageKit' ; //该模块提供相册管理模块能力，包括创建相册以及访问、修改相册中的媒体数据信息等。 import { photoAccessHelper } from '@kit.MediaLibraryKit' ; //该模块提供呼叫管理功能，包括拨打电话、跳转到拨号界面、获取通话状态、格式化电话号码等。 import { call } from '@kit.TelephonyKit' ; //资源管理模块，根据当前configuration：语言、区域、横竖屏、Mcc（移动国家码）和Mnc（移动网络码）、Device capability（设备类型）、Density（分辨率）提供获取应用资源信息读取接口。 import { resourceManager } from '@kit.LocalizationKit' //本模块提供分享数据创建及分享面板拉起的功能，提供多种系统标准分享服务，例如分享数据给其他应用、复制、打印等。 // // 分享接入应用需要配置、呈现和关闭分享面板。 // 分享面板的配置包括数据对象、呈现视图的方式、预览方式等。 import { systemShare } from '@kit.ShareKit' ; //本模块对标准化数据类型进行了抽象定义与描述。 import { uniformTypeDescriptor as utd } from '@kit.ArkData' ; //@ohos.data.preferences (用户首选项)用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。 // // 数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。 import { preferences } from '@kit.ArkData' ; //错误信息打印 import { BusinessError } from '@kit.BasicServicesKit' ; //开发者可以通过该模块引用Ability公共模块类。 import { common } from '@kit.AbilityKit' ; //需要校验的权限名称，合法的权限名取值可在应用权限列表中查询。 import { Permissions } from '@kit.AbilityKit' ; //UIAbility是包含UI界面的应用组件，继承自Ability，提供组件创建、销毁、前后台切换等生命周期回调，同时也具备组件协同的能力，组件协同主要提供如下常用功能： import { UIAbility } from '@kit.AbilityKit' ; //本模块提供应用信息查询能力，支持BundleInfo、ApplicationInfo、AbilityInfo、ExtensionAbilityInfo等信息的查询。 import { bundleManager } from '@kit.AbilityKit' ; //Want是对象间信息传递的载体, 可以用于应用组件间的信息传递。 Want的使用场景之一是作为startAbility的参数, 其包含了指定的启动目标, 以及启动时需携带的相关数据, 如bundleName和abilityName字段分别指明目标Ability所在应用的Bundle名称以及对应包内的Ability名称。当Ability A需要启动Ability B并传入一些数据时, 可使用Want作为载体将这些数据传递给Ability B。 import { Want } from '@kit.AbilityKit' ; //本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求，支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。 import { http } from '@kit.NetworkKit' ; //网络连接管理提供管理网络一些基础能力，包括获取默认激活的数据网络、获取所有激活数据网络列表、开启关闭飞行模式、获取网络能力信息等功能。 import { connection } from '@kit.NetworkKit' ; //本模块提供默认界面扫码能力。 import { scanBarcode } from '@kit.ScanKit' //本模块提供扫码公共信息。 import { scanCore } from '@kit.ScanKit' //本模块提供终端设备信息查询，开发者不可配置。其中deviceInfo.marketNames可以获取设备名称，比如mate60 import { deviceInfo } from '@kit.BasicServicesKit' ; //本模块提供了在同一进程不同线程间，或同一进程同一线程内，发送和处理事件的能力，包括持续订阅事件、单次订阅事件、取消订阅事件，以及发送事件到事件队列的能力。 import { emitter } from '@kit.BasicServicesKit' ; //本模块主要提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。系统剪贴板支持对文本、HTML、URI、Want、PixelMap等内容的操作。 import { pasteboard } from '@kit.BasicServicesKit' ; //该模块为基础文件操作API，提供基础文件操作能力，包括文件基本管理、文件目录管理、文件信息统计、文件流式读写等常用功能。 import { fileIo as fs } from '@kit.CoreFileKit' ; //该模块提供空间查询相关的常用功能：包括对内外卡的空间查询，对应用分类数据统计的查询，对应用数据的查询等。 import { storageStatistics } from '@kit.CoreFileKit' ; //选择器(Picker)是一个封装PhotoViewPicker、DocumentViewPicker、AudioViewPicker等API模块，具有选择与保存的能力。应用可以自行选择使用哪种API实现文件选择和文件保存的功能。该类接口，需要应用在界面UIAbility中调用，否则无法拉起photoPicker应用或FilePicker应用。 import { picker } from '@kit.CoreFileKit' ; //本模块提供设置动画插值曲线功能，用于构造阶梯曲线对象、构造三阶贝塞尔曲线对象和构造弹簧曲线对象。 import { curves } from '@kit.ArkUI' ; //ComponentContent表示组件内容的实体封装，其对象支持在非UI组件中创建与传递，便于开发者对弹窗类组件进行解耦封装。ComponentContent底层使用了BuilderNode，相关使用规格参考BuilderNode。 import { ComponentContent } from '@kit.ArkUI' ; //用于设置长度属性，当长度单位为PERCENT时，值为1表示100%。 import { LengthMetrics } from '@kit.ArkUI' ; //创建并显示文本提示框、对话框和操作菜单。 import { promptAction } from '@kit.ArkUI' ; //窗口提供管理窗口的一些基础能力，包括对当前窗口的创建、销毁、各属性设置，以及对各窗口间的管理调度。 // // 该模块提供以下窗口相关的常用功能： // // Window：当前窗口实例，窗口管理器管理的基本单元。 // WindowStage：窗口管理器。管理各个基本窗口单元。 import { window } from '@kit.ArkUI' ; //一种普通标题栏，支持设置标题、头像（可选）和副标题（可选），可用于一级页面、二级及其以上界面配置返回键。 import { ComposeTitleBar } from '@kit.ArkUI' ; //本模块提供通过不同的url访问不同的页面，包括跳转到应用内的指定页面、同应用内的某个页面替换当前页面、返回上一页面或指定的页面等。 // // 推荐使用Navigation组件作为应用路由框架。 import { router } from '@kit.ArkUI' ; //页签型标题栏，用于页面之间的切换。仅一级页面适用。 import { TabTitleBar } from '@kit.ArkUI' ; class MyUIAbility extends UIAbility { } @Builder function buildText ( params : object ) {   Column ( ) {   } . backgroundColor ( '#FFF0F0F0' ) } @Entry @Component struct Page14 {   controller : webview . WebviewController = new webview .WebviewController ( ) ;   test ( ) {    router . pushUrl ( {       url : 'pages/routerpage2'     } )     let config : window . Configuration = {       name : "test" ,       windowType : window . WindowType . TYPE_DIALOG ,       ctx : getContext ( )     } ;     let promise = window . createWindow ( config ) ;     try {      promptAction . showToast ( {         message : 'Hello World' ,         duration : 2000       } ) ;     } catch ( error ) {       let message = ( error as BusinessError ) . message       let code = ( error as BusinessError ) . code      console . error ( ` showToast args error code is ${code } , message is ${message } ` ) ;     }     ;   }   aboutToAppear ( ) : void {    LengthMetrics . vp ( 3 )     let uiContext = this . getUIContext ( ) ;     let promptAction = uiContext . getPromptAction ( ) ;     let contentNode = new ComponentContent ( uiContext , wrapBuilder ( buildText ) , Object ) ;    curves . initCurve ( Curve . EaseIn ) // 创建一个默认先慢后快插值曲线     let documentPicker = new picker .DocumentViewPicker ( getContext ( ) ) ;    storageStatistics . getCurrentBundleStats ( ) . then ( ( BundleStats : storageStatistics .BundleStats ) => {      console . info ( "getCurrentBundleStats successfully:" + JSON . stringify ( BundleStats ) ) ;     } ) . catch ( ( err : BusinessError ) => {      console . error ( "getCurrentBundleStats failed with error:" + JSON . stringify ( err ) ) ;     } ) ;     let filePath = "pathDir/test.txt" ;    fs . stat ( filePath ) . then ( ( stat : fs .Stat ) => {      console . info ( "get file info succeed, the size of file is " + stat . size ) ;     } ) . catch ( ( err : BusinessError ) => {      console . error ( "get file info failed with error message: " + err . message + ", error code: " + err . code ) ;     } ) ;     let dataXml = new ArrayBuffer ( 256 ) ;     let pasteData : pasteboard . PasteData = pasteboard . createData ( 'app/xml' , dataXml ) ;     let innerEvent : emitter . InnerEvent = {       eventId : 1     } ;    console . info ( ` marketName: ${deviceInfo .marketName } ` )     let netConnection = connection . createNetConnection ( ) ;    http . RequestMethod . POST    hilog . isLoggable ( 0x0001 , "testTag" , ) ;     const color : ArrayBuffer = new ArrayBuffer ( 96 ) ; // 96为需要创建的像素buffer大小，取值为：height * width *4     let opts : image . InitializationOptions = { editable : true , pixelFormat : 3 , size : { height : 4 , width : 6 } }    image . createPixelMap ( color , opts ) . then ( ( pixelMap : image .PixelMap ) => {      console . info ( 'Succeeded in creating pixelmap.' ) ;     } ) . catch ( ( error : BusinessError ) => {      console . error ( ` Failed to create pixelmap. code is ${error .code } , message is ${error .message } ` ) ;     } )     //此处获取的phAccessHelper实例为全局对象，后续使用到phAccessHelper的地方默认为使用此处获取的对象，如未添加此段代码报phAccessHelper未定义的错误请自行添加     let context = getContext ( this ) ;     let phAccessHelper = photoAccessHelper . getPhotoAccessHelper ( context ) ;    call . makeCall ( "138xxxxxxxx" , ( err : BusinessError ) => {       if ( err ) {        console . error ( ` makeCall fail, err-> ${ JSON . stringify (err ) } ` ) ;       } else {        console . log ( ` makeCall success ` ) ;       }     } ) ;     let systemResourceManager = resourceManager . getSystemResourceManager ( ) ;     let data : systemShare . SharedData = new systemShare .SharedData ( {       utd : utd . UniformDataType . PLAIN_TEXT ,       content : 'Hello HarmonyOS'     } ) ;    preferences . getPreferencesSync ( getContext ( ) , { name : 'myStore' } )     let uiAbilityContext : common . UIAbilityContext ;     let permissionName : Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS' ;     let bundleFlags = bundleManager . BundleFlag . GET_BUNDLE_INFO_WITH_APPLICATION |    bundleManager . BundleFlag . GET_BUNDLE_INFO_WITH_METADATA ;     let want : Want = {       deviceId : '' , // deviceId为空表示本设备       bundleName : 'com.example.myapplication' ,       abilityName : 'EntryAbility' ,       moduleName : 'entry' // moduleName非必选     } ;     // 定义扫码参数options     let options : scanBarcode . ScanOptions = {       scanTypes : [ scanCore . ScanType . ALL ] ,       enableMultiMode : true ,       enableAlbum : true     } ;     // 可调用getContext接口获取当前页面关联的UIAbilityContext    scanBarcode . startScanForResult ( context , options , ( error : BusinessError , result : scanBarcode .ScanResult ) => {     } )   }   build ( ) {     Column ( ) {       ComposeTitleBar ( {         title : "标题" ,         subtitle : "副标题" ,       } )       TabTitleBar ( {         // swiperContent: this.componentBuilder,         // tabItems: this.tabItems,         // menuItems: this.menuItems,       } )     }     . height ( '100%' )     . width ( '100%' )   } }

总结

在使用 HarmonyOS API 时，注意手动导包、使用正确的 @Kit 版本以及确保真机版本的兼容性。这些注意事项和示例代码将帮助你更高效地开发项目。