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

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>

支援的版面配置

填滿固定固定高度彈性項目固有不顯示回應式

用法

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-templates 可能包含任何有效的 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-templates 可能包含任何有效的 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

說明