HarmonyOS Developer 开发指导

丶龙八夷
发布于 2023-3-31 16:38
浏览
0收藏

应用事件打点开发指导

简介

传统的日志系统里汇聚了整个设备上所有程序运行的过程流水日志,难以识别其中的关键信息。因此,应用开发者需要一种数据打点机制,用来评估如访问数、日活、用户操作习惯以及影响用户使用的关键因素等关键信息。

HiAppEvent是在系统层面为应用开发者提供的一种事件打点机制,用于帮助应用记录在运行过程中发生的故障信息、统计信息、安全信息、用户行为信息,以支撑开发者分析应用的运行情况。

基本概念

  • 打点
    记录由用户操作引起的变化,提供业务数据信息,以供开发、产品、运维分析。

事件设计规范

  • 事件领域:用于标识事件的领域,建议设置为业务模块名称,以便于区分不同的业务模块。
  • 事件名称:用于指定事件的名称,建议设置为具体的业务名称,以便于描述实际的业务意义。
  • 事件类型:用于指定事件的类型,支持以下四种类型事件:

      ○ 行为事件:用于记录用户日常操作行为的事件,例如按钮点击、界面跳转等行为。

      ○ 故障事件:用于定位和分析应用故障的事件,例如界面卡顿、掉网掉话等异常。

      ○ 统计事件:用于统计和度量应用关键行为的事件,例如对使用时长、访问数等的统计。

      ○ 安全事件:用于记录涉及应用安全行为的事件,例如密码修改、用户授权等行为。

  • 事件参数:用于指定事件的参数,每个事件可以包含一组参数,建议设置为事件属性或事件发生上下文信息,以便于描述事件的详细信息。

接口说明

应用事件打点接口由hiAppEvent模块提供,API接口的具体使用说明(参数使用限制、具体取值范围等)请参考​​应用事件打点API文档​​。

打点接口功能介绍:

接口名

描述

write(AppEventInfo info, AsyncCallback<void> callback): void

应用事件异步打点方法,使用callback方式作为异步回调。

write(AppEventInfo info): Promise<void>

应用事件异步打点方法,使用Promise方式作为异步回调。

订阅接口功能介绍:

接口名

描述

addWatcher(Watcher watcher): AppEventPackageHolder

添加应用事件观察者,以添加对应用事件的订阅。

removeWatcher(Watcher watcher): void

移除应用事件观察者,以移除对应用事件的订阅。

开发步骤

以实现对用户点击按钮行为的事件打点及订阅为例,说明开发步骤。

  1. 新建一个ets应用工程,编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ts” 文件,在onCreate函数中添加对用户点击按钮事件的订阅,完整示例代码如下:

import hilog from '@ohos.hilog';
import UIAbility from '@ohos.app.ability.UIAbility';
import Window from '@ohos.window'
import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'

export default class EntryAbility extends UIAbility {
    onCreate(want, launchParam) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
        hilog.info(0x0000, 'testTag', '%{public}s', 'want param:' + JSON.stringify(want) ?? '');
        hilog.info(0x0000, 'testTag', '%{public}s', 'launchParam:' + JSON.stringify(launchParam) ?? '');

        hiAppEvent.addWatcher({
            // 开发者可以自定义观察者名称,系统会使用名称来标识不同的观察者
            name: "watcher1",
            // 开发者可以订阅感兴趣的应用事件,此处是订阅了按钮事件
            appEventFilters: [{ domain: "button" }],
            // 开发者可以设置订阅回调触发的条件,此处是设置为事件打点数量满足1个
            triggerCondition: { row: 1 },
            // 开发者可以自行实现订阅回调函数,以便对订阅获取到的事件打点数据进行自定义处理
            onTrigger: function (curRow, curSize, holder) {
                // 返回的holder对象为null,表示订阅过程发生异常,因此在记录错误日志后直接返回
                if (holder == null) {
                    hilog.error(0x0000, 'testTag', "HiAppEvent holder is null")
                    return
                }
                let eventPkg = null
                // 根据设置阈值大小(默认为512KB)去获取订阅事件包,直到将订阅数据全部取出
                // 返回的事件包对象为null,表示当前订阅数据已被全部取出,此次订阅回调触发结束
                while ((eventPkg = holder.takeNext()) != null) {
                    // 开发者可以对事件包中的事件打点数据进行自定义处理,此处是将事件打点数据打印在日志中
                    hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.packageId=%{public}d`, eventPkg.packageId)
                    hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.row=%{public}d`, eventPkg.row)
                    hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.size=%{public}d`, eventPkg.size)
                    for (const eventInfo of eventPkg.data) {
                        hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.info=%{public}s`, eventInfo)
                    }
                }
            }
        })
    }
}
  1. 编辑工程中的“entry > src > main > ets > pages > Index.ets” 文件,添加一个按钮并在其onClick函数中进行事件打点,以记录按钮点击事件,完整示例代码如下:

