Посмотреть на GitHub Оригинал

Выпадающие списки

Переключайте контекстные наложения для отображения списков ссылок и многого другого с помощью плагина раскрывающегося списка Bootstrap.

Обзор

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

Выпадающие списки созданы на основе сторонней библиотеки Popper, которая обеспечивает динамическое позиционирование и обнаружение области просмотра. Обязательно включите popper.min.js перед загрузочным JavaScript или используйте bootstrap.bundle.min.js / bootstrap.bundle.js, который содержит Popper . Popper не используется для размещения раскрывающихся списков на навигационных панелях, хотя динамическое позиционирование не требуется.

Если Вы создаете наш JavaScript из исходного кода, он требуется util.js.

Доступность

WAI ARIA стандарт определяет фактический виджет role="menu", но это относится к меню, похожему на приложение, которое запускает действия или функции. Меню ARIA могут содержать только элементы меню, элементы меню с флажками, элементы меню с переключателями, группы переключателей и подменю.

С другой стороны, выпадающие списки Bootstrap разработаны как общие и применимы к различным ситуациям и структурам разметки. Например, можно создавать раскрывающиеся списки, содержащие дополнительные входные данные и элементы управления формой, такие как поля поиска или формы входа. По этой причине Bootstrap не ожидает (и не добавляет автоматически) какие-либо атрибуты role и aria-, необходимые для истинных ARIA. Авторы должны сами включить эти более конкретные атрибуты.

Однако Bootstrap добавляет встроенную поддержку для большинства стандартных взаимодействий с меню клавиатуры, таких как возможность перемещаться по отдельным элементам .dropdown-item с помощью клавиш курсора и закрывать меню с помощью клавиши ESC.

Примеры

Оберните переключатель раскрывающегося списка (Вашу кнопку или ссылку) и раскрывающееся меню внутри .dropdown, или другого элемента, объявляющего position: relative;. Выпадающие списки можно запускать из элементов <a> или <button>, чтобы лучше соответствовать вашим потенциальным потребностям.

Одна кнопка

Любой отдельный .btn можно превратить в раскрывающийся список с некоторыми изменениями разметки. Вот как Вы можете заставить их работать с любым элементом <button>:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Кнопка выпадающего списка
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Действие</a>
    <a class="dropdown-item" href="#">Другое действие</a>
    <a class="dropdown-item" href="#">Что-то еще здесь</a>
  </div>
</div>

И с элементами <a>:

<div class="dropdown">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-expanded="false">
    Ссылка выпадающего списка
  </a>

  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Действие</a>
    <a class="dropdown-item" href="#">Другое действие</a>
    <a class="dropdown-item" href="#">Что-то еще здесь</a>
  </div>
</div>

Самое приятное то, что Вы можете сделать это и с любым вариантом кнопки:

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Действие
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Действие</a>
    <a class="dropdown-item" href="#">Другое действие</a>
    <a class="dropdown-item" href="#">Что-то еще здесь</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Отдельная ссылка</a>
  </div>
</div>

Раздельная кнопка

Точно так же создайте раскрывающиеся списки с разделенными кнопками с практически такой же разметкой, что и раскрывающиеся списки с одной кнопкой, но с добавлением .dropdown-toggle-split для правильного интервала вокруг курсора раскрывающегося списка.

Мы используем этот дополнительный класс, чтобы уменьшить горизонтальный padding по обе стороны от курсора на 25% и удалить margin-left, который добавляется для обычных раскрывающихся списков кнопок. Эти дополнительные изменения удерживают курсор в центре разделенной кнопки и обеспечивают область нажатия более подходящего размера рядом с основной кнопкой.

<!-- Пример раздельной кнопки Опасность -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Действие</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Переключатель выпадающего списка</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Действие</a>
    <a class="dropdown-item" href="#">Другое действие</a>
    <a class="dropdown-item" href="#">Что-то еще здесь</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Отдельная ссылка</a>
  </div>
</div>

Размеры

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

<!-- Группы больших кнопок (по умолчанию и разделенные) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Большая кнопка
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    Большая раздельная кнопка
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Переключатель выпадающего списка</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

