AMP

amp-list

CORS JSON 엔드포인트에서 동적으로 콘텐츠를 가져오고 제공된 템플릿을 사용하여 렌더링합니다.

필수 스크립트 <script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-0.1.js"></script>
지원되는 레이아웃 fill, fixed, fixed-height, flex-item, nodisplay, responsive
AMP By Example의 amp-list example을 참조하세요.

사용

<amp-list> 구성요소는 CORS JSON 엔드포인트에서 동적 콘텐츠를 가져옵니다. 엔드포인트의 응답에는 지정된 템플릿에서 렌더링되는 데이터가 포함되어 있습니다.

엔드포인트에서 AMP의 CORS 요청 사양에 지정된 요구 사항을 구현해야 합니다.

다음 두 방법 중 하나로 템플릿을 지정할 수 있습니다.

  • 기존 template 또는 script 요소의 ID를 참조하는 template 속성
  • amp-list 요소 내에 직접 중첩된 template 또는 script 요소

템플릿에 관한 자세한 내용은 AMP HTML 템플릿을 참조하세요.

예: 동적 목록 표시

다음 예에서는 URL과 제목을 포함하는 JSON 데이터를 검색하고 중첩된 amp-mustache template의 콘텐츠를 렌더링합니다.

<amp-list width="auto"
  height="100"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-urls.json">
  <template type="amp-mustache">
    <div class="url-entry">
      <a href="{{url}}">{{title}}</a>
    </div>
</template>
</amp-list>
Open this snippet in playground

다음은 사용한 JSON 파일입니다.

{
 "items": [
   {
     "title": "AMP YouTube Channel",
     "url": "https://www.youtube.com/channel/UCXPBsjgKKG2HqsKBhWA4uQw"
   },
   {
     "title": "AMP.dev",
     "url": "https://amp.dev/"
   },
   {
     "title": "AMP Validator",
     "url": "https://validator.amp.dev/"
   },
   {
     "title": "AMP Playground",
     "url": "https://playground.amp.dev/"
   }
 ]
}

가져온 콘텐츠의 스타일을 지정하는 방법은 다음과 같습니다.

amp-list div[role="list"] {
  display: grid;
  grid-gap: 0.5em;
  }

동작

AMP 캐시에서 문서를 제공하는 경우에도 항상 클라이언트에서 요청합니다. 현재 표시 영역에서 요소가 얼마나 멀리 떨어져 있는지에 따라 일반 AMP 규칙을 사용하여 로드를 트리거합니다.

로드 후에 <amp-list>에 추가 공간이 필요한 경우 일반 AMP 흐름을 사용하여 높이를 업데이트하도록 AMP 런타임에 요청합니다. AMP 런타임에서 새로운 높이에 대한 요청을 처리할 수 없으면 사용 가능한 경우 overflow 요소를 표시합니다. 그러나 문서 하단에 일반적으로 <amp-list> 요소를 게재하면 AMP 런타임에서 크기를 조정할 수 있음을 거의 항상 보장합니다.

기본적으로 <amp-list>list ARIA 역할을 목록 요소에 추가하고 listitem 역할을 템플릿을 통해 렌더링한 항목 요소에 추가합니다.

XHR 배치

AMP에서 XMLHttpRequests(XHRs)를 JSON 엔드포인트에 배치합니다. 즉, AMP 페이지에서 여러 소비자(예: 여러 <amp-list> 요소)의 데이터 소스로 단일 JSON 데이터 요청을 사용할 수 있습니다. 예를 들어 <amp-list>에서 엔드포인트에 대해 XHR을 작업하는 경우 XHR이 진행되는 동안 동일한 엔드포인트에 대한 모든 후속 XHR이 트리거되지 않고, 대신 첫 번째 XHR의 결과를 반환합니다.

<amp-list>에서 items 속성을 사용하여 JSON 응답의 하위 세트를 렌더링할 수 있으므로, 여러 <amp-list> 요소에서 서로 다른 콘텐츠를 렌더링하지만 단일 XHR을 공유할 수 있습니다.

오버플로 지정

선택적으로 <amp-list> 요소에는 overflow 속성이 있는 요소를 포함할 수 있습니다. AMP 런타임에서 요청한 대로 <amp-list> 요소의 크기를 조정할 수 없으면 이 요소가 표시됩니다.

예: 목록에 추가 공간이 필요한 경우 오버플로 표시

다음 예에서는 이미지와 제목의 목록을 표시합니다. <amp-list> 콘텐츠에 사용 가능한 것보다 많은 공간이 필요하면 AMP 런타임에서 오버플로 요소를 표시합니다.

