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

格式指南 & 教程

指南和教程以 Markdown 格式提交，并带有额外的前言和短代码格式。

文档位置

amp.dev 上的内容来自两个存储库，amp.dev 和 AMPHTML。组件下的所有参考文档都来自 AMPHTML，无论是内置组件还是扩展组件。

还有一些其他文档从 AMPHTML 导入到 amp.dev。它们在此文件中列出。不要在 amp.dev 存储库中更新这些文档 – 您的更改将在后续构建中被覆盖！

前言

前言位于每个指南和教程的顶部。

示例

$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 Stories 相关，但与 AMP 广告或 AMP 电子邮件无关，则您的前言如下所示： ```yaml formats: - websites - stories ```
author 作者就是您！使用您的 GitHub 用户名。
contributors 列出任何为您的文档做出贡献的人。此字段为可选字段。
description 简要描述您的指南或教程。这有助于搜索引擎优化，使您的作品能够被需要它的人所看到！
tutorial 在前言中添加 `tutorial: true`，以便网站在旁边添加教程图标。教程位于目录中其部分的底部。

短代码

有关短代码及其用法的列表，请查看 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 格式相关，但某些格式可能需要进一步的解释或信息，而这些信息与其他格式无关。您可以通过将这些部分包裹在以下短代码中来筛选这些部分。

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

提示

您可以通过将文本包裹在以下短代码中来添加提示和标注

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

这就是它的样子

你好，世界
<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 Stories

对于预览 AMP Stories，请将 `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 电子邮件的绝对 URL

请注意，如果嵌入到 AMP 电子邮件中，我们如何使用 `{{server_for_email}}` 来使端点 URL 成为绝对 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` 示例。必须使用 `{% raw %}` 和 `{% endraw %}` 在示例中转义 Mustache 模板

[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 Stories）进行筛选。当链接到此类页面时，您应该明确指定目标支持的格式，方法是将 format 参数附加到链接

 [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