菜单

下拉菜单
下拉菜单允许用户从一系列选项中选择某个值

下载

类型

下拉菜单 (Dropdown)

下拉菜单

指示 (Pointing)

下拉菜单可以格式化为菜单指向

指向底部的下拉菜单向上开启的子菜单

浮动 (Floating)

下拉菜单可以浮动在一个元素下面。

保存

简单下拉 (Simple)

简单的下拉菜单可以不适用javascript

内容

状态

激活 (Active)

激活的下拉菜单是打开状态

激活状态将只会自动打开 ui simple Dropdown。打开正常的下拉菜单请使用 $('.ui.dropdown').dropdown('show');

禁用 (Disabled)

禁用的下拉菜单不能被打开或关闭

变形

选择下拉菜单

最大的选择 (Maximum Selections)

使用 maxSelections 能强制使用最大选择数。你也可以使用 form validation 来设置最大选择和最小选择。

选择
搜索选择
不使用标签
$('.max.example .ui.normal.dropdown') .dropdown({ maxSelections: 3 }) ; $('.max.example .ui.special.dropdown') .dropdown({ useLabels: false, maxSelections: 3 }) ;

标记和用户添加 (Tagging and User Additions)

使用 allowAdditions: true 可以让用户添加自己的选项。单选框和多选框都适合。

虽然所有下拉菜单都支持 select 初始化,自定义选择 不会在页面刷新时保存 除非你使用隐藏的输入框。这是因为 option 动态创建不保存在页面刷新。
单选
多选
$('.tag.example .ui.dropdown') .dropdown({ allowAdditions: true }) ;

移除内容 (Remote Content)

搜索选择下拉列表可以指定检索值的远程API设置,这可以使用一个命名API行为URL

利用API可以让用户从大型数据集中进行选择,这个大型数据集可能由于太大而不能直接在页面加载。

如果你的后端设计无法返回正确的标记,你可以使用API的 onResponse 回调函数在接收到服务器数据后进行调整。

对于相同的API端点的请求会自动在本地缓存,以避免服务器切换。你可以通过调整缓存API设置来禁用此操作。

当用户刷新页面,选择标签会自动重新使用sessionStorage存储相应的名称选择的值。你也可以设置 saveRemoteData: false 来禁用。
$('.remote.example .ui.dropdown') .dropdown({ apiSettings: { url: '//api.semantic-ui.com/tags/{query}' } }) ;
// Expected server response { "success": true, "results": [ { // name displayed in dropdown "name" : "Choice 1", // selected value "value" : "value1", // name displayed after selection (optional) "text" : "Choice 1" // whether field should be displayed as disabled (optional) "disabled" : false }, { "name" : "Choice 2", "value" : "value2", "text" : "Choice 2" }, { "name" : "Choice 3", "value" : "value3", "text" : "Choice 3" }, { "name" : "Choice 4", "value" : "value4", "text" : "Choice 4" }, { "name" : "Choice 5", "value" : "value5", "text" : "Choice 5" } ] }

文本标签 (Text Labels)

有时候,多选可能会出现文本太多太长的情况,设置 useLabels: false 将只显示一个选择计数, 并且允许直接从菜单选择。

你可以调整模板中的 settings.message 来自定义显示的消息。
或者
$('.no.label.example .ui.dropdown') .dropdown({ useLabels: false }) ;

向上 (Upward)

如果屏幕周围空间不够大,下拉菜单会自动改变它打开的方向。如果您需要在特定方向上打开下拉菜单,则可以在初始化下拉菜单时指定它。

$('.upward.example .dropdown') .dropdown({ direction: 'upward' }) ;

菜单

改变过渡 (Changing Transitions)

下拉菜单可以指定一个不同的 过渡