import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'
import hilog from '@ohos.hilog'
@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Button("writeTest").onClick(()=>{
          // 在按钮点击函数中进行事件打点,以记录按钮点击事件
          hiAppEvent.write({
            // 事件领域定义
            domain: "button",
            // 事件名称定义
            name: "click",
            // 事件类型定义
            eventType: hiAppEvent.EventType.BEHAVIOR,
            // 事件参数定义
            params: { click_time: 100 }
          }).then(() => {
            hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`)
          }).catch((err) => {
            hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`)
          })
        })
      }
      .width('100%')
    }
    .height('100%')
  }
}
  1. 点击IDE界面中的运行按钮,运行应用工程,然后在应用界面中点击按钮“writeTest”,触发一次按钮点击事件打点。
  2. 最终,可以在Log窗口看到按钮点击事件打点成功的日志,以及触发订阅回调后对打点事件数据的处理日志:

HiAppEvent success to write event

HiAppEvent eventPkg.packageId=0
HiAppEvent eventPkg.row=1
HiAppEvent eventPkg.size=124
HiAppEvent eventPkg.info={"domain_":"button","name_":"click","type_":4,"time_":1670268234523,"tz_":"+0800","pid_":3295,"tid_":3309,"click_time":100}

性能打点跟踪开发指导

简介

hiTraceMeter为开发者提供系统性能打点接口。开发者通过在自己的业务逻辑中的关键代码位置调用HiTraceMeter接口提供的API接口,能够有效跟踪进程轨迹、查看系统性能。

基本概念

  • hiTraceMeter Tag
    跟踪数据使用类别分类,称作hiTraceMeter Tag或hiTraceMeter Category,一般每个软件子系统对应一个Tag,该Tag在打点API中以类别Tag参数传入。hiTraceMeter命令行工具采集跟踪数据时,只采集给定的Tag类别选项指定的跟踪数据。

实现原理

  • 应用程序通过hiTraceMeter函数接口进行打点,hiTraceMeter函数将跟踪数据通过内核sysfs文件接口输出到内核的ftrace数据缓冲区。
  • hiTraceMeter命令行工具读取内核ftrace缓冲区中的跟踪数据,将文本格式的跟踪数据保存到设备侧的文件中。

约束与限制

  • 由于JS程序的异步IO特性,现在hiTraceMeter只提供了异步接口。

接口说明

性能打点跟踪接口由hiTraceMeter模块提供,详细API请参考​​性能打点跟踪API参考​​。

性能打点跟踪接口功能介绍:

接口名

返回值

描述

hiTraceMeter.startTrace(name: string, taskId: number)

void

标记一个预跟踪耗时任务的开始。如果有多个相同name的任务需要跟踪或者对同一个任务要跟踪多次,并且任务同时被执行,则每次调用startTrace的taskId不相同。如果具有相同name的任务是串行执行的,则taskId可以相同。

hiTraceMeter.finishTrace(name: string, taskId: number)

void

name和taskId必须与流程开始的hiTraceMeter.startTrace对应参数值保持一致。

hiTraceMeter.traceByValue(name: string, value: number)

void

用来标记一个预跟踪的数值变量,该变量的数值会不断变化。

开发步骤

