Silver Formily Antd Mobile0.0.0-alpha.1

Appearance

Mobile Preview Open
Open mobile preview

CalendarPicker ​

CalendarPicker 是对 antd-mobile 日历选择器的 Formily 适配，支持单日和日期范围。表单值按 format 序列化为字符串，默认格式为 YYYY-MM-DD。

提示

关于 CalendarPicker 组件的右侧箭头相关逻辑请参考 FormItem 中的箭头与清除按钮

基础使用 ​

tsx
import { CalendarPicker, FormButtonGroup, FormItem, Submit } from '@silver-formily/antd-mobile'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'

const form = createForm({
  initialValues: {
    birthday: '2026-10-15',
  },
})

function onSubmit(values: unknown) {
  return Prompts.alert(JSON.stringify(values, null, 2))
}

export default function CalendarPickerBasic() {
  return (
    <FormProvider form={form}>
      <Field
        name="birthday"
        title="生日"
        decorator={[FormItem]}
        component={[CalendarPicker]}
      />
      <FormButtonGroup>
        <Submit onSubmit={onSubmit}>提交</Submit>
      </FormButtonGroup>
    </FormProvider>
  )
}

日期范围 ​

设置 selectionMode="range" 选择起止日期。字段值为两个日期字符串组成的数组，展示时以 ~ 分隔。

tsx
import { CalendarPicker, FormButtonGroup, FormItem, Submit } from '@silver-formily/antd-mobile'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'

const form = createForm({
  initialValues: {
    stay: ['2026-10-15', '2026-10-18'],
  },
})

function onSubmit(values: unknown) {
  return Prompts.alert(JSON.stringify(values, null, 2))
}

export default function CalendarPickerRange() {
  return (
    <FormProvider form={form}>
      <Field
        name="stay"
        title="入住日期"
        decorator={[FormItem, { clearable: true }]}
        component={[CalendarPicker, { selectionMode: 'range', placeholder: '请选择入住和离店日期' }]}
      />
      <FormButtonGroup>
        <Submit onSubmit={onSubmit}>提交</Submit>
      </FormButtonGroup>
    </FormProvider>
  )
}

格式与日期限制 ​

displayRender(value, props) 自定义编辑态和阅读态的展示内容，返回 ReactNode，不影响表单值。与其他 picker 一致，format 用于日期值的序列化和解析，也决定默认展示格式。min、max 接收原生 Date，shouldDisableDate 可禁用指定日期；本例限制为 2026 年 10 月的工作日。

tsx
import type { ICalendarPickerProps } from '@silver-formily/antd-mobile'
import { CalendarPicker, FormButtonGroup, FormItem, Submit } from '@silver-formily/antd-mobile'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'

const form = createForm({
  initialValues: {
    appointment: '2026/10/15',
  },
})

function onSubmit(values: unknown) {
  return Prompts.alert(JSON.stringify(values, null, 2))
}

export default function CalendarPickerOptions() {
  return (
    <FormProvider form={form}>
      <Field
        name="appointment"
        title="预约日期"
        decorator={[FormItem]}
        component={[CalendarPicker, {
          format: 'YYYY/MM/DD',
          displayRender: (value: ICalendarPickerProps['value']) => (
            <span>
              预约：
              {String(value ?? '')}
            </span>
          ),
          min: new Date(2026, 9, 1),
          max: new Date(2026, 9, 31),
          weekStartsOn: 'Monday',
          shouldDisableDate: (date: Date) => date.getDay() === 0 || date.getDay() === 6,
        }]}
      />
      <FormButtonGroup>
        <Submit onSubmit={onSubmit}>提交</Submit>
      </FormButtonGroup>
    </FormProvider>
  )
}

自定义展示 ​

displayRender(value, props) 同时用于编辑态和阅读态。本例将日期范围展示为 2026/10/15 至 2026/10/18，提交值仍为两个 YYYY-MM-DD 字符串组成的数组。返回 undefined 时使用对应状态的占位内容。

tsx
import type { ICalendarPickerProps } from '@silver-formily/antd-mobile'
import { CalendarPicker, FormButtonGroup, FormItem, Submit } from '@silver-formily/antd-mobile'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'

const form = createForm({
  initialValues: {
    editable: ['2026-10-15', '2026-10-18'],
    preview: ['2026-10-15', '2026-10-18'],
  },
})

const displayRender: ICalendarPickerProps['displayRender'] = (value) => {
  if (!value)
    return undefined
  const text = Array.isArray(value) ? value.map(date => String(date).replaceAll('-', '/')).join(' 至 ') : String(value ?? '').replaceAll('-', '/')
  return <span style={{ color: 'var(--adm-color-primary)' }}>{text}</span>
}

function onSubmit(values: unknown) {
  return Prompts.alert(JSON.stringify(values, null, 2))
}

export default function CalendarPickerDisplay() {
  return (
    <FormProvider form={form}>
      <Field
        name="editable"
        title="编辑态"
        decorator={[FormItem]}
        component={[CalendarPicker, { selectionMode: 'range', displayRender }]}
      />
      <Field
        name="preview"
        title="阅读态"
        pattern="readPretty"
        decorator={[FormItem]}
        component={[CalendarPicker, { selectionMode: 'range', displayRender }]}
      />
      <FormButtonGroup>
        <Submit onSubmit={onSubmit}>提交</Submit>
      </FormButtonGroup>
    </FormProvider>
  )
}

字段状态 ​

禁用态不可打开弹层；只读态可打开查看，但不能修改或提交选择；阅读态仅展示格式化后的日期。空值阅读态使用 PreviewText 的占位配置。

tsx
import { CalendarPicker, FormButtonGroup, FormItem, Submit } from '@silver-formily/antd-mobile'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'

const form = createForm({
  initialValues: {
    disabled: '2026-10-15',
    readOnly: '2026-10-15',
    readPretty: ['2026-10-15', '2026-10-18'],
  },
})

function onSubmit(values: unknown) {
  return Prompts.alert(JSON.stringify(values, null, 2))
}

export default function CalendarPickerStatus() {
  return (
    <FormProvider form={form}>
      <Field name="disabled" title="禁用" pattern="disabled" decorator={[FormItem]} component={[CalendarPicker]} />
      <Field name="readOnly" title="只读" pattern="readOnly" decorator={[FormItem]} component={[CalendarPicker]} />
      <Field name="readPretty" title="阅读态" pattern="readPretty" decorator={[FormItem]} component={[CalendarPicker, { selectionMode: 'range' }]} />
      <FormButtonGroup>
        <Submit onSubmit={onSubmit}>提交</Submit>
      </FormButtonGroup>
    </FormProvider>
  )
}

API ​

属性 ​

属性名类型描述默认值
selectionMode'single' | 'range'单日或日期范围选择；封装默认启用单日选择'single'
formatstring | ((value: Dayjs) => string)日期值的序列化格式及默认展示格式；字符串格式也用于解析输入值'YYYY-MM-DD'
displayRender(value: ICalendarPickerProps['value'], props: ICalendarPickerProps) => ReactNode自定义编辑态和阅读态展示，不影响提交值-
placeholderReactNode空值占位内容'请选择'

透传上游配置，参见 CalendarPicker 官方文档。