鴻蒙開(kāi)源第三方組件—日期和時(shí)間處理組件JodaTime-ohos

作者：朱偉ISRC 2021-06-29 09:28:16

文章由鴻蒙社區(qū)產(chǎn)出，想要了解更多內(nèi)容請(qǐng)前往：51CTO和華為官方戰(zhàn)略合作共建的鴻蒙技術(shù)社區(qū)https://harmonyos.51cto.com

[[407815]]

想了解更多內(nèi)容，請(qǐng)?jiān)L問(wèn)：

51CTO和華為官方合作共建的鴻蒙技術(shù)社區(qū)

https://harmonyos.51cto.com

前言

基于安卓平臺(tái)的日期和時(shí)間處理組件JodaTime-ohos(https://github.com/dlew/joda-time-android)，實(shí)現(xiàn)鴻蒙化遷移和重構(gòu)。代碼已經(jīng)開(kāi)源到(https://gitee.com/isrc_ohos/joda-time_ohos)，歡迎各位下載使用并提出寶貴意見(jiàn)!

背景

JodaTime-ohos是一個(gè)日期和時(shí)間處理組件，可以獲取標(biāo)準(zhǔn)時(shí)間、當(dāng)前時(shí)間、相對(duì)時(shí)間、格式化時(shí)間等多種形式的時(shí)間，并支持對(duì)各類時(shí)間進(jìn)行計(jì)算和判斷。該組件易于使用、可擴(kuò)展性強(qiáng)、擁有全面的功能集，支持多種日歷系統(tǒng)，被廣泛應(yīng)用于時(shí)間顯示類應(yīng)用。

組件效果展示

(1)顯示“標(biāo)準(zhǔn)時(shí)間”“一段時(shí)間”“格式化時(shí)間”“一段時(shí)間的相對(duì)表示”“一段時(shí)間的相對(duì)的字符串表示”“相對(duì)時(shí)間”

標(biāo)準(zhǔn)時(shí)間：程序執(zhí)行時(shí)刻的時(shí)間表示，見(jiàn)圖1中的a。
格式化時(shí)間：將日期/時(shí)間格式轉(zhuǎn)換為預(yù)先定義的日期/時(shí)間格式，見(jiàn)圖1中的b。
一段時(shí)間：在程序執(zhí)行時(shí)刻的基礎(chǔ)上，增加一段時(shí)間后的起始時(shí)間和結(jié)果時(shí)間顯示，見(jiàn)圖1中的c。
一段時(shí)間的相對(duì)表示：未來(lái)或者在過(guò)去的某個(gè)時(shí)間段表示，見(jiàn)圖1中的d。
一段時(shí)間的相對(duì)字符串表示：在程序執(zhí)行時(shí)刻的基礎(chǔ)上，增加一段時(shí)間的結(jié)果時(shí)間顯示，見(jiàn)圖1中的e。
相對(duì)時(shí)間：在程序執(zhí)行時(shí)刻的基礎(chǔ)上，增加一段時(shí)間后的結(jié)果時(shí)間和時(shí)間段表示，見(jiàn)圖1中的f。

圖1 顯示“標(biāo)準(zhǔn)時(shí)間”“一段時(shí)間”“格式化時(shí)間”“一段時(shí)間的相對(duì)表示”“一段時(shí)間的相對(duì)的字符串表示”“相對(duì)時(shí)間”

(2)顯示“當(dāng)前時(shí)間”、“是否為今天”

當(dāng)前時(shí)間：程序執(zhí)行時(shí)刻的年月日表示。同時(shí)也可以給出在當(dāng)前時(shí)間的基礎(chǔ)上增加一段時(shí)間后的結(jié)果表示，如圖2的a所示。
是否為今天：可以判斷程序執(zhí)行的日期是否為今天、是否為昨天、是否為明天，如圖2的b所示。

鴻蒙開(kāi)源第三方組件——日期和時(shí)間處理組件JodaTime-ohos-鴻蒙HarmonyOS技術(shù)社區(qū)

圖2 顯示“當(dāng)前時(shí)間”、“是否為今天”

(3)顯示“一段時(shí)間的格式化表示”

“一段時(shí)間的格式化表示”：將一段時(shí)間用對(duì)應(yīng)的單位表示出來(lái)。

圖3 顯示“一段時(shí)間的格式化表示”

Sample解析

1、工程結(jié)構(gòu)

圖4 Sample的工程結(jié)構(gòu)

從上圖可以看出，Sample的工程結(jié)構(gòu)主要分為三個(gè)部分：圖中第①部分的MainAbilitySlice主要負(fù)責(zé)構(gòu)建組件應(yīng)用的主頁(yè)面布局。主頁(yè)面上有9個(gè)按鈕，點(diǎn)擊不同的按鈕，會(huì)跳轉(zhuǎn)到不同的導(dǎo)航界面，每個(gè)界面顯示不同的時(shí)間格式，如圖5所示。

圖5 組件應(yīng)用的主頁(yè)面布局

圖中第②部分的內(nèi)容包含多個(gè)AbilitySlice，每一個(gè)AbilitySlice都對(duì)應(yīng)①中的一個(gè)導(dǎo)航界面。界面中會(huì)包含特定格式的時(shí)間顯示，如圖6所示。

圖6 按鈕導(dǎo)航界面

圖中第③部分內(nèi)容包含兩個(gè)文件：MainAbility是一切應(yīng)用的入口，通過(guò)setMainRoute()設(shè)置路由，將組件應(yīng)用的主界面設(shè)置為MainAbilitySlice。JodaTime則是為了創(chuàng)建示例接收時(shí)區(qū)變換的廣播。

// JodaTime 
try { 
    JodaTimeAndroid.init(this); //init方法用于創(chuàng)建示例接收時(shí)區(qū)變換的廣播 
} catch (RemoteException e) { 
    e.printStackTrace(); 
}

2、時(shí)間的獲取

JodaTime-ohos可以為開(kāi)發(fā)者提供9種不同格式的時(shí)間，下面我們以sampleGetRelativeTimeSpanStringslice為例，展示“一段時(shí)間的相對(duì)表示”時(shí)間的獲取，效果如上述圖1中的d所示。其余幾種時(shí)間格式的使用方法同理，不再贅述。

（1）導(dǎo)入相關(guān)類

在sampleGetRelativeTimeSpanStringslice導(dǎo)入DateTime類，并得到實(shí)例化對(duì)象，該類是時(shí)間日期獲取工具類。

//導(dǎo)入相關(guān)類DateTime 
import org.joda.time.DateTime; 
...... 
//實(shí)例化類對(duì)象 
DateTime now = DateTime.now();

（2）設(shè)置時(shí)間顯示布局

在sampleGetRelativeTimeSpanStringslice中創(chuàng)建一個(gè)DirectionalLayout布局，用于顯示獲取到的時(shí)間。

DirectionalLayout directionalLayout = new DirectionalLayout(this); 
...... 
@Override 
protected void onStart(Intent intent) { 
    super.onStart(intent); 
    //設(shè)置Layout的寬和高 
    directionalLayout.setWidth(ComponentContainer.LayoutConfig.MATCH_PARENT); 
    directionalLayout.setHeight(ComponentContainer.LayoutConfig.MATCH_PARENT); 
    directionalLayout.setPadding(32, 32, 80, 80); //設(shè)置Layout填充距離 
    ShapeElement element = new ShapeElement(); 
    element.setRgbColor(new RgbColor(255, 255, 255)); 
    directionalLayout.setBackground(element); //設(shè)置Layout背景 
    ...... 
}

（3）設(shè)置時(shí)間顯示控件

由于需要在布局中顯示多個(gè)時(shí)間結(jié)果，所以此處創(chuàng)建一個(gè)List，內(nèi)部元素為String類型，每個(gè)String元素表示一個(gè)時(shí)間結(jié)果。

List<String> text = new ArrayList<String>();

（4）獲取日期和時(shí)間值

通過(guò)上述創(chuàng)建的DateTime 類對(duì)象，分別調(diào)用類中不同的方法如plusMinutes()、minusMinutes()，在起始時(shí)間點(diǎn)的基礎(chǔ)上增加或減少一個(gè)固定的時(shí)間;后使用DateUtils類的getRelativeTimeSpanString()方法將獲得到日期和時(shí)間值以對(duì)應(yīng)的單位(時(shí)、分或秒)表示出來(lái)。

text.add("Short future: " + DateUtils.getRelativeTimeSpanString(this, now.plusMinutes(25)));//目前時(shí)間值基礎(chǔ)上增加分鐘數(shù) 
text.add("Medium future: " + DateUtils.getRelativeTimeSpanString(this, now.plusHours(5)));//目前時(shí)間值基礎(chǔ)上增加小時(shí)數(shù) 
text.add("Long future: " + DateUtils.getRelativeTimeSpanString(this, now.plusDays(3)));//目前時(shí)間值基礎(chǔ)上增加天數(shù) 
text.add("Short past: " + DateUtils.getRelativeTimeSpanString(this, now.minusMinutes(25)));//目前時(shí)間值基礎(chǔ)上減少分鐘數(shù) 
text.add("Medium past: " + DateUtils.getRelativeTimeSpanString(this, now.minusHours(5)));//目前時(shí)間值基礎(chǔ)上減少小時(shí)數(shù) 
text.add("Long past: " + DateUtils.getRelativeTimeSpanString(this, now.minusDays(3)));//目前時(shí)間值基礎(chǔ)上減少天數(shù)

（5）添加控件到布局中

將獲取到的日期和時(shí)間值添加到時(shí)間顯示布局DirectionalLayout中。

directionalLayout.addComponent(textT);

3、日期和時(shí)間常用類

第2小節(jié)的例子通過(guò)DateTime來(lái)獲取時(shí)間，通常情況下，在使用JodaTime_ohos組件的過(guò)程中，使用最多的日期時(shí)間獲取類共有5種，分別是：Instant類、DateTime類、LocalDate類、LocalTime類和LocalDateTime類。根據(jù)要獲取日期和時(shí)間值的格式不同，需要引入的類也會(huì)有所差別，以下分別對(duì)這幾個(gè)類的功能做簡(jiǎn)單介紹：

Instant：用來(lái)表示時(shí)間軸上一個(gè)瞬時(shí)的點(diǎn)，即一個(gè)事件發(fā)生的時(shí)間戳，可以忽略其使用的日歷系統(tǒng)或所在時(shí)區(qū)。

DateTime類：是JodaTime_ohos的核心類，能夠確定在時(shí)間軸上的位置。使用此類的時(shí)間格式有標(biāo)準(zhǔn)時(shí)間(sampleDateTimeslice)、格式化時(shí)間(sampleFormatDateTimeslice)、一段時(shí)間間隔(sampleDateRangeslice)、相對(duì)時(shí)間(sampleGetRelativeDateTimeStringslice)、一段時(shí)間的相對(duì)表示(sampleGetRelativeTimeSpanStringslice)、一段相對(duì)時(shí)間的字符串表示(sampleGetRelativeTimeSpanStringWithPrepositionslice)。
LocalDate類：表示本地的日期，不包含時(shí)間部分，因此適合強(qiáng)調(diào)日期的情況如紀(jì)念日。使用此類的時(shí)間格式有當(dāng)前時(shí)間(sampleLocalDateslice)、今日時(shí)間(sampleIsTodayslice)。
LocalTime：表示本地的時(shí)間，不包含日期部分，因此適合強(qiáng)調(diào)時(shí)間的情況如上下班時(shí)間。
LocalDateTime：表示本地的日期和時(shí)間，因此適用于同時(shí)強(qiáng)調(diào)日期和時(shí)間的情況，如考試時(shí)間。

上述五個(gè)類都是不可變的類，不論怎樣對(duì)它進(jìn)行修改和處理，所有日期和時(shí)間相關(guān)操作的 API 都將返回一個(gè)全新的JodaTime_ohos 實(shí)例，類似Java的String類。除了上述5種常用類，本Sample中還使用到了Duration類，涉及到此類的時(shí)間格式是一段時(shí)間的格式化表示(sampleFormatDurationslice)。

Library解析

JodaTime-ohos組件的整個(gè)library分為五個(gè)部分，如圖7所示。

圖7 library組成結(jié)構(gòu)

JodaTimeAndroid類負(fù)責(zé)初始化相關(guān)操作，在開(kāi)始使用JodaTime_ohos組件之前，都需要通過(guò)此類的init()方法進(jìn)行初始化操作，否則將不能正常訪問(wèn)組件中的類和方法;
ResourceZoneInfoProvide類負(fù)責(zé)監(jiān)控時(shí)區(qū)變化，但是此處需要注意的是，鴻蒙里沒(méi)有提示時(shí)區(qū)變化的intent;
TimeZoneChangedReceiver類則負(fù)責(zé)處理監(jiān)控到的時(shí)區(qū)變化;
DateUtils類主要負(fù)責(zé)將獲取到的日期和時(shí)間值進(jìn)行處理得到多種格式。

其中，DateUtils類是最核心的時(shí)間格式處理類，是經(jīng)過(guò)封裝的工具類。如圖8所示，在Sample中使用到的日期和時(shí)間類是DateTime類、LocalDate類和Duration類，共三種，在通過(guò)DateUtils類中相應(yīng)方法將獲取到日期和時(shí)間值進(jìn)行處理之后，可以得到多達(dá)7種格式的日期和時(shí)間表現(xiàn)形式。

圖8 時(shí)間格式處理核心類

1、方法重載實(shí)現(xiàn)多時(shí)間格式

在DateUtils類中，包含很多時(shí)間格式轉(zhuǎn)換的方法，其中有些方法通過(guò)方法重載存在多種參數(shù)形式，在使用時(shí)可以根據(jù)需求傳入不同個(gè)數(shù)的參數(shù)，從而得到不同格式的日期和時(shí)間，增加了程序的可讀性。

以getRelativeTimeSpanString()方法為例，此方法用于獲得相對(duì)時(shí)間的跨度，如“20分鐘前”、“20分鐘內(nèi)”。通過(guò)方法重載的方式，調(diào)用此方法根據(jù)參數(shù)的不同能夠得到兩種，分別有兩個(gè)參數(shù)和三個(gè)參數(shù)兩種形式：

(1)兩個(gè)參數(shù)

當(dāng)傳入?yún)?shù)分別是time和flags時(shí)，得到的時(shí)間格式是一段時(shí)間的相對(duì)表示，效果如上述圖1.1中的d圖所示。在獲取到傳入的原始時(shí)間值之后，進(jìn)行時(shí)、分、秒的判斷，從而完成相應(yīng)的處理。