在应用启动执行页面加载后,开始分布式跟踪,完成业务之后,停止分布式跟踪。

  1. 新建一个JS应用工程,在“Project”窗口点击“entry > src > main > js > default > pages > index”,打开工程中的“index.js”文件,在页面执行加载后,在自己的业务中调用hiTraceMeter的接口,进行性能打点跟踪,示例代码如下:

import hiTraceMeter from '@ohos.hiTraceMeter'

export default {
    data: {
        title: ""
    },
    onInit() {
        this.title = this.$t('strings.world');

        // 跟踪并行执行的同名任务
        hiTraceMeter.startTrace("business", 1);
        // 业务流程
        console.log(`business running`);
        hiTraceMeter.startTrace("business", 2);  // 第二个跟踪任务开始,同时第一个跟踪的同名任务还没结束,出现了并行执行,对应接口的taskId需要不同。
        // 业务流程
        console.log(`business running`);
        hiTraceMeter.finishTrace("business", 1);
        // 业务流程
        console.log(`business running`);
        hiTraceMeter.finishTrace("business", 2);

        // 跟踪串行执行的同名任务
        hiTraceMeter.startTrace("business", 1);
        // 业务流程
        console.log(`business running`);
        hiTraceMeter.finishTrace("business", 1);  // 第一个跟踪的任务结束
        // 业务流程
        console.log(`business running`);
        hiTraceMeter.startTrace("business", 1);   // 第二个跟踪的同名任务开始,同名的待跟踪任务串行执行。
        // 业务流程
        console.log(`business running`);

        let traceCount = 3;
        hiTraceMeter.traceByValue("myTestCount", traceCount);
        traceCount = 4;
        hiTraceMeter.traceByValue("myTestCount", traceCount);
        hiTraceMeter.finishTrace("business", 1);
    }
}

  1. 运行项目,点击应用界面上的运行按钮,即可通过日志信息分析实际业务。

分布式跟踪开发指导

简介

hiTraceChain是基于云计算分布式跟踪调用链思想,在端侧业务流程(涉及跨线程、跨进程、跨设备)中的一种轻量级实现。hiTraceChain在业务控制面流程中,生成和传递唯一跟踪标识,在业务流程中输出的各类信息中(包括应用事件、系统时间、日志等)记录该跟踪标识。在调试、问题定位过程中,开发者可以通过该唯一跟踪标识将本次业务流程端到端的各类信息快速关联起来。hiTraceChain为开发者提供业务流程调用链跟踪的维测接口,帮助开发者迅速获取指定业务流程调用链的运行日志,定位跨设备/跨进程/跨线程的故障问题。

基本概念

  • chainId
    分布式跟踪标识,属于HiTraceId的一部分,用于标识当前跟踪的业务流程。

接口说明

分布式跟踪接口由hiTraceChain模块提供,详细API请参考​​分布式跟踪API参考​​。

分布式跟踪接口功能介绍:

接口名

返回值

描述

hiTraceChain.begin(name: string, flags: number = HiTraceFlag.DEFAULT)

HiTraceId

开始跟踪。

hiTraceChain.tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string)

void

信息埋点。

hiTraceChain.end(id: HiTraceId)

void

结束跟踪。

开发步骤

在应用启动执行页面加载后,开始分布式跟踪,完成业务之后,停止分布式跟踪。

  1. 新建一个JS应用工程,在“Project”窗口点击“entry > src > main > js > default > pages > index”,打开工程中的“index.js”文件,在页面执行加载后,在实际业务逻辑中调用hiTraceChain的API,进行分布式跟踪,示例代码如下:

import hiTraceChain from '@ohos.hiTraceChain'

export default {
    data: {
        title: ""
    },
    onInit() {
        this.title = this.$t('strings.world');

        // 1、开启分布式跟踪
        let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN);
        
        // 2、业务流程开始
        console.log(`business start`);

        // 3、埋点操作
        hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example");

        // 4、业务流程执行中
        console.log(`business running`);

        // 5、业务流程结束
        console.log(`business end`);

        // 6、停止跟踪
        hiTraceChain.end(asyncTraceId);
    }
}

  1. 运行项目,点击应用界面上的运行按钮,即可通过日志信息分析实际业务。

国际化开发概述