<!-- Небольшие группы кнопок (по умолчанию и разделенные) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Маленькая кнопка
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    Маленькая раздельная кнопка
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Переключатель выпадающего списка</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

Направления

Выпадающий вверх

Вызвать раскрывающееся меню над элементами, добавив к родительскому элементу .dropup.

<!-- Кнопка выпадающего меню по умолчанию -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Выпадающий вверх
  </button>
  <div class="dropdown-menu">
    <!-- Ссылки раскрывающегося меню -->
  </div>
</div>

<!-- Раздельная кнопка выпадающая вверх -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    Раздельный выпад вверх
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Переключатель выпадающего списка</span>
  </button>
  <div class="dropdown-menu">
    <!-- Ссылки раскрывающегося меню -->
  </div>
</div>

Выпад вправо

Откройте раскрывающееся меню справа от элементов, добавив .dropright к родительскому элементу.

<!-- Кнопка выпадающего вправо по умолчанию -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Выпадающий вправо
  </button>
  <div class="dropdown-menu">
    <!-- Ссылки раскрывающегося меню -->
  </div>
</div>

<!-- Раздельная кнопка выпадающего вправо по умолчанию -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    Раздельный выпадающий вправо
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Переключатель выпада вправо</span>
  </button>
  <div class="dropdown-menu">
    <!-- Ссылки раскрывающегося меню -->
  </div>
</div>

Выпадающий влево

Активируйте раскрывающиеся меню слева от элементов, добавив .dropleft к родительскому элементу.

<!-- Кнопка выпадающая влево по умолчанию -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Выпадающий влево
  </button>
  <div class="dropdown-menu">
    <!-- Ссылки раскрывающегося меню -->
  </div>
</div>

<!-- Раздельная кнопка выпадающая влево -->
<div class="btn-group">
  <div class="btn-group dropleft">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
      <span class="sr-only">Переключатель выпадающего влево</span>
    </button>
    <div class="dropdown-menu">
      <!-- Ссылки раскрывающегося меню -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    Раздельный выпадающий влево
  </button>
</div>

Пункты меню

Исторически содержимое выпадающего меню должно было быть ссылками, но в версии 4 это уже не так. Теперь Вы можете при желании использовать элементы <button> в раскрывающихся списках вместо просто <a>.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Выпадающий вниз
  </button>
  <div class="dropdown-menu">
    <button class="dropdown-item" type="button">Действие</button>
    <button class="dropdown-item" type="button">Другое действие</button>
    <button class="dropdown-item" type="button">Что-то еще здесь</button>
  </div>
</div>

Вы также можете создавать неинтерактивные выпадающие элементы с помощью .dropdown-item-text. Не стесняйтесь изменять стиль с помощью пользовательских CSS или текстовых утилит.

<div class="dropdown-menu">
  <span class="dropdown-item-text">Текст выпадающего списка</span>
  <a class="dropdown-item" href="#">Действие</a>
  <a class="dropdown-item" href="#">Другое действие</a>
  <a class="dropdown-item" href="#">Что-то еще здесь</a>
</div>

Активный

Добавьте .active к элементам в раскрывающемся списке, чтобы сделать их активными.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Обычная ссылка</a>
  <a class="dropdown-item active" href="#">Активная ссылка</a>
  <a class="dropdown-item" href="#">Другая ссылка</a>
</div>

Отключенный

Добавьте .disabled к элементам в раскрывающемся списке, чтобы сделать их отключенными.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Обычная ссылка</a>
  <a class="dropdown-item disabled">Отключенная ссылка</a>
  <a class="dropdown-item" href="#">Другая ссылка</a>
</div>

Выравнивание меню

По умолчанию раскрывающееся меню автоматически располагается на 100% сверху и слева от своего родителя. Добавьте .dropdown-menu-right в .dropdown-menu, чтобы выровнять раскрывающееся меню по правому краю.

Внимание! Выпадающие списки располагаются благодаря Popper (кроме случаев, когда они содержатся в панели навигации).

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Меню с выравниванием по правому краю
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">Действие</button>
    <button class="dropdown-item" type="button">Другое действие</button>
    <button class="dropdown-item" type="button">Что-то еще здесь</button>
  </div>
</div>

Адаптивное выравнивание

