amp-date-picker

說明

提供用於選取日期的 Widget。日期選取器可以輸入欄位的相對覆蓋層或靜態日曆 Widget 的形式呈現。

必要指令碼

<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 會在網頁上呈現日曆，讓使用者可以從中選取日期。

在此範例中，我們會顯示固定高度的靜態日曆，使用者可以在其中選取單一日。

<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

說明