重要事項：此文件不適用於您目前選取的格式故事！

amp-date-picker

描述

提供用於選取日期的 Widget。日期選取器可以覆蓋在輸入欄位上呈現，或作為靜態日曆 Widget 呈現。

必要腳本

<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 會自動將 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 屬性，則目前日期將為最小日期。

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 重複日期陣列，以在日曆視圖中呈現為封鎖。使用者無法選取這些日期。
`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 屬性，則範本內容將針對所有不符合現有範本的日期呈現。

日期選取器提供 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

描述