Добавление поддержки функции "Близкие люди" в приложение

  • Статья

Важно!

Мои люди больше не поддерживаются в версиях Windows 11 и Windows 10 с применением КБ5034203.

Примечание.

По состоянию на обновление Windows 10 за май 2019 г. (версия 1903) новые установки Windows 10 больше не будут отображать Люди на панели задач по умолчанию. Клиенты могут включить эту функцию, щелкнув правой кнопкой мыши панель задач и нажав кнопку "Показать Люди на панели задач". Разработчикам не рекомендуется добавлять поддержку my Люди в свои приложения, и следует посетить блог разработчика Windows для получения дополнительных сведений об оптимизации приложений для Windows 10.

Функция "Моя Люди" позволяет пользователям закреплять контакты из приложения непосредственно на панели задач, что создает новый объект контакта, с которым они могут взаимодействовать несколькими способами. В этой статье показано, как добавить поддержку этой функции, позволяя пользователям закреплять контакты непосредственно из приложения. При закреплении контактов новые типы взаимодействия с пользователем становятся доступными, например "Мои Люди совместное использование и уведомления".

My people chat

Requirements

  • Windows 10 и Microsoft Visual Studio 2019. Дополнительные сведения об установке см. в статье "Настройка с помощью Visual Studio".
  • Знание основ C# или схожих объектно-ориентированных языков программирования. Сведения о начале работы с C#см. в статье "Создание приложения Hello, world".

Обзор

Чтобы приложение использовало функцию My Люди, необходимо выполнить три действия.

  1. Объявите поддержку контракта активации shareTarget в манифесте приложения.
  2. Заметьте контакты, к которым пользователи могут предоставить общий доступ с помощью приложения.
  3. Поддержка нескольких экземпляров приложения, выполняющихся одновременно. Пользователи должны иметь возможность взаимодействовать с полной версией приложения при его использовании на панели контактов. Они могут даже использовать его в нескольких контактных панелях одновременно. Для поддержки этого приложение должно одновременно запускать несколько представлений. Чтобы узнать, как это сделать, см. статью "Показать несколько представлений для приложения".

После этого приложение появится на панели контактов для аннотированных контактов.

Объявление поддержки контракта

Чтобы объявить поддержку контракта My Люди, откройте приложение в Visual Studio. В Обозреватель решений щелкните правой кнопкой мыши Package.appxmanifest и выберите "Открыть с помощью". В меню выберите редактор XML (текст) и нажмите кнопку "ОК". Внесите следующие изменения в манифест:

До:

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	    </Application>
	</Applications>

После:

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	      <Extensions>
	        <uap4:Extension Category="windows.contactPanel" />
	      </Extensions>
	    </Application>
	</Applications>

С помощью этого дополнения приложение теперь можно запустить через окна. Контракт ContactPanel , позволяющий взаимодействовать с панелями контактов.

Аннотирование контактов

Чтобы разрешить контактам из приложения отображаться на панели задач через панель "Моя Люди", необходимо написать их в хранилище контактов Windows. Чтобы узнать, как писать контакты, см. пример карточки контакта.

Приложение также должно написать заметку для каждого контакта. Заметки — это фрагменты данных из приложения, связанных с контактом. Заметка должна содержать активируемый класс, соответствующий требуемому представлению в члене ProviderProperties, и объявить поддержку операции ContactProfile.

Вы можете заметить контакты в любой момент во время работы приложения, но обычно вы должны запишите контакты, как только они будут добавлены в хранилище контактов Windows.

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 5))
{
	// Create a new contact annotation
	ContactAnnotation annotation = new ContactAnnotation();
	annotation.ContactId = myContact.Id;

	// Add appId and contact panel support to the annotation
	String appId = "MyApp_vqvv5s4y3scbg!App";
	annotation.ProviderProperties.Add("ContactPanelAppID", appId);
	annotation.SupportedOperations = ContactAnnotationOperations.ContactProfile;

	// Save annotation to contact annotation list
	// Windows.ApplicationModel.Contacts.ContactAnnotationList 
	await contactAnnotationList.TrySaveAnnotationAsync(annotation));
}

AppId — это имя семейства пакетов, за которым следует "!" и идентификатор активируемых классов. Чтобы найти имя семейства пакетов, откройте Package.appxmanifest с помощью редактора по умолчанию и перейдите на вкладку "Упаковка". Здесь "App" — это активируемый класс, соответствующий представлению запуска приложения.

Разрешить контактам приглашать новых потенциальных пользователей

По умолчанию приложение будет отображаться только на панели контактов для контактов, которые вы специально заметили. Это позволяет избежать путаницы с контактами, с которыми невозможно взаимодействовать через приложение. Если вы хотите, чтобы приложение отображалось для контактов, о том, что приложение не знает (чтобы пригласить пользователей добавить этот контакт в свою учетную запись, например), вы можете добавить в манифест следующее:

До:

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
    	<uap4:Extension Category="windows.contactPanel" />
	  </Extensions>
	</Application>
</Applications>

