重要提示：此文档不适用于您当前选择的格式故事！

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

当 static 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 属性。这可以防止不必要地打开设备的屏幕键盘。要选择退出此行为，请将 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` 属性。

在用户手势之后，可以使用 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 事件包含以下属性。

对于单个日期选择器

属性	描述
`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 属性，则模板内容将为所有不匹配现有模板的日期渲染。

日期选择器提供了 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

描述