Использование Office UI Fabric Core и Fabric React в SharePoint Framework

Статья
03/21/2023

Office UI Fabric — это официальная интерфейсная платформа для создания возможностей в Office 365 и SharePoint. SharePoint обеспечивает простую интеграцию с Fabric, что позволяет корпорации Майкрософт предоставлять надежный и согласованный язык проектирования в различных интерфейсах SharePoint, таких как современные сайты групп, современные страницы и современные списки. Кроме того, UI Fabric Office доступен разработчикам в SharePoint Framework при создании пользовательских решений SharePoint.

Корпорация Майкрософт использует Fabric Core и Fabric React в SharePoint. Она регулярно выпускает обновления для SharePoint Online, при установке которых также могут обновиться ваши версии Fabric Core и Fabric React. Возможны конфликты этих обновлений со сторонними клиентскими решениями, созданными с помощью предыдущих версий Fabric Core и Fabric React. В результате этого в таких модификациях могут возникать исключения. Основная причина таких сбоев — использование глобальных стилей CSS в обеих библиотеках Fabric. Таких конфликтов следует избегать любой ценой.

Трудности с глобальными стилями CSS хорошо описаны в следующей презентации на примере React и JavaScript: React CSS в JS.

Одно из главных препятствий для обеспечения надежности — использование глобальных стилей CSS. Это гарантирует, что вместо глобальных имен классов в разметке HTML будут использоваться примеси и переменные Fabric Core в файле объявлений SASS. При этом объявления SASS для Fabric Core импортируются из файла SASS, после чего переменные и примеси используются надлежащим образом.

Цели

Цель SharePoint Framework — помочь корпорации Майкрософт и ее клиентам создавать функциональные, привлекательные и согласованные решения на основе SharePoint.

Достижению этих целей способствуют основные принципы разработки, перечисленные ниже.

Удобство и надежность для пользователей при использовании Fabric Core и Fabric React в решениях.
Корпорация Майкрософт должна развертывать обновленные решения, использующие обновленные версии Fabric Core и Fabric React, в SharePoint без конфликтов с решениями клиента.
Пользователи должны иметь возможность настраивать и переопределять стили, оформление и компоненты в соответствии с потребностями решения.

Office UI Fabric состоит из двух частей, доступных разработчикам:

Office UI Fabric Core. Набор, включающий основные стили, оформление, адаптируемую сетку, анимацию, значки и другие стандартные блоки общего языка дизайна.
Office UI Fabric React. Набор компонентов React, основанных на языке дизайна Fabric, для использования в проектах на основе React.

Пакет Office UI Fabric Core

Пакет npm с SharePoint Framework Fabric Core (@microsoft/sp-office-ui-fabric-core) содержит поддерживаемые стили Fabric Core, которые можно безопасно использовать в компоненте SharePoint Framework.

В пакете поддерживаются следующие основные стили:

шрифтовое оформление;
макеты;
цвета;
темы;
локализация.

В нем пока что не поддерживаются следующие элементы:

анимация;
Значки

Начиная с версии 1.3.4 генератора Yeoman для SharePoint Framework стандартные шаблоны проектов (веб-частей и расширений) включают новый пакет @microsoft/sp-office-ui-fabric-core и используют основные стили из пакета, а не глобальные стили CSS.

Обновление существующих проектов

Чтобы использовать пакет Fabric Core в имеющемся проекте, установите пакет в качестве зависимости:

npm install @microsoft/sp-office-ui-fabric-core --save

После установки можно импортировать объявления SASS для Fabric Core из файла определений SASS, а затем использовать примеси и переменные, как описано в разделе ниже.

Использование стилей Fabric Core

Чтобы использовать стили Fabric Core, необходимо импортировать объявления SPFabricCore в файл SASS.

Примечание.

Убедитесь, что установлен пакет npm @microsoft/sp-office-ui-fabric-core.

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

Теперь вы можете использовать основные стили в качестве примесей и переменных.

.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-themeDark;
  padding: 20px;
}

Office UI Fabric React

Рекомендуем использовать версии пакета Fabric React пользовательского интерфейса Office, включенного в проект генератора Yeoman SharePoint Framework. Например, версия 1.7.0 SharePoint Framework использует версию Fabric React 5.131.0

Примечание.

Fabric React версий 2.x и ниже не поддерживается в SharePoint Framework.

Установив пакет Fabric React, вы можете импортировать из него необходимые компоненты.

//import Button component from Fabric React Button bundle
import { Button } from 'office-ui-fabric-react/lib/Button';

//use it in your component
render() {
  ...
  <div>
    <Button>click me</Button>
  </div>
  ...
}