Если Вы хотите использовать адаптивное выравнивание, отключите динамическое позиционирование, добавив атрибут data-display="static" и используйте гибкие классы вариантов.

Чтобы выровнять вправо раскрывающееся меню с заданной контрольной точкой или больше, добавьте .dropdown-menu{-sm|-md|-lg|-xl}-right.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-expanded="false">
    По левому краю, но по правому краю на большом экране
  </button>
  <div class="dropdown-menu dropdown-menu-lg-right">
    <button class="dropdown-item" type="button">Действие</button>
    <button class="dropdown-item" type="button">Другое действие</button>
    <button class="dropdown-item" type="button">Что-то еще здесь</button>
  </div>
</div>

Чтобы выровнять слева раскрывающееся меню с заданной контрольной точкой или больше, добавьте .dropdown-menu-right и .dropdown-menu{-sm|-md|-lg|-xl}-left.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-expanded="false">
    По правому краю, но по левому краю на большом экране
  </button>
  <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
    <button class="dropdown-item" type="button">Действие</button>
    <button class="dropdown-item" type="button">Другое действие</button>
    <button class="dropdown-item" type="button">Что-то еще здесь</button>
  </div>
</div>

Обратите внимание, что Вам не нужно добавлять атрибут data-display="static" к кнопкам раскрывающегося списка на панели навигации, поскольку Popper не используется в панелях навигации.

Содержание меню

Заголовки

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

<div class="dropdown-menu">
  <h6 class="dropdown-header">Заголовок раскрывающегося списка</h6>
  <a class="dropdown-item" href="#">Действие</a>
  <a class="dropdown-item" href="#">Другое действие</a>
</div>

Разделители

Разделите группы связанных пунктов меню разделителем.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Действие</a>
  <a class="dropdown-item" href="#">Другое действие</a>
  <a class="dropdown-item" href="#">Что-то еще здесь</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Отдельная ссылка</a>
</div>

Текст

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

<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
  <p>
    Пример текста, который свободно перемещается в раскрывающемся меню.
  </p>
  <p class="mb-0">
    И это еще один пример текста.
  </p>
</div>

Формы

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

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">Адрес электронной почты</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Пароль</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Пароль">
    </div>
    <div class="form-group">
      <div class="form-check">
        <input type="checkbox" class="form-check-input" id="dropdownCheck">
        <label class="form-check-label" for="dropdownCheck">
          Запомните меня
        </label>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Войти в систему</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Новенький здесь? Зарегистрироваться</a>
  <a class="dropdown-item" href="#">Забыли пароль?</a>
</div>

<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">Адрес электронной почты</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Пароль</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Пароль">
  </div>
  <div class="form-group">
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck2">
      <label class="form-check-label" for="dropdownCheck2">
        Запомните меня
      </label>
    </div>
  </div>
  <button type="submit" class="btn btn-primary">Войти в систему</button>
</form>

Параметры раскрывающегося списка

Используйте data-offset или data-reference, чтобы изменить расположение раскрывающегося списка.

<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false" data-offset="10,20">
      Смещение
    </button>
    <div class="dropdown-menu">
      <a class="dropdown-item" href="#">Действие</a>
      <a class="dropdown-item" href="#">Другое действие</a>
      <a class="dropdown-item" href="#">Что-то еще здесь</a>
    </div>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-secondary">Справка</button>
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false" data-reference="parent">
      <span class="sr-only">Переключатель выпадающего списка</span>
    </button>
    <div class="dropdown-menu">
      <a class="dropdown-item" href="#">Действие</a>
      <a class="dropdown-item" href="#">Другое действие</a>
      <a class="dropdown-item" href="#">Что-то еще здесь</a>
      <div class="dropdown-divider"></div>
      <a class="dropdown-item" href="#">Отдельная ссылка</a>
    </div>
  </div>
</div>

Применение

С помощью атрибутов данных или JavaScript плагин раскрывающегося списка переключает скрытый контент (раскрывающиеся меню), переключая класс .show в родительском .dropdown-menu. Атрибут data-toggle="dropdown" используется для закрытия раскрывающихся меню на уровне приложения, поэтому рекомендуется всегда использовать его.

