From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../mdn/structures/compatibility_tables/index.html | 500 +++++++++++++++++++++ files/zh-cn/mdn/structures/index.html | 18 + files/zh-cn/mdn/structures/live_samples/index.html | 213 +++++++++ .../simple_live_sample_demo/index.html | 31 ++ .../mdn/structures/macros/custom_macros/index.html | 222 +++++++++ files/zh-cn/mdn/structures/macros/index.html | 48 ++ 6 files changed, 1032 insertions(+) create mode 100644 files/zh-cn/mdn/structures/compatibility_tables/index.html create mode 100644 files/zh-cn/mdn/structures/index.html create mode 100644 files/zh-cn/mdn/structures/live_samples/index.html create mode 100644 files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html create mode 100644 files/zh-cn/mdn/structures/macros/custom_macros/index.html create mode 100644 files/zh-cn/mdn/structures/macros/index.html (limited to 'files/zh-cn/mdn/structures') diff --git a/files/zh-cn/mdn/structures/compatibility_tables/index.html b/files/zh-cn/mdn/structures/compatibility_tables/index.html new file mode 100644 index 0000000000..fdcf1d1408 --- /dev/null +++ b/files/zh-cn/mdn/structures/compatibility_tables/index.html @@ -0,0 +1,500 @@ +--- +title: 兼容性表格 +slug: MDN/Structures/Compatibility_tables +tags: + - MDN Meta + - 兼容性表格 + - 指南 + - 浏览器兼容性 +translation_of: MDN/Structures/Compatibility_tables +--- +
{{MDNSidebar}}
+ +
{{IncludeSubnav("/zh-CN/docs/MDN")}}
+ +

MDN 为我们的开放网页文档提供了兼容性表格的标准格式; 它是对比所有浏览器之间，包含 DOM，HTML，CSS，JavaScript，SVG 等技术的文档。本文将介绍如何使用我们的功能将兼容性数据添加到MDN页面。

+ +
+

重要: 数据的生成方式已经发生了变更。过去，我们的表格直接嵌入在页面中，而且数据是手动填写的。这样效率很低，难以维护，而且使得数据不够灵活，不便更新。所以我们正在把我们的兼容性表格迁移到一个数据 repo 中（https://github.com/mdn/browser-compat-data）并且改为使用程序化的方式生成它。
+
+ 本指南中，我们撰写了关于如何向 MDN 添加新的兼容性数据的文档，但是我们仍然保留了旧的方法来保证旧文档的兼容性表格可用：正如你所见，手动输入的表格依然存在于 MDN 上。如果你有必要使用旧方法的话，可以参考这篇文章：Old compatibility tables。

+
+ +
+

注意：如果您需要本指南任何步骤的帮助，欢迎您在MDN论坛上与我们联系。

+
+ +

如何访问 data repo

+ +

数据存储在一个 GitHub repo 中，到 https://github.com/mdn/browser-compat-data 查看。想要访问它，你必须拥有一个 GitHub 账号，fork浏览器兼容数据仓库到你自己的账户，然后克隆你的fork到你的本地机器。

+ +

选择要贡献的数据类型

+ +

首先，确定一下你想为何种 Web 技术贡献兼容性数据。可以是一个 HTML 元素、CSS 属性、JS 语法或者 JS API 接口。我们鼓励您贡献 API 接口的数据, 因为已经有人在贡献 HTML、JS 和 CSS 的数据了。你可以在表格 Browser Compat Data migration 中查看各个需要添加兼容性数据的 Web 技术的数据状态。

+ +

电子表格的使用步骤如下:

+ +
    +
  1. 直接挑选一个还未开始或者还未完成数据录入的功能点，在“Who”一栏中填入你的名字, 最好能够和你的MDN用户名保持一致，以便我们在需要联系你的时候能够查找到你的邮件地址.
    2. +
  2. 如果该功能点不在表格上，那么你可以参照现有的格式在合适的位置上加一行。注意要使用同等的粒度（例如，HTML以标签元素为单位、CSS以选择器或者属性值为单位、JS以对象为单位、JS API以特定的接口为单位）
    3. +
  3. 当你已经开始录入数据的时候，把对应状态栏的下拉选项置于“In progress”（进行中）状态。
    4. +
  4. 一旦添加完数据，并且向主仓库提交了一个拉取请求（pull request），那么把对应状态栏的下拉选项置于“PR done”状态。
    5. +
  5. 当你的数据已经成功合并到主分支，或者已经添加到npm包里面的时候，请尽量更新对应的状态栏到相应的状态。
    6. +
  6. 当你更新了你的功能文档页面，并且使用新的脚步命令使其可以在每一个页面都可以动态的生成合适的数据表格的时候，你就需要在电子表格中修改对应功能的状态为“Article updated”（文章已更新）。这意味着你已经完成了这一功能的所有数据录入工作。
    7. +