当应用具有多个在语言、时区、区域特性等方面存在显著差异的目标用户和市场时,开发者往往需要提供应用的多个本地化版本,以保证不同地区用户的体验。

应用的国际化能力决定了应用本地化过程的难易程度。系统提供了一系列的国际化接口,基于这些国际化接口,开发者可以设计并实现具有良好国际化能力的应用,从而可以高效、低成本的实现应用的本地化。

基本概念

  • Locale:Locale是对一个群体在语言、脚本、国家或区域,以及日历、排序、货币等区域特性方面的共性的抽象表示。
  • 偏好语言:偏好语言是用户设置过的语言,表示该语言是用户可接受的语言。用户可以在 设置/系统和更新/语言和输入法/语言和地区/添加语言中添加偏好语言。

运作机制

在调用国际化接口时,需要提供Locale信息,接口会依据该Locale的特性进行差异化的执行。Locale信息可以由开发人员通过硬编码的方式提供,但更通常的情况是使用用户设置的系统语言和区域。

约束与限制

Intl开发指导

本模块提供基础的应用国际化能力,包括时间日期格式化、数字格式化、排序等,相关接口在ECMA 402标准中定义。更多接口和使用方式请见​​Intl​​。

​I18N​​模块提供其他非ECMA 402定义的国际化接口,与本模块共同使用可提供完整地国际化支持能力。

设置区域信息

调用​​Locale​​的相关接口实现最大化区域信息或最小化区域信息。

接口说明

类名

接口名称

描述

Locale

constructor()8+

实例化Locale对象。

Locale

constructor(locale:string,options?:LocaleOptions)

基于locale参数及其选项实例化Locale对象。

Locale

toString():string

将Locale信息转换为字符串。

Locale

maximize():Locale

最大化区域信息。

Locale

minimize():Locale

最小化区域信息。

开发步骤
  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import Intl from '@ohos.intl'

 2.实例化Locale对象。使用Locale的构造函数创建Locale对象,该方法接收一个表示Locale的字符串及可选的​​属性​​​列表(intl为导入的模块名)。
表示Locale的字符串参数可以分为以下四部分:语言、脚本、地区、扩展参数。各个部分按照顺序使用中划线“-”进行连接。

  • 语言:必选,使用2个或3个小写英文字母表示(可参考ISO-639标准),例如英文使用“en”表示,中文使用“zh”表示。
  • 脚本:可选,使用4个英文字母表示,其中首字母需要大写,后面3个使用小写字母(可参考ISO-15924)。例如,中文繁体使用脚本“Hant”表示,中文简体使用脚本“Hans”表示。
  • 国家或地区:可选,使用两个大写字母表示(可参考ISO-3166),例如中国使用“CN”表示,美国使用“US”表示;
  • 扩展参数:可选,由key和value两部分组成,目前支持以下扩展参数(可参考BCP 47扩展)。各个扩展参数之间没有严格的顺序,使用“-key-value”的格式书写。扩展参数整体使用“-u”连接到语言、脚本、地区后面。例如“zh-u-nu-latn-ca-chinese”表示使用“latn”数字系统,“chinese”日历系统。扩展参数也可以通过第二个参数传入。

扩展参数ID

扩展参数说明

ca

表示日历系统

co

表示排序规则

hc

表示守时惯例

nu

表示数字系统

kn

表示字符串排序、比较时是否考虑数字的实际值

kf


表示字符串排序、比较时是否考虑大小写

let locale = "zh-CN";
let options = {caseFirst: "false", calendar: "chinese", collation: "pinyin"};
let localeObj = new Intl.Locale(locale, options);
  1. 获取Locale的字符串表示。

调用toString方法来获取Locale对象的字符串表示,其中包括了语言、区域及其他选项信息。

let localeStr = localeObj.toString(); // localeStr = "zh-CN-u-ca-chinese-co-pinyin-kf-false
  1. 最大化区域信息。

调用maximize方法来最大化区域信息,即当缺少脚本与地区信息时,对其进行补全。

let maximizedLocale = localeObj.maximize();
let maximizedLocaleStr = maximizedLocale.toString(); // localeStr = "zh-Hans-CN-u-ca-chinese-co-pinyin-kf-false
  1. 最小化区域信息。

