zarm
Version:
基于 React 的移动端UI库
385 lines (346 loc) • 11.4 kB
Markdown
# Cascader 级联选择器
## 基本用法
```jsx
import { useState } from 'react';
import { Cascader, List, Button } from 'zarm';
const Demo = () => {
const [visible, setVisible] = useState(false);
const [value, setValue] = useState([]);
const District = [
{
value: '340000',
label: '安徽省',
children: [
{
value: '340800',
label: '安庆市',
children: [
{
value: '340803',
label: '大观区',
children: [],
},
{
value: '340822',
label: '怀宁县',
children: [],
},
{
value: '340882',
label: '其它区',
children: [],
},
],
},
],
},
{
value: '310000',
label: '上海',
children: [
{
value: '310100',
label: '上海市',
children: [
{
value: '310113',
label: '宝山区',
children: [],
},
{
value: '310105',
label: '长宁区',
children: [],
},
{
value: '310230',
label: '崇明县',
children: [],
},
{
value: '310152',
label: '川沙区',
children: [],
},
],
},
],
},
];
return (
<>
<List>
<List.Item
title="普通"
suffix={
<Button size="xs" onClick={() => setVisible(true)}>
选择
</Button>
}
>
{value.join(',')}
</List.Item>
</List>
<Cascader
maskClosable
visible={visible}
value={value}
title="级联选择器"
dataSource={District}
onChange={(value, items) => {
console.log('onChange', value, items);
}}
onConfirm={(value, items) => {
console.log('onConfirm', value, items);
setValue(value);
setVisible(false);
}}
onCancel={() => {
console.log('onCancel');
setVisible(false);
}}
/>
</>
);
};
ReactDOM.render(<Demo />, mountNode);
```
## 指令式
```jsx
import { useState, useEffect } from 'react';
import { List, Cascader, Button, Toast } from 'zarm';
const PROMPT_DATA = [
{
value: '340000',
label: '安徽省',
children: [
{
value: '340800',
label: '安庆市',
children: [
{
value: '340803',
label: '大观区',
children: [],
},
{
value: '340822',
label: '怀宁县',
children: [],
},
{
value: '340882',
label: '其它区',
children: [],
},
],
},
],
},
{
value: '310000',
label: '上海',
children: [
{
value: '310100',
label: '上海市',
children: [
{
value: '310113',
label: '宝山区',
children: [],
},
{
value: '310105',
label: '长宁区',
children: [],
},
{
value: '310230',
label: '崇明县',
children: [],
},
{
value: '310152',
label: '川沙区',
children: [],
},
],
},
],
},
];
const Demo = () => {
const [value, setValue] = useState([]);
return (
<List>
<List.Item
title="选择城市"
suffix={
<Button
size="xs"
onClick={async () => {
const { value: changedValue } = await Cascader.prompt({
value,
dataSource: PROMPT_DATA,
});
if (!changedValue) return;
setValue(changedValue);
Toast.show(JSON.stringify(changedValue));
}}
>
选择
</Button>
}
/>
</List>
);
};
ReactDOM.render(<Demo />, mountNode);
```
## CascaderView 级联选择视图
```jsx
import { useState } from 'react';
import { CascaderView } from 'zarm';
const Demo = () => {
const [value, setValue] = useState([]);
const District = [
{
value: '340000',
label: '安徽省',
children: [
{
value: '340800',
label: '安庆市',
children: [
{
value: '340803',
label: '大观区',
children: [],
},
{
value: '340822',
label: '怀宁县',
children: [],
},
{
value: '340882',
label: '其它区',
children: [],
},
],
},
],
},
{
value: '310000',
label: '上海',
children: [
{
value: '310100',
label: '上海市',
children: [
{
value: '310113',
label: '宝山区',
children: [],
},
{
value: '310105',
label: '长宁区',
children: [],
},
{
value: '310230',
label: '崇明县',
children: [],
},
{
value: '310152',
label: '川沙区',
children: [],
},
],
},
],
},
];
return (
<CascaderView
value={value}
dataSource={District}
onChange={(value, items) => {
console.log('onChange', value, items);
}}
/>
);
};
ReactDOM.render(<Demo />, mountNode);
```
## API
| 属性 | 类型 | 默认值 | 说明 |
| :----------- | :------------------------------- | :------------------------------------------------------- | :--------------------------------------- |
| dataSource | CascaderOption[] | [] | 数据源 |
| defaultValue | CascaderValue[] | - | 初始值 |
| value | CascaderValue[] | - | 值 |
| fieldNames | object | { label: `label`, value: `value`, children: `children` } | 自定义节点 label、value、children 的字段 |
| itemRender | (data?: object) => data.label | (data?: object) => data.label | 单个选项的展示 |
| onChange | (value: CascaderValue[]) => void | - | 值变化时触发的回调函数 |
### 指令式调用
Cascader 支持指令式调用，提供了 `prompt` 方法
```tsx
prompt: (props: Omit<CascaderProps, 'visible' | 'visible' | 'children'>) =>
Promise<CascaderValue[] | null>;
```
`prompt` 方法的返回值是一个 Promise，如果用户点击了确定，从 Promise 中可以解析到 `CascaderValue[]`，而如果用户是触发的取消操作，那么 Promise 中的值是 `null`。你可以通过 `await` 或 `.then()` 来获取到其中的值：
```tsx
const value = await Cascader.prompt({
dataSource: dataSourceConfig,
});
Cascader.prompt({
columns: dataSourceConfig,
}).then((value) => {
// ...
});
```
### 仅 Cascader 支持的属性
| 属性 | 类型 | 默认值 | 说明 |
| :----------- | :------------------------------- | :------- | :--------------------------------------------- |
| visible | boolean | false | 是否展示 |
| title | string | '请选择' | 选择器标题 |
| confirmText | string | '确定' | 确定栏文字 |
| cancelText | string | '取消' | 取消栏文字 |
| maskClosable | boolean | true | 是否点击遮罩层时关闭，需要和 onCancel 一起使用 |
| safeArea | boolean | false | 是否适配安全区域 |
| onConfirm | (value: CascaderValue[]) => void | - | 点击确定时触发的回调函数 |
| onCancel | () => void | - | 点击取消时触发的回调函数 |
### CascaderValue
`string | number`
### CascaderOption
| 属性 | 类型 | 默认值 | 说明 |
| :------- | :--------------- | :----- | :----------- |
| value | CascaderValue | - | 选项值 |
| label | React.ReactNode | - | 选项显示名称 |
| children | CascaderOption[] | - | 子选项 |
## CSS 变量
### Cascader
| 属性 | 默认值 | 说明 |
| :------------------------- | :----------------------------- | :------------------- |
| --header-height | '45px' | 头部高度 |
| --header-font-size | '16px' | 头部文字大小 |
| --header-background | '#f7f7f7' | 头部背景 |
| --header-title-text-color | 'var(--za-color-text)' | 头部标题文字颜色 |
| --header-submit-text-color | 'var(--za-theme-primary)' | 头部提交按钮文字颜色 |
| --header-cancel-text-color | 'var(--za-color-text-caption)' | 头部取消按钮文字颜色 |
### CascaderView
| 属性 | 默认值 | 说明 |
| :------------------------- | :--------------------------------- | :--------------- |
| --background | '#fff' | 弹层背景 |
| --padding | 'var(--za-padding-v-sm)' | 选项内边距 |
| --tab-text-color | 'var(--za-color-text-placeholder)' | 标签文字颜色 |
| --tab-active-text-color | 'var(--za-theme-primary)' | 标签选中文字颜色 |
| --options-height | '300px' | 选项面板高度 |
| --option-font-size | 'var(--za-font-size-sm)' | 选项字体大小 |
| --option-height | '44px' | 选项高度 |
| --option-text-color | 'var(--za-color-text)' | 选项文字颜色 |
| --option-active-text-color | 'var(--za-theme-primary)' | 选项选中文字颜色 |