После:

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
		<uap4:Extension Category="windows.contactPanel">
	    	<uap4:ContactPanel SupportsUnknownContacts="true" />
		</uap4:Extension>
	  </Extensions>
	</Application>
</Applications>

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

My People contact panel

Поддержка приложений электронной почты

Если вы пишете приложение электронной почты, вам не нужно добавлять заметки о каждом контакте вручную. Если вы объявляете поддержку области контактов и протокола mailto: протокол, приложение будет автоматически отображаться для пользователей с адресом электронной почты.

Выполнение на панели контактов

Теперь, когда приложение появится на панели контактов для некоторых или всех пользователей, необходимо обработать активацию с помощью контракта панели контактов.

override protected void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.ContactPanel)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        var rootFrame = new Frame();

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;

        // Navigate to the page that shows the Contact UI.
        rootFrame.Navigate(typeof(ContactPage), e);

        // Ensure the current window is active
        Window.Current.Activate();
    }
}

При активации приложения с помощью этого контракта он получит объект ContactPanelActivatedEventArgs. Он содержит идентификатор контакта, с которым приложение пытается взаимодействовать при запуске, и объект ContactPanel . Вы должны сохранить ссылку на этот объект ContactPanel, который позволит взаимодействовать с панелью.

Объект ContactPanel имеет два события, которые приложение должно прослушивать:

  • Событие LaunchFullAppRequested отправляется, когда пользователь вызвал элемент пользовательского интерфейса, запрашивающий запуск полного приложения в собственном окне. Ваше приложение отвечает за запуск, передавая все необходимые контексты. Вы можете сделать это, однако, вы хотите (например, через запуск протокола).
  • Событие закрытия отправляется при закрытии приложения, что позволяет сохранить любой контекст.

Объект ContactPanel также позволяет задать цвет фона заголовка панели контактов (если он не задан, по умолчанию используется системная тема) и программно закрыть панель контактов.

Поддержка неисправного уведомления

Если вы хотите, чтобы контакты, закрепленные на панели задач, отображались при поступлении новых уведомлений из приложения, связанных с этим человеком, необходимо включить параметр подсказки для пользователей в всплывающие уведомления и выражения уведомлений My Люди.

People notification badging

Чтобы провести значок контакта, узел всплывающего уведомления верхнего уровня должен включать параметр подсказки для указания контакта или связанного контакта. Этот параметр может иметь любое из следующих значений:

  • Адрес электронной почты
  • Номер телефона
  • Удаленный идентификатор
    • Например, remoteid:1234

Ниже приведен пример определения всплывающего уведомления, связанного с конкретным человеком:

<toast hint-people="mailto:johndoe@mydomain.com">
    <visual lang="en-US">
        <binding template="ToastText01">
            <text>John Doe posted a comment.</text>
        </binding>
    </visual>
</toast>

Примечание.

Если приложение использует API ContactStore и использует свойство StoredContact.RemoteId для связывания контактов, хранящихся на компьютере, с контактами, хранящимися удаленно, важно, чтобы значение свойства RemoteId было стабильным и уникальным. Это означает, что удаленный идентификатор должен последовательно определять одну учетную запись пользователя и содержать уникальный тег, чтобы гарантировать, что он не конфликтует с удаленными идентификаторами других контактов на компьютере, включая контакты, принадлежащие другим приложениям. Если удаленные идентификаторы, используемые приложением, не будут стабильными и уникальными, можно использовать класс RemoteIdHelper, показанный далее в этом разделе, чтобы добавить уникальный тег ко всем удаленным идентификаторам перед добавлением их в систему. Или вы можете не использовать свойство RemoteId вообще и вместо этого создать настраиваемое расширенное свойство, в котором хранятся удаленные идентификаторы для контактов.

Класс PinnedContactManager

PinnedContactManager используется для управления контактами, закрепленными на панели задач. Этот класс позволяет закреплять и открепить контакты, определять, закреплен ли контакт, а также определить, поддерживается ли закрепление на определенной поверхности системой, в которую в настоящее время работает ваше приложение.

Объект PinnedContactManager можно получить с помощью метода GetDefault :

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Закрепление и отключение контактов

Теперь вы можете закрепить и открепить контакты с помощью только что созданного pinnedContactManager. Методы RequestPinContactAsync и RequestUnpinContactAsync предоставляют пользователю диалоговые окна подтверждения, поэтому их необходимо вызывать из потока однопоточной квартиры приложения (ASTA или пользовательского интерфейса).

async void PinContact (Contact contact)
{
    await pinnedContactManager.RequestPinContactAsync(contact,
                                                      PinnedContactSurface.Taskbar);
}

async void UnpinContact (Contact contact)
{
    await pinnedContactManager.RequestUnpinContactAsync(contact,
                                                        PinnedContactSurface.Taskbar);
}

Вы также можете закрепить несколько контактов одновременно:

async Task PinMultipleContacts(Contact[] contacts)
{
    await pinnedContactManager.RequestPinContactsAsync(
        contacts, PinnedContactSurface.Taskbar);
}

Примечание.

В настоящее время для отмены контактов нет пакетной операции.

Примечание.

См. также