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]

它的外观如下

Hello World
<div style="background: red; width: 200px; height: 200px;">Hello World</div>
在 Playground 中打开此代码片段

内联示例直接嵌入到页面中。如果组件已在页面上使用（例如 amp-consent），则可能会导致冲突。

顶框预览

每当需要指定标头元素或在 <style amp-custom> 内定义全局样式时，请使用顶框预览。

请勿在标头中添加任何 AMP 样板代码，因为这会根据 AMP 格式自动添加。仅将示例所需的元素添加到 head！

  [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

将 preview="top-frame" 与 orientation="portrait" 一起使用以预览 AMP Stories。

  [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 绝对。

  [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