See more
<amp-list width="auto"
  height="140"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-data.json">
  <template type="amp-mustache">
    <div class="image-entry">
      <amp-img src="{{imageUrl}}"
        width="100"
        height="75"></amp-img>
      <span class="image-title">{{title}}</span>
    </div>
</template>
  <div overflow
    class="list-overflow">
    See more
  </div>
</amp-list>
Open this snippet in playground

다음은 overflow의 CSS입니다.

.list-overflow[overflow] {
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  }

자리표시자 및 대체

선택적으로 <amp-list>에서는 자리표시자 및/또는 대체를 지원합니다.

  • 자리표시자placeholder 속성을 사용하는 하위 요소입니다. 이 요소는 <amp-list>가 성공적으로 로드될 때까지 표시됩니다. 대체도 제공되는 경우 <amp-list>를 로드하지 못하면 자리표시자를 숨깁니다.
  • 대체fallback 속성을 사용하는 하위 요소입니다. <amp-list>를 로드하지 못하면 이 요소가 표시됩니다.

자리표시자 및 대체에 관해 자세히 알아보세요. 하위 요소는 자리표시자와 대체 중 하나여야 합니다.

<amp-list src="https://foo.com/list.json">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>
</amp-list>

데이터 새로고침

<amp-list> 요소에서는 다른 요소가 on="tap:..." 속성에서 참조할 수 있는 refresh 작업을 공개합니다.

<button on="tap:myList.refresh">Refresh List</button>
<amp-list id="myList" src="https://foo.com/list.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-list>

동적 크기 조정

실험: amp-list-resizable-children

사용자 상호작용에서 크기를 조정하는 데 <amp-list>가 필요한 경우도 있습니다. 예를 들어 <amp-list>에 사용자가 탭할 수 있는 amp-accordion이 포함되는 경우, 바인드된 CSS 클래스 때문에 <amp-list>의 콘텐츠 크기가 변경되거나 바인드된 [src] 속성 때문에 <amp-list> 내부의 항목 수가 변경되는 경우입니다. 이 작업을 트리거할 때 amp 목록을 layout="CONTAINER"로 변경하여 changeToLayoutContainer 작업에서 이 문제를 처리합니다. 다음 예제를 참조하세요.

<button on="list.changeToLayoutContainer()">Show Grid</button>
  <amp-list id="list"
        width="396" height="80" layout="responsive"
        src="/test/manual/amp-list-data.json?RANDOM">
        <template type="amp-mustache">
        {{title}}
    </template>
  </amp-list>

이 작업은 amp-list-resizable-children에서 실험적으로 사용할 수 있습니다.

속성

src(필수)

<amp-list>에서 렌더링할 JSON을 반환하는 원격 엔드포인트의 URL입니다. CORS HTTP 서비스여야 하며 URL의 프로토콜은 HTTPS여야 합니다.

엔드포인트에서 AMP의 CORS 요청 사양에 지정된 요구 사항을 구현해야 합니다.

[src] 속성이 있으면 src를 생략할 수 있습니다. amp-bind 작업 중에 페이지 로드가 아니라 사용자 제스처의 결과로 콘텐츠를 렌더링할 때 유용합니다.

credentials(선택사항)

Fetch API에 지정된 대로 credentials 옵션을 정의합니다.

  • 지원되는 값: omit, include
  • 기본값: omit

사용자 인증 정보를 보내려면 include의 값을 전달하세요. 이 값이 설정된 경우 응답이 AMP CORS 보안 지침을 따라야 합니다.

다음은 목록에 맞춤설정된 콘텐츠를 표시하기 위해 사용자 인증 정보를 비롯한 사양을 지정하는 예입니다.

<amp-list credentials="include"
      src="<%host%>/json/product.json?clientId=CLIENT_ID(myCookieId)">
    <template type="amp-mustache">
      Your personal offer: ${{price}}
  </template>
</amp-list>
items(선택사항)

응답에서 렌더링할 배열을 찾는 표현식을 정의합니다. 이 표현식은 JSON 응답의 필드를 통해 이동하는 점으로 표시됩니다. 기본 <amp-list>는 배열되고 single-item 속성은 객체에서 데이터를 로드하는 데 사용할 수 있습니다.

  • 기본값은 'items'입니다. 예상 응답: {items: [...]}.
  • 응답 자체가 원하는 배열이면 '.' 값을 사용합니다. 예상 응답: [...].
  • 중첩 이동이 허용됩니다(예: 'field1.field2'). 예상 응답: {field1: {field2: [...]}}.

items="items"가 지정되면(즉, 기본값) 응답은 'items'라는 배열 속성이 포함된 JSON 객체여야 합니다.

{
  "items": [...]
}

max-items(선택사항)

