nutui-uniapp

Appearance

Picker ​

介绍 ​

提供多个选项集合供用户选择其中一项，通常与弹出层组件配合使用。

基础用法 ​

html
<template>
  <nut-picker :columns="columns"
              title="城市选择"
              @change="onChange"
              @confirm="onConfirm"></nut-picker>
</template>
typescript
import type { PickerBaseEvent, PickerChangeEvent } from 'nutui-uniapp'

const columns = ref([
  { text: '南京市', value: 'NanJing' },
  { text: '无锡市', value: 'WuXi' },
  { text: '海北藏族自治区', value: 'ZangZu' },
  { text: '北京市', value: 'BeiJing' },
  { text: '连云港市', value: 'LianYunGang' },
  { text: '浙江市', value: 'ZheJiang' },
  { text: '江苏市', value: 'JiangSu' }
])

function onChange({ columnIndex, selectedValue, selectedOptions }: PickerChangeEvent) {
  console.log(columnIndex, selectedValue, selectedOptions)
}

function onConfirm({ selectedValue, selectedOptions }: PickerBaseEvent) {
  console.log(selectedValue, selectedOptions)
}

搭配 Popup 使用 ​

Picker 通常作为用于辅助表单填写，可以搭配 Popup 实现效果。

html
<template>
  <nut-cell title="城市选择" :desc="popupDesc" @click="show = true"></nut-cell>

  <nut-popup v-model:visible="show" position="bottom" safe-area-inset-bottom>
    <nut-picker v-model="popupValue"
                :columns="columns"
                title="城市选择"
                @confirm="onConfirm"
                @cancel="show = false">
      <nut-button block type="primary">
        永远有效
      </nut-button>
    </nut-picker>
  </nut-popup>
</template>
typescript
import type { PickerBaseEvent } from 'nutui-uniapp'

const show = ref<boolean>(false)
const popupDesc = ref<string>('')
const popupValue = ref<string[]>([])

const columns = ref([
  { text: '南京市', value: 'NanJing' },
  { text: '无锡市', value: 'WuXi' },
  { text: '海北藏族自治区', value: 'ZangZu' },
  { text: '北京市', value: 'BeiJing' },
  { text: '连云港市', value: 'LianYunGang' },
  { text: '浙江市', value: 'ZheJiang' },
  { text: '江苏市', value: 'JiangSu' }
])

function onConfirm({ selectedValue, selectedOptions }: PickerBaseEvent) {
  console.log(selectedValue, selectedOptions)

  popupDesc.value = selectedOptions.map(item => item.text).join(',')
  show.value = false
}

默认选中项 ​

通过设置 modelValue 实现默认选中项，modelValue 是一个包含每项配置 value 值的数组。

html
<template>
  <nut-picker v-model="selectedValue"
              :columns="columns"
              title="城市选择"
              @confirm="onConfirm"></nut-picker>
</template>
typescript
const selectedValue = ref<string[]>(['ZheJiang'])

const columns = ref([
  { text: '南京市', value: 'NanJing' },
  { text: '无锡市', value: 'WuXi' },
  { text: '海北藏族自治区', value: 'ZangZu' },
  { text: '北京市', value: 'BeiJing' },
  { text: '连云港市', value: 'LianYunGang' },
  { text: '浙江市', value: 'ZheJiang' },
  { text: '江苏市', value: 'JiangSu' }
])

3D效果 ​

属性 three-dimensional 可开启 3D 滚动效果。

html
<template>
  <nut-picker :columns="columns"
              title="城市选择"
              three-dimensional
              @change="onChange"
              @confirm="onConfirm"></nut-picker>
</template>

多列展示 ​

columns 属性可以通过二维数组的形式配置多列选择。

html
<template>
  <nut-picker v-model="selectedValue"
              :columns="multipleColumns"
              title="城市选择"
              @confirm="onConfirm"></nut-picker>
</template>
typescript
const selectedValue = ref<string[]>(['Wednesday', 'Afternoon'])

const multipleColumns = ref([
  [
    { text: '周一', value: 'Monday' },
    { text: '周二', value: 'Tuesday' },
    { text: '周三', value: 'Wednesday' },
    { text: '周四', value: 'Thursday' },
    { text: '周五', value: 'Friday' }
  ],
  [
    { text: '上午', value: 'Morning' },
    { text: '下午', value: 'Afternoon' },
    { text: '晚上', value: 'Evening' }
  ]
])

