Skip to content

Latest commit

 

History

History
512 lines (367 loc) · 30.9 KB

README.ru.md

File metadata and controls

512 lines (367 loc) · 30.9 KB
Raw

Библиотека BEM Components

bem-components — это библиотека с открытым кодом, которая предоставляет набор готовых визуальных компонентов (блоков). Содержит контролы форм и другие базовые компоненты для построения интерфейсов.

Библиотека предоставляет темы оформления. В данной версии представлена тема islands, реализующая дизайн Яндекса. Предусмотрена одновременная поддержка нескольких тем и возможность создания новых.

GitHub Release Build Status Coverage Status devDependency Status

Содержание

Дополнительная информация

Уровни переопределения

  • common.blocks — поддержка всех устройств и браузеров.
  • desktop.blocks — поддержка всех десктопных браузеров.
  • touch.blocks — реализация специфических особенностей для touch-платформ.
  • touch-phone.blocks — реализация специфических особенностей для смартфонов.
  • touch-pad.blocks — реализация специфических особенностей для планшетов.
  • design/<common|desktop|touch|touch-phone|touch-pad>.blocks — реализация различных дизайнов (тем).

Блоки

Поддерживаемые браузеры

  • Desktop

    • Firefox (две последние стабильные версии)
    • Chrome (две последние стабильные версии)
    • Safari (две последние стабильные версии)
    • Yandex (две последние стабильные версии)
    • Opera 12.6+
    • Internet Explorer 9+
    • Частичная поддержка Internet Explorer 8

  • Touch

    • Android 4+
    • iOS 5+
    • Internet Explorer 10+

Поддержка Internet Explorer 8

Для поддержки Internet Explorer 8 подключите на страницу:

  • es5-shim;
  • файлы стилей с расширением *.ie.styl. Для этого укажите их в сборке (пример) и добавьте условные комментарии в блоке page (пример). Подключить стили для Internet Explorer 8 можно также на уровне шаблонов.

Технологии

Инструменты

Сборщики

Оптимизаторы

Проверка кода

Прочее

  • Autoprefixer — применяется во время сборки для генерации вендорных префиксов для поддерживаемых браузеров на основании конфигурации.

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

Существует несколько способов начать работу с bem-components. Выбор подходящего способа использования зависит от требований проекта и его совместимости с технологиями и инструментами библиотеки, а также от вашего опыта работы с БЭМ-проектами.

Выберите способ поставки, наиболее подходящий вашему проекту:

Dist Source Compiled
Предсобранный CSS- и JavaScript-код и шаблоны библиотеки. Подключается ссылками на страницу. Не требует сборки и совместимости с вашим проектом. Полный исходный код библиотеки. Для использования необходима предварительная сборка. Требует полной совместимости проекта с технологиями и инструментами библиотеки. Полный исходный код библиотеки. Для использования необходима предварительная сборка. Отличается от способа «Source» тем, что PostCSS скомпилирован в CSS. Подходит для проектов, не использующих PostCSS.

Способ использования библиотеки определяет порядок ее подключения в проект:

Подключение исходного кода библиотеки (Source и Compiled)

Рекомендуемый способ подключения — использование инструментов ENB или bem-tools.

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

Подключение предсобранных файлов библиотеки (Dist)

Самый простой способ подключить библиотеку в проект — скачать предварительно собранные файлы библиотеки и добавить их в HTML страницы с помощью элементов <link> и <script>. Сделать это можно разными способами:

О том, как работать с подключенными файлами библиотеки, читайте в разделе Работа с библиотекой.

Состав предсобранной библиотеки

Доступны отдельные наборы файлов для трех платформ:

  • desktop
  • touch-pad
  • touch-phone

