HarmonyOS 项目 API 使用注意事项总结
1.手动导包的重要性:
* 自动导包(Alt + 回车)并不总是有效,某些包需要手动输入。例如:
2.使用 @Kit:
* 从 API 12 开始,使用 @Kit 替代 @ohos。许多论坛资料仍使用 @ohos,可能导致功能不显示。例如:
要把
改为
* 新建 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';
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
- 16.
- 17.
- 18.
- 19.
- 20.
- 21.
- 22.
- 23.
- 24.
- 25.
- 26.
- 27.
- 28.
- 29.
- 30.
- 31.
- 32.
- 33.
- 34.
- 35.
- 36.
- 37.
- 38.
- 39.
- 40.
示例代码
// @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", hilog.LogLevel.INFO);
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%')
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
- 16.
- 17.
- 18.
- 19.
- 20.
- 21.
- 22.
- 23.
- 24.
- 25.
- 26.
- 27.
- 28.
- 29.
- 30.
- 31.
- 32.
- 33.
- 34.
- 35.
- 36.
- 37.
- 38.
- 39.
- 40.
- 41.
- 42.
- 43.
- 44.
- 45.
- 46.
- 47.
- 48.
- 49.
- 50.
- 51.
- 52.
- 53.
- 54.
- 55.
- 56.
- 57.
- 58.
- 59.
- 60.
- 61.
- 62.
- 63.
- 64.
- 65.
- 66.
- 67.
- 68.
- 69.
- 70.
- 71.
- 72.
- 73.
- 74.
- 75.
- 76.
- 77.
- 78.
- 79.
- 80.
- 81.
- 82.
- 83.
- 84.
- 85.
- 86.
- 87.
- 88.
- 89.
- 90.
- 91.
- 92.
- 93.
- 94.
- 95.
- 96.
- 97.
- 98.
- 99.
- 100.
- 101.
- 102.
- 103.
- 104.
- 105.
- 106.
- 107.
- 108.
- 109.
- 110.
- 111.
- 112.
- 113.
- 114.
- 115.
- 116.
- 117.
- 118.
- 119.
- 120.
- 121.
- 122.
- 123.
- 124.
- 125.
- 126.
- 127.
- 128.
- 129.
- 130.
- 131.
- 132.
- 133.
- 134.
- 135.
- 136.
- 137.
- 138.
- 139.
- 140.
- 141.
- 142.
- 143.
- 144.
- 145.
- 146.
- 147.
- 148.
- 149.
- 150.
- 151.
- 152.
- 153.
- 154.
- 155.
- 156.
- 157.
- 158.
- 159.
- 160.
- 161.
- 162.
- 163.
- 164.
- 165.
- 166.
- 167.
- 168.
- 169.
- 170.
- 171.
- 172.
- 173.
- 174.
- 175.
- 176.
- 177.
- 178.
- 179.
- 180.
- 181.
- 182.
- 183.
- 184.
- 185.
- 186.
- 187.
- 188.
- 189.
- 190.
- 191.
- 192.
- 193.
- 194.
- 195.
- 196.
- 197.
- 198.
- 199.
- 200.
- 201.
- 202.
- 203.
- 204.
- 205.
- 206.
- 207.
- 208.
- 209.
- 210.
- 211.
- 212.
- 213.
- 214.
- 215.
- 216.
- 217.
- 218.
- 219.
- 220.
- 221.
- 222.
- 223.
- 224.
- 225.
- 226.
- 227.
- 228.
- 229.
- 230.
- 231.
- 232.
- 233.
- 234.
- 235.
- 236.
总结
在使用 HarmonyOS API 时,注意手动导包、使用正确的 @Kit 版本以及确保真机版本的兼容性。这些注意事项和示例代码将帮助你更高效地开发项目。