语言: 英文中文

搜索栏

搜索栏允许用户在列表元素中搜索,或者它可以用来作为UI组件,放到你自己的搜索实现中。

搜索栏布局

搜索栏应该放到“.page”内,“.page-content”前:

<div class="page">
    <!-- Search bar -->
    <form class="searchbar">
        <div class="searchbar-input">
            <input type="search" placeholder="Search">
            <a href="#" class="searchbar-clear"></a>
        </div>
        <a href="#" class="searchbar-cancel">Cancel</a>
    </form>
    
    <!-- Search bar overlay-->
    <div class="searchbar-overlay"></div>
    
    <!-- Page content -->
    <div class="page-content">
        <div class="content-block searchbar-not-found">
                Nothing found
        </div>
 
        <div class="list-block list-block-search searchbar-found">
            <ul>
                ... list view items ...
            </ul>
        </div>
    </div>
</div>

其中:

  • form class="searchbar" - 主要的搜索栏容器。它不必是个form元素,但推荐如此。
    • div class="searchbar-input" - 搜索区域和取消按钮的容器
      • input type="search" - search field
      • a class="searchbar-clear" - button to clear field value and reset search results. Optional element
    • a class="searchbar-cancel" - searchbar Cancel button that will deactivate searchbar, reset search results and clear search field. Optional element
  • div class="searchbar-overlay" - Add this element right after search bar to enable dark overlay over page content when search bar is active. Optional element.
  • "list-block-search" - list block where we are going to search elements.
  • "searchbar-found" - element with this class will be displayed if searchbar find elements that match to search query. Visible by default. Optional element.
  • "searchbar-not-found" - element with this class will be displayed if searchbar doesn't find elements that match to search query. Hidden by default. Optional element.

Initialize Searchbar with JavaScript

Now, when we have Searchbar' HTML, we need to initialize it. We need to use related App's method:

myApp.searchbar(searchbarContainer, parameters) - initialize searchbar with options

  • searchbarContainer - HTMLElement or string (with CSS Selector) of Searchbar container HTML element. Required.
  • parameters - object - object with Searchbar parameters. Optional.
  • Method returns initialized Searchbar instance

For example:

var mySearchbar = app.searchbar('.searchbar', {
    searchList: '.list-block-search',
    searchIn: '.item-title'
});   
Note that Searchbar container should be in DOM on a moment of initialization. So if you use it not on home page, you need to initialize it within pageInit event or callback

Searchbar Parameters

Let's look on list of all available parameters:

Parameter Type Default Description
searchList string or HTMLElement CSS selector or HTML element of list block to search
searchIn string '.item-title' CSS selector of List View element's field where we need to search. Usually we search through element titles ('.item-title'). It is also to pass few elements for search like '.item-title, .item-text'
found string or HTMLElement CSS selector or HTMLElement of searchbar "found" element. If not specified, searchbar will look for .searchbar-found element on page
notFoud string or HTMLElement CSS selector or HTMLElement of searchbar "not-found" element. If not specified, searchbar will look for .searchbar-not-found element on page
overlay string or HTMLElement CSS selector or HTMLElement of searchbar overlay. If not specified, searchbar will look for .searchbar-overlay element on page
ignore string '.searchbar-ignore' CSS selector for items to be ignored by searchbar and always present in search results
customSearch boolean false When enabled searchbar will not search through any of list blocks specified by `searchList` and you will be able to use custom search functionality, for example, for calling external APIs with search results and for displaying them manually
removeDiacritics boolean false Enable to remove/replace diacritics (á, í, ó, etc.) during search
hideDividers boolean true If enabled, then search will consider item dividers and group titles and hide them if there are no found items right after them
hideGroups boolean true If enabled, then search will consider list view groups hide them if there are no found items inside of these groups
Callbacks
onSearch function (s) Callback function will be triggered during search (search field change).
onEnable function (s) Callback will be triggered when Search Bar becomes active
onDisable function (s) Callback will be triggered when Search Bar becomes inactive - when user clicks on "Cancel" button or on "searchbar-overlay" element
onClear function (s) Callback will be triggered when user clicks on Search Bar's "clear" element

Searchbar Methods & Properties