public static CharSequence getRelativeTimeSpanString(Context context, ReadableInstant time, int flags) throws NotExistException, WrongTypeException, IOException { 
        boolean abbrevRelative = (flags & (FORMAT_ABBREV_RELATIVE | FORMAT_ABBREV_ALL)) != 0; 
   //將傳入的原始時(shí)間值轉(zhuǎn)換為DateTime類型 
        DateTime now = DateTime.now(time.getZone()).withMillisOfSecond(0); 
        //獲取原始時(shí)間值    
   DateTime timeDt = new DateTime(time).withMillisOfSecond(0); 
        boolean past = !now.isBefore(timeDt); 
        Interval interval = past ? new Interval(timeDt, now) : new Interval(now, timeDt); 
        ... 
        //進(jìn)行時(shí)、分、秒的判斷，完成相應(yīng)處理 
        if (Minutes.minutesIn(interval).isLessThan(Minutes.ONE)) {...} 
        else if (Hours.hoursIn(interval).isLessThan(Hours.ONE)) {...} 
        else if (Days.daysIn(interval).isLessThan(Days.ONE)) {...} 
        else if (Weeks.weeksIn(interval).isLessThan(Weeks.ONE)) {...} 
        ... 
        return String.format(format, count);//返回處理結(jié)果 
}