Каждый набор включает в себя:

  • bem-components.css — стили

  • bem-components.ie.css — стили для IE8 (подробнее)

  • bem-components.js — JavaScript

  • bem-components.bemhtml.js — BEMHTML-шаблоны

  • bem-components.bh.js — BH-шаблоны

  • bem-components.js+bemhtml.js — объединение JavaScript-кода и BEMHTML-шаблонов для использования шаблонов в браузере

  • bem-components.js+bh.js — объединение JavaScript-кода и BH-шаблонов для использования шаблонов в браузере

  • bem-components.no-autoinit.js - JavaScript без автоматической инициализации. Следует использовать при необходимости писать собственный код на i-bem.js

  • bem-components.no-autoinit.js+bemhtml.js

  • bem-components.no-autoinit.js+bh.js

В каждый набор также включены аналогичные dev-версии (с сохранением форматирования и комментариев).

Подключение файлов с CDN

Самый быстрый и простой способ подключить библиотеку в проект — добавить элементы <link> и <script> в HTML страницы:

<link rel="stylesheet" href="https://yastatic.net/bem-components/latest/desktop/bem-components.css">
<script src="https://yastatic.net/bem-components/latest/desktop/bem-components.js+bemhtml.js"></script>

Схема подключения файла с CDN: //yastatic.net/название-библиотеки/версия/платформа/имя-файла.

Пример: //yastatic.net/bem-components/latest/desktop/bem-components.dev.js+bemhtml.js.

Загрузка в виде архива

Выберите необходимую версию библиотеки и скачайте архив. Распакуйте. Добавьте файлы на страницу с помощью элементов <link> и <script>:

<link rel="stylesheet" href="desktop/bem-components.css">
<script src="desktop/bem-components.js+bemhtml.js"></script>

Сбор файлов из исходного кода

Код библиотеки находится на Github: https://github.com/bem/bem-components.

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

# Клонируйте исходный код библиотеки
git clone https://github.com/bem/bem-components.git
# Перейдите в папку библиотеки
cd bem-components
# Установите необходимые зависимости
npm install
# Соберите Dist
npm run dist

В результате сборки файлы будут доступны в папке bem-components-dist. Подключите файлы в HTML страницы:

<link rel="stylesheet" href="bower_components/bem-components-dist/desktop/bem-components.css">
<script src="bower_components/bem-components-dist/desktop/bem-components.js+bemhtml.js"></script>

Установка с помощью Bower

При условии, что Bower уже установлен в ваш проект, выполните следующую команду:

bower i bem/bem-components-dist

В результате сборки файлы будут доступны в папке bem-components-dist. Подключение не отличается от предыдущего способа:

<link rel="stylesheet" href="bower_components/bem-components-dist/desktop/bem-components.css">
<script src="bower_components/bem-components-dist/desktop/bem-components.js+bemhtml.js"></script>

Работа с библиотекой в виде Dist

Работу с библиотекой можно разбить на два шага:

  1. Найти нужный блок на сайте библиотеки: bem.info. Например, select.
  2. Получить необходимый HTML.

Первый шаг всегда одинаковый. Второй — выполняется тремя разными способами, которые можно произвольно комбинировать:

Способ I. Скопировать нужный HTML из примера. Для этого перейдите во вкладку HTML в шапке примера.

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

Способ II. Использовать шаблонизацию в браузере. Сборка библиотеки Dist включает предсобранные шаблоны BEMHTML и BH на выбор.

Для этого скопируйте из документации BEMJSON-код примера и вставьте его в HTML страницы. Используйте вкладку BEMJSON в шапке примера.

HTML страницы будет выглядеть следующим образом:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>bem-components as a library</title>
    <link rel="stylesheet" href="https://yastatic.net/bem-components/latest/desktop/bem-components.css">
</head>
<body class="page page_theme_islands">
    <form class="form" action="/"></form>