$('.dropdown') .dropdown({ // you can use any ui transition transition: 'drop' }) ;
切换

分类选择 (Category Selection)

多级菜单使用 allowCategorySelection: true 将使子菜单项被选中。

$('.category.example .ui.dropdown') .dropdown({ allowCategorySelection: true }) ;

调整行为

组合下拉菜单 (Combo Dropdowns)

下拉菜单可以被格式化为 按钮

使用 combo 将改变前面选择的元素。

$('.combo.dropdown') .dropdown({ action: 'combo' }) ;
保存

耦合

初始化

初始化现有的HTML (Initializing Existing HTML)

初始化一个已经存在的HTML下拉列表比用select元素初始化有更更高的性能。

任何选择元素初始化为下拉框都会被隐藏,直到JavaScript创建HTML。这是为了避免让内容闪烁,并且元素的高度更好的适应页面。
$('.ui.dropdown') .dropdown() ;

转换表单元素 (Converting Form Elements)

为方便,select 元素能自动转换为 selection dropdown。选择空白的字符串值将被转换为提示文字选项。

$('#select') .dropdown() ;

混合形式初始化 (Hybrid Form Initialization)

作为一个选择,你对 select 进行封装,这样他将在加载的时候正确显示。但这将会在javascript失效时 遮盖掉隐藏菜单 在这种情况下 select 元素不接受 ui dropdown 类。

$('#hybrid select') .dropdown({ on: 'hover' }) ;

搜索下拉菜单 (Searching Dropdowns)

使用 search selection dropdown 将能使你更容易的在大数据里选择自己需要的值。这也可以直接从一个选择元素转换过来。

$('#search-select') .dropdown() ;

多重选择 (Multiple Selections)

您可以通过选择元素的多个属性允许多个选择,也可以在下拉列表中包含多个类。

当一个隐藏的输入框使用时,值将通过分隔符单个传递。默认是 "," 但可以用 delimiter 来修改。

$('#multi-select') .dropdown() ;
Dropdown
Select

特定选择操作 (Specifying Select Action)

选择项目会触发下拉框的多种内置行为,你可以在 settings.action 中赋值指定一个内置行为,或者是一个自定义方法。

行为 描述
activate (Default) 选择当前项目,调整下拉值和更改下拉文本
combo 和 activate 一样,但是更新以前的元素文本而不是它自己
select 从菜单选择当前项,但不改变下拉框文字
hide 隐藏下拉菜单并存储值,但不会更改文本
function(text, value){} 自定义操作
nothing 什么也不做

要指定一个不同的内置动作,只需指定动作名称即可。

$('.dropdown') .dropdown({ action: 'combo' }) ;

只触发 自定义动作 而不触发默认动作, 需在 settings.action中指定自己的方法。

$('.dropdown') .dropdown({ action: function(text, value) { // nothing built in occurs } }) ;

如果你想同时触发默认和自定义动作,只要 onChangeaction一起使用即可。

$('.dropdown') .dropdown({ action: 'hide', onChange: function(value, text, $selectedItem) { // custom action } }) ;

行为

所有以下的行为都可以用以下语法:

$('.your.element') .dropdown('behavior name', argumentOne, argumentTwo) ;
行为 描述
setup menu 从选择项 option 的值重新创建下拉菜单。
refresh 刷新所有缓存选择器和数据
toggle 切换当前下拉框的可见性
show 显示下拉框
hide 隐藏下拉框
clear 清除下拉框的选择
hide others 隐藏当前下拉菜单除外的其他所有菜单
restore defaults 将下拉框文本和值还原到页加载的值
restore default text 将下拉框文本恢复到页面加载的值
restore placeholder text 恢复下拉框文本到其原始占位符文本
restore default value 将下拉框值还原到页加载的值
save defaults 保存当前文本和值作为新的缺省值 (用于恢复)
set selected(value) 设置选择的值
remove selected(value) 将选定项的值移除
set selected([value1, value2]) 添加一组选择的值
set exactly([value1, value2]) 将选定的值设置为指定的值,取消当前选择
set text(text) 将下拉框选择的文本设置为一个值
set value(value) 将下拉框输入转换为值 (不更新显示状态)
get text 返回当前下拉框文本
get value 返回当前下拉框输入值
get item(value) 返回 DOM 元素的匹配给定的输入值
bind touch events 添加触摸事件到元素
bind mouse events 添加鼠标事件到元素
bind intent 将单击绑定到文档以确定是否点击了下拉菜单
unbind intent 解除绑定
determine intent 判断在下拉框内部是否发生了事件
determine select action(text, value) 在文本/值的基础上判断预设值
set active 设置下拉到激活状态
set visible 设置下拉到可见状态
remove active 移除下拉框激活状态
remove visible 移除下拉框可见状态
is selection 判断下拉框是否为可选下拉框
is animated 判断下拉框是否为动画
is visible 判断下拉框是否下拉可见
is hidden 判断下拉框是否隐藏
get default text 返回下拉框在页面加载时候的默认值
get placeholder text 返回默认占位符的值

下拉框

日常使用设置 (Frequently Used Settings)

设置 默认 描述
on click 切换下拉框的事件 (鼠标悬停, 单击, 自定义事件)
allowReselection false 当设置为 true 时出发 onChange 事件,这是在用户选择的值和当前值相同的请款下。
allowAdditions false 判断搜索选择框是否允许用户添加自己的选择项,单选或者多选。
hideAdditions true When disabled user additions will appear in the results menu using a specially for马特ed selection item for马特ed by templates.addition.
action auto

Sets a default action to occur. (See usage guide)

activate (default)
Updates dropdown text with selected value, sets element state to active, updates any hidden fields if available
select
activates menu and updates input fields, but does not change current text
combo
changes text of previous sibling element
nothing
no action occurs
hide
Dropdown menu is hidden
function(text, value, element){}
custom function is executed with values specified in callback
minCharacters 1 The minimum characters for a search to begin showing results
match both When using search selection specifies how to match values.
both
Matches against text and value
value
matches against value only
text
matches against text only
selectOnKeydown true Whether dropdown should select new option when using keyboard shortcuts. Setting to false will require enter or left click to confirm a choice.
forceSelection true Whether search selection will force currently selected choice when element is blurred.
allowCategorySelection false Whether menu items with sub-menus (categories) should be selectable
placeholder auto
auto
Convert option with "" (blank string) value to placeholder text
value
Sets string value to placeholder text, leaves "" value
false
Leaves "" value as a selectable option

Remote Settings

Setting Default Description
apiSettings false Can be set to an object to specify API settings for retrieving remote selection menu content from an API endpoint
fields
fields: { remoteValues : 'results', // grouping for api results values : 'values', // grouping for all dropdown values name : 'name', // displayed dropdown text value : 'value' // actual dropdown value }
List mapping dropdown content to JSON Property when using API
saveRemoteData true When enabled will automatically store selected name/value pairs in sessionStorage to preserve user selection on page refresh. Disabling will clear remote dropdown values on refresh.

Multiple Select Settings

Setting Default Description
useLabels true Whether multiselect should use labels. Must be set to true when allowAdditions is true
maxSelections false When set to a number, sets the maximum number of selections
glyphWidth 1.0714 Maximum glyph width, used to calculate search size. This is usually size of a "W" in your font in em
label
label: { transition : 'horizontal flip', duration : 200, variation : false }
Allows customization of multi-select labels

Additional Settings

Setting Default Description
direction 'auto' When set to auto determines direction based on whether dropdown can fit on screen. Set to upward or downward to always force a direction.
keepOnScreen true Whether dropdown should try to keep itself on screen by checking whether menus display position in its context (Default context is page).
context window Element context to use when checking whether can show when keepOnScreen: true
fullTextSearch false Specifying to "true" will use a fuzzy full text search, setting to "exact" will force the exact search to be matched somewhere in the string
preserveHTML true Whether HTML included in dropdown values should be preserved. (Allows icons to show up in selected value)
sortSelect false Whether to sort values when creating a dropdown automatically from a select element.
showOnFocus true Whether to show dropdown menu automatically on element focus.
allowTab true Whether to allow the element to be navigable by keyboard, by automatically creating a tabindex
transition auto (slide down / slide up) Named transition to use when animating menu in and out. Defaults to slide down or slide up depending on dropdown direction. Fade and slide down are available without including ui transitions
duration 200 Duration of animation events
keys
keys : { backspace : 8, delimiter : 188, // comma deleteKey : 46, enter : 13, escape : 27, pageUp : 33, pageDown : 34, leftArrow : 37, upArrow : 38, rightArrow : 39, downArrow : 40 }
The keycode used to represent keyboard shortcuts. To avoid issues with some foreign languages, you can pass false for comma delimiter's value
delay
delay : { hide : 300, show : 200, search : 50, touch : 50 }
Time in milliseconds to debounce show or hide behavior when on: hover is used, or when touch is used.

Callbacks

Context Description
onChange(value, text, $choice) Dropdown Is called after a dropdown value changes. Receives the name and value of selection and the active menu element
onAdd(addedValue, addedText, $addedChoice) Dropdown Is called after a dropdown selection is added using a multiple select dropdown, only receives the added value
onRemove(removedValue, removedText, $removedChoice) Dropdown Is called after a dropdown selection is removed using a multiple select dropdown, only receives the removed value
onLabelCreate(value, text) $label (jQDOM) Allows you to modify a label before it is added. Expects the jQ DOM element for a label to be returned.
onLabelRemove(value) $label (jqDOM) Called when a label is remove, return false; will prevent the label from being removed.
onLabelSelect($selectedLabels) Dropdown Is called after a label is selected by a user
onNoResults(searchValue) Dropdown Is called after a dropdown is searched with no matching values
onShow Dropdown Is called before a dropdown is shown. If false is returned, dropdown will not be shown.
onHide Dropdown Is called before a dropdown is hidden. If false is returned, dropdown will not be hidden.

Module Settings

DOM Settings
DOM settings specify how this module should interface with the DOM

Default Description
namespace dropdown Event namespace. Makes sure module teardown does not effect other events attached to an element.
message

You can specify site wide messages by modifying $.fn.dropdown.settings.message that will apply on any dropdown if it appears in the page.

message: { addResult : 'Add {term}', count : '{count} selected', maxSelections : 'Max {maxCount} selections', noResults : 'No results found.' }
selector
selector : { addition : '.addition', dropdown : '.ui.dropdown', icon : '> .dropdown.icon', input : '> input[type="hidden"], > select', item : '.item', label : '> .label', remove : '> .label > .delete.icon', siblingLabel : '.label', menu : '.menu', message : '.message', menuIcon : '.dropdown.icon', search : 'input.search, .menu > .search > input', text : '> .text:not(.icon)' }
regExp
regExp : { escape : /[-[\]{}()*+?.,\\^$|#\s]/g, }
metadata
metadata : { defaultText : 'defaultText', defaultValue : 'defaultValue', placeholderText : 'placeholderText', text : 'text', value : 'value' }
className
className : { active : 'active', addition : 'addition', animating : 'animating', disabled : 'disabled', dropdown : 'ui dropdown', filtered : 'filtered', hidden : 'hidden transition', item : 'item', label : 'ui label', loading : 'loading', menu : 'menu', message : 'message', multiple : 'multiple', placeholder : 'default', search : 'search', selected : 'selected', selection : 'selection', upward : 'upward', visible : 'visible' }
name Dropdown Name used in debug logs
silent False Silences all console output including error messages, regardless of other debug settings.
debug False Provides standard debug output to console
performance True Provides standard debug output to console
verbose True Provides ancillary debug output to console
error
error : { action : 'You called a dropdown action that was not defined', alreadySetup : 'Once a select has been initialized behaviors must be called on the created ui dropdown', labels : 'Allowing user additions currently requires the use of labels.', method : 'The method you called is not defined.', noTransition : 'This module requires ui transitions ' }

Dimmer Message
Dimmer sub-header