快速入门：管理约会 (HTML)
[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅 最新文档 ]
通过 Windows.ApplicationModel.Appointments 命名空间，你可以在用户的日历应用中创建和管理约会。我们将在此处向你介绍如何创建约会、将其添加到日历应用、在日历应用中替换它以及从日历应用中删除它。我们还将显示如何显示日历应用的时间跨度以及创建一个约会循环对象。管理约会从 Windows 8.1 开始受支持。
我们在此处引用约会 API 示例。此示例演示了如何通过 Windows 运行时应用内的 Windows.ApplicationModel.Appointments 命名空间的 API 管理约会。
先决条件
- 我们建议你熟悉 Microsoft Visual Studio 及其关联模板。
- 我们建议你熟悉 JavaScript 开发。
创建一个约会并向其应用数据
创建一个 Windows.ApplicationModel.Appointments.Appointment 对象并将其分配给某个变量。然后，应用到由用户通过 UI 提供的 Appointment 约会属性。
function createAppointment() {
var isAppointmentValid = true;
var appointment = new Windows.ApplicationModel.Appointments.Appointment();
// StartTime
var startTime = document.querySelector('#startDatePicker').winControl.current;
var time = document.querySelector('#startTimePicker').winControl.current;
startTime.setMinutes(time.getMinutes());
startTime.setHours(time.getHours());
appointment.startTime = startTime;
// Subject
appointment.subject = document.querySelector('#subjectInput').value;
if (appointment.subject.length > 255) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The subject cannot be greater than 255 characters.";
}
// Location
appointment.location = document.querySelector('#locationInput').value;;
if (appointment.location.length > 32768) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The location cannot be greater than 32,768 characters.";
}
// Details
appointment.details = document.querySelector('#detailsInput').value;
if (appointment.details.length > 1073741823) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The details cannot be greater than 1,073,741,823 characters.";
}
// Duration
if (document.querySelector('#durationSelect').selectedIndex === 0) {
// 30 minute duration is selected
appointment.duration = (30 * 60 * 1000);
} else {
// 1 hour duration is selected
appointment.duration = (60 * 60 * 1000);
}
// All Day
appointment.allDay = (document.querySelector('#allDayCheckBox').checked);
// Reminder
if (document.querySelector('#reminderCheckBox').checked) {
switch (document.querySelector('#reminderSelect').selectedIndex) {
case 0:
appointment.reminder = (15 * 60 * 1000);
break;
case 1:
appointment.reminder = (60 * 60 * 1000);
break;
case 2:
appointment.reminder = (24 * 60 * 60 * 1000);
break;
}
}
//Busy Status
switch (document.querySelector('#busyStatusSelect').selectedIndex) {
case 0:
appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.busy;
break;
case 1:
appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.tentative;
break;
case 2:
appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.free;
break;
case 3:
appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.outOfOffice;
break;
case 4:
appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.workingElsewhere;
break;
}
// Sensitivity
switch (document.querySelector('#sensitivitySelect').selectedIndex) {
case 0:
appointment.sensitivity = Windows.ApplicationModel.Appointments.AppointmentSensitivity.public;
break;
case 1:
appointment.sensitivity = Windows.ApplicationModel.Appointments.AppointmentSensitivity.private;
break;
}
// Uri
var uriValue = document.querySelector('#uriInput').value;
if (uriValue.length > 0) {
try {
appointment.uri = new Windows.Foundation.Uri(uriValue);
}
catch (e) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The Uri provided is invalid.";
}
}
// Organizer
// Note: Organizer can only be set if there are no invitees added to this appointment.
if (document.querySelector('#organizerRadioButton').checked) {
var organizer = new Windows.ApplicationModel.Appointments.AppointmentOrganizer();
// Organizer Display Name
organizer.displayName = document.querySelector('#organizerDisplayNameInput').value;
if (organizer.displayName.length > 256) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The organizer display name cannot be greater than 256 characters.";
} else {
// Organizer Address (e.g. Email Address)
organizer.address = document.querySelector('#organizerAddressInput').value;
if (organizer.address.length > 321) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The organizer address cannot be greater than 321 characters.";
} else if (organizer.address.length === 0) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The organizer address must be greater than 0 characters.";
} else {
appointment.organizer = organizer;
}
}
}
// Invitees
// Note: If the size of the Invitees list is not zero, then an Organizer cannot be set.
if (document.querySelector('#inviteeRadioButton').checked) {
var invitee = new Windows.ApplicationModel.Appointments.AppointmentInvitee();
// Invitee Display Name
invitee.displayName = document.querySelector('#inviteeDisplayNameInput').value;
if (invitee.displayName.length > 256) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The invitee display name cannot be greater than 256 characters.";
} else {
// Invitee Address (e.g. Email Address)
invitee.address = document.querySelector('#inviteAddressInput').value;
if (invitee.address.length > 321) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The invitee address cannot be greater than 321 characters.";
} else if (invitee.address.length === 0) {
isAppointmentValid = false;
document.querySelector('#result').innerText = "The invitee address must be greater than 0 characters.";
} else {
// Invitee Role
switch (document.querySelector('#inviteeRoleSelect').selectedIndex) {
case 0:
invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.requiredAttendee;
break;
case 1:
invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.optionalAttendee;
break;
case 2:
invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.resource;
break;
}
// Invitee Response
switch (document.querySelector('#inviteeResponseSelect').selectedIndex) {
case 0:
invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.none;
break;
case 1:
invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.tentative;
break;
case 2:
invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.accepted;
break;
case 3:
invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.declined;
break;
case 4:
invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.unknown;
break;
}
appointment.invitees.append(invitee);
}
}
}
if (isAppointmentValid) {
document.querySelector('#result').innerText = "The appointment was created successfully and is valid.";
}
}
向用户的日历添加约会
创建一个 Windows.ApplicationModel.Appointments.Appointment 对象并将其分配给某个变量。然后，调用 AppointmentManager.ShowAddAppointmentAsync(Appointment, Rect, Placement) 方法来显示默认约会提供程序添加约会 UI，以使用户能够添加约会。如果用户单击了“添加”，该示例将打印 ShowAddAppointmentAsync 返回的约会标识符。
function addAppointment(e) {
// Create an Appointment that should be added the user's appointments provider app.
var appointment = new Windows.ApplicationModel.Appointments.Appointment();
// Get the selection rect of the button pressed to add this appointment
var boundingRect = e.srcElement.getBoundingClientRect();
var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };
// ShowAddAppointmentAsync returns an appointment id if the appointment given was added to the user's calendar.
// This value should be stored in app data and roamed so that the appointment can be replaced or removed in the future.
// An empty string return value indicates that the user canceled the operation before the appointment was added.
Windows.ApplicationModel.Appointments.AppointmentManager.showAddAppointmentAsync(appointment, selectionRect, Windows.UI.Popups.Placement.default)
.done(function (appointmentId) {
if (appointmentId) {
document.querySelector('#result').innerText = "Appointment Id: " + appointmentId;
} else {
document.querySelector('#result').innerText = "Appointment not added";
}
});
}
在用户的日历中替换约会
创建一个 Windows.ApplicationModel.Appointments.Appointment 对象并将其分配给某个变量。然后，调用合适的 AppointmentManager.ShowReplaceAppointmentAsync 方法来显示默认约会提供程序替换约会 UI，以使用户能够替换约会。用户还可以提供他们想要替换的约会标识符。此标识符已从 AppointmentManager.ShowAddAppointmentAsync 中返回。 如果用户单击了“替换”，该示例将指示它已更新该约会标识符。
function replaceAppointment(e) {
// The appointment id argument for ReplaceAppointmentAsync is typically retrieved from AddAppointmentAsync and stored in app data.
var appointmentIdOfAppointmentToReplace = document.querySelector('#appointmentIdInput').value;
if (!appointmentIdOfAppointmentToReplace) {
document.querySelector('#result').innerText = "The appointment id cannot be empty";
} else {
// The Appointment argument for ReplaceAppointmentAsync should contain all of the Appointment's properties including those that may have changed.
var appointment = new Windows.ApplicationModel.Appointments.Appointment();
// Get the selection rect of the button pressed to replace this appointment
var boundingRect = e.srcElement.getBoundingClientRect();
var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };
// ReplaceAppointmentAsync returns an updated appointment id when the appointment was successfully replaced.
// The updated id may or may not be the same as the original one retrieved from AddAppointmentAsync.
// An optional instance start time can be provided to indicate that a specific instance on that date should be replaced
// in the case of a recurring appointment.
// If the appointment id returned is an empty string, that indicates that the appointment was not replaced.
if (document.querySelector('#instanceStartDateCheckBox').checked) {
// Replace a specific instance starting on the date provided.
var instanceStartDate = document.querySelector('#startTimeDatePicker').winControl.current;
Windows.ApplicationModel.Appointments.AppointmentManager.showReplaceAppointmentAsync(
appointmentIdOfAppointmentToReplace, appointment, selectionRect, Windows.UI.Popups.Placement.default, instanceStartDate)
.done(function (updatedAppointmentId) {
if (updatedAppointmentId) {
document.querySelector('#result').innerText = "Updated Appointment Id: " + updatedAppointmentId;
} else {
document.querySelector('#result').innerText = "Appointment not replaced";
}
});
} else {
// Replace an appointment that occurs only once or in the case of a recurring appointment, replace the entire series.
Windows.ApplicationModel.Appointments.AppointmentManager.showReplaceAppointmentAsync(
appointmentIdOfAppointmentToReplace, appointment, selectionRect, Windows.UI.Popups.Placement.default)
.done(function (updatedAppointmentId) {
if (updatedAppointmentId) {
document.querySelector('#result').innerText = "Updated Appointment Id: " + updatedAppointmentId;
} else {
document.querySelector('#result').innerText = "Appointment not replaced";
}
});
}
}
}
从用户的日历中删除约会
调用合适的 AppointmentManager.ShowRemoveAppointmentAsync 方法来显示默认约会提供程序删除约会 UI，以使用户能够删除约会。用户还可以提供他们想要删除的约会标识符。此标识符已从 AppointmentManager.ShowAddAppointmentAsync 中返回。 如果用户单击了“删除”，该示例将指示它已删除由该约会标识符指定的约会。
function removeAppointment(e) {
// The appointment id argument for ShowRemoveAppointmentAsync is typically retrieved from AddAppointmentAsync and stored in app data.
var appointmentId = document.querySelector('#appointmentIdInput').value;
// The appointment id cannot be empty.
if (!appointmentId) {
document.querySelector('#result').innerText = "The appointment id cannot be empty";
} else {
// Get the selection rect of the button pressed to remove this appointment
var boundingRect = e.srcElement.getBoundingClientRect();
var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };
// ShowRemoveAppointmentAsync returns a boolean indicating whether or not the appointment related to the appointment id given was removed.
// An optional instance start time can be provided to indicate that a specific instance on that date should be removed
// in the case of a recurring appointment.
if (document.querySelector('#instanceStartDateCheckBox').checked) {
// Remove a specific instance starting on the date provided.
var instanceStartDate = document.querySelector('#startTimeDatePicker').winControl.current;
Windows.ApplicationModel.Appointments.AppointmentManager.showRemoveAppointmentAsync(
appointmentId, selectionRect, Windows.UI.Popups.Placement.default, instanceStartDate)
.done(function (removed) {
if (removed) {
document.querySelector('#result').innerText = "Appointment removed";
} else {
document.querySelector('#result').innerText = "Appointment not removed";
}
});
} else {
// Remove an appointment that occurs only once or in the case of a recurring appointment, remove the entire series.
Windows.ApplicationModel.Appointments.AppointmentManager.showRemoveAppointmentAsync(
appointmentId, selectionRect, Windows.UI.Popups.Placement.default)
.done(function (removed) {
if (removed) {
document.querySelector('#result').innerText = "Appointment removed";
} else {
document.querySelector('#result').innerText = "Appointment not removed";
}
});
}
}
}
显示约会提供程序的时间跨度
如果用户单击了“显示”****，则调用 AppointmentManager.ShowTimeFrameAsync 方法来为默认约会提供程序的主 UI 显示特定时间跨度。该示例指示默认约会提供程序已显示在屏幕上。
// Show the appointment provider app at the current date and time with a 1 hour duration
function showTimeFrame() {
var dateToShow = new Date();
Windows.ApplicationModel.Appointments.AppointmentManager.showTimeFrameAsync(dateToShow, (60 * 60 * 1000))
.done(function () {
document.querySelector('#result').innerText = "The default appointments provider should have appeared on screen.";
});
}
创建一个约会循环对象并向其应用数据
创建一个 Windows.ApplicationModel.Appointments.AppointmentRecurrence 对象并将其分配给某个变量。然后，应用到由用户通过 UI 提供的 AppointmentRecurrence 循环属性。
function createRecurrence() {
var isRecurrenceValid = true;
var recurrence = new Windows.ApplicationModel.Appointments.AppointmentRecurrence();
// Unit
switch (document.querySelector('#unitSelect').selectedIndex) {
case 0:
recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.daily;
break;
case 1:
recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.weekly;
break;
case 2:
recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthly;
break;
case 3:
recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthlyOnDay;
break;
case 4:
recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearly;
break;
case 5:
recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearlyOnDay;
break;
}
// Occurrences
// Note: Occurrences and Until properties are mutually exclusive.
if (document.querySelector('#occurrencesRadioButton').checked) {
recurrence.occurrences = document.querySelector('#occurrencesRange').valueAsNumber;
}
// Until
// Note: Until and Occurrences properties are mutually exclusive.
if (document.querySelector('#untilRadioButton').checked) {
recurrence.until = document.querySelector('#untilDatePicker').winControl.current;
}
// Interval
recurrence.interval = document.querySelector('#intervalRange').valueAsNumber;
// Week of the month
switch (document.querySelector('#weekOfMonthSelect').selectedIndex) {
case 0:
recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.first;
break;
case 1:
recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.second;
break;
case 2:
recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.third;
break;
case 3:
recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.fourth;
break;
case 4:
recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.last;
break;
}
// Days of the Week
// Note: For Weekly, MonthlyOnDay or YearlyOnDay recurrence unit values, at least one day must be specified.
if (document.querySelector('#sundayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.sunday; }
if (document.querySelector('#mondayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.monday; }
if (document.querySelector('#tuesdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.tuesday; }
if (document.querySelector('#wednesdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.wednesday; }
if (document.querySelector('#thursdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.thursday; }
if (document.querySelector('#fridayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.friday; }
if (document.querySelector('#saturdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.saturday; }
if (((recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.weekly) ||
(recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthlyOnDay) ||
(recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearlyOnDay)) &&
(recurrence.daysOfWeek === Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.none)) {
isRecurrenceValid = false;
document.querySelector('#result').innerText = "The recurrence specified is invalid. For Weekly, MonthlyOnDay or YearlyOnDay recurrence unit values,
at least one day must be specified.";
}
// Month of the year
recurrence.month = document.querySelector('#monthOfYearRange').valueAsNumber;
// Day of the month
recurrence.day = document.querySelector('#dayOfMonthRange').valueAsNumber;
if (isRecurrenceValid)
{
document.querySelector('#result').innerText = "The recurrence specified was created successfully and is valid.";
}
}
摘要和后续步骤
现在你已基本了解如何管理约会。从代码库下载约会 API 示例，以查看如何管理约会的完整示例。