На устройствах с сенсорным экраном открытие раскрывающегося списка добавляет пустые ($.noop) обработчики mouseover к непосредственным дочерним элементам элемента <body>. Этот, по общему признанию, уродливый взлом необходим, чтобы обойти причуду в делегировании событий iOS, которая в противном случае предотвратила бы нажатие где-нибудь за пределами раскрывающегося списка от запуска кода, закрывающего раскрывающийся список. После закрытия раскрывающегося списка эти дополнительные пустые обработчики mouseover указателя мыши удаляются.

Через атрибуты данных

Добавьте data-toggle="dropdown" к ссылке или кнопке, чтобы переключить раскрывающийся список.

<div class="dropdown">
  <button type="button" data-toggle="dropdown" aria-expanded="false">
    Триггер выпадающего списка
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

Через JavaScript

Вызов выпадающих списков через JavaScript:

$('.dropdown-toggle').dropdown()

`data-toggle="dropdown"` все еще требуется

Независимо от того, вызываете ли Вы раскрывающийся список через JavaScript или вместо этого используете data-api, в элементе триггера раскрывающегося списка всегда должен присутствовать data-toggle="dropdown".

Параметры

Параметры могут передаваться через атрибуты данных или JavaScript. Для атрибутов данных добавьте имя параметра к data-, как в data-offset="".

Имя	Тип	По умолчанию	Описание
offset	number \| string \| function	0	Смещение раскрывающегося списка относительно его цели. Когда функция используется для определения смещения, она вызывается с объектом, содержащим данные смещения в качестве первого аргумента. Функция должна возвращать объект с такой же структурой. Узел DOM запускающего элемента передается как второй аргумент. Дополнительную информацию смотрите в документации Popper по смещению.
flip	boolean	true	Разрешить раскрывающемуся списку переворачиваться в случае перекрытия ссылочного элемента. Для получения дополнительной информации смотрите документации переворотов Popper.
boundary	string \| element	'scrollParent'	Граница ограничения переполнения раскрывающегося меню. Принимает значения `'viewport'`, `'window'`, `'scrollParent'` или ссылку HTMLElement (только JavaScript). Дополнительную информацию смотрите в документации preventOverflow Popper.
reference	string \| element	'toggle'	Справочный элемент раскрывающегося меню. Принимает значения `'toggle'`, `'parent'` или ссылка HTMLElement. Дополнительную информацию смотрите документацию referenceObject Popper.
display	string	'dynamic'	По умолчанию мы используем Popper для динамического позиционирования. Отключите это с помощью `static`.
popperConfig	null \| object	null	Чтобы изменить конфигурацию Popper по умолчанию в Bootstrap, смотрите конфигурацию Popper.

Обратите внимание, что если параметр boundary имеет любое значение, отличное от 'scrollParent', к контейнеру .dropdown применяется стиль position: static.

Методы

Метод	Описание
`$().dropdown('toggle')`	Переключает раскрывающееся меню данной панели навигации или навигации с вкладками.
`$().dropdown('show')`	Показывает раскрывающееся меню данной панели навигации или навигации с вкладками.
`$().dropdown('hide')`	Скрывает раскрывающееся меню данной панели навигации или навигации с вкладками.
`$().dropdown('update')`	Обновляет позицию раскрывающегося списка элемента.
`$().dropdown('dispose')`	Уничтожает раскрывающийся список элемента.

События

Все выпадающие события запускаются в родительском элементе .dropdown-menu и имеют свойство relatedTarget, значением которого является переключаемый элемент привязки. События hide.bs.dropdown и hidden.bs.dropdown имеют свойство clickEvent (только если исходный тип события click), который содержит объект события для события щелчка.

События	Описание
`show.bs.dropdown`	Это событие срабатывает немедленно, когда вызывается метод экземпляра шоу.
`shown.bs.dropdown`	Это событие запускается, когда раскрывающийся список становится видимым для пользователя (будет ожидать завершения переходов CSS).
`hide.bs.dropdown`	Это событие запускается сразу после вызова метода экземпляра hide.
`hidden.bs.dropdown`	Это событие запускается, когда раскрывающийся список перестает быть скрытым от пользователя (будет ожидать завершения переходов CSS).

$('#myDropdown').on('show.bs.dropdown', function () {
  // сделайте что-нибудь...
})