SDatePicker <s-date-picker>

用于选择单个日期或日期范围的日历。 SDatePicker 是 Shopify Polaris <s-date-picker> web component 的带类型 Vue 3 wrapper。

import { SDatePicker } from 'polaris-vue-elements'

最佳实践

• 从合理的日期开始。 预填 value，让商家能更快完成选择。
• 为常用选择提供快捷方式。 “今天”“最近 7 天”或“本月”等预设可以让商家无需在日历中逐页点击。
• 对开始和结束日期使用 type="range"。 范围选择适合报表、数据分析以及其他基于时间段的筛选。
• 屏蔽不适用的日期。 使用 allow 和 disallow，使商家无法选择对你的用例无效的日期。
• 在选择器周围留出空间。 为其留出足够的空间，避免妨碍屏幕键盘或其他交互元素。
• 为较远的日期做好规划。 跨越几年后逐月翻页会变得繁琐，因此对于大约 5–10 年范围之外的日期，请提供预设或允许商家直接输入年份。

<SDatePicker type="range" />

参阅 Shopify 关于 <s-date-picker> 的最佳实践（英文）以获取完整指南。

示例

Selected: (none)

<script setup>
import { ref } from 'vue'
import { SDatePicker } from 'polaris-vue-elements'

const value = ref('')
</script>

<template>
  <SDatePicker type="single" v-model="value" />
  <p>Selected: {{ value }}</p>
</template>

v-model

<SDatePicker> 上的 v-model 绑定到 value property，并监听 input DOM 事件。

<SDatePicker v-model="value" />

等价于：

<SDatePicker :value="value" @input="value = $event.target.value" />

Props

Prop	类型	说明
allow	string	以逗号分隔的列表指定可以选择的日期。空字符串（默认）允许所有日期。 格式：* - YYYY-MM-DD：单个日期 - YYYY-MM：整个月份 - YYYY：整年 - start--end：日期范围（包含两端，省略 start/end 时不受限制） 示例：* - 2024-02--2025：从 2024 年 2 月到 2025 年底 - 2024-05-09, 2024-05-11：仅 2024 年 5 月 9 日和 11 日
allowDays	string	以逗号分隔的列表指定可以选择的星期几。进一步限制 allow 和 disallow 中的日期。空字符串（默认）不起作用。 有效值*：sunday、monday、tuesday、wednesday、thursday、friday、saturday 示例：* saturday, sunday（仅周末）
defaultValue	string	组件首次渲染时初始选中的日期。空字符串表示初始时未选择日期。 - 当 type 设置为 "single" 时，为 YYYY-MM-DD 格式的单个日期 - 当 type 设置为 "range" 时，为 YYYY-MM-DD--YYYY-MM-DD 格式的日期范围（包含首尾）
defaultView	string	默认显示的月份，格式为 YYYY-MM。在通过用户交互或以编程方式设置 view 回调之前使用。默认为用户所在区域的当前月份。
disallow	string	以逗号分隔的列表指定不可选择的日期。这些日期会从 allow 指定的日期中排除。空字符串（默认）不起作用。 格式：* - YYYY-MM-DD：单个日期 - YYYY-MM：整个月份 - YYYY：整年 - start--end：日期范围（包含两端，省略 start/end 时不受限制） 示例：* - --2024-02：2024 年 2 月之前的所有日期 - 2024-05-09, 2024-05-11：2024 年 5 月 9 日和 11 日
disallowDays	string	以逗号分隔的列表指定不可选择的星期几。从 allowDays 中排除这些天，并与 allow 和 disallow 取交集。空字符串（默认）不起作用。 有效值*：sunday、monday、tuesday、wednesday、thursday、friday、saturday 示例：* saturday, sunday（不含周末）
name	string	字段的标识符，在最近的外层表单内唯一。
type	"single" | "range"	允许的日期选择类型。 - single：选择单个日期 - range：选择日期范围
value	string	当前选中的日期。空字符串表示未选择日期。 - 当 type 设置为 "single" 时，为 YYYY-MM-DD 格式的单个日期 - 当 type 设置为 "range" 时，为 YYYY-MM-DD--YYYY-MM-DD 格式的日期范围（包含首尾）
view	string	当前显示的月份，格式为 YYYY-MM。更改时会触发 viewchange 回调。默认为 defaultView。
visibleMonths	"auto" | "1" | "2"	控制显示的月份数量。 - 'auto'：由上下文决定。目前渲染单个月份，与 '1' 相同。 - '1'：一次渲染一个月份。 - '2'：并排渲染两个连续的月份。

Events

Event	类型
blur	FocusEvent
change	Event
focus	FocusEvent
input	Event
viewchange	CustomEvent

在 <SDatePicker> 上使用 @blur 形式的监听器来监听这些事件。