Добавление поддержки функции "Близкие люди" в приложениеAdding My People support to an application

Примечание

Начиная с Windows 10 Май 2019 обновления (версия 1903), новые установки Windows 10 больше не будут показывать "пользователи на панели задач" по умолчанию.As of the Windows 10 May 2019 Update (version 1903), new Windows 10 installations will no longer show ‘People in the taskbar’ by default. Клиенты могут включить эту функцию, щелкнув правой кнопкой мыши панель задач и нажав кнопку "отображать людей на панели задач".Customers can enable the feature by right-clicking on the taskbar and pressing “Show People on the taskbar.” Разработчикам не рекомендуется добавлять поддержку пользователей в свои приложения, и вы должны посетить блог разработчиков Windows , чтобы получить дополнительные сведения о оптимизации приложений для Windows 10.Developers are discouraged from adding My People support to their applications, and should visit the Windows Developer Blog for more information about optimizing apps for Windows 10.

Функция "Близкие люди" позволяет пользователям закреплять контакты из приложения непосредственно на панели задач. При этом создается новый объект контакта, с который они могут взаимодействовать несколькими способами.The My People feature allows users to pin contacts from an application directly to their taskbar, which creates a new contact object that they can interact with in several ways. В этой статье показано, как добавить поддержку этой функции, чтобы пользователи могли закреплять контакты непосредственно из приложения.This article shows how you can add support for this feature, allowing users to pin contacts directly from your app. Когда контакты закреплены, становятся доступны новые типы взаимодействия с пользователем, такие как публикация для близких людей и уведомления.When contacts are pinned, new types of user interaction become available, such as My People sharing and notifications.

Чат "Близкие люди"

ТребованияRequirements

ОбзорOverview

Чтобы реализовать поддержку функции "Близкие люди" в приложении, необходимо выполнить три действия:There are three things you need to do to enable your application to use the My People feature:

  1. Объявить поддержку контракта активации shareTarget в манифесте приложения.Declare support for the shareTarget activation contract in your application manifest.
  2. Указать контакты, с которыми пользователи могут делиться данными с помощью вашего приложения.Annotate the contacts that the users can share to using your app.
  3. Реализовать поддержку нескольких экземпляров приложения, запущенных одновременно.Support multiple instances of your application running at the same time. Пользователям необходимо взаимодействовать с полной версией приложения при работе с ним на панели контактов.Users must be able to interact with a full version of your application while using it in a contact panel. Они могут даже использовать его на нескольких панелях контактов одновременно.They may even use it in multiple contact panels at once. Для этого приложение должно поддерживать возможность одновременного запуска нескольких представлений.To support this, your application needs to be able to run multiple views simultaneously. Сведения о том, как это сделать, см. в статье Отображение нескольких представлений для приложения.To learn how to do this, see the article "show multiple views for an app".

После реализации этой возможности ваше приложение будет отображаться на панели контактов для указанных контактов.When you’ve done this, your application will appear in the contact panel for annotated contacts.

Объявление поддержки контрактаDeclaring support for the contract

Чтобы объявить поддержку контракта "Близкие люди", откройте приложение в Visual Studio.To declare support for the My People contract, open your application in Visual Studio. В обозревателе решений щелкните правой кнопкой мыши файл Package.appxmanifest и выберите команду Открыть с помощью.From the Solution Explorer, right click Package.appxmanifest and select Open With. В меню выберите XML (текстовый редактор ) и нажмите кнопку ОК.From the menu, select XML (Text) Editor) and click OK. Внесите следующие изменения в манифест:Make the following changes to the manifest:

ДоBefore

<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>

ПослеAfter

<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>

После этого ваше приложение можно будет запускать через контракт windows.ContactPanel, который позволяет взаимодействовать с панелями контакта.With this addition, your application can now be launched through the windows.ContactPanel contract, which allows you to interact with contact panels.

Аннотация контактовAnnotating contacts

Чтобы включить отображение контактов из вашего приложения на панели задач с использованием области "Близкие люди", необходимо записать их в хранилище контактов Windows.To allow contacts from your application to appear in the taskbar via the My People pane, you need to write them to the Windows contact store. Сведения о записи контактов см. в разделе Пример карточки контакта.To learn how to write contacts, see the Contact Card sample.