+ +

准备添加数据

+ +

在添加新数据之前，你应该保证您的 fork 是主 repo 的最新版本（它们应包含相同的内容）。在您的 fork 里添加一个包含您的更改的分支，然后把它pull到您本地的仓库，这样你就可以开始贡献了：

+ +

下面是更新您的分支的一个简单方法：

+ +

将浏览器兼容信息的主 repo 添加到远端服务器列表中

+ +

在您的终端或命令行中进入您的fork的本地仓库，用以下命令将（服务器上的）主 repo 添加到远端服务器列表中（您只需执行以下命令一次）：

+ +
git remote add upstream https://github.com/mdn/browser-compat-data.git
+ +

如果您不确定自己是否做到了这一点， 您可以检查您仓库已经在用的远端服务器列表：

+ +
git remote -v
+ +

让您的分支与服务器上的内容同步

+ +

现在，只要您想更新您的分支，您就可以这样做：

+ +
    +
  1. +

    确定您已切换到在主分支：

    + + 
    git checkout master
    +
    2. +
  2. +

    使用以下命令来获取服务器上最新的内容：

    + + 
    git fetch upstream
    +
    3. +
  3. +

    用rebase将主仓库的内容合并到您的master分支中：

    + + 
    git rebase upstream/master
    +
    4. +
  4. +

    将来自主 repo 的更新 push 回您自己的 repo 中：

    + + 
    git push -f
    +
    5. +
+ +

创建您用来工作的分支：

+ +

接下来，打开您在服务器上的fork（它的地址可能是https://github.com/your-username/browser-compat-data）并且创建一个新分支来存储您的改动。步骤如下：

+ +
    +
  1. 点击"Branch: Master"按钮；
    2. +
  2. 在"Find or create a branch..."文本输入框中输入一个新的分支名；
    3. +
  3. 点击下方出现的"Create branch name-of-branch from Master"按钮。
    4. +
+ +

举个例子，如果您想补充WebVR API的信息，您可以创建一个名为“webvr”的分支.

+ +

切换到新分支

+ +

此时，回到您的终端或命令行，用以下命令将您的新分支同步到您本地的fork中：

+ +
git pull
+ +

现在用以下命令切换到您的新分支

+ +
git checkout -b name-of-branch
+ +

现在您可以开始进行您对浏览器兼容信息的补充和修改了。

+ +

添加数据

+ +

为添加新的数据，您需要新建文件以存储您的兼容性数据。对于不同技术的数据，您需要创建的文件也有所不同：

+ + + +
+

注意：您会留意到，该仓库还包含了浏览器拓展和HTTP的数据。These data sets are basically finished as they stand, but more features may need to be added in the future.

+
+ +

你创建的每个文件都需要跟随定义在我们repo的schema中的这些模板的规定。你可以参考详细的模板描述。

+ +

基本的兼容性数据的结构

+ +

让我们来看一下如下例子。一个CSS属性JSON文件需要以下的结构：

+ +
{
+  "css": {
+    "properties": {
+      "border-width": {
+        "__compat": {
+          ...
+        }
+      }
+    }
+  }
+}
+ +

首先有一个css对象，其中包含了一个properties对象。每个您要设定兼容性数据的特性都对应一个properties对象中的成员。而每一个这些成员都有一个__compat成员，__compat成员中则是实际的数据。

+ +

以上的数据能在 browser-width.json 文件中找到——可将这与 MDN上渲染后的浏览器兼容性 相比较。

+ +

对于其他类型特性，写法是类似的，但对象的名称不同：

+ + + +
+

在一个HTML、CSS和JS页面中，通常您只需要有一个特性。API则有些不同——它们总是包含多个子特性 （参见下边的 {{anch("Sub-features")}}）。

+ +

一个特性中的基础结构

+ +

在一个特性的__compat成员中，您需要包含以下成员：

+ + + +

