原文

ical.js uses a layered approach towards parsing and processing iCalendar data.

ical.js使用分层的方法来解析和处理iCalendar数据。

iCalendar Data ↔ jCal Data ↔ Component Model Layer ↔ Item Model Layer

iCalendar数据 ↔ jCal数据 ↔ 组件模型层 ↔ 元素模型层

iCalendar数据(iCalendar Data)

This is data in the iCalendar format, described by rfc5545. It can be converted to the jCal format, which is a JSON representation of the iCalendar data.

第一层,iCalendar格式的数据,由rfc5545定义。可以转化为jCal格式——iCalendar数据对应的JSON格式表示。

The following sections will reference properties of this example iCalendar data:

下面是iCalendar格式的示例数据:

BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Example Inc.//Example Calendar//EN
VERSION:2.0
BEGIN:VEVENT
DTSTAMP:20080205T191224Z
DTSTART:20081006
SUMMARY:Planning meeting
UID:4088E990AD89CB3DBB484909
END:VEVENT
END:VCALENDAR

Here is an example on how to parse an iCalendar string to jCal:

如下操作可以将iCalendar字符串转换为jCal:

var iCalendarData = "BEGIN:VCALENDAR" + /* ... */ + "END:VCALENDAR";
var jcalData = ICAL.parse(iCalendarData);

jcalData will now contain an array describing the VCALENDAR component, adhering to the jCal format. If iCalendarData contains more than one top level component (i.e multiple VCALENDAR components concatenated) then ICAL.parse will return an array of such components instead.

现在jcalData包含一组用jCal格式描述的VCALENDAR组件。如果iCalendarData包含多个顶级组件(比如,拼接在一起的多个VCALENDAR组件),ICAL.parse方法将返回一个由上述组件组成的数组。

jCal数据(jCal Data)

At this stage you have access to the raw jCal data. You can already use this representation to read simple information on the events in your data, but at some stage you will need one of the higher layers to process the data more easily.

经过上面的处理后,在这个阶段,已经可以访问原始的第二层jCal数据。可以直接从这份数据表示中读取简单的信息,但通常情况下,需要更高层次的数据,以便于使用。

Based on the above example, the jCal object will look like this:

["vcalendar",
  [
    ["calscale", {}, "text", "GREGORIAN"],
    ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"],
    ["version", {}, "text", "2.0"]
  ],
  [
    ["vevent",
      [
        ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"],
        ["dtstart", {}, "date", "2008-10-06"],
        ["summary", {}, "text", "Planning meeting"],
        ["uid", {}, "text", "4088E990AD89CB3DBB484909"]
      ],
      []
    ]
  ]
]

组件模型层(Component Model Layer)

This layer organizes the jCal data into components, subcomponents, properties, parameters and values. In the above example, vcalendar and vevent are considered components. summary is considered a property, the (currently empty) object inside the summary-array holds the parameters. The value is mapped to a rich object that contains methods to manipulate it, for example a date value.

第三层层将jCal数据组织成组件,子组件,属性,参数和值。在上面的例子中,vcalendarvevent被认为是组件,summary被认为是属性,summary中的对象(当前为空对象)表示参数,值被影射为包含一组操作方法的对象,比如日期值。

This example retrieves the value of the summary property, using the jcalData from the above example:

如下所示,可以从上面示例的jcalData中获取summary属性值:

var comp = new ICAL.Component(jcalData);
var vevent = comp.getFirstSubcomponent("vevent");
var summary = vevent.getFirstPropertyValue("summary");

元素模型层(Item Model Layer)

In this layer, common properties on the known subcomponents can be easily retrieved. This layer is not yet complete. If you would like to use more features here consider contributing to the ical.js code.

在第四层,可以方便的获取已知子组件的常用属性。目前这一层尚未完全完成,如果你需要更多的特性,可以贡献ical.js代码。

This example achieves the same as in the previous example but using the Item Module Layer:

下面的示例,用元素模型层的方法获取了之前示例中的相同属性:

var comp = new ICAL.Component(jcalData);
var vevent = comp.getFirstSubcomponent("vevent");
var event = new ICAL.Event(vevent);
var summary = event.summary;

It may seem like more lines of code, but ICAL.Event has some other nice features that make it useful.

从表面上看,这个例子比上一个例子多写了一行代码,但ICAL.Event提供了更多有用的特性。

更多文档(Further Documentation)

Currently, there is not much documentation (sorry!). You are going to have to look at the source files to figure out which methods are available. We are going to fix this using automated documentation generation in the future. In the meanwhile we hope the above examples will get you started. Here are some more interesting pages:

目前,还没有更多的文档(抱歉!)。你需要从代码中查找更多可用的方法。正在计划自动生成文档来解决这个问题。同时,希望上面的例子能让你对ical.js有个初步的了解,下面是两个有趣的页面:

编者按

翻译这篇文档时,API文档已经自动生成,可以直接查看。