Пакет Fabric React включает поддерживаемые стили Fabric Core, используемые в компонентах Fabric React. Рекомендуем импортировать стили Fabric Core из пакета Fabric React, а не @microsoft/sp-office-ui-fabric-core, чтобы обеспечить использование подходящих стилей в компоненте.

Так как пакет @microsoft/sp-office-ui-fabric-core уже установлен в решении генератором Yeoman, рекомендуем удалить этот пакет, если вы решите использовать компоненты Fabric и уменьшить размер пакета компонентов.

npm uninstall @microsoft/sp-office-ui-fabric-core --save

После этого вы можете импортировать основные стили из объявлений SASS, доступных в пакете Fabric React.

@import '~office-ui-fabric-react/dist/sass/_References.scss';

Общие сведения об этом подходе и его недостатках

Компоненты Fabric в решении привязаны к установленной у вас версии Fabric React. Чтобы получить новые компоненты (если они доступны в более новой версии пакета), необходимо обновить пакет Fabric React. Так как компоненты Fabric включены в пакет компонентов, его размер может увеличиться. Однако это единственный официально поддерживаемый подход при использовании Office UI Fabric React в решениях SharePoint Framework.

Трудности с CSS в Office UI Fabric

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

Глобальные стилей CSS

Как избегать использования глобальных стилей CSS любой ценой — это серьезная проблема. На данный момент библиотеки Fabric Core и Fabric React содержат глобальные стили. Отсутствие встроенных в браузеры решений для управления областями стилей делает это очень трудной задачей.

Области CSS находятся на ранней стадии рассмотрения.
Элементы IFrame плохо подходят для изолирования стилей.
Веб-компоненты — еще один стандарт, который включает стили с ограниченной областью действия, но пока только обсуждается.
Суть проблемы хорошо раскрыта в обсуждении React CSS в JS.

В Интернете есть множество другой документации, посвященной решениям проблемы с глобальными пространствами имен.

Специфичность CSS

Как правила CSS применяются к веб-интерфейсу? Стили с большей специфичностью переопределяют стили с меньшей специфичностью. Но самое важное — понять, как применяются правила специфичности. Общий порядок приоритетов (по убыванию) выглядит так:

атрибут стиля (например, style="background:red;");
селекторы идентификаторов (#myDiv { });
селекторы классов (.myCssClass{}), селекторы атрибутов ([type="radio"]) и псевдоклассы (:hover);
селекторы типов (h1).

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

<style>
  .greenButton { color: green; }
</style>
<style>
  .redButton { color: red; }
</style>
<body>
  <button class="greenButton redButton"></button>
</body>

Другие подходы, которые были рассмотрены и отклонены

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

Office UI Fabric Core

Разработчику веб-части не требовалось бы выполнять никаких явных действий, чтобы определения областей работали. Мы планировали решить эту проблему с помощью специфичности CSS и селектора потомков. Разработчики Fabric Core собирались выпустить несколько копий CSS-файла Fabric Core (например, fabric-6.css, fabric-6-scoped.css, fabric-6.0.0.css и fabric-6.0.0-scoped.css).

Все стили в CSS-файлах с ограниченной областью действия были бы включены в селектор потомков, например .ms-Fabric--v6-0-0 .ms-Icon--List. Во время компиляции инструменты получали бы версию Office UI Fabric Core, с помощью которой была создана веб-часть. Это могла быть версия, входящая в состав SharePoint Framework. Кроме того, разработчики веб-частей могли бы явно указывать зависимость от определенной версии Office UI Fabric Core в файле package.json.

Разделителю веб-части была бы назначена эта область действия, т. е. <div data-sp-webpart class="ms-Fabric--v6-0-0">. Платформа загружала бы определенную основную версию CSS-файла с областью действия на уровне Fabric Core. Если веб-часть была создана с помощью CSS-файла Fabric Core версии 6.0.0, платформа скачивала бы файл fabric-6-scoped.css во время загрузки веб-части.

Остальная часть страницы содержала бы стили Office UI Fabric Core с неограниченной областью действия. Таким образом, согласно правилам специфичности CSS внутри разделителя веб-части имели бы приоритет стили CSS с ограниченной областью действия. Веб-часть и ее содержимое приспосабливались бы к определенной версии Office UI Fabric Core, выбранной разработчиком.

Переопределение стилей Fabric Core не поддерживалось бы.

// Sample of how the scoping would work.
import { SPComponentLoader } from '@microsoft/sp-loader';

export default class MyWebPart {
    constructor() {
        super();

        SPComponentLoader.loadCss('https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/6.0.0/css/fabric-6.0.0.scoped.css');
    }
}

protected render(): void {
  <div className="ms-Fabric--v6-0-0">
    { // Rest of the web part UI }
  </div>
}

Недостатки этой стратегии

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

Отсутствие надежной поддержки вложения

Этот подход работает, только если страница и веб-части Майкрософт используют версию Office UI Fabric Core (т. е. ms-Icon--List) с неограниченной областью действия, а сторонние веб-части — только CSS Office UI Fabric Core с ограниченной областью действия, как описано выше.

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

Кроме того, несколько расширений, вложенных друг в друга, не могут использовать разные версии Fabric Core. Например, в примере ниже применяется только ms-Fabric--v6-0-0.

<div className="ms-Fabric--v6-0-0">
  { // Rest of the web part UI }
    { // inside of this SPExtension trying to use different Fabric core version does not work }
    <div className="ms-Fabric--v8-0-0">
    </div>
</div>

Ниже представлен более простой пример, иллюстрирующий эту проблему.

<html>
<head>
  <title>CSS specifity test</title>
  <style>
  .myButton {
      background-color: brown;
      color: brown;
      height: 20px;
      width: 40px;
  }
  </style>
  <style>
  .scope2 .myButton {
      background-color: green;
      color: green;
  }
  </style>
  <style>
  .scope3 .myButton {
      background-color: yellow;
      color: yellow;
  }
  </style>
  <style>
  .scope1 .myButton {
      background-color: red;
      color: red;
  }
  </style>
</head>
<body>
  <div>
    <span>These tests demonstrate descendant selectors, nesting and load order problems.</span>

    <div>
      <br/>
      <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
      All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
      <div class='scope1'>
        <button class='myButton'</button>
        <div class='scope2'>
          <button class='myButton'></button>
          <div class='scope3'>
            <button class='myButton'></button>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

Утечки из неограниченных классов

Есть еще одна проблема с селекторами потомков. Обратите внимание, что в предыдущем примере стили высоты и ширины из неограниченного класса myButton применяются ко всем кнопкам. Это означает, что изменение этого стиля может случайно сделать неработоспособным код HTML, в котором используется разметка с ограниченной областью действия.

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

Безопасное использование устаревших стилей Office UI Fabric (после SPFx v1.8.2)

Важно!

Следующие рекомендации относятся к SharePoint Framework >= 1.8.2

Убедитесь в том, что манифест веб-части требует загрузки на страницу устаревших основных стилей Fabric. Это можно сделать, указав loadLegacyFabricCss: true в манифесте решения.

До выпуска SPFx v1.8.2 была обнаружена ошибка страницы узла, когда устаревшие основные стили Fabric загружались без области видимости. Таким образом, если другое решение требовало использование стилей, то все другие решения на странице могли их использовать. Это привело к тому, что решения работали некорректно, если не были отображены изолированно.

Чтобы устранить эту ошибку, стили были ограничены классом .ms-SPLegacyFabricBlock и применены к решениям SPFx, которые требуют загрузки основной таблицы стилей Fabric. Чтобы указать способ переноса для решений, зависящих от вышеуказанного побочного эффекта, класс .ms-SPLegacyFabricBlock применяется ко всем <div>, подверженным решениям сторонних производителей. В течение этого времени необходимо изменить затронутые решения, чтобы объявить зависимость от устаревших стилей ядра Fabric.

Важно!

В конечном итоге явная ссылка на .ms-SPLegacyFabricBlockбудет удалена из модели DOM для решений, которые не объявляют свою зависимость. Об этом изменении будет широко сообщено по существующим каналам до удаления этого класса.

Если решение выполняется в элементах DOM, которые не предоставляются SPFx (который обычно не поддерживается), необходимо применить класс .ms-SPLegacyFabricBlockсамостоятельно.

Использование значков Office UI Fabric в компонентах SPFx

Начиная с SharePoint Framework v1.8.2 внесены изменения в способ применения значков Office UI Fabric при отображении решений SharePoint Framework.

Устаревший способ применения значков (до версии SPFx 1.8.2)

<i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>

Обновленный способ применения значков (после версии SPFx 1.8.2)

Решения, созданные без варианта использования платформы JavaScript.

Добавьте пакет @uifabric/styling в свой файл package.json
Измените код аналогично примеру ниже, чтобы получить нужный значок в своем коде:

import { getIconClassName } from '@uifabric/styling';

return `<i class="${getIconClassName('Mail')}" />`;

Решения, созданные с вариантом использования React или с помощью React в целом.

Добавьте пакет office-ui-fabric-react в свой файл package.json, если он еще не добавлен.
Измените код аналогично примеру ниже, чтобы получить нужный значок в своем коде:

import { Icon } from 'office-ui-fabric-react/lib/Icon';

<Icon iconName='Mail' />

См. также

Обзор SharePoint Framework

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