• x7_211199
  • 336.3KB
  • zip
  • 0
  • VIP专享
  • 0
  • 2022-05-25 05:55
EasyDropDown 4 EasyDropDown将不起眼的<select>元素转换为适合您的设计和品牌的空白画布。 作为一项直接的增强功能,EasyDropDown保留了标准单选项选择菜单的所有功能和可访问性,同时公开了易于设计和自定义以满足设计需求的语义DOM结构。 EasyDropDown捆绑了三个,可以用作自定义样式的起点。 查看,看有什么可能。 演示的源代码可以在目录中找到。 注意:如果您正在移动设备上查看演示,则会根据看到设备的本机选择UI。 特征 尊重原生<select>元素API * 全面的键盘支持(导航,搜索和选择) 发出本地change事件 增强的占位符支持 表单重置和验证支持 碰撞检测 实时更新 退回到移动设备上的本机UI CSS模块支持 TypeScript /智能支持 符合ARIA的标记 支持IE9 +和所有现代浏览器。 9kb压缩 没有第三方
# EasyDropDown 4 [![Build Status](https://img.shields.io/travis/patrickkunka/easydropdown.svg?style=flat-square)](https://travis-ci.org/patrickkunka/easydropdown) [![Coverage Status](https://img.shields.io/coveralls/patrickkunka/easydropdown.svg?style=flat-square)](https://coveralls.io/github/patrickkunka/easydropdown) [![Latest Release](https://img.shields.io/npm/v/easydropdown.svg?style=flat-square)](https://www.npmjs.com/package/easydropdown) [![Apache License](https://img.shields.io/npm/l/easydropdown.svg?style=flat-square)](https://www.apache.org/licenses/) EasyDropDown transforms the humble `<select>` element into a blank canvas for your design and brand. As a drop-in enhancement, EasyDropDown maintains all the functionality and accessibility of a standard single-option select menu, while exposing a semantic DOM-structure that's easy to style and customize to the needs of your design. EasyDropDown comes bundled with three [ready-made themes](./demos/themes) which can be used as a starting point for custom styling. Check out the **[demos](https://demos.kunkalabs.com/easydropdown/)** to see what's possible. The source code for the demos can be found in the [./demos/](./demos/) directory. *NB: If you are viewing the demos on a mobile device, you will see the device's native select UI as per the [default configuration](#usenativeuionmobile).* ### Features - Respects the native `<select>` element API* - Full keyboard support (navigation, search and select) - Emits native `change` events - Enhanced placeholder support - Form reset and validation support - Collision detection - Live updates - Falls back to native UI on mobile devices - CSS Modules support - TypeScript/intellisense support - ARIA-compliant-markup - Support for IE9+, and all modern browsers. - 9kb gzipped - No third-party dependencies **EasyDropDown [does not support](#multiple-attribute-support) the `multiple` attribute.* #### Contents - [Installation](#installation) - [Usage](#usage) - [Single-instance instantiation](#single-instance-instantiation) - [Batch instantiation](#batch-instantiation) - [Placeholder Functionality](#placeholder-functionality) - [Reading and Writing Values](#reading-and-writing-values) - [Anatomy of EasyDropDown](#anatomy-of-easydropdown) - [Configuration Options](#configuration-options) - [Available Options](#available-options) - [API Methods](#api-methods) - [React Example](#react-example) - [CSS Modules Example](#css-modules-example) - [TypeScript Support](#typescript-support) - [Multiple Attribute Support](#multiple-attribute-support) ## Installation Firstly, install the package using your package manager of choice. ``` npm install easydropdown --save ``` #### Module Import You may then import the `easydropdown()` factory function into your project's modules. ```js // ES Modules import easydropdown from 'easydropdown'; // CommonJS const easydropdown = require('easydropdown'); // AMD/RequireJS define(['easydropdown/bundles/easydropdown.js'] , easydropdown => { ... }); ``` #### Script Tag Alternatively, for basic projects without modular scoping or a build process, the most simple way to use EasyDropDown is via a `<script>` tag before your closing body tag. A pre-built "UMD" bundle is provided for this purpose which can be found at `./bundle/easydropdown.js`. ```html ... <script src="./path/to/easydropdown.min.js"/> </body> ``` This will attach the `easydropdown` factory function to the `window` as a global. ## Usage Because EasyDropDown is an enhancement on top of native the `<select>` element, we must firstly create an underlying select element in our project's HTML, just as we normally would: ```html <select name="foo" id="my-select"> <option value="">Select</option> <option value="1">Option 1</option> <option value="2">Option 2</option> <option value="3">Option 3</option> ... </select> ``` Next, we instantiate EasyDropDown by passing a reference to the select element(s), or a selector string. We can either instantiate a single instance at a time, or a batch of instances. #### Single-instance Instantiation We can create an instance of EasyDropDown by passing a reference to a `<select>` element to the `easydropdown()` factory function: ```js const selectElement = document.querySelector('#my-select'); const edd = easydropdown(selectElement); ``` Or, by passing a selector string directly: ```js const edd = easydropdown('#my-select'); ``` As shown above, a reference to the dropdown instance (`edd`) can be held onto in order to destroy it later, or interact with the dropdown programmatically. See [API Methods](#api-methods) for more information. This approach is recommended for any component-based architecture where only the component is concerned with the dropdown instance. The factory function also accepts an optional second parameter of configuration options. See [Configuration Options](#configuration-options) for more information. #### Batch Instantiation For simple static pages/applications, we can use the `.all()` static method of the factory function to crawl the DOM for *all* `<select>` elements found in the document, and then batch instantiate EasyDropDown on each one. ```js easydropdown.all(); ``` The `all()` method also accepts an optional parameter of configuration options to be passed to each instance. See [Configuration Options](#configuration-options) for more information. ### Placeholder Functionality With the exception of the [multiple attribute](#multiple-attribute), EasyDropDown supports all the available attributes of the native `<select>` element, such as `disabled`, `required` and `selected`. In addition to these, EasyDropDown adds a new "placeholder" attribute. A common pattern when working with `<select>` elements, is to use the first `<option>` element as a placeholder value by giving it an empty `""` value, as the first option will always be selected by default. For example: ```html <select> <option value="">Select an option</option> <option value="1">Option 1</option> <option value="2">Option 2</option> <option value="3">Option 3</option> ... </select> ``` EasyDropDown enhances this pattern with the ability to add a `data-placeholder` attribute to this element to inform EasyDropDown that the option is a placeholder only and should *not* be an available selection once the user has selected a value. ```html <select> <option value="" data-placeholder>Select an option</option> <option value="1">Option 1</option> <option value="2">Option 2</option> <option value="3">Option 3</option> ... </select> ``` Check out the [Basic List with Placeholder](https://demos.kunkalabs.com/easydropdown/02-basic-list-with-placeholder.html) demo to see an example of this feature. *NB: This feature should not be used if you want the user to be able to leave the field blank.* Additionally, EasyDropDown can be configured to reshow the placeholder value after a value has been selected as a hint to the user whenever the dropdown is open. This is available via the `behavior.showPlaceholderWhenOpen` configuration option, and can be seen in the [Show Placeholder When Open](https://demos.kunkalabs.com/easydropdown/11-show-placeholder-when-open.html) demo. ### Reading and Writing Values As en enhancement on top of native `<select>` elements, EasyDropDown always keeps the underyling `<select>` element in sync with the current selection (emitting a `change` event on value change), and conversely, always updates itself in response to a programmatic change in value to the underlying select. As such, you can read and write the `value` of the underlying select, just as you normally would. ```js const selectElement = document.querySelector('#my-select'); const edd = easydropdown(selectElement); selectElement.value = 'foo'; console.log(edd.value); // foo ``` > Writing a value to the select element ```js const selectElement = docum