Ваше приложение также должно записать аннотацию для каждого контакта.Your application must also write an annotation to each contact. Аннотации — это компоненты данных из приложения, связанные с контактом.Annotations are pieces of data from your application that are associated with a contact. Аннотация должна содержать активируемый класс, соответствующий требуемому представлению, в элементе ProviderProperties, а также должна объявить поддержку операции ContactProfile.The annotation must contain the activatable class corresponding to your desired view in its ProviderProperties member, and declare support for the ContactProfile operation.

Аннотировать контакты можно в любой момент во время работы приложения, но в общем случае необходимо делать это, как только они добавляются в хранилище контактов Windows.You can annotate contacts at any point while your app is running, but generally you should annotate contacts as soon as they are added to the Windows contact store.

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" — это имя семейства пакетов, за которым следует символ "!"The “appId” is the Package Family Name, followed by ‘!’ и идентификатор активируемого класса.and the activatable class ID. Чтобы найти имя семейства пакета, откройте Package.appxmanifest с помощью редактора по умолчанию и найдите вкладку «Упаковка». Здесь элемент «Приложение» является активируемым классом, соответствующим представлению запуска приложения.To find your Package Family Name, open Package.appxmanifest using the default editor, and look in the “Packaging” tab. Here, “App” is the activatable class corresponding to the application startup view.

Предоставление контактам возможности приглашать новых потенциальных пользователейAllow contacts to invite new potential users

По умолчанию приложение отображается на панели контактов только для указанных вами контактов.By default, your application will only appear in the contact panel for contacts that you have specifically annotated. Это позволяет избежать путаницы с контактами, с которыми невозможно взаимодействовать с помощью вашего приложения.This is to avoid confusion with contacts that can’t be interacted with through your app. Чтобы приложение отображалось для контактов, которые неизвестны вашему приложению (например, чтобы пригласить пользователей добавить эти контакты в свою учетную запись), можно добавить следующий код в манифест:If you want your application to appear for contacts that your application doesn’t know about (to invite users to add that contact to their account, for instance), you can add the following to your manifest:

ДоBefore

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

ПослеAfter

<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>

После этого изменения приложение будет отображаться как доступный параметр на панели контактов для всех закрепленных пользователем контактов.With this change, your application will appear as an available option in the contact panel for all contacts that the user has pinned. Когда приложение активируются с помощью контракта панели контактов, необходимо проверить, известен ли этот контакт вашему приложению.When your application is activated using the contact panel contract, you should check to see if the contact is one your application knows about. Если это не так, следует отобразить интерфейс для нового пользователя.If not, you should show your app’s new user experience.

Панель контактов "Близкие люди"

Поддержка почтовых приложенийSupport for email apps

Если вы создаете почтовое приложение, вам не нужно аннотировать каждый контакт вручную.If you are writing an email app, you don’t need to annotate every contact manually. Если объявить поддержку панели контактов и протокола mailto:, приложение автоматически будет отображаться для пользователей с электронным адресом.If you declare support for the contact pane and for the mailto: protocol, your application will automatically appear for users with an email address.

Запуск на панели контактовRunning in the contact panel

Когда приложение появится на панели контактов для некоторых или всех пользователей, необходимо обрабатывать активацию с помощью контракта панели контактов.Now that your application appears in the contact panel for some or all users, you need to handle activation with the contact panel contract.

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.When your application is activated with this contract, it will receive a ContactPanelActivatedEventArgs object. Он содержит идентификатор контакта, с которым ваше приложение пытается взаимодействовать при запуске, и объект ContactPanel.This contains the ID of the Contact that your application is trying to interact with on launch, and a ContactPanel object. Вам следует сохранить ссылку на этот объект ContactPanel, что позволит взаимодействовать с панелью.You should keep a reference to this ContactPanel object, which will allow you to interact with the panel.

Объект ContactPanel предоставляет два события, которые ваше приложение должно прослушивать.The ContactPanel object has two events your application should listen for:

  • Событие LaunchFullAppRequested отправляется, когда пользователь вызывает элемент интерфейса, который запрашивает запуск полного приложения в отдельном окне.The LaunchFullAppRequested event is sent when the user has invoked the UI element that requests that your full application be launched in its own window. Ваше приложение отвечает за собственный запуск и передачу необходимого контекста.Your application is responsible for launching itself, passing along all necessary context. Вы можете сделать это любым способом (например, за счет запуска протокола).You are free to do this however you’d like (for example, via protocol launch).
  • Событие Closing отправляется, когда приложение закрывается, что позволяет сохранить любой контекст.The Closing event is sent when your application is about to be closed, allowing you to save any context.

