Mục lục

Hướng dẫn & thực hành định dạng

Các hướng dẫn và thực hành được gửi trong Markdown, với một front matter bổ sung và định dạng mã ngắn.

Địa chỉ tài liệu

Nội dung trên amp.dev được kéo từ hai kho lưu trữ, amp.dev và AMPHTML. Mọi tài liệu tham khảo trong các thành phần đều được kéo từ AMPHTML, từ các thành phần tích hợp hoặc mở rộng.

Có một vài loại tài liệu khác được nhập vào amp.dev từ AMPHTML. Chúng được liệt kê trong tập tin này. Không cập nhật các tài liệu này trong kho lưu trữ amp.dev – các thay đổi của bạn sẽ bị ghi đè trên các lần dựng sau đó!

Front matter

Front matter được hiển thị ở đầu mỗi bài hướng dẫn và thực hành.

Ví dụ:

$title: Include Custom JavaScript in AMP Pages
$order: 7
formats:
  - websites
author: CrystalOnScript
contributors:
  - fstanis
description: For web experiences requiring a high amount of customization AMP has created amp-script, a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.

`$title`	Tiêu đề của tài liệu của bạn như được hiển thị trong phần mục lục. Viết hoa chữ đầu tiên của từ đầu tiên, ngoại trừ “AMP” và các danh từ riêng khác. Sử dụng ký tự `&` thay cho từ `and` (và).
`$order`	Quy định vị trí của tài liệu của bạn trong phần mục lục. Bạn có thể cần sửa `$order` trong các tài liệu khác để đảm bảo nó được hiển thị ở đúng vị trí.
`formats`	Liệt kê các trải nghiệm AMP liên quan đến tài liệu của bạn. Nếu tài liệu của bạn liên quan đến các website AMP và câu chuyện AMP, nhưng không phải là quảng cáo AMP hoặc email AMP, front matter của bạn sẽ trông như thế này: ```yaml formats: - websites - stories ```
`author`	Tác giả là bạn! Sử dụng tên người dùng GitHub của bạn.
`contributors`	Liệt kê bất cứ ai đã đóng góp vào tài liệu của bạn. Trường này không bắt buộc.
`description`	Viết một mô tả ngắn về bài hướng dẫn hoặc thực hành của bạn. Việc này sẽ giúp tối ưu công cụ tìm kiếm, và đưa bài viết của bạn đến với những người cần nó!
`tutorial`	Thêm `tutorial: true` vào front matter cho website để thêm biểu tượng thực hành vào cạnh nó. Các bài thực hành được đặt ở cuối phần của chúng trong mục lục.

Mã ngắn

Để xem danh sách các mã ngắn và ứng dụng của chúng, hãy đọc documentation.md trên GitHub.

Ảnh

amp.dev được xây dựng với AMP! Do đó, các ảnh của chúng tôi phải phù hợp với tiêu chí amp-img. Quy trình xây dựng sử dụng cú pháp sau để chuyển đổi ảnh sang định dạng amp-img chuẩn.

Lọc các phần

Một số tài liệu có thể liên quan cho nhiều định dạng AMP, nhưng một số định dạng có thể cần được giải thích thêm hoặc chứa những thông tin không liên quan đến các định dạng khác. Bạn có thể lọc các phần này bằng cách gói chúng trong mã ngắn sau.

&lsqb;filter formats="websites"]
This is only visible for [websites](?format=websites).
&lsqb;/filter]

&lsqb;filter formats="websites"]
This is only visible for [websites](?format=websites).
&lsqb;/filter]

&lsqb;filter formats="websites, email"]
This is visible for [websites](?format=websites) & [email](?format=email).
&lsqb;/filter]

&lsqb;filter formats="stories"]
This is visible for [stories](?format=stories).
&lsqb;/filter]

Mẹo

Bạn có thể thêm mẹo và chú ý bằng cách gói văn bản trong mã ngắn sau:

&lsqb;tip type="default"]
Default tip
[/tip]

&lsqb;tip type="important"]
Important
[/tip]

&lsqb;tip type="note"]
Note
[/tip]