<script src="https://yastatic.net/bem-components/latest/desktop/bem-components.no-autoinit.js+bemhtml.js"></script>
<script>
modules.require(['i-bem__dom', 'BEMHTML', 'jquery'], function(BEMDOM, BEMHTML, $) {
    var html = BEMHTML.apply({
        block : 'select',
        mods : { mode : 'check', theme : 'islands', size : 'm' },
        name : 'select1',
        val : [2, 3],
        text : 'Программа конференции',
        options : [
            { val : 1, text : 'Доклад' },
            { val : 2, text : 'Мастер-класс' },
            { val : 3, text : 'Круглый стол' }
        ]
    });

    BEMDOM.append($('.form'), html);    // https://ru.bem.info/libs/bem-core/current/desktop/i-bem/jsdoc/#append-1
});
</script>
</body>
</html>

Такой код не потребует изменений в разметке при обновлении библиотеки до новой версии в отличие от способа I. Однако генерируемая на клиенте разметка может хуже индексироваться поисковыми системами.

Способ III. Выполнять {BEMHTML,BH}.apply() в Node.js и отдавать браузеру уже готовый HTML:

var BEMHTML = require('./dist/desktop/bem-components.bemhtml.js').BEMHTML;

BEMHTML.apply({
    block : 'select',
    mods : { mode : 'check', theme : 'islands', size : 'm' },
    name : 'select1',
    val : [2, 3],
    text : 'Программа конференции',
    options : [
        { val : 1, text : 'Доклад' },
        { val : 2, text : 'Мастер-класс' },
        { val : 3, text : 'Круглый стол' }
    ]
}); // возвращает HTML-строку

Понимание принципов библиотеки

Блок и его состояния

Библиотека состоит из блоков, визуальное представление которых можно увидеть на витрине bem-components. У блоков есть состояния, которые определяют его поведенческую модель. Состояние блока выражается через модификаторы и специализированные поля. Изменение модификатора создает событие, которое можно использовать для работы с блоком.

Нет необходимости создавать специальное дополнительное БЭМ-событие, если есть возможность работать с событием на изменение модификатора. В зависимости от того, с помощью чего изменяется состояние компонента (модификатор или поле), используются разные события:

  • Для реакции на изменения «состояния» полей value применяется событие change.
  • Для реакции на установку/снятие модификатора применяются различные события на изменение модификатора.

Контролы в bem-components

Контролы в bem-components могут использоваться как базовая часть для создания других компонетов библиотек. Такие контролы не имеют моделей, как в HTML, и могут использоваться для решения задач, в которых не нужна семантика конкретной HTML-модели.

В качестве примера рассмотрим «поведенческую модель» HTMLInputElement, которая представляет собой высокоуровневый интерфейс, специально созданый для редактирования данных. Блоки в bem-components отличаются тем, что могут использоваться как базовая часть блока другой библиотеки, который будет решать эту же задачу. Но, помимо этого, они могут решать и другие интерфейсные задачи, в которых не нужна семантика HTML input.

Особенности реализации

Модификатор focused

Контролы в bem-components имеют два типа фокуса, которые выставляются с помощью модификаторов focused и focused-hard. Тип фокуса определяет внешний вид контрола.

Выбор модификатора происходит автоматически в зависимости от способа установки фокуса:

  • focused — выставляется при клике на контрол курсором мыши.
  • focused-hard — выставляется при переходе на контрол с помощью клавиатуры или через JavaScript. Создан для более явного визуального выделения компонента при получении фокуса. Например, в теме islands большинство контролов получают дополнительную рамку при установке модификатора focused-hard.

Разработка

Рабочая копия

Получение исходников:

$ git clone git://github.com/bem/bem-components.git
$ cd bem-components

Установка зависимостей (инструментов):

$ npm install

Для последующего запуска локально установленных инструментов потребуется export PATH=./node_modules/.bin:$PATH или любой альтернативный способ.

Установка зависимых библиотек:

$ bower install

Сборка примеров и тестов:

$ npm run build-all

Запуск сервера для разработки:

$ npm start
$ open http://localhost:8080/

NB Точечная сборка отдельных блоков описана в разделе Тесты на шаблоны.

Проверка кода:

$ npm run lint

Тестирование

Юнит-тесты на JavaScript

Команда npm run test-specs запускает юнит-тесты на JS.

