Silver Formily Vant1.0.1

Appearance

Mobile Preview Open
Open mobile preview

Cascader ​

Cascader 是基于 Vant 官方 Cascader 做的表单封装。

提示

由于 PickerGroup 不支持内嵌 Cascader 组件，没有独立使用的价值，因此暂时没有做xxxPanel的拆分。

基础使用 ​

vue
<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Cascader, Form, FormButtonGroup, FormItem, Submit } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { showDemoResult } from '../shared'
import { cityOptions } from './shared'

const form = createForm({
  values: {
    area: ['330000', '330100', '330106'],
  },
})

async function handleSubmit(values: typeof form.values) {
  await showDemoResult(values)
}
</script>

<template>
  <Form :form="form">
    <Field
      name="area"
      title="所在地区"
      :decorator="[FormItem, { isLink: true }]"
      :component="[Cascader]"
      :data-source="cityOptions"
    />

    <FormButtonGroup>
      <Submit @submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

中国省市区数据 ​

文档站已经安装 @vant/area-data，这里直接使用官方推荐的 useCascaderAreaData() 来生成选项数据。

vue
<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Cascader, Form, FormButtonGroup, FormItem, Submit } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { useCascaderAreaData } from '@vant/area-data'
import { showDemoResult } from '../shared'

const form = createForm({
  values: {
    areaCode: null,
  },
})

const areaOptions = useCascaderAreaData()

async function handleSubmit(values: typeof form.values) {
  await showDemoResult(values)
}
</script>

<template>
  <Form :form="form">
    <Field
      name="areaCode"
      title="省市区"
      :decorator="[FormItem, { isLink: true }]"
      :component="[Cascader]"
      :data-source="areaOptions"
    />

    <FormButtonGroup>
      <Submit @submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

自定义颜色 ​

vue
<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Cascader, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'
import { cityOptions } from './shared'

const form = createForm({
  values: {
    area: ['320000', '320100', '320106'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="area"
        title="自定义颜色"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          Cascader,
          {
            activeColor: '#ee0a24',
          },
        ]"
        :data-source="cityOptions"
      />
    </div>
  </FormProvider>
</template>

异步加载选项 ​

封装层保留了 change 事件，payload 会额外携带当前字段实例 field 和当前已选路径值 currentValue。异步场景里可以直接通过 field.setDataSource(...) 更新当前字段的数据源，不需要额外再维护一份本地 options 状态。

vue
<script setup lang="ts">
import type { DataField } from '@silver-formily/core'
import type { CascaderChangeEvent, CascaderOption } from '@silver-formily/vant'
import { createForm, onFieldInit } from '@silver-formily/core'
import { Cascader, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'
import { closeToast, showLoadingToast } from 'vant'

const asyncChildrenMap: Record<string, CascaderOption[]> = {
  330000: [
    { text: '杭州市', value: '330100' },
    { text: '宁波市', value: '330200' },
  ],
}

function createInitialOptions(): CascaderOption[] {
  return [
    {
      text: '浙江省',
      value: '330000',
      children: [],
    },
  ]
}

function resolveAsyncChildren(value: string | number): CascaderOption[] {
  return (asyncChildrenMap[String(value)] ?? []).map(option => ({ ...option }))
}

const form = createForm({
  effects() {
    onFieldInit('asyncArea', (field: DataField) => {
      field.setDataSource(createInitialOptions())
    })
  },
})

function onChange({ value, field }: CascaderChangeEvent) {
  const currentOptions = Array.isArray(field?.dataSource)
    ? field.dataSource as CascaderOption[]
    : []
  const currentOption = currentOptions[0]

  if (!currentOption || value !== currentOption.value || currentOption.children?.length) {
    return
  }

  showLoadingToast({
    message: '加载中...',
    duration: 0,
    forbidClick: true,
  })

  window.setTimeout(() => {
    const nextOptions = currentOptions.map((option) => {
      if (option.value !== value) {
        return option
      }

      return {
        ...option,
        children: resolveAsyncChildren(value),
      }
    })

    field?.setDataSource(nextOptions)
    closeToast()
  }, 1000)
}
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="asyncArea"
        title="异步加载选项"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          Cascader,
          {
            onChange,
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

自定义字段名 ​

vue
<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Cascader, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'
import { customFieldOptions, fieldNames } from './shared'

const form = createForm({
  values: {
    areaCode: ['330000', '330100'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="areaCode"
        title="自定义字段名"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          Cascader,
          {
            fieldNames,
          },
        ]"
        :data-source="customFieldOptions"
      />
    </div>
  </FormProvider>
</template>

自定义选项上方内容 ​

vue
<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Cascader, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'
import { cityOptions } from './shared'

const form = createForm({
  values: {
    area: null,
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="area"
        title="自定义选项上方内容"
        :decorator="[FormItem, { isLink: true }]"
        :component="[Cascader]"
        :data-source="cityOptions"
      >
        <template #options-top="{ tabIndex }">
          <div class="cascader-level-tip">
            当前为第 {{ tabIndex + 1 }} 级
          </div>
        </template>
      </Field>
    </div>
  </FormProvider>
</template>

<style scoped>
.cascader-level-tip {
  padding: 12px 16px 8px;
  font-size: 12px;
  color: var(--van-text-color-2);
  background: var(--van-gray-1);
}
</style>

自定义标题与选项 ​

vue
<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Cascader, Form, FormItem } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { Tag } from 'vant'
import { cityOptions } from './shared'

const form = createForm({
  values: {
    serviceRegion: ['320000', '320100', '320106'],
  },
})
</script>

<template>
  <Form :form="form">
    <Field
      name="serviceRegion"
      title="服务区域"
      :decorator="[FormItem, { isLink: true }]"
      :component="[
        Cascader,
        {
          activeColor: '#ee0a24',
          closeIcon: 'cross',
        },
      ]"
      :data-source="cityOptions"
    >
      <template #title>
        <div class="demo-cascader-title">
          选择服务片区
        </div>
      </template>

      <template #option="{ option }">
        <div class="demo-cascader-option">
          <span>{{ option.text }}</span>
          <Tag
            plain
            size="medium"
            :type="option.children?.length ? 'primary' : 'success'"
          >
            {{ option.children?.length ? '继续选择' : '最终节点' }}
          </Tag>
        </div>
      </template>
    </Field>
  </Form>
</template>

<style scoped>
.demo-cascader-title {
  padding: 8px 0;
  font-size: 16px;
  font-weight: 600;
}

.demo-cascader-option {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  width: 100%;
}
</style>

API ​

触发区交互状态跟随 Field 的 disabled / readOnly / readPretty，不会透传到内部 Vant Cascader。

补充 Props ​

属性名类型描述默认值
modelValuestring[] | number[] | string | number | -当前值，兼容叶子值输入-
separatorstring字段展示区路径分隔符' / '
displayFormatterFunction自定义展示区文案-
popupPropsCascaderPopupProps传给内部 Popup 的配置-

其余的属性、事件、插槽可以直接参考官方文档Vant Cascader 官方文档

参考createPopup