概述

Tizen Time API 支持使用指定区域的日历功能，该功能通过获取指定日期的当前当地时间来实现。 Time API允许您设置指定时区的时间和日期。 它还可以进行时区之间的转换。 对于一个给定的日期，您可以执行计算，以将本地时间转换为任何在过去、 现在、 还是将来的日期，并处理夏令时 (DST) 的信息。 若要使用此 API，为 config.xml 文件添加所需要的权限 （请参阅下面章节中的先决条件小节）。 当启动应用程序时，时间对象时会自动在 tizen 对象中实例化。 tizen.time 对象是一个实例的 TimeUtil 接口的实例，该实例提供了日期、 时间和时区的管理功能。

下图显示 API 对象如何在应用程序窗口内结构化。

   

时间对象 

• 获取当前日期和时间
• 创建和设置新的日期和时间
• 获取时区信息
• 检查日期和时间格式
• 闰年检查
• 时间转换
• 计算时间差异
• 检查是否启用了夏令时
• 持续时间的变化
• 比较时间

系统必备组件

" Time API 具有不同级别的访问权限来处理系统和敏感数据。 您可以启用不同的权限 Time 在 API config.xml 文件。

• http://tizen.org/api/time： 允许访问的所有功能的权限 Time API
• http://tizen.org/api/time.read： 特权允许访问获取当前时间、 日期、 时间区域、 时间和日期的格式
• http://tizen.org/api/time.write： 特权要允许访问设置日期和时间

获取当前日期和时间

" Time API 提供了 TimeUtil 接口使您能够与当前的系统日期和当前系统时间。

您可以获取和设置当前系统日期和时间。

• 获取当前日期和时间

  " TimeUtil.getCurrentDateTime 方法检索当前系统日期和时间。 此方法返回 TZDate 对象设置新的值。

  // Retrieves the current system date time and writes to console.
  var current_dt = tizen.time.getCurrentDateTime();
  console.log ("current date / time is " + current_dt.toLocaleString());

  此外，您可以使用访问功能，如 tizen.time.TZDate.getFullYear()，tizen.time.TZDate.getMonth()。 若要检索的单个字段的年、 月、 等信息。

创建和设置新的日期和时间

创建的实例 Time 通过传递的日期、 时间和时区值的接口 new tizen.TZDate() 方法。

// Creates a time interface instance with the given values
var newDT = new tizen.TZDate(2012, 9, 22, 2, 25, 23, 200, );
console.log ("date / time is " + newDT.toLocaleString());

• 设置当前日期和时间

  您可以使用类似的方法 tizen.time.TZDate.setFullYear(), tizen.time.TZDate.setMonth(), tizen.time.TZDate.setHours(), tizen.time.TZDate.setMinutes() .. 将值设置为单个字段的年、 月、 小时、 分钟，等。

  // Creates a time interface instance with the given values
  var newDT = new tizen.TZDate(2012, 9, 22, 2, 25, 23, 200, );
  newDT.setMonth(2); // Sets month as March

  下表显示的参数 TZDate 界面的构造函数。

  参数	格式	示例
  一年	YYYY （4 位数字的年份)	2011
  个月	毫米 （2 位数表示的月份）	11
  一天	DD (每月 2 位数天)	10
  小时	hh （2 个小时的数字）	3 03）
  分钟	毫米 （2 位数字的分钟）	45
  秒	ss （2 位数字的秒）	4 04）
  毫秒为单位）	（毫秒为单位） 的 3 位数字）	999
  时区	特定的描述符 1/特定描述符 2/特定描述符 n(string)	美国/阿根廷/Buenos_Aires

  除了第一天的参数，开始从 1、 所有的参数 TZDate 构造函数是从 0 开始的。 这意味着个月的一年，一月的值是 0、 2 月，它是 1，和 12 月，它是 11。 因此，它可能会方便所返回的值加 1 tizen.time.TZDate.getMonth() 方法。

获取时区信息

• 获取本地时区

  " TimeUtil.getLocalTimeZone 方法用于获取本地时区。 此方法以字符串形式返回时区的时间。

  // Sets the system date and time to Sep 22, 2012 and 01:32:46
  var newTZ = tizen.time.getLocalTimezone();
  console.log ("Local time zone is " + newTZ);

• 获取可用的时区

  使用可获取可用的时区列表 tizen.time.getAvailableTimezones() 方法。

  // Gets the list of available time zones and prints the number to console
  var tzList = tizen.time.getAvailableTimezones();
  console.log ("The device supports  " + tzList.length + "time zones");

• 获取时区缩写

  " TZDate.getTimezoneAbbreviation() 方法确定时区缩写，用于在特定时区中的时间日期。

  // Gets abbrevation of the time zone
  var current_dt = tizen.time.getCurrentDateTime();
  var tzAbbr = current_dt.getTimezoneAbbreviation();
  console.log ("Time zone abbrevation " + tzAbbr);