调用minimize方法来最小化区域信息,即当存在脚本与地区信息时,对其进行删除。

let minimizedLocale = localeObj.minimize();
let minimizedLocaleStr = minimizedLocale.toString(); // zh-u-ca-chinese-co-pinyin-kf-false

格式化日期时间

调用日期时间格式化​​DateTimeFormat​​的接口,实现针对特定Locale的日期格式化以及时间段格式化功能。

接口说明

类名

接口名称

描述

DateTimeFormat

constructor()8+

创建日期时间格式化对象。

DateTimeFormat

constructor(locale:string|Array<string>,options?:DateTimeOptions)

创建日期时间格式化对象,并设置提供的Locale和格式化相关属性。

DateTimeFormat

format(date:Date):string

依据DateTimeFormat对象的Locale及其他格式化属性,计算日期时间的格式化表示。

DateTimeFormat

formatRange(startDate:Date,endDate:Date):string

依据DateTimeFormat对象的Locale及其他格式化属性,计算时间段的格式化表示。

DateTimeFormat

resolvedOptions():DateTimeOptions

获取DateTimeFormat对象的相关属性。

开发步骤
  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import Intl from '@ohos.intl'
  1. 实例化日期时间格式化对象。

一种方法是使用DateTimeFormat提供的默认构造函数,通过访问系统语言和地区设置,获取系统默认Locale,并将其作为DateTimeFormat对象内部的Locale。

let dateTimeFormat = new Intl.DateTimeFormat();

另一种方法是使用开发者提供的Locale和格式化参数来创建日期时间格式化对象。其中,格式化参数是可选的,完整的格式化参数列表见​​DateTimeOptions​​。

let options = {dateStyle: "full", timeStyle: "full"};
let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options);
  1. 格式化日期时间。

使用DateTimeFormat的format方法对一个Date对象进行格式化,该方法会返回一个字符串作为格式化的结果。

let options = {dateStyle: "full", timeStyle: "full"};
let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options);
let date = new Date(2022, 12, 12, 12, 12, 12);
let formatResult = dateTimeFormat.format(date); // formatResult = "2023年1月12日星期四 中国标准时间 下午12:12:12"
  1. 格式化时间段。

使用DateTimeFormat的formatRange方法对一个时间段进行格式化。该方法需要传入两个Date对象,分别表示时间段的起止日期,返回一个字符串作为格式化的结果。

let startDate = new Date(2021, 11, 17, 3, 24, 0);
let endDate = new Date(2021, 11, 18, 3, 24, 0);
let datefmt = new Intl.DateTimeFormat("en-GB");
let formatRangeResult = datefmt.formatRange(startDate, endDate); // formatRangeResult = "17/12/2021-18/12/2021"
  1. 访问日期时间格式化对象的相关属性。

DateTimeFormat的resolvedOptions方法会返回一个对象,该对象包含了DateTimeFormat对象的所有相关属性及其值。

let options = {dateStyle: "full", timeStyle: "full"};
let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options);
let resolvedOptions = dateTimeFormat.resolvedOptions(); // resolvedOptions = {"locale": "zh-CN", "calendar": "gregorian", "dateStyle":"full", "timeStyle":"full", "timeZone": "CST"}

数字格式化

调用数字格式化​​NumberFormat​​的接口,实现针对特定Locale的数字格式化功能。

接口说明

类名

接口名称

描述

NumberFormat

constructor()8+

创建数字格式化对象。

NumberFormat

constructor(locale:string|Array<string>,options?:NumberOptions)

创建数字格式化对象,并设置提供的locale和格式化相关属性。

NumberFormat

format(number:number):string

依据NumberFormat对象的Locale及其他格式化属性,计算数字的格式化表示。

NumberFormat

resolvedOptions():NumberOptions

获取NumberFormat对象的相关属性。

开发步骤
  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import Intl from '@ohos.intl'
  1. 实例化数字格式化对象。

一种方法是使用NumberFormat提供的默认构造函数,通过访问系统的语言和地区以获取系统默认Locale并进行设置(intl为导入的模块名)。

