options.md 11.2 KB

原文件审查历史永久链接



Core options


Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in 
data-style="" or data-selected-text-format="count".


    Name
    Type
    Default
    Description
  
  
    actionsBox
    boolean
    false
    
      When set to true, adds two buttons to the top of the dropdown menu (Select All & Deselect All).
    
  
    container
    string | false
    false
    
        When set to a string, appends the select to a specific element or selector, e.g., 
        container: 'body' | '.main-body'
    
  
    countSelectedText
    string | function
    function
    
      Sets the format for the text displayed when selectedTextFormat is count or count > 
      #. {0} is the selected amount. {1} is total available for selection.
      When set to a function, the first parameter is the number of selected options, and the second is the total number of 
      options. The function must return a string.
    
  
    deselectAllText
    string
    'Deselect All'
    
      The text on the button that deselects all options when actionsBox is enabled.
    
  
    dropdownAlignRight
    boolean | 'auto'
    false
    
      Align the menu to the right instead of the left. If set to 'auto', the menu will automatically align right if there isn't room for the menu's full width when aligned to the left.
    
  
    dropupAuto
    boolean
    true
    
      checks to see which has more room, above or below. If the dropup has enough room to fully open normally, but
      there is more room above, the dropup still opens normally. Otherwise, it becomes a dropup. If dropupAuto is
      set to false, dropups must be called manually.
    
  
    header
    string
    false
    
      adds a header to the top of the menu; includes a close button by default
    
  
    hideDisabled
    boolean
    false
    
      removes disabled options and optgroups from the menu data-hide-disabled: true
    
  
    iconBase
    string
    'glyphicon'
    
      Set the base to use a different icon font instead of Glyphicons. If changing iconBase, you might also want to change tickIcon, in case the new icon font uses a different naming scheme.
    
  
    liveSearch
    boolean
    false
    
      When set to true, adds a search box to the top of the selectpicker dropdown.
    
  
    liveSearchNormalize
    boolean
    false
    
      Setting liveSearchNormalize to true allows for accent-insensitive searching.
    
  
    liveSearchPlaceholder
    string
    null
    
      When set to a string, a placeholder attribute equal to the string will be added to the liveSearch input.
    
  
    liveSearchStyle
    string
    'contains'
    
      When set to 'contains', searching will reveal options that contain the searched text. For example, searching for pl with return both Apple, Plum, and Plantain. When set to 'startsWith', searching for pl will return only Plum and Plantain.
    
  
    maxOptions
    integer | false
    false
    
      When set to an integer and in a multi-select, the number of selected options cannot exceed the given value.
      This option can also exist as a data-attribute for an <optgroup>, in which case it only 
      applies to that <optgroup>.
    
  
    maxOptionsText
    string | array | function
    function
    
      The text that is displayed when maxOptions is enabled and the maximum number of options for the given scenario have been selected.
      If a function is used, it must return an array. array[0] is the text used when maxOptions is applied to the entire select element. array[1] is the text used when maxOptions is used on an optgroup. If a string is used, the same text is used for both the element and the optgroup.
    
  
    mobile
    boolean
    false
    
      When set to true, enables the device's native menu for select menus.
    
  
    multipleSeparator
    string
    ', '
    
      Set the character displayed in the button that separates selected options.
    
  
    noneSelectedText
    string
    'Nothing selected'
    
      The text that is displayed when a multiple select has no selected options.
    
  
    selectAllText
    string
    'Select All'
    
      The text on the button that selects all options when actionsBox is enabled.
    
  
    selectedTextFormat
    
'values' | 'static' | 'count' | 'count > x' (where x is an integer)
    'values'
    
      Specifies how the selection is displayed with a multiple select.
      'values' displays a list of the selected options (separated by multipleSeparator. 'static' simply displays the select element's title. 'count' displays the total number of selected options. 'count > x' behaves like 'values' until the number of selected options is greater than x; after that, it behaves like 'count'.
    

    selectOnTab
    boolean
    false
    
      When set to true, treats the tab character like the enter or space characters within the 
      selectpicker dropdown.
    
  
    showContent
    boolean
    true
    
      When set to true, display custom HTML associated with selected option(s) in the button. When set 
       to false, the option value will be displayed instead.
    
  
    showIcon
    boolean
    true
    
      When set to true, display icon(s) associated with selected option(s) in the button.
    
  
    showSubtext
    boolean
    false
    
      When set to true, display subtext associated with a selected option in the button.
    
  
    showTick
    boolean
    false
    
      Show checkmark on selected option (for items without multiple attribute).
    
  
    size
    
'auto' | integer | false
    'auto'
    
      When set to 'auto', the menu always opens up to show as many items as the window will allow
      without being cut off.
      When set to an integer, the menu will show the given number of items, even if the dropdown is cut off.
      When set to false, the menu will always show all items.
    
  
    style
    string | null
    null
    
      When set to a string, add the value to the button's style.
    
  
    tickIcon
    string
    'glyphicon-ok'
    
      Set which icon to use to display as the "tick" next to selected options.
    
  
    title
    string | null
    null
    
      The default title for the selectpicker.
    
  
    width
    
'auto' | 'fit' | css-width | false (where css-width is a CSS width with units, e.g. 100px)
    false
    
      When set to auto, the width of the selectpicker is automatically adjusted to accommodate the 
      widest option.
      When set to a css-width, the width of the selectpicker is forced inline to the given value.
      When set to false, all width information is removed.
    
  
Events


Bootstrap-select exposes a few events for hooking into select functionality.

hide.bs.select, hidden.bs.select, show.bs.select, and shown.bs.select all have a relatedTarget property, whose value is the toggling anchor element.


      Event Type
      Description
    
  
      show.bs.select
      This event fires immediately when the show instance method is called.
    
    
      shown.bs.select
      This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete).
    
    
      hide.bs.select
      This event is fired immediately when the hide instance method has been called.
    
    
      hidden.bs.select
      This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete).
    
    
      loaded.bs.select
      This event fires after the select has been initialized.
    
    
      rendered.bs.select
      This event fires after the render instance has been called.
    
    
      refreshed.bs.select
      This event fires after the refresh instance has been called.
    
    
      changed.bs.select
      This event fires after the select's value has been changed. It passes through event, clickedIndex, newValue, oldValue.
    
  
$('#mySelect').on('hidden.bs.select', function (e) {
  // do something...
});