amp-date-picker

说明

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

必需脚本

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

支持的布局

fill fixed fixed-height flex-item intrinsic nodisplay responsive

示例

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 属性添加到其 <input> 元素中。这可以防止设备的屏幕键盘不必要地打开。要选择退出此行为，请将 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 重复日期数组，在日历视图中呈现为已阻止。用户无法选择这些日期。
`date`	指定最初选定的日期。在具有 `type="range"` 的日期选择器中，此项无效。为了防止覆盖用户的输入，如果用户已经选择了一个日期，此值无效。
`endDate`	指定最初选定的结束日期。在具有 `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 事件包含以下属性。

对于单个日期选择器

属性	说明
`date`	所选日期。
`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 属性，则模板内容将针对所有与现有模板不匹配的日期进行呈现。

日期选择器提供了小胡子变量，以便在模板中呈现。这些变量是 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

说明