【HarmonyOS】公司鸿蒙项目收工总结之《API》

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", 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%')
  }
}

总结

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