amp-date-picker

说明

提供一个用于选择日期的小部件。日期选择器可以呈现为相对于输入字段的叠加层，或作为静态日历小部件。

必需的脚本

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

支持的布局

填充固定固定高度 flex-item 固有 nodisplay 自适应

示例

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 之一。

当静态 amp-date-picker 在 <form> 中呈现时，如果没有使用 *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 属性。这可以防止设备的屏幕键盘不必要地打开。要退出此行为，请向 <amp-date-picker> 元素添加 touch-keyboard-editable 属性。

选择类型

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 属性，则当前日期将是最小日期。

min 属性可以在用户手势后使用 amp-bind 进行更新。

max

用户可以选择的最新日期。必须以 ISO 8601 日期格式设置。如果没有 max 属性，则日期选择器将没有最大日期。

max 属性可以在用户手势后使用 amp-bind 进行更新。

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 重复日期的数组。
`startDate`	为具有 `type="range"` 的日期选择器指定最初选定的开始日期。在具有 `type="single"` 的日期选择器中，此设置无效。为了防止覆盖用户的输入，如果用户已经选择了开始日期，此值将无效。
`templates`	templates 属性是 “模板定义对象” 的数组。这些对象具有 `id` 属性和 `dates` 属性。

src 属性可以在用户手势后使用 amp-bind 进行更新。

模板定义对象

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>

对于日期范围选择器

属性	说明
`dates`	选定日期的数组。数组中的每个对象都包含单个日期选择器 `change` 事件对象中的 `date` 和 `id` 属性。
`start`	日期范围中第一个日期的快捷方式（`event.dates[0]`）。
`end`	日期范围中最后一个日期的快捷方式（`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

说明