Создание приложений, подключающихся к программам «Люди» и «Календарь». Часть 2: встречи

В первой статье мы рассмотрели один из контрактов Windows 8.1 — карточки контактов. В этой статье мы рассмотрим работу приложения с календарем пользователя через API «Встречи Windows 8.1», где действия с календарем обрабатываются выбранным пользователем приложением-календарем.

Интеграция приложений со встречами

Мы все храним данные о встречах в календарях, используя их в качестве поставщика информации о наших планах на день, неделю или даже несколько месяцев. Но мы также пользуемся многими другими приложениями, работающими с событиями и встречами.

События в Facebook, приглашения на вечеринки в Evite, регулярные встречи клуба любителей книг в Meetup, крайние сроки выполнения домашних заданий в приложении для учебы, даты вылетов в приложении для путешествий, бронирование столиков в ресторанах, даты дней рождения и юбилеев и т. п. Некоторые из этих приложений вы уже опубликовали в Магазине Windows либо же думаете об их создании.

Если каждое приложение будет иметь функцию календаря, то информация окажется рассредоточенной по разным приложениям и пользователю будет трудно получить ответ на простой, казалось бы, вопрос: «Что у меня запланировано на сегодня?» Мы рассчитываем, что календарь — это центральное место для хранения всего нашего расписания. Мы видели удобную кнопку Add to Calendar (Добавить в календарь) на многих веб-сайтах. Так почему бы не разместить ее в любых наших приложениях? Это можно сделать с помощью контракта «Встречи Windows 8.1»! В ваших приложениях Windows 8.1 пользователи смогут с легкостью просматривать свое расписание в календаре, а также добавлять события в предпочитаемый календарь — не выходя из приложения!

Что такое контракт «Встречи»?

Как и другие контракты Windows (например, «Общий доступ» и «Люди»), «Встречи» — это контракт между исходным приложением (содержащим информацию о встречах и событиях) и конечным приложением (предпочитаемым календарем пользователя с поддержкой контракта поставщика). Контракт служит для выполнения следующих сценариев:

1. Просмотр календаря пользователя рядом с исходным приложением.
2. Добавление новых встреч в календарь пользователя.
3. Замена существующей встречи в календаре пользователя.
4. Удаление существующей встречи из календаря пользователя.

API для них находятся в пространстве имен Windows.ApplicationModel.Appointments, а конкретнее — в классе AppointmentManager.

Просмотр календаря из приложения

Для просмотра календаря пользователя вызовите из своего приложения метод  AppointmentManager.ShowTimeFrameAsync с двумя аргументами:

• Объект даты и времени, обозначающий начало периода времени для конечного приложения-календаря.
• Период времени, подсказывающий приложению обзор нужного дня, недели или месяца, с которым запускается приложение-календарь. (Период выражается в сотнях наносекунд в C#, Visual Basic и C++; в JavaScript используются миллисекунды.)

Используя эту информацию, рядом с вашим приложением запустится приложение-календарь пользователя по умолчанию (рисунок 1). Теперь пользователь может взаимодействовать с полностью интерактивным календарем, изменять его размер или убрать его с экрана одним движением пальца.

Увеличить

Рисунок 1

JavaScript

// Показываем приложение — поставщик встреч по умолчанию в текущую дату и время
// с длительностью в 1 час
function showTimeFrame() {
  var dateToShow = new Date();
  Windows.ApplicationModel.Appointments.AppointmentManager.showTimeFrameAsync(
    dateToShow, (60 * 60 * 1000));
}

C#

/// Показываем приложение — поставщик встреч по умолчанию 25/2/2014 в 18:32:00 по Тихоокеанскому стандартному времени
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private async void Show_Click(object sender, RoutedEventArgs e)
{
  var dateToShow = new DateTimeOffset(2014, 2, 25, 18, 32, 0, 0,
    TimeSpan.FromHours(-8));
  var duration = TimeSpan.FromHours(1);
  await Windows.ApplicationModel.Appointments.AppointmentManager.ShowTimeFrameAsync(
    dateToShow, duration);
}

Добавление события из приложения в календарь

Чтобы добавить новую встречу, вызовите метод AppointmentManager.ShowAddAppointmentAsync со следующими аргументами:

• Объект Appointment, представляющий информацию для события, которую нужно добавить.
• Прямоугольник зоны в интерфейсе приложения, вызывающего календарь. Например, если приложение использует кнопку Add to Calendar (Добавить в календарь), предоставьте координаты кнопки, чтобы интерфейс приложения-календаря отобразился вокруг кнопки, а не поверх нее.
• (Опционально) Предпочитаемое размещение интерфейса приложения-календаря относительно области выбора. Опции размещены выше (по умолчанию), ниже, левее или правее пользовательской области выбора.

Метод вызывает UI приложения-календаря в элементе, всплывающем поверх приложения, и предоставляет встраиваемый интерфейс (рисунок 2). Благодаря этому пользователь может подтвердить информацию о встрече, прежде чем добавить ее в календарь, что обеспечивает защиту от приложений, пытающихся заполнить календарь спамом. Всплывающий элемент с календарем состоит из предоставляемого Windows заголовка, отображающего название и логотип приложения-календаря, и тела, в котором приложение-календарь отображает свой интерфейс. Таким образом обеспечивается согласованный пользовательский интерфейс, поскольку при добавлении встречи из любого исходного приложения всегда будет отражаться этот знакомый и легко узнаваемый интерфейс. Взамен исходное приложение получает уникальный идентификатор для события, добавленного в календарь, который может использоваться для вызова похожего рабочего процесса для замены или удаления существующих событий. Приложение-календарь отображает подходящий интерфейс в зависимости от конкретных действий.

Увеличить

Рисунок 2

JavaScript

function addAppointment(e) {
  // Создаем встречу, которую нужно добавить в пользовательское
  // приложение, работающее со встречами
  var appointment = new Windows.ApplicationModel.Appointments.Appointment();
 appointment.startTime = new Date(2014, 2, 28, 18); // March 28th, 2014 at 6:00pm
  appointment.duration = (60 * 60 * 100000) / 100; // 1 час в сотнях миллисекунд
  appointment.location = "Ben Miller's home";
  appointment.subject = "Frank's Birthday";
  appointment.details = "Surprise party to celebrate Frank's 60th birthday! Hoping you all can join us.";
  appointment.reminder = (15 * 60 * 1000000000) / 100; // Remind me 15 minutes prior to appointment
// Получаем прямоугольник выделения кнопки, нажатой для добавления этой встречи
  var boundingRect = e.srcElement.getBoundingClientRect();
  var selectionRect = { x: boundingRect.left, y: boundingRect.top,
    width: boundingRect.width, height: boundingRect.height };
// ShowAddAppointmentAsync возвращает идентификатор встречи, если предоставленная встреча была добавлена в календарь пользователя
  // Это значение должно храниться в данных приложения и перемещаться так, чтобы встречу можно было заменить или удалить в будущем
  // Возвращенное значение в виде пустой строки означает, что пользователь отменил операцию до того, как встреча была добавлена
  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";
      }
    });
}

C#

/// <summary>
/// Создаем встречу на основе данных из полей ввода и подтверждаем ее
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void CreateAppointment(object sender, RoutedEventArgs e)
{
  var appointment = new Windows.ApplicationModel.Appointments.Appointment();

  // StartTime
  var date = StartTimeDatePicker.Date;
  var time = StartTimeTimePicker.Time;
  var timeZoneOffset = TimeZoneInfo.Local.GetUtcOffset(DateTime.Now);
  var startTime = new DateTimeOffset(date.Year, date.Month, date.Day, time.Hours,
    time.Minutes, 0, timeZoneOffset);
  appointment.StartTime = startTime;

  // Subject
  appointment.Subject = SubjectTextBox.Text;

  // Location
  appointment.Location = LocationTextBox.Text;

  // Details
  appointment.Details = DetailsTextBox.Text;

  // Выбрано время действия 1 час
  appointment.Duration = TimeSpan.FromHours(1);

  // Reminder
  appointment.Reminder = TimeSpan.FromMinutes(15);
}