let numberFormat = new Intl.NumberFormat();

另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中,格式化参数是可选的,完整的格式化参数列表参见​​NumberOptions​​。

let options = {compactDisplay: "short", notation: "compact"};
let numberFormat = new Intl.NumberFormat("zh-CN", options);
  1. 数字格式化。

使用NumberFormat的format方法对传入的数字进行格式化。该方法返回一个字符串作为格式化的结果。

let options = {compactDisplay: "short", notation: "compact"};
let numberFormat = new Intl.NumberFormat("zh-CN", options);
let number = 1234.5678let formatResult = numberFormat.format(number); // formatResult = "1235"
  1. 访问数字格式化对象的相关属性。

NumberFormat的resolvedOptions方法会返回一个对象,该对象包含了NumberFormat对象的所有相关属性及其值。

let options = {compactDisplay: "short", notation: "compact"};
let numberFormat = new Intl.NumberFormat("zh-CN", options);
let resolvedOptions = numberFormat.resolvedOptions();  // resolvedOptions = {"locale": "zh-CN", "compactDisplay": "short", "notation": "compact", "numberingSystem": "Latn"}

字符串排序

不同区域的用户对于字符串排序具有不同的需求。调用字符串排序​​Collator​​的接口,实现针对特定Locale的字符串排序功能。

接口说明

类名

接口名称

描述

Collator

constructor()8+

创建排序对象。

Collator

constructor(locale:string|Array<string>,options?:CollatorOptions)8+

创建排序对象,并设置提供的locale和其他相关属性。

Collator

compare(first:string,second:string):number8+

依据排序对象的Locale及其属性,计算两个字符串的比较结果。

Collator

resolvedOptions():CollatorOptions8+

获取排序对象的相关属性。

开发步骤
  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import Intl from '@ohos.intl'
  1. 实例化排序对象。

一种方法是使用Collator提供的默认构造函数,通过访问系统的语言和地区以获取系统默认Locale并进行设置(intl为导入的模块名)。

let collator = new Intl.Collator();

另一种方法是使用开发者提供的Locale和其他相关参数来创建Collator对象,完整的参数列表参见​​CollatorOptions​​。其中,sensitivity参数用于控制哪些级别的差异会被用于比较两个字符串。取值"base"表示,仅比较字符本身,不考虑重音符号、大小写差异。例如,'a' != 'b','a' == 'á','a' == 'A'。取值"accent"表示考虑重音符号,不考虑大小写的差异。例如,'a' != 'b','a' != 'á','a' == 'A'。取值"case"表示考虑大小写的差异,不考虑重音符号的差异。例如,'a' != 'b','a' == 'á','a' != 'A'。取值"variant"表示考虑重音符号、大小写等方面差异。例如'a' != 'b','a' != 'á','a' != 'A'。

let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort", sensitivity: "case"});
  1. 比较字符串。

使用Collator的compare方法对传入的两个字符串进行比较。该方法返回一个数值作为比较的结果,返回-1表示第一个字符串小于第二个字符串,返回1表示第一个字符大于第二个字符串,返回0表示两个字符串相同。基于两个字符串的比较结果,开发者可以字符串集合进行排序。

let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort", sensitivity: "case"});
let str1 = "first string";let str2 = "second string";
let compareResult = collator.compare(str1, str2); // compareResult = -1
str1 = "first";
str2 = "First";
compareResult = collator.compare(str1, str2); // compareResult = -1
  1. 访问排序对象的相关属性。

Collator的resolvedOptions方法会返回一个对象,该对象包含了Collator对象的所有相关属性及其值。

let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"});
let options = collator.resolvedOptions(); // options = {"localeMatcher": "best fit", "locale": "zh-CN", "usage": "sort", "sensitivity": "variant", "ignorePunctuation": "false", "numeric": false, "caseFirst": "false", "collation": "default"}

判定单复数类别

在一些语言的语法中,当数字后面存在名词时,名词需要根据数字的值采用不同的形式。调用单复数​​PluralRules​​的接口,可以实现针对特定Locale计算数字单复数类别的功能,从而选择合适的名词单复数表示。

