Компонент средства выбора в наборе средств Microsoft Graph

Статья
02/08/2024

Компонент Выбора использует для mgt-get запроса Microsoft API Graph затем отображает раскрывающийся элемент управления, позволяющий выбрать один ресурс из массива ресурсов.

Пример

В следующем примере показано использование компонента для mgt-picker выбора списка задач из списков задач пользователя. Вы можете использовать редактор кода, чтобы узнать, как свойства и атрибуты изменяют поведение компонента.

HTML
React;

Откройте этот пример в mgt.dev.

Свойства и атрибуты

Чтобы изменить поведение компонента, можно использовать несколько атрибутов. Компонент имеет обязательные атрибуты, такие как resource , например, /users и key-name , например, displayName.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
    "id": "03ef14b0-ca33-4840-8f4f-d6e91916010e",
    "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
    },
    "certification": {
           "isPublisherAttested": true,
           "isCertifiedByMicrosoft": true,
           "lastCertificationDateTime": "2021-05-11T23:26:20Z",
           "certificationExpirationDateTime": "2022-05-11T23:26:20Z",
           "certificationDetailsUrl": "https://learn.microsoft.com/microsoft-365-app-certification/forward/azure/631a96bc-a705-4eda-9f99-fdaf9f54f6a2"
    },
    "tags": [],
    "tokenEncryptionKeyId": null,
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "appRoles": [],
    "web": {
        "redirectUris": [],
        "homePageUrl": null,
        "logoutUrl": null,
        "implicitGrantSettings": {
            "enableIdTokenIssuance": false,
            "enableAccessTokenIssuance": false
        }
    }
}

значение атрибута key-name может иметь значение web.homePageUrl или verifiedPublisher.displayName.

Атрибут	Свойство	Описание
resource	resource	Ресурс, который требуется получить из Microsoft Graph (например, `/me` или `/users`).
placeholder	placeholder	Заполнитель, отображаемый в средства выбора (например, `Select a user` или `Select a task list`).
key-name	keyName	Ключ для отображения в средства выбора (например, `displayName`).
выбранное значение	Selectedvalue	Необязательный параметр. Значение, которое должно быть задано в качестве выбранного в данный момент параметра в элементе выбора. Должен присутствовать в параметрах, предоставляемых запросом Microsoft Graph.
scopes	scopes	Необязательный массив строк, если используется свойство либо область с разделителями-запятыми, при использовании атрибута. Компонент и поддерживаемый поставщик гарантируют, что пользователь дал согласие по крайней мере на одно из предоставленных разрешений.
version	version	Необязательная версия API, используемая при выполнении `GET` запроса. Значение по умолчанию: `v1.0`.
max-pages	maxPages	Необязательное количество страниц (для ресурсов, поддерживающих разделение на страницы). Значение по умолчанию: 3. При установке этого значения 0 извлекаются все страницы.
cache-enabled	cacheEnabled	Необязательное логическое значение. Если задано значение , это означает, что ответ от ресурса кэшируется. Переопределите, если `refresh()` вызывается или используется `pollingRate` . Значение по умолчанию: `false`.
cache-invalidation-period	cacheInvalidationPeriod	Необязательное количество миллисекунда. Если задано в сочетании с `cacheEnabled`, задержка до того, как кэш достигнет своего периода недействительности, изменяет это значение. Значение по умолчанию — и `0` использует период недействительности по умолчанию.
Н/Д	response	Нередактируемый ответ в Microsoft Graph, если запрос был успешен.
Н/Д	error	Ошибка только для чтения из Microsoft Graph, если запрос не был успешным.

Настраиваемые свойства CSS

Компонент mgt-picker определяет следующие настраиваемые свойства CSS для предоставления переопределений.

<mgt-picker
  class="picker"
  resource="me/todo/lists"
  scopes="tasks.read, tasks.readwrite"
  key-name="displayName"
></mgt-picker>

.picker {
  --picker-background-color: grey;
  --picker-list-max-height: 200px;
}

Дополнительные сведения см. в статье Компоненты стиля.

Методы

Метод	Описание
refresh(force?: boolean)	Вызов метода для обновления данных. По умолчанию пользовательский интерфейс обновляется только при изменении данных. Передайте `true` для принудительного обновления компонента.

События

Событие	Когда он генерируется	Пользовательские данные	Отменяемым	Пузыри	Работает с пользовательским шаблоном
`selectionChanged`	Срабатывает при изменении выбранного ресурса в раскрывающемся списке.	`{ response: any, error: any }`. Свойство `response` содержит ответ, полученный из Microsoft Graph. Свойство `error` содержит сведения об ошибке, если она произошла.	Нет	Да	Да

Совет

Дополнительные сведения о данных, возвращаемых в свойстве response , см. в справочнике по API, который вы использовали в свойстве resource компонента Picker.

Дополнительные сведения об обработке событий см. в разделе События.

Шаблоны

Компонент mgt-picker поддерживает несколько шаблонов, с помощью которых можно определить внешний вид и удобство использования. Чтобы указать шаблон, включите <template> элемент внутри компонента и задайте для data-type параметра одно из следующих значений.

Тип данных	Контекст данных	Описание
error	Ошибка из Microsoft Graph.	Этот шаблон используется при возникновении ошибки при выполнении запроса.
loading	Н/Д	Этот шаблон используется во время выполнения запроса.
no-data	Н/Д	Этот шаблон используется, когда запрос не возвращает данных.

Пример использования шаблона

<mgt-picker resource="me/todo/lists" scopes="tasks.read, tasks.readwrite" key-name="displayName">
  <div>Loading template</div>
    <template data-type="loading">
      Loading
    </template>
    <template data-type="no-data">
      <div>No data</div>
    </template>
    <template data-type="error">
      <div>Error</div>
    </template>
  </div>
</mgt-picker>

Разрешения Microsoft Graph

Разрешения, необходимые для этого компонента, зависят от данных, которые вы хотите получить с помощью Microsoft Graph. Microsoft Graph Toolkit проверяет, согласился ли текущий пользователь по крайней мере на один из предоставленных scopes. Дополнительные сведения о разрешениях см. в справочнике по разрешениям Microsoft Graph.

Проверка подлинности

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

Кэш

Чтобы включить и настроить кэш, используйте cacheEnabled свойства и cacheInvalidationPeriod . По умолчанию mgt-picker компонент не кэширует ответы.

Хранилище объектов	Кэшированные данные	Замечания
`response`	Полный ответ, полученный из Microsoft Graph для запроса, указанного в свойстве `resourcemgt-picker`

Дополнительные сведения см. в разделе Кэширование.

Локализация

Элемент управления предоставляет следующие переменные, которые можно локализовать. Дополнительные сведения о настройке локализации см. в разделе Локализация компонентов.

Имя строки	Значение по умолчанию
comboboxPlaceholder	`Select an item`