С помощью объекта ContactPanel также можно задать цвет фона заголовка панели контактов (если он не задан, используется цвет системной темы) и программно закрыть панель контактов.The ContactPanel object also allows you to set the background color of the contact panel header (if not set, it will default to the system theme) and to programmatically close the contact panel.

Поддержка индикаторов для уведомленийSupporting notification badging

Если вы хотите, чтобы на контактах, закрепленных на панели задач, появлялись индикаторы при получении новых уведомлений, связанных с этим контактом, из вашего приложения, необходимо включить параметр hint-people во всплывающих уведомлениях и явные Уведомления близких людей.If you want contacts pinned to the taskbar to be badged when new notifications arrive from your app that are related to that person, then you must include the hint-people parameter in your toast notifications and expressive My People notifications.

Индикаторы для уведомлений людей

Для добавления индикатора контакту узел всплывающего уведомления верхнего уровня должен содержать параметр hint-people для указания контакта-отправителя или связанного контакта.To badge a contact, the top-level toast node must include the hint-people parameter to indicate the sending or related contact. Этот параметр может принимать любое из перечисленных ниже значений.This parameter can have any of the following values:

  • Адрес электронной почтыEmail address
    • Пример:E.g. mailto:johndoe@mydomain.commailto:johndoe@mydomain.com
  • Номер телефонаTelephone number
    • Пример:E.g. tel:888-888-8888tel:888-888-8888
  • удаленный идентификатор;Remote ID
    • Пример:E.g. remoteid:1234remoteid:1234

Ниже приведен пример определения всплывающего уведомления, связанного с определенным человеком.Here is an example of how to identify a toast notification is related to a specific person:

<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 было и стабильным, и уникальным.If your app uses the ContactStore APIs and uses the StoredContact.RemoteId property to link contacts stored on the PC with contacts stored remotely, it is essential that the value for the RemoteId property is both stable and unique. Это значит, что удаленный идентификатор должен неизменно обозначать одну учетную запись пользователя и содержать уникальный тег, чтобы гарантировать отсутствие конфликтов с удаленными идентификаторами других контактов на компьютере, включая контакты, которыми владеют другие приложения.This means that the remote ID must consistently identify a single user account and should contain a unique tag to guarantee that it does not conflict with the remote IDs of other contacts on the PC, including contacts that are owned by other apps. Если уникальность и стабильность удаленных идентификаторов, используемых вашим приложением, нельзя гарантировать, то можно использовать класс RemoteIdHelper, показанный ниже в этом разделе, чтобы добавить ко всем вашим удаленным идентификаторам уникальный тег перед добавлением их к системе.If the remote IDs used by your app are not guaranteed to be stable and unique, you can use the RemoteIdHelper class shown later in this topic in order to add a unique tag to all of your remote IDs before you add them to the system. Или можно вовсе отказаться от использования свойства RemoteId и создать собственное расширенное свойство, в котором будут храниться удаленные идентификаторы для ваших контактов.Or you can choose to not use the RemoteId property at all and instead you create a custom extended property in which to store remote IDs for your contacts.

Класс The PinnedContactManagerThe PinnedContactManager class

Класс PinnedContactManager используется для управления контактами, которые закреплены на панели задач.The PinnedContactManager is used to manage which contacts are pinned to the taskbar. Этот класс позволяет закрепить и открепить контакты, определить, закреплен ли контакт и поддерживается ли закрепление на той или иной поверхности системой, в которой сейчас выполняется приложение.This class lets you pin and unpin contacts, determine whether a contact is pinned, and determine if pinning on a particular surface is supported by the system your application is currently running on.

Вы можете получить объект PinnedContactManager с помощью метода GetDefault:You can retrieve the PinnedContactManager object using the GetDefault method:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Закрепление и открепление контактовPinning and unpinning contacts

Теперь вы можете закреплять и откреплять контакты с помощью созданного объекта PinnedContactManager.You can now pin and unpin contacts using the PinnedContactManager you just created. Методы RequestPinContactAsync и RequestUnpinContactAsync предоставляют пользователям диалоговые окна подтверждения, поэтому их следует вызывать из вашего потока ASTA или пользовательского интерфейса.The RequestPinContactAsync and RequestUnpinContactAsync methods provide the user with confirmation dialogs, so they must be called from your Application Single-Threaded Apartment (ASTA, or UI) thread.

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

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

Можно также закрепить несколько контактов одновременно:You can also pin multiple contacts at the same time:

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

Примечание

В данный момент пакетная операция для закрепления контактов отсутствует.There is currently no batch operation for unpinning contacts.

Примечание.Note:

См. также разделSee also