amp-date-picker

描述

提供一个用于选择日期的微件。日期选择器可以呈现为相对于输入字段的覆盖层，也可以呈现为静态日历微件。

必需的脚本

<script async custom-element="amp-date-picker" src="https://cdn.ampproject.org/v0/amp-date-picker-0.1.js"></script>

支持的布局

填充固定固定高度弹性项目固有无显示响应式

示例

amp-date-picker 酒店

用法

amp-date-picker 在页面上呈现一个日历，用户可以从中选择日期。

在此示例中，我们显示一个固定高度的静态日历，用户可以在其中选择一个日期

<amp-date-picker layout="fixed-height" height="360"> </amp-date-picker>

在此示例中，日历显示为特定表单字段的覆盖层

<form method="post" action-xhr="/form/echo-json/post" target="_blank">
  <amp-date-picker
    mode="overlay"
    layout="container"
    input-selector="[name=deliverydate]"
  >
    <label for="deliverydate">Deliver Date:</label>
    <input type="text" name="deliverydate" />
  </amp-date-picker>
</form>

显示模式

amp-date-picker 提供两种模式来呈现日期选择器：静态（默认）或覆盖。

静态模式

通过指定 mode="static"，amp-date-picker 将呈现静态日历视图。这是默认显示模式；如果未指定模式，则会呈现静态日历。

对于静态日期选择器，您必须指定一个大小定义的布局，可以是以下之一：fixed、fixed-height、responsive、fill 或 flex-item。

当在 <form> 中呈现 static amp-date-picker 时，如果没有使用 *input-selector 指定的输入，则 amp-date-picker 会创建隐藏的输入元素（例如，<input type="hidden" …）。amp-date-picker 将元素命名为 date 或 start-date 和 end-date；如果这些名称已在表单中使用，则 amp-date-picker 会尝试使用 <amp-date-picker> 的 id 来命名输入字段。

此示例演示了如何在表单中使用静态日期选择器，用户可以在日历中选择日期范围。由于 amp-date-picker 中未定义 *input-selector 属性，因此会自动生成隐藏的输入字段。

<form method="post" action-xhr="/form-post" target="_blank">
  <fieldset>
    <label>
      <span>Your name</span>
      <input type="text" name="name" id="name" required />
    </label>
    <label for="date">Your date</label>
    <amp-date-picker
      type="range"
      mode="static"
      id="date"
      layout="fixed-height"
      height="360"
    >
      <!-- automatically generates hidden input fields:
    <input type="hidden" name="start-date">
    <input type="hidden" name="end-date"> -->
    </amp-date-picker>
    <input type="submit" value="Subscribe" />
  </fieldset>
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for choosing {{start-date}} and {{end-date}}.
    </template>
  </div>
</form>

覆盖模式

通过指定 mode="overlay"，当用户单击、聚焦或按下与 amp-date-picker 连接的输入字段中的向下箭头时，日历会显示。日历覆盖层会相对于 <amp-date-picker> 标记定位自身。

对于覆盖日期选择器，您必须指定 layout="container" 并包含它将呈现的输入字段。

此示例演示了如何在表单中使用覆盖日期选择器，用户可以在其中选择日期。日期选择器通过 input-selector 属性连接到特定的输入字段。

<form method="post" action-xhr="/form-post" target="_blank">
  <input type="text" name="name" placeholder="Your Name" required />
  <amp-date-picker
    type="single"
    mode="overlay"
    layout="container"
    input-selector="[name=date]"
  >
    <input type="text" name="date" placeholder="Your Date" />
  </amp-date-picker>
  <input type="submit" value="Subscribe" />
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for choosing {{date}}.
    </template>
  </div>
</form>

在触摸设备上，覆盖模式下的 amp-date-picker 会自动向其 <input> 元素添加 readonly 属性。这可以防止设备的屏幕键盘不必要地打开。要选择退出此行为，请将 touch-keyboard-editable 属性添加到 <amp-date-picker> 元素。

选择类型

amp-date-picker 提供两种类型的日期供选择

single：在日期选择器中选择单个日期。
range：在日期选择器中选择日期范围。

`type="single"`

通过指定 type="single"，日期选择器会附加到单个输入，并且用户可以选择单个日期。这是默认的选择类型。

<amp-date-picker type="single" layout="fixed-height" height="360">
</amp-date-picker>

`type="range"`

通过指定 type="range"，日期选择器会附加到两个输入，并且用户可以选择具有开始日期和结束日期的日期范围。

<amp-date-picker type="range" layout="fixed-height" height="360">
</amp-date-picker>

日期格式

amp-date-picker 属性接受 ISO 8601 和 RFC 5545 RRULE 格式的日期。

ISO 8601 将日期格式化为 YYYY-MM-DD，并且是电子系统之间共享日期的标准。例如，ISO 8601 将 2018 年 2 月 28 日的日期格式化为 2018-02-28。

RFC 5545 重复规则 (RRULE) 标准化了用于指定重复日期的格式。例如，RFC 5545 将万圣节格式化为 RRULE:FREQ=YEARLY;BYMONTH=10;BYMONTHDAY=31。也可以使用更复杂的日期，例如美国的感恩节，该节日在每年 11 月的第四个星期四：RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=+4TH。该 API 不容易记忆，但网上有各种RRULE 生成器可用。

属性

mode

指定如何呈现日期选择器。允许的值为

static（默认）：日期选择器呈现为交互式日历视图。
overlay：在用户与 <amp-date-picker> 中嵌套的所需输入字段交互之前，不会呈现日期选择器日历视图。

type

指定日期选择器的选择类型。允许的值为

single（默认）：用户可以选择单个日期。
range：用户可以选择日期范围。

input-selector

单日历选择器输入的查询选择器。如果省略此项，日期选择器会自动生成一个隐藏的输入字段，并使用日期选择器的 id 为其分配一个名称 date 或 ${id}-date。如果其中任何一个与表单中的现有元素冲突，则会发出错误。

当 amp-date-picker 加载时，输入元素的值将用于显示最初选择的日期。

通过 src 属性指定 date 属性以动态设置初始日期。

<amp-date-picker
  type="single"
  mode="overlay"
  layout="container"
  input-selector="[name=deliverydate]"
>
  <input type="text" name="deliverydate" placeholder="Delivery Date" />
</amp-date-picker>

start-input-selector

日期范围选择器的开始日期输入的查询选择器。如果省略此项，日期选择器会自动生成一个隐藏的输入字段，并使用日期选择器的 id 为其分配一个名称 start-date 或 ${id}-start-date。如果其中任何一个与表单中的现有元素冲突，则会发出错误。

当 amp-date-picker 加载时，输入元素的值将用于显示最初选择的开始日期。

通过 src 属性指定 startDate 属性以动态设置初始结束日期。

<input id="a2" />
<input id="b2" />
<amp-date-picker
  type="range"
  start-input-selector="#a2"
  end-input-selector="#b2"
  layout="fixed-height"
  height="360"
>
</amp-date-picker>

end-input-selector

日期范围选择器的结束日期输入的查询选择器。如果省略此项，日期选择器会自动生成一个隐藏的输入字段，并使用日期选择器的 id 为其分配一个名称 end-date 或 ${id}-end-date。如果其中任何一个与表单中的现有元素冲突，则会发出错误。

当 amp-date-picker 加载时，输入元素的值将用于显示最初选择的结束日期。

通过 src 属性指定 endDate 属性以动态设置初始结束日期。

<input id="a2" />
<input id="b2" />
<amp-date-picker
  type="range"
  start-input-selector="#a2"
  end-input-selector="#b2"
  layout="fixed-height"
  height="360"
>
</amp-date-picker>

min

用户可以选择的最早日期。此日期必须格式化为 ISO 8601 日期。如果不存在 min 属性，则当前日期将为最小日期。

用户手势操作后，可以使用 amp-bind 更新 min 属性。

max

用户可以选择的最晚日期。此日期必须格式化为 ISO 8601 日期。如果不存在 max 属性，则日期选择器将没有最大日期。

用户手势操作后，可以使用 amp-bind 更新 max 属性。

month-format

用于在日历视图中显示月份的格式。默认格式为："MMMM YYYY"。

format

用于在输入框中显示和解析日期的格式。默认格式为 "YYYY-MM-DD"。

week-day-format

用于在日历视图中显示星期几的格式。如果不存在 week-day-format，则星期几会显示为星期几的第一个字符。

