@mijadesign/nut-mcp 1.0.0-alpha.0

package/docs/docs/components/dentry/picker/index.md

@@ -0,0 +1,621 @@
+---
+order: 16
+demoUrl: 'https://frontend.mishudata.com/mobile/demo/#/dentry/pages/picker/index'
+group:
+    title: 数据录入
+    order: 5
+---
+
+# Picker 选择器 <Badge>2.0.0</Badge>
+
+
+提供多个选项集合供用户选择其中一项。
+
+## 引入
+
+```tsx
+import { Picker } from '@mijadesign/mjui-react-taro';
+```
+
+## 示例代码
+
+### 基础用法
+
+
+```tsx
+import { Cell, Picker, PickerOnChangeCallbackParameter, PickerOption, PickerValue } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo1 = () => {
+  const [visible, setVisible] = useState(false)
+  const [isVisible, setIsVisible] = useState(false)
+  const [isVisible1, setIsVisible1] = useState(false)
+  const [value0, setValue0] = useState<PickerValue[]>([1])
+  const [value, setValue] = useState<PickerValue[]>([2, 1, 1])
+  const [value1, setValue1] = useState<PickerValue[]>(['Wednesday', 'Morning'])
+  const [baseDesc, setBaseDesc] = useState('南京')
+  const [cityCustom, setCityCustom] = useState('浙江省 杭州市 西湖区')
+  const [mutilDesc, setMutilDesc] = useState('周三 上午')
+
+  const options = [
+    [
+      { value: 1, text: '南京市' },
+      { value: 2, text: '无锡市' },
+      { value: 3, text: '海北藏族自治区' },
+      { value: 4, text: '北京市' },
+      { value: 5, text: '连云港市' },
+      { value: 8, text: '大庆市' },
+      { value: 9, text: '绥化市' },
+      { value: 10, text: '潍坊市' },
+      { value: 12, text: '乌鲁木齐市' },
+    ],
+  ]
+  const customCityData = [
+    [
+      {
+        value: 1,
+        text: '江苏省',
+        children: [
+          {
+            value: 1,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 2,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 3,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 4,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 5,
+            text: '西城区',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '西湖区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 6,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+        ],
+      },
+      {
+        value: 2,
+        text: '浙江省',
+        children: [
+          {
+            value: 1,
+            text: '杭州市',
+            children: [
+              { value: 1, text: '西湖区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 2,
+            text: '南京市',
+            children: [
+              { value: 1, text: '西湖区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 3,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '西湖区' },
+            ],
+          },
+          {
+            value: 4,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '雨花台区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '西湖区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+          {
+            value: 5,
+            text: '南京市',
+            children: [
+              { value: 1, text: '雨花台区' },
+              { value: 2, text: '西湖区' },
+              { value: 3, text: '雨花台区' },
+              { value: 4, text: '雨花台区' },
+              { value: 5, text: '雨花台区' },
+            ],
+          },
+        ],
+      },
+    ],
+  ]
+  const options1 = [
+    [
+      {
+        text: '周一',
+        value: 'Monday',
+        children: [
+          { text: '上午', value: 'Morning' },
+          { text: '下午', value: 'Afternoon' },
+          { text: '晚上', value: 'Evening' },
+        ],
+      },
+      {
+        text: '周二',
+        value: 'Tuesday',
+        children: [
+          { text: '上午', value: 'Morning' },
+          { text: '下午', value: 'Afternoon' },
+          { text: '晚上', value: 'Evening' },
+        ],
+      },
+      {
+        text: '周三',
+        value: 'Wednesday',
+        children: [
+          { text: '上午', value: 'Morning' },
+          { text: '下午', value: 'Afternoon' },
+          { text: '晚上', value: 'Evening' },
+        ],
+      },
+      {
+        text: '周四',
+        value: 'Thursday',
+        children: [
+          { text: '上午', value: 'Morning' },
+          { text: '下午', value: 'Afternoon' },
+          { text: '晚上', value: 'Evening' },
+        ],
+      },
+      {
+        text: '周五',
+        value: 'Friday',
+        children: [
+          { text: '上午', value: 'Morning' },
+          { text: '下午', value: 'Afternoon' },
+          { text: '晚上', value: 'Evening' },
+        ],
+      },
+    ],
+  ]
+
+  const changePicker = ({ value, index, selectedOptions }: PickerOnChangeCallbackParameter) => {
+    console.log('changePicker', value, index, selectedOptions)
+  }
+  const confirmPicker = (selectedOptions: PickerOption[], selectedValue: PickerValue[]) => {
+    let description = ''
+    selectedOptions.forEach((option: PickerOption) => {
+      description += ` ${option.text}`
+    })
+    setBaseDesc(description)
+    setValue0(selectedValue)
+  }
+  const setChooseValueCustom = (selectedOptions: PickerOption[], selectedValue: PickerValue[]) => {
+    console.log('onconfirm', selectedOptions, selectedValue)
+    const city = selectedOptions.map((item: PickerOption) => item.text).join(' ')
+    setCityCustom(city)
+    setValue(selectedValue)
+  }
+  const confirmPicker1 = (selectedOptions: PickerOption[], selectedValue: PickerValue[]) => {
+    console.log('confirmPicker', selectedOptions, selectedValue)
+    const description = selectedOptions.map((item: PickerOption) => item.text).join(' ')
+    setMutilDesc(description)
+    setValue1(selectedValue)
+  }
+  return (
+    <Cell.Group>
+      <Cell title="城市" extra={baseDesc} onClick={() => setVisible(!visible)} />
+      <Cell title="时间" extra={mutilDesc} onClick={() => setIsVisible1(!isVisible1)} />
+      <Cell title="多级联动" extra={cityCustom} onClick={() => setIsVisible(!isVisible)} />
+      <Picker
+        title="请选择城市"
+        visible={visible}
+        options={options}
+        onConfirm={confirmPicker}
+        onClose={() => setVisible(false)}
+        value={value0}
+        onChange={changePicker}
+      />
+      <Picker
+        title="请选择"
+        visible={isVisible1}
+        options={options1}
+        onClose={() => setIsVisible1(false)}
+        value={value1}
+        onConfirm={confirmPicker1}
+        onChange={({ value, index, selectedOptions }) => console.log('多级联动', value, index, selectedOptions)}
+      />
+      <Picker
+        title="请选择"
+        visible={isVisible}
+        options={customCityData}
+        value={value}
+        onClose={() => setIsVisible(false)}
+        onConfirm={setChooseValueCustom}
+        onChange={({ value, index, selectedOptions }) => console.log('多级联动', value, index, selectedOptions)}
+      />
+    </Cell.Group>
+  )
+}
+export default Demo1
+
+```
+    
+### 受控
+
+
+```tsx
+import { Cell, Picker, PickerOption, PickerValue } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo3 = () => {
+  const [visible, setVisible] = useState(false)
+  const [baseDesc, setBaseDesc] = useState('')
+  const [value, setValue] = useState<PickerValue[]>([] as PickerValue[])
+  const options = [
+    [
+      { value: 1, text: '南京市' },
+      { value: 2, text: '无锡市' },
+      { value: 3, text: '海北藏族自治区' },
+      { value: 4, text: '北京市' },
+      { value: 5, text: '连云港市' },
+      { value: 8, text: '大庆市' },
+      { value: 9, text: '绥化市' },
+      { value: 10, text: '潍坊市' },
+      { value: 12, text: '乌鲁木齐市' },
+    ],
+  ]
+
+  const changePicker = ({ value, index, selectedOptions }: any) => {
+    console.log('changePicker', value, index, selectedOptions)
+  }
+  const confirmPicker = (selectedOptions: PickerOption[], selectedValue: PickerValue[]) => {
+    setValue(selectedValue)
+    let description = ''
+    selectedOptions.forEach((option: any) => {
+      description += ` ${option.text}`
+    })
+    setBaseDesc(description)
+  }
+  return (
+    <Cell.Group>
+      <Cell title="请选择城市" extra={baseDesc} onClick={() => setVisible(!visible)} />
+      <Picker
+        title="请选择城市"
+        visible={visible}
+        value={value}
+        options={options}
+        onChange={changePicker}
+        onConfirm={confirmPicker}
+        onClose={() => setVisible(false)}
+      />
+    </Cell.Group>
+  )
+}
+export default Demo3
+
+```
+    
+### 平铺展示
+
+通过设置 `threeDimensional` 取消 3D 展示效果，并且通过设置 `duration` 可以控制快速滚动的时长。
+
+
+```tsx
+import { Cell, Picker, PickerOption } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo5 = () => {
+  const [isVisible, setIsVisible] = useState(false)
+  const [tileDesc, settileDesc] = useState('无锡市')
+  const options = [
+    [
+      { value: 1, text: '南京市' },
+      { value: 2, text: '无锡市' },
+      { value: 3, text: '海北藏族自治区' },
+      { value: 4, text: '北京市' },
+      { value: 5, text: '连云港市' },
+      { value: 8, text: '大庆市' },
+      { value: 9, text: '绥化市' },
+      { value: 10, text: '潍坊市' },
+      { value: 12, text: '乌鲁木齐市' },
+    ],
+  ]
+
+  const confirmPicker = (options: PickerOption[]) => {
+    let description = ''
+    options.forEach((option: any) => {
+      description += ` ${option.text}`
+    })
+    settileDesc(description)
+    setIsVisible(false)
+  }
+  return (
+    <Cell.Group>
+      <Cell title="请选择城市" extra={tileDesc} onClick={() => setIsVisible(!isVisible)} />
+      <Picker
+        title="请选择城市"
+        visible={isVisible}
+        options={options}
+        onConfirm={confirmPicker}
+        defaultValue={[2]}
+        threeDimensional={false}
+        duration={1000}
+        onClose={() => setIsVisible(false)}
+      />
+    </Cell.Group>
+  )
+}
+export default Demo5
+
+```
+    
+### 异步获取
+
+
+```tsx
+import { Cell, Picker, PickerOnChangeCallbackParameter, PickerOption, PickerValue } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo7 = () => {
+  const [isVisible, setIsVisible] = useState(false)
+  const [value, setValue] = useState<PickerValue[]>([1])
+  const [asyncDesc, setasyncDesc] = useState('北京')
+  const [asyncData, setAsyncData] = useState([
+    [
+      {
+        value: 1,
+        text: '北京',
+        children: [
+          {
+            value: 1,
+            text: '朝阳区',
+          },
+          {
+            value: 2,
+            text: '海淀区',
+          },
+          {
+            value: 3,
+            text: '大兴区',
+          },
+          {
+            value: 4,
+            text: '东城区',
+          },
+          {
+            value: 5,
+            text: '西城区',
+          },
+          {
+            value: 6,
+            text: '丰台区',
+          },
+        ],
+      },
+      {
+        value: 2,
+        text: '上海',
+        children: [],
+      },
+    ],
+  ])
+  const updateChooseValueCustmer = ({ value, index, selectedOptions }: PickerOnChangeCallbackParameter) => {
+    if (value[0] === 2 && asyncData[0]?.[1].children.length === 0) {
+      console.log('updateChooseValueCustmer', index, value, selectedOptions)
+      setTimeout(() => {
+        asyncData[0][1].children = [
+          {
+            value: 1,
+            text: '黄埔区',
+          },
+          {
+            value: 2,
+            text: '长宁区',
+          },
+          {
+            value: 3,
+            text: '普陀区',
+          },
+          {
+            value: 4,
+            text: '杨浦区',
+          },
+          {
+            value: 5,
+            text: '浦东新区',
+          },
+        ]
+        setAsyncData([...[...asyncData]])
+      }, 0)
+    }
+  }
+  const setAsyncConfirm = (selectedOptions: PickerOption[], selectedValue: PickerValue[]) => {
+    console.log('onconfirm', selectedOptions, selectedValue)
+    const city = selectedOptions.map((item: PickerOption) => item.text).join('-')
+    setasyncDesc(city)
+    setValue(selectedValue)
+  }
+
+  return (
+    <Cell.Group>
+      <Cell title="请选择城市" extra={asyncDesc} onClick={() => setIsVisible(!isVisible)} />
+
+      <Picker
+        title="请选择城市"
+        visible={isVisible}
+        options={asyncData}
+        value={value}
+        onClose={() => setIsVisible(false)}
+        onConfirm={setAsyncConfirm}
+        onChange={updateChooseValueCustmer}
+      />
+    </Cell.Group>
+  )
+}
+export default Demo7
+
+```
+    
+### 自定义主题
+
+
+```tsx
+import { Cell, ConfigProvider, Picker, PickerOption, PickerValue } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo8 = () => {
+  const [visible, setVisible] = useState(false)
+  const [baseDesc, setBaseDesc] = useState('')
+  const options = [
+    [
+      { value: 1, text: '南京市' },
+      { value: 2, text: '无锡市' },
+      { value: 3, text: '海北藏族自治区' },
+      { value: 4, text: '北京市' },
+      { value: 5, text: '连云港市' },
+      { value: 8, text: '大庆市' },
+      { value: 9, text: '绥化市' },
+      { value: 10, text: '潍坊市' },
+      { value: 12, text: '乌鲁木齐市' },
+    ],
+  ]
+
+  const confirmPicker = (selectedOptions: PickerOption[], selectedValue: PickerValue[]) => {
+    console.log('confirmPicker', selectedOptions, selectedValue)
+    let description = ''
+    selectedOptions.forEach((option: PickerOption) => {
+      description += ` ${option?.text}`
+    })
+    setBaseDesc(description)
+  }
+  return (
+    <Cell.Group>
+      <Cell title="请选择城市" extra={baseDesc} onClick={() => setVisible(!visible)} />
+      <ConfigProvider
+        theme={{
+          nutuiPickerItemHeight: '48px',
+          nutuiPickerItemActiveLineBorder: '1px dashed var(--nutui-color-primary)',
+          nutuiPickerItemTextColor: 'var(--nutui-color-primary)',
+        }}
+      >
+        <Picker
+          title="请选择城市"
+          visible={visible}
+          options={options}
+          onConfirm={confirmPicker}
+          onClose={() => setVisible(false)}
+        />
+      </ConfigProvider>
+    </Cell.Group>
+  )
+}
+export default Demo8
+
+```
+    
+## Picker
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| visible | 是否可见 | `boolean` | `false` |
+| title | 设置标题 | `string` | `-` |
+| options | 列表数据 | `Array` | `[]` |
+| value | 选中值，受控 | `Array` | `[]` |
+| defaultValue | 默认选中 | `Array` | `[]` |
+| threeDimensional | 是否开启3D效果 | `boolean` | `true` |
+| duration | 快速滑动时惯性滚动的时长，单位 ms | `string`  \|  `number` | `1000` |
+| popupProps | 透传popup属性 | `object` | `-` |
+| closeOnOverlayClick | 是否点击遮罩关闭 | `boolean` | `true` |
+| onConfirm | 点击确认按钮时候回调 | `(options, value) => void` | `-` |
+| onChange | 每一列值变更时调用 | `(options, value) => void` | `-` |
+| onCancel | 点击取消按钮时触发 | `() => void` | `-` |
+| onClose | 确定和取消时，都触发 | `(options, value) => void` | `-` |
+| afterClose | 联动时，关闭时回调 | `(options, value) => void` | `-` |
+
+### options 数据结构
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| text | 选项的文字内容 | `string`  \|  `number` | `-` |
+| value | 选项对应的值，且唯一 | `string`  \|  `number` | `-` |
+| children | 用于级联选项 | `Array` | `-` |
+
+## 主题定制
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](#/zh-CN/component/configprovider)。
+
+| 名称 | 说明 | 默认值 |
+| --- | --- | --- |
+| \--nutui-picker-item-active-font-weight | 面板当前选中字体权重 | `$font-weight-bold` |
+| \--nutui-picker-item-active-line-border | 面板当前选中的border值 | `0.5px solid $color-border` |
+| \--nutui-picker-item-height | 面板每一条数据高度 | `48px` |
+| \--nutui-picker-item-text-color | 面板每一条数据的字色 | `$color-title` |
+| \--nutui-picker-item-text-font-size | 面板每条数据字号 | `$font-size-base` |
+| \--nutui-picker-list-height | 面板高度 | `calc(36vh - 64px)` |
+| \--nutui-picker-title-cancel-color | 取消文案的色值 | `$color-text` |
+| \--nutui-picker-title-cancel-font-size | 取消字号 | `$font-size-2` |
+| \--nutui-picker-title-ok-color | 確認文案的色值 | `$color-primary` |
+| \--nutui-picker-title-ok-font-size | 确认字号 | `$font-size-2` |