/// <summary>
/// Добавляем встречу в приложение, работающее со встречами, по умолчанию
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private async void AddAppointment(object sender, RoutedEventArgs e)
{
  // Создаем встречу, которую нужно добавить в пользовательское приложение,
  // работающее со встречами
  var appointment = new Windows.ApplicationModel.Appointments.Appointment();

  // Получаем прямоугольник выделения кнопки, нажатой для добавления этой встречи
  var rect = GetElementRect(sender as FrameworkElement);

  // ShowAddAppointmentAsync возвращает идентификатор встречи, если предоставленная встреча была добавлена в календарь пользователя
  // Это значение должно храниться в данных приложения и перемещаться так, чтобы встречу можно было заменить или удалить в будущем
  // Возвращенное значение в виде пустой строки означает, что пользователь отменил операцию до того, как встреча была добавлена
  String appointmentId = await
  Windows.ApplicationModel.Appointments.AppointmentManager.ShowAddAppointmentAsync(
    appointment, rect, Windows.UI.Popups.Placement.Default);
  if (appointmentId != String.Empty)
  {
    ResultTextBlock.Text = "Appointment Id: " + appointmentId;
  }
  else
  {
    ResultTextBlock.Text = "Appointment not added.";
  }
}

Как видите, исходное приложение и приложение — поставщик встреч работают совместно через строго типизированный объект Appointment. Этот объект поддерживает большое количество свойств, например, recurrence для добавления повторяющихся событий в календарь пользователя, invitees для предоставления списка участников встречи и т. п.

Приложения могут также содержать функции для замены или удаления существующих встреч, добавленных в календарь пользователя. Для замены встречи вызовите AppointmentManager.ShowReplaceAppointmentAsync с новыми деталями встречи и идентификатором встречи, которую нужно заменить. Если соответствующая встреча не найдена, поскольку пользователь, возможно, удалил ее из календаря, добавляется новая встреча, а уникальный идентификатор замененной встречи возвращается в ваше приложение.

Для удаления существующей встречи вызовите AppointmentManager.ShowRemoveAppointmentAsync API с идентификатором встречи, которую нужно удалить. Если соответствующая встреча найдена в календаре пользователя, во всплывающем окне отобразится интерфейс приложения-календаря для проверки встречи пользователем и подтверждения ее удаления. Этот метод возвращает значение типа Boolean, обозначающее, удалена ли встреча приложением — поставщиком встреч.

Для более подробной информации обо всех указанных выше методах смотрите пример использования API Встречи.

Приложения — поставщики встреч

Встроенное приложение «Календарь Windows» поддерживает контракт поставщика встреч в качестве конечного приложения, но другие приложения также могут выполнять эту роль с помощью контракта.

Чтобы сделать приложение поставщиком встреч, сначала нужно обновить манифест вашего приложения так, чтобы он включал расширение AppointmentsProvider, которое уведомляет Windows о том, что приложение способно управлять встречами. Затем приложение должно обрабатывать каждое действие, которое поставщик встреч может выполнять для других приложений. Эти действия включают добавление, удаление и замену встречи, показ временных рамок (активацию поставщика встреч для отображения пользовательского календаря на определенный день и время). Для получения более подробной информации о том, как сделать приложение поставщиком встреч, смотрите эту статью Ника Юбэнкса (Nick Eubanks) в блоге MSDN.

В заключение

Пользователи любят приложения, позволяющие быстро выполнять задания без смены контекста. С помощью API «Встречи» приложения предоставляют быстрый обзор календаря, функции по добавлению или редактированию событий в предпочитаемом календаре, благодаря чему пользователи получают полное представление обо всем, что происходит у них в течение дня. Пользователи сами решают, что добавить в календарь, с помощью всплывающего интерфейса приложения-календаря поверх вашего приложения. Встроенное приложение «Календарь Windows» поддерживает контракт поставщика встреч для работы с вашими приложениями. Мы надеемся увидеть больше приложений, использующих этот новый контракт для более персонализированной работы пользователей.