检查日期和时间格式

" TimeUtil 接口提供用于获取日期和时间格式的方法。

• 获取时间格式

  你可以得到系统的本地时间使用格式 tizen.time.getTimeFormat() 方法。 返回一个字符串。 例如，您可以获取"h:m ap"，其中 h 表示小时 （0 到 23 或 1 到 12 如果 AM/PM 显示），m 表示分钟 （0 到 59)、 s 表示秒 （0 到 59) 和 ap 立场为 AM/PM 显示格式。

  // Gets the system's local time format and prints to console
  var timeFormat = tizen.time.getTimeFormat();
  console.log ("System's local time format " + timeFormat);

  很多的时间格式中包括 hh:mm:ss (例如，16:08:27) 和 hh:mm:ss 的 Tizen 支持 ap （例如，4:8:27 下午)

• 获取日期格式

  你可以得到系统的本地日期格式使用 tizen.time.getDateFormat() 方法。 返回一个字符串。 例如，您可以获取字符串"d/m/y"，d 代表天，m 代表月，和 y 表示年。

  // Gets the system's local date format and prints to console
  var dateFormat = tizen.time.getDateFormat();
  console.log ("System's local date format " + dateFormat);

  中泰其中包括 DD，毫米，YYYY 支持多种日期格式 （例如，1996/10/23），YYYY DD 毫米 （例如 1996年-23-10），和混合格式 （例如，星期三 1996 年 10 月 23 日。

检查有闰年

今年为了保持历年与天文或季节性年同步包含一个额外的一天是闰年。 在每个闰年，2 月份有 29 天，而不是 28。

如果您要创建一个日历基于应用程序或接受应用程序窗体上的出生日期，您必须验证用户输入闰年日期值。 例如，29，02，2011年是无效的用户输入。

" TimeUtil.isLeapYear 方法用于检查给定的年份是否为闰年。 此方法采用年输入 YYYY 格式。

en.time.getCurrentDateTime();
var is_leap = tizen.time.isLeapYear(current_dt.getFullYear());
if (is_leap)
   console.log("This year is a leap year.");

时间的转换

" Time API 的 TimeDuration 接口提供方法来将时间转换为本地或指定的时区与 UTC 标准时间。

var now = tizen.time.getCurrentDateTime();
var newtz = now.toTimezone();
var str = newtz.getTimezone();
console.log("Converted time zone " + str);
newtz = date.toLocalTimezone();
str = newtz.getTimezone();
console.log("Local time zone " + str);
var tzUTC = newtz.toUTC();
console.log("UTC standard time " + tzUTC.toLocaleString());

计算时间差异

" Time API 的 TimeDuration 接口提供了差分法来计算两个日期或时间事件而不必费心的不同事件中单位之间的差异。 TimeDuration.difference 方法接受另一个 TimeDuration 对象，并执行 (this object – parameter object) 操作，并返回一个 TimeDuration 对象。

// Compute event1.duration - event2.duration
var diff = event1.duration.difference(event2.duration);
if (diff.length > 0)
   console.log("Event1 is longer than Event2");
else if (diff.length = 0)
   console.log("Event1 is as long as Event2");
else
   console.log("Event1 is shorter than Event2");

检查是否启用了夏令时

夏令时，也称为夏季时间用来更好地利用日光

" TzDate.isDST 方法用来检查是否已为当前时区启用了 DST

var current_dt = tizen.time.getCurrentDateTime();
var is_DST = current_dt.isDST;
if (is_DST)
   console.log("Day light saving is enabled");

• 获取以前的 DST 过渡

  返回以前的夏令时过渡为时区的日期。

  var now = tizen.time.getCurrentDateTime();
  var tzDT = now.getPreviousDSTTransition();

• 获取下一个 DST 转换

  返回下一个夏令时过渡为时区的日期。

  var now = tizen.time.getCurrentDateTime();
  var tzDT = now.getNextDSTTransition();

持续时间的变化

您可以使用 tizen.time.TZDate.addDuration() 方法将指定的秒数添加到当前时间或指定的数目的天到当前的日期 ；持续时间是类型 TimeDuration.

// a journey in time
var now = tizen.time.getCurrentDateTime();
var newDT = now.addDuration(new tizen.TimeDuration(5, "DAYS"));

比较时间

有方便的时间比较三种方法： tizen.time.TZDate.equalsTo(), tizen.time.TZDate.earlierThan() 和 tizen.time.TZDate.laterThan(). 他们每个人都应适用于 TZDateobject 和他们每个人都返回一个布尔值。

if(newDT.equalsTo(myGetCurrentDateTime.currentDT) == false) {
    // changed
    if(newDT.earlierThan(myGetCurrentDateTime.currentDT) == true ) {
        // earlier - time has stepped back!
    }
    if(newDT.laterThan(myGetCurrentDateTime.currentDT) == true ) {
        // later - time has elapsed.
    }
} else {
    // the same time!
}