<amp-date-picker
  type="single"
  mode="overlay"
  layout="container"
  format="MM/DD/YYYY"
  week-day-format="ddd"
  input-selector="[name=date]"
>
  <input type="text" name="date" placeholder="Your Date" />
</amp-date-picker>

locale

用于呈现日历视图的语言环境。默认语言环境为 "en"。

maximum-nights

用户在日期范围内的选择可能不能超过的夜数。默认值为 "0"。值为 "0" 允许用户选择无限数量的夜晚。

minimum-nights

用户必须在日期范围内选择的夜数。默认值为 "1"。值为 "0" 允许用户为开始日期和结束日期选择相同的日期。

number-of-months

日历视图中一次显示的月份数。默认值为 "1"。

first-day-of-week

指定一周的第一天（0-6）。默认值为 "0"（星期日）。

blocked

一个以空格分隔的 ISO 8601 日期或 RFC 5545 RRULE 重复日期列表，用于阻止用户在日历上选择这些日期。

highlighted

一个以空格分隔的 ISO 8601 日期或 RFC 5545 RRULE 重复日期列表，用于特别突出显示，以引起用户的注意。默认样式是在日期上显示一个蓝色圆点。

day-size

日历视图表格中日期单元格的大小，单位为 px。默认值为 39。

.amp-date-picker-resize-bug .DayPicker_transitionContainer {
  min-height: 354px; /* 354px is the default. You must update it. */
}

allow-blocked-end-date

如果存在此属性，则允许用户在选择的开始日期之后的第一个被阻止日期上选择结束日期。默认情况下，此属性不存在。

allow-blocked-ranges

如果存在此属性，则允许用户选择包含被阻止日期的范围。默认情况下，此属性不存在。

src

如果存在此属性，amp-date-picker 会请求 JSON 数据以动态填充某些属性，以及将日期列表与模板 id 匹配，以便在日历中呈现日期。

如果您的日历数据是为用户个性化的或经常更新，则这些值应在 src JSON 响应中指定，而不是在 amp-date-picker 元素上使用相应的属性。

下表列出了您可以在 JSON 数据中指定的属性

`src` 属性	描述
`blocked`	一个 ISO 8601 单个日期或 RFC 5545 RRULE 重复日期数组，在日历视图中呈现为被阻止状态。用户无法选择这些日期。
`日期`	指定最初选择的日期。在 `type="range"` 的日期选择器中，此属性无效。为了防止覆盖用户的输入，如果用户已经选择了日期，则此值无效。
`结束日期`	指定最初选择的结束日期。在 `type="single"` 的日期选择器中，此属性无效。为了防止覆盖用户的输入，如果用户已经选择了结束日期，则此值无效。
`highlighted`	一个 ISO 8601 单个日期或 RFC 5545 RRULE 重复日期数组，在日历视图中呈现为突出显示状态。
`开始日期`	为 `type="range"` 的日期选择器指定最初选择的开始日期。在 `type="single"` 的日期选择器中，此属性无效。为了防止覆盖用户的输入，如果用户已经选择了开始日期，则此值无效。
`模板`	模板属性是一个 “模板定义对象” 数组。这些对象具有 `id` 属性和 `dates` 属性。

用户操作后，可以使用 amp-bind 更新 src 属性。

模板定义对象

dates 属性是一个 ISO 8601 单个日期或 RFC 5545 RRULE 重复日期数组。id 属性指定一个模板的 id，日期选择器可以使用该模板在日历视图中呈现指定的日期。

{
  "id": "my-template-id",
  "dates": [
    "2018-01-02",
    "FREQ=WEEKLY;DTSTART=20180101T000000Z;COUNT=52;WKST=SU;BYDAY=TU"
  ]
}

如果在模板定义对象中未指定 dates 属性，则具有给定 id 的模板将用作默认模板来呈现任何未明确指定模板的日期。

{"id": "my-default-template-id"}

示例：通过 src 属性指定属性

{
  "blocked": ["2018-02-14"],
  "highlighted": ["2018-02-15"],
  "templates": [
    {
      "id": "my-template-id",
      "dates": ["2018-01-01"]
    },
    {
      "id": "my-second-template-id",
      "dates": [
        "2018-01-02",
        "FREQ=WEEKLY;DTSTART=20180101T000000Z;COUNT=52;WKST=SU;BYDAY=TU"
      ]
    },
    {
      "id": "my-default-template-id"
    }
  ],
  "startDate": "2018-01-01",
  "endDate": "2018-02-02",
  "date": "2018-02-03"
}

