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

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

<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

描述