Telerik
/
kendo-react-dropdowns
зеркало из https://github.com/telerik/kendo-react-dropdowns.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

docs(dropdownlist): Add DropDownList overview topic

This commit is contained in:
Alexander Valchev 2016-05-02 13:59:55 +03:00
Родитель fba6e4677c
Коммит e50b62e3ea
1 изменённых файлов: 363 добавлений и 148 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

511
docs/dropdownlist/index.md
Просмотреть файл

@ -8,7 +8,7 @@ position: 1
# DropDownList Overview # DropDownList Overview
The Kendo UI DropDownList for React provides suggestions to the user from a previously entered list of options depending on the typed input. The Kendo UI DropDownList for React displays a list of values and allows for a single selection from the list. The user input is restricted within the predefined options. Use the Kendo UI ComboBox for React component if you want to apply a keyboard input.
The Kendo UI DropDownList for React is part of the DropDowns `npm` package of the Kendo UI suite for React. The Kendo UI DropDownList for React is part of the DropDowns `npm` package of the Kendo UI suite for React.
@ -28,234 +28,441 @@ The Kendo UI DropDownList for React is part of the DropDowns `npm` package of th
The example below demonstrates the default setup of a Kendo UI DropDownList for React. The example below demonstrates the default setup of a Kendo UI DropDownList for React.
```html-preview ```html-preview
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [ "Item 1", "Item 2", "Item 3" ];
ReactDOM.render(
<KendoReactDropdowns.DropDownList data={data} defaultItem="Select..." />,
document.getElementById('app')
);
``` ```
## Configuration ## Configuration
### Data ### Data
data: PropTypes.arrayOf(PropTypes.oneOfType([ Kendo UI DropDownList for React supports binding data of complex (object) or primitive (string, number) type.
PropTypes.object, The `defaultItem` property type must match the data type, e.g. if the component `data` contains objects the `defaultItem` must be defined as an object with same `textField` and `valueField` as the data items.
PropTypes.string,
PropTypes.number #### Binding to array of primitive data
]))
```html ```html
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [ "Item 1", "Item 2", "Item 3" ];
ReactDOM.render(
<KendoReactDropdowns.DropDownList data={data} defaultItem="Select..." />,
document.getElementById('app')
);
``` ```
dataItem: PropTypes.oneOfType([ #### Binding to array of objects
PropTypes.object,
PropTypes.string,
PropTypes.number
])
```html ```html
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [
{ text: "Foo", value: 1 },
{ text: "Bar", value: 2 },
{ text: "Baz", value: 3 },
];
``` ReactDOM.render(
<KendoReactDropdowns.DropDownList
data={data}
defaultItem={{ text: "Select...", value: null }}
textField="text"
valueField="value"
/>,
document.getElementById('app')
);
```
defaultItem: function(props, propName, componentName) { ### Value
if (props.defaultItem && props.valueField && typeof props.defaultItem !== "object") {
return new Error(` The value of the DropDownList component can be set via `value` or `index` property. If both are provided the `value` will take precedence.
${componentName} invalid configuration. When the value changes the component will execute the `onChange` callback function.
DefaultItem type should match the data items type!
Define the defaultItem as an object with ${props.textField} and ${props.valueField} fields! ```html-preview
); <div id="app"></div>
```
```jsx
const data = [
{ text: "Foo", value: 1 },
{ text: "Bar", value: 2 },
{ text: "Baz", value: 3 },
];
class DropDownListContainer extends React.Component {
constructor(props) {
super(props);
this.state = {
value: 2
};
}
onChange = (value) => {
this.setState({
value: value
});
}
render() {
const value = this.state.value;
return (
<div>
<KendoReactDropdowns.DropDownList
data={data}
defaultItem={{ text: "Select...", value: null }}
onChange={this.onChange}
textField="text"
valueField="value"
value={value}
/>
<span>Selected value: <span style={{ color: "#f00" }}>{value}</span></span>
</div>
);
}
} }
}
```html
```
```jsx
ReactDOM.render(
<DropDownListContainer />,
document.getElementById('app')
);
``` ```
### Features ### Features
className: PropTypes.string #### Search with keyboard
```html By default the user is able to navigate between items by typing with the keyboard. By default the seach is case-insensitive and the delay before the search-text typed by the end user is cleared is 500 milliseconds.
These settings can be changed through the `ignoreCase` and `delay` configuration properties.
```html-preview
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [ "Jack", "Jane", "John", "Jacob", "Jake" ];
ReactDOM.render(
<div>
<p>Focus the component and use the keyboard to navigate between items</p>
<KendoReactDropdowns.DropDownList data={data} delay={1000} ignoreCase={false} index={0} />
</div>,
document.getElementById('app')
);
``` ```
delay: PropTypes.number #### Filter the items
```html If the `filterable` attribute is set the component will render filter input field that allows the user to filter the DropDownList options.
When the user changes the filter input value the component will execute its `onFilter` callback. It is responsibility of the developer to perform the data filtration and update DropDownList's data through the component's props.
> If filtration is enabled the default search between items functionality will be automatically disabled.
```html-preview
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [
"Albania",
"Andorra",
"Armenia",
"Austria",
"Azerbaijan",
"Belarus",
"Belgium",
"Bosnia & Herzegovina",
"Bulgaria",
"Croatia",
"Cyprus",
"Czech Republic",
"Denmark",
"Estonia",
"Finland",
"France",
"Georgia",
"Germany",
"Greece",
"Hungary",
"Iceland",
"Ireland",
"Italy",
"Kosovo",
"Latvia",
"Liechtenstein",
"Lithuania",
"Luxembourg",
"Macedonia",
"Malta",
"Moldova",
"Monaco",
"Netherlands",
"Norway",
"Poland",
"Portugal",
"Romania",
"Russia",
"San Marino",
"Serbia",
"Slovakia",
"Slovenia",
"Spain",
"Sweden",
"Switzerland",
"Turkey",
"Ukraine",
"United Kingdom",
"Vatican City"
];
class DropDownListContainer extends React.Component {
constructor(props) {
super(props);
this.state = {
value: null,
data: data
};
}
onChange = (value) => {
this.setState({
value: value
});
}
onFilter = (text) => {
let result;
if (text) {
result = data.filter(function(item) {
return item.toLowerCase().startsWith(text.toLowerCase());
});
} else {
result = data;
}
this.setState({
data: result
});
}
render() {
const { data, value } = this.state;
return (
<div>
<KendoReactDropdowns.DropDownList
data={data}
filterable
onChange={this.onChange}
onFilter={this.onFilter}
value={value}
/>
<span>Selected value: <span style={{ color: "#f00" }}>{value}</span></span>
</div>
);
}
}
ReactDOM.render(
<DropDownListContainer />,
document.getElementById('app')
);
``` ```
disabled: PropTypes.bool #### Disabled DropDownList
```html If set the component will be disabled and will not allow user input.
```html-preview
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [ "Jack", "Jane", "John", "Jacob", "Jake" ];
ReactDOM.render(
<div>
<p>Disabled DropDownList</p>
<KendoReactDropdowns.DropDownList data={data} defaultItem="Select..." disabled />
</div>,
document.getElementById('app')
);
``` ```
filterable: PropTypes.bool #### Custom item and value render function
```html By default the widget will display selected item's `textField` both in the list and in the component's header.
This behaviour can be easily overwritten with the `itemRenderer` and `valueRenderer` callbacks.
```html-preview
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [
{ value: 1, text: "Foo" },
{ value: 2, text: "Bar" },
{ value: 3, text: "Baz" }
];
function renderItem (dataItem) {
return `Item: ${dataItem.text}`;
}
function renderValue (dataItem) {
return `Value: ${dataItem.value}`;
}
ReactDOM.render(
<KendoReactDropdowns.DropDownList
data={data}
itemRenderer={renderItem}
textField="text"
valueField="value"
valueRenderer={renderValue}
/>,
document.getElementById('app')
);
``` ```
focused: PropTypes.number ### Events
#### Popup open/close
```html ```html
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [
{ value: 1, text: "Foo" },
{ value: 2, text: "Bar" },
{ value: 3, text: "Baz" }
];
function onOpen(event) {
console.log("open");
}
function onClose(event) {
console.log("close");
}
ReactDOM.render(
<KendoReactDropdowns.DropDownList
data={data}
onClose={onClose}
onOpen={onOpen}
textField="text"
valueField="value"
/>,
document.getElementById('app')
);
``` ```
height: PropTypes.number #### Select and change
```html ```html
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [
{ value: 1, text: "Foo" },
{ value: 2, text: "Bar" },
{ value: 3, text: "Baz" }
];
function onSelect(value, dataItem) {
console.log("select");
}
function onChange(value, dataItem) {
console.log("change");
}
ReactDOM.render(
<KendoReactDropdowns.DropDownList
data={data}
onSelect={onSelect}
onChange={onChange}
textField="text"
valueField="value"
/>,
document.getElementById('app')
);
``` ```
ignoreCase: PropTypes.bool #### Filter
```html ```html
<div id="app"></div>
``` ```
```jsx ```jsx
const data = [
{ value: 1, text: "Foo" },
{ value: 2, text: "Bar" },
{ value: 3, text: "Baz" }
];
``` class DropDownListContainer extends React.Component {
constructor(props) {
super(props);
this.state = {
value: null,
data: data
};
}
selected: PropTypes.number onChange = (value) => {
this.setState({
value: value
});
}
```html onFilter = (text) => {
let result;
``` if (text) {
```jsx result = data.filter(function(item) {
return item.text.toLowerCase().startsWith(text.toLowerCase());
});
} else {
result = data;
}
``` this.setState({
data: result
});
}
show: PropTypes.bool render() {
const { data, value } = this.state;
```html return (
<div>
``` <KendoReactDropdowns.DropDownList
```jsx data={data}
filterable
``` onChange={this.onChange}
onFilter={this.onFilter}
style: PropTypes.object value={value}
/>
```html <span>Selected value: <span style={{ color: "#f00" }}>{value}</span></span>
</div>
``` );
```jsx }
}
```
tabIndex: PropTypes.number
```html
```
```jsx
```
textField: PropTypes.string
```html
```
```jsx
```
### Values
itemRenderer: PropTypes.func
```html
```
```jsx
```
valueField: PropTypes.string
```html
```
```jsx
```
valueRenderer: PropTypes.func
```html
```
```jsx
```
### State
onClose: PropTypes.func
```html
```
```jsx
```
onFilter: PropTypes.func
```html
```
```jsx
```
onOpen: PropTypes.func
```html
```
```jsx
```
onSelect: PropTypes.func
```html
```
```jsx
ReactDOM.render(
<DropDownListContainer />,
document.getElementById('app')
);
``` ```
For detailed information on the Kendo UI DropDownList for React configuration, refer to its [client-side API documentation]({% slug api_ddl_kendouiforreact %}). For detailed information on the Kendo UI DropDownList for React configuration, refer to its [client-side API documentation]({% slug api_ddl_kendouiforreact %}).
@ -266,10 +473,18 @@ Below is the list with the keyboard shortcuts the DropDownList supports.
| SHORTCUT | DESCRIPTION | | SHORTCUT | DESCRIPTION |
|:--- |:--- | |:--- |:--- |
| `up arrow` or `left arrow` | Highlights previous item |
| `down arrow` or `right arrow` | Highlights next item |
| `home` | Selects the first item from the list |
| `end` | Selects the last item from the list |
| `enter` | Selects the highlighted item |
| `esc` | Closes the popup |
| `alt` + `up arrow` | Closes the popup |
| `alt` + `down arrow` | Opens the popup |
## Accessibility ## Accessibility
The DropDownList is WAI ARIA-accessible through the `Tab` key. The `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` properties define the accessibility values when the user drags the handle of the DropDownList or interacts with the DropDownList through its buttons. The DropDownList is WAI ARIA-accessible through the `Tab` key.
## Suggested Links ## Suggested Links