&lsqb;tip type="read-on"]
Read-on
[/tip]

Trích đoạn code

Đặt trích đoạn code trong nhóm 3 dấu huyền (backtick), quy định ngôn ngữ ở cuối nhóm dấu huyền đầu tiên.

```html
  // code sample

```css
// code sample





  // code sample
```</pre></div>

Nếu mã của bạn chứa 2 ngoặc nhọn, thường là khi bạn sử dụng khuôn mẫu [`amp-mustache`](../../../../documentation/components/reference/amp-mustache.md?format=websites), bạn phải gói phần chứa code:

<div class="ap-m-code-snippet"><pre>```html<br><br>  // code with double curly braces<br><br>```</pre></div>

### Trích đoạn mã trong danh sách

Python-Markdown có một số giới hạn. Sử dụng cú pháp sau khi bao gồm các trích đoạn code trong danh sách:

<div class="ap-m-code-snippet"><pre>&lsqb;sourcecode:html]
      <html>
        <p>Indented content.</p>
      </html>
    &lsqb;/sourcecode]</pre></div>

## Xem trước code mẫu

Code mẫu có thể có một bản xem trước và/hoặc liên kết đến một phiên bản [Sân thực hành AMP](https://playground.amp.dev/).

<div class="ap-m-code-snippet">
  <pre>&lsqb;example preview="default: none|inline|top-frame"
          playground="default: true|false"
          imports="<custom-element-1>,<custom-element-2>,..."
          template="<custom-template>"]
  ```html
    // code sample




[/example]

Lưu ý: Bản xem trước sẽ tự động được chuyển đổi thành định dạng hiện tại khi mở nó trong sân thực hành 🤯!

Sử dụng thuộc tính preview để quy định cách tạo bản xem trước này:

none: Không có bản xem trước nào được tạo
inline: Bản xem trước sẽ được hiển thị bên trên mã nguồn. Một bản xem trước inline chỉ khả dĩ cho các ví dụ website thông thường nếu code này không chứa bất kỳ yếu tố head nào. Sử dụng tùy chọn này cho các ví dụ nhỏ không cần tạo phong cách hoặc các yếu tố head khác (không tính dữ liệu trích nhập, bởi chúng được quy định qua thuộc tính imports).
top-frame: Bản xem trước sẽ được hiển thị bên trên mã nguồn trong một iframe. Hướng có thể được chuyển đổi giữa chế độ portrait (dọc) và landscape(ngang). Bạn có thể chọn sẵn hướng bằng cách quy định thuộc tính bổ sung:
orientation: default: landscape|portrait

Nếu cần yếu tố tùy chỉnh, quy định chúng trong thuộc tính imports dưới dạng một danh sách phân tách bởi dấu phẩy, với tên của thành phần theo sau bởi một dấu hai chấm và phiên bản. Nếu mã của bạn sử dụng amp-mustache, hãy quy định yếu tố phụ thuộc trong thuộc tính template.

Đối với nội dung email chứa liên kết tài nguyên, hãy sử dụng mã giữ chỗ trong mã nguồn.

Ví dụ Inline

Đây là một ví dụ đơn giản về code inline nhúng. Bạn có thể quy định CSS thông qua phong cách inline:



  
     Hello World
  



    ```html
    Hello World
    ```
  [/example]

Nó trông như thế này:

[example preview="inline" playground="true"]

<div style="background: red; width: 200px; height: 200px;">Hello World</div>

Mở đoạn mã này trong sân thực hành

Cảnh báo: ví dụ inline được nhúng trực tiếp vào trang. Điều này có thể gây xung đột nếu các thành phần đã được sử dụng trên trang này rồi (ví dụ amp-consent).

Xem trước Top-Frame

Sử dụng xem trước top-frame mỗi khi bạn cần quy định các yếu tố đầu mục hoặc quy định phong cách toàn cục trong <style amp-custom>.

Quan trọng: Không thêm bất kỳ đoạn code soạn sẵn AMP nào vào phần đầu mục bởi nó sẽ được thêm tự động tùy vào định dạng AMP. Chỉ thêm các yếu tố mà code mẫu cần vào đầu mục!

  [example preview="top-frame"
         playground="true"]
    ```html
    <head>
      <script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
      <style amp-custom>
        body {
          background: red;
        }
      </style>
    </head>
    <body>
      <h1>Hello AMP</h1>
      <amp-youtube width="480"
        height="270"
        layout="responsive"
        data-videoid="lBTCB7yLs8Y">
      </amp-youtube>
    </body>
    ```
  [/example]

Nó trông như thế này:

<head>
  <script
    async
    custom-element="amp-youtube"
    src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"
  ></script>
  <style amp-custom>
    body {
      background: red;
    }
  </style>
</head>
<body>
  <h1>Hello AMP</h1>
  <amp-youtube
    width="480"
    height="270"
    layout="responsive"
    data-videoid="lBTCB7yLs8Y"
  >
  </amp-youtube>
</body>

Mở đoạn mã này trong sân thực hành

Câu chuyện AMP

Sử dụng preview="top-frame" cùng với orientation="portrait" để xem trước các Câu chuyện AMP.

  [example preview="top-frame"
         orientation="portrait"
         playground="true"]
    ```html
    <head>
      <script async custom-element="amp-story"
          src="https://cdn.ampproject.org/v0/amp-story-1.0.js"></script>
      <style amp-custom>
        body {
          font-family: 'Roboto', sans-serif;
        }
        amp-story-page {
          background: white;
        }
      </style>
    </head>
    <body>
      <amp-story standalone>
        <amp-story-page id="cover">
          <amp-story-grid-layer template="vertical">
            <h1>Hello World</h1>
            <p>This is the cover page of this story.</p>
          </amp-story-grid-layer>
        </amp-story-page>
        <amp-story-page id="page-1">
          <amp-story-grid-layer template="vertical">
            <h1>First Page</h1>
            <p>This is the first page of this story.</p>
          </amp-story-grid-layer>
        </amp-story-page>
      </amp-story>
    </body>
    ```
  [/example]

Nó trông như thế này:

<head>
  <script
    async
    custom-element="amp-story"
    src="https://cdn.ampproject.org/v0/amp-story-1.0.js"
  ></script>
  <style amp-custom>
    body {
      font-family: 'Roboto', sans-serif;
    }
    amp-story-page {
      background: white;
    }
  </style>
</head>
<body>
  <amp-story standalone>
    <amp-story-page id="cover">
      <amp-story-grid-layer template="vertical">
        <h1>Hello World</h1>
        <p>This is the cover page of this story.</p>
      </amp-story-grid-layer>
    </amp-story-page>
    <amp-story-page id="page-1">
      <amp-story-grid-layer template="vertical">
        <h1>First Page</h1>
        <p>This is the first page of this story.</p>
      </amp-story-grid-layer>
    </amp-story-page>
  </amp-story>
</body>

Mở đoạn mã này trong sân thực hành

URL tuyệt đối cho Email AMP

Lưu ý cách chúng tôi sử dụng để quy định URL điểm cuối tuyệt đối nếu code được nhúng trong một email AMP.

Nó trông như thế này:

[example preview="top-frame" playground="true"]

<div class="resp-img">
  <amp-img
    alt="flowers"
    src="/static/inline-examples/images/flowers.jpg"
    layout="responsive"
    width="640"
    height="427"
  ></amp-img>
</div>

Mở đoạn mã này trong sân thực hành

Thoát khuôn mẫu mustache

Đây là một ví dụ top-frame sử dụng một điểm cuối từ xa. Khuôn mẫu mustache cần được thoát trong các ví dụ sử dụng và :

Nó trông như thế này:

[example preview="top-frame" playground="true" imports="amp-list:0.1" template="amp-mustache:0.2"]

<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>

Mở đoạn mã này trong sân thực hành

Liên kết

Bạn có thể liên kết đến các trang khác với cú pháp liên kết markdown tiêu chuẩn:

[link](../../../courses/beginning-course/index.md)

Khi liên kết đến một trang khác trên amp.dev, tham chiếu sẽ là một đường dẫn tập tin tương đối đến tập tin mục tiêu.

Anchor

Liên kết đến các phần cụ thể trong một tài liệu sử dụng các anchor:

[link to example section](#example-section)

Vui lòng tạo mục tiêu anchor bằng <a name="#anchor-name></a> trước khi liên kết đến một phần không có anchor. Một vị trí tốt là ở cuối đầu mục phần:

## Example section <a name="example-section"></a>

Bạn chỉ được sử dụng chữ cái, số, dấu gạch ngang và gạch dưới trong một anchor. Vui lòng sử dụng tên anchor ngắn bằng tiếng Anh, phù hợp với đầu mục hoặc mô tả phần. Đảm bảo tên anchor là duy nhất trong tài liệu.

Khi một Trang được dịch, tên anchor phải không được thay đổi và giữ nguyên bằng tiếng Anh.

Khi bạn tạo một anchor mà sẽ được sử dụng trong một liên kết từ một trang khác, bạn cũng nên tạo anchor đó trong tất cả các bản dịch.

Bộ lọc định dạng AMP

Tài liệu thành phần, hướng dẫn và thực hành cùng các ví dụ có thể được lọc theo định dạng AMP, ví dụ như website AMP hoặc câu chuyện AMP. Khi liên kết đến một trang như vậy, bạn cần quy định rõ một định dạng được hỗ trợ bởi mục tiêu, bằng cách chèn tham số định dạng vào liên kết:

[link](../../learn/amp-actions-and-events.md?format=websites)

Chỉ khi bạn chắc chắn rằng mục tiêu hỗ trợ tất cả các định dạng mà trang của bạn hỗ trợ thì bạn mới có thể bỏ tham số này.

Tham khảo cho thành phần

Một liên kết đến tài liệu tham khảo cho thành phần sẽ tự động chỉ đến phiên bản mới nhất nếu liên kết của bạn không chứa thông tin phiên bản. Khi bạn muốn chỉ đến một phiên bản cụ thể, hãy nhập tên đầy đủ:

[latest version](../../../components/reference/amp-carousel.md?format=websites)
[explicit version](../../../components/reference/amp-carousel-v0.2.md?format=websites)

Cấu trúc Tài liệu

Tiêu đề, đầu mục và tiểu mục

Chữ cái đầu tiên của từ đầu tiên trong tiêu đề, đầu mục và tiểu mục được viết hoa, những chữ sau được viết thường. Ngoại lệ bao gồm AMP và các danh từ riêng. Không có đầu mục nào được đặt tên là Introduction (Giới thiệu), phần giới thiệu phải ở sau tiêu đề tài liệu.

Đặt tên cho tài liệu

Đặt tên tài liệu theo quy ước về dấu gạch ngang.

Nên	Không nên
hello-world-tutorial.md	hello_world_tutorial.md
website-fundamentals.md	websiteFundamentals.md
actions-and-events.md	actionsandevents.md

Written by @CrystalOnScript

{{#initial}}Các Thành phần Quan trọng{{/initial}}{{^initial}}Thành phần{{/initial}}

{{#initial}}<{{title}}>{{/initial}}{{^initial}}{{title}}{{/initial}}

{{#initial}}Bài viết Phổ biến{{/initial}}{{^initial}}Kết quả{{/initial}}

{{title}}

;(

Đã có lỗi xảy ra…

¯\_(ツ)_/¯

Không tìm thấy kết quả nào.

Hướng dẫn & thực hành định dạng

Địa chỉ tài liệu

Front matter

Mã ngắn

Ảnh

Lọc các phần

Mẹo

Trích đoạn code

Ví dụ Inline

Xem trước Top-Frame

Câu chuyện AMP

URL tuyệt đối cho Email AMP

Thoát khuôn mẫu mustache

Liên kết

Anchor

Bộ lọc định dạng AMP

Tham khảo cho thành phần

Cấu trúc Tài liệu

Tiêu đề, đầu mục và tiểu mục

Đặt tên cho tài liệu