用法
屬性
動作
活動
樣式設定
- 範本
  - date-template (日期範本)
  - info-template (資訊範本)
驗證

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

amp-date-picker

說明

提供用於選取日期的微型應用程式。日期選擇器可以輸入欄位的相對位置以覆蓋方式呈現，或以靜態日曆微型應用程式呈現。

必要指令碼

<script async custom-element="amp-date-picker" src="https://cdn.ampproject.org/v0/amp-date-picker-1.0.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 提供兩種模式來呈現日期選擇器：static (靜態) (預設) 或 overlay (覆蓋)。

靜態模式

透過指定 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)`	第一個日期範本的 `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

說明