(2)三個(gè)參數(shù)：

當(dāng)傳入?yún)?shù)分別是time、flags和withPrepositon時(shí)，得到的時(shí)間格式是一段相對(duì)時(shí)間的字符串表示，效果如上述圖1.1中的e圖所示。先獲取傳入的原始時(shí)間值，將其轉(zhuǎn)換為L(zhǎng)ocalDate格式，之后分別針對(duì)時(shí)、分、秒進(jìn)行判斷，從而完成處理返回相應(yīng)的時(shí)間格式。

public static CharSequence getRelativeTimeSpanString(Context ctx, ReadableInstant time, boolean withPreposition) throws NotExistException, WrongTypeException, IOException { 
    String result; 
    LocalDate now = LocalDate.now();//實(shí)例化LocalDate對(duì)象，獲取本地時(shí)間 
    LocalDate timeDate = new LocalDate(time);//將傳入的原始時(shí)間值轉(zhuǎn)換為L(zhǎng)ocalDate類型 
    int prepositionId; 
    //針對(duì)時(shí)、分、秒進(jìn)行判斷，完成處理 
    if (Days.daysBetween(now, timeDate).getDays() == 0) {...} 
    else if (Years.yearsBetween(now, timeDate).getYears() != 0) {...} 
    else {...} 
    if (withPreposition) { 
        result = ctx.getResourceManager().getElement(prepositionId).getString(result); 
    } 
    return result;//返回處理結(jié)果 
}

2、同方法中通過(guò)判斷實(shí)現(xiàn)多時(shí)間格式

除了上述通過(guò)方法重載實(shí)現(xiàn)不同時(shí)間格式的情況，DateUtils類中還有另一種實(shí)現(xiàn)多時(shí)間格式的方式，即在同一個(gè)方法中，通過(guò)判斷不同類型的原始時(shí)間數(shù)據(jù)進(jìn)行相應(yīng)的處理，從而得到不同類型的時(shí)間值。

以一段時(shí)間的格式化表示的sampleFormatDurationslice類為例，效果如上述圖1.4。開(kāi)發(fā)者在Sample中使用的時(shí)候，在分別通過(guò)standardSeconds()、standardMinutes()、standardHours()方法按需獲取不同時(shí)間值即秒、分鐘、小時(shí)之后，再調(diào)用DateUtils中的formatDuration()方法：

text.add("Seconds: " + DateUtils.formatDuration(this, Duration.standardSeconds(25)));//獲取25秒的標(biāo)準(zhǔn)時(shí)間值 
text.add("Minutes: " + DateUtils.formatDuration(this, Duration.standardMinutes(5)));//獲取5分鐘的標(biāo)準(zhǔn)時(shí)間值 
text.add("Hours: " + DateUtils.formatDuration(this, Duration.standardHours(3)));//獲取3小時(shí)的標(biāo)準(zhǔn)時(shí)間值

