diff options
Diffstat (limited to 'files/zh-cn/mdn/structures')
6 files changed, 1032 insertions, 0 deletions
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 +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p class="summary"><span class="seoSummary">MDN 为我们的开放网页文档提供了兼容性表格的标准格式; 它是对比所有浏览器之间，包含 DOM，HTML，CSS，JavaScript，SVG 等技术的文档。</span>本文将介绍如何使用我们的功能将兼容性数据添加到MDN页面。</p> + +<div class="warning syntaxbox"> +<p><strong>重要</strong>: <strong><em>数据的生成方式已经发生了变更</em></strong>。过去，我们的表格直接嵌入在页面中，而且数据是手动填写的。这样效率很低，难以维护，而且使得数据不够灵活，不便更新。所以我们正在把我们的兼容性表格迁移到一个数据 repo 中（<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>）并且改为使用程序化的方式生成它。<br> + <br> + 本指南中，我们撰写了关于如何向 MDN 添加新的兼容性数据的文档，但是我们仍然保留了旧的方法来保证旧文档的兼容性表格可用：正如你所见，手动输入的表格依然存在于 MDN 上。如果你有必要使用旧方法的话，可以参考这篇文章：<a href="/en-US/docs/MDN/Contribute/Structures/Old_compatibility_tables">Old compatibility tables</a>。</p> +</div> + +<div class="note"> +<p><strong>注意：</strong>如果您需要本指南任何步骤的帮助，欢迎您在<a href="https://discourse.mozilla-community.org/c/mdn">MDN论坛</a>上与我们联系。</p> +</div> + +<h2 id="如何访问_data_repo">如何访问 data repo</h2> + +<p>数据存储在一个 GitHub repo 中，到 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 查看。想要访问它，你必须拥有一个 GitHub 账号，fork浏览器兼容数据仓库到你自己的账户，然后克隆你的fork到你的本地机器。</p> + +<h2 id="选择要贡献的数据类型">选择要贡献的数据类型</h2> + +<p>首先，确定一下你想为何种 Web 技术贡献兼容性数据。可以是一个 HTML 元素、CSS 属性、JS 语法或者 JS API 接口。我们鼓励您贡献 API 接口的数据, 因为已经有人在贡献 HTML、JS 和 CSS 的数据了。你可以在表格 <a href="https://docs.google.com/spreadsheets/d/1ivgyPBr9Lj3Wvj5kyndT1rgGbX-pGggrxuMtrgcOmjM/edit#gid=926663640">Browser Compat Data migration</a> 中查看各个需要添加兼容性数据的 Web 技术的数据状态。</p> + +<p>电子表格的使用步骤如下:</p> + +<ol> + <li>直接挑选一个还未开始或者还未完成数据录入的功能点，在“Who”一栏中填入你的名字, 最好能够和你的MDN用户名保持一致，以便我们在需要联系你的时候能够查找到你的邮件地址.</li> + <li>如果该功能点不在表格上，那么你可以参照现有的格式在合适的位置上加一行。注意要使用同等的粒度（例如，HTML以标签元素为单位、CSS以选择器或者属性值为单位、JS以对象为单位、JS API以特定的接口为单位）</li> + <li>当你已经开始录入数据的时候，把对应状态栏的下拉选项置于“In progress”（进行中）状态。</li> + <li>一旦添加完数据，并且向主仓库提交了一个拉取请求（pull request），那么把对应状态栏的下拉选项置于“PR done”状态。</li> + <li>当你的数据已经成功合并到主分支，或者已经添加到npm包里面的时候，请尽量更新对应的状态栏到相应的状态。</li> + <li>当你更新了你的功能文档页面，并且使用新的脚步命令使其可以在每一个页面都可以动态的生成合适的数据表格的时候，你就需要在电子表格中修改对应功能的状态为“Article updated”（文章已更新）。这意味着你已经完成了这一功能的所有数据录入工作。</li> +</ol> + +<h2 id="准备添加数据">准备添加数据</h2> + +<p>在添加新数据之前，你应该保证您的 fork 是主 repo 的最新版本（它们应包含相同的内容）。在您的 fork 里添加一个包含您的更改的分支，然后把它pull到您本地的仓库，这样你就可以开始贡献了：</p> + +<p>下面是更新您的分支的一个简单方法：</p> + +<h3 id="将浏览器兼容信息的主_repo_添加到远端服务器列表中">将浏览器兼容信息的主 repo 添加到远端服务器列表中</h3> + +<p>在您的终端或命令行中进入您的fork的本地仓库，用以下命令将（服务器上的）主 repo 添加到远端服务器列表中（您只需执行以下命令一次）：</p> + +<pre class="brush: bash notranslate">git remote add upstream https://github.com/mdn/browser-compat-data.git</pre> + +<p><span id="result_box" lang="zh-CN">如果您不确定自己是否做到了这一点</span>， 您可以检查您仓库已经在用的远端服务器列表：</p> + +<pre class="brush: bash notranslate">git remote -v</pre> + +<h3 id="让您的分支与服务器上的内容同步">让您的分支与服务器上的内容同步</h3> + +<p><span id="result_box" lang="zh-CN"><span>现在，只要您想更新您</span></span><span lang="zh-CN"><span>的分支，</span></span><span id="result_box" lang="zh-CN"><span>您</span></span><span lang="zh-CN"><span>就可以这样做：</span></span></p> + +<ol> + <li> + <p>确定您已切换到在主分支：</p> + + <pre class="brush: bash notranslate">git checkout master</pre> + </li> + <li> + <p>使用以下命令来获取服务器上最新的内容：</p> + + <pre class="brush: bash notranslate">git fetch upstream</pre> + </li> + <li> + <p>用rebase将主仓库的内容合并到您的master分支中：</p> + + <pre class="brush: bash notranslate">git rebase upstream/master</pre> + </li> + <li> + <p>将来自主 repo 的更新 push 回您自己的 repo 中：</p> + + <pre class="brush: bash notranslate">git push -f</pre> + </li> +</ol> + +<h3 id="创建您用来工作的分支：">创建您用来工作的分支：</h3> + +<p>接下来，打开您在服务器上的fork（它的地址可能是<code>https://github.com/<em>your-username</em>/browser-compat-data</code>）并且创建一个新分支来存储您的改动。步骤如下：</p> + +<ol> + <li>点击"Branch: Master"按钮；</li> + <li>在"Find or create a branch..."文本输入框中输入一个新的分支名；</li> + <li>点击下方出现的"Create branch <em>name-of-branch</em> from Master"按钮。</li> +</ol> + +<p>举个例子，如果您想补充WebVR API的信息，您可以创建一个名为“webvr”的分支.</p> + +<h3 id="切换到新分支">切换到新分支</h3> + +<p>此时，回到您的终端或命令行，用以下命令将您的新分支同步到您本地的fork中：</p> + +<pre class="brush: bash notranslate">git pull</pre> + +<p>现在用以下命令切换到您的新分支</p> + +<pre class="brush: bash notranslate">git checkout <em>-b name-of-branch</em></pre> + +<p>现在您可以开始进行您对浏览器兼容信息的补充和修改了。</p> + +<h2 id="添加数据">添加数据</h2> + +<p>为添加新的数据，您需要新建文件以存储您的兼容性数据。对于不同技术的数据，您需要创建的文件也有所不同：</p> + +<ul> + <li><a href="/zh-CN/docs/Web/HTML/">HTML</a>：被包含在 <a href="https://github.com/mdn/browser-compat-data/tree/master/html/elements">browser-compat-data/html/elements</a> 中，每个HTML元素对应一个文件。文件需要以元素的小写的名称命名，例如<code>div.json</code>。</li> + <li><a href="/zh-CN/docs/CSS">CSS</a>：每个CSS属性或选择器对应一个文件。它们被包含在对应的目录中（请参考 <a href="https://github.com/mdn/browser-compat-data/tree/master/css">browser-compat-data/css</a>）。文件需要以CSS特性的小写的名称命名，如<code>background-color.json</code>或者<code>hover.json</code>。</li> + <li><a href="/zh-CN/docs/JavaScript">JS</a>：被包含在 <a href="https://github.com/mdn/browser-compat-data/tree/master/javascript/builtins">browser-compat-data/javascript/builtins</a> 中，每个JavaScript对象对应一个文件。文件要以JavaScript对象的准确名称命名，保留其大小写，如 <code>Date.json</code> 或 <code>InternalError.json</code>。</li> + <li><a href="/zh-CN/docs/Web/API">API</a>：API中的每个接口对应一个文件。它们在 <a href="https://github.com/mdn/browser-compat-data/tree/master/api">browser-compat-data/api</a> 中。每个文件要以接口的准确名称命名，保留其大小写，例如WebVR API的文件为<code>VRDisplay.json</code>，<code>VRDisplayCapabilities.json</code>，等等。</li> +</ul> + +<div class="note"> +<p><strong>注意：您会留意到，该仓库还包含了<a href="/en-US/Add-ons/WebExtensions">浏览器拓展</a>和</strong><a href="/en-US/docs/Web/HTTP">HTTP</a><strong>的数据。</strong>These data sets are basically finished as they stand, but more features may need to be added in the future.</p> +</div> + +<p>你创建的每个文件都需要跟随定义在我们repo的schema中的这些模板的规定。你可以参考<a href="https://github.com/mdn/browser-compat-data/blob/master/compat-data-schema.md">详细的模板描述</a>。</p> + +<h3 id="基本的兼容性数据的结构">基本的兼容性数据的结构</h3> + +<p>让我们来看一下如下例子。一个CSS属性JSON文件需要以下的结构：</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "border-width": { + "__compat": { + ... + } + } + } + } +}</pre> + +<p>首先有一个<code>css</code>对象，其中包含了一个<code>properties</code>对象。每个您要设定兼容性数据的特性都对应一个<code>properties</code>对象中的成员。而每一个这些成员都有一个<code>__compat</code>成员，<code>__compat</code>成员中则是实际的数据。</p> + +<p>以上的数据能在 <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">browser-width.json</a> 文件中找到——可将这与 <a href="/zh-CN/docs/Web/CSS/border-width#Browser_compatibility">MDN上渲染后的浏览器兼容性</a> 相比较。</p> + +<p>对于其他类型特性，写法是类似的，但对象的名称不同：</p> + +<ul> + <li>对于CSS选择器，它与CSS属性的写法基本相同，不同之处在于顶级对象结构是是 <code>css.selectors</code> 而不是<code>css.properties</code>. 请以 <a href="https://github.com/mdn/browser-compat-data/blob/master/css/selectors/cue.json">cue.json</a> 作为参考示例。</li> + <li>对于HTML数据，它的写法基本相同，不同之处在于顶级对象结构是<code>html.elements</code>。请以<code>article.json</code>作为参考示例。</li> + <li>JS内置对象对应的顶级结构是<code>javascript.builtins</code>；请以 <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Array.json">Array.json</a> 作为参考示例。</li> +</ul> + +<div> +<p>在一个HTML、CSS和JS页面中，通常您只需要有一个特性。API则有些不同——它们总是包含多个子特性 （参见下边的 {{anch("Sub-features")}}）。</p> + +<h3 id="一个特性中的基础结构">一个特性中的基础结构</h3> + +<p>在一个特性的<code>__compat</code>成员中，您需要包含以下成员：</p> + +<ul> + <li><code>mdn_url</code>: MDN上这个特性的页面的URL。注意，这个URL不可以带上本地化文件夹名称，例如：是 <code>/docs/...</code> 而不是 <code>/docs/en-US/...</code> （或者其他）。本地化文件夹名称会在页面加载时被添加。</li> + <li><code>support</code>: 所有不同浏览器对这个特性的浏览器支持的信息。</li> + <li><code>status</code>: Contains members reporting the standards track status of this feature.</li> +</ul> + +<p>浏览器成员名称在架构里被定义（参见 <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#browser-identifiers">浏览器标识符</a>）。你应该使用现有定义的标识符的完整列表。如果你希望添加其他浏览器，请先联系我们，因为这可能会产生广泛的影响，不应该在未经认真考虑就这么做。</p> + +<p>在一个基本的浏览器兼容数据文件中，你只需要在浏览器标识符成员仲包含"version_added" （以下我们会说到{{anch("Advanced cases")}}）。其他你可能使用的值还包括： </p> + +<ul> + <li>一个版本号：如果你知道一个浏览器开始支持这个特性的准确版本，用一个字符串表述版本号，例如“47”。 </li> + <li><code>true</code>: 如果一个浏览器支持这个特性，但你不知道准确的版本号，取值用<code>true</code>。</li> + <li><code>false</code>: 如果一个浏览器支持这个特性，取值用 <code>false</code>。</li> + <li><code>null</code>: 如果一个浏览器支持这个特性，取值用 <code>null</code>。</li> +</ul> + +<p>在 <code>status</code> 成员中，包含三个子成员：</p> + +<ul> + <li> <code>"experimental"</code>: 如果这个特性是<a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">试验性</a>的，取值为 <code>true</code> ，否则为 <code>false</code> 。</li> + <li><code>"standard_track"</code>: 如果这个特性是个在某些规范里的标准的属性（最常见的是W3C/WHATWG，但有其他规范如Khronos或TC39等），取值为<code>true</code> ，否则为 <code>false</code> 。</li> + <li><code>"deprecated"</code>: 如果这个特性已经<a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">过时</a>，取值为<code>true</code> ，否则为 <code>false</code> 。</li> +</ul> + +<p>作为例子，以下是 <a href="/en-US/docs/Web/CSS/border-width#Browser_compatibility">border-width</a> 特性的数据 (参见 <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a>) ：</p> + +<pre class="brush: json notranslate">"__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 + } +}</pre> + +<h4 id="添加描述说明">添加描述说明</h4> + +<p>There is a fourth, optional, member that can go inside the __compat member — <code>description</code>. 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:</p> + +<pre class="brush: json notranslate">{ + "api": { + "AbortController": { + "__compat": { + ... + }, + "AbortController": { + "__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController", + "description": "<code>AbortController()</code> constructor", + "support": { + ... + } + } + } + + ... etc. + } + } +}</pre> + +<h3 id="子特性">子特性</h3> + +<p>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.</p> + +<p>As an example, see the <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/background-color.json">compat data</a> and <a href="/en-US/docs/Web/CSS/background-color">corresponding MDN page</a> for the <code>background-color</code> property. The basic support exists inside the <code>__compat</code> object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own <code>__compat</code> object.</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "background-color": { + "__compat": { + ... + }, + "alpha_ch_for_hex": { + "__compat": { + ... + }, + } + } + } + } +}</pre> + +<p>For an API, you've got the top two levels defined as <code>api.<em>name-of-the-interface</em></code>, then a top-level <code>__compat</code> 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:</p> + +<pre class="brush: json notranslate">{ + "api": { + "VRDisplay": { + "__compat": { + ... + }, + "cancelAnimationFrame": { + "__compat": { + ... + } + }, + "capabilities": { + "__compat": { + ... + } + }, + + ... etc. + + } + } +}</pre> + +<p>See <a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a> for a full example.</p> +</div> + +<h2 id="添加数据：高级场景">添加数据：高级场景</h2> + +<p>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.</p> + +<h3 id="Including_a_footnote">Including a footnote</h3> + +<p>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 <a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a>) (at the time of writing) had a footnote "<span class="pl-s">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:</span></p> + +<pre class="brush: json notranslate">"chrome_android": { + "version_added": true, + "notes": "Currently supported only by Google Daydream." +}</pre> + +<h3 id="包含浏览器厂商的前缀">包含浏览器厂商的前缀</h3> + +<p>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浏览器中要用<code>-moz-</code>前缀才被支持，要在兼容性数据中指明这一点，您需在对应的"firefox"子成员中增加一个"prefix"子成员。它看起来是这样的：</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": true, + "prefix": "-moz-" +}</pre> + +<h3 id="Including_browser_preferences_or_flags">Including browser preferences or flags</h3> + +<p>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.</p> + +<p>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:</p> + +<ul> + <li>"type": The type of flag or pref this is. The most common value is "preference", which is set inside the browser (for example, using <code>about:config</code> in Firefox, or <code>chrome://flags</code> in Chrome), but you might also sometimes use a value of <span class="pl-s"><span class="pl-pds">"</span>compile_flag<span class="pl-pds">", which is a preference set when the browser build is compiled.</span></span></li> + <li>"name": This is a string representing the name of the preference that needs to have a value set on it. For example, "Enable Experimental Web Platform Features" is a preference that exists in Chrome, found in <code>chrome://flags</code>.</li> + <li>"value_to_set": This is a string representing the value that needs to be set on the preference, for example "true".</li> +</ul> + +<p>So to add a preference/flag to the Chrome support for a feature, you'd do something like this:</p> + +<pre class="brush: json notranslate">"chrome": { + "version_added": "50", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] +},</pre> + +<p>If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example:</p> + +<pre class="brush: json notranslate">"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" + } + ] +},</pre> + +<h3 id="包含特性不再被支持的版本">包含特性不再被支持的版本</h3> + +<p>有时一个特性在浏览器的某个版本被加进去，然后又因为该特性过时而被被移除掉。这可以在"version_removed"子成员中体现。该子成员是一个代表特性被移除的版本的字符串。例如：</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "35", + "version_removed": "47", +},</pre> + +<h3 id="Including_multiple_support_points_for_the_same_browser_entry">Including multiple support points for the same browser entry</h3> + +<p>Sometimes you'll want to add multiple support data points for the same browser inside the same feature.</p> + +<p>As an example, the {{cssxref("text-align-last")}} property (see also <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/text-align-last.json">text-align-last.json</a>) was added to Chrome in version 35, supported behind a pref.</p> + +<p>The support mentioned above was then removed in version 47; also in version 47, support was added for <code>text-align-last</code> enabled by default.</p> + +<p>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:</p> + +<pre class="brush: json notranslate">"chrome": [ + { + "version_added": "47" + }, + { + "version_added": "35", + "version_removed": "47", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] + } +],</pre> + +<div class="note"> +<p><strong>Note</strong>: 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.</p> +</div> + +<h3 id="包含一个可选的名字">包含一个可选的名字</h3> + +<p>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.</p> + +<p>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.</p> + +<div class="note"> +<p><strong>Note</strong>: The alternative name might not be an exact alias — it might have differing behaviour to the standard version.</p> +</div> + +<p>Let's look at an example. The {{cssxref("border-top-right-radius")}} property (see also <a href="https://github.com/mdn/browser-compat-data/blob/2a0cc3f6bb17aa4345441bed47a059dffd847793/css/properties/border-top-right-radius.json">border-top-right-radius.json</a>) was supported in Firefox:</p> + +<ul> + <li>From version 4 onwards with the standard name <code>border-top-right-radius</code>.</li> + <li>From version 49 onwards with a <code>-webkit-</code> prefix, for browser compatibility purposes.</li> + <li>From version 1 onwards with the alternative name <code>-moz-border-radius-topright</code>. Support for this alias was removed in version 12.</li> +</ul> + +<p>To represent this in the data, we used the following JSON:</p> + +<pre class="brush: json notranslate">"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" + } +],</pre> + +<h2 id="将变更推送回主仓库">将变更推送回主仓库</h2> + +<p>在您添加完您的兼容性数据之后，您应该先用以下命令测试一下：</p> + +<ul> + <li><code>npm run lint</code> — 测试所有兼容性数据以确保JSON的格式和书写风格正确，例如正确的缩进和没有遗漏逗号等等。该命令会打印出一个很长的文件名和测试结果的列表；if an error is found, the linter will throw an error on the file it is found in, giving you useful debugging info like line number, error message, etc.</li> + <li><code>npm run show-errors</code> — validates the JSON against the data schema, and highlights errors such as invalid browser version numbers being used.</li> + <li><code>npm run render 'dotted.path.to.feature'</code> — allows you to preview the markup for the compat table for a data file in the repo. As an example, <code>npm run render 'css.properties.background'</code> shows the table markup for the {{cssxref("background")}} property.</li> +</ul> + +<p>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:</p> + +<pre class="brush: bash notranslate">git add . +git commit -m 'adding compat data for name-of-feature' +git push</pre> + +<p>Now go to your remote fork (i.e. <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) 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.</p> + +<p>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.</p> + +<h2 id="将数据插入MDN页">将数据插入MDN页</h2> + +<p>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.</p> + +<p>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:</p> + +<pre class="brush: html notranslate"><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></pre> + +<p>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 <a href="https://github.com/mdn/browser-compat-data/blob/master/http/headers/accept-charset.json">accept-charset.json</a> file in the repo, you'll see how this is reflected in the JSON data.</p> + +<p>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):</p> + +<hr> +<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> + +<p>{{Compat("api.VRDisplay.capabilities")}}</p> + +<div class="note"> +<p><strong>注意</strong>: 文件名通常与给予JSON结构内的接口的标签相匹配，但事实并非总是如此。 当宏调用生成表时，他们遍历所有文件，直到找到相关的JSON使用，所以文件名不是关键。 说到这一点，你应该始终尽可能直观地命名它们。</p> +</div> 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 +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p>在MDN里有各式各样的重复使用的文档结构，来使MDN文章中的内容有一致性的表现。这里的文章描述了这些结构。因此作为一名MDN的作者，你可以确认、应用并修改成适合于你写、编辑或翻译的文档。</p> + +<p>{{LandingPageListSubPages()}}</p> 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 +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN 支持将文章中的示例代码转化为运行实例。运行实例可以包括 HTML、CSS、 JavaScript 的任意组合。</span>注意，“运行”的实例是<em> 非交互性 </em>的。它们仅仅由代码示例生成，只是用来展示示例的输出效果。本文在JavaScript语法的基础上说明了该系统的集体使用。</p> + +<h2 id="运行实例系统如何工作">运行实例系统如何工作</h2> + +<p>运行实例系统将所有代码整合为一个集合，再将这个集合融合到一个 HTML 文件中，然后在 内联框架{{HTMLElement("iframe")}} 中渲染这个文件。一个运行实例由两个部分构成：</p> + +<ul> + <li>一个代码块组成的集合</li> + <li>一个调用（创建的框架或链接）该代码块结果的宏</li> +</ul> + +<p>一个代码块的集合，在此上下文中，以行级或块级元素（类似 {{HTMLElement("div")}} ）的 id作为标识。</p> + +<ul> + <li>如果这个 id 属于一个块级元素，该集合将包含该块元素包含范围内的所有代码。</li> + <li>如果这个编号属于一个行级元素，该集合将包含本行级元素之后到下个同级行级元素之前的所有代码。请注意，子元素下的代码块也会被包含，如果不希望这样的效果，可以使用块级元素的id。</li> +</ul> + +<p>宏使用一个特殊的 URL 来取得一个分组中的代码示例：<code>http://<em>url-of-page</em>$samples/<em>group-id</em></code>。 <code>group-id</code> 指代码所在行级或者块级元素的id。用来展示运行结果的框架(或页面)会运行在沙盒中，在安全条件下实现任何想在网络上实现的功能。当然，在实践中，代码需要针对于包含它的页面，否则会被社区编辑移除。</p> + +<div class="note"> +<p><strong>注意：</strong><strong>必须</strong>使用宏来展示运行实例的输出。为保安全，MDN 编辑器将会移除直接使用 <code><iframe></code> 标签的地方。</p> +</div> + +<p>每个包含示例代码的 {{HTMLElement("pre")}} 段落都有一个 class 指示它由何种语言写成（HTML、CSS 或 JavaScript）。这些 class 的值是“brush: html”、“brush: css”或“brush: js”。这些 class 必须与代码匹配以被维基正确使用。一般情况下，当你在使用编辑器工具栏的语法高亮时候，这些属性会被自动添加。</p> + +<p>运行实例系统由很多可用选项，我们会分解开来讲解。</p> + +<h3 id="运行实例宏">运行实例宏</h3> + +<p>你可以用两种宏来展示实例：</p> + +<ul> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a></code></span> 将一个运行实例嵌入到页面中</li> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> 创建一个链接，在新的页面中打开运行实例</li> +</ul> + +<p>在很多情况下，可以很便捷地使用以上两种宏 <span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a></code></span> 或 <span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> 。只要代码示例可以通过一个行级元素的id 或一个块级元素的id 的区分开，就可以简单的插入宏来实现功能。</p> + +<h4 id="页内运行实例宏">页内运行实例宏</h4> + +<pre class="syntaxbox notranslate"> \{{EmbedLiveSample(<em>block_ID</em>, <em>width</em>, <em>height</em>, <em>screenshot_URL</em>, <em>page_slug</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>必需。包含示例代码的元素的 id 。保证 ID正确的最好的办法是在内容表中查看 URL。</dd> + <dt>width</dt> + <dd>可选。创建的 {{HTMLElement("iframe")}} 元素的宽度，以 <code>px</code> 为单位。若忽略该项，系统会使用一个合理的默认宽度。请注意，如果需要指定该项，那么<strong>必须</strong>同时指定高度。</dd> + <dt>height</dt> + <dd>可选。创建的 {{HTMLElement("iframe")}} 元素的高度，以 <code>px</code> 为单位。若忽略该项，系统会使用一个合理的默认高度。请注意，如果需要指定该项，那么<strong>必须</strong>同时指定宽度。如果仅仅指定了高度和宽度中的一个，那么系统会应用默认尺寸。</dd> + <dt>screenshot_URL</dt> + <dd>可选。截屏 URL 显示了运行实例的效果。对于用户浏览器尚未支持的新技术很有用，他们就可以看到结果的快照。如果指定该项，截屏会带着相关标题显示在运行实例之后。</dd> + <dt>page_slug</dt> + <dd>可选。包含示例的页面的代称。若忽略该项，示例将会从宏所在页面拉取。</dd> +</dl> + +<ol> +</ol> + +<h4 id="链接运行实例宏">链接运行实例宏</h4> + +<pre class="syntaxbox notranslate"> \{{LiveSampleLink(<em>block_ID</em>, <em>link_text</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>必需。根据标题或段落的 ID 识别示例。保证正确使用 ID 最好的办法是在页面的目录中查找 URL。</dd> + <dt>link_text</dt> + <dd>链接地址文本。</dd> +</dl> + +<h2 id="使用运行实例系统">使用运行实例系统</h2> + +<p>以下部分描述了一些运行实例系统的常见用例。</p> + +<p>在所有这些用例中，必须点击编辑器的“<strong>保存更改</strong>”（将关闭编辑模式）才能看到运行实例。“预览变更”功能不可展示运行实例。</p> + +<h3 id="将片段转为运行实例">将片段转为运行实例</h3> + +<p>一个常见的用例是将 MDN 中已有代码片段转为运行实例。</p> + +<h4 id="准备代码示例">准备代码示例</h4> + +<p>第一步是添加代码片段，或根据内容和标记确认已有片段可以成为运行实例。代码片段必须组成一个完整可运行的示例。比如，如果已有 <code>CSS</code> 片段，那么需要添加一段 <code>HTML</code>。</p> + +<p>每段代码都需要包含在正确标记其语言的 {{HTMLElement("pre")}} 块中，每块中只能包含一种语言。多数情况下，这些步骤都没问题，不过再检查一遍总是好的。工具栏中<strong> <code>PRE</code> </strong>图标旁的按钮是一个提供选择语法的下拉框（语法高亮）。该选项除了设置语法高亮以外，还标记了代码片段在运行实例系统中的语言。</p> + +<div class="note"> +<p><strong>注意：</strong>每种语言的代码可以分布在几个 {{HTMLElement("pre")}} 块里，所有代码会被连接起来。这个特性允许一块代码对应一块简介。这样有利于制作教程，比如代码间夹杂着大量的注释。</p> +</div> + +<p>所以确认代码块被正确标记为其所用语言，然后你可以继续了。</p> + +<div class="note"> +<p><span style="font-size: 14px; line-height: 21px;"><strong>注意：</strong></span>当向MDN中粘贴内容时，请注意在粘贴带样式的内容时，可能会带来不需要的样式（比如复制高亮代码）。请尽量避免粘贴带样式的内容，在必须的情况下，请在源码模式中删除不需要的样式，或者使用“粘贴为纯文本”。</p> +</div> + +<h4 id="插入运行实例宏">插入运行实例宏</h4> + +<p>当代码准备好并被正确标记之后，需要插入宏来创建 <code>iframe</code>。</p> + +<ol> + <li>点击“<strong>插入运行实例框架</strong>”按钮（<img alt="" src="https://mdn.mozillademos.org/files/5383/insert-live-sample-btn.png" style="height: 18px; width: 19px;">），将会打开一个对话框可以配置。<img alt="" src="https://mdn.mozillademos.org/files/5385/sample-finder.png" style="height: 358px; width: 405px;"></li> + <li> + <p>在 <strong>Document</strong> 下方，输入包含实例的文章标题。默认是当前正被编辑的文章，但是可以被更改为 MDN 中的其它文章。这项特性允许在不同的页面中重用实例。（如果输入文字，将会出现一个部分匹配输入内容文章列表，可以从中选取需要的文章。）</p> + </li> + <li>在 <strong>Sections in Document</strong> 选项中，选取需要将包含实例的部分。</li> + <li>点击 <strong>OK</strong> 按钮，生成并将宏插入到文章中，宏调用代码看起来是这样的：<br> + <strong>\{{ EmbedLiveSample('Live_sample_demo') }}</strong></li> +</ol> + +<h3 id="增加新的运行实例">增加新的运行实例</h3> + +<p>在编辑一个新的一页需要插入运行实例时，编辑器做更多工作。</p> + +<ol> + <li>点击 <strong>Insert Code Sample Template</strong> 按钮（<img alt="" src="/files/4265/live-sample-button.png" style="height: 19px; width: 21px;">），将会出现这样的对话框。<br> + <img alt="" src="https://mdn.mozillademos.org/files/5387/insert-live-sample-template.png" style="height: 155px; width: 251px;"></li> + <li>输入运行实例的标题，请确保标题对于当前页面是有意义的。</li> + <li>点击 <strong>OK</strong>。会创建一个新的标题，还有一个空的代码框，可以输入 HTML、CSS 或 JavaScript。</li> + <li>删除不需要的标题的代码框。</li> + <li>输入代码</li> +</ol> + +<h2 id="Live_sample_demo" name="Live_sample_demo">查找需要更新的示例</h2> + +<p>当查询实例的时候，有三种可能的更新方式。</p> + +<ul> + <li>将一个非运行实例转为运行实例</li> + <li>解决运行实例的缺陷或错误</li> + <li>在技术有变更时，提升或更新运行实例</li> +</ul> + +<div class="note"> +<p><strong>注意：</strong>如果发现包含需要更新到运行实例系统的文章，请为文章增加标签“ NeedsLiveSample ”。</p> +</div> + +<h3 id="查找需要转为运行实例的示例">查找需要转为运行实例的示例</h3> + +<p>MDN 上有很多老版本的并且使用运行实例系统的示例。我们希望可以将多数示例更新到运行实例。这将会提升网站的一致性和可用性。在访问 MDN 时，你一定经常看到这些例子。然而，很难如果你想要找到某个特定的例子来更新，不过有一些方法可以试一试。</p> + +<ul> + <li>查询<a href="/en-US/docs/tag/NeedsLiveSample" title="/en-US/docs/tag/NeedsLiveSamples">带“NeedsLiveSample”的页面</a>。这些页面被用户标记为需要更新。如果发现需要被更新到运行实例的页面但是没时间理科更新的话，你也需要将该页面加上这个标记。</li> + <li>浏览可能包含示例的文档。比如 <a href="/en-US/docs/Web/JavaScript/Guide" title="/en-US/docs/Web/JavaScript/Guide">JavaScript Guide</a>、<a href="/en-US/docs/Web/HTML" title="/en-US/docs/Web/HTML">HTML documentation</a> 和 <a href="/en-US/docs/Web/CSS/Reference" title="/en-US/docs/Web/CSS/Reference">CSS reference</a>。</li> + <li>查看类似“<a href="/en-US/search?q=example" title="/en-US/search?q=example">example</a>”或“<a href="/en-US/search?q=sample" title="/en-US/search?q=sample">sample</a>”的关键词的搜索结果页面。</li> +</ul> + +<h2 id="Live_sample_demo" name="Live_sample_demo">运行实例演示</h2> + +<p>这部分是使用“插入运行实例模板”按钮插入运行实例标题和代码块的结果。每种语言可以有不止一个代码块。同样也不需要有特定的顺序，所有代码会被混合匹配。</p> + +<p>可以选取删除任何部分。如果不需要脚本，那么删掉脚本的标题和代码块就可以了。同样，也可以删掉其余任何代码块。</p> + +<p>代码模板插入之后，可以增加一些代码，也可以加入一些注释。</p> + +<h3 id="HTML">HTML</h3> + +<p>这段 HTML 代码创建了一个段落和几个 <code>DIV</code> 可以展示信息。</p> + +<pre class="brush: html notranslate"><p>A simple example of the live sample system in action.</p> +<div class="box"> + <div id="item">Hello world!</div> +</div> +</pre> + +<h3 id="CSS">CSS</h3> + +<p>这段 CSS 代码为信息增加样式。</p> + +<pre class="brush: css notranslate">.box { + width: 200px; + height: 100 px; + border-radius: 6px; + background-color: #ffaabb; +} + +#item { + width: 100%; + font-weight: bold; + text-align: center; + font-size: 2em; +} +</pre> + +<h3 id="JavaScript">JavaScript</h3> + +<p>这段代码很简单，只是增加了一个点击事件来弹出信息。</p> + +<pre class="brush: js notranslate">var el = document.getElementById('item'); +el.onclick = function() { + alert('Owww, stop poking me!'); +} +</pre> + +<p>这里通过<code>\{{EmbedLiveSample('Live_sample_demo')}}</code>来展示上面实例运行的结果。</p> + +<p>{{EmbedLiveSample('Live_sample_demo')}}</p> + +<p>这是使用外链宏<code>\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</code>来展示实例运行的结果。</p> + +<p>{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}的集合</p> 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 +--- +<div>{{MDNSidebar}}</div><h2 id="The_example">The_example</h2> + +<p id="Simple_example_of_a_live_demo">This is a very simple example showing you how to do a live demo in MDN. For more information, see <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">Live samples</a>.</p> + +<pre class="brush: html notranslate"><form> + <label>Try me<input type="text" name="name"></label> + <input type="submit" value="go"> +</form></pre> + +<pre class="brush: css notranslate">form { + border-radius: 10px; + background: powderblue; +}</pre> + +<pre class="brush: js notranslate">var f = document.querySelector('form'); + +f.addEventListener('submit', function(ev) { + ev.preventDefault(); + document.querySelectorAll('input')[1].value = 'sending'; +}, false);</pre> + +<p>{{ EmbedLiveSample('The_example', '', '', '') }}</p> + +<p> </p> + +<p> </p> 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 +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见<a href="/en-US/docs/MDN/Contribute/Content/Macros">使用宏</a>和<a href="/en-US/docs/MDN/Contribute/Editor/Links#Using_link_macros">使用链接宏</a>。</span>对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Other">其它宏</a>。这里也有一份 <a href="/en-US/docs/templates">MDN 上所有宏的完整列表</a>。</p> + +<p>对于适合你使用的样式，另见 <a href="/en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS 样式指南</a>。</p> + +<h2 id="链接">链接</h2> + +<h3 id="创建一个单独的超链接">创建一个单独的超链接</h3> + +<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的<strong>链接</strong>按钮创建链接。</p> + +<ul> + <li>{{TemplateLink("Glossary")}} 宏创建一个链接指向 MDN <a href="/en-US/docs/Glossary">术语汇编（glossary）</a>里的一个具体的术语词条。这个宏接受一个必须的和两个可选的参数： + + <ol> + <li>术语的名称（比如 "HTML"）。</li> + <li>代替术语名称显示在文章中的文本（此项应当尽可能少地使用）。{{optional_inline}}</li> + <li>如果这个参数是明确的并且是非零的，一般用于术语汇编链接的自定义样式将不适用。{{optional_inline}}</li> + </ol> + + <p>示例：</p> + + <ul> + <li>\{{Glossary("HTML")}} 生成 {{Glossary("HTML")}}</li> + <li>\{{Glossary("CSS", "Cascading Style Sheets")}} 生成 {{Glossary("CSS", "Cascading Style Sheets")}}</li> + <li>\{{Glossary("HTML", "", 1)}} 生成 {{Glossary("HTML", "", 1)}}</li> + </ul> + </li> +</ul> + +<h3 id="链接到参考文档页面">链接到参考文档页面</h3> + +<p>有各种宏用来链接到 MDN 上特定参考区域里的页面。</p> + +<ul> + <li>{{TemplateLink("cssxref")}} 链接到 <a href="/en-US/docs/CSS_Reference" title="en-US/docs/CSS_Reference">CSS 参考</a>里的一个页面。<br> + 示例： <code>\{{cssxref("cursor")}}</code>，显示为：{{ cssxref("cursor") }} 。</li> + <li>{{TemplateLink("domxref")}} 链接到 DOM 参考里的页面；如果你在结尾列入了圆括号，这个模板会像一个函数名那样显示这个链接。例如，<span class="plain"><span class="nowiki">\{{domxref("document.getElementsByName()")}}</span></span> 显示为 {{ domxref("document.getElementsByName()") }} <code>而 \{\{domxref("Node")\}\}</code> 显示为 {{ domxref("Node") }} 。</li> + <li>{{TemplateLink("event")}} 链接到 DOM 事件参考，例如：\{{event("change")}} 显示为 {{event("change")}} 。</li> + <li>{{TemplateLink("HTMLElement")}} 链接到 HTML 参考里的一个 HTML 元素。</li> + <li>{{TemplateLink("htmlattrxref")}} 链接到一个 HTML 属性。如果你只指定属性名，它将是一个全局属性的描述。如果你指定一个属性名和一个元素名，它将是一个具体元素的一个属性名。例如，<code>\{\{htmlattrxref("lang")\}\} </code>将创建链接：{{htmlattrxref("lang")}} 。<code>\{\{htmlattrxref("type","input")\}\}</code> 将创建链接：{{htmlattrxref("type","input")}} 。</li> + <li>{{TemplateLink("jsxref")}} 链接到 <a href="/en-US/docs/Web/JavaScript/Reference" title="en-US/docs/Web/JavaScript/Reference">JavaScript 参考</a>里的一个页面。</li> + <li>{{TemplateLink("SVGAttr")}} 链接到一个特定的 SVG 属性。例如，<code>\{\{SVGAttr("d")\}\}</code> 创建这样的链接： {{SVGAttr("d")}} 。</li> + <li>{{TemplateLink("SVGElement")}} 链接到 SVG 参考里的一个 SVG 元素。</li> +</ul> + +<h3 id="链接到漏洞和互联网中继聊天（IRC）">链接到漏洞和互联网中继聊天（IRC）</h3> + +<ul> + <li>漏洞 + <ul> + <li>通过使用下面的语法 {{TemplateLink("bug")}} 可以让你轻松地链接到 bugzilla.mozilla.org 上的一个漏洞（页面）：<code>\{\{Bug(123456)\}\}</code> 。这将显示：{{ Bug(123456) }} 。</li> + <li>{{TemplateLink("WebkitBug")}} 插入一条指向 WebKit 漏洞数据库中一个漏洞的链接。例如：<code>\{\{WebkitBug(31277)\}\}</code> 插入 {{ WebkitBug(31277) }} 。</li> + </ul> + </li> + <li>{{TemplateLink("IRCLink")}} 插入一条指向特定 IRC 频道的链接，它带有一个提示框标明它是做什么的以及它需要一个 IRC 客户端。</li> +</ul> + +<h3 id="用于多页面指南的导航帮助">用于多页面指南的导航帮助</h3> + +<p>{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。</p> + +<h2 id="代码示例">代码示例</h2> + +<h3 id="实样">实样</h3> + +<ul> + <li>{{TemplateLink("EmbedLiveSample")}} 让你嵌入一个如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样（Live samples）</a>中描述的代码示例结果到页面上。</li> + <li>{{TemplateLink("LiveSampleLink")}} 创建一个链接指向一个包含（当前）页面上如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样</a>中描述的代码示例结果。</li> +</ul> + +<h3 id="附上的示例文件">附上的示例文件</h3> + +<ul> + <li>{{TemplateLink("Embed_text")}} 模板允许你嵌入一份附加的文本文件到你的文章主体部分中。这将有助于你让代码段既可下载又能显示在文章内容中。你可以为语法高亮选择地指定一种语言。如果你不指定一种（语言），该文本将无格式化嵌入。第一个参数是被嵌入附件的文件名；第二个（参数），如果支持的话，是用于语法高亮的语言，比如 "javascript", "svg" 或 "cpp" 。</li> + <li>{{TemplateLink("EmbedSVG")}} 嵌入一个附带 XML 文件作为一张 SVG 图像到页面当中。指定附带的 SVG 文件的文件名。你可以和 {{TemplateLink("Embed_text")}} 一同使用来展示源码和相同文件的渲染输出。</li> +</ul> + +<h2 id="侧边栏组">侧边栏组</h2> + +<p>There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。</p> + +<ul> + <li>{{TemplateLink("CSSRef")}} 生成 CSS 参考页面的侧边栏。</li> + <li>{{TemplateLink("HTMLRef")}} 生成 HTML 参考页面的侧边栏。</li> + <li>{{TemplateLink("APIRef")}} 生成 Web API 参考页面的侧边栏。</li> +</ul> + +<p>（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）</p> + +<h2 id="通用格式化">通用格式化</h2> + +<h3 id="API_文档的行内指示器">API 文档的行内指示器</h3> + +<p>{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。</p> + +<p>用法: <code>\{{optional_inline()}}</code> 或 <code>\{{ReadOnlyInline()}} 。</code>示例：</p> + +<dl> + <dt><code>isCustomObject</code> {{ReadOnlyInline()}}</dt> + <dd>如果为真，指示该对象是一个自定义对象。</dd> + <dt>parameterX {{ optional_inline() }}</dt> + <dd>Blah blah blah...</dd> +</dl> + +<h2 id="状态和兼容性指示器">状态和兼容性指示器</h2> + +<h3 id="没有附加参数的行内指示器">没有附加参数的行内指示器</h3> + +<h4 id="非标准的">非标准的</h4> + +<p>{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。</p> + +<h5 id="语法"><strong>语法</strong></h5> + +<p><code>\{{non-standard_inline}}</code></p> + +<h5 id="示例">示例</h5> + +<ul> + <li>图标：{{non-standard_inline}}</li> +</ul> + +<h4 id="实验性的">实验性的</h4> + +<p>{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。</p> + +<h5 id="语法_2">语法</h5> + +<p><code>\{{experimental_inline}}</code></p> + +<h5 id="示例_2"><code>示例</code></h5> + +<ul> + <li>图标：{{experimental_inline}}</li> +</ul> + +<h3 id="提供明确技术的指示器">提供明确技术的指示器</h3> + +<p>在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。</p> + +<h4 id="不赞成的">不赞成的</h4> + +<p>{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。<strong>注意：</strong>“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。</p> + +<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p> + +<h5 id="语法_3">语法</h5> + +<p><code>\{{deprecated_inline}}</code> <code>或 \{{deprecated_inline("gecko5")}}</code></p> + +<h5 id="示例_3">示例</h5> + +<ul> + <li>图标：{{deprecated_inline}}</li> + <li>徽标：{{deprecated_inline("gecko5")}}</li> +</ul> + +<h4 id="已废弃的">已废弃的</h4> + +<p>{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。</p> + +<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p> + +<h5 id="语法_4">语法</h5> + +<p><code>\{{obsolete_inline}}</code> 或<code> \{{obsolete_inline("js1.8.5")}}</code></p> + +<h5 id="示例_4">示例</h5> + +<ul> + <li>图标：{{obsolete_inline}}</li> + <li>徽标：{{obsolete_inline("js1.8.5")}}</li> +</ul> + +<h3 id="模板徽标">模板徽标</h3> + +<p>这些宏大多数被用于 <a href="/en-US/docs/WebAPI">WebAPI</a> 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。</p> + +<h3 id="页面或区域标头指示">页面或区域标头指示</h3> + +<p>这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。</p> + +<ul> + <li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_header()}}</code> {{ Non-standard_header() }}</li> + <li>{{TemplateLink("SeeCompatTable")}} 应该被放置在介绍实验性功能或兼容性的区域。 示例: <code>\{{SeeCompatTable()}}</code> {{ SeeCompatTable() }}</li> + <li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li> + <li>{{TemplateLink("deprecated_header")}} 搭配变量: <code>\{{deprecated_header("gecko5")}}</code> {{ Deprecated_header("gecko5") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li> + <li>{{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header()}}</code> {{ Obsolete_header() }}</li> + <li>{{TemplateLink("obsolete_header")}} 搭配变量: <code>\{{obsolete_header("gecko30")}}</code> {{ Obsolete_header("gecko30") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li> + <li>{{TemplateLink("secureContext_header")}}: <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li> +</ul> + +<h3 id="指示一个功能在Web_workers中可用">指示一个功能在Web workers中可用</h3> + +<p> {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在<a href="/en-US/docs/Web/API/Web_Workers_API">Web worker</a> 上下文中可用。</p> + +<h2 id="版本信息宏">版本信息宏</h2> + +<p>这些宏被用来指示这个语段只与一个产品的特定版本有关。</p> + +<ul> + <li>{{TemplateLink("gecko_minversion_inline")}}: 示例: {{ gecko_minversion_inline("9.9") }}</li> + <li>{{TemplateLink("fx_minversion_inline")}}:示例: {{ fx_minversion_inline("9.9") }}</li> +</ul> + +<ol> +</ol> + +<ol> +</ol> 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 +--- +<div>{{MDNSidebar}}</div> + +<p><a href="/en-US/docs/Project:MDN/Kuma" title="/en-US/docs/Project:MDN/Kuma">Kuma</a> 平台为 MDN 提供了强大的宏系统——<a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a>，使得 MDN 能够自动地去做各种东西。本文提供一些信息以便大家知道如何使用 MDN 上的文章内的宏。</p> + +<p>鉴于本文只是 KumaScript 的简介，<a href="/zh-CN/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript 指南</a>提供了更深入的内容。</p> + +<h2 id="宏是如何实现的">宏是如何实现的</h2> + +<p>MDN使用的Macros(宏)是基于<a href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a>执行环境，并在服务端执行运行。这里包括了大量的代码库，另外对此还提供了丰富的wiki说明文档内容。如果你希望能学习到更多的内容，可以查看 <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript 指南</a>， <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_reference" title="/en-US/docs/Project:MDN/Kuma/KumaScript_reference">KumaScript reference</a> 则提供了更多关于这些代码库和KumaScript的API的实现机理。</p> + +<h2 id="在文章中使用宏">在文章中使用宏</h2> + +<p>要实际使用宏，只需将对宏的调用括在一对双括号中，其参数（如果有）括在括号中;如下：</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>关于宏调用的一些注意事项：</p> + +<ul> + <li>宏名称区分大小写，但有些尝试是为了纠正常见的大写错误;即使宏名称在其中使用大写，您也可以使用全部小写，并且您可以将名称通常以小写字母开头的宏大写。</li> + <li>参数以逗号分隔</li> + <li>如果没有参数，您可以完全省略括号; <code>\{{macroname()}}</code> 和 <code>\{{macroname}}</code> 完全相同。</li> + <li>数字参数可以是引号，也可以不是。这取决于您（但是，如果您的版本号中包含多个小数，则需要在引号中）</li> + <li>如果您遇到错误，请仔细检查您的代码。如果仍然无法弄清楚发生了什么，请参阅<a href="/en-US/docs/MDN/Kuma/Troubleshooting_KumaScript_errors">Troubleshooting KumaScript errors</a>以获取帮助。</li> +</ul> + +<p>宏被高度缓存;对于任何一组输入值（参数和环境值，例如运行宏的URL），结果都会被存储和重用。这意味着宏仅在输入发生变化时才实际运行。</p> + +<div class="note"> +<p><strong>注意:</strong> 您可以通过在浏览器中强制刷新页面（即转移重新加载）来强制重新评估页面上的所有宏。</p> +</div> + +<p>宏可以像插入更大的文本块或从MDN的另一部分交换内容一样简单，也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。</p> + +<p>您可以在<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="/en-US/docs/Project:MDN/Contributing/Custom_macros">Commonly-used macros</a>页面上阅读我们最常用的宏;另外，这里有<a href="https://developer.mozilla.org/en-US/docs/templates" title="https://developer.mozilla.org/en-US/docs/templates">complete list of all macros</a>。大多数宏都有内置的文档，作为顶部的注释。</p> + +<p>{{EditorGuideQuicklinks}}</p> |