After we initialize Searchbar we have its initialized instance in variable (like mySearchbar variable in example above) with helpful methods and properties:

Properties
mySearchbar.params Object with passed initialization parameters
mySearchbar.query Current search query (search input value)
mySearchbar.searchList Dom7 element with search list block.
mySearchbar.container Dom7 element with searchbar container HTML element.
mySearchbar.input Dom7 element with searchbar input HTML element
mySearchbar.active Boolean value that represents is searchbar enabled or disabled
Methods
mySearchbar.search(query); Force searchbar to search passed query
mySearchbar.enable(); Enable/activate searchbar
mySearchbar.disable(); Disable/deactivate searchbar
mySearchbar.clear(); Clear search query and update results
mySearchbar.destroy(); Destroy searchbar instance

Initialize Searchbar with HTML

If you don't need to use Searchbar methods and properties you can initialize it using HTML without JavaScript. You can do that just by adding additional "searchbar-init" class to .searchbar. In this case we may pass required parameters using data- attributes.

<div class="page">
    <!-- Search bar with "searchbar-init" class for auto initialization -->
    <form class="searchbar searchbar-init" data-search-list=".list-block-search" data-search-in=".item-title" data-found=".searchbar-found" data-not-found=".searchbar-not-found">
        <div class="searchbar-input">
            <input type="search" placeholder="Search">
            <a href="#" class="searchbar-clear"></a>
        </div>
        <a href="#" class="searchbar-cancel">Cancel</a>
    </form>
    
    <div class="searchbar-overlay"></div>
    
    <div class="page-content">
        <div class="content-block searchbar-not-found">
                Nothing found
        </div>
 
        <div class="list-block list-block-search searchbar-found">
            <ul>
                ... list view items ...
            </ul>
        </div>
    </div>
</div> 

Parameters that used in camelCase, for example searchList, in data- attributes should be used as hypens-case as data-search-list

Access to Searchbar's Instance

If you initialize Searchbar using HTML it is still possible to access to Searchbar's instance. It is "f7Searchbar" property of searchbar's container HTML element:

var mySearchbar = $$('.searchbar')[0].f7Searchbar;
 
// Now you can use it
mySearchbar.search('Hello world');

Search Bar Example

In this example we use searchbar with auto initialization

<div data-page="home" class="page">
  <!-- Search bar -->
  <form data-search-list=".list-block-search" data-search-in=".item-title" class="searchbar searchbar-init">
    <div class="searchbar-input">
      <input type="search" placeholder="Search"><a href="#" class="searchbar-clear"></a>
    </div><a href="#" class="searchbar-cancel">Cancel</a>
  </form>
 
  <!-- Search bar overlay -->
  <div class="searchbar-overlay"></div>
 
  <div class="page-content">
    <!-- This block will be displayed if nothing found -->
    <div class="content-block searchbar-not-found">
      <div class="content-block-inner">Nothing found</div>
    </div>
 
    <!-- This block will be displayed if anything found, and this list block is used a searbar target -->
    <div class="list-block list-block-search searchbar-found">
      <ul>
        <li class="item-content">
          <div class="item-inner">
            <div class="item-title">Acura </div>
          </div>
        </li>
        <li class="item-content">
          <div class="item-inner">
            <div class="item-title">Audi</div>
          </div>
        </li>
        ...
      </ul>
    </div>
  </div>
</div>          

搜索栏JavaScript事件

事件 目标 描述
搜索 在"data-search-list"<div class="list-block">中被指定的列表元素 在搜索过程中(搜索域改变)事件会被触发。事件包含搜索请求(e.detail.query)和找到的HTML元素(e.detail.foundItems)
清空搜索 在"data-search-list"<div class="list-block">中被指定的列表元素 当用户点击搜索栏“清空”按钮(a href="#" class="searchbar-clear")的时候,事件被触发
启用搜索 在"data-search-list"<div class="list-block">中被指定的列表元素 当搜索栏起作用时,事件被触发
禁用搜索 在"data-search-list"<div class="list-block">中被指定的列表元素 当搜索栏被禁用时 - 用户点击“取消”按钮或"searchbar-overlay"元素,事件被触发