示例：使用 src 属性的标记

<amp-date-picker
  src="https://www.example.com/date-data.json"
  layout="fixed-height"
  height="360"
>
  <template type="amp-mustache" date-template id="my-template-id">⚡️</template>
  <template type="amp-mustache" date-template id="my-second-template-id"
    >🌮</template
  >
  <template type="amp-mustache" date-template id="my-default-template-id"
    >{{D}}</template
  >
</amp-date-picker>

fullscreen

渲染选择器以填充其可用空间，例如在全屏灯箱中。这与 layout="fill" 配合使用效果最佳。

<input on="tap:lightbox.open" placeholder="Start" id="start" />
<input on="tap:lightbox.open" placeholder="End" id="end" />
<button on="tap:dp.clear">Clear</button>
<amp-lightbox id="lightbox" layout="nodisplay">
  <amp-date-picker
    id="date-picker"
    layout="fill"
    fullscreen
    type="range"
    number-of-months="12"
    start-input-selector="#start"
    end-input-selector="#end"
    on="
      activate: lightbox.open;
      deactivate: lightbox.close"
  ></amp-date-picker>
</amp-lightbox>

open-after-select

如果存在此属性，则在用户选择一个或多个日期后，保持日期选择器覆盖层打开。默认情况下，此属性不存在。

open-after-clear

如果存在此属性，则在用户清除一个或多个日期后，保持日期选择器打开。默认情况下，此属性不存在。

hide-keyboard-shortcuts-panel

如果存在此属性，则隐藏选择器底部的键盘快捷键面板。默认情况下，此属性不存在。

常用属性

此元素包含扩展到 AMP 组件的通用属性。

操作

这些操作可以使用 on 属性由其他组件触发。例如：on="tap: date-picker.setDate(date=state.value)"

阅读更多关于AMP 操作和事件的信息。

clear

clear 操作从具有指定 id 的单个日期选择器或日期范围选择器中清除日期值，例如 date-picker。

<button on="tap: date-picker.clear">Clear</button>

setDate

setDate 操作将 date 参数的值分配给具有指定 id 的单个日期选择器，例如 date-picker。

<button on="tap: date-picker.setDate(date='2018-01-01')">
  Set to Jan 1, 2018
</button>

setDates

setDate 操作将 start 和 end 参数的值分配给具有指定 id 的日期范围选择器，例如 date-picker。

<button on="tap: date-picker.setDates(start='2018-01-01', end='2018-01-07')">
  Set to Jan 1, 2018 through Jan 7, 2018
</button>

today

today 操作将当前日期的值加上 offset 参数的值分配给具有指定 id 的单个日期选择器，例如 date-picker。offset 参数值可以是任何整数。

<button on="tap: date-picker.today">Today</button>
<button on="tap: date-picker.today(offset=1)">Tomorrow</button>
<button on="tap: date-picker.today(offset=-1)">Yesterday</button>

startToday

startToday 操作将当前日期的值加上 offset 参数的值分配给具有指定 id 的日期范围选择器，例如 date-picker。offset 参数值可以是任何整数。

<button on="tap: date-picker.startToday">Today</button>
<button on="tap: date-picker.startToday(offset=1)">Tomorrow</button>
<button on="tap: date-picker.startToday(offset=-1)">Yesterday</button>

startToday 操作可以与 endToday 操作组合使用，以选择具有偏移量的范围。

<button
  on="tap:date-picker.startToday(offset=7), date-picker.endToday(offset=14)"
>
  Next week
</button>

endToday

endToday 操作将当前日期的值加上 offset 参数的值分配给具有指定 id 的日期范围选择器，例如 date-picker。offset 参数值可以是任何整数。

<button on="tap: date-picker.endToday">Today</button>
<button on="tap: date-picker.endToday(offset=1)">Tomorrow</button>
<button on="tap: date-picker.endToday(offset=-1)">Yesterday</button>

endToday 操作可以与 startToday 操作组合使用，以选择具有偏移量的范围。

<button
  on="tap:date-picker.startToday(offset=7), date-picker.endToday(offset=14)"