在formatDuration()方法中，若原始時(shí)間數(shù)據(jù)包含小時(shí)，則進(jìn)行第一個(gè)判斷，返回小時(shí)類型的時(shí)間處理結(jié)果;若原始時(shí)間數(shù)據(jù)包含分鐘，則進(jìn)行第二個(gè)判斷，返回分鐘類型的時(shí)間處理結(jié)果;若原始時(shí)間數(shù)據(jù)包含秒，則不進(jìn)入判斷直接返回秒類型的時(shí)間處理結(jié)果。

public static CharSequence formatDuration(Context context, ReadableDuration readableDuration) throws IOException, NotExistException, WrongTypeException { 
    ResourceManager res = context.getResourceManager(); 
    Duration duration = readableDuration.toDuration();//將傳入的原始時(shí)間值轉(zhuǎn)換為Duration類型 
    final int hours = (int) duration.getStandardHours();//獲取傳入的原始時(shí)間值 
    if (hours != 0) {//判斷傳入時(shí)間值中是否包含小時(shí) 
        return //返回時(shí)間值包含小時(shí)的時(shí)間格式res.getElement(net.danlew.android.joda.ResourceTable.Plural_joda_time_android_duration_hours).getPluralString(hours, hours); 
    } 
    final int minutes = (int) duration.getStandardMinutes(); 
    if (minutes != 0) {//判斷傳入時(shí)間值中是否包含分鐘 
        return //返回時(shí)間值包含分鐘的時(shí)間格式res.getElement(net.danlew.android.joda.ResourceTable.Plural_joda_time_android_duration_minutes).getPluralString(minutes, minutes); 
    } 
    final int seconds = (int) duration.getStandardSeconds(); 
    return //傳入時(shí)間值中包含秒則直接返回處理后的結(jié)果res.getElement(net.danlew.android.joda.ResourceTable.Plural_joda_time_android_duration_seconds).getPluralString(seconds, seconds); 
}