amp-position-observer

說明

監控使用者捲動時，元素在視口中的位置，並派發可用於其他 AMP 元件的事件。

必要指令碼

<script async custom-element="amp-position-observer" src="https://cdn.ampproject.org/v0/amp-position-observer-0.1.js"></script>

支援版面配置

nodisplay

範例

滾動綁定效果基礎捲動至頂端

用法

amp-position-observer 元件會監控使用者捲動時，元素在視口中的位置，並派發 enter、exit 和 scroll:<Position In Viewport As a Percentage> 事件 (低信任等級)，可用於觸發其他元件 (例如 amp-animation) 的動作 (僅限低信任動作)。

amp-position-observer 元件僅在與其他元件搭配使用時才有用，本身不會執行任何動作。

目前，amp-animation 和 AMP 中的數個影片播放器是唯一允許低信任事件觸發其動作的元件 (例如，啟動動畫、搜尋動畫中的位置、暫停影片等)。

滾動綁定動畫

amp-animation 元件公開了 seekTo 動作，可以與 amp-position-observer 的 scroll 事件連結，以實作滾動綁定動畫。

範例：動畫隨著使用者捲動而旋轉

想像一個動畫，時鐘的時針會隨著使用者捲動頁面而旋轉。

<!-- An animation that rotates a clock hand 180 degrees. -->
<!--
   Note that we are NOT setting `trigger=visibility`
   since we will manually trigger the animation.
-->
<amp-animation id="clockAnim" layout="nodisplay">
  <script type="application/json">
    {
      "duration": "3s",
      "fill": "both",
      "direction": "alternate",
      "animations": [
        {
          "selector": "#clock-scene .clock-hand",
          "keyframes": [
            {"transform": "rotate(-180deg)"},
            {"transform": "rotate(0deg)"}
          ]
        }
      ]
    }
  </script>
</amp-animation>

<!-- The clock container -->
<div id="clock-scene">
  <!--
    Use amp-position-observer to tie the movement of the clock scene within
    the viewport to the timeline of the animation
  -->
  <amp-position-observer
    intersection-ratios="1"
    on="scroll:clockAnim.seekTo(percent=event.percent)"
    layout="nodisplay"
  >
  </amp-position-observer>
  <amp-img layout="responsive" width="2" height="1.5" src="./img/clock.jpg">
    <div class="clock-hand"></div>
  </amp-img>
</div>

根據視口中的可見度啟動/暫停的動畫場景

amp-animation 元件也公開了 start 和 pause 動作，可以與 amp-position-observer 的 enter 和 exit 事件連結，以根據可見度控制動畫的啟動/暫停時機。

amp-position-observer 元件公開了各種可見度配置，例如 intersection-ratios 和 viewport-margins (類似於 IntersectionObserver)，可用於微調目標被視為可見的時機。

範例：動畫根據可見度啟動和暫停

考慮相同的時鐘動畫，但這次指針會隨著時間動畫，只是我們希望動畫在時鐘至少 50% 可見時啟動，並在時鐘變得小於 50% 可見時立即暫停。

<!-- An animation that rotates a clock hand 180 degrees. -->
<!--
   Note that we are NOT setting `trigger=visibility`
   since we will manually trigger the animation
-->
<!--
   Also note that this is the same animation as the scroll-bound version above
   the animation is the same, just the triggering mechanism with
   `amp-position-observer` is different!
-->
<amp-animation id="clockAnim" layout="nodisplay">
  <script type="application/json">
    {
      "duration": "3s",
      "fill": "both",
      "direction": "alternate",
      "animations": [
        {
          "selector": "#clock-scene .clock-hand",
          "keyframes": [
            {"transform": "rotate(-180deg)"},
            {"transform": "rotate(0deg)"}
          ]
        }
      ]
    }
  </script>
</amp-animation>

<!-- The clock container -->
<div id="clock-scene">
  <!--
    Use amp-position-observer to tie the start/pause of the animation with
    the visibility of the scene.
  -->
  <amp-position-observer
    intersection-ratios="0.5"
    on="enter:clockAnim.start;exit:clockAnim.pause"
    layout="nodisplay"
  >
  </amp-position-observer>

  <amp-img layout="responsive" width="2" height="1.5" src="./img/clock.jpg">
    <div class="clock-hand"></div>
  </amp-img>
</div>

滾動綁定和基於可見度的動畫之無障礙考量

一般而言，動畫可能會對某些使用者群體造成問題。特別是滾動綁定和視差動畫，對於患有前庭疾病的使用者來說可能有問題。請務必查看 amp-animation 的無障礙考量中提供的建議。

屬性

target (選填)

指定要觀察的元素 ID。如果未指定，則會使用 <amp-position-observer> 的父元素作為目標。

intersection-ratios (選填)

定義在 <amp-position-observer> 觸發其任何事件之前，目標應在視口中可見的程度。值是介於 0 和 1 之間的數字 (預設值為 0)。

您可以透過提供兩個值 (<top> <bottom>) 來指定頂部與底部的不同比率。

intersection-ratios="0" 表示只要目標的單一像素進入視口就會觸發 enter，而只要目標的最後一個像素離開視口就會觸發 exit。
intersection-ratios="0.5" 表示只要目標的 50% 進入視口就會觸發 enter，而只要目標少於 50% 在視口中就會觸發 exit。
intersection-ratios="1" 表示當目標完全可見時會觸發 enter，而只要單一像素離開視口就會觸發 exit。
intersection-ratios="0 1" 會根據目標是從頂部 (將使用 0) 或底部 (將使用 1) 進入/離開而使條件有所不同。

viewport-margins (選填)

可用於縮小用於可見度計算的視口區域的 px 或 vh 值。沒有單位的數字將被視為 px。預設值為 0。

您可以透過提供兩個值 (<top> <bottom>) 來指定頂部與底部的不同值。

viewport-margins="100px" 表示從頂部和底部將視口縮小 100 像素。
viewport-margins="25vh" 表示從頂部和底部將視口縮小 25%。實際上只考慮視口的中間 50%。
viewport-margins="100px 10vh" 表示從頂部將視口縮小 100 像素，從底部縮小 10%。

once (選填)

僅觸發 enter 和 exit 事件一次。scroll 事件也只會執行一次迭代。

屬性的存在表示 true 值，而屬性的不存在表示 false 值。如果屬性存在，則其值必須是空字串、once 或未指定。

驗證

請參閱 AMP 驗證器規格中的 amp-position-observer 規則。

需要更多協助嗎？

您已經閱讀這份文件十幾次了，但它仍然沒有涵蓋您的所有問題？也許其他人也有同樣的感受：在 Stack Overflow 上與他們聯繫。

前往 Stack Overflow

發現錯誤或缺少功能？

AMP 專案強烈鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎您針對您特別感興趣的問題做出一次性貢獻。

前往 GitHub