>
  Next week
</button>

活动

这些事件可以使用 on 属性触发其他 AMP 组件的操作。例如：on="activate: my-lightbox.open"

阅读更多关于AMP 操作和事件的信息。

activate

当用户开始与日历视图交互时（即，当覆盖层将打开时），日期选择器会触发 activate 事件。

deactivate

当用户结束与日历视图的交互时（即，当覆盖层将关闭时），日期选择器会触发 deactivate 事件。

select

当用户选择一个日期或日期范围时，日期选择器会触发 select 事件。选择日期范围时，会在开始日期和结束日期都选中时发出该事件。select 事件包含以下属性。

对于单个日期选择器

属性	描述
`日期`	选择的日期。
`id`	适用于此日期的第一个日期模板的 `id` 属性。

<amp-date-picker
  type="single"
  on="select: AMP.setState({date: event.date, templateSelected: event.id})"
  …
>
  <!-- … -->
</amp-date-picker>

对于日期范围选择器

属性	描述
`日期`	选择的日期数组。数组中的每个对象都包含来自单个日期选择器 `change` 事件对象的 `date` 和 `id` 属性。
`开始`	日期范围中第一个日期的快捷方式 (`event.dates[0]`)。
`结束`	日期范围中最后一个日期的快捷方式 (`event.dates[event.dates.length - 1]`)。

<amp-date-picker
  type="range"
  on="select: AMP.setState({dates: event.dates, firstTemplate: event.start.id})"
  …
>
  <!-- … -->
</amp-date-picker>

样式

模板

amp-date-picker 提供一个标记 API 来呈现某些日期的模板，以及日历视图下方的额外信息区域。

date-template

amp-date-picker 使用 HTML 标记中指定的模板来呈现日期。这些模板必须仅用于不需要经常更新的日期，例如假期。对于在日历天中呈现特殊信息，例如有促销活动的日子、金额或其他必须经常更改的信息，请考虑使用 src 属性。使用 src 可以防止缓存的 AMP 文档显示过时的信息。

date-template 必须具有 dates 或 default 属性。

dates：一个以空格分隔的 ISO 8601 单个日期或 RFC 5545 RRULE 重复日期列表。模板内容将为与属性中日期匹配的日期呈现。
default：如果存在 default 属性，则模板内容将为所有不匹配现有模板的日期呈现。

日期选择器提供 Mustache 变量以在模板中呈现。这些变量是 ISO 8601 格式的字符串值，例如 DD、D、X 等。

date-template 可以包含任何有效的 AMP 内容，并且仅在日历视图首次呈现后呈现。

<amp-date-picker layout="fixed-height" height="360">
  <!-- Render the "party" emoji on New Years Day 2018 -->
  <template type="amp-mustache" date-template dates="2018-01-01">🎉</template>
  <!-- Render the "taco" emoji every Tuesday for 52 weeks starting 2018-01-01 -->
  <template
    type="amp-mustache"
    date-template
    dates="FREQ=WEEKLY;DTSTART=20180101T000000Z;COUNT=52;WKST=SU;BYDAY=TU"
    >🌮</template
  >
  <!-- Render an image -->
  <template type="amp-mustache" date-template dates="2018-01-02">
    <amp-img layout="fixed-height" height="39" src="./example.jpg"></amp-img>
  </template>
  <!-- Renders dates in the two-digit day format -->
  <template type="amp-mustache" date-template default>{{DD}}</template>
</amp-date-picker>

info-template

info-template 包含要在日历视图下方的信息区域中呈现的标记。info-template 可以包含任何有效的 AMP 内容，并且仅在日历视图首次呈现后呈现。

<amp-date-picker layout="fixed-height" height="360">
  <template type="amp-mustache" info-template>
    Warning: Tacos are only available on Tuesday
  </template>
</amp-date-picker>

验证

请参阅 AMP 验证器规范中的 amp-date-picker 规则。

需要更多帮助？

您已经阅读此文档多次，但它并没有真正涵盖您的所有问题？也许其他人也有同样的感受：在 Stack Overflow 上联系他们。

转到 Stack Overflow

发现错误或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的持续参与者，但我们也欢迎您为特别关注的问题做出一次性贡献。

转到 GitHub

amp-date-picker 1.0 0.1

描述