接口说明

类名

接口名称

描述

PluralRules

constructor()8+

创建单复数对象。

PluralRules

constructor(locale:string|Array<string>,options?:PluralRulesOptions)8+

创建单复数对象,并设置提供的locale和其他相关属性。

PluralRules

select(n:number):string8+

依据单复数对象的Locale及其他格式化属性,计算数字的单复数类别。

开发步骤
  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import Intl from '@ohos.intl'
  1. 实例化单复数对象。

一种方法是使用PluralRules提供的默认构造函数,通过访问系统的语言和地区以获取系统默认Locale并进行设置(intl为导入的模块名)。

let pluralRules = new Intl.PluralRules();

另一种方法是使用开发者提供的Locale和其他相关参数来创建单复数对象。完整的参数列表参见​​PluralRulesOptions​​。

let pluralRules = new Intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"});
  1. 计算数字单复数类别。

使用PluralRules的select方法计算传入数字的单复数类别。该方法返回一个字符串作为传入数字的类别,包括:"zero", "one", "two", "few", "many", "other"六个类别。

let pluralRules = new Intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"});
let number = 1234.5678;
let categoryResult = pluralRules.select(number); // categoryResult = "other"

相对时间格式化

调用相对时间格式化​​RelativeTimeFormat​​的接口,实现针对特定Locale的相对时间格式化功能。

接口说明

类名

接口名称

描述

RelativeTimeFormat

constructor()8+

创建相对时间格式化对象。

RelativeTimeFormat

constructor(locale:string|Array<string>,options?:RelativeTimeFormatInputOptions)8+

创建相对时间格式化对象,并设置提供的locale和格式化相关属性。

RelativeTimeFormat

format(value:number,unit:string):string8+

依据相对时间格式化对象的Locale及其他格式化属性,计算相对时间的格式化表示。

RelativeTimeFormat

formatToParts(value:number,unit:string):Array<object>8+

依据相对时间格式化对象的Locale及其他格式化属性,返回相对时间格式化表示的各个部分。

RelativeTimeFormat

resolvedOptions():RelativeTimeFormatResolvedOptions8+

获取相对时间格式化对象的相关属性。

开发步骤
  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import Intl from '@ohos.intl'
  1. 实例化相对时间格式化对象。

一种方法是使用RelativeTimeFormat提供的默认构造函数,通过访问系统的语言和地区以获取系统默认Locale并进行设置(intl为导入的模块名)。

let relativeTimeFormat = new Intl.RelativeTimeFormat();

另一种方法是使用开发者提供的Locale和格式化参数来创建相对时间格式化对象。其中,格式化参数是可选的,完整的参数列表参见​​ RelativeTimeFormatInputOptions​

let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
  1. 相对时间格式化。

使用RelativeTimeFormat的format方法对相对时间进行格式化。方法接收一个表示相对时间长度的数值和表示单位的字符串,其中单位包括:"year", "quarter", "month", "week", "day", "hour", "minute", "second"。方法返回一个字符串作为格式化的结果。

let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
let number = 2;
let unit = "year";
let formatResult = relativeTimeFormat.format(number, unit); // 2年后
  1. 获取相对时间格式化结果的各个部分。

获取相对时间格式化结果的各个部分,从而自定义格式化结果。

let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
let number = 2;
let unit = "year";
let formatPartsResult = relativeTimeFormat.formatToParts(number, unit); // formatPartsResult = [{"type": "integer", "value": "2", "unit": "year"}, {"type":"literal", "value": "年后"}]
  1. 访问相对时间格式化对象的相关属性。

RelativeTimeFormat的resolvedOptions方法会返回一个对象,该对象包含了RelativeTimeFormat对象的所有相关属性及其值,完整的属性列表参见​​ RelativeTimeFormatResolvedOptions​​。

let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"});
let options = relativeTimeFormat.resolvedOptions(); // options = {"locale": "zh-CN", "style": "long", "numeric": "always", "numberingSystem": "latn"}



文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/intl-guidelines-0000001427744736-V3​

标签
已于2023-3-31 16:38:46修改
收藏
回复
举报
回复