Для запуска точечной сборки используйте команду enb make specs desktop.specs/<block-name> (например, enb make specs desktop.specs/input).

Тесты запускаются автоматически на Travis для каждого pull request'а.

Регрессионное тестирование верстки

Для тестирования верстки используется Gemini.

Тесты каждого блока находятся в отдельном файле вида block-name.gemini.js в директории gemini/. Локально тесты запускаются вручную. Тесты на Travis запускаются автоматически. В качестве Selenium Grid используется сервис SauceLabs.

Для запуска тестов локально необходимо:

  1. Создайте учетную запись OpenSauce в SauceLabs.
  2. Установите утилиту Sauce Connect.
  3. Настройте окружение (переменные среды SAUCE_USERNAME и SAUCE_ACCESS_KEY).
  4. Запустите утилиту sc (SauceConnect) и дождаться установки туннеля.
  5. Запустите тесты командой npm run gemini.
  6. Соберите новые версии скриншотов при необходимости командой npm run gemini-gather.

При разработке новых тестов для ускорения локального запуска:

  1. Установите и запустите Selenium Server или PhantomJS.
  2. Исправьте в файле .gemini.yml опцию gridUrl на http://localhost:4444/.
  3. Запустите тесты.

Подробно про использование Gemini с разными бекендами читайте в статье Введение в работу с Gemini.

NB В репозиторий необходимо сохранять скриншоты, собранные в SauceLabs. Это позволит избежать отличий в отрисовке шрифтов.

Перед коммитом новых или измененных эталонных изображений необходимо:

  1. Проверить корректность изображения. Для определения разницы между старой и новой версиями, используйте утилиту Araxis Merge или аналогичную.
  2. Сжать изображения с помощью ImageOptim (самый эффективный инструмент сжатия изображений на май 2014 года).

Тесты на шаблоны

Инструменты сборки библиотеки позволяют собирать и запускать тесты на BEMHTML- и BH-шаблоны блоков.

Добавление теста для блока

  • Создать каталог с названием [имя блока].tmpl-specs в директории блока на требуемом уровне переопределения. В данном каталоге будут храниться файлы тестов.
  • Для каждого теста создать пару файлов: BEMJSON и HTML. В BEMJSON-файле находится пример для блока, в HTML-файле – эталонный HTML-код, который должен получиться после применения шаблона блока к BEMJSON-у примера. Имена файлов (не включая расширения) для одного теста должны совпадать. Например, 10-default.bemjson.js и 10-default.html.

К блоку могут быть написаны несколько тестов и, соответственно, каждый тест будет состоять из пары файлов BEMJSON + HTML с одинаковыми именами.

desktop.blocks
    └── myblocks
        ├── myblock.bemhtml.js
        ├── myblock.bh.js
        ├── ...
        └── myblock.tmpl-specs
            ├── 10-default.bemjson.js
            ├── 10-default.html
            ├── 20-advanced.bemjson.js
            └── 20-advanced.html

Команда для сборки и запуска тестов:

magic run tmpl-specs

Сборка тестов на нужном уровне переопределения:

magic make desktop.tmpl-specs

Сборка тестов только для одного блока (точечная сборка):

magic make desktop.tmpl-specs/button

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

Все тесты автоматически запускаются на Travis для каждого pull request'a.

Команда основной разработки

Рабочий процесс

Список текущих задач отображается на специальном Agile Board.

Статусы задач:

  • backlog — неразобранные задачи, которые требуют обсуждения командой для оценки и принятия решения о реализации. В таком статусе также могут находиться задачи, по которым нужна дополнительная информация.
  • ready — разобранные задачи, решение о реализации которых принято.
  • in progress — задачи с конкретным исполнителем, которые находятся в работе.
  • done — задачи, закрытые за последние семь дней (это временное техническое ограничение выбранного Agile Board).

Лицензия

© 2012 YANDEX LLC. Код лицензирован Mozilla Public License 2.0.