AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

格式指南與教學

指南與教學以 Markdown 格式提交，並具有額外的 frontmatter (前言) 和 shortcode (短代碼) 格式。

文件位置

amp.dev 上的內容取自兩個儲存庫：amp.dev 和 AMPHTML。元件下的所有參考文件皆取自 AMPHTML，無論是內建或擴充功能。

還有其他一些文件從 AMPHTML 匯入到 amp.dev。它們列於此檔案中。請勿在 amp.dev 儲存庫中更新這些文件，您的變更會在後續版本中被覆寫！

Frontmatter (前言)

Frontmatter (前言) 位於每個指南和教學的頂部。

範例

$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 (標題) 文件的標題，將顯示在目錄中。第一個字詞的第一個字母需大寫，但「AMP」和其他專有名詞除外。請使用 & 符號 `&` 代替文字 `and`。
$order (順序) 定義您的文件在目錄中出現的位置。您可能需要編輯其他文件中的 `$order (順序)`，使其出現在正確的位置。
formats (格式) 列出您的文件相關的 AMP 體驗。如果您的文件與 AMP 網站和 AMP 故事相關，但與 AMP 廣告或 AMP 電子郵件無關，您的 frontmatter (前言) 會像這樣： ```yaml formats: - websites - stories ```
author (作者) 作者就是您！請使用您的 GitHub 使用者名稱。
contributors (貢獻者) 列出任何為您的文件做出貢獻的人。此欄位為選填。
description (描述) 撰寫指南或教學的簡短描述。這有助於搜尋引擎最佳化，讓需要的人更容易找到您的作品！
tutorial (教學) 在 frontmatter (前言) 中新增 `tutorial: true`，讓網站在教學旁邊新增教學圖示。教學位於目錄中其章節的底部。

Shortcodes (短代碼)

如需 shortcode (短代碼) 及其用途的清單，請參閱 GitHub 上的 documentation.md。

圖片

amp.dev 以 AMP 建構！因此，我們的圖片必須符合 amp-img 標準。建構程序使用以下語法將圖片轉換為正確的 amp-img 格式。

{{ image('/static/img/docs/tutorials/custom-javascript-tutorial/image1.jpg', 500, 369, layout='intrinsic', alt='Image of basic amp script tutorial starter app') }}

篩選章節

有些文件可能與多種 AMP 格式相關，但某些格式可能需要進一步的說明或資訊，這些說明或資訊與其他格式無關。您可以將這些章節包裝在以下 shortcode (短代碼) 中來篩選這些章節。

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

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

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

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

提示

您可以透過將文字包裝在以下 shortcode (短代碼) 中來新增提示和重點

[tip type="default"]
Default tip
[/tip]

[tip type="important"]
Important
[/tip]

[tip type="note"]
Note
[/tip]

[tip type="read-on"]
Read-on
[/tip]

程式碼片段

將程式碼片段放置在三組反引號內，並在第一組反引號的末尾指定語言。

```html
  // code sample
```

```css
  // code sample
```

```js
  // code sample
```

如果您的程式碼包含雙大括號，如果您使用 amp-mustache 範本，通常會是這種情況，您必須包裝程式碼部分

```html
{% raw %}
  // code with double curly braces
{% endraw  %}
```

清單中的程式碼片段

Python-Markdown 有一些限制。在清單中包含程式碼片段時，請使用以下語法

1. First:
    [sourcecode:html]
      <html>
        <p>Indented content.</p>
      </html>
    [/sourcecode]
  2. Second
  3. Third

預覽程式碼範例

程式碼範例可以有預覽和/或連結到 AMP Playground 版本。

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

當在 Playground 中開啟時，預覽會自動轉換為目前選取的格式 🤯！

使用 preview 屬性定義預覽的產生方式

  • none (無)：不會產生預覽

  • inline (行內)：範例預覽顯示在原始程式碼上方。只有在程式碼不包含任何 head 元素的情況下，才有可能進行一般網站範例的行內預覽。對於不需要任何樣式或其他 head 元素的小範例，請使用此選項 (匯入不算在內，因為它們是透過 imports 屬性指定的)。

  • top-frame (頂層框架)：範例預覽顯示在 iframe 內的原始程式碼上方。方向可以在 portrait (直向) 和 landscape (橫向) 模式之間切換。您可以透過指定額外的屬性來預先選取方向

  • orientation (方向)：default: landscape|portrait (預設值：橫向|直向)

如果需要自訂元素，請在 imports 屬性中指定它們，以逗號分隔的清單，元件名稱後接冒號和版本。如果您的程式碼使用 amp-mustache，請改為在 template 屬性中指定依賴性。