렌더링할 항목 배열의 최대 길이를 지정하는 정수 값입니다. 반환된 값이 max-items를 초과하면 items 배열이 max-items 항목에서 잘립니다.

single-item(선택사항)

<amp-list>에서 반환된 결과를 단일 요소 배열인 것처럼 처리하게 합니다. 객체 응답은 배열로 래핑되므로 {items: {...}}{items: [{...}]}인 것처럼 동작합니다.

reset-on-refresh(선택사항)

amp-bind 또는 refresh() 작업을 통해 목록의 소스를 새로고칠 때 로드되는 표시기와 자리표시자를 다시 표시합니다.

기본적으로 네트워크 가져오기를 일으키는 새로고침만 트리거합니다. 새로고침을 모두 재설정하려면 reset-on-refresh="always"를 사용합니다,

[is-layout-container] (실험, 선택사항)

기본적으로 항상 false여야 하는 바인드 가능 속성입니다. bind를 통해 true로 설정하면 <amp-list>의 레이아웃을 CONTAINER의 레이아웃으로 변경합니다. 이 속성은 amp-list의 동적 크기 조정을 처리하는 데 유용합니다. <amp-list>에서 CONTAINER 레이아웃을 지원하지 않는 이유와 같은 이유로 이 속성은 기본적으로 true가 될 수 없습니다. 잠재적으로 첫 번째 로드 시 콘텐츠가 점핑됩니다. 이 속성은 amp-list-resizable-children에서 실험적으로 사용 가능합니다. 또는 changeToLayoutContainer 작업도 사용할 수 있습니다.

binding(선택사항)

<amp-list>를 사용하며 amp-bind도 사용하는 페이지의 경우 렌더링된 하위 요소의 바인딩 평가(예: [text])에서 렌더링 차단 여부를 제어합니다.

더 빠른 성능을 위해 binding="no" 또는 binding="refresh"를 사용하는 것이 좋습니다.

  • binding="no": 렌더링을 차단하지 않습니다(가장 빠름).
  • binding="refresh": 초기 로드 시 렌더링을 차단하지 않습니다(더 빠름).
  • binding="always": 렌더링을 항상 차단합니다(느림).

binding 속성이 제공되지 않으면 기본값은 always입니다.

실험: 추가 로드 및 무한 스크롤(amp-list-load-more)

<amp-list>의 페이지로 나누기 및 무한 스크롤의 구현으로 amp-list-load-more 실험을 소개했습니다. 실험 페이지에서 'amp-list-load-more' 실험을 켜고 load-more 속성을 <amp-list>로 추가하여 이 기능을 사용 설정할 수 있습니다. 이 기능은 현재 원본 평가판에 있으며 최종 API는 변경될 수 있습니다.

샘플 사용

<amp-list height="200" src="https://my.rest.endpoint/" width="100" load-more="auto">
  <template type="amp-mustache">
    // ...
  </template>
</amp-list>

작동 예를 보려면 test/manual/amp-list/infinite-scroll-1.amp.htmltest/manual/amp-list/infinite-scroll-2.amp.html을 참조하세요.

속성

load-more(필수)

이 속성에서는 'auto' 또는 'manual'을 허용합니다. 이 속성의 값을 'manual'로 설정하면 <amp-list>의 끝에 'load-more' 버튼이 표시됩니다. 이 속성의 값을 'auto'로 설정하면 무한 스크롤 효과를 위해 <amp-list>에서 세 개의 표시 영역 아래 자동으로 추가 요소를 로드합니다.

load-more-bookmark(선택사항)

이 속성을 통해서는 로드할 다음 항목의 url을 제공하는 필드 이름을 반환된 데이터에 지정합니다. 이 속성이 지정되지 않은 경우 <amp-list>에는 다음으로 로드할 url에 해당하는 load-more-src 필드가 있는 json 페이로드가 있어야 합니다. 이 필드의 이름을 다르게 지정하는 경우 load-more-bookmark 필드를 통해 해당 필드의 이름을 지정할 수 있습니다.예를 들어 다음 샘플 페이로드에서 load-more-bookmark="next"를 지정합니다.

{ "items": [...], "next": "https://url.to.load" }

load-more 요소 맞춤설정

load-more 속성을 사용하는 <amp-list>에는 load-more 버튼, 로더, load-failed 요소 및 선택적으로 목록의 끝을 표시하는 end-cap과 같은 UI 요소가 포함되어 있습니다. 이 요소는 <amp-list-load-more> 요소를 다음과 같은 속성이 있는 <amp-list>의 하위 요소로 제공하여 맞춤설정할 수 있습니다.

load-more-button