多级联动 ​

使用 columns 属性的 children 字段可以实现选项级联的效果。

html
<template>
  <nut-picker v-model="selectedCascader"
              :columns="cascaderColumns"
              title="城市选择"
              @confirm="onConfirm"></nut-picker>
</template>
typescript
const selectedCascader = ref<string[]>(['FuJian', 'FuZhou', 'TaiJiang'])

const cascaderColumns = ref([
  {
    text: '浙江',
    value: 'ZheJiang',
    children: [
      {
        text: '杭州',
        value: 'HangZhou',
        children: [
          { text: '西湖区', value: 'XiHu' },
          { text: '余杭区', value: 'YuHang' }
        ]
      },
      {
        text: '温州',
        value: 'WenZhou',
        children: [
          { text: '鹿城区', value: 'LuCheng' },
          { text: '瓯海区', value: 'OuHai' }
        ]
      }
    ]
  },
  {
    text: '福建',
    value: 'FuJian',
    children: [
      {
        text: '福州',
        value: 'FuZhou',
        children: [
          { text: '鼓楼区', value: 'GuLou' },
          { text: '台江区', value: 'TaiJiang' }
        ]
      },
      {
        text: '厦门',
        value: 'XiaMen',
        children: [
          { text: '思明区', value: 'SiMing' },
          { text: '海沧区', value: 'HaiCang' }
        ]
      }
    ]
  }
])

自定义字段名 ​

自 0.3.0 开始可以使用 field-names 属性自定义 columns 中数据的格式。

html
<template>
  <nut-picker :columns="customColumns"
              title="城市选择"
              :field-names="fieldNames"
              @confirm="onConfirm" />
</template>
typescript
const customColumns = ref([
  {
    name: '浙江',
    code: 'ZheJiang',
    list: [
      {
        name: '杭州',
        code: 'HangZhou',
        list: [
          { name: '西湖', code: 'XiHu' },
          { name: '余杭', code: 'YuHang' }
        ]
      },
      {
        name: '温州',
        code: 'WenZhou',
        list: [
          { name: '鹿城区', code: 'LuCheng' },
          { name: '瓯海区', code: 'OuHai' }
        ]
      }
    ]
  }
])

const fieldNames = ref({
  text: 'name',
  value: 'code',
  children: 'list'
})

API ​

Props ​

参数说明类型默认值
v-model选中项(string | number)[][]
columns对象数组，配置每一列显示的数据(PickerOption | PickerOption[])[][]
show-toolbar是否显示顶部导航booleantrue
title设置标题string-
ok-text确定按钮文案string确定
cancel-text取消按钮文案string取消
three-dimensional是否开启3D效果booleanfalse
swipe-duration惯性滚动时长number \ string1000
visible-option-num可见的选项个数number \ string7
option-height选项高度number \ string36
field-names 0.3.0自定义 columns 中的字段object{ text: 'text', value: 'value', children: 'children', className: 'className' }

Events ​

事件名说明回调参数
change选项发生改变时触发{ columnIndex, selectedValue, selectedOptions }
confirm点击确定按钮时触发{ selectedValue, selectedOptions }
cancel点击取消按钮时触发{ selectedValue, selectedOptions }

Slots ​

名称说明
default自定义滑动数据底部区域
top自定义滑动数据顶部区域

PickerOption 数据结构 ​

键名说明类型默认值
text选项的文字内容number \ string-
value选项对应的值，且唯一number \ string-
children用于级联选项PickerOption[]-
className添加额外的类名string-

主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值
--nut-picker-cancel-color#808080
--nut-picker-ok-colorvar(--nut-primary-color)
--nut-picker-bar-cancel-font-size14px
--nut-picker-bar-ok-font-size14px
--nut-picker-bar-button-padding0 15px
--nut-picker-bar-title-font-size16px
--nut-picker-bar-title-colorvar(--nut-title-color)
--nut-picker-bar-title-font-weightnormal
--nut-picker-item-height36px
--nut-picker-item-text-colorvar(--nut-title-color)
--nut-picker-item-text-font-size14px
--nut-picker-item-active-line-border1px solid #d8d8d8

MIT Licensed

版权所有 © 2023 年-至今 yang1206 贡献者