對於具有資源連結的電子郵件內容，請在原始碼中使用佔位符 {{server_for_email}}。

行內範例

以下是簡單的行內範例嵌入。您可以透過行內樣式定義 CSS

  [example preview="inline" playground="true"]
    ```html
    <div style="background: red; width: 200px; height: 200px;">Hello World</div>
    ```
  [/example]
  [/example]

這就是它的外觀

Hello World (哈囉世界)
<div style="background: red; width: 200px; height: 200px;">Hello World</div>
在 Playground 中開啟此程式碼片段

行內範例直接嵌入到頁面中。如果頁面上已使用元件 (例如 amp-consent)，則可能會導致衝突。

頂層框架預覽

當您需要指定標頭元素或在 <style amp-custom> 內定義全域樣式時，請使用頂層框架預覽。

請勿將任何 AMP 樣板程式碼新增至標頭，因為這會根據 AMP 格式自動新增。僅將範例所需的元素新增至標頭！

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

這就是它的外觀

 
<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>
在 Playground 中開啟此程式碼片段

AMP 故事

對於預覽 AMP 故事，請將 preview="top-frame" 與 orientation="portrait" 一起使用。

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

這就是它的外觀

 
  <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>
在 Playground 中開啟此程式碼片段

AMP 電子郵件的絕對網址

請注意我們如何使用 {{server_for_email}}，以便在嵌入 AMP 電子郵件中時，讓端點 URL 成為絕對網址。

  [example preview="top-frame" playground="true"]
    ```html
    <div class="resp-img">
      <amp-img alt="flowers"
        src="{{server_for_email}}/static/inline-examples/images/flowers.jpg"
        layout="responsive"
        width="640"
        height="427"></amp-img>
    </div>
    ```
  [/example]

這就是它的外觀

 
<div class="resp-img">
  <amp-img alt="flowers"
    src="/static/inline-examples/images/flowers.jpg"
    layout="responsive"
    width="640"
    height="427"></amp-img>
</div>
在 Playground 中開啟此程式碼片段

跳脫 Mustache 範本

以下是使用遠端端點的 top-frame (頂層框架) 範例。Mustache 範本需要在範例中使用 {% raw %} 和 {% endraw %} 進行跳脫

[example preview="top-frame"
        playground="true"
        imports="amp-list:0.1"
        template="amp-mustache:0.2"]
    ```html
    <amp-list width="auto" height="100" layout="fixed-height"
      src="{{server_for_email}}/static/inline-examples/data/amp-list-urls.json">
      <template type="amp-mustache">{% raw %}
        <div class="url-entry">
          <a href="{{url}}">{{title}}</a>
        </div>
      {% endraw %}
      </template>
    </amp-list>
    ```
[/example]

這就是它的外觀

 
<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>
在 Playground 中開啟此程式碼片段

您可以使用標準 Markdown 連結語法連結到其他頁面

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

當連結到 amp.dev 上的另一個頁面時，參考將是目標檔案的相對檔案路徑。

錨點

使用錨點連結到文件中的特定章節

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

請在使用沒有錨點的章節連結之前，使用 <a name="#anchor-name></a> 建立錨點目標。一個好的位置是在章節標題的結尾

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

您只能在錨點中使用字母、數字、破折號和底線。請使用簡短的英文錨點名稱，以符合標題或描述章節。請確保錨點名稱在文件中是唯一的。

當頁面被翻譯時，錨點名稱不得變更，且必須保留英文。

當您建立將在另一個頁面的連結中使用的錨點時，您也應該在所有翻譯中建立相同的錨點。

AMP 格式篩選器

元件文件、指南與教學和範例可依 AMP 格式篩選，例如 AMP 網站或 AMP 故事。當連結到此類頁面時，您應該明確指定目標支援的格式，方法是將格式參數附加到連結

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

只有當您確定目標支援您的頁面支援的所有格式時，您才能省略參數。

元件參考

如果您的連結省略版本部分，則元件參考文件的連結會自動指向最新版本。當您明確想要指向某個版本時，請指定完整名稱

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

文件結構

標題、大標題和小標題

標題、大標題和小標題中，第一個字詞的第一個字母需大寫，後續字母則為小寫。例外情況包括 AMP 和其他專有名詞。沒有標題命名為 Introduction (簡介)，簡介會接在文件標題之後。

文件命名

以破折號命名慣例命名文件。


正確 錯誤
hello-world-tutorial.md hello_world_tutorial.md
website-fundamentals.md websiteFundamentals.md
actions-and-events.md actionsandevents.md