로드할 추가 요소가 있으면 목록의 끝에 표시되는(수동 load-more의 경우) load-more-button 속성을 사용하는 <amp-list-load-more> 요소입니다. 이 요소를 클릭하면 load-more-src 필드 또는 load-more-bookmark 속성에 해당하는 반환된 데이터의 필드에 포함된 url에서 추가 요소를 로드하는 가져오기를 트리거합니다. 이 요소는 load-more-button 속성이 있는 하위 요소에 <amp-list>를 제공하여 맞춤설정할 수 있습니다.

예:
<amp-list load-more="manual" src="https://www.load.more.example.com/" width="400" height="800">
  ...
  <amp-list-load-more load-more-button>
    <button>See More</button> /* My custom see more button */
    </amp-list-load-more>
  </amp-list>

amp-mustache를 통해 템플릿으로 작성될 수 있습니다.

예:
<amp-list load-more="auto" width="100" height="500" src="https://www.load.more.example.com/">
  ...
  <amp-list-load-more load-more-button>
    <template type="amp-mustache">
      Showing {{#count}} out of {{#total}} items
      <button>
        Click here to see more!
      </button>
    </template>
  </amp-list-load-more>
</amp-list>

load-more-loading

이 요소는 목록의 끝에 도달하지만 콘텐츠를 여전히 로드 중이거나 사용자가 load-more-button 요소를 클릭한 결과(<amp-list>의 새 하위 요소를 여전히 로드 중) 표시되는 로더입니다. 이 요소는 load-more-loading 속성이 있는 하위 요소에 <amp-list>를 제공하여 맞춤설정할 수 있습니다. 예를 들어 다음과 같습니다.

<amp-list load-more=auto src="https://www.load.more.example.com/" width="400" height="800">
  ...
  <amp-list-load-more load-more-loading>
    <svg>...</svg> /* My custom loader */
    </amp-list-load-more>
  </amp-list>

load-more-failed

로드에 실패하는 경우 <amp-list>의 하단에 표시될 load-more-clickable 속성이 있는 버튼을 포함하는 load-more-failed 속성이 있는 <amp-list-load-more> 요소입니다. 이 요소를 클릭하면 실패한 url의 새로고침을 트리거합니다. 이 요소는 load-more-failed 속성이 있는 하위 요소에 <amp-list>를 제공하여 맞춤설정할 수 있습니다. 예를 들어 다음과 같습니다.

<amp-list load-more="auto" src="https://www.load.more.example.com/" width="200" height="500">
  ...
  <amp-list-load-more load-more-failed>
    <button>Unable to Load More</button>
  </amp-list-load-more>
</amp-list>

위의 예에서 전체 load-more-failed 요소를 클릭할 수 있습니다. 그러나 이 요소의 일반적인 패턴은 클릭 가능한 '새로고침' 버튼을 포함하는 일반적인 클릭 불가능 '로드 실패' 요소입니다. 이를 처리하기 위해 load-more-clickable 요소를 포함하는 버튼이 있는 일반적으로 클릭 불가능한 요소를 사용할 수 있습니다. 예를 들어 다음과 같습니다.

<amp-list load-more="auto" src="https://www.load.more.example.com/" width="200" height="500">
  ...
  <amp-list-load-more load-more-failed>
    <div>
      Here is some unclickable text saying sorry loading failed.
    </div>
    <button load-more-clickable>Click me to reload!</button>
  </amp-list-load-more>
</amp-list>

load-more-end

이 요소는 기본적으로 제공되지 않지만, load-more-end 속성을 포함하는 <amp-list-load-more> 요소가 하위 요소로 <amp-list>에 연결된 경우 추가 항목이 없으면 <amp-list>의 하단에 표시됩니다. 이 요소는 amp-mustache를 통해 템플릿으로 작성될 수 있습니다. 예를 들어 다음과 같습니다.

<amp-list load-more="auto" src="https://www.load.more.example.com/" width="200" height="500">
  ...
  <amp-list-load-more load-more-end>
    Congratulations! You've reached the end. /* Custom load-end element */
  </amp-list-load-more>
</amp-list>
공통 속성

이 요소에는 AMP 구성요소로 확장된 공통 속성이 포함됩니다.

대체

<amp-list>를 사용하면 모든 표준 URL 변수를 대체할 수 있습니다. 자세한 정보는 대체 가이드를 참조하세요.

예를 들어 다음과 같습니다.

<amp-list src="https://foo.com/list.json?RANDOM"></amp-list>

에서는 https://foo.com/list.json?0.8390278471201과 같은 사이트에 요청할 수 있습니다. 여기서는 노출할 때마다 RANDOM 값이 무작위로 생성됩니다.

유효성 검사

AMP 유효성 검사기 사양의 amp-list rules를 참조하세요.

도움이 더 필요한가요?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub