Рекомендации по работе с CSS в решениях SharePoint Framework

2023-04-08

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

Настройки SharePoint Framework являются частью страницы

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

Решения SharePoint Framework являются частью страницы и полностью интегрируются с моделью DOM этой страницы. Хотя это снимает ряд ограничений, связанных с моделью надстройки, ваше решение подвергается риску. Если эта часть страницы не будет явно изолирована, к ней будут применяться все стили CSS, которые есть на странице, что может привести к нежелательным результатам. Чтобы избежать таких рисков, нужно определить стили CSS так, чтобы они не влияли ни на что другое на странице, кроме вашей настройки.

Организация файлов CSS в решении

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

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

todoWebPart\components
                      \todoList
                               \todoList.tsx
                               \todoList.module.scss
                      \todoItem
                               \todoItem.tsx
                               \todoItem.module.scss

Использование SASS

В SharePoint Framework можно использовать как CSS, так и SASS. SASS — это расширенная версия CSS, которая поддерживает переменные, вложение селекторов и примеси — все это упрощает работу со стилями CSS и управление ими в долгосрочной перспективе.

Полный набор функций см. на веб-сайте Sass. Синтаксис CSS полностью совместим с синтаксисом SASS, что очень полезно, если вы еще не работали с SASS раньше и хотите постепенно изучить его возможности.

Не используйте идентификаторы в разметке

Используя SharePoint Framework, вы создаете настройки, которые пользователи добавляют в SharePoint. Невозможно предугадать, сколько экземпляров конкретной настройки будет открыто на странице.

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

Не рекомендуется

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="helloWorld">
        Hello world
      </div>`;
  }

  // ...
}

Использование CSS-модулей для избежания конфликтов стилей

SharePoint Framework решения являются частью страницы. Чтобы стили CSS для одного компонента не влияли на другие элементы на странице, следует определить селекторы CSS таким образом, чтобы они применялись только к модели DOM решения. Это мученно и подвержено ошибкам, но SharePoint Framework может сделать это автоматически за вас.

Чтобы избежать конфликтов стилей, SharePoint Framework использует модули CSS. При сборке проекта цепочка инструментов SharePoint Framework обрабатывает все файлы с расширением .module.scss. Для каждого файла SharePoint Framework считывает все селекторы классов и добавляет к ним уникальное хэш-значение. После этого он записывает обновленные селекторы в промежуточные файлы CSS, которые включаются в пакет веб-части.

В продолжение предыдущего примера, предположим, что у вас было два следующих файла SASS:

todoList.module.scss

.todoList {
  margin: 1em 0;

  .text {
    font-weight: bold;
    font-size: 1.5em;
  }
}

todoItem.module.scss

.todoItem {
  padding: 0.5em 1em;

  .text {
    font-size: 0.9em;
  }
}

После создания проекта в папке lib появится два созданных файла CSS, представленных ниже (разрывы строк и отступы добавлены для лучшей читаемости):

todoList.module.css

.todoList_3e9d35f0 {
  margin:1em 0
}

.todoList_3e9d35f0 .text_3e9d35f0 {
  font-weight:700;
  font-size:1.5em
}

todoItem.module.css

.todoItem_f7081cc4 {
  padding:.5em 1em
}

.todoItem_f7081cc4 .text_f7081cc4 {
  font-size:.9em
}

Несмотря на то что в обоих файлах SASS был определен класс .text, в созданных файлах CSS к нему добавлены к нему два разных хэша, что делает его уникальным именем класса, характерным для каждого компонента.

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

todoList.module.scss.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable */
require('./todoList.module.css');
var styles = {
    todoList: 'todoList_3e9d35f0',
    text: 'text_3e9d35f0',
};
exports.default = styles;
/* tslint:enable */

//# sourceMappingURL=todoList.module.scss.js.map

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

import styles from './todoList.module.scss';
// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        <div className={styles.text}>Hello world</div>
      </div>
    );
  }
}

Для правильной работы модулей CSS должны выполняться следующие условия:

Файлы SASS должны иметь расширение .module.scss. Если используется расширение .scss без .module, в ходе сборки отобразится предупреждение. Файл SASS будет транспилирован в промежуточный файл CSS, но имена классов не будут уникальными. Расширение .module может не использоваться преднамеренно, когда необходимо переопределить сторонние стили CSS.
Имена классов CSS должны быть действительными именами переменных JavaScript. Например, они не могут содержать дефисы: todoList — правильно, а todo-list — неправильно.
Рекомендуем указывать имена классов в верблюжьем регистре, но это не обязательно.

Упаковка стилей CSS в класс, названный именем компонента

Объединив модули CSS с поддержкой вложения наборов правил SASS, можно упростить стили CSS и убедиться, что они не повлияют на другие элементы на странице.

Упакуйте стили CSS в класс, названный именем компонента, для которого они созданы. Затем назначьте этот класс корневому элементу компонента.

todoList.module.scss

.todoList {
  a {
    display: block;
  }
}

TodoList.tsx

// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        ...
      </div>
    );
  }
}

После транспиляции файл CSS будет выглядеть примерно так:

.todoList_3e9d35f0 a {
  display: block;
}

Так как селектор начинается с уникального имени класса, используемого для компонента, альтернативное представление применяется только к гиперссылкам внутри компонента.

Обработка префикса поставщика CSS

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

Если веб-часть должна использовать новую модель адаптируемого блока (определяется объявлением display: flex), в некоторых старых браузерах на основе WebKit и Internet Explorer требуется определенный префикс поставщика в CSS.

.container{
  display: flex;
}

В код SASS артефакта SharePoint не требуется включать префиксы поставщиков. Они автоматически добавляются после компиляции SASS в CSS. В итоге получается приведенное ниже объявление CSS.

.container_7e976ae1 {
  display: -webkit-box; // older Safari on MacOS and iOS
  display: -ms-flexbox; // IE 10 - 11
  display: flex;
}

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

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

В примере ниже используется свойство border-radius, для которого не требуются префиксы поставщиков в поддерживаемых системах.

.container {
  /* Safari 3-4, iOS 1-3.2, Android 1.6- */
  -webkit-border-radius: 7px;
  /* Firefox 1-3.6 */
  -moz-border-radius: 7px;
  /* Opera 10.5, IE 9, Safari 5, Chrome, Firefox 4, iOS 4, Android 2.1+ */
  border-radius: 7px;
}

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

.container_9e54c0b0 {
  border-radius: 7px
}

Дополнительные сведения об автоматическом добавлении префиксов см. в документации из репозитория autoprefixer на сайте GitHub. База данных с описанием этого процесса доступна на сайте Can I use__?.

Интеграция с Office UI Fabric

Если ваши настройки будут выглядеть и работать как стандартные функции SharePoint и Office 365, пользователям будет удобнее с ними работать. В Office UI Fabric вы найдете набор элементов управления и стилей, при использовании которых ваши настройки будут идеально вписываться в существующий интерфейс.

Дополнительные сведения об использовании Office UI Fabric в SharePoint Framework см. в этой статье.

Использование цветов темы

SharePoint позволяет пользователям выбирать цвет темы для своих сайтов. Тема настройки SharePoint Framework должна соответствовать теме, выбранной пользователями, чтобы настройка выглядела как неотъемлемая часть сайта и излишне не выделялась.

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

Дополнительные сведения об этой возможности см. в статье Использование цветов темы в настройках SharePoint Framework.

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

Рекомендации по работе с CSS в решениях SharePoint Framework

Настройки SharePoint Framework являются частью страницы

Организация файлов CSS в решении

Использование SASS

Не используйте идентификаторы в разметке

Не рекомендуется

Рекомендуется

Использование CSS-модулей для избежания конфликтов стилей

todoList.module.scss

todoItem.module.scss

todoList.module.css

todoItem.module.css

todoList.module.scss.js

Упаковка стилей CSS в класс, названный именем компонента

todoList.module.scss

TodoList.tsx

Обработка префикса поставщика CSS

Интеграция с Office UI Fabric

Использование цветов темы

Дополнительные ресурсы