浏览器成员名称在架构里被定义（参见 浏览器标识符）。你应该使用现有定义的标识符的完整列表。如果你希望添加其他浏览器，请先联系我们，因为这可能会产生广泛的影响，不应该在未经认真考虑就这么做。

+ +

在一个基本的浏览器兼容数据文件中，你只需要在浏览器标识符成员仲包含"version_added" （以下我们会说到{{anch("Advanced cases")}}）。其他你可能使用的值还包括： 

+ + + +

在 status 成员中，包含三个子成员：

+ + + +

作为例子，以下是 border-width 特性的数据 (参见 border-width.json) ：

+ +
"__compat": {
+  "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width",
+  "support": {
+    "chrome": {
+      "version_added": "1"
+    },
+    "webview_android": {
+      "version_added": "2"
+    },
+    "edge": {
+      "version_added": true
+    },
+    "edge_mobile": {
+      "version_added": true
+    },
+    "firefox": {
+      "version_added": "1"
+    },
+    "firefox_android": {
+      "version_added": "1"
+    },
+    "ie": {
+      "version_added": "4"
+    },
+    "ie_mobile": {
+      "version_added": "6"
+    },
+    "opera": {
+      "version_added": "3.5"
+    },
+    "opera_android": {
+      "version_added": "11"
+    },
+    "safari": {
+      "version_added": "1"
+    },
+    "safari_ios": {
+      "version_added": "3"
+    }
+  },
+  "status": {
+    "experimental": false,
+    "standard_track": true,
+    "deprecated": false
+  }
+}
+ +

添加描述说明

+ +

There is a fourth, optional, member that can go inside the __compat member — description. This can be used to include a human-readable description of the feature. You should only include this if it is hard to see what the feature is from glancing at the data. For example, it might not be that obvious what a constructor is from looking at the data structure, so you can include a description like so:

+ +
{
+  "api": {
+    "AbortController": {
+      "__compat": {
+        ...
+      },
+      "AbortController": {
+        "__compat": {
+          "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController",
+          "description": "<code>AbortController()</code> constructor",
+          "support": {
+            ...
+          }
+        }
+      }
+
+      ... etc.
+    }
+  }
+}
+ +

子特性

+ +

In a page where the compat table has more than one row, you'll need multiple subfeatures inside each feature to define the information for each row. This can happen, for example, when you've got the basic support for a feature stored in one row, but then the feature also has a new property or value type that was addded much later in the specification's life and is only supported in a couple of browsers.

+ +

As an example, see the compat data and corresponding MDN page for the background-color property. The basic support exists inside the __compat object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own __compat object.

+ +
{
+  "css": {
+    "properties": {
+      "background-color": {
+        "__compat": {
+          ...
+        },
+        "alpha_ch_for_hex": {
+          "__compat": {
+            ...
+          },
+        }
+      }
+    }
+  }
+}
+ +

For an API, you've got the top two levels defined as api.name-of-the-interface, then a top-level __compat section to define the overall browser compatibility of the interface, then a sub-feature for each of the methods, properties, and constructors contained inside the interface. The basic structure looks like this:

+ +
{
+  "api": {
+    "VRDisplay": {
+      "__compat": {
+        ...
+      },
+      "cancelAnimationFrame": {
+        "__compat": {
+          ...
+        }
+      },
+      "capabilities": {
+        "__compat": {
+          ...
+        }
+      },
+
+      ... etc.
+
+    }
+  }
+}
+ +

See VRDisplay.json for a full example.

+
+ +

添加数据：高级场景

+ +

There are some advanced features that you'll want to include in browser compat data. The aim of this section is to list the most common ones, providing an example of each to show how you can implement them in your own compat data.

+ +

Including a footnote

+ +

Often compat tables will include footnotes related to certain entries that explain useful details or strange behavior that developers will find useful. As an example, the Chrome Android entry for {{domxref("VRDisplay.capabilities")}} (see also VRDisplay.json)  (at the time of writing) had a footnote "Currently supported only by Google Daydream." To include this in the capabilities data, we added a "notes" submember inside the relevant "chrome_android" submember; it would look like this:

+ +
"chrome_android": {
+  "version_added": true,
+  "notes": "Currently supported only by Google Daydream."
+}
+ +

包含浏览器厂商的前缀

+ +

