Поделиться через

Настройка значка веб-части

  • Статья

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

Предварительная настройка веб-частей

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

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

В манифесте веб-части можно настроить значок веб-части, отображаемый на панели элементов, и изображение предварительного просмотра, отображаемое при создании страниц приложения с одной веб-частью.

Укажите значок для панели элементов

Значок для панели элементов отображается на панели элементов веб-части, когда пользователи добавляют веб-часть на страницу.

Панель элементов веб-части отображается на современной странице

В SharePoint Framework поддерживаются разные способы определения значка вашей веб-части для панели элементов.

Использование шрифта значков Fluent UI

Один из способов определить значок для вашей веб-части — воспользоваться свойством officeFabricIconFontName. С помощью этого свойства можно выбрать один из значков, входящих в состав Fluent UI.

Список доступных значков Fluent UI см. в разделе Значки.

Использование определенного значка

  1. Скопируйте имя значка со страницы обзора значков Fluent UI и вставьте его в качестве значения свойства officeFabricIconFontName в манифест веб-части.

    Стрелка от имени значка на странице с обзором значков Fluent UI к коду манифеста веб-части

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "bcae7077-85cb-41a0-b3d3-2084f268a211",
  "alias": "WeatherWebPart",
  "componentType": "WebPart",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,
  "preconfiguredEntries": [
    {
      "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
      "group": {
        "default": "Advanced"
      },
      "title": {
        "default": "Weather"
      },
      "description": {
        "default": "Shows current weather in the given location"
      },
      "officeFabricIconFontName": "Sunny",
      "properties": {
        "location": "Munich"
      }
    }
  ]
}

  2. При добавлении веб-части на страницу выбранный значок будет отображаться на панели элементов.

Выбранный значок Fluent UI, представляющий веб-часть на панели элементов

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

Использование внешнего изображения

Fluent UI предоставляет множество изображений, но при создании веб-частей вам может потребоваться использовать значок, относящийся к вашей организации, чтобы четко отделить свои веб-части от других веб-частей (как собственных, так и сторонних) на панели элементов.

Помимо значков Fluent UI, на платформе SharePoint Framework также можно использовать изображения.

Использование изображения в качестве значка веб-части

  1. Укажите абсолютный URL-адрес изображения в свойстве iconImageUrl в манифесте веб-части.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "bcae7077-85cb-41a0-b3d3-2084f268a211",
  "alias": "WeatherWebPart",
  "componentType": "WebPart",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,
  "preconfiguredEntries": [
    {
      "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
      "group": {
        "default": "Advanced"
      },
      "title": {
        "default": "Weather"
      },
      "description": {
        "default": "Shows current weather in the given location"
      },
      "iconImageUrl": "https://assets.contoso.com/weather.png",
      "properties": {
        "location": "Munich"
      }
    }
  ]
}

  2. Размер значка веб-части, отображаемого на панели элементов, составляет 40 x 28 пикселей. Если указано изображение большего размера, оно будет уменьшено с сохранением пропорций.

    Пользовательское изображение, используемое в качестве значка веб-части на панели элементов

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

Использование изображения в кодировке Base64

При использовании собственного изображения можно не указывать абсолютный URL-адрес файла изображения, размещенного вместе с другими ресурсами веб-части, а закодировать изображение в формате Base64 и использовать строку Base64 вместо URL-адреса.

В Интернете есть ряд служб, позволяющих закодировать изображение в формате Base64, например эта.

Использование изображения в кодировке Base64

  1. Закодируйте изображение.

  2. Скопируйте строку в кодировке Base64 и используйте ее в качестве значения свойства iconImageUrl в манифесте веб-части.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "bcae7077-85cb-41a0-b3d3-2084f268a211",
  "alias": "WeatherWebPart",
  "componentType": "WebPart",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,
  "preconfiguredEntries": [
    {
      "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
      "group": {
        "default": "Advanced"
      },
      "title": {
        "default": "Weather"
      },
      "description": {
        "default": "Shows current weather in the given location"
      },
      "iconImageUrl": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMTAyMiIgaGVpZ2h0PSI5NzgiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6c3ZnPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CiA8Zz4KICA8dGl0bGU+TGF5ZXIgMTwvdGl...",
      "properties": {
        "location": "Munich"
      }
    }
  ]
}

Кодировка Base64 подходит как для растровых изображений (например, PNG-файлов), так и для векторных изображений в формате SVG. Главное преимущество изображений в кодировке Base64 заключается в том, что нет необходимости отдельно развертывать значок веб-части.

Изображение в кодировке Base64 отображается в качестве значка веб-части на панели элементов

Дополнительные рекомендации

У каждой веб-части должен быть значок. Если значок веб-части задан с помощью свойств officeFabricIconFontName и iconImageUrl, используется значок, указанный в officeFabricIconFontName.

Если вы не используете значок Fluent UI, необходимо указать URL-адрес в свойстве iconImageUrl.

Настройка изображения предварительного просмотра для страницы приложения с одной веб-частью

В SharePoint Framework 1.11 и более поздних версий можно указать изображение предварительного просмотра для вашей веб-части. Это изображение будет показано при создании пользователями страницы приложения с одной веб-частью.

Изображение предварительного просмотра страницы приложения с одной веб-частью отображается при создании такой страницы приложения

Осторожностью

В настоящее время можно задать только URL-адрес изображения страницы приложения с одной веб-частью. Использование изображений в кодировке Base64 в настоящее время не поддерживается.

Настройка изображения предварительного просмотра для страницы приложения с одной веб-частью

Укажите абсолютный URL-адрес изображения в свойстве fullPageAppIconImageUrl в манифесте веб-части.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "bcae7077-85cb-41a0-b3d3-2084f268a211",
  "alias": "WeatherWebPart",
  "componentType": "WebPart",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,
  "preconfiguredEntries": [
    {
      "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
      "group": {
        "default": "Advanced"
      },
      "title": {
        "default": "Weather"
      },
      "description": {
        "default": "Shows current weather in the given location"
      },
      "officeFabricIconFontName": "Sunny",
      "fullPageAppIconImageUrl": "https://assets.contoso.com/fullPageAppIcon.png",
      "properties": {
        "location": "Munich"
      }
    }
  ]
}

Совет

Если изображение отобразилось в браузере, размер изображения будет скорректирован в зависимости от текущего размера экрана. Размер изображения по умолчанию — 193 на 158 пикселей, причем нижние 48 пикселей частично закрыты меткой с именем веб-части. На небольших экранах размер отображаемого изображения будет различаться, а метка с именем веб-части может закрывать относительно более крупную часть изображения.