diff --git a/zh-cn/application-dev/device/figures/zh-cn_image_0000001180249428.png b/zh-cn/application-dev/device/figures/zh-cn_image_0000001180249428.png new file mode 100644 index 0000000000000000000000000000000000000000..0f8cd72f3fc88533dc99761c08764b3a498ce115 Binary files /dev/null and b/zh-cn/application-dev/device/figures/zh-cn_image_0000001180249428.png differ diff --git a/zh-cn/application-dev/device/figures/zh-cn_image_0000001196654004.png b/zh-cn/application-dev/device/figures/zh-cn_image_0000001196654004.png new file mode 100644 index 0000000000000000000000000000000000000000..48b1613b6e67f2dd57cd480fdb7fd0312594e049 Binary files /dev/null and b/zh-cn/application-dev/device/figures/zh-cn_image_0000001196654004.png differ diff --git a/zh-cn/application-dev/device/figures/zh-cn_image_0000001226521897.png b/zh-cn/application-dev/device/figures/zh-cn_image_0000001226521897.png new file mode 100644 index 0000000000000000000000000000000000000000..b00280219ffe5b8fa4f4f090a6d13254b01db042 Binary files /dev/null and b/zh-cn/application-dev/device/figures/zh-cn_image_0000001226521897.png differ diff --git a/zh-cn/application-dev/device/figures/zh-cn_image_0000001241693881.png b/zh-cn/application-dev/device/figures/zh-cn_image_0000001241693881.png new file mode 100644 index 0000000000000000000000000000000000000000..5c54c71606ce2f81308923d8d4c579f1b9b3ad3c Binary files /dev/null and b/zh-cn/application-dev/device/figures/zh-cn_image_0000001241693881.png differ diff --git a/zh-cn/application-dev/device/figures/zh-cn_image_0000001241733907.png b/zh-cn/application-dev/device/figures/zh-cn_image_0000001241733907.png new file mode 100644 index 0000000000000000000000000000000000000000..d0a680b7138b81e6e9a1e598634b66dd598dd603 Binary files /dev/null and b/zh-cn/application-dev/device/figures/zh-cn_image_0000001241733907.png differ diff --git a/zh-cn/application-dev/device/sensor-guidelines.md b/zh-cn/application-dev/device/sensor-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..d69088647aa8c1feee551bc1e872930399796b11 --- /dev/null +++ b/zh-cn/application-dev/device/sensor-guidelines.md @@ -0,0 +1,133 @@ +# 传感器开发指导 + + +## 场景介绍 + +- 通过指南针传感器数据，感知用户设备当前的朝向，从而达到为用户指明方向的目的。 + +- 通过接近光传感器数据，感知距离遮挡物的距离，使设备能够自动亮灭屏，达到防误触目的。 + +- 通过气压计传感器数据，准确的判断设备当前所处的海拔。 + +- 通过环境光传感器数据，设备能够实现背光自动调节。 + +- 通过霍尔传感器数据，设备实现皮套功能等。 + +- 通过心率传感器数据，感知用户当前的心率。 + +- 通过计步传感器数据，可以统计用户的步数。 + +- 通过佩戴检测传感器，可以检测用户是否佩戴。 + + +## 接口说明 + +| 模块 | 接口名 | 描述 | +| -------- | -------- | -------- | +| ohos.sensor | sensor.on(sensorType, callback:AsyncCallback<Response>): void | 持续监听传感器数据变化 | +| ohos.sensor | sensor.once(sensorType, callback:AsyncCallback<Response>): void | 获取一次传感器数据变化 | +| ohos.sensor | sensor.off(sensorType, callback:AsyncCallback<void>): void | 注销传感器数据的监听 | + + +## 开发步骤 + +1. 获取设备上传感器的数据，需要在“config.json”里面进行配置请求权限。具体如下： + + ``` + ”reqPermissions“:[ + { + "name":"ohos.permission.ACCELEROMETER", + "reason"":"", + "usedScene":{ + "ability": ["sensor.index.MainAbility",".MainAbility"], + "when":"inuse" + } + }, + { + "name":"ohos.permission.GYROSCOPE", + "reason"":"", + "usedScene":{ + "ability": ["sensor.index.MainAbility",".MainAbility"], + "when":"inuse" + } + }, + { + "name":"ohos.permission.ACTIVITY_MOTION", + "reason"":"ACTIVITY_MOTION_TEST", + "usedScene":{ + "ability": ["sensor.index.MainAbility",".MainAbility"], + "when":"inuse" + } + }, + { + "name":"ohos.permission.READ_HEALTH_DATA", + "reason"":"HEALTH_DATA_TEST", + "usedScene":{ + "ability": ["sensor.index.MainAbility",".MainAbility"], + "when":"inuse" + } + }, + { + "name":"ohos.permission.VIBRATE", + "reason"":"", + "usedScene":{ + "ability": [".MainAbility"], + "when":"inuse" + } + }, + ] + ``` + +2. 持续监听传感器数据变化。 + + ``` + import sensor from "@ohos.sensor" + sensor.on(sensor.sensorType,function(error,data){ + if (error) {//调用失败，打印error.code和error.message + console.error("Subscription failed. Error code: " + error.code + "; message: " + error.message); + return; + }; + console.info("Subscription succeeded. data = "+ data);//调用成功，打印对应传感器的数据 + } + ); + ``` + + 以SensorType为SENSOR_TYPE_ID_ACCELEROMETER为例展示运行结果，持续监听传感器接口的结果如下图所示： + + ![zh-cn_image_0000001241693881](figures/zh-cn_image_0000001241693881.png) + +3. 注销传感器数据监听。 + + ``` + import sensor from "@ohos.sensor" + sensor.off(sensor.sensorType,function(error) { + if (error) {//注销失败，返回error.code和error.message + console.error("Failed to unsubscribe from acceleration sensor data. Error code: " + error.code + "; message: " + error.message); + return; + }; + console.info("Succeeded in unsubscribing from acceleration sensor data.");//注销成功，返回打印结果 + } + ); + ``` + + 以SensorType为SENSOR_TYPE_ID_ACCELEROMETER为例展示运行结果，注销传感器成功结果如下图所示： + + ![zh-cn_image_0000001196654004](figures/zh-cn_image_0000001196654004.png) + +4. 获取一次传感器数据变化。 + + ``` + import sensor from "@ohos.sensor" + sensor.once(sensor.sensorType,function(error, data) { + if (error) {//获取数据失败，返回error.code和error.message + console.error("Failed to obtain data. Error code: " + error.code + "; message: " + error.message); + return; + }; + console.info("Data obtained successfully. data="+data);//获取数据成功，打印对应传感器的数据 + } + ); + ``` + + 以SensorType为SENSOR_TYPE_ID_ACCELEROMETER为例展示运行结果，获取数据成功日志如下图所示： + + ![zh-cn_image_0000001241733907](figures/zh-cn_image_0000001241733907.png) diff --git a/zh-cn/application-dev/device/sensor-overview.md b/zh-cn/application-dev/device/sensor-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..ea60e7c4e4947ac66ca5242a280976a4b323eef3 --- /dev/null +++ b/zh-cn/application-dev/device/sensor-overview.md @@ -0,0 +1,111 @@ +# 传感器开发概述 + + +OpenHarmony系统传感器是应用访问底层硬件传感器的一种设备抽象概念。开发者根据传感器提供的Sensor API，可以查询设备上的传感器，订阅传感器数据，并根据传感器数据定制相应的算法开发各类应用，比如指南针、运动健康、游戏等。 + + +根据传感器的用途，可以将传感器分为六大类：运动类传感器、环境类传感器、方向类传感器、光线类传感器、健康类传感器、其他传感器（如霍尔传感器），每一大类传感器都包含不同类型的传感器，某些类型的传感器可能是单一的物理传感器，也可能是由多个物理传感器复合而成。下面为传感器列表： + + + **表1** 运动类-ohos.sensor.agent.CategoryMotionAgent + +| 传感器类型 | 中文描述 | 说明 | 主要用途 | +| -------- | -------- | -------- | -------- | +| SENSOR_TYPE_ACCELEROMETER | 加速度传感器 | 测量三个物理轴（x、y 和 z）上，施加在设备上的加速度（包括重力加速度），单位 : m/s2 | 检测运动状态 | +| SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED | 未校准加速度传感器 | 测量三个物理轴（x、y 和 z）上，施加在设备上的未校准的加速度（包括重力加速度），单位 : m/s2 | 检测加速度偏差估值 | +| SENSOR_TYPE_LINEAR_ACCELERATION | 线性加速度传感器 | 测量三个物理轴（x、y 和 z）上，施加在设备上的线性加速度（不包括重力加速度），单位 : m/s2 | 检测每个单轴方向上的线性加速度 | +| SENSOR_TYPE_GRAVITY | 重力传感器 | 测量三个物理轴（x、y 和 z）上，施加在设备上的重力加速度，单位 : m/s2 | 测量重力大小 | +| SENSOR_TYPE_GYROSCOPE | 陀螺仪传感器 | 测量三个物理轴（x、y 和 z）上，设备的旋转角速度，单位 : rad/s | 测量旋转的角速度 | +| SENSOR_TYPE_GYROSCOPE_UNCALIBRATED | 未校准陀螺仪传感器 | 测量三个物理轴（x、y 和 z）上，设备的未校准旋转角速度，单位 : rad/s | 测量旋转的角速度及偏差估值 | +| SENSOR_TYPE_SIGNIFICANT_MOTION | 大幅度动作传感器 | 测量三个物理轴（x、y 和 z）上，设备是否存在大幅度运动；如果取值为1则代表存在大幅度运动，取值为0则代表没有大幅度运动 | 用于检测设备是否存在大幅度运动 | +| SENSOR_TYPE_DROP_DETECTION | 跌落检测传感器 | 检测设备的跌落状态；如果取值为1则代表发生跌落，取值为0则代表没有发生跌落 | 用于检测设备是否发生了跌落 | +| SENSOR_TYPE_PEDOMETER_DETECTION | 计步器检测传感器 | 检测用户的计步动作；如果取值为1则代表用户产生了计步行走的动作；取值为0则代表用户没有发生运动 | 用于检测用户是否有计步的动作 | +| SENSOR_TYPE_PEDOMETER | 计步器传感器 | 统计用户的行走步数 | 用于提供用户行走的步数数据 | + + + **表2** 环境类-ohos.sensor.agent.CategoryOrientationAgent + +| 传感器类型 | 中文描述 | 说明 | 主要用途 | +| -------- | -------- | -------- | -------- | +| SENSOR_TYPE_AMBIENT_TEMPERATURE | 环境温度传感器 | 测量环境温度，单位 : 摄氏度 (°C) | 测量环境温度 | +| SENSOR_TYPE_MAGNETIC_FIELD | 磁场传感器 | 测量三个物理轴向（x、y、z）上，环境地磁场，单位 : μT | 创建指南针 | +| SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED | 未校准磁场传感器 | 测量三个物理轴向（x、y、z）上，未校准环境地磁场，单位 : μT | 测量地磁偏差估值 | +| SENSOR_TYPE_HUMIDITY | 湿度传感器 | 测量环境的相对湿度，以百分比 (%) 表示 | 监测露点、绝对湿度和相对湿度 | +| SENSOR_TYPE_BAROMETER | 气压计传感器 | 测量环境气压，单位 : hPa 或 mbar | 测量环境气压 | +| SENSOR_TYPE_SAR | 比吸收率传感器 | 测量比吸收率，单位：W/kg | 测量设备的电磁波能量吸收比值。 | + + + **表3** 方向类-ohos.sensor.agent.CategoryOrientationAgent + +| 传感器类型 | 中文描述 | 说明 | 主要用途 | +| -------- | -------- | -------- | -------- | +| SENSOR_TYPE_6DOF | 自由度传感器 | 测量上下、前后、左右方向上的位移，单位：m或mm；测量俯仰、偏摆、翻滚的角度，单位：rad | 检测设备的三个平移自由度以及旋转自由度，用于目标定位追踪，如：VR | +| SENSOR_TYPE_SCREEN_ROTATION | 屏幕旋转传感器 | 检测设备屏幕的旋转状态 | 用于检测设备屏幕是否发生了旋转 | +| SENSOR_TYPE_DEVICE_ORIENTATION | 设备方向传感器 | 测量设备的旋转方向，单位：rad | 用于检测设备旋转方向的角度值 | +| SENSOR_TYPE_ORIENTATION | 方向传感器 | 测量设备围绕所有三个物理轴（x、y、z）旋转的角度值，单位：rad | 用于提供屏幕旋转的3个角度值 | +| SENSOR_TYPE_ROTATION_VECTOR | 旋转矢量传感器 | 测量设备旋转矢量，复合传感器：由加速度传感器、磁场传感器、陀螺仪传感器合成 | 检测设备相对于东北天坐标系的方向 | +| SENSOR_TYPE_GAME_ROTATION_VECTOR
SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR | 游戏旋转矢量传感器
地磁旋转矢量传感器 | 测量设备游戏旋转矢量，复合传感器：由加速度传感器、陀螺仪传感器合成
测量设备地磁旋转矢量，复合传感器：由加速度传感器、磁场传感器合成 | 应用于游戏场景
用于测量地磁旋转矢量 | + + + **表4** 光线类-ohos.sensor.agent.CategoryLightAgent + +| 传感器类型 | 中文描述 | 说明 | 主要用途 | +| -------- | -------- | -------- | -------- | +| SENSOR_TYPE_PROXIMITY | 接近光传感器 | 测量可见物体相对于设备显示屏的接近或远离状态 | 通话中设备相对人的位置 | +| SENSOR_TYPE_TOF | ToF传感器 | 测量光在介质中行进一段距离所需的时间 | 人脸识别 | +| SENSOR_TYPE_AMBIENT_LIGHT | 环境光传感器 | 测量设备周围光线强度，单位：lux | 自动调节屏幕亮度，检测屏幕上方是否有遮挡 | +| SENSOR_TYPE_COLOR_TEMPERATURE | 色温传感器 | 测量环境中的色温 | 应用于设备的影像处理 | +| SENSOR_TYPE_COLOR_RGB | RGB颜色传感器 | 测量环境中的RGB颜色值 | 通过三原色的反射比率实现颜色检测 | +| SENSOR_TYPE_COLOR_XYZ | XYZ颜色传感器 | 测量环境中的XYZ颜色值 | 用于辨识真色色点，还原色彩更真实 | + + + **表5** 健康类-ohos.sensor.agent.CategoryBodyAgent + +| 传感器类型 | 中文描述 | 说明 | 主要用途 | +| -------- | -------- | -------- | -------- | +| SENSOR_TYPE_HEART_RATE | 心率传感器 | 测量用户的心率数值 | 用于提供用户的心率健康数据 | +| SENSOR_TYPE_WEAR_DETECTION | 佩戴检测传感器 | 检测用户是否佩戴 | 用于检测用户是否佩戴智能穿戴 | + + + **表6** 其他 + +| 传感器类型 | 中文描述 | 说明 | 主要用途 | +| -------- | -------- | -------- | -------- | +| SENSOR_TYPE_HALL | 霍尔传感器 | 测量设备周围是否存在磁力吸引 | 设备的皮套模式 | +| SENSOR_TYPE_GRIP_DETECTOR | 手握检测传感器 | 检测设备是否有抓力施加 | 用于检查设备侧边是否被手握住 | +| SENSOR_TYPE_MAGNET_BRACKET | 磁铁支架传感器 | 检测设备是否被磁吸 | 检测设备是否位于车内或者室内 | +| SENSOR_TYPE_PRESSURE_DETECTOR | 按压检测传感器 | 检测设备是否有压力施加 | 用于检测设备的正上方是否存在按压 | + + +## 运作机制 + +OpenHarmony传感器包含如下四个模块：Sensor API、Sensor Framework、Sensor Service和HD_IDL层。 + + **图1** OpenHarmony传感器 + ![zh-cn_image_0000001226521897](figures/zh-cn_image_0000001226521897.png) + +- Sensor API：提供传感器的基础API，主要包含查询传感器列表，订阅/取消传感器的数据、执行控制命令等，简化应用开发。 + +- Sensor Framework：主要实现传感器的订阅管理，数据通道的创建、销毁、订阅与取消订阅，实现与SensorService的通信。 + +- Sensor Service：主要实现HD_IDL层数据接收、解析、分发，前后台的策略管控，对该设备Sensor的管理，Sensor权限管控等。 + +- HD_IDL层：对不同的FIFO、频率进行策略选择，以及适配不同设备。 + + +## 约束与限制 + +1.针对下面所列传感器，开发者需要请求响应的权限，才能获取到相应传感器的数据。 + + + **表7** 传感器数据权限 + +| 传感器 | 权限名 | 敏感级别 | 权限描述 | +| -------- | -------- | -------- | -------- | +| 加速度传感器，加速度未校准传感器，线性加速度传感器 | ohos.permission.ACCELEROMETER | system_grant | 允许订阅Motion组对应的加速度传感器的数据 | +| 陀螺仪传感器，陀螺仪未校准传感器 | ohos.permission.GYROSCOPE | system_grant | 允许订阅Motion组对应的陀螺仪传感器的数据 | +| 计步器 | ohos.permission.ACTIVITY_MOTION | user_grant | 允许订阅运动状态 | +| 心率计 | ohos.permission.READ_HEALTH_DATA | user_grant | 允许读取健康数据 | + + +2. 传感器数据订阅和取消订阅接口成对调用，当不再需要订阅传感器数据时，开发者需要调用取消订阅接口停止数据上报。 diff --git a/zh-cn/application-dev/device/vibrator-guidelines.md b/zh-cn/application-dev/device/vibrator-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..60c290835eee87723194f1a7859ca54ccf89208f --- /dev/null +++ b/zh-cn/application-dev/device/vibrator-guidelines.md @@ -0,0 +1,84 @@ +# Vibrator开发指导 + + +## 场景介绍 + +当设备需要设置不同的振动效果时，可以调用Vibrator模块，例如：设备的按键可以设置不同强度和不同时长的振动，闹钟和来电可以设置不同强度和时长的单次或周期振动。 + + +## 接口说明 + + | 模块 | 接口名 | 描述 | +| -------- | -------- | -------- | +| ohos.vibrator | vibrate(duration: number): Promise<void> | 触发马达按照时长振动，Promise型。 | +| ohos.vibrator | vibrate(duration: number, callback?: AsyncCallback<void>): void | 触发马达按照时长振动，Callback型。 | +| ohos.vibrator | vibrate(effectId: EffectId): Promise<void> | 触发马达按照指定字符串振动，Promise型。 | +| ohos.vibrator | vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void | 触发马达按照指定字符串振动，Callback型。 | +| ohos.vibrator | stop(stopMode: VibratorStopMode): Promise<void> | 停止振动。 | +| ohos.vibrator | stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void | 停止振动。 | + + +## 开发步骤 + +1. 控制设备上的振动器，需要在“config.json”里面进行配置请求权限。具体如下： + + ``` + ”reqPermissions“:[ + { + "name":"ohos.permission.ACCELEROMETER", + "reason"":"", + "usedScene":{ + "ability""[ + ".MainAbility" + ], + "when":"inuse" + } + }, + { + "name":"ohos.permission.VIBRATE", + "reason"":"", + "usedScene":{ + "ability""[ + ".MainAbility" + ], + "when":"inuse" + } + }, + { + "name":"ohos.permission.ACTIVITY_MOTION", + "reason"":"", + "usedScene":{ + "ability""[ + ".MainAbility" + ], + "when":"inuse" + } + }, + ] + ``` + +2. 触发设备振动。 + + ``` + import vibrator from "@ohos.vibrator" + vibrator.vibrate(duration: number).then((error)=>{ + if(error){//调用失败，打印error.code和error.message + console.log("Promise return faild.error.code"+error.code+"error.message"+error.message); + }else{//调用成功,设备开始振动 + console.log("Promise returned to indicate a successful vibration.") + }; + }) + ``` + +3. 停止设备振动。 + + ``` + import vibrator from "@ohos.vibrator" + vibrator.stop(stopMode: VibratorStopMode).then((error)=>{ + if(error){//调用失败，打印error.code和error.message + console.log(“Promise return faild.error.code”+error.code+“error.message”+error.message); + }else{//调用成功，设备停止振动 + Console.log(“Promise returned to indicate successful.”); + }; + }) + ``` diff --git a/zh-cn/application-dev/device/vibrator-overview.md b/zh-cn/application-dev/device/vibrator-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..8817a737a10b247a9663e3e9f1937625af3b9cb5 --- /dev/null +++ b/zh-cn/application-dev/device/vibrator-overview.md @@ -0,0 +1,25 @@ +# Vibrator开发概述 + + +马达振动服务最大化开放硬工最新马达器件能力，通过拓展原生马达服务实现振动与交互融合设计，打造细腻精致的一体化振动体验和差异化体验，提升用户交互效率和易用性、提升用户体验、增强品牌竞争力。 + + +## 运作机制 + +Vibrator属于控制类小器件，主要包含以下四个模块：Vibrator API，Vibrator Framework，Vibrator Service和HD_IDL层。 + + **图1** 控制类小器件中的Vibrator + ![zh-cn_image_0000001180249428](figures/zh-cn_image_0000001180249428.png) + +- Vibrator API：提供振动器基础的API，主要包含振动器的列表查询，振动器的振动器效果查询，触发/关闭振动器等接口。 + +- Vibrator Framework：实现振动器的框架层管理，实现与控制类小器件Service的通信。 + +- Vibrator Service：实现控制器的服务管理。 + +- HD_IDL层：适配不同设备。 + + +## 约束与限制 + +在使用振动器时，开发者需要配置请求振动器的权限ohos.permission.VIBRATE，才能控制振动器振动。 diff --git a/zh-cn/application-dev/internationalization/Readme-CN.md b/zh-cn/application-dev/internationalization/Readme-CN.md new file mode 100644 index 0000000000000000000000000000000000000000..61b9279c0dd6ecaeab5c7b8808397b10e53f96f0 --- /dev/null +++ b/zh-cn/application-dev/internationalization/Readme-CN.md @@ -0,0 +1,5 @@ +# 国际化 + +- [国际化开发概述](international-overview.md) +- [Intl开发指导](intl-guidelines.md) +- [I18n开发指导](i18n-guidelines.md) diff --git a/zh-cn/application-dev/internationalization/i18n-guidelines.md b/zh-cn/application-dev/internationalization/i18n-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..28d64fe9b7cc727fc1bdca1b83740e7de7337cb1 --- /dev/null +++ b/zh-cn/application-dev/internationalization/i18n-guidelines.md @@ -0,0 +1,363 @@ +# I18n开发指导 + + +## 获取系统语言区域信息 + +调用系统提供的接口访问系统的语言区域信息。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.i18n | getSystemLanguage(): string | 获取系统语言。 | +| ohos.i18n | getSystemRegion(): string | 获取系统区域。 | +| ohos.i18n | getSystemLocale(): string | 获取系统Locale。 | +| ohos.i18n | isRTL(locale: string): boolean7+ | locale对应的语言是否为从右到左语言。 | +| ohos.i18n | is24HourClock(): boolean7+ | 获取当前系统时间是否采用24小时制 | +| ohos.i18n | getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string | 获取语言的本地化表示。 | +| ohos.i18n | getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string | 获取国家的本地化表示。 | + + +### 开发步骤 + +1. 获取系统语言 + 调用getSystemLanguage方法获取当前系统设置的语言（i18n为导入的模块）。 + + + ``` + var language = i18n.getSystemLanguage(); + ``` + +2. 获取系统区域 + 调用getSystemRegion方法获取当前系统设置的区域 + + ``` + var region = i18n.getSystemRegion(); + ``` + +3. 获取系统Locale + 调用getSystemLocale方法获取当前系统设置的Locale + + ``` + var locale = i18n.getSystemLocale(); + ``` + +4. 判断Locale的语言是否为RTL语言 + 调用isRTL方法获取Locale的语言是否为从右到左语言。 + + + ``` + var rtl = i18n.isRTL("zh-CN"); + ``` + +5. 判断当前系统时间是否采用24小时制 + 调用is24HourClock方法来判断当前系统的时间是否采用24小时制。 + + ``` + var hourClock = i18n.is24HourClock(); + ``` + +6. 获取语言的本地化表示 + 调用getDisplayLanguage方法获取某一语言的本地化表示。其中，language表示待本地化显示的语言，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。 + + ``` + var language = "en"; + var locale = "zh-CN"; + var sentenceCase = false; + var localizedLanguage = i18n.getDisplayLanguage(language, locale, sentenceCase); + ``` + +7. 获取国家的本地化表示 + 调用getDisplayCountry方法获取某一国家的本地化表示。其中，country表示待本地化显示的国家，locale表示本地化的Locale，sentenceCase结果是否需要首字母大写。 + + ``` + var country = "US"; + var locale = "zh-CN"; + var sentenceCase = false; + var localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase); + ``` + + +## 获取日历信息 + +调用日历[Calendar](../reference/apis/js-apis-intl.md)相关接口来获取日历的相关信息，例如获取日历的本地化显示、一周起始日、一年中第一周的最小天数等。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.i18n | getCalendar(locale: string, type?: string): Calendar8+ | 获取指定locale和type的日历对象。 | +| ohos.i18n | setTime(date: Date)8+ | 设置日历对象内部的时间日期。 | +| ohos.i18n | setTime(time: number)8+ | 设置日历对象内部的时间日期。 | +| ohos.i18n | set(year: number, month: number, date: number, hour?: number, minute?: number, second?: number)8+ | 设置日历对象的年、月、日、时、分、秒。 | +| ohos.i18n | setTimeZone(timezone: string)8+ | 设置日历对象的时区。 | +| ohos.i18n | getTimeZone(): string8+ | 获取日历对象的时区。 | +| ohos.i18n | getFirstDayOfWeek(): number8+ | 获取日历对象的一周起始日。 | +| ohos.i18n | setFirstDayOfWeek(value: number)8+ | 设置日历对象的一周起始日。 | +| ohos.i18n | getMinimalDaysInFirstWeek(): number8+ | 获取一年中第一周的最小天数。 | +| ohos.i18n | setMinimalDaysInFirstWeek(value: number)8+ | 设置一年中第一周的最小天数。 | +| ohos.i18n | getDisplayName(locale: string): string8+ | 获取日历对象的本地化表示。 | +| ohos.i18n | isWeekend(date?: Date): boolean8+ | 判断给定的日期是否在日历中是周末。 | + + +### 开发步骤 + +1. 实例化日历对象 + 调用getCalendar方法获取指定locale和type的时区对象（i18n为导入的模块）。其中，type表示合法的日历类型，目前合法的日历类型包括："buddhist", "chinese", "coptic", "ethiopic", "hebrew", "gregory", "indian", "islamic_civil", "islamic_tbla", "islamic_umalqura", "japanese", "persian"。当type没有给出时，采用区域默认的日历类型。 + + + ``` + var calendar = i18n.getCalendar("zh-CN", "gregory); + ``` + +2. 设置日历对象的时间 + 调用setTime方法设置日历对象的时间。setTime方法接收两种类型的参数。一种是传入一个Date对象，另一种是传入一个数值表示从1970.1.1 00:00:00 GMT逝去的毫秒数。 + + ``` + var date1 = new Date(); + calendar.setTime(date1); + var date2 = 1000; + calendar.setTime(date2); + ``` + +3. 设置日历对象的年、月、日、时、分、秒 + 调用set方法设置日历对象的年、月、日、时、分、秒。 + + ``` + calendar.set(2021, 12, 21, 6, 0, 0) + ``` + +4. 设置、获取日历对象的时区 + 调用setTimeZone方法和getTimeZone方法来设置、获取日历对象的时区。其中，setTimeZone方法需要传入一个字符串表示需要设置的时区。 + + + ``` + calendar.setTimeZone("Asia/Shanghai"); + var timezone = calendar.getTimeZone(); + ``` + +5. 设置、获取日历对象的一周起始日 + 调用setFirstDayOfWeek方法和getFirstDayOfWeek方法设置、获取日历对象的一周起始日。其中，setFirstDayOfWeek需要传入一个数值表示一周的起始日，1代表周日，7代表周六。 + + + ``` + calendar.setFirstDayOfWeek(1); + var firstDayOfWeek = calendar.getFirstDayOfWeek(); + ``` + +6. 设置、获取日历对象第一周的最小天数 + 调用setMinimalDaysInFirstWeek方法和getMinimalDaysInFirstWeek方法来设置、获取日历对象第一周的最小天数。 + + ``` + calendar.setMinimalDaysInFirstWeek(3); + var minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); + ``` + +7. 获取日历对象的本地化显示 + 调用getDisplayName来获取日历对象的本地化显示。 + + + ``` + var localizedName = calendar.getDisplayName("zh-CN"); + ``` + +8. 判断某一个日期是否为周末 + 调用isWeekend方法来判断输入的Date是否为周末。 + + + ``` + var date = new Date(); + var weekend = calendar.isWeekend(date); + ``` + + +## 电话号码格式化 + +调用电话号码格式化[PhoneNumberFormat](../reference/apis/js-apis-intl.md)的接口，实现对针对不同国家电话号码的格式化以及判断电话号码格式是否正确的功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.i18n | constructor(country: string, options?: PhoneNumberFormatOptions)8+ | 实例化PhoneNumberFormat对象。 | +| ohos.i18n | isValidNumber(number: string): boolean8+ | 判断number是否是一个格式正确的电话号码。 | +| ohos.i18n | format(number: string): string8+ | 对number按照指定国家及风格进行格式化。 | + + +### 开发步骤 + +1. 实例化电话号码格式化对象 + 调用PhoneNumberFormat的构造函数来实例化电话号码格式化对象，需要传入电话号码的国家代码及格式化选项。其中，格式化选项是可选的，包括style选项，该选项的取值包括："E164", "INTERNATIONAL", "NATIONAL", "RFC3966"。 + + + ``` + var phoneNumberFormat = new i18n.PhoneNubmerFormat("CN", {type: "E164"}); + ``` + +2. 判断电话号码格式是否正确 + 调用isValidNumber方法来判断输入的电话号码的格式是否正确。 + + ``` + var validNumber = phoneNumberFormat.isValidNumber("15812341234"); + ``` + +3. 电话号码格式化 + 调用电话号码格式化对象的format方法来对输入的电话号码进行格式化。 + + ``` + var formattedNumber = phoneNumberFormat.format("15812341234"); + ``` + + +## 度量衡转换 + +度量衡转换接口可以实现度量衡转换的相关功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.i18n | unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string8+ | 将fromUnit的单位转换为toUnit的单位，并根据区域与风格进行格式化。 | + + +### 开发步骤 + +1. 度量衡单位转换 + 调用[unitConvert](../reference/apis/js-apis-intl.md)方法实现度量衡单位转换，并进行格式化显示的功能。 + + + ``` + var fromUnit = {unit: "cup", measureSystem: "US"}; + var toUnit = {unit: "liter", measureSystem: "SI"}; + var number = 1000; + var locale = "en-US"; + var style = "long"; + i18n.Util.unitConvert(fromUtil, toUtil, number, locale, style); + ``` + + +## 字母表索引 + +调用字母表索引[IndexUtil](../reference/apis/js-apis-intl.md)的接口可以获取不同Locale的字母表索引，以及实现计算字符串所属索引的功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.i18n | getInstance(locale?: string): IndexUtil8+ | 实例化字母表索引对象。 | +| ohos.i18n | getIndexList(): Array<string>8+ | 获取当前Locale的索引列表。 | +| ohos.i18n | addLocale(locale: string)8+ | 将新的Locale对应的索引加入当前索引列表。 | +| ohos.i18n | getIndex(text: string): string8+ | 获取text对应的索引。 | + + +### 开发步骤 + +1. 实例化字母表索引对象 + 调用getInstance方法来实例化特定locale对应的字母表索引对象。当locale参数为空时，实例化系统默认Locale的字母表索引对象。 + + + ``` + var indexUtil = getInstance("zh-CN"); + ``` + +2. 获取索引列表 + 调用getIndexList方法来获取当前Locale对应的字母表索引列表。 + + ``` + var indexList = indexUtil.getIndexList(); + ``` + +3. 增加新的索引 + 调用addLocale方法，将新的Locale对应的字母表索引添加到当前字母表索引列表中。 + + ``` + indexUtil.addLocale("ar") + ``` + +4. 获取字符串对应的索引 + 调用getIndex方法来获取某一字符串对应的字母表索引。 + + ``` + var text = "access index"; + indexUtil.getIndex(text); + ``` + + +## 获取文本断点位置 + +当文本比较长无法在一行进行显示时，调用文本断点[BreakIterator8](../reference/apis/js-apis-intl.md)的接口，来获取文本可以断行的位置。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.i18n | getLineInstance(locale: string): BreakIterator8+ | 实例化断行对象。 | +| ohos.i18n | setLineBreakText(text: string)8+ | 设置要处理的文本。 | +| ohos.i18n | getLineBreakText(): string8+ | 获取要处理的文本。 | +| ohos.i18n | current(): number8+ | 获取当前断行对象在处理文本的位置。 | +| ohos.i18n | first(): number8+ | 将断行对象设置到第一个可断句的分割点。 | +| ohos.i18n | last(): number8+ | 将断行对象设置到最后一个可断句的分割点。 | +| ohos.i18n | next(index?: number): number8+ | 将断行对象移动index个分割点的位置。 | +| ohos.i18n | previous(): number8+ | 将断行对象移动到前一个分割点的位置。 | +| ohos.i18n | following(offset: number): number8+ | 将断行对象移动到offset指定位置的后面一个分割点的位置。 | +| ohos.i18n | isBoundary(offset: number): boolean8+ | 判断某个位置是否是分割点。 | + + +### 开发步骤 + +1. 实例化断行对象 + 调用getLineInstance方法来实例化断行对象。 + + + ``` + var locale = "en-US" + var breakIterator = i18n.getLineInstance(locale); + ``` + +2. 设置、访问要断行处理的文本 + 调用setLineBreakText方法和getLineBreakText方法来设置、访问要断行处理的文本。 + + + ``` + var text = "Apple is my favorite fruit"; + breakIterator.setLineBreakText(text); + var breakText = breakIterator.getLineBreakText(); + ``` + +3. 获取断行对象当前的位置 + 调用current方法来获取断行对象在当前处理文本中的位置。 + + + ``` + var pos = breakIterator.current(); + ``` + +4. 设置断行对象的位置 + 系统提供了很多接口可以用于调整断行对象在处理文本中的位置，包括first, last, next, previous, following。 + + + ``` + var firstPos = breakIterator.first(); // 将断行对象设置到第一个分割点的位置，即文本的起始位置； + var lastPos = breakIterator.last(); // 将断行对象设置到最后一个分割点的位置，即文本末尾的下一个位置； + // 将断行对象向前或向后移动一定数量的分割点。 + // 当传入正数时，向后移动；当传入负数时，向前移动；当未传入数值时，则向后移动一个位置； + // 当移动超出了文本的长度范围，则返回-1； + var nextPos = breakIterator.next(-2); + var previousPos = breakIterator.previous(); // 将断行对象向前移动向前移动一个分割点，当超出文本长度范围时返回-1； + // 将断行对象移动到offset指定位置的后面一个分割点。如果offset所指定的位置的下一个分割点超出了文本的长度范围，则返回-1； + var followingPos = breakIterator.following(10); + ``` + +5. 判断某个位置是否为分割点 + 调用isBoundary方法来判断一个方法是否为分割点；如果该位置是分割点，则返回true，并且将断行对象移动到该位置；如果该位置不是分割点，则返回false，并且将断行对象移动到该位置后的一个分割点。 + + + ``` + var isboundary = breakIterator.isBoundary(5); + ``` diff --git a/zh-cn/application-dev/internationalization/international-overview.md b/zh-cn/application-dev/internationalization/international-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..920da61ba06b3db2a87b19a24ac5290219a096e3 --- /dev/null +++ b/zh-cn/application-dev/internationalization/international-overview.md @@ -0,0 +1,24 @@ +# 国际化开发概述 + + +当应用具有多个在语言、时区、区域特性等方面存在显著差异的目标用户和市场时，开发者往往需要提供应用的多个本地化版本，以保证不同地区用户的体验。 + + +应用的国际化能力决定了应用本地化过程的难易程度。系统提供了一系列的国际化接口，基于这些国际化接口，开发者可以设计并实现具有良好国际化能力的应用，从而可以高效、低成本的实现应用的本地化。 + + +## 基本概念 + +- Locale：Locale是对一个群体在语言、脚本、国家或区域，以及日历、排序、货币等区域特性方面的共性的抽象表示。 + +- 偏好语言：偏好语言是用户设置过的语言，表示该语言是用户可接受的语言。用户可以在 设置/系统和更新/语言和输入法/语言和地区/添加语言中添加偏好语言。 + + +## 运作机制 + +在调用国际化接口时，需要提供Locale信息，接口会依据该Locale的特性进行差异化的执行。Locale信息可以由开发人员通过硬编码的方式提供，但更通常的情况是使用用户设置的系统语言和区域。 + + +## 约束与限制 + +无 diff --git a/zh-cn/application-dev/internationalization/intl-guidelines.md b/zh-cn/application-dev/internationalization/intl-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..ca13f2f31612bdd8d15401e0d9a3d12a0261b700 --- /dev/null +++ b/zh-cn/application-dev/internationalization/intl-guidelines.md @@ -0,0 +1,302 @@ +# Intl开发指导 + + +## 设置区域信息 + +调用[Locale](../reference/apis/js-apis-intl.md)的相关接口实现最大化区域信息或最小化区域信息。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 实例化Locale对象。 | +| ohos.intl | constructor(locale: string, options?: LocaleOptions) | 基于locale参数及其选项实例化Locale对象。 | +| ohos.intl | toString(): string | 将Locale信息转换为字符串。 | +| ohos.intl | maximize(): Locale | 最大化区域信息。 | +| ohos.intl | minimize(): Locale | 最小化区域信息。 | + + +### 开发步骤 + +1. 实例化Locale对象 + 使用Locale的构造函数创建Locale对象，该方法接收一个表示Locale的字符串及可选的[属性](../reference/apis/js-apis-intl.md)列表（intl为导入的模块名）。 + + + ``` + var locale = "zh-CN"; + var options = {caseFirst: false, calendar: "chinese", collation: pinyin}; + var localeObj = new intl.Locale(locale, options); + ``` + +2. 获取Locale的字符串表示 + 调用toString方法来获取Locale对象的字符串表示，其中包括了语言、区域及其他选项信息。 + + ``` + var localeStr = localeObj.toString(); + ``` + +3. 最大化区域信息 + 调用maximize方法来最大化区域信息，即当缺少脚本与地区信息时，对其进行补全。 + + ``` + var maximizedLocale = localeObj.maximize(); + ``` + +4. 最小化区域信息 + 调用minimize方法来最大化区域信息，即当存在脚本与地区信息时，对其进行删除。 + + ``` + var minimizedLocale = localeObj.minimize(); + ``` + + +## 格式化日期时间 + +调用日期时间格式化[DateTimeFormat](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的日期格式化以及时间段格式化功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 创建日期时间格式化对象。 | +| ohos.intl | constructor(locale: string \| Array, options?: DateTimeOptions) | 创建日期时间格式化对象，并设置提供的Locale和格式化相关属性。 | +| ohos.intl | format(date: Date): string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算日期时间的格式化表示。 | +| ohos.intl | formatRange(startDate: Date, endDate: Date): string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算时间段的格式化表示。 | +| ohos.intl | resolvedOptions(): DateTimeOptions | 获取DateTimeFormat对象的相关属性。 | + + +### 开发步骤 + +1. 实例化日期时间格式化对象 + 一种方法是使用DateTimeFormat提供的默认构造函数，通过访问系统语言和地区设置，获取系统默认Locale，并将其作为DateTimeFormat对象内部的Locale（intl为导入的模块名）。 + + + ``` + var dateTimeFormat = new intl.DateTimeFormat(); + ``` + + 另一种方法是使用开发者提供的Locale和格式化参数来创建日期时间格式化对象。其中，格式化参数是可选的，完整的格式化参数列表见[DateTimeOptions](../reference/apis/js-apis-intl.md)。 + + ``` + var options = {dateStyle: "full", timeStyle: "full"}; + var dateTimeFormat = new intl.DateTimeFormat("zh-CN", options); + ``` + +2. 格式化日期时间 + 使用DateTimeFormat的format方法对一个Date对象进行格式化，该方法会返回一个字符串作为格式化的结果。 + + ``` + Date date = new Date(); + var formatResult = dateTimeFormat.format(date); + ``` + +3. 格式化时间段 + 使用DateTimeFormat的formatRange方法对一个时间段进行格式化。该方法需要传入两个Date对象，分别表示时间段的起止时间，返回一个字符串作为格式化的结果。 + + ``` + Date startDate = new Date(); + Date endDate = new Date(); + var formatResult = dateTimeFormat.formatRange(startDate, endDate); + ``` + +4. 访问日期时间格式化对象的相关属性 + DateTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了DateTimeFormat对象的所有相关属性及其值。 + + ``` + var options = dateTimeFormat.resolvedOptions(); + ``` + + +## 数字格式化 + +调用数字格式化[NumberFormat](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的数字格式化功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 创建数字格式化对象。 | +| ohos.intl | constructor(locale: string \| Array, options?: NumberOptions) | 创建数字格式化对象，并设置提供的locale和格式化相关属性。 | +| ohos.intl | format(number: number): string | 依据NumberFormat对象的Locale及其他格式化属性，计算数字的格式化表示。 | +| ohos.intl | resolvedOptions(): NumberOptions | 获取NumberFormat对象的相关属性。 | + + +### 开发步骤 + +1. 实例化数字格式化对象 + 一种方法是使用NumberFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 + + + ``` + var numberFormat = new intl.NumberFormat(); + ``` + + 另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中，格式化参数是可选的，完整的格式化参数列表参见[NumberOptions](../reference/apis/js-apis-intl.md)。 + + ``` + var options = {compactDisplay: "short", notation: "compact"}; + var numberFormat = new intl.NumberFormat("zh-CN", options); + ``` + +2. 数字格式化 + 使用NumberFormat的format方法对传入的数字进行格式化。该方法返回一个字符串作为格式化的结果。 + + ``` + var number = 1234.5678 + var formatResult = numberFormat.format(number); + ``` + +3. 访问数字格式化对象的相关属性 + NumberFormat的resolvedOptions方法会返回一个对象，该对象包含了NumberFormat对象的所有相关属性及其值。 + + ``` + var options = numberFormat.resolvedOptions(); + ``` + + +## 字符串排序 + +不同区域的用户对于字符串排序具有不同的需求。调用字符串排序[Collator](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的字符串排序功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 创建排序对象。 | +| ohos.intl | constructor(locale: string \| Array, options?: CollatorOptions)8+ | 创建排序对象，并设置提供的locale和其他相关属性。 | +| ohos.intl | compare(first: string, second: string): number8+ | 依据排序对象的Locale及其属性，计算两个字符串的比较结果。 | +| ohos.intl | resolvedOptions(): CollatorOptions8+ | 获取排序对象的相关属性。 | + + +### 开发步骤 + +1. 实例化排序对象 + 一种方法是使用Collator提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 + + + ``` + var collator = new intl.Collator(); + ``` + + 另一种方法是使用开发者提供的Locale和其他相关参数来创建Collator对象，完整的参数列表参见[CollatorOptions](../reference/apis/js-apis-intl.md)。 + + ``` + var collator= new intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"}; + ``` + +2. 比较字符串 + 使用Collator的compare方法对传入的两个字符串进行比较。该方法返回一个数值作为比较的结果，返回-1表示第一个字符串小于第二个字符串，返回1表示第一个字符大于第二个字符串，返回0表示两个字符串相同。 + + ``` + var str1 = "first string"; + var str2 = "second string"; + var compareResult = collator.compare(str1, str2); + ``` + +3. 访问排序对象的相关属性 + Collator的resolvedOptions方法会返回一个对象，该对象包含了Collator对象的所有相关属性及其值。 + + ``` + var options = collator.resolvedOptions(); + ``` + + +## 判定单复数类别 + +在一些语言的语法中，当数字后面存在名词时，名词需要根据数字的值采用不同的形式。调用单复数[PluralRules](../reference/apis/js-apis-intl.md)的接口，可以实现针对特定Locale计算数字单复数类别的功能，从而选择合适的名词单复数表示。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 创建单复数对象。 | +| ohos.intl | constructor(locale: string \| Array, options?: PluralRulesOptions)8+ | 创建单复数对象，并设置提供的locale和其他相关属性。 | +| ohos.intl | select(n: number): string8+ | 依据单复数对象的Locale及其他格式化属性，计算数字的单复数类别。 | + + +### 开发步骤 + +1. 实例化单复数对象 + 一种方法是使用PluralRules提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 + + + ``` + var pluralRules = new intl.PluralRules(); + ``` + + 另一种方法是使用开发者提供的Locale和其他相关参数来创建单复数对象，完整的参数列表参见[PluralRulesOptions](../reference/apis/js-apis-intl.md)。 + + ``` + var plurals = new intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"}; + ``` + +2. 计算数字单复数类别 + 使用PluralRules的select方法计算传入数字的单复数类别。该方法返回一个字符串作为传入数字的类别，包括："zero", "one", "two", "few", "many", "other"六个类别。 + + ``` + var number = 1234.5678 + var categoryResult = plurals.select(number); + ``` + + +## 相对时间格式化 + +调用相对时间格式化[RelativeTimeFormat](../reference/apis/js-apis-intl.md)的接口，实现针对特定Locale的相对时间格式化功能。 + + +### 接口说明 + +| 模块 | 接口名称 | 描述 | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 创建相对时间格式化对象。 | +| ohos.intl | constructor(locale: string \| Array, options?: RelativeTimeFormatInputOptions)8+ | 创建相对时间格式化对象，并设置提供的locale和格式化相关属性。 | +| ohos.intl | format(value: number, unit: string): string8+ | 依据相对时间格式化对象的Locale及其他格式化属性，计算相对时间的格式化表示。 | +| ohos.intl | formatToParts(value: number, unit: string): Array8+ | 依据相对时间格式化对象的Locale及其他格式化属性，返回相对时间格式化表示的各个部分。 | +| ohos.intl | resolvedOptions(): RelativeTimeFormatResolvedOptions8+ | 获取相对时间格式化对象的相关属性。 | + + +### 开发步骤 + +1. 实例化相对时间格式化对象 + 一种方法是使用RelativeTimeFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 + + + ``` + var relativeTimeFormat = new intl.RelativeTimeFormat(); + ``` + + 另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中，格式化参数是可选的，完整的参数列表参见[ RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md)。 + + ``` + var relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}; + ``` + +2. 相对时间格式化 + 使用RelativeTimeFormat的format方法对相对时间进行格式化。方法接收一个表示相对时间长度的数值和表示单位的字符串，其中单位包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。方法返回一个字符串作为格式化的结果。 + + ``` + var number = 2; + var unit = "year" + var formatResult = relativeTimeFormat.format(number, unit); + ``` + +3. 获取相对时间格式化结果的各个部分 + 获取相对时间格式化结果的各个部分，从而自定义格式化结果。 + + ``` + var number = 2; + var unit = "year" + var formatResult = relativeTimeFormat.formatToParts(number, unit); + ``` + +4. 相对时间格式化对象的相关属性 + RelativeTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了RelativeTimeFormat对象的所有相关属性及其值，完整的属性列表参见[ RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md)。 + + ``` + var options = numberFormat.resolvedOptions(); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-audio.md b/zh-cn/application-dev/reference/apis/js-apis-audio.md index 0d782ef00721e9e579cc36b817064ed831559fe1..848ddae588ed7df25aea071ee9a4b1b27eaf6ae2 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-audio.md +++ b/zh-cn/application-dev/reference/apis/js-apis-audio.md @@ -44,9 +44,9 @@ createAudioRenderer(options: AudioRendererOptions, callback: AsyncCallback\ | 是 | 音频渲染器对象。 | **示例：** @@ -135,9 +135,9 @@ createAudioCapturer(options: AudioCapturerOptions, callback: AsyncCallback