If a feature is supported behind a vendor prefix in one or more browsers, you'll want to make that clear in the browser compat data. 例如您可能有一个特性在Firefox浏览器中要用-moz-前缀才被支持，要在兼容性数据中指明这一点，您需在对应的"firefox"子成员中增加一个"prefix"子成员。它看起来是这样的：

+ +
"firefox": {
+  "version_added": true,
+  "prefix": "-moz-"
+}
+ +

Including browser preferences or flags

+ +

Some features may be supported in a browser, but they are experimental and turned off by default. If a user wants to play with this feature they need to turn it on using a preference/flag.

+ +

To represent this in the compat data, you need to add the "flags" submember inside the relevant browser identifier submember. The value of "flags" is an array of objects each of which contains of three members:

+ + + +

So to add a preference/flag to the Chrome support for a feature, you'd do something like this:

+ +
"chrome": {
+  "version_added": "50",
+  "flags": [
+    {
+      "type": "preference",
+      "name": "Enable Experimental Web Platform Features",
+      "value_to_set": "true"
+    }
+  ]
+},
+ +

If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example:

+ +
"firefox": {
+  "version_added": "57",
+  "flags": [
+    {
+      "type": "preference",
+      "name": "dom.streams.enabled",
+      "value_to_set": "true"
+    },
+    {
+      "type": "preference",
+      "name": "javascript.options.streams",
+      "value_to_set": "true"
+    }
+  ]
+},
+ +

包含特性不再被支持的版本

+ +

有时一个特性在浏览器的某个版本被加进去，然后又因为该特性过时而被被移除掉。这可以在"version_removed"子成员中体现。该子成员是一个代表特性被移除的版本的字符串。例如：

+ +
"firefox": {
+  "version_added": "35",
+  "version_removed": "47",
+},
+ +

Including multiple support points for the same browser entry

+ +

Sometimes you'll want to add multiple support data points for the same browser inside the same feature.

+ +

As an example, the {{cssxref("text-align-last")}} property (see also text-align-last.json) was added to Chrome in version 35, supported behind a pref.

+ +

The support mentioned above was then removed in version 47; also in version 47, support was added for text-align-last enabled by default.

+ +

To include both of these data points, you can make the value of the "chrome" submember an array containing two support information objects, rather than just a single support information object:

+ +
"chrome": [
+  {
+    "version_added": "47"
+  },
+  {
+    "version_added": "35",
+    "version_removed": "47",
+    "flags": [
+      {
+        "type": "preference",
+        "name": "Enable Experimental Web Platform Features",
+        "value_to_set": "true"
+      }
+    ]
+  }
+],
+ +
+

Note: You should put the most current or important support point first in the array — this makes the data easier to read for people who just want to scan it for the latest info.

+
+ +

包含一个可选的名字

+ +

Occasionally browsers will support a feature under a different name to the name defined in its specification. This might be for example because a browser added experimental support for a feature early, and then the name changed before the spec stabilized.

+ +

To include such a case in the browser compat data, you can include a support information point that specifies the alternative name inside an "alternative_name" member.

+ +
+

Note: The alternative name might not be an exact alias — it might have differing behaviour to the standard version.

+
+ +

Let's look at an example. The {{cssxref("border-top-right-radius")}} property (see also border-top-right-radius.json) was supported in Firefox:

+ + + +

To represent this in the data, we used the following JSON:

+ +
"firefox": [
+  {
+    "version_added": "4",
+    "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0."
+  },
+  {
+    "prefix": "-webkit-",
+    "version_added": "49",
+    "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>."
+  },
+  {
+    "alternative_name": "-moz-border-radius-topright",
+    "version_added": "1",
+    "version_removed": "12"
+  }
+],
+ +

将变更推送回主仓库

+ +

在您添加完您的兼容性数据之后，您应该先用以下命令测试一下：

+ + + +

If it is looking OK, you then need to commit it and push it back up to your remote fork on GitHub. You can do this easily with terminal commands like this:

+ +
git add .
+git commit -m 'adding compat data for name-of-feature'
+git push
+ +

Now go to your remote fork (i.e. https://github.com/your-username/browser-compat-data) and you should see information about your push at the top of the files list (under "Your recently pushed branches"). You can create a pull request (starting the process of pushing this to the main repo) by pressing the "Compare & pull request" button, then following the simple prompts on the subsequent screen.

+ +

At this point, you just need to wait. A reviewer will review your pull request, and merge it with the main repo, OR request that you make changes. If changes are needed, make the changes and submit again until the PR is accepted.

+ +

将数据插入MDN页

+ +

Once your new data has been included in the main repo, you can start dynamically generating browser compat tables based on that data on MDN pages using the \{{Compat}} macro. This takes a single parameter, the dot notation required to walk down the JSON data and find the object representing the feature you want to generate the compat table for.

+ +

Above the macro call, to help other contributors finding their way, you should add a hidden text that is only visible in MDN contributors in edit mode:

+ +
<div class="hidden">
+<p>此页面上的兼容性表格由结构化数据生成。如果你想贡献数据，可以看看 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>并向我们发送 pull request.</p>
+</div>
+ +

As an example, on the {{httpheader("Accept-Charset")}} HTTP header page, the macro call looks like this: \{{Compat("http.headers.Accept-Charset")}}. If you look at the accept-charset.json file in the repo, you'll see how this is reflected in the JSON data.

+ +

As another example, The compat table for the {{domxref("VRDisplay.capabilities")}} property is generated using \{{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):

+ +
+ + +

{{Compat("api.VRDisplay.capabilities")}}

+ +
+

注意: 文件名通常与给予JSON结构内的接口的标签相匹配，但事实并非总是如此。 当宏调用生成表时，他们遍历所有文件，直到找到相关的JSON使用，所以文件名不是关键。 说到这一点，你应该始终尽可能直观地命名它们。

+
diff --git a/files/zh-cn/mdn/structures/index.html b/files/zh-cn/mdn/structures/index.html new file mode 100644 index 0000000000..aee298c70e --- /dev/null +++ b/files/zh-cn/mdn/structures/index.html @@ -0,0 +1,18 @@ +--- +title: 文档结构 +slug: MDN/Structures +tags: + - Landing + - MDN Meta + - NeedsTranslation + - Structures + - TopicStub +translation_of: MDN/Structures +--- +
{{MDNSidebar}}
+ +
{{IncludeSubnav("/zh-CN/docs/MDN")}}
+ +

在MDN里有各式各样的重复使用的文档结构，来使MDN文章中的内容有一致性的表现。这里的文章描述了这些结构。因此作为一名MDN的作者，你可以确认、应用并修改成适合于你写、编辑或翻译的文档。

+ +

{{LandingPageListSubPages()}}

diff --git a/files/zh-cn/mdn/structures/live_samples/index.html b/files/zh-cn/mdn/structures/live_samples/index.html new file mode 100644 index 0000000000..0b50a1b8f7 --- /dev/null +++ b/files/zh-cn/mdn/structures/live_samples/index.html @@ -0,0 +1,213 @@ +--- +title: 运行实例 +slug: MDN/Structures/Live_samples +tags: + - Guide + - Intermediate + - MDN Meta + - NeedsTranslation + - Structures + - TopicStub +translation_of: MDN/Structures/Live_samples +--- +
{{MDNSidebar}}

MDN 支持将文章中的示例代码转化为运行实例。运行实例可以包括 HTML、CSS、 JavaScript 的任意组合。注意，“运行”的实例是 非交互性 的。它们仅仅由代码示例生成，只是用来展示示例的输出效果。本文在JavaScript语法的基础上说明了该系统的集体使用。

+ +

运行实例系统如何工作

+ +

运行实例系统将所有代码整合为一个集合，再将这个集合融合到一个 HTML 文件中，然后在 内联框架{{HTMLElement("iframe")}} 中渲染这个文件。一个运行实例由两个部分构成：

+ + + +

一个代码块的集合，在此上下文中，以行级或块级元素（类似 {{HTMLElement("div")}} ）的 id作为标识。

+ + + +

宏使用一个特殊的 URL 来取得一个分组中的代码示例：http://url-of-page$samples/group-id。 group-id 指代码所在行级或者块级元素的id。用来展示运行结果的框架(或页面)会运行在沙盒中，在安全条件下实现任何想在网络上实现的功能。当然，在实践中，代码需要针对于包含它的页面，否则会被社区编辑移除。

+ +
+

注意：必须使用宏来展示运行实例的输出。为保安全，MDN 编辑器将会移除直接使用 <iframe> 标签的地方。

+
+ +

每个包含示例代码的 {{HTMLElement("pre")}}  段落都有一个 class 指示它由何种语言写成（HTML、CSS 或 JavaScript）。这些 class 的值是“brush: html”、“brush: css”或“brush: js”。这些 class 必须与代码匹配以被维基正确使用。一般情况下，当你在使用编辑器工具栏的语法高亮时候，这些属性会被自动添加。

+ +

运行实例系统由很多可用选项，我们会分解开来讲解。

+ +

运行实例宏

+ +

你可以用两种宏来展示实例：

+ + + +

在很多情况下，可以很便捷地使用以上两种宏 EmbedLiveSample 或 LiveSampleLink 。只要代码示例可以通过一个行级元素的id 或一个块级元素的id 的区分开，就可以简单的插入宏来实现功能。

+ +

页内运行实例宏

+ +
 \{{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}
+ +
+
block_ID
+
必需。包含示例代码的元素的 id 。保证 ID正确的最好的办法是在内容表中查看 URL。
+
width
+
可选。创建的 {{HTMLElement("iframe")}} 元素的宽度，以 px 为单位。若忽略该项，系统会使用一个合理的默认宽度。请注意，如果需要指定该项，那么必须同时指定高度。
+
height
+
可选。创建的 {{HTMLElement("iframe")}} 元素的高度，以 px 为单位。若忽略该项，系统会使用一个合理的默认高度。请注意，如果需要指定该项，那么必须同时指定宽度。如果仅仅指定了高度和宽度中的一个，那么系统会应用默认尺寸。
+
screenshot_URL
+
可选。截屏 URL 显示了运行实例的效果。对于用户浏览器尚未支持的新技术很有用，他们就可以看到结果的快照。如果指定该项，截屏会带着相关标题显示在运行实例之后。
+
page_slug
+
可选。包含示例的页面的代称。若忽略该项，示例将会从宏所在页面拉取。
+
+ +
    +
+ +

链接运行实例宏

+ +
 \{{LiveSampleLink(block_ID, link_text)}}
+ +
+
block_ID
+
必需。根据标题或段落的 ID 识别示例。保证正确使用 ID 最好的办法是在页面的目录中查找 URL。
+
link_text
+
链接地址文本。
+
+ +

使用运行实例系统

+ +

以下部分描述了一些运行实例系统的常见用例。

+ +

在所有这些用例中，必须点击编辑器的“保存更改”（将关闭编辑模式）才能看到运行实例。“预览变更”功能不可展示运行实例。

+ +

将片段转为运行实例

+ +

一个常见的用例是将 MDN 中已有代码片段转为运行实例。

+ +

准备代码示例

+ +

第一步是添加代码片段，或根据内容和标记确认已有片段可以成为运行实例。代码片段必须组成一个完整可运行的示例。比如，如果已有 CSS 片段，那么需要添加一段 HTML。

+ +

每段代码都需要包含在正确标记其语言的 {{HTMLElement("pre")}} 块中，每块中只能包含一种语言。多数情况下，这些步骤都没问题，不过再检查一遍总是好的。工具栏中 PRE 图标旁的按钮是一个提供选择语法的下拉框（语法高亮）。该选项除了设置语法高亮以外，还标记了代码片段在运行实例系统中的语言。

+ +
+

注意：每种语言的代码可以分布在几个 {{HTMLElement("pre")}} 块里，所有代码会被连接起来。这个特性允许一块代码对应一块简介。这样有利于制作教程，比如代码间夹杂着大量的注释。

+
+ +

所以确认代码块被正确标记为其所用语言，然后你可以继续了。

+ +
+

注意：当向MDN中粘贴内容时，请注意在粘贴带样式的内容时，可能会带来不需要的样式（比如复制高亮代码）。请尽量避免粘贴带样式的内容，在必须的情况下，请在源码模式中删除不需要的样式，或者使用“粘贴为纯文本”。

+
+ +

插入运行实例宏

+ +

当代码准备好并被正确标记之后，需要插入宏来创建 iframe。

+ +
    +
  1. 点击“插入运行实例框架”按钮（），将会打开一个对话框可以配置。
    2. +
  2. +

    在 Document 下方，输入包含实例的文章标题。默认是当前正被编辑的文章，但是可以被更改为 MDN 中的其它文章。这项特性允许在不同的页面中重用实例。（如果输入文字，将会出现一个部分匹配输入内容文章列表，可以从中选取需要的文章。）

    +
    3. +
  3. 在 Sections in Document 选项中，选取需要将包含实例的部分。
    4. +
  4. 点击 OK 按钮，生成并将宏插入到文章中，宏调用代码看起来是这样的：
    + \{{ EmbedLiveSample('Live_sample_demo') }}
    5. +
+ +

增加新的运行实例

+ +

在编辑一个新的一页需要插入运行实例时，编辑器做更多工作。

+ +
    +
  1. 点击 Insert Code Sample Template 按钮（），将会出现这样的对话框。
    +
    2. +
  2. 输入运行实例的标题，请确保标题对于当前页面是有意义的。
    3. +
  3. 点击 OK。会创建一个新的标题，还有一个空的代码框，可以输入 HTML、CSS 或 JavaScript。
    4. +
  4. 删除不需要的标题的代码框。
    5. +
  5. 输入代码
    6. +
+ +

查找需要更新的示例

+ +

当查询实例的时候，有三种可能的更新方式。

+ + + +
+

注意：如果发现包含需要更新到运行实例系统的文章，请为文章增加标签“ NeedsLiveSample ”。

+
+ +

查找需要转为运行实例的示例

+ +

MDN 上有很多老版本的并且使用运行实例系统的示例。我们希望可以将多数示例更新到运行实例。这将会提升网站的一致性和可用性。在访问 MDN 时，你一定经常看到这些例子。然而，很难如果你想要找到某个特定的例子来更新，不过有一些方法可以试一试。

+ + + +

运行实例演示

+ +

这部分是使用“插入运行实例模板”按钮插入运行实例标题和代码块的结果。每种语言可以有不止一个代码块。同样也不需要有特定的顺序，所有代码会被混合匹配。

+ +

可以选取删除任何部分。如果不需要脚本，那么删掉脚本的标题和代码块就可以了。同样，也可以删掉其余任何代码块。

+ +

代码模板插入之后，可以增加一些代码，也可以加入一些注释。

+ +

HTML

+ +

这段 HTML 代码创建了一个段落和几个 DIV 可以展示信息。

+ +
<p>A simple example of the live sample system in action.</p>
+<div class="box">
+  <div id="item">Hello world!</div>
+</div>
+
+ +

CSS

+ +

这段 CSS 代码为信息增加样式。

+ +
.box {
+  width: 200px;
+  height: 100 px;
+  border-radius: 6px;
+  background-color: #ffaabb;
+}
+
+#item {
+  width: 100%;
+  font-weight: bold;
+  text-align: center;
+  font-size: 2em;
+}
+
+ +

JavaScript

+ +

这段代码很简单，只是增加了一个点击事件来弹出信息。

+ +
var el = document.getElementById('item');
+el.onclick = function() {
+  alert('Owww, stop poking me!');
+}
+
+ +

这里通过\{{EmbedLiveSample('Live_sample_demo')}}来展示上面实例运行的结果。

+ +

{{EmbedLiveSample('Live_sample_demo')}}

+ +

这是使用外链宏\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}来展示实例运行的结果。

+ +

{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}的集合

diff --git a/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html b/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html new file mode 100644 index 0000000000..d0ca0069fb --- /dev/null +++ b/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html @@ -0,0 +1,31 @@ +--- +title: A simple demo of a live code sample +slug: MDN/Structures/Live_samples/Simple_live_sample_demo +translation_of: MDN/Structures/Live_samples/Simple_live_sample_demo +--- +
{{MDNSidebar}}

The_example

+ +

This is a very simple example showing you how to do a live demo in MDN. For more information, see Live samples.

+ +
<form>
+  <label>Try me<input type="text" name="name"></label>
+  <input type="submit" value="go">
+</form>
+ +
form {
+  border-radius: 10px;
+  background: powderblue;
+}
+ +
var f = document.querySelector('form');
+
+f.addEventListener('submit', function(ev) {
+  ev.preventDefault();
+  document.querySelectorAll('input')[1].value = 'sending';
+}, false);
+ +

{{ EmbedLiveSample('The_example', '', '', '') }}

+ +

 

+ +

 

diff --git a/files/zh-cn/mdn/structures/macros/custom_macros/index.html b/files/zh-cn/mdn/structures/macros/custom_macros/index.html new file mode 100644 index 0000000000..3809bb2094 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/custom_macros/index.html @@ -0,0 +1,222 @@ +--- +title: 常用的宏 +slug: MDN/Structures/Macros/Custom_macros +tags: + - CSS + - 参考 + - 宏 + - 结构 +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +
{{MDNSidebar}}
+ +

本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见使用宏和使用链接宏。对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见其它宏。这里也有一份 MDN 上所有宏的完整列表。

+ +

对于适合你使用的样式，另见 CSS 样式指南。

+ +

链接

+ +

创建一个单独的超链接

+ +

通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的链接按钮创建链接。

+ + + +

链接到参考文档页面

+ +

有各种宏用来链接到 MDN 上特定参考区域里的页面。

+ + + +

链接到漏洞和互联网中继聊天（IRC）

+ + + +

用于多页面指南的导航帮助

+ +

{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。

+ +

代码示例

+ +

实样

+ + + +

附上的示例文件

+ + + +

侧边栏组

+ +

There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。

+ + + +

（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）

+ +

通用格式化

+ +

API 文档的行内指示器

+ +

{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。

+ +

用法: \{{optional_inline()}} 或 \{{ReadOnlyInline()}} 。示例：

+ +
+
isCustomObject {{ReadOnlyInline()}}
+
如果为真，指示该对象是一个自定义对象。
+
parameterX {{ optional_inline() }}
+
Blah blah blah...
+
+ +

状态和兼容性指示器

+ +

没有附加参数的行内指示器

+ +

非标准的

+ +

{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。

+ +
语法
+ +

\{{non-standard_inline}}

+ +
示例
+ + + +

实验性的

+ +

{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。

+ +
语法
+ +

\{{experimental_inline}}

+ +
示例
+ + + +

提供明确技术的指示器

+ +

在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。

+ +

不赞成的

+ +

{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。注意：“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。

+ +

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

+ +
语法
+ +

\{{deprecated_inline}} 或 \{{deprecated_inline("gecko5")}}

+ +
示例
+ + + +

已废弃的

+ +

{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。

+ +

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

+ +
语法
+ +

\{{obsolete_inline}} 或 \{{obsolete_inline("js1.8.5")}}

+ +
示例
+ + + +

模板徽标

+ +

这些宏大多数被用于 WebAPI 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。

+ +

页面或区域标头指示

+ +

这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。

+ + + +

指示一个功能在Web workers中可用

+ +

 {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在Web worker 上下文中可用。

+ +

版本信息宏

+ +

这些宏被用来指示这个语段只与一个产品的特定版本有关。

+ + + +
    +
+ +
    +
diff --git a/files/zh-cn/mdn/structures/macros/index.html b/files/zh-cn/mdn/structures/macros/index.html new file mode 100644 index 0000000000..4ddb72e576 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/index.html @@ -0,0 +1,48 @@ +--- +title: Macros +slug: MDN/Structures/Macros +tags: + - Guide + - Kuma + - KumaScript + - MDN Meta + - Structures +translation_of: MDN/Structures/Macros +--- +
{{MDNSidebar}}
+ +

Kuma 平台为 MDN 提供了强大的宏系统——KumaScript，使得 MDN 能够自动地去做各种东西。本文提供一些信息以便大家知道如何使用 MDN 上的文章内的宏。

+ +

鉴于本文只是 KumaScript 的简介，KumaScript 指南提供了更深入的内容。

+ +

宏是如何实现的

+ +

MDN使用的Macros(宏)是基于Node.js执行环境，并在服务端执行运行。这里包括了大量的代码库，另外对此还提供了丰富的wiki说明文档内容。如果你希望能学习到更多的内容，可以查看 KumaScript 指南， KumaScript reference 则提供了更多关于这些代码库和KumaScript的API的实现机理。

+ +

在文章中使用宏

+ +

要实际使用宏，只需将对宏的调用括在一对双括号中，其参数（如果有）括在括号中;如下：

+ +
\{{macroname(parameter-list)}}
+ +

关于宏调用的一些注意事项：

+ + + +

宏被高度缓存;对于任何一组输入值（参数和环境值，例如运行宏的URL），结果都会被存储和重用。这意味着宏仅在输入发生变化时才实际运行。

+ +
+

注意: 您可以通过在浏览器中强制刷新页面（即转移重新加载）来强制重新评估页面上的所有宏。

+
+ +

宏可以像插入更大的文本块或从MDN的另一部分交换内容一样简单，也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。

+ +

您可以在Commonly-used macros页面上阅读我们最常用的宏;另外，这里有complete list of all macros。大多数宏都有内置的文档，作为顶部的注释。

+ +

{{EditorGuideQuicklinks}}

-- cgit v1.2.3-54-g00ecf