diff options
Diffstat (limited to 'files/zh-cn/mdn/contribute/howto')
18 files changed, 2661 insertions, 0 deletions
diff --git a/files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html b/files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html new file mode 100644 index 0000000000..243f6b29a7 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html @@ -0,0 +1,30 @@ +--- +title: 如何将代码示例转换成“实时的” +slug: MDN/Contribute/Howto/Convert_code_samples_to_be_live +translation_of: MDN/Contribute/Howto/Convert_code_samples_to_be_live +--- +<div>{{MDNSidebar}}</div><p class="summary">MDN 拥有一套 "<a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">live sample</a>" 系统，在那里页面上展示的代码示例将被直接使用，以显示该示例的输出结果。然而，许多现有文章的代码示例还没有使用这套系统，它们需要被转换。</p> + +<p><span class="seoSummary">实样让你可以看到示例输出的样子，让文档生动有益。这篇指南涵盖如何获取现有示例并添加上“实时的”功能性。</span></p> + +<dl> + <dt>哪里需要完成它？</dt> + <dd>标记有 <a href="/en-US/docs/tag/NeedsLiveSample">NeedsLiveSample</a> 的文章。</dd> + <dt><strong>做这项任务你需要知道哪些？</strong></dt> + <dd> + <ul> + <li>基于代码示例，对 HTML, CSS 和/或 JavaScript 的理解。</li> + <li>能够在 MDN 文章中使用 <a href="/en-US/docs/MDN/Contribute/Tools/KumaScript">KumaScript</a> 宏。</li> + </ul> + </dd> + <dd><strong>做这项任务的步骤是什么？</strong></dd> + <dd> + <ol> + <li>从标记 <a href="/en-US/docs/tag/NeedsLiveSample">NeedsLiveSample</a> 的文章列表中选取一篇文章，这篇文章里的代码示例是你熟悉的。</li> + <li>转换代码示例为“实例的”。</li> + <li>删除之前用于显示示例输出结果的任何代码或图像。</li> + </ol> + </dd> +</dl> + +<p>关于创建和编辑实样的更多信息，见 <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Using the live sample system</a></p> diff --git a/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html b/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html new file mode 100644 index 0000000000..256d61b897 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html @@ -0,0 +1,44 @@ +--- +title: 如何创建 MDN 账号 +slug: MDN/Contribute/Howto/Create_an_MDN_account +tags: + - MDN + - 创建账户 + - 初学者指南 + - 新手上路 +translation_of: MDN/Contribute/Howto/Create_an_MDN_account +--- +<div>{{MDNSidebar}}</div> + +<p> <span class="seoSummary">要对MDN的内容进行任何更改，你需要一个<strong>MDN</strong>账户。别担心，如果你只是打算阅读或搜索MDN，就不需要一个账户！这个指南 将帮助你建立MDN账户。</span></p> + +<div class="pull-aside"> +<div class="moreinfo"> +<p><strong>为什么MDN需要我的电子邮件地址？</strong></p> + +<p>你的电子邮件地址用于帐户恢复；必要时，MDN管理员会通过它来联系您，讨论你的账户或在网站上的活动。</p> + +<p>此外，你可以选择订阅通知（例如，<a href="/zh-CN/docs/MDN/Contribute/Howto/Watch_a_page">当特定的页面被更改</a>）和消息（例如，如果你选择加入我们的beta测试团队，你可能会收到关于待测试新功能的邮件）。</p> + +<p>你的电子邮件地址永远不会显示在MDN，并只会按照我们的<a href="https://www.mozilla.org/privacy/websites/">隐私政策</a>使用。</p> + +<div class="note">如果你通过Github登录到MDN，并且你的Github账号使用了“noreply”的电子邮件地址，你将<em>不会</em>收到任何来自MDN的信息（包括你从页面订阅的通知）。</div> +</div> +</div> + +<ol> + <li>在每个MDN页面的顶部都有一个<strong>登录</strong>按钮。将鼠标指向它（如果你在移动设备上使用，轻触即可），以显示支持的登录到MDN的认证服务列表。</li> + <li>选择一项服务以登录。目前，我们只支持使用Github登录。值得注意的是如果你选择GitHub，你的MDN公开资料页上将显示一个链接，其指向你的GitHub个人资料页。</li> + <li>按照Github的提示，将你的GitHub帐户绑定到MDN。</li> + <li>从认证服务页面返回到MDN之后，MDN会提示你输入用户名和电子邮件地址。<em>你的用户名会公开显示，以便展示你做过的工作。请不要将你的电子邮件地址作为用户名</em>。</li> + <li>点击<strong>创建我的MDN个人资料</strong>。</li> + <li>如果你在步骤4中指定的电子邮件地址与认证服务所使用的不同，请检查<em>这个</em>邮箱，并点击我们发送的确认邮件中的链接。</li> +</ol> + +<p>一切就绪！你已经拥有一个MDN帐户，并可以立即编辑页面！</p> + +<p>你可以在任何MDN页面的顶部点击你的名字以查看账号的公开资料。从那里，你可以点击<strong>编辑</strong>按钮修改或更新你的个人资料。</p> + +<div class="note"> +<p>注：新用户名不能包含空格或“@”字符。请记住，你的用户名将会公开显示，以标识你做过的工作！</p> +</div> diff --git a/files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html b/files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html new file mode 100644 index 0000000000..57f573339d --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html @@ -0,0 +1,186 @@ +--- +title: 如何创建及编辑页面 +slug: MDN/Contribute/Howto/Create_and_edit_pages +tags: + - 指南 + - 新手 + - 简介 +translation_of: MDN/Contribute/Howto/Create_and_edit_pages +--- +<h2 id="测试页面">测试页面</h2> + +<p><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Community">需要帮助？</a> • <a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor">编者指南</a> • <a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Content/Style_guide">风格指南</a></p> + +<p>如何编辑一个页面: </p> + +<ol> + <li>登陆 MDN Web Docs 账号，若未注册请注册。</li> + <li>如果你在只读版本的 MDN Web Docs（https://developer.mozilla.org），点击点击页面右上角的 <strong>Edit in wiki（在 wiki 编辑）</strong>按钮。这将带你进入可编辑的，wiki 版本的网页（https://wiki.developer.mozilla.org），但是这并没有真正地打开可编辑的界面。</li> + <li>请点击 wiki 页面文章标题旁的 <strong>编辑</strong> 按钮<strong>。</strong></li> + <li>页面会重新加载具有规定格式的编辑页面，你可以直接在页面上新增或者删除内容。</li> + <li>你可以新增段落，删除文本，插入标题，并且执行更多涉及编写和编辑的功能。</li> +</ol> + +<p>通过查看<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN Editor guide</a>里的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics">Editor UI elements</a>获得更多关于MDN内置编辑器的信息。</p> + +<h3 id="预览修改">预览修改</h3> + +<p>查看你修改的内容：</p> + +<ul> + <li>点击文章标题上方的"<strong>Preview</strong>"（<strong>预览</strong>）按钮（在编辑模式下）。</li> + <li>这会在新窗口或新标签页中打开一个修改过的预览页。</li> + <li>每次点击按钮，预览页都会刷新到最新的状态。</li> +</ul> + +<p>注意！预览页面并<strong>不会</strong>保存你的修改内容，所以你在关闭编辑的页面前必须保存你的修改。</p> + +<h3 id="版本注释">版本注释</h3> + +<p>当预览修改之后，你需要保存你的修改版本。在<strong>保存</strong>之前，查看页面文章下方的版本注释栏，留下一些注释信息来告诉其它贡献者你为什么要去修改它。例如，你可能新增加了一个章节，或修改了一些文字来使得术语表述的更加一致，亦或重构了一个段落使其语言更加易于理解，或者就是删除了一些冗余信息。</p> + +<h3 id="目录">目录</h3> + +<p>一篇文章的“在本文中”部分是自动生成的页面上标题的链接列表。这些链接的措词可以通过编辑标题进行编辑。也可以通过选择“编辑页面标题和属性”和改变“TOC”下拉列表的值，从而删除目录，或减少链接数量。</p> + +<h3 id="标签">标签</h3> + +<p>你可以新增或删除编辑区域下面的一些描述页面内容或者功能的标签。查看 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Tagging">如何正确标记页面</a> 来了解如何为页面添加合适的标签。</p> + +<h3 id="需要复核？">需要复核？</h3> + +<p>保存之前，为了确保信息的准确性，你可以勾选技术复核（针对代码，API，或技术），编辑复核（针对文章，语法，和内容），或模板复核（针对KumaScript code）的选择框，来让专家或有经验的贡献者复核你的编辑信息。</p> + +<h3 id="附件">附件</h3> + +<p>如果你想<strong>附加某个文件</strong>到一个现有的页面中来添加插图或作进一步说明的话，你可以在页面底部输入。当你上传图片时，请确保使用图片优化工具进行优化，以便我们的图片足够小，方便下载。这样便提高了页面加载速度，提升MDN的整体性能。有可能有你钟爱的工具，如果没有的话，我们推荐一款容易上手的Web工具：<a href="https://tinypng.com/">TinyPNG</a>。</p> + +<h3 id="保存，放弃更改，继续编辑">保存，放弃更改，继续编辑</h3> + +<p>当你完成编辑，并确认过预览界面，你可以点击标题右边或者文章底部的的绿色按钮<strong>“发布修改”</strong>来发布你的文章和注释。如果你想要继续编辑，可以选择点击按钮<strong>“发布并继续编辑”</strong>来保证在保存编辑的同时不离开编辑模式。</p> + +<p>如果你改变主意，你也可以点击页面右侧的红色按钮<strong>“放弃”</strong>来放弃你的编辑，注意放弃更改是不可撤销返回的。</p> + +<p>在版本注释区域点击 <strong>Enter 键</strong>和点击按钮<strong>“发布并继续编辑”</strong>具有相同的效果。</p> + +<div class="blockIndicator note"> +<p><strong>注意：</strong>当你尝试保存你编辑好的页面时发现你的编辑被视为无效操作而被拒绝了，若你编辑好的内容又确实是适合MDN的，此时你可以向<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/mdn-admins@mozilla.com">MDN管理团队</a>发送邮件来获得帮助。</p> +</div> + +<h2 id="获取新建页面的许可">获取新建页面的许可</h2> + +<p>出于对安全的考虑，最近创建的MDN账号是没有权限新建页面的。如果你尝试这样做，你将看到一个页面引导你如何创建新页面。有以下两种可选的方式：</p> + +<ul> + <li><strong>请别人帮你创建。</strong>为此，请您提供一份<a href="https://bugzilla.mozilla.org/enter_bug.cgi?bug_file_loc=http%3A%2F%2F&bug_ignored=0&bug_severity=normal&bug_status=NEW&cf_fx_iteration=---&cf_fx_points=---&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&flag_type-4=X&flag_type-607=X&flag_type-800=X&flag_type-803=X&form_name=enter_bug&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=Unspecified&priority=--&product=Developer%20Documentation&rep_platform=Unspecified&short_desc=Create%20page%3A%20&status_whiteboard=create-page&target_milestone=---&version=unspecified">用于提出 bug 的申请书</a>，并且以 "Create page: <页面标题>" 为主题。如果您知道该页面应该放在 MDN 中的什么位置，请确保填写好一个 URL 来描述该位置。您还应该注明您为何需要创建该页面。</li> + <li><strong>申请页面创建权限。</strong>如果您申请了页面创建权限且得到了授权，您将可以根据下述的指南自行创建新页面。为了请求该权限，请您将申请书通过电子邮件<a href="mailto:mdn-admins@mozilla.org">发送给 MDN 管理团队</a>。请确保申请书的内容涵盖了您的用户名，以及为什么您有能力创建一个新页面（比方说：您正在编制一份新的 API 文档，该文档涉及许多新页面，又或者您想添加一些新条目到术语表）。您还应该曾经为该网站的内容作出过许多有益贡献，并且成为贡献者应该已经有一段时日了（至于这段时日有多久，这并没有一个固定期限，因为还需要同时考虑其他的因素）。</li> +</ul> + +<h2 id="新建一个页面">新建一个页面</h2> + +<p>当你拥有创建新页面的权限之后，你就可以开始创建页面了。</p> + +<p>找不到在哪里新建一个页面？<strong>别担心！</strong>你可以在任何地方新建一个页面，我们会找到它并把它归档或者合并到最合适的类别下。你也不用过多担心它不够完美，我们有热心的志愿者来帮你打理，让你的文章保持干净美观。 </p> + +<p>下面是一些新建页面的方法：</p> + +<ul> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Missing_page_link">已有网页上的“缺失页面”链接</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#New_page_without_link">不需要链接的新页面</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Subpage_of_an_existing_page">在现有页面下新增子页面</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Clone_of_an_existing_page">克隆已存在的页面</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Link_from_an_existing_page">从已存在页面创建链接</a></li> +</ul> + +<h3 id="“缺失页面”链接">“缺失页面”链接</h3> + +<p>和许多维基站点一样，在 MDN 也有可能创建一个链接，它指向一个尚不存在的页面。例如：一个作者可能创建了一个清单页面，该页面涵盖了某个API的所有成员，而这些成员对应的页面还没创建好。在 MDN，指向到缺失页面的链接通常显示为红色。</p> + +<p>从“缺失页面”链接创建对应的页面需要：</p> + +<ol> + <li>确认已登录进 MDN，并且拥有新建页面的权限。（若未登录就点击“缺失页面”链接，会得到一个404（找不到页面）的错误。）</li> + <li>点击“缺失页面”链接。如果你拥有页面创建权限，<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN编辑器界面</a>会自动打开，准备好让你创建缺失的页面。</li> + <li>编写页面内容，然后保存。</li> +</ol> + +<h3 id="不需要链接的新页面">不需要链接的新页面</h3> + +<p>想要创建一个没有链接到其他页面的新页面时，你需要在你的浏览器中键入一个包含新页面名字段的URL。例如，如果你键入以下URL并回车：</p> + +<pre class="notranslate"><code>https://developer.mozilla.org/en-US/docs/FooBar</code></pre> + +<p>MDN将创建一个标题为“FooBar”的新页面并且打开编辑器让你能够为新添加的页面添加内容。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在的页面</a>的小节来学习如何使用编辑器模式。</p> + +<p>要创建一个没有链接到其他页面的新页面需要：</p> + +<ol> + <li>确保您已经登陆MDN，并且拥有创建新页面的权限。</li> + <li>在您的浏览器中输入以下URL并回车。</li> +</ol> + +<pre class="notranslate"><code>https://developer.mozilla.org/en-US/docs/new</code></pre> + +<p>此时，MDN 创建新页面时有一个地方专门用来填写标题，打开编辑器后您就可以添加内容到这个新页面。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在的页面</a>的小节来学习如何使用编辑器模式。</p> + +<h3 id="已存在页面的子页面">已存在页面的子页面</h3> + +<p>在页面层次结构中的现有页面以下创建页面，需要：</p> + +<ol> + <li>在“父”页面，点击<strong>高级</strong>菜单（工具栏中的齿轮按钮），然后点击“<strong>新建子页面</strong>”。</li> + <li>打开编辑器视图以创建新文档。</li> + <li>在标题栏键入文档<strong>标题</strong>。</li> + <li>需要的话，更改 <strong>Slug</strong> 字段（例如，若标题太长而你又想用较短的URL）。该字段由编辑器自动填充，替换掉标题处的空白下划线并且只更改文档对应的URL的最后一部分。</li> + <li>在 <strong>TOC</strong> 字段，选择你想自动显示在页面目录中的标题级别，或者如果一个都不需要的话可以选择”无目录“。</li> + <li>在编辑框中编写页面内容，然后保存您的修改。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在页面</a>的小节来学习如何使用编辑器模式。</li> +</ol> + +<h3 id="克隆一个已存在的页面">克隆一个已存在的页面</h3> + +<p>如果你想应用一个已经存在的页面的版式，你可以“克隆”这个页面并且修改其内容。</p> + +<ol> + <li>在原页面中，点击<strong>高级</strong>菜单（工具栏中的齿轮按钮），然后点击“<strong>克隆此文章</strong>”，一个编辑器视图就会被打开来创建新文档。</li> + <li>更换一个合适的标题，当你在更改<strong>标题</strong>时，<strong>Slug </strong>字段会自动更新。</li> + <li> + <p>如果需要，更改 <strong>Slug</strong> 字段部分的路径，然后把新的文档放入文件夹的另一处（在大多数情况下这是没有必要的，因为克隆的页面与原始页面拥有相似的内容，因此克隆的页面应该与原始页面安排在相近的位置）。</p> + </li> + <li> + <p>在<strong>TOC</strong>字段中，选择你想让其显示在目录中的标题等级，或者选择“没有目录（No table of contents）”如果页面不需要的话。</p> + </li> + <li> + <p>在编辑面板输入页面的内容并保存您的修改。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在页面</a>的小节来学习如何使用编辑器模式。</p> + </li> +</ol> + +<h3 id="从现有页面链接到新页面">从现有页面链接到新页面</h3> + +<p>你可以在一个现有页面创建一个链接，然后点击这个链接来创建一个新页面：</p> + +<ol> + <li>在现有页面上任意但合理的位置输入新页面的名字</li> + <li>将名字设置为高亮显示并在编辑工具栏点击<strong>链接图标<a href="https://developer.mozilla.org/files/3810/link-icon.png"><img alt="" src="https://developer.mozilla.org/files/3810/link-icon.png"></a></strong>（也可能是简洁的锁链状）。“<strong>更新链接</strong>”对话框打开，高亮的文字会被显示在“<strong>链接文本</strong>”框中。 </li> + <li>"/en-US/docs/" 会被默认添加到URL的开头。在 "/en-US/docs/" 后输入此页面的名字。当然，链接文字和新页面的标题也可以不一样。</li> + <li>点击“确认”来创建和插入这个链接。</li> +</ol> + +<p>如果这个页面不存在，这个链接将会用红色显示。如果这个页面存在，这个链接将会用蓝色显示。如果你想创建一个新的页面，但是你想创建页面的标题被占用了，请考虑是否更应该去编辑和改进这个已经存在的页面。如果您认为创建一个新页面更有必要，可以选择一个不同的标题并创建它。请参考<a href="https://developer.mozilla.org/Project:cn/Page_Naming_Guide">页面命名指南</a>获得指导。</p> + +<p>为了给您新建的页面添加内容，点击您刚刚创建的红色的链接（在保存并且关闭编辑器之后）。新的页面将进入编辑模式使您能够开始编写内容，请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在的页面</a>的小节来学习如何使用编辑器模式。</p> + +<h2 id="刷新页面内容">刷新页面内容</h2> + +<p>由于性能上原因，MDN对KumaScript 宏指令和将一个页面嵌入另一个页面中的支持有时候会稍微被页面缓存所妨碍。页面由它们的数据源编译，并且输出会被缓存起来用来将来的页面请求。从那时起，在该页面的任何宏指令（模板）或者嵌入（使用宏<code><a href="https://developer.mozilla.org/en-US/docs/Template:Page">Page</a></code> ）将不会展现由于宏，宏的输出，或者嵌入的原本内容所引起的变化。</p> + +<ul> + <li>当想要手动刷新一个页面时，您可以在浏览器中强制刷新。MDN能够识别这个动作并且触发一个页面的重新编译，拉取一个更新过的宏输出并且传输页面内容。</li> + <li>您也可以配置页面定期的自动重新编译。除非您期望页面需要经常性的更新，否则不应这样做。参考<a href="https://developer.mozilla.org/Project:cn/Page_Regeneration">页面重新生成</a>获取更多信息。</li> +</ul> + +<h2 id="更多参考">更多参考</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN 编辑器指南</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Content/Style_guide">MDN 编辑风格指南</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html b/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html new file mode 100644 index 0000000000..83945186c5 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html @@ -0,0 +1,57 @@ +--- +title: 如何进行技术审查 +slug: MDN/Contribute/Howto/Do_a_technical_review +tags: + - MDN Meta + - 复核 + - 如何做 + - 指南 + - 文档 +translation_of: MDN/Contribute/Howto/Do_a_technical_review +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">技术复核包括审查一篇文章的技术准确性和完整性，并在必要的时候予以纠正。 如果<span id="result_box" lang="zh-CN"><span>一篇文章</span></span>的作者需要其他人来对文章进行技术复核的话，就需要在编辑时勾选”技术复核“选项。<span id="result_box" lang="zh-CN"><span>通常情况下，作者会联系特定的工程师来执行技术审查，</span></span>但是任何具有此领域专业技能的人都可以完成技术复核。</p> + +<p><span id="result_box" lang="zh-CN"><span>本文介绍如何进行技术复核</span></span><span lang="zh-CN"><span>，从而帮助确保MDN的内容的正确性。</span></span></p> + +<h4 id="任务是什么？">任务是什么？</h4> + +<p> <span id="result_box" lang="zh-CN"><span>审查和纠正文章的技术准确性和完整性。</span></span></p> + +<h4 id="什么地方需要技术审核？">什么地方需要技术审核？</h4> + +<p> 在被标记为需要<a href="https://wiki.developer.mozilla.org/zh-CN/docs/needs-review/technical">技术审核</a>的特定文章中。</p> + +<h4 id="开始做任务前你需要了解什么？">开始做任务前你需要了解什么？</h4> + +<ul> + <li>在此篇文章技术领域的专业知识。如果你在阅读这篇文章的时候没有学到任何新知识，那么你就是这篇文章技术领域的专家。</li> + <li><span class="short_text" id="result_box" lang="zh-CN"><span>如何在MDN上编辑wiki文章</span></span></li> +</ul> + +<h4 id="完成任务的步骤是什么？">完成任务的步骤是什么？</h4> + +<ol> + <li>选取一篇需要复查的文章： + <ol> + <li>前往 <a href="https://wiki.developer.mozilla.org/zh-CN/docs/needs-review/technical">technical reviews</a> 页面。这里列出了所有需要技术复核的文章。</li> + <li>选择一个你非常熟悉的领域的页面。</li> + <li>点击该页面。</li> + </ol> + </li> + <li>在阅读这篇文章的时候注意文章里的所有技术细节：这篇文章的内容正确吗？是否缺少了一些细节？如果你觉得这篇文章不适合你，那么请毫不犹豫地换一篇文章。</li> + <li>如果没有错误，你不需要重新编辑来把这篇文章标识为”已复核“，你只需要找到左边导航栏最下方的”快速复核“框。黄色背景的框里列出了所有等待复核的请求，像这样：<img alt="" src="https://mdn.mozillademos.org/files/13016/SidebarTechReviewRequested.png" style="height: 93px; width: 321px;"></li> + <li>去掉需要技术复核前面的勾，然后点保存。</li> + <li>如果你发现了需要被修正的错误，你可以在编辑器里修改这篇文章的审核请求状态。以下是操作步骤： + <ol> + <li>点击页面顶部的编辑按钮，进入 <a href="https://developer.mozilla.org/zh-CN/docs/Project:MDN/%E8%B4%A1%E7%8C%AE/Editor_guide">MDN editor</a> 页面，来编辑该页面。</li> + <li>更正不正确的技术信息，还可以添加文章遗漏的任何重要信息。</li> + <li>在文章的底部输入修改注释。这个注释简要地描述你的修改工作，比如“完成技术审查。”如果你更正了某些信息，将它们写进你的注释，比如“技术审查以及修复参数的相关描述。”这将帮助其他贡献者和网站编辑人员知道你修改的部分以及原因。如果你认为文章中有些不必要被审查的部分，也可以在注释中提出来。</li> + <li>取消勾选“需要审查”下面的“技术”选项框了吗？它就在页面的审查注释区域。</li> + <li>点击发布按钮。</li> + </ol> + </li> +</ol> + +<p>祝贺你，你已经完成了你的第一篇技术复核，<span id="result_box" lang="zh-CN"><span>感谢您的帮助！</span></span></p> diff --git a/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html b/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html new file mode 100644 index 0000000000..48396dcd33 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html @@ -0,0 +1,55 @@ +--- +title: 如何进行编辑审核 +slug: MDN/Contribute/Howto/Do_an_editorial_review +tags: + - 指导 + - 文档 + - 编辑审核 +translation_of: MDN/Contribute/Howto/Do_an_editorial_review +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p class="summary"><strong>编辑审核</strong>的工作由修改文中排版错误，拼写、语法、用法等文本错误构成。并不是所有贡献者都是语言专家，但有了他们的共同努力，他们把那些需要编辑以及校对的文章转化为了极其有用的文章；这些都是在编辑审核的工作中完成的。</p> + +<p><span class="seoSummary">这篇文章描述了如何进行编辑审核，从而帮助实现 MDN 的内容精确。</span></p> + +<dl> + <dt>任务是什么？</dt> + <dd>编辑并审核那些被标记为需要编辑审核的文章。</dd> + <dt>应该在何处处理它？</dt> + <dd>在特定的文章中会有标记有需要编辑审核的地方。</dd> + <dt>开始做任务前你需要了解什么？</dt> + <dd>你需要有好的中文语法和词汇技能。文章复核是要确保语法、用词都是正确的并且有意义，同时遵循 <a href="/zh-CN/docs/MDN/Contribute/Content/Style_guide">MDN 样式指南</a>。</dd> + <dt>完成任务的步骤是什么？</dt> + <dd> + <ol> + <li>选择一篇文章来审核： + <ol> + <li>访问<a href="/zh-CN/docs/needs-review/editorial">需要复核的文章列表</a>。它陈列了所有请求编辑审核的页面。</li> + <li>点击文章链接进入页面。<br> + <strong>注意：</strong>这个列表是自动生成的，但更新并不频繁，所以列表中的一些文章是不再需要编辑审核的。如果你选择的文章<em>没有</em>显示“这篇文章需要复核”，跳过这一篇文章，再选择其他的文章。</li> + </ol> + </li> + <li id="core-steps">仔细阅读文章，特别注意其中可能出现的排版、错字、语法或者词语使用错误。如果你觉得这篇文章不适合你，随时可以换一篇其它文章。</li> + <li>如果文章中没有任何错误，你不需要进入编辑页面再把它标记为“已审核”。在页面的左侧边栏处可以找到“快速复核”对话框：<br> + <img alt="文法复核边栏屏幕截图" src="https://mdn.mozillademos.org/files/13164/editorial%20review%5Bzh-CN%5D.JPG" style="height: 99px; width: 284px;"></li> + <li>取消 <strong>文法</strong> 的勾选之后点击 <strong>保存</strong> 。</li> + <li>如果你发现了需要改正的错误： + <ol> + <li>点击右上角蓝色的 <code><strong>编辑</strong></code> 按钮；它将带你进入 <a href="/zh-CN/docs/Project:MDN/Contributing/Editor_guide">MDN 编辑器</a>。</li> + <li>更正所有你看到的的排版、错字、语法或者词语使用错误。你并不需要将所有问题都一次性改好，不过当完成整篇文章的时候你还觉得不确定是否完美，一定要保留文法复核的请求。</li> + <li>在文本底部输入一段<strong>修订注释</strong>；比如 <em>“文法符合：更改了排版，语法和用词错误。” </em>这有助于其他编辑者和网站管理员知道你更改了什么以及为什么做出更改。</li> + <li>在 <strong>需要复核吗？</strong> 下面取消 <strong>文法</strong> 的选择。这一项位于页面的 <strong>版本备注</strong> 当中。<br> + <img alt="文法复核编辑模式屏幕截图" src="https://mdn.mozillademos.org/files/13166/editorial%20review%20edit-mode%5Bzh-CN%5D.JPG" style="height: 246px; width: 259px;"></li> + <li>点击 <strong>发布</strong> 按钮。</li> + </ol> + </li> + </ol> + + <div class="note"> + <p>你所做出的更改在保存后不一定立即可见，页面保存和处理过程可能出现一些延迟。</p> + </div> + </dd> +</dl> diff --git a/files/zh-cn/mdn/contribute/howto/index.html b/files/zh-cn/mdn/contribute/howto/index.html new file mode 100644 index 0000000000..c63b358e37 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/index.html @@ -0,0 +1,16 @@ +--- +title: MDN 使用指南 +slug: MDN/Contribute/Howto +tags: + - Documentation + - Landing + - MDN + - TopicStub +translation_of: MDN/Contribute/Howto +--- +<p><% //插入当前页面的子页面的定义列表，每个 //页面的标题为</p> + +<dl> + <dt>术语，其 SEO 摘要为</dt> + <dd>术语。的 //如果可能，列表以两列视图显示。 // //参数： //没有 var html = 等待模板 （[子页与摘要] ); //现在，我们有了HTML中的整个列表。让我们通过它，并尝试用力把它分成两列。 %> <%-等待模板（"MakeColumnsForDL"，[html]）%></dd> +</dl> diff --git a/files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html b/files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html new file mode 100644 index 0000000000..5be8c9fe23 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html @@ -0,0 +1,89 @@ +--- +title: 如何在您的MDN账户中关联一个GitHub账户 +slug: MDN/Contribute/Howto/Link_a_GitHub_account +tags: + - MDN + - 文档 +translation_of: Archive/MDN/Howto_Link_a_Github_account +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<div class="note"> +<p><strong>Note: </strong>Support for Persona logins on MDN was disabled on November 1, 2016. The method for adding a Github account to your profile therefore no longer works. If you didn't add a GitHub login to your MDN account before we disabled Persona logins, please <strong>file an <a class="external external-icon" href="https://mzl.la/accounthelp">"Account Help" bug</a> </strong>on Bugzilla. For further reading about the end of life of Persona, see: <a href="https://wiki.mozilla.org/Identity/Persona_Shutdown_Guidelines_for_Reliers">Persona shutdown guidelines</a>.</p> +</div> + + +<p><span class="seoSummary">由于Mozilla的 <a href="https://login.persona.org/">Persona</a> 身份认证系统将会于2016年11月30日起关闭，所有希望为MDN做贡献的用户都需要用其他手段来登录到 MDN。当前，我们支持的唯一选择就是 GitHub，所以您需要在截止日期过后使用 <a href="https://github.com/">GitHub</a> 账户登入并编辑 MDN。这篇文章讲述了如何将 GitHub 身份认证添加到您的MDN账户中。</span></p> + +<div class="warning"> +<p>您必须在2016年11月30日前完成此操作，否则您将再也无法登录 MDN！</p> +</div> + +<h2 id="概述">概述</h2> + +<p>将GitHub身份认证添加到您的账户中并不难。下面我们将进一步讨论细节，但首先，先看一下步骤概述：</p> + +<ol> + <li><a href="/zh-CN/docs/MDN/Signing_in">登录您的 MDN 账户</a></li> + <li>转到 <a href="https://developer.mozilla.org/en-US/users/account/connections">账户关联</a> 页面</li> + <li>添加 GitHub 身份认证。</li> +</ol> + +<h2 id="详细指南">详细指南</h2> + +<p>下面是一个手把手的教程，教您如何完成您需要知道的事情。</p> + +<h3 id="登入您的_MDN_账户">登入您的 MDN 账户</h3> + +<ol> + <li>在任意MDN页面的顶端，将鼠标悬浮于或点击登录框。它会显示可用的身份认证方式：<strong>Persona</strong> 或 <strong>GitHub </strong>。<br> + <img alt="Sign in box on MDN, showing Persona and Github." src="https://mdn.mozillademos.org/files/13426/Mozilla_Developer_Network_-__Private_Browsing_.png" style="border-style: solid; border-width: 1px; height: 140px; width: 425px;"></li> + <li>选择 <strong>Persona </strong>，然后用您常用的登录凭据登入。</li> +</ol> + +<h3 id="转到账户关联页面">转到账户关联页面</h3> + +<p>有两种方法转到账户关联页面。</p> + +<p>一种方法就是点击下面的链接。</p> + + +<p>还有一种方法就是完成下列步骤：</p> + +<ol> + <li>在任意 MDN 的页面顶端单击您的用户名（就是您未登录时登入框的位置）。这将带您到您的资料页面。</li> + <li>点击“齿轮”菜单，然后单击 <strong>Account connections </strong>（账户关联）。<br> + <img alt='Gear menu in profile, showing the "Account connections" option' src="https://mdn.mozillademos.org/files/13428/SheppyWork___MDN_-__Private_Browsing_.png" style="height: 217px; width: 219px;"></li> +</ol> + +<h3 id="添加_GitHub_身份认证">添加 GitHub 身份认证</h3> + +<p>您现在位于"Account connections"（账户关联）页面，它罗列了您已连接到您的 MDN 个人资料的外部账户。如果 GitHub 账户已经列出，那么恭喜你！您已经完成了！但为了测试一下您是否牢记您的密码，可以登出 MDN，再使用您的 GitHub 身份凭证登入。</p> + +<p>如果 Github 没有列出，请看看页面底部的已连接账户列表。您可以看到<strong>连接一个新的账号</strong>小节，这里列出了您可以与您的 MDN 个人资料建立连接的账户。如下图：</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13430/Account_Connections___MDN_-__Private_Browsing_.png" style="height: 79px; width: 476px;"></p> + +<p>要想添加 GitHub：</p> + +<ol> + <li>点击 <strong>连接 Github</strong>。MDN 将会向 Github 请求权限连接这两个账户。如果您还未登录 Github，登录页面将会显示出来：<br> + <img alt="Screenshot of GitHub sign in window." src="https://mdn.mozillademos.org/files/13444/GitHub_Sign_In.png" style="height: 447px; width: 356px;"></li> + <li>如果您为您的 Github 账户开通了两步验证，您须要输入您的验证码：<br> + <img alt="Screenshot of GitHub's Two-factor authentication window." src="https://mdn.mozillademos.org/files/13460/GitHub_-_Where_software_is_built.png" style="height: 448px; width: 361px;"></li> + <li>现在您登录您的 Github 账户了。您可以进行授权，以连接 Github 与 MDN 账户（除非您曾经因某些原因授权过）。此页面如下图：<br> + <img alt='Screenshot of GitHub "Authorize application" window.' src="https://mdn.mozillademos.org/files/13456/Authorize_Mozilla_Developer_Network.png" style="height: 420px; width: 766px;"><br> + 点击绿色的 <strong>Authorize application</strong>（授权应用） 按钮授予您的 MDN 账户访问您的 Github 账户的权限。当您的 Github 账户成功与 MDN 账户建立连接时，您将看到这一信息：<br> + <img alt="Account successfully created." src="https://mdn.mozillademos.org/files/13454/Edit_Your_Profile___MDN.png" style="height: 57px; width: 646px;"></li> +</ol> + +<p>现在您不仅可用 GitHub 登录 MDN，还已经使用 GitHub 身份认证登入了！您已经准备好应对 Persona 关闭了。如有必要，您应该确定已经更新了安装的所有密码管理器。</p> + +<h2 id="相关链接">相关链接</h2> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Create_an_MDN_account">如何创建一个MDN账户</a></li> + <li><a href="/zh-CN/docs/MDN/Getting_started">初入MDN</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html b/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html new file mode 100644 index 0000000000..bf90ff0262 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html @@ -0,0 +1,59 @@ +--- +title: 如何为页面编写概要 +slug: MDN/Contribute/Howto/Set_the_summary_for_a_page +tags: + - 指南 +translation_of: MDN/Contribute/Howto/Set_the_summary_for_a_page +--- +<div>{{MDNSidebar}}</div> + +<p>您可以在MDN的每一个页面上定义概要，它可以在很多方面起到作用，如包含在搜索引擎的搜索结果中，或者在其他MDN页面如热门话题页或者工具提示页。它应该概括的描述该页面的所有内容，并且当在其他页面显示时，不包含页面内容的无关部分。</p> + +<div class="blockIndicator warning"> +<p><strong>一个概要可以被明确的定在在一个页面中。如果概要没有被明确的定义，通常会使用该页面内容的第一句话作为概要，而它往往不是该页面最精确的描述。</strong></p> +</div> + +<table class="full-width-table"> + <tbody> + <tr> + <td><strong>任务是什么？</strong></td> + <td>标记应被用作其在其他情况下摘要页面中的文本;这项任务可能包括在需要写相应的文本。</td> + </tr> + <tr> + <td><strong>哪些地方需要它？</strong></td> + <td>在缺乏一个总结或总结不太好的页面。</td> + </tr> + <tr> + <td><strong>完成任务需要什么？</strong></td> + <td>能够使用MDN编辑器的能力;良好的英语写作能力;对网页的主题足够熟悉，以便于能写一个很好的总结。</td> + </tr> + <tr> + <td><strong>怎样完成任务？</strong></td> + <td> + <ol> + <li>选择一个页面来设置总结: + <ol> + <li>在<a href="/zh-CN/docs/MDN/Doc_status">MDN documentation status</a> 页面上的section中, 点击你所了解的话题。<img alt="" src="https://mdn.mozillademos.org/files/8681/sections.png"></li> + <li>在主题的文档状态页面，单击汇总表中的页头。这需要你在该主题区段的所有网页的索引;它示出了在左侧列中的页面的链接，以及在右栏中的标签和摘要。<img alt="" src="https://mdn.mozillademos.org/files/8675/pages.png"></li> + <li>挑选缺少一个总结页面，或者说有一个较差的总结的页面。<img alt="" src="https://mdn.mozillademos.org/files/8677/summary.png"></li> + </ol> + </li> + </ol> + + <div class="blockIndicator warning"> + <p>点击链接进入该页面。</p> + </div> + + <ol> + <li>单击编辑在MDN编辑器中打开该页面。</li> + <li>找一两句话，作为一个总结。如果需要，可以编辑现有的内容来创建或修改的句子来做一个很好的总结。</li> + <li>选择要使用的摘要文本。</li> + <li>在样式插件的编辑器工具栏，选择搜索引擎优化摘要。 (In the page source, this creates a {{HTMLElement("span")}} element with <code>class="seoSummary"</code> around the selected text.)<img alt="" src="https://mdn.mozillademos.org/files/8679/styles.png"></li> + <li>保存你的更改，并附上类似“设置页面总结”的修改意见。修改意见是可选的，但我们鼓励你添加一个。这样便于其他人了解变更的情况。</li> + </ol> + </td> + </tr> + </tbody> +</table> + +<p>完成这样的一份任务后，你就是MDN的一员。</p> diff --git a/files/zh-cn/mdn/contribute/howto/tag/index.html b/files/zh-cn/mdn/contribute/howto/tag/index.html new file mode 100644 index 0000000000..67415b88f1 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/tag/index.html @@ -0,0 +1,536 @@ +--- +title: 如何合理的标记页面 +slug: MDN/Contribute/Howto/Tag +tags: + - MDN 元 + - 初学者 + - 如何 + - 指南 + - 教程 +translation_of: MDN/Contribute/Howto/Tag +--- +<div>{{MDNSidebar}}</div> + +<p><strong>文章标签</strong>是一个让游客接触到有用内容的重要方式。每一个页面通常都应该有几个标签来保持其内容的组织性。 <span class="seoSummary">这一页解释了标记页面的最好方法，以使我们的读者可以找到信息和让我们的页面保持组织有序。</span></p> + +<p>对于编辑标签的用户界面的帮助, 请看我们的编辑者指南里的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics#The_tags_box">标记部分</a>。</p> + +<p>请根据下面所解释的来合理的使用标签。 如果你没有这么做, 我们的自动化工具将不能正确的生成内容列表，着陆页面和文章的交叉链接。</p> + +<h2 id="MDN如何使用标签">MDN如何使用标签</h2> + +<p>MDN有这么几种方法来使用标签：</p> + +<dl> + <dt>文档分类：</dt> + <dd>这个文档是什么类型的？是一篇参考？一篇教程？还是一篇着陆页？我们的游客可以使用这些标签来过滤搜索，所以它们真的很重要！</dd> + <dt>主题识别</dt> + <dd>这篇文章是关于什么的？关于API？DOM？图形？重申一遍，这些标签很重要，因为它们可以用来过滤搜索。</dd> + <dt>技术现状</dt> + <dd>这门技术的现状是什么？它是非标准的？过时的还是已经被弃用了的？还是处于实验性的？</dd> + <dt>技术水平</dt> + <dd>教程和指南，这篇文章中涵盖的内容有多先进？</dd> + <dt>文档元数据</dt> + <dd>写作社区使用标签来跟踪哪些页面需要什么样的工作。</dd> +</dl> + +<h2 id="标签类型指南">标签类型指南</h2> + +<p>这里是关于标签类型的快速指南和它们可能用到的值。</p> + +<h3 id="文档类别">文档类别</h3> + +<p>当你使用这些类别中的一个来标记文章的时候, 你帮助了自动化工具更准确的生成着陆页面，内容表，和更多。我们新的搜索系统也可以使用这些来让我们的游客更好的根据他们的意愿来定位参考和指南。</p> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>我们使用以下类别名称作为标准标记术语：</span></p> +</div> +</div> + +<dl> + <dt><code>{{Tag("Intro")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>这篇文章提供了一个有关主题的介绍材料。</span><span>最理想的是每一个技术领域应该只能有一个“Intro”标签。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Featured")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>这篇文章是至关重要的，将在登陆页面上显示在突出的位置上。</span><span>有节制地使用这个标签（每个文件区不要超过三个）。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Reference")}}</code></dt> + <dd>这篇文章包含API、元素、属性、等的参考资料。</dd> + <dt><code>{{Tag("Landing")}}</code></dt> + <dd>这是一个着陆页面。</dd> + <dt><code>{{Tag("Guide")}}</code></dt> + <dd>这篇文章是一个告诉如何做或者指南的页面。</dd> + <dt><code>{{Tag("Example")}}</code></dt> + <dd>这是代码示例页面，或者有代码示例（那是有用的代码实例，而不是一行“语法例子”）。</dd> +</dl> + +<h3 id="主题">主题</h3> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>通过确定文章的主题区域，您可以帮助产生更好的搜索结果（以及着陆页和导航）。</span></p> +</div> +</div> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>虽然在这里有一些灵活的空间可以识别新的主题领域，但我们试着将自己限制在API和技术的名字</span><span>上，一些有用的例子：</span></p> +</div> +</div> + +<ul> + <li><code>{{Tag("HTML")}}</code></li> + <li><code>{{Tag("CSS")}}</code></li> + <li><code>{{Tag("JavaScript")}}</code> (注意大写字母 “S”！)</li> + <li><code>{{Tag("Document")}}</code></li> + <li><code>{{Tag("DOM")}}</code></li> + <li><code>{{Tag("API")}}</code> 对于每一个接口，方法和属性。</li> + <li><code>{{Tag("Method")}}</code> 对于API的每一个方法。</li> + <li><code>{{Tag("Property")}}</code> 对于API的每一个属性。</li> + <li><code>{{Tag("Graphics")}}</code></li> + <li><code>{{Tag("Firefox OS")}}</code></li> + <li><code>{{Tag("Gecko")}}</code></li> + <li><code>{{Tag("XUL")}}</code></li> + <li><code>{{Tag("XPCOM")}}</code></li> + <li><code>{{Tag("SVG")}}</code></li> + <li><code>{{Tag("WebGL")}}</code></li> + <li><code>{{Tag("Element")}}</code></li> + <li><code>{{Tag("Node")}}</code></li> + <li><code>{{Tag("Tools")}}</code></li> + <li><code>{{Tag("Web")}}</code></li> +</ul> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output">一般而言，您的主题标识标签应该是一个接口的名称，和相关的页面（如<a href="/en-US/docs/Web/API/Node" title="/en-US/docs/Web/API/Node">Node</a>，它的各种属性和方法有很多页），或一个整体的技术类型的名称。<span>你可以对图形、WebGL和WebGL设置页面标签，而不仅是一个关于</span>{{HTMLElement("canvas")}} <span>与HTML、元素，Canvas，和图形。</span></p> + +<h4 class="ordinary-output target-output" id="Mozilla_特定内容"><span>Mozilla 特定内容</span></h4> + +<p><span>这些标签只用于Mozilla特定内容:</span></p> + +<ul> + <li>{{Tag("Mozilla")}}</li> + <li>{{Tag("Firefox")}}</li> + <li><code>{{Tag("Firefox OS")}}</code></li> + <li><code>{{Tag("Gecko")}}</code></li> + <li><code>{{Tag("XUL")}}</code></li> + <li><code>{{Tag("XPCOM")}}</code></li> +</ul> + + + +<h3 id="API_标识">API 标识</h3> + +<p>在API引用中, 每篇文章都应该标明它覆盖了哪部分API:</p> + +<dl> + <dt>{{tag("Interface")}}</dt> + <dd>一个接口的主要文章应该有这样的标签. 例如, {{DOMxRef("RTCPeerConnection")}}.</dd> + <dt>{{tag("Constructor")}}</dt> + <dd>每个接口最多可以有一个页面标记为“构造函数”（接口的构造函数）。页面应该有和接口一样的名字，如{{DOMxRef("RTCPeerConnection.RTCPeerConnection()","RTCPeerConnection()")}}.</dd> + <dt>{{tag("Property")}}</dt> + <dd>每一篇描述接口内特定属性的文章都需要这样的标记。以{{DOMxRef("RTCPeerConnection.connectionState")}}, 为例。</dd> + <dt>{{tag("Method")}}</dt> + <dd>每一篇记录接口方法的文章都需要这样的标记。以 {{DOMxRef("RTCPeerConnection.createOffer()")}}为例。</dd> +</dl> + +<p>此外，引用页面需要在其标记中包含接口、属性和方法名称。一些例子如下：</p> + +<dl> + <dt>接口 {{DOMxRef("RTCPeerConnection")}}</dt> + <dd>包含标签 "RTCPeerConnection" 以及其他相关标记 （"Interface"，"WebRTC"，"WebRTC API"，"API"，"Reference"等）。</dd> + <dt>方法{{DOMxRef("RTCPeerConnection.createOffer()")}}</dt> + <dd>包括标记 "RTCPeerConnection"和 "createOffer" (注意标记名中没有括号！) 以及其他相关标记，包括 "WebRTC"，"WebRTC API"，"API"，"Reference"等。考虑包含像 "Offer"和 "SDP"这些内容，它们在这里也是相关的。</dd> + <dt>属性{{DOMxRef("RTCPeerConnection.iceConnectionState")}}</dt> + <dd>包括标记"RTCPeerConnection"和"iceConnectionState"以及其他相关标记，包括 "WebRTC"，"WebRTC API"，"API"和"Reference"。也需要考虑包括 "ICE"。</dd> +</dl> + + + +<ul> +</ul> +</div> +</div> + +<h3 id="技术状况">技术状况</h3> + +<p>为了帮助读者了解可行的技术是怎样的，<span class="high-light-bg">我们使用标签来标记页面的技术规范的状态。</span><span class="high-light-bg">这并不像实际解释规格是什么，以及技术在规范过程中出现了多少（这正是规格表的用途）</span><span>，但它有助于读者判断，乍一看之下，使用在文章中描述的技术是否是一个好主意。</span></p> + +<p>这些标记是一些可能的值：</p> + +<dl> + <dt><code>{{Tag("Non-standard")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>表示页面中描述的技术或应用接口不是标准的一部分，但是在任何实现浏览器中都是稳定的。</span><span>如果你不使用这个标签，你的读者会认为这是标准的技术。</span><span>页面上的兼容性表应该说明该技术或API的支持。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Deprecated")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>网页上的技术或API被标记为过时的规范，并有可能最终被删除，但一般仍可用在当前版本的浏览器。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Obsolete")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>该技术或API已被认为已经过时，并已经在所有或大多数当前浏览器中被删除（或正在积极被删除）。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Experimental")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>技术不是规范，而是一个实验性的技术或API，可能会或可能不会成为标准的一部分。它可能</span>在浏览器的实现上被改变。</p> + </div> + </div> + </dd> + <dt><code>{{Tag("Needs Privileges")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>该接口要求访问该设备在该设备上运行的权限。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Certified Only")}}</code></dt> + <dd>该API仅适用于认证码。</dd> +</dl> + +<p>这些标签没有理由离开你文章中的 <a href="/en-US/docs/Project:Compatibility_tables" title="/en-US/docs/Project:Compatibility_tables">兼容性表</a> ！</p> + +<h3 id="技术水平">技术水平</h3> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>指南或教程的技术水平标签类型（那是，被标记的指南）帮助用户来基于他们的熟悉程度来选择教程，这里有三个值：</span></p> +</div> +</div> + +<dl> + <dt><code>{{Tag("Beginner")}}</code></dt> + <dd>介绍读者到一个从未使用过的技术或仅仅是一种熟悉的技术。</dd> + <dt><code>{{Tag("Intermediate")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>已经开始使用该技术的用户的文章，但不是专家。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Advanced")}}</code></dt> + <dd>关于拓展技术和读者能力的文章。</dd> +</dl> + +<h3 id="文档元数据">文档元数据</h3> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>写作社区要求根据特定类型的工作来使用标签标记文章。</span><span>以下是我们最常用的一个列表：</span></p> +</div> +</div> + +<dl> + <dt><code>{{Tag("Draft")}}</code></dt> + <dd>文章不完整，至少在理论上仍在积极更新（尽管它也有可能被遗忘）。在进行更改之前，请尝试与最新的贡献者进行检查，以避免潜在的内容冲突。</dd> + <dt><code>{{Tag("NeedsCompatTable")}}</code></dt> + <dd>文章需要一个表来指定跨浏览器特性的兼容性，有关促进浏览器兼容性的指南参见<a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">此处</a>。</dd> +</dl> + +<dl> + <dt><code>{{Tag("NeedsContent")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>文章是一个存根，或者是缺乏其他信息。</span><span>这个标签意味着有人应该审查的内容，并添加更多的细节和/或完成写作的文章。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("NeedsExample")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>文章需要一个或多个例子来帮助说明文章的要点。</span><span>这些例子应该使用</span><a href="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples" title="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples">实时示例系统</a>.</p> + </div> + </div> + </dd> + <dt><code>{{Tag("NeedsLiveSamples")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>本文有一个或多个实例，需要使用</span> <a href="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples" title="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples">在线样本系统</a>更新。</p> + </div> + </div> + </dd> + <dt><code>{{Tag("NeedsUpdate")}}</code></dt> + <dd>内容过时，需要更新。</dd> + <dt><code>{{Tag("l10n:exclude")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>内容是不真正值得本地化，不会出现在本地化状态页。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("l10n:priority")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>内容重要，应该被MDN标记为优先翻译。</span><span>在本地化状态页上显示了一个额外的优先级表。</span></p> + </div> + </div> + </dd> +</dl> + +<h3 id="Web_Literacy_Map">Web Literacy Map</h3> + +<p>The <a href="https://webmaker.org" rel="external">WebMaker</a> project, through the <a href="https://webmaker.org/literacy" rel="external">Web Literacy Map</a>, has defined skills needed to optimally read, write, and participate on the Web. We use Web literacy skills as tags on MDN to help our users find the resources that best suit their needs:</p> + +<dl> + <dt>{{Tag("Navigation")}}</dt> + <dd>文章包含关于在web上如何搜索的信息。</dd> + <dt>{{Tag("WebMechanics")}}</dt> + <dd>内容有关于web如何组织和如何工作的信息。</dd> + <dt>{{Tag("Search")}}</dt> + <dd>文章解释了如何在web上寻找信息、人和资源。</dd> + <dt>{{Tag("Credibility")}}</dt> + <dd>文章中的信息帮助读者理解怎样批判性的评估他们在web上找到的信息。</dd> + <dt>{{Tag("Security")}}</dt> + <dd>文章提供有关如何保持系统、身份和内容安全的信息。</dd> + <dt>{{Tag("Composing")}}</dt> + <dd>文档解释如何创建和curate web上的内容。</dd> + <dt>{{Tag("Remixing")}}</dt> + <dd>文章讲授如何修改existing的网络资源来创建新的东西。</dd> + <dt>{{Tag("Design")}}</dt> + <dd>文档解释如何提高视觉和其他用户体验。</dd> + <dt>{{Tag("Accessibility")}}</dt> + <dd>文档描述如何用universally-recognizable的方式交流。</dd> + <dt>{{Tag("CodingScripting")}}</dt> + <dd>如何在网络上写代码和（或）创造交互式的用户体验。</dd> + <dt>{{Tag("Infrastructure")}}</dt> + <dd>文档解释Internet's technical stack是如何工作的。</dd> + <dt>{{Tag("Sharing")}}</dt> + <dd>文章内容包含与他人一起创造资源的方式。</dd> + <dt>{{Tag("Collaborating")}}</dt> + <dd>文档提供关于如何与他人一同工作的信息。</dd> + <dt>{{Tag("Community")}}</dt> + <dd>文章详细说明如何参与网络社区并理解他们如何工作。</dd> + <dt>{{Tag("Privacy")}}</dt> + <dd>材料帮助检查在网络上分享数据的后果。</dd> + <dt>{{Tag("OpenPractices")}}</dt> + <dd>文章provid=deshow帮助保持人人可以连接网络。</dd> +</dl> + +<h2 id="把它们放到一起">把它们放到一起</h2> + +<p>就可以从几种标签种类中搜索你标记的网页，例如</p> + +<dl> + <dt>A tutorial about WebGL for beginners</dt> + <dd><code>WebGL</code>, <code>Graphics</code>, <code>Guide</code>, <code>Beginner</code></dd> + <dt>Reference page for {{HTMLElement("canvas")}}</dt> + <dd><code>Canvas</code>, <code>HTML</code>, <code>Element</code>, <code>Graphics,</code> <code>Reference</code></dd> + <dt>A landing page for Firefox OS developer tools</dt> + <dd><code>Tools</code>, <code>Firefox OS</code>, <code>Landing</code></dd> +</dl> + +<h2 id="标签和搜索过滤">标签和搜索过滤</h2> + +<p>只有我们正确地标记网页，搜索过滤才能正确工作。这是一个搜索过滤和它们寻找的标签的表格。</p> + +<div class="note"> +<p><strong>注意：Note:</strong> 如果多个标签被列在“tag name”下，那说明，为了搜索，任何一个或更多的标签必须在文章中。</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Filter group</th> + <th scope="col">Search filter name</th> + <th scope="col">Tag name</th> + </tr> + </thead> + <tbody> + <tr> + <th>Topic</th> + <td>Open Web Apps</td> + <td>{{Tag("Apps")}}</td> + </tr> + <tr> + <th></th> + <td>HTML</td> + <td>{{Tag("HTML")}}</td> + </tr> + <tr> + <th></th> + <td>CSS</td> + <td>{{Tag("CSS")}}</td> + </tr> + <tr> + <th></th> + <td>JavaScript</td> + <td>{{Tag("JavaScript")}}</td> + </tr> + <tr> + <th></th> + <td>APIs and DOM</td> + <td>{{Tag("API")}}</td> + </tr> + <tr> + <th></th> + <td>Canvas</td> + <td>{{Tag("Canvas")}}</td> + </tr> + <tr> + <th></th> + <td>SVG</td> + <td>{{Tag("SVG")}}</td> + </tr> + <tr> + <th></th> + <td>MathML</td> + <td>{{Tag("MathML")}}</td> + </tr> + <tr> + <th></th> + <td>WebGL</td> + <td>{{Tag("WebGL")}}</td> + </tr> + <tr> + <th></th> + <td>XUL</td> + <td>{{Tag("XUL")}}</td> + </tr> + <tr> + <th></th> + <td>Marketplace</td> + <td>{{Tag("Marketplace")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox</td> + <td>{{Tag("Firefox")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox for Android</td> + <td>{{Tag("Firefox Mobile")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox for Desktop</td> + <td>{{Tag("Firefox Desktop")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox OS</td> + <td>{{Tag("Firefox OS")}}</td> + </tr> + <tr> + <th></th> + <td>Mobile</td> + <td>{{Tag("Mobile")}}</td> + </tr> + <tr> + <th></th> + <td>Web Development</td> + <td>{{Tag("Web Development")}}</td> + </tr> + <tr> + <th></th> + <td>Add-ons & Extensions</td> + <td>{{Tag("Add-ons ")}}|| {{Tag("Extensions")}} || {{Tag("Plugins")}} || {{Tag("Themes")}}</td> + </tr> + <tr> + <th></th> + <td>Games</td> + <td>{{Tag("Games")}}</td> + </tr> + <tr> + <th>Skill level</th> + <td>I'm an Expert</td> + <td>{{Tag("Advanced")}}</td> + </tr> + <tr> + <th></th> + <td>Intermediate</td> + <td>{{Tag("Intermediate")}}</td> + </tr> + <tr> + <th></th> + <td>I'm Learning</td> + <td>{{Tag("Beginner")}}</td> + </tr> + <tr> + <th>Document type</th> + <td>Docs</td> + <td><em>This restricts the search to docs content, leaving out Hacks and other MDN content.</em></td> + </tr> + <tr> + <th></th> + <td>Demos</td> + <td><em>This includes Demo Studio content in the search results.</em></td> + </tr> + <tr> + <th></th> + <td>Tools</td> + <td>{{Tag("Tools")}}</td> + </tr> + <tr> + <th></th> + <td>Code Samples</td> + <td>{{Tag("Example")}}</td> + </tr> + <tr> + <th></th> + <td>How-To & Tutorial</td> + <td>{{Tag("Guide")}}</td> + </tr> + <tr> + <th></th> + <td>Developer Profiles</td> + <td><em>This includes developer profiles from the MDN site in the search results.</em></td> + </tr> + <tr> + <th></th> + <td>External Resources</td> + <td><em>The dev team is still figuring this out...</em></td> + </tr> + </tbody> +</table> + +<h2 id="你可以修改的标签的错误">你可以修改的标签的错误</h2> + +<p>这些种类的标签错误你可以帮助修改：</p> + +<dl> + <dt>没有标签</dt> + <dd>一般来说文章应该至少有一个 "<a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Category" title="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Categories">category</a>" 标签和一个 "<a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Topic" title="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Topic">topic</a>"标签. 虽然有其他标签也好, 但是如果你能帮我们提供最基本的标签（前文所说的category和topic标签）, 你将会是一名（维护）文档的英雄!</dd> + <dt>不符合我们<s>标签</s>标准的标签</dt> + <dd>请修正一切含有不合标准标签的文档.请注意由于<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=776048">Kuma的一个bug</a>, 一些本地化的标签(比如 <code>Référence</code>) 可能会出现在一些英语页面上. 这些标签还有可能反复出现,即使你已经吧它们删除; 请耐心处理这些问题直到kuma的那个bug被修复.</dd> + <dt>不正确的标签</dt> + <dd>如果你正在看一篇关于HTML的文章并且发现它被标上了"JavaScript"的标签, 那很有可能这是一个错误标签! 同理, 如果一篇文章在讨论Mozilla internals 但是有一个"Web"标签, 那也有可能是错误的. 删除这些错误的标签并且如果还没有合适标签的话，加上正确的标签. 同样请更正拼写错误的标签(e.g., 因为标签是大小写敏感的, 所以"Javascript" 仍然匹配, 但是我们还是不要马虎对待!).</dd> + <dt>缺失的标签</dt> + <dd>如果一篇文章有标签但是不全面, 请补全. 比如, 一页JavaScript 的参考文档被(正确) 标签为 "JavaScript" 但是除此之外什么也没有了, 请你就为它标上"参考"的标签!</dd> + <dt>垃圾标签</dt> + <dd>这只潜伏的怪兽是所有标签问题中最让人讨厌的: some Web vermin has deposited its droppings in the page tags (like "Free warez!" or "Hey I was browsing your site and wanted to ask you if you could help me solve this problem I'm having with Flash crashing all the time"). We've got to delete these right away! They're ugly, they're hard to manage if they're allowed to linger too long, and they're terrible for {{Glossary("SEO")}}.</dd> +</dl> + +<p>如果你发现了以上问题, 请<a href="/en-US/docs/Project:MDN/Contributing/Getting_started#Logging_into_MDN">登录MDN</a>点击MDN窗口右上方的 EDIT按钮. 等编辑器载入完成后, 到页面底部, 你就会看到标签. 想了解标签操作界面的更多信息, 请参看 "<a href="/en-US/docs/Project:MDN/Contributing/Editor_guide#The_tags_box" title="/en-US/docs/Project:MDN/Contributing/Editor_guide#The_tags_box">The tags box</a>" in the <a href="/en-US/docs/Project:MDN/Contributing/Editor_guide" title="/en-US/docs/Project:MDN/Contributing/Editor_guide">MDN editor guide</a>.</p> diff --git a/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html b/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html new file mode 100644 index 0000000000..4420d3f04e --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html @@ -0,0 +1,69 @@ +--- +title: 如何给JavaScript相关页面添加标签 +slug: MDN/Contribute/Howto/Tag_JavaScript_pages +translation_of: MDN/Contribute/Howto/Tag_JavaScript_pages +--- +<div>{{MDNSidebar}}</div><p class="summary"><strong>标记工作包括给页面添加元信息，使得这些页面的相关内容能被搜索工具等正确的分拣。</strong></p> + +<dl> + <dt>哪里需要做这件事<strong>?</strong></dt> + <dd>那些特定的<a href="/en-US/docs/Web/JavaScript/Doc_status#No_tags">没有标签的JavaScript相关的页面</a></dd> + <dt><strong>开始标记任务前你需要知道些什么？</strong></dt> + <dd>一些基本的JavaScript编程知识，比如javascript中的方法和属性都是些什么。</dd> + <dt><strong>你的工作有以下几个步骤</strong></dt> + <dd> + <ol> + <li>选择下面列举的某篇文章。</li> + <li>点击该文章所对应的链接，载入页面。</li> + <li>当页面载入完毕时，点击顶部附近的<strong>EDIT按钮，</strong>就会进入MDN编辑模式。</li> + <li>最后就是添加Javascript相关的标签了，我们提供了如下可选的标签。 + <table class="standard-table"> + <thead> + <tr> + <th scope="col">标签名</th> + <th scope="col">适用于含有哪些内容的页面</th> + </tr> + </thead> + <tbody> + <tr> + <td>Method</td> + <td>方法</td> + </tr> + <tr> + <td>Property</td> + <td>属性</td> + </tr> + <tr> + <td><font face="Consolas, Liberation Mono, Courier, monospace">Prototype</font></td> + <td>原型</td> + </tr> + <tr> + <td>Object type name</td> + <td>所述对象的名字，例如String.fromCharCode就应该有String标签</td> + </tr> + <tr> + <td><code>ECMAScript6 </code>and <code>Experimental</code></td> + <td>在新版ECMAScript标准中增加的特性</td> + </tr> + <tr> + <td><code>Deprecated</code></td> + <td>不赞成使用的特性（那些不鼓励使用但仍然被浏览器支持的特性）</td> + </tr> + <tr> + <td><code>Obsolete</code></td> + <td>被废弃的特性（那些不再被浏览器支持的特性）</td> + </tr> + <tr> + <td>others</td> + <td>查看 <a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards">MDN 标签规则</a> 中其他可选标签</td> + </tr> + </tbody> + </table> + </li> + <li>添加备注信息并保存你的修改。</li> + <li>你做到了！</li> + </ol> + </dd> +</dl> + +<p> </p> diff --git a/files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html b/files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html new file mode 100644 index 0000000000..29ad28e098 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html @@ -0,0 +1,107 @@ +--- +title: 如何撰写和引用一个词汇表中的条目 +slug: MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary +translation_of: MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary +--- +<div>{{MDNSidebar}}</div> + +<p>MDN <a href="/zh-CN/docs/Glossary">术语表</a> 是一个定义所有被用于文档和编码的术语、行话和缩写的地方。对词汇表做出贡献是使Web更易于理解的简单方法。您不需要高水平的技术技能来编写词汇表条目，因为它们应该保持简单直接。</p> + +<h2 id="如何写一个条目">如何写一个条目</h2> + +<p>如果您正在寻找需要词汇表条目的主题，请查看词汇表首页末尾的<a href="/zh-CN/docs/Glossary#Contribute_to_the_glossary">未撰写文档的条目清单</a>。请单击您希望创建的词汇条目的链接，进入”新的词汇表页面“准备新条目的创建。然后按照后面的步骤操作。</p> + +<p>如果您有添加新的词汇表条目的想法，只需在新选项卡中打开以下按钮，然后按照按钮下方的步骤操作：</p> + +<p></p><div class="align-center"><a class="button ignore-external mega positive" href="/zh-CN/docs/new?parent=4391">向术语表中添加一个新条目<div></div></a></div><p></p> + +<h3 id="第一步_写概要">第一步: 写概要</h3> + +<p>任何词汇表页面的第一段是对该术语的简单和简短描述（最好不超过两个句子）。 确保阅读说明的人能够立即了解定义的术语。</p> + +<div class="note"> +<p><strong>注意:</strong> 请不要直接从其他地方复制和粘贴定义（尤其是维基百科，因为许可证版本范围较小，因此与MDN不兼容）。确保条目内容简单易懂是很重要的。值得花一些时间来撰写定义，而不是简单盲目地窃取其他地方的内容。 这个词汇表应该是有用的新内容，而不是和别处重复的。</p> +</div> + +<p>使用“链接到词汇表条目”工具可以方便读者直接看到词汇条目中的定义，不需要读者跳转到词汇条目的页面。（更多内容请浏览如何使用 \{{Glossary}} 宏插入词汇表条目的链接。）</p> + +<p>如果需要的话，你可以添加少量额外的段落，但是这很容易导致你写了一整篇文章的情况发生。写一个完整的文章很棒，但是请不要把它们整个放在词汇表中。如果你不确定这里是否适合放你的文章，你就要随时<a href="/en-US/docs/MDN/Community#Join_our_mailing_lists">在这里讨论</a>。</p> + +<h3 id="第二步_扩展链接">第二步: 扩展链接</h3> + +<p>最后，一个词汇表的条目应该总是有“了解更多”这个部分。这个部分应该包含帮助读者看得更深入的链接：探索发现更多细节、学习使用相关技术等。</p> + +<p>我们建议您将链接分为以下三组：</p> + +<dl> + <dt>基础知识</dt> + <dd>提供更多一般信息的链接。如：到<a href="https://zh.wikipedia.org/">维基百科</a>的链接是一个很棒的点。 </dd> + <dt>技术参考</dt> + <dd>链接到更深入的技术信息，在MDN或其他地方。</dd> + <dt>学习它</dt> + <dd>链接到教程、练习或任何其他材料，帮助读者学习使用定义术语背后的技术。</dd> +</dl> + +<h2 id="小建议">小建议</h2> + +<p>所以你想贡献，但你不知道需要定义哪些术语？ <a href="/zh-CN/docs/Glossary#Contribute_to_the_glossary">这里是是建议列表</a>。点击一下，开始吧！</p> + +<h2 id="消除歧义">消除歧义</h2> + +<p>有时，根据上下文，术语有几个含义。 要解决歧义，您必须遵循以下准则：</p> + +<ul> + <li>该术语的主页面必须是一个包含了 {{TemplateLink("GlossaryDisambiguation")}} 宏的消歧页面；</li> + <li>该术语具有定义给定上下文的术语的子页面。</li> +</ul> + +<p>我们以一个例子来说明。<em>signature</em> 条目在至少三种不同的语境中具有不同的含义： <em>安全</em>、<em>函数 </em>和 <em>电子邮件</em>。</p> + +<ol> + <li><a href="/zh-CN/docs/Glossary/Signature">Glossary/Signature</a> 页面是使用了 {{TemplateLink("GlossaryDisambiguation")}} 宏的消歧页面；</li> + <li><a href="/zh-CN/docs/Glossary/Signature/Security">Glossary/Signature/Security</a> 页面是定义安全上下文中签名的条目页面；</li> + <li><a href="/zh-CN/docs/Glossary/Signature/Function">Glossary/Signature/Function</a> 页面是定义函数签名的条目页面；</li> + <li><a href="/zh-CN/docs/Glossary/Signature/Email">Glossary/Signature/Email</a> 页面是定义电子邮件签名的条目页面。</li> +</ol> + +<h2 id="如何使用_Glossary_宏">如何使用 \{{Glossary}} 宏</h2> + +<p>当人们可以在另一个文档访问到词汇的定义，而无需他们从正在阅读的内容进行跳转阅读词汇定义时，词汇表是最好用的。因此，我们敦促您随时使用 {{TemplateLink("Glossary")}} 宏将词汇链接到词汇表：</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">宏</th> + <th scope="col">结果</th> + <th scope="col">备注</th> + </tr> + </thead> + <tbody> + <tr> + <td>\{{Glossary("browser")}}</td> + <td>{{Glossary("browser")}}</td> + <td>当文本与要定义的术语匹配时，只需直接使用宏（不区分大小写）</td> + </tr> + <tr> + <td>\{{Glossary("browser", "Web浏览器")}}</td> + <td>{{Glossary("browser","Web浏览器")}}</td> + <td>要显示替代文本，请使用第二个参数来指定该文本</td> + </tr> + <tr> + <td>\{{Glossary("browser", "Web浏览器", 1)}}</td> + <td>{{Glossary("browser","Web浏览器",1)}}</td> + <td>指定 <code>1</code> 作为可选的第三个参数，将链接显示为常规链接，而不是单纯的提示文本的样式</td> + </tr> + </tbody> +</table> + +<p>使用 \{{Glossary}} 宏创建的链接将总是展示一个包含了词汇表条目的概要段落的提示文本（tooltip）。</p> + +<h3 id="使用方针">使用方针</h3> + +<p>在许多情况下，在MDN上的任何地方使用该宏是非常安全的。 但是，您应该谨慎处理的几种情况：</p> + +<ul> + <li>如果一个术语已经链接到MDN的另一部分，这样的情况请不要使用 \{{Glossary}} 宏；</li> + <li>在文章部分（Section）中，对于相同的术语仅使用一次 \{{Glossary}} 宏 （<em>提示：一个部分总是以标题开始的</em>）。</li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html new file mode 100644 index 0000000000..4ef7b2bcec --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html @@ -0,0 +1,446 @@ +--- +title: How to write an API reference +slug: MDN/Contribute/Howto/Write_an_API_reference +tags: + - API + - Documentation + - Guide + - Howto + - MDN Meta + - NeedsTranslation + - TopicStub +translation_of: MDN/Contribute/Howto/Write_an_API_reference +--- +<div>{{MDNSidebar}}</div> + +<div class="summary"> +<p><span class="seoSummary">This guide takes you through all you need to know to write an API reference on MDN.</span></p> +</div> + +<h2 id="Getting_prepared">Getting prepared</h2> + +<p>Before starting to document an API, there are some things you should prepare and plan in advance of starting to actually write.</p> + +<h3 id="Prerequisite_knowledge">Prerequisite knowledge</h3> + +<p>It is assumed that before reading this guide you have a reasonable knowledge of:</p> + +<ul> + <li>Web technologies like HTML, CSS and JavaScript. JavaScript is most important.</li> + <li>Reading Web technology specs. You'll be looking at these a lot as you document APIs.</li> +</ul> + +<p>Everything else can be learned along the way.</p> + +<h3 id="Prerequisite_resources">Prerequisite resources</h3> + +<p>Before starting to document an API, you should have available:</p> + +<ol> + <li>The latest spec: Whether it is a W3C Recommendation or an early editor's draft, you should refer to the latest available draft of the spec that covers (or specs that cover) that API. To find it, you can usually do a Web search. The latest version will often be linked to from all versions of the spec, listed under "latest draft" or similar.</li> + <li>The latest modern web browsers: These should be experimental/alpha builds such as <a href="https://nightly.mozilla.org/">Firefox Nightly</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">Chrome Canary</a> that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a nascent/experimental API.</li> + <li>Demos/blog posts/other info: Find as much info as you can.</li> + <li>Useful engineering contacts: It is really useful to find yourself a friendly engineering contact to ask questions about the spec, someone who is involved in the standardization of the API, or its implementation in a browser. Good places to find them are: + <ul> + <li>Your internal company address book, if you work for a relevant company.</li> + <li>A public mailing list that is involved in the discussion of that API, such as Mozilla's <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a> or <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> lists, or a W3C list like <a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a>.</li> + <li>The spec itself. For example, the <a href="https://webaudio.github.io/web-audio-api/">Web Audio API spec</a> lists the authors and their contact details at the top.</li> + </ul> + </li> +</ol> + +<h3 id="Take_some_time_to_play_with_the_API">Take some time to play with the API</h3> + +<p>You will return to building demos many times through the course of documenting an API, but it is useful to start by spending time familiarizing yourself with how the API works — learn what the main interfaces/properties/methods are, what the primary use cases are, and how to write simple functionality with it.</p> + +<p>When an API has changed, you need to be careful that existing demos you refer to or learn from are not out of date. Check the main constructs that are used in the demo to see if they match up to the latest spec. They may also not work in up-to-date browsers, but this is not a very reliable test, as often the old features continue to be supported for backwards compatibility.</p> + +<div class="note"> +<p><strong>Note</strong>: If the spec has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place, so that the old and new methods are covered. If you need help, refer to demos you have found, or ask an engineering contact.</p> +</div> + +<h3 id="Create_the_list_of_documents_you_need_to_write_or_update">Create the list of documents you need to write or update</h3> + +<p>Reference documents for an API are quite numerous. There is an overview page for the API, a page for each interface, one for each method (including constructors) and property (including event handlers properties). There is also one page per event.</p> + +<h4 id="Overview_page">Overview page</h4> + +<p>The API overview page described the role of the API and the top-level interfaces. Its name is NAME OF API and its slug (that is the end part of the URL) must contains at least one space. It is placed at the top level of the API reference (<a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>)</p> + +<ul> + <li>Title: <em>Web Audio API</em></li> + <li>Slug: <em>Web/API/Web_Audio_API</em></li> + <li>Tags: must include the 'Overview' and 'API' tags</li> +</ul> + +<p>Note that most API have a special sidebar with quicklinks. This sidebar lists all interfaces, and possibly tutorials and related API.</p> + +<h4 id="Interfaces">Interfaces</h4> + +<p>Each interface will have its own page too. It will describe the purpose of the interface and lists all constructors, methods, and properties. The title of the page will be the name of the interface (always starting with an uppercase letter), its slug, the interface name, will be at the top level of the API reference (<a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>)</p> + +<ul> + <li>Title: <em>AudioContext</em></li> + <li>Slug: <em>Web/API/AudioContext</em></li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface.</em></li> +</ul> + +<ul> + <li>Title: <em>AudioNode</em></li> + <li>Slug: <em>Web/API/AudioNode</em></li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface</em>.</li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> We document every property and interface appearing in the <u>prototype</u> of an object implementing this interface. This has the following consequences:</p> + +<ul> + <li>We do not document inherited properties and methods of the interface: they are listed on the respective parent interface. We do hint at their existence though.</li> + <li>We do document properties and methods defined in mixins, though we use the mixin name as interface name. (This is not optimal as the mixin name will not appear in the console, but prevents the duplication of documentation. We may revisit this in the future.)</li> + <li>There is one subpage per method, or constructor: if there are several variants, with different parameters, we still create one subpage and use its Syntax section to list all variants.</li> + <li>Special methods like the stringfier (<code>toString()</code>) and the jsonizier (<code>toJSON()</code>) are also listed if they do exist.</li> + <li>Named constructors (like <code>Image()</code> for {{domxref("HTMLImageElement")}} ) are also listed, if relevant.</li> +</ul> +</div> + +<h4 id="Properties">Properties</h4> + +<p>The set of properties of a given interface can be found on its <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#Properties">WebIDL</a>. We document each one in a single page. It will describe the purpose of the property, its syntax, and provide examples of use, in isolation. Its slug is the property name, as a subpage of the interface:</p> + +<ul> + <li>Title: <em>AudioContext.currentTime</em></li> + <li>Slug: <em>Web/API/AudioContext/currentTime</em></li> + <li>Tags: must contain the API name as a tag (here <em>Web Audio API</em>), the interface name (here <em>AudioContext</em>) as well as <em>Property</em>. If the property is read-only, like this example, <em>Read-only</em> must be added too.<br> + </li> + <li>Title: <em>AudioNode.numberOfInputs</em></li> + <li>Slug: <em>Web/API/AudioNode/numberOfInputs</em></li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface</em>.</li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> Event handlers properties (<code>onXYZ</code> properties) are also listed: they'll have their individual subpage, like any other property.</p> +</div> + +<h4 id="Methods">Methods</h4> + +<p>Like for properties, methods are listed on the interface's <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#Methods">WebIDL</a> and we document each method in a single page. It will describe the purpose of the method, its syntax, and provide examples of use, in isolation. Its slug, without the parenthesis, is the method name, as a subpage of the interface:</p> + +<ul> + <li>Title: <em>AudioContext.createBuffer()</em> Note the parentheses, making it clear that it is a method.</li> + <li>Slug: <em>Web/API/AudioContext/createBuffer </em>No parenthesis here.</li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), the interface name (here <em>AudioContext</em>) as well as <em>Method</em>.</li> +</ul> + +<h4 id="Constructors">Constructors</h4> + +<p>Similar in structure to methods, they also have their own pages. Note that only one unnamed constructor may exist per interface. The title convention is slightly different than the one of methods: it isn't prefixed.</p> + +<ul> + <li>Title: <em>Worker() </em>Note the parenthesis and the absence of prefix</li> + <li>Slug: <em>Web/API/Worker/Worker</em> No parenthesis here. Constructors are also subpages of the interface page.</li> + <li>Tags: must include the API name as a tag (here <em>Web Workers</em>), the interface name (here Worker) as well as<em> Constructor</em>.</li> +</ul> + +<h4 id="Events">Events</h4> + +<p>Events are the last type of objects needing documentation. Unless the previous documents, event subpages lies under the Web/Events hierarchy. Each event has its own subpage:</p> + +<ul> + <li>Title: <em>start</em></li> + <li>Slug: <em>Web/Events/start</em></li> +</ul> + +<h4 id="Listing_them_all">Listing them all</h4> + +<p>Creating a list of all these subpages is a good way to track them. For example:</p> + +<ul> + <li>Web_Audio_API</li> + <li>AudioContext + <ul> + <li>AudioContext.currentTime</li> + <li>AudioContext.destination</li> + <li>AudioContext.listener</li> + <li> ...</li> + <li>AudioContext.createBuffer()</li> + <li>AudioContext.createBufferSource()</li> + <li> ...</li> + </ul> + </li> + <li>AudioNode + <ul> + <li>AudioNode.context</li> + <li>AudioNode.numberOfInputs</li> + <li>AudioNode.numberOfOutputs</li> + <li> ...</li> + <li>AudioNode.connect(Param)</li> + <li> ...</li> + </ul> + </li> + <li>AudioParam</li> + <li>Events (update list) + <ul> + <li>start</li> + <li>end</li> + <li>…</li> + </ul> + </li> +</ul> + +<p>Each interface in the list has a separate page created for it as a subpage of https://developer.mozilla.org/en-US/docs/Web/API; for example, the document for {{domxref("AudioContext")}} would be located at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext. Each {{anch("Interface pages", "interface page")}} explains what that interface does and provides a list of the methods and properties that comprise the interface. Then each method and property is documented on its own page, which is created as a subpage of the interface it's a member of. For instance, {{domxref("AudioContext.currentTime")}} is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/currentTime.</p> + +<p>For example, given the list above, the {{domxref("AudioContext")}} interface is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext</p> + +<h3 id="Create_the_overview_page">Create the overview page</h3> + +<p>Now create the overview (API landing) page:</p> + +<ol> + <li>Go to <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a> and, making sure you are logged in, select the <em>Cog icon > New sub-page</em>. You should now be in an editor for a new page.</li> + <li>Enter the title as the API name as defined by the spec, plus "API". So for example "Web Audio API", "IndexedDB API", or "MediaRecorder API".</li> + <li>The Slug should be auto-filled, with underscores in the place of spaces. If it isn't, correct it.</li> + <li>Enter some dummy content into the large content area, such as "TBD" or "Content", then click <em>Save Changes</em>. Or just soar right on into the section {{anch("Overview page")}} and start filling out the real content right away.</li> +</ol> + +<p>Your landing page now exists! Now all you have to do is fill it in, which is discussed in the next section.</p> + +<h2 id="Structure_of_an_overview_page">Structure of an overview page</h2> + +<div class="warning"> +<p><strong>Important</strong>: This section is still a proposal, without consensus yet reached. Don't use it yet.</p> +</div> + +<p>API landing pages will differ greatly in length, depending on how big the API is, but they will all have basically the same features. See <a href="/en-US/docs/Web/API/Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API</a> for an example of a big landing page.</p> + +<p>The features of a landing page are outlined below:</p> + +<ol> + <li><strong>Description</strong>: the first paragraph of the landing page should provide a short, concise description of the API's overarching purpose.</li> + <li><strong>Concepts and usage section</strong>: The next section should be titled "[name of API] concepts and usage", and provide an overview of all the main functionality that the API provides, what problems it solves, and how it works — all at a high level. This section should be fairly short, and not go into code or specific implementation details.</li> + <li><strong>List of interfaces</strong>: This section should be titled "[name of API] interfaces", and provide links to the reference page for each interface that makes up the API, along with a short description of what each one does. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create new pages. Only current interfaces should be in this list; obsolete ones should be placed in (or moved into, if obsoleted after initially being documented) the following section.</li> + <li><strong>Obsolete interfaces:</strong> This section lists obsolete interfaces. <em>Ed. note: should this be a subsection of the main "Interfaces" section above?</em></li> + <li><strong>List of mixins</strong>: If any mixins are defined on the API spec, list them under a separate section, as they aren't interfaces as such.</li> + <li><strong>Example</strong>: This section should show a simple use case for the API.</li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc.</li> + <li><strong>Tags</strong>: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.</li> +</ol> + +<h2 id="Structure_of_an_interface_page">Structure of an interface page</h2> + +<p>Now you should be ready to start writing your interface pages. Each interface reference page should observe the following structure:</p> + +<ol> + <li><strong>\{{APIRef}}</strong>: Include the \{{APIRef}} macro in the first line of each interface page, including the name of the API as an argument, so for example \{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left hand side of the interface page, including properties and methods, and other quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.<br> + <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li> + <li><strong>Standardization status</strong>: The banner indicating the standardization status should be added next (these can be placed on the same line as the \{{APIRef}} macro.): + <ul> + <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li> + <li>\{{Deprecated_header}}</li> + <li>\{{Obsolete_header}}</li> + <li>\{{Non-standard_header}}</li> + </ul> + </li> + <li><strong>Description</strong>: the first paragraph of the interface page should provide a short concise description of the interface's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Note that if the interface defines a mixin, you shouldn't use the term "Interface" to describe it, but mixin instead — it isn't really a standalone interface as such, but a mixin that adds functionality to multiple other interfaces. Similarly, if the interface is actually a dictionary, you should use that term instead of "interface".</li> + <li><strong>Inheritance diagram:</strong> Use the {{TemplateLink("InheritanceDiagram")}} macro to embed an SVG inheritance diagram for the interface. For most interfaces, you won't need any parameters, but if the inheritance chain is long, you may need to use \{{InheritanceDiagram(600, 120)}} to make room vertically for two rows of boxes.</li> + <li> + <p><strong>List of properties, List of methods</strong>: These sections should be titled "Properties" and "Methods", and provide links (using the \{{domxref}} macro) to a reference page for each property/method of that interface, along with a description of what each one does. These should be marked up using description/definition lists, which can be created using the "Definition List", "Definition Term", and "Definition Description" buttons on the MDN editor toolbar. Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create links to other pages.<br> + <br> + At the beginning of both sections, before the beginning of the list of properties/methods, indicate inheritance using the appropriate sentence, in italics:<br> + <em>This interface doesn't implement any specific properties, but inherits properties from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em><br> + <em>This interface also inherits properties from </em><em>\{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.<br> + This interface doesn't implement any specific methods, <em>but inherits methods from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em><br> + <em>This interface also inherits methods from </em><em>\{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em></em></p> + + <div class="note"> + <p><strong>Note</strong>: If the interface features event handlers, put these inside the "Properties" section (they are a type of property) under a subheading of "Event handlers".</p> + </div> + + <div class="note"> + <p><strong>Note</strong>: Properties that are read-only should have the \{{readonlyInline}} macro, which creates a nifty little "Read only" badge, included on the same line as their \{{domxref}} links (after the use of the \{{experimentalInline}}, \{{obsoleteInline}}, \{{non-standard_Inline}} and \{{deprecatedInline}} macros, if some of these are needed.</p> + </div> + </li> + <li><strong>Example</strong>: Include a code listing to show typical usage of a major feature of the API. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you could reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">Github gh-pages </a>feature (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page. + <div class="note"> + <p><strong>Note</strong>: More details about writing code examples can be found in the "Examples" section.</p> + </div> + </li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>Polyfill</strong>: If appropriate, include this section, providing code for a polyfill that enables the API to be used even on browsers that don't implement it. If no polyfill exists or is needed, leave this section out entirely.</li> + <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc. We have a liberal policy for linking to external sources, but pay attention: + <ul> + <li>Do not include pages with the same information as another page in the MDN; link to that page instead.</li> + <li>Do not put author names — we are a writer-neutral documentation site. Link to the document; the author name will be displayed there.</li> + <li>Pay special attention to blog posts: they tend to become outdated (old syntax, wrong compat information). Link to them only if they have a clear added value that can't be found in a maintained document.</li> + <li>Do not use action verb like "See … for more information" or "Click to…", you don't know if your reader is able to see, or to click on the link (like on a paper version of the document).</li> + </ul> + </li> + <li><strong>Tags</strong>: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.</li> +</ol> + +<h3 id="Interface_page_examples">Interface page examples</h3> + +<p>The following are exemplary examples of Interface pages:</p> + +<ul> + <li>{{domxref("Request")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li> + <li>{{domxref("SpeechSynthesis")}} from the <a href="/en-US/docs/Web/API/Web_Speech_API">Web Speech API</a>.</li> +</ul> + +<h2 id="Structure_of_a_property_page">Structure of a property page</h2> + +<p>You can now fill in your interface property pages. Since the structures of all of them are the same, it usually works best to open all the property pages for each interface in separate tabs. From here you can fill one in fully, then copy its contents to all the other property pages and just update the bits that need changing, rather than having to fill each one in from scratch.</p> + +<p>Edit the property page name to follow the <code>Interface.property_name</code> convention.</p> + +<p>Property pages must have the following sections:</p> + +<ol> + <li><strong>Title</strong>: the title of the page must be <strong>InterfaceName.propertyName</strong>. The interface name must start with a capital letter. Although an interface is implemented in JavaScript on the prototype of objects, we don't include <code>.prototype.</code> in the title, like we do in the <a href="/en-US/docs/Web/JavaScript/Reference">JavaScript reference</a>.</li> + <li><strong>\{{APIRef}}</strong>: Include the \{{APIRef}} macro in the first line of each property page, including the name of the API as an argument, so for example \{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left hand side of the interface page, including properties and methods, and other quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.<br> + <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li> + <li><strong>Standardization status</strong>: The banner indicating the standardization status should be added next to the interface name (these can be placed on the same line as the \{{APIRef}} macro): + <ul style="margin-left: 40px;"> + <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li> + <li>\{{Deprecated_header}}</li> + <li>\{{Obsolete_header}}</li> + <li>\{{Non-standard_header}}</li> + </ul> + </li> + <li><strong>Description</strong>: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read only or not. The structure of the first sentence must be: + <dl> + <dt>For read-only properties</dt> + <dd>The <code><strong>InterfaceName.property</strong></code> read-only property returns a \{{domxref("type")}} that...</dd> + <dt>For other properties</dt> + <dd>The <strong><code>InterfaceName.property</code></strong> property is a \{{domxref("type")}} that…</dd> + </dl> + + <div class="note"><strong>Note</strong>: <code>InterfaceName.property</code> should be in <code><code></code>, and should additionally be in bold (<code><strong></code>) the first time it's used.</div> + </li> + <li><strong>Syntax</strong>: The syntax section should show how to get the property, and how to set it, if it's not read only. Use the <code>syntaxbox</code> class for it and italics for part to be replaced by the actual variable name. For example: + <pre class="syntaxbox">var <em>myType</em> = <em>oscillator</em>.type; +<em>oscillator</em>.type = <em>aType;</em> +</pre> + The syntax section should also have a subsection — "Value", which will contain a description of the property's value. This should contain the data type of the property, and what it represents. For an example, see {{domxref("SpeechRecognition.grammars")}}</li> + <li> + <p><strong>Example</strong>: Include a code listing to show typical usage of the property in question. You should start with a simple example that shows how an object of the type is created and how to access the property. More complex examples can be added after such an example. In these additional examples, rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you can reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">github gh-pages feature</a> (so long as it uses only client-side code of course.) You can also make use of the <a href="/en-US/docs/MDN/Contribute/Tools/Sample_server">MDN Sample Server</a>, which is particularly helpful for more complex samples. If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.</p> + + <div class="note"><strong>Note</strong>: If you make use of Github, the example must live under <a href="https://github.com/mdn/">github.com/mdn</a>. See the "Examples" section for more details.</div> + </li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when using this technology: like methods and properties affected by a change of this property or events thrown in relation to it. More links useful when learning about this technology, including MDN (and external) tutorials, examples, libraries,… can be added, though it may be useful to consider adding them on the interface reference page instead.</li> + <li><strong>Tags</strong>: There is a set of standard tags you should include for each property page — see the "Tags" section for more.</li> +</ol> + +<h3 id="Property_page_examples">Property page examples</h3> + +<p>The following are exemplary examples of property pages:</p> + +<ul> + <li>{{domxref("Request.method")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li> + <li>{{domxref("SpeechSynthesis.speaking")}} from the <a href="/en-US/docs/Web/API/Web_Speech_API">Web Speech API</a>.</li> +</ul> + +<h2 id="Structure_of_a_method_page">Structure of a method page</h2> + +<p>You can now fill in your interface method pages. Since the structure of all of them are the same, one possible way of doing it is to open all the method pages for each interface in separate tabs. From here you can fill one in fully, then copy its contents to all the other method pages and just update the bits that need changing, rather than having to fill each one in from scratch.</p> + +<p>Method pages need the following sections:</p> + +<ol> + <li><strong>Title</strong>: the title of the page must be <strong>InterfaceName.method()</strong> (with the two terminal parentheses), but the slug (the end of the page URL) must not include the brackets. Also the interface name must start with a capital. Although an interface is implemented in JavaScript on the prototype of objects, we don't put <code>.prototype.</code> in the title, like we do in the <a href="/en-US/docs/Web/JavaScript/Reference">JavaScript reference</a>.</li> + <li><strong>\{{APIRef}}</strong>: Include the \{{APIRef}} macro in the first line of each method page, including the name of the API as an argument, so for example \{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left hand side of the interface page, including properties and methods, and other quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.<br> + <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li> + <li><strong>Standardization status</strong>: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \{{APIRef}} macro): + <ul> + <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li> + <li>\{{Deprecated_header}}</li> + <li>\{{Obsolete_header}}</li> + <li>\{{Non-standard_header}}</li> + </ul> + </li> + <li><strong>Description</strong>: The first paragraph of the method page should provide a short concise description of the method's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default parameter values, any theory that the method relies on, and what the parameter values do. + <dl> + <dt>The beginning of the first sentence must follow the following structure:</dt> + <dd>The <strong>InterfaceName.method()</strong> method interface ...</dd> + </dl> + + <div class="note"><strong>Note:</strong> <code>InterfaceName.method()</code> should be in <code><code></code>, and should also be in bold (<code><strong></code>) the first time it's used.</div> + </li> + <li><strong>Syntax</strong>: The syntax section should include a 2–3 line example — usually just construction of the interface, then calling of the interface method. + <dl> + <dt>The syntax should be of the form:</dt> + <dd>var <em>returnValue</em> = <em>ifName</em>.method(<em>param1</em>, <em>param2</em>, ...)</dd> + <dt>If the method has no return value (<code>void</code> as return value in the webidl), use:</dt> + <dd><em>ifName</em>.method(<em>param1</em>, <em>param2</em>, ...)</dd> + </dl> + The syntax section should include three subsections (see {{domxref("SubtleCrypto.sign()")}} for an example): + + <ul> + <li>"Parameters": This should contain a definition list (or unordered list) that names and describes the different parameters the method takes. You should include the {{optional_inline}} macro next to the parameter name, in the case of optional parameters. If there are no parameters, this section should be omitted.</li> + <li>"Return value": This should say what return value the method has, be it a simple value like a double or boolean, or a more complex value like another interface object, in which case you can use \{{domxref}} macro to link to the MDN API page covering that interface (if it exists.) A method might return nothing, in which case the return value should be written as "\{{jsxref('undefined')}}" (which will look like this in the rendered page: {{jsxref("undefined")}}).</li> + <li>"Exceptions": This should list the different exceptions that can be raised when invoking the method, and what circumstances cause them. If there are no exceptions, this section should be omitted.</li> + </ul> + </li> + <li><strong>Example</strong>: Include a code listing to show typical usage of the method in question. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you should reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">Github gh-pages feature</a> (so long as it uses only client-side code of course.) You can also make use of the <a href="/en-US/docs/MDN/Contribute/Tools/Sample_server">MDN Sample Server</a>, which is particularly helpful for more complex samples. See the "Examples" section for more details. If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.</li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>Polyfill</strong>: If appropriate (especially if common browsers are still shipping without support for the method), you can include a section which includes the code for a polyfill to allow the API to be used in browsers that don't implement it.</li> +</ol> + +<h3 id="Method_page_examples">Method page examples</h3> + +<p>The following are exemplary examples of Interface pages:</p> + +<ul> + <li>{{domxref("Document.getAnimations()")}} from the <a href="/en-US/docs/Web/API/Web_Animations_API">Web Animations API</a>.</li> + <li>{{domxref("GlobalFetch.fetch()")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li> +</ul> + +<h2 id="Tagging">Tagging</h2> + +<p>For API reference pages, there are standard tags that all pages should have:</p> + +<ul> + <li>"API"</li> + <li>"Reference"</li> + <li>Name of API (e.g. "Web Audio API")</li> + <li>Any pertinent related keywords (e.g. "audio") </li> +</ul> + +<p>For Interface pages, also add:</p> + +<ul> + <li>"Interface"</li> + <li>The name of the interface, e.g. "AudioContext"</li> +</ul> + +<p>For method pages, also add:</p> + +<ul> + <li>"Method"</li> + <li>The name of the interface the method relates to, e.g. "AudioContext"</li> + <li>The name of the method, e.g. "createBuffer"</li> +</ul> + +<p>For property pages, also add:</p> + +<ul> + <li>"Property"</li> + <li>The name of the interface the property relates to, e.g. "AudioContext"</li> + <li>The name of the property, e.g. "currentTime" </li> +</ul> + +<p>In all cases, also add a keyword indicating the standardization status:</p> + +<ul> + <li>Experimental (if the spec is not a CR)</li> + <li>Deprecated</li> + <li>Obsolete</li> + <li>Non-standard</li> +</ul> + +<p>These tags will be used to generate correct quicklinks, with nice icons. See <a href="/en-US/docs/MDN/Contribute/Howto/Tag">How to properly tag pages</a> for additional information on tagging, as well as about other tags you may find useful.</p> diff --git a/files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html new file mode 100644 index 0000000000..239c6a83f4 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html @@ -0,0 +1,505 @@ +--- +title: Information contained in a WebIDL file +slug: >- + MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file +translation_of: >- + MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file +--- +<div> +<p><font><font>{{MDNSidebar}}</font></font></p> + +<p><font><font>在编写有关API的文档时，信息来源很多：规范描述了应该实现的内容以及模型，实现描述了实际放在浏览器中的内容。</font><font>WebIDL文件是一种非常简洁的方式，可以提供很多（但不是全部）有关API的信息。</font><font>本文档提供了有助于理解WebIDL语法的参考。</font></font></p> + +<p><font><font>IDL代表</font></font><em><strong><font><font>接口定义语言</font></font></strong></em><font><font>，它用于描述API。</font><font>在更广泛的计算领域，有几种IDL。</font><font>在浏览器领域，我们使用的IDL称为</font></font><em><font><font>WebIDL</font></font></em><font><font>。</font><font>有两种WebIDL可用：WebIDL规范中给出的一种，以及在浏览器中实现的一种。</font><font>规范是规范引用，浏览器WebIDL描述了在特定浏览器中实际实现的内容，并包含其他内容，例如注释和有关非标准元素的信息。</font></font></p> +</div> + +<p> </p> + +<h2 id="在哪里可以找到WebIDL文件"><font><font>在哪里可以找到WebIDL文件</font></font></h2> + +<p><font><font>WebIDL可以在多个位置找到：</font></font></p> + +<ul> + <li><font><font>每个规范在文本中都包含WebIDL：它是一种传达精确定义的非常方便的方法。</font><font>这些描述了API的语法。</font><font>虽然是规范参考，但我们必须记住，它们可能与实际实施不同。</font><font>在MDN上，我们希望实用并记录Web平台的真正含义，而不是理想应该是什么。</font><font>因此，请仔细检查实现中的内容（如果发现错误，请不要犹豫，立即提交）。</font></font></li> + <li><font><font>三个浏览器引擎使用（修改）WebIDL作为其工具链的一部分：Gecko，Chromium / Blink和WebCore / WebKit。</font><font>Edge在内部使用它，但遗憾的是它们不公开（它会帮助我们很多）。</font></font> + <ul> + <li><font><font>对于Gecko，所有WebIDL文件都分组在一个目录中：</font></font><a href="https://dxr.mozilla.org/mozilla-central/source/dom/webidl/">https://dxr.mozilla.org/mozilla-central/source/dom/webidl/</a><font><font> </font></font></li> + <li><font><font>他们的延伸是</font></font><code>.webidl</code><font><font>。</font></font><code>*.idl</code><font><font>Gecko源代码树中</font><font>还有其他 </font><font>文件，但它们不是WebIDL，因此您可以忽略它们。</font><font>旧版本的Gecko有一些WebIDL分散在某些地方，甚至可能使用Mozilla的IDL而不是WebIDL来描述一些Web界面，但这在任何最近的Gecko代码中都不会成为问题。</font></font></li> + <li><font><font>对于Chromium，它们分散在源代码中，所以你需要多花点功夫：例如</font></font><a href="http://src.chromium.org/viewvc/blink/trunk/Source/modules/mediastream/MediaStream.idl"><font><font>http://src.chromium.org/viewvc/blink/trunk/Source/modules/mediastream/MediaStream.idl</font></font></a></li> + <li><font><font>同样，WebCore正如预期的那样，因为Chromium是从它分叉出来的，例如</font></font><a href="https://github.com/WebKit/webkit/blob/master/Source/WebCore/html/DOMTokenList.idl"><font><font>https://github.com/WebKit/webkit/blob/master/Source/WebCore/html/DOMTokenList.idl</font></font></a> </li> + </ul> + </li> +</ul> + +<h2 id="Different_dialects_of_WebIDL">Different dialects of WebIDL</h2> + +<p>WebIDL is defined in <a href="https://heycam.github.io/webidl/">its specification</a>. But it has been designed to be extended to convey more information, and browser vendors have done so:</p> + +<ul> + <li>For Gecko, MDN has the <a href="/en-US/docs/Mozilla/WebIDL_bindings">documentation</a> of its dialectal WebIDL.</li> + <li>For Chromium, Google also created a <a href="https://www.chromium.org/blink/webidl">document</a> to describe its extensions.</li> + <li>For WebCore, Apple also made available a <a href="https://trac.webkit.org/wiki/WebKitIDL">page</a> for its dialect.</li> +</ul> + +<div class="note"> +<p>We describe here only the subset of WebIDL which is most useful when writing documentation. There are many more annotations useful for implementers; refer to the four documents linked above to have a complete overview.</p> +</div> + +<h2 id="Interfaces">Interfaces</h2> + +<p>This section explains the WebIDL syntax that describes overall API features.</p> + +<h3 id="Name_of_the_interface">Name of the interface</h3> + +<p>The interface name is the string that appears after the keyword <code>interface</code><em> </em>and before the next opening bracket (<code>'{'</code>) or colon (<code>':'</code>).</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>interface</strong> URL {};</span></pre> + +<p>Each WebIDL interface, being a true interface or a mixin, has its own page in the documentation, listing every constructor, property and method defined for it.</p> + +<h3 id="Inheritance_chain">Inheritance chain</h3> + +<p>The parent, if any, of a given interface is defined after the interface name, following a colon (<code>':'</code>). There can be only one parent per interface.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">interface HTMLMediaElement : <strong>HTMLElement</strong> {…}</span></pre> + +<p><span>The inheritance chain is listed automatically in the sidebar (using the \{{APIRef}} macro). It can also be added as an SVG image via the macro \{{InheritanceDiagram}}.</span></p> + +<h3 id="Mixins">Mixins</h3> + +<p>Some properties or methods are available to several interfaces. To prevent redefinition they are defined in special WebIDL interfaces called <em>mixins</em>. In the WebIDL, they are prefixed using the <code>[NoInterfaceObject]</code> annotation. The name of a mixin, <code>Body</code> in the following example, doesn't appear in JavaScript.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[NoInterfaceObject]</strong> + <strong>interface</strong> Body {…}</span></pre> + +<p>For documentation purposes, we create a mixin page, with the same structure as an interface page. As they are not true interfaces, the word <em>interface</em> is not used — <em>mixin</em> is used instead.</p> + +<p>Mixin methods and properties are listed in the same way as regular methods and properties:</p> + +<ul> + <li>They have their own pages, prefixed with the mixin name. E.g {{domxref('Body.bodyUsed')}} or {{domxref('Body.blob()')}}.</li> + <li>They are listed on the interface page when the interface <em>implements</em> the mixin. Unlike regular properties and methods, they are prefixed with the mixin name and not the interface name. You can see <code>Body</code> properties and methods listed on both {{domxref('Request')}} and {{domxref('Response')}} interfaces, as they both implement the <code>Body</code> mixin.</li> +</ul> + +<p>Mixins implemented on an interface are defined using the <code>implements</code> keyword.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">Request <strong>implements</strong> Body; +Response <strong>implements</strong> Body;</span></pre> + +<div class="note"> +<p><span><strong>Note:</strong> Mixin names do not appear in a Web developer console. We shouldn't show them, but we currently do this as it saves us from duplicating content, which would lead to a maintenance issue. We do this if the mixin is only used in one interface (such cases are bugs in the relevant specs — they shouldn't be defined as mixins, but as partial interfaces.)</span></p> +</div> + +<h3 id="Availability_in_workers"><span>Availability in workers</span></h3> + +<p>Availability in Web workers (of any type) and on the Window scope is defined using an annotation: <code>[Exposed=(Window,Worker)]</code>. The annotation applies to the partial interface it is listed with. If no annotation is available, the default value is <code>Window</code>.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Exposed=(Window,Worker)]</strong> +interface Performance { + [DependsOn=DeviceState, Affects=Nothing]<a class="l d1" href="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/Performance.webidl#19"> +</a> DOMHighResTimeStamp now(); +};</span> + +<strong>[Exposed=Window]</strong> +partial interface Performance { + [Constant] + readonly attribute PerformanceTiming timing; + [Constant] + readonly attribute PerformanceNavigation navigation; + + jsonifier; +};</pre> + +<p>In this case <code>Performance.now()</code> is available on the <code>Window</code> scope and to any worker, while <code>Performance.timing</code>, <code>Performance.navigation</code> and <code>Performance.toJSON()</code> are not available to Web workers.</p> + +<p>The most common values for the <code>[Exposed]</code> are:</p> + +<dl> + <dt><code>Window</code></dt> + <dd>The partial interface is available to the {{domxref('Window')}} global scope.</dd> + <dt><code>Worker</code></dt> + <dd>The partial interface is available to any kind of worker, that is if the global scope is a descendant of {{domxref('WorkerGlobalScope')}} — {{domxref('DedicatedWorkerGlobalScope')}}, {{domxref('SharedWorkerGlobalScope')}}, or {{domxref('ServiceWorkerGlobalScope')}} (It also is available to <code>ChromeWorker</code>, but we don't document this as they are not visible on the Web and are internal to Firefox.)</dd> + <dt><code>DedicatedWorker</code></dt> + <dd>The partial interface is available to the {{domxref('DedicatedWorkerGlobalScope')}} only.<code> </code></dd> + <dt><code>SharedWorker</code></dt> + <dd>The partial interface is available to the {{domxref('SharedWorkerGlobalScope')}} only.</dd> + <dt><code>ServiceWorker</code></dt> + <dd>The partial interface is available to the {{domxref('ServiceWorkerGlobalScope')}} only.</dd> +</dl> + +<p>Another value is possible, like <code>System</code>, but this has a <a href="/en-US/docs/Mozilla/WebIDL_bindings#Exposed">special meaning</a> and doesn't need to be documented.</p> + +<p>Note that these possible values are themselves defined in WebIDL files. Interfaces may have a <code>[Global=xyz]</code> annotation. It means that when an object of this type is used as a global scope, any interface, property or method, with <code>xyz</code> as a value of <code>[Exposed]</code> is available.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[Global=(Worker,DedicatedWorker), Exposed=DedicatedWorker] +interface DedicatedWorkerGlobalScope : WorkerGlobalScope {…}</span></pre> + +<p>Here, it is defined that when the global scope is of type <code>DedicatedWorkerGlobalScope</code>, that is if we are in a dedicated worker, any interface, property or method exposed – using the <code>[Exposed]</code> annotation – to <code>Worker</code> or <code>DedicatedWorker</code> is available.</p> + +<p>Even the primary global is defined in WebIDL. The primary global is the value of an <code>[Exposed]</code> annotation when not present. This is defined using the <code>[PrimaryGlobal]</code> annotation and is present on {{domxref('Window')}}:</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[PrimaryGlobal, NeedResolve] +/*sealed*/ interface Window : EventTarget {…}</span></pre> + +<h3 id="Preferences">Preferences</h3> + +<div class="note"> +<p><strong>Note:</strong> this information is specific to Gecko and should only be used in the Browser compatibility section.</p> +</div> + +<p>In Gecko, the availability of a partial interface, including its constructor, properties and methods may be controlled by a preference (usually called a "pref"). This is marked in the WebIDL too.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Pref="media.webspeech.synth.enabled"]</strong> +interface SpeechSynthesis { + readonly attribute boolean pending; + readonly attribute boolean speaking; + readonly attribute boolean paused; +};</span></pre> + +<p><span>Here <code>media.webspeech.synth.enabled</code> controls the <code>SpeechSynthesis</code> interface and its properties (the full listing has more than 3.)</span></p> + +<div class="note"> +<p><span><strong>Note:</strong> the default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)</span></p> +</div> + +<h2 id="Properties">Properties</h2> + +<p>You can recognize the definition of a property by the presence of the <code>attribute</code> keyword.</p> + +<h3 id="Name_of_the_property">Name of the property</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">readonly attribute MediaError? <strong>error</strong>;</span></pre> + +<p>In the above example the name of the property is <code>error</code>; in the docs we will refer to it as <code>HTMLMediaElement.error</code> as it belongs to the <code>HTMLMediaElement</code> interface. Linking to the page is either done <strong>with</strong> the interface prefix using \{{domxref('HTMLMediaElement.error')}} or <strong>without</strong> the prefix using \{{domxref('HTMLMediaElement.error', 'error')}} when the context is obvious and unambiguous.</p> + +<h3 id="Type_of_the_property">Type of the property</h3> + +<pre class="syntaxbox"><span id="the-code">readonly attribute <strong>MediaError?</strong> error;</span></pre> + +<p><span>The property value is an object of type <code>MediaError</code>. The question mark (<code>'?'</code>) indicates that it can take a value of <code>null</code>, and the documentation must explain <em>when</em> this may occur. If no question mark is present, the <code>error</code> property can't be <code>null</code>.</span></p> + +<h3 id="Writing_permissions_on_the_property"><span>Writing permissions on the property</span></h3> + +<pre class="syntaxbox"><span id="the-code"><strong>readonly</strong> attribute MediaError? error;</span></pre> + +<p><span>If the keyword <code>readonly</code> is present, the property can't be modified. It must be marked as read-only:</span></p> + +<ul> + <li><span>In the interface, by adding the \{{ReadOnlyInline}} macro next to its definition term.</span></li> + <li><span>In the first sentence of its own page, by starting the description with: <em>The read-only <code><strong>HTMLMediaElement.error</strong></code> property…</em></span></li> + <li><span>By adding the <code>Read-only</code> tag to its own page.</span></li> + <li><span>By starting its description in the interface page with <em>Returns…</em></span></li> +</ul> + +<div class="note"> +<p><span><em><strong>Note:</strong> Only read-only properties can be described as 'returning' a value. Non read-only properties can also be used to set a value.</em></span></p> +</div> + +<ul> +</ul> + +<h3 id="Throwing_exceptions">Throwing exceptions</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[SetterThrows]</strong> + attribute DOMString src;</span></pre> + +<p><span>In some cases, like when some values are illegal, setting a new value can lead to an exception being raised. This is marked using the <code>[SetterThrows]</code> annotation. When this happens, the Syntax section of the property page <em>must</em> have an Exceptions subsection. The list of exceptions and the conditions to have them thrown are listed, as textual information, in the specification of that API.</span></p> + +<p><span>Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. <a href="http://heycam.github.io/webidl/#es-enumeration">Trying to set an illegal enumerated value</a> (mapped to a JavaScript {{jsxref('String')}}) raises a {{exception('TypeError')}} exception. This must be documented, but is only implicitly marked in the WebIDL document.</span></p> + +<p><span>It is uncommon to have getters throwing exceptions, though it happens in a few cases. In this case the <code>[GetterThrows]</code> annotation is used. Here also, the Syntax section of the property page <em>must</em> have an Exceptions subsection.</span></p> + +<pre class="syntaxbox"><code id="line-16">partial interface Blob {</code><code id="line-17"> +</code><code id="line-18"> <strong>[GetterThrows]</strong> +</code><code id="line-19"> readonly attribute <span class="k">unsigned</span> <span class="k">long</span> <span class="k">long</span> size; +};</code> +</pre> + +<h3 id="Not_throwing_exceptions">Not throwing exceptions</h3> + +<p>When the semantics of Webidl is not followed, an exception is often thrown, even without <code>[SetterThrows]</code> or <code>[GetterThrows]</code> set. For example, in strict mode, if we try to set a read-only property to a new value, that is to call its implicit setter, a read-only property will throw in strict mode.</p> + +<p>Mostly for compatibility purpose, this behavior is sometimes annoying. To prevent this by creating a no-op setter (that is by silently ignoring any attempt to set the property to a new value), the <code>[LenientSetter]</code> annotation can be used.</p> + +<pre class="syntaxbox"><code id="line-223">partial interface Document {</code><code id="line-225"><span class="c"> +</span></code><code id="line-226"><strong> [LenientSetter]</strong> +</code><code id="line-227"> readonly attribute boolean fullscreen;</code><code id="line-229"> +</code><code id="line-230"><strong> [LenientSetter]</strong> +</code><code id="line-231"> readonly attribute boolean fullscreenEnabled; +};</code> +</pre> + +<p>In these cases, an extra sentence is added to the description of the property. E.g</p> + +<p><em>Although this property is read-only, it will not throw if it is modified (even in strict mode); the setter is a no-operation and it will be ignored.</em></p> + +<h3 id="New_objects_or_references"><span>New objects or references</span></h3> + +<p><span>The return value of a property can be either a copy of an internal object, a newly created synthetic object, or a reference to an internal object.</span></p> + +<p><span>Basic objects with types like {{jsxref("String")}} (being an IDL <code>DOMString</code>, or other), {{jsxref("Number")}} (being an IDL <code>byte</code>, <code>octet</code>, <code>unsigned int</code>, or other), and {{jsxref("Boolean")}} are always copied and nothing special has to be noted about them (it is natural behavior expected by a JavaScript developer.)</span></p> + +<p><span>For interface objects, the default is to return a <em>reference</em> to the internal object. This has to be mentioned both in the short description in the interface page, and in the description in the specific sub-pages.</span></p> + +<div class="note"> +<p><span><strong>Note:</strong> The keyword <code>readonly</code> used with a property returning an object applies to the <u>reference</u> (the internal object cannot be changed.) The properties of the returned object can be changed, even if they are marked as read-only in the relevant interface.</span></p> +</div> + +<p>Sometimes an API must return a <em>new</em> object, or a <em>copy</em> of an internal one. This case is indicated in the WebIDL using the <code>[NewObject]</code> annotation.</p> + +<pre class="syntaxbox" lang="en"><strong>[NewObject]</strong> + readonly attribute TimeRanges buffered;</pre> + +<p>In this case, each call to <code>buffered</code> returns a different object: changing it will not change the internal value, and a change in the internal value will not affect each object instance. In the documentation, we will mark it by using the adjective <em>new</em> next to object:</p> + +<p><em>The <strong><code>HTMLMediaElement.buffered</code></strong> read-only property returns a new \{{domxref("TimeRanges")}} object that… </em></p> + +<p>and</p> + +<dl> + <dt><em>\{{domxref("HTMLMediaElement.buffered")}}\{{readonlyinline}}</em></dt> + <dd><em>Returns a new \{{domxref("TimeRanges")}} object that …</em></dd> +</dl> + +<p>In the case of a reference to a collection object (like <code>HTMLCollection</code>, <code>HTMLFormElementsCollection</code>, or <code>HTMLOptionsCollection</code>, always without <code>[NewObject]</code>), we make it explicit that changes to the underlying object will be available via the returned reference. To mark this, we qualify the collection as a <strong>live </strong><code>HTMLCollection</code><strong> </strong>(or <code>HTMLFormElementsCollections</code>, or <code>HTMLOptionsCollection</code>), both in the interface description and in the subpage.</p> + +<p>E.g.</p> + +<dl> + <dt>\{{domxref("HTMLFormElement.elements")}}\{{readonlyinline}}</dt> + <dd>Returns a live \{{domxref("HTMLFormControlsCollection")}} containing…</dd> +</dl> + +<h3 id="Availability_in_workers_2"><span>Availability in workers</span></h3> + +<p>Individual property availability in workers is also found in the WebIDL. For a property, the default is the same availability as the <code>interface</code> (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the <code>partial interface</code> it is defined in.</p> + +<p>For documentation, the subpage must contain a sentence indicating if it is available or not in Web workers, right before the "Syntax" section.</p> + +<h3 id="Preferences_2">Preferences</h3> + +<div class="note"> +<p>This information is specific to Gecko and should only be used in the Browser compatibility section.</p> +</div> + +<p>In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Pref="media.webvtt.enabled"]</strong> + readonly attribute TextTrackList? textTracks;</span></pre> + +<p><span>Here <code>media.webvtt.enabled</code> controls the <code>textTracks</code> property. </span></p> + +<div class="note"> +<p><span>The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another).</span></p> +</div> + +<h2 id="Methods">Methods</h2> + +<p>You can recognize the definition of a method by the presence of parentheses after the name.</p> + +<h3 id="Name_of_the_method">Name of the method</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">DOMString <strong>canPlayType</strong>(DOMString type);</span></pre> + +<p>The name of the method is <code>canPlayType</code>, and we will refer to it as <code>HTMLMediaElement.canPlayType()</code> (with the parentheses that indicate that it is a method) in the docs, as it belongs to the <code>HTMLMediaElement</code> interface. Linking to the page is either done <strong>with</strong> the interface prefix using \{{domxref('HTMLMediaElement.canPlayType()')}}, or <strong>without</strong> the prefix using \{{domxref('HTMLMediaElement.canPlayType', 'canPlayType()')}} when the context is obvious and unambiguous. The parentheses should always be included.</p> + +<h3 id="Parameters">Parameters</h3> + +<pre class="syntaxbox"><span id="the-code">TextTrack addTextTrack(TextTrackKind <strong>kind</strong>, + optional DOMString <strong>label</strong> = "", + optional DOMString <strong>language</strong> = "");</span></pre> + +<p>The parameters of a method are listed in the Syntax section of the method sub-page. They are listed in the WebIDL in order, between the parenthesis, as a comma-separated list. Each parameter has a name (indicated above) and a type (e.g. a <code>'?'</code> means that the <code>null</code> value is valid.) If marked <code>optional</code>, the parameter is optional to include in a method call and must have the \{{OptionalInline}} flag included when it is listed in the Syntax section. The parameter's default value is listed after the equality sign (<code>'='</code>).</p> + +<h3 id="Type_of_the_return_value">Type of the return value</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">DOMString <strong>canPlayType</strong>(DOMString type);</span></pre> + +<p><span>The return value type is indicated first inside the parentheses — in the above case the value is an object of type <code>DOMString</code>. if followed by a question mark (<code>'?'</code>), a value of <code>null</code> can be returned too, and the documentation must explain <em>when</em> this may happen. If no question mark is present, like here, the return value can't be <code>null</code>.</span></p> + +<p><span>The keyword <code>void</code> means that there is no return value. It is not a return value type. If the WebIDL entry reads <code>void</code>, the <em>Return value</em> section in the docs should contain only a simple <em>None</em>.</span></p> + +<h3 id="Throwing_exceptions_2">Throwing exceptions</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Throws]</strong> + void fastSeek(double time);</span></pre> + +<p><span>Some methods can throw exceptions. This is marked using the <code>[Throws]</code> annotation. When this happens, the Syntax section of the method page <em>must</em> have an Exceptions subsection. The list of exceptions and the conditions to have them thrown are listed, as textual information, in the specification of that API.</span></p> + +<p><span>Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. <a href="http://heycam.github.io/webidl/#es-enumeration">Trying to set an illegal enumerated value</a> (mapped to a JavaScript {{jsxref('String')}}) as a parameter will raise a {{exception('TypeError')}} exception. This must be documented, but it is only implicitly marked in the WebIDL document.</span></p> + +<p><span>Have a look at one of these <a href="https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#Exceptions"><em>Exceptions</em> sections</a>.</span></p> + +<h3 id="Availability_in_workers_3"><span>Availability in workers</span></h3> + +<p>Individual method availability in workers is also found in the WebIDL. For a method, the default is the same availability as the <code>interface</code> (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the <code>partial interface</code> it is defined it.</p> + +<p>For the documentation, the sub-page must contain a sentence indicating if it is available in Web workers, right before the Syntax section.</p> + +<h3 id="Preferences_3">Preferences</h3> + +<div class="note"> +<p><strong>Note:</strong> this information is specific to Gecko and should only be used in the Browser compatibility section.</p> +</div> + +<p>In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Pref="media.webvtt.enabled"]</strong> + TextTrack addTextTrack(TextTrackKind kind, + optional DOMString label = "", + optional DOMString language = "");</span></pre> + +<p><span>Here <code>media.webvtt.enabled</code> controls the <code>addTextTrack()</code> method. </span></p> + +<div class="note"> +<p><span><strong>Note:</strong> The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)</span></p> +</div> + +<h3 id="sect1"> </h3> + +<h2 id="Special_methods">Special methods</h2> + +<p>Some methods are not listed as regular methods in WebIDL but instead as special keywords, which translate to specific standard JavaScript methods.</p> + +<h3 id="toString()_and_toJSON()">toString() and toJSON()</h3> + +<p>A stringifier is mapped to <code>toString()</code> and defined as:</p> + +<pre class="syntaxbox"><strong><span id="the-code">stringifier;</span></strong></pre> + +<p>The <code>toString()</code> method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Range.toString()")}})</p> + +<p>A jsonifier is mapped to <code>toJSON()</code> and defined as:</p> + +<pre class="syntaxbox" lang="en"><strong><span id="the-code">jsonifier; </span></strong><span>// Gecko version</span><strong><span> +serializer;</span></strong><span> // Standard version</span> +</pre> + +<p>The <code>toJSON()</code> method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Performance.toJSON()")}})</p> + +<div class="note"> +<p><strong>Note:</strong> the WebIDL specification uses <code>serializer</code> instead of <code>jsonifier</code>. This is not used in Gecko — only the non-standard likely early proposal <code>jsonifier</code> is found in mozilla-central.</p> +</div> + +<p> </p> + +<h3 id="Iterator-like_methods">Iterator-like methods</h3> + +<p>An interface may be defined as <em>iterable</em>, meaning that it will have the following methods: <code>entries()</code>, <code>keys()</code>, <code>values()</code> and <code>forEach()</code>. They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface.</p> + +<p>There are two kinds of iteration possible: the <em>value iterator</em> and the <em>pair iterator.</em></p> + +<h4 id="Value_iterator">Value iterator</h4> + +<pre class="syntaxbox">iterable<<em>valueType</em>></pre> + +<p>The iterator will iterate over values of type <em>valueType</em>. The generated methods will be:</p> + +<ul> + <li><code>entries()</code>, which returns an {{jsxref('iterator')}} on the indexes (that are <code>unsigned long</code>).</li> + <li><code>values()</code>, which returns an {{jsxref('iterator')}} on the values.</li> + <li><code>keys()</code>, which returns an {{jsxref('iterator')}} on the keys, that are its indexes (that are <code>unsigned long</code>). In the case of value iterators, <code>keys()</code> and <code>entries()</code> are identical.</li> + <li><code>forEach()</code>, which returns an {{jsxref('iterator')}} on the keys that calls a given callback function one for each entry in the list.</li> +</ul> + +<p>Such an iterator allows to use the syntax <code>for (var p in object)</code> as a shorthand of <code>for (var p in object.entries())</code>. We add a sentence about it in the interface description.</p> + +<div class="note"> +<p><strong>Note:</strong> the value pairs to iterate over can be defined in two different ways:</p> + +<ol> + <li>Outside the webidl file, in the prose accompanying it. Such a prose is in the spec and usually starts with: <em>"The <a class="external" href="https://heycam.github.io/webidl/#dfn-values-to-iterate-over">values to iterate over</a>…"</em>.</li> + <li>In the webidl file, implicitly, if the interface supports indexed properties, that is when the interface has a <code>getter</code> methods with a parameter of type <code>unsigned long</code>.</li> +</ol> +</div> + +<h4 id="Pair_iterator">Pair iterator</h4> + +<pre class="syntaxbox">iterable<<em>keyType, valueType</em>></pre> + +<p>The iterator will iterate over values of type <em>valueType</em>, with keys of type <em>keyType</em>. The generated methods will be:</p> + +<ul> + <li><code>entries()</code> that returns an {{jsxref('iterator')}} on the indexes (of type <em>keyType</em>). E.g. {{domxref('FormData.entries()')}}</li> + <li><code>values()</code> that returns an {{jsxref('iterator')}} on the values. E.g. {{domxref('FormData.values()')}}</li> + <li><code>keys()</code> that returns an {{jsxref('iterator')}} on the keys. E.g. {{domxref('FormData.keys()')}}</li> + <li>Once {{bug(1216751)}} lands, <code>forEach()</code>.</li> +</ul> + +<p>Such an iterator allows to use the syntax <code>for (var p in object)</code> as a shorthand of <code>for (var p in object.entries())</code>. We add a sentence about it in the interface description. E.g. {{domxref('FormData')}}.</p> + +<div class="note"> +<p><strong>Note:</strong> the value pairs to iterate over are <em>not</em> defined in the webidl file, but in the prose accompanying it. Such a prose is in the spec and usually starts with: <em>"The <a class="external" href="https://heycam.github.io/webidl/#dfn-value-pairs-to-iterate-over">value pairs to iterate over</a>…"</em><br> + E.g, for {{domxref('FormData')}} you find in the spec: <em>"The <a class="external" href="https://heycam.github.io/webidl/#dfn-value-pairs-to-iterate-over">value pairs to iterate over</a> are the <a href="https://xhr.spec.whatwg.org/#concept-formdata-entry" title="concept-FormData-entry">entries</a> with the key being the <a href="https://xhr.spec.whatwg.org/#concept-formdata-entry-name" title="concept-FormData-entry-name">name</a> and the value the <a href="https://xhr.spec.whatwg.org/#concept-formdata-entry-value" title="concept-FormData-entry-value">value</a>. "</em></p> +</div> + +<h3 id="Set-like_methods">Set-like methods</h3> + +<p>An interface may be defined as <em>set-like</em>, meaning that it represents an <em>ordered set of values</em> will have the following methods: <code>entries()</code>, <code>keys()</code>, <code>values()</code>, <code>forEach(),</code> and <code>has()</code> (it also has the <code>size</code> property). They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface. The set-like can be prefixed <code>readonly</code> or not. If not read-only, the methods to modify the set are also implemented: <code>add()</code>, <code>clear()</code>, and <code>delete()</code>.</p> + +<pre class="syntaxbox">setlike<<em>valueType</em>></pre> + +<p>The generated properties will be:</p> + +<ul> + <li><code>entries()</code> that returns an {{jsxref('iterator')}} on the indexes. E.g. {{domxref('FontFaceSet.entries()')}}.</li> + <li><code>values()</code> that returns an {{jsxref('iterator')}} on the values. E.g. {{domxref('FontFaceSet.values()')}}.</li> + <li><code>keys()</code> that returns an {{jsxref('iterator')}} on the keys. E.g. {{domxref('FontFaceSet.keys()')}},</li> + <li><code>forEach()</code>.</li> +</ul> + +<p>In the case, the set-like declaration is not prefixed by read-only, the following methods are also generated:</p> + +<ul> + <li><code>add()</code> that adds an entry. E.g. {{domxref('FontFaceSet.add()')}}.</li> + <li><code>clear()</code> that empty the set-like. E.g. {{domxref('FontFaceSet.clear()')}}.</li> + <li><code>delete()</code> that remove an entry. E.g. {{domxref('FontFaceSet.delete()')}}.</li> +</ul> + +<p>Such an set interface also allows to use the syntax <code>for (var p in object)</code> as a shorthand of <code>for (var p in object.entries())</code>. We add a sentence about it in the interface description. E.g. {{domxref('FontFaceSet')}}.</p> + +<p> </p> + +<h2 id="Constructors">Constructors</h2> + +<p>Constructors are a little bit hidden in WebIDL: they are listed as annotations of the main interface.</p> + +<h3 id="Unnamed_constructors">Unnamed constructors</h3> + +<p>This is the most common case for constructors. The constructor of a given interface A, can be used as <code>a = new A(<em>parameters</em>);</code></p> + +<pre class="syntaxbox" lang="en"><span id="the-code"> [<strong>Constructor</strong>, Func="MessageChannel::Enabled", + Exposed=(Window,Worker)] + interface MessageChannel {…};</span></pre> + +<p><span>A constructor with the same interface is defined using the <code>Constructor</code> annotation on the interface. There can be parenthesis and a list of parameters or not (like in the above example.) We document all the unnamed constructors on a sub-page — for example the above is given the slug <em>Web/API/MessageChannel/MessageChannel</em> and the title <code>MessageChannel()</code>.</span></p> + +<p><span>Another example of an unnamed constructor, with parameters:</span></p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[<strong>Constructor</strong>(DOMString type, optional MessageEventInit eventInitDict), + Exposed=(Window,Worker,System)] + interface MessageEvent : Event {…};</span></pre> + +<p>There can also be several unnamed constructors, differing by their parameter lists. All syntax is documented in one single sub-page.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[<strong>Constructor</strong>(DOMString url, URL base), + <strong>Constructor</strong>(DOMString url, optional DOMString base), + Exposed=(Window,Worker)] + interface URL {};</span></pre> + +<h3 id="Named_constructors">Named constructors</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">[<strong>NamedConstructor</strong>=Image(optional unsigned long width, optional unsigned long height)] + interface HTMLImageElement : HTMLElement {…</span></pre> + +<p><span>A named constructor is a constructor that has a different name than that of its interface. For example<code> new Image(…)</code> creates a new <code>HTMLImageElement</code> object. They are defined in the WebIDL using the <code>NamedConstructor</code> annotation on the interface, followed by the name of the constructor after the equality sign (<code>'='</code>) and the parameter inside the parenthesis, in the same format as you'll see for methods.</span></p> + +<p><span>There can be several named constructors for a specific interface, but this is extremely rare; in such a case we include one sub-page per name.</span></p> + +<h3 id="Availability_in_workers_4"><span>Availability in workers</span></h3> + +<p>Constructors have the same availability as the interface, or partial interface, they are defined on. The sub-page provides this information in the same way as for a method.</p> + +<h3 id="Preferences_4">Preferences</h3> + +<p>Constructors are controlled by the same preference as the interface, or partial interface, they are defined on. The sub-page provides this information in the same way as for a method.</p> diff --git a/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html b/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html new file mode 100644 index 0000000000..15c6f0b2ee --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html @@ -0,0 +1,117 @@ +--- +title: 如何写文章帮助人们了解 Web +slug: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +tags: + - MDN元数据 + - 学习社区 + - 指导 + - 贡献指南 +translation_of: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +--- +<div>{{MDNSidebar}}</div> + +<p>MDN 的<strong><a href="/zh-CN/docs/Learn">学习区</a></strong>是我们给新手开发者介绍 Web 概念的大本营。因为它的内容主要面对初学者，这是你分享知识，帮助新手逐渐了解 Web 的绝佳地点。确保新手开发者能够跟上这里的内容是很重要的，所以我们格外重视学习区。</p> + +<p><span class="seoSummary">这篇文章解释了如何给<a href="/zh-CN/docs/Learn">学习区</a>写文章。</span></p> + +<h2 id="如何写学习社区的文章">如何写学习社区的文章</h2> + +<p>要开始贡献你的知识，只需点击绿色大按钮，然后按照下面的五个步骤。如果你想找点子，请看一下我们的团队<a href="https://trello.com/b/LDggrYSV"> Trello </a>！</p> + +<div class="align-center"><a class="button ignore-external mega positive" href="/en-US/docs/new?parent=111819">写一篇新的学习文章</a> + +<div></div> +</div> + +<p>这篇文章可能不会在正确的地方出现，但至少是在MDN上。如果你需要找人谈谈把它搬到正确的地方，请<a href="/en-US/docs/Learn#Contact_us">联系我们</a>。</p> + +<h3 id="第一步：写两行">第一步：写两行</h3> + +<p>你文章的第一句话需要总结一下你将要涉及的主题，第二句话应该更详细地介绍你要放在文章中的内容（项目）。例如：</p> + +<div class="summary"> +<p> {{glossary("HTML")}} 文件包含的结构和内容, {{Glossary("CSS")}}以及其他主要的Web技术，使内容看起来像你想要的那样。在本文中，我们将介绍这项技术是如何工作的，以及如何编写你自己的基本示例。</p> +</div> + +<p>注意示例如何简要说明CSS是用于样式化页面的核心Web技术。 这足以使读者很好地了解本文所涵盖的内容。</p> + +<p>因为学习区域的文章主要是针对初学者的，所以每篇文章都应该涵盖一个简单的主题，以免给读者带来太多的新信息。如果你不能在一句话中总结这篇文章，那么你可能在一篇文章中做得太多了!</p> + +<h3 id="第二步：添加一个顶部框">第二步：添加一个顶部框</h3> + +<p>然后添加一个顶框，以帮助读者了解他们在学习过程中的位置。 这是“<a href="/en-US/docs/Learn/Understanding_URLs">了解URL及其结构</a> ”顶部框的示例。 您可以在编写自己的文章时将其用作模型。</p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">必要条件:</th> + <td>您首先必须清楚Internet的工作方式，Web服务器是什么，与Web链接背后的所有概念。</td> + </tr> + <tr> + <th scope="row">目标:</th> + <td>您将了解什么是URL以及它如何在Web上工作</td> + </tr> + </tbody> +</table> + +<dl> + <dt>必要条件</dt> + <dd>读者首先必须知道什么东西才能读懂你的一篇文章?在有可能的状况下，让每一个前提条件链接到另一篇涵盖概念的学习领域的一篇文章(除了您写的是是一篇完全不需要首先先验知识的无比基础的文章)。</dd> + <dt>目标</dt> + <dd>这一章节粗略说明了您的读者在阅读学习这篇文章的过程中会学到（并学会）什么。这与一行程序有点不同;一行代码总结了文章的主题，而目标部分专门列出了读者在阅读文章过程中所希望完成的全部内容。</dd> +</dl> + +<div class="note"> +<p>注意:要创建此表，您可以复制并粘贴上面的示例表，或者使用MDN的编辑器 <a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Tables">台式工具</a>。如果选择使用table工具，则需要在默认的standard-table类之外特别添加learn-box CSS类。为此，当您创建或编辑表的属性时，请转到“Advanced”面板并将样式表类字段设置为“standard-table learn-box”。</p> +</div> + +<h3 id="第三步写一个完整的描述">第三步:写一个完整的描述</h3> + +<p>接下来，写一个更长的描述，提供更全面的文章概述，突出最重要的概念。不要忘记解释为什么读者要花时间来学习这个主题并阅读你的文章！</p> + +<h3 id="第四步：更深一步">第四步：更深一步</h3> + +<div>当你完成了所有这些，你终于可以深入到主题。你可以根据自己的喜好来组织文章的这一部分(尽管您能够随时咨询我们的 <a href="/en-US/docs/MDN/Contribute/Style_guide">设计指南</a>)。这是你闪耀的机会!详细解释你要写的主题。提供指向完整参考文档的链接，详细解释该技术的工作原理，提供语法和用法细节，等等。由你决定 + +<div></div> +</div> + +<ul> + <li>专注于一个主题。如果你觉得你需要涵盖其他主题，这意味着要么你错过了一篇必备文章，要么你需要把你的文章分解成多个主题</li> + <li>使用简单的英语。尽可能避免使用技术术语，或者至少定义它们并在适用的情况下链接到它们的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary#How_to_use_the_.7B.7BGlossary.7D.7D_macro">术语表条目。</a></li> + <li>包括直接的例子，使理论概念更容易掌握。许多人以身作则学得最好。与写学术论文相比，我们希望初学者能容易地跟上文章的节奏</li> + <li>视觉辅助工具通常可以使内容更容易消化，并携带额外的信息，所以请随意使用图像、图表、视频和表格。如果您正在使用包含文本的图表，我们建议您使用{{Glossary("SVG")}}，这样我们的翻译团队就可以本地化文本。</li> +</ul> + +<p>看一看我们的函数的前几节<a href="/en-US/docs/Learn/JavaScript/Building_blocks/Functions">可重用代码块文章</a> ，有一些很好的描述部分。</p> + +<h3 id="第五步提供“主动学习”材料">第五步:提供“主动学习”材料</h3> + +<p>为了阐明本文并帮助读者更好地理解他们正在学习的内容，请确保提供练习、教程和需要完成的任务。通过让他们积极地、实际地使用和试验你文章中解释的概念，你可以帮助他们将信息“锁定”在大脑中。</p> + +<p>您可以选择在页面中直接包含这些示例作为 <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实时实例</a>,或者<a href="/en-US/docs/MDN/Contribute/Editor/Links">直接链接到它们。</a> （如果它们不能作为实时实例。） 如果你有兴趣帮助创造这些有价值的东西 ，请参阅<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web">《创建一个交互式的练习来帮助学习网络》</a></p> + +<p>如果您不能提供到现有活动学习材料的链接(您不知道或者没有时间创建它们)，那么您应该在文章中添加标记{{tag ("NeedsActiveLearning")}}。这样，其他贡献者就可以找到需要积极学习材料的文章，并可能帮助你找到它们。</p> + +<p dir="rtl">看看<a href="/en-US/docs/Learn/CSS/Introduction_to_CSS/Simple_selectors#Active_learning_Selecting_different_elements">《主动学习:选择不同的元素》</a>进行现场互动学习练习或者<a href="/en-US/docs/Learn/JavaScript/Building_blocks/Functions#Active_learning_Playing_with_scope">《主动学习: 玩转范围》</a>或者另一种不同风格的练习，要求它们在本地下载模板并按照提供的步骤更改</p> + +<p dir="rtl"></p> + +<p dir="rtl"> </p> + +<h3 id="第六步：查看文章，并放入学习区域导航菜单">第六步：查看文章，并放入学习区域导航菜单</h3> + +<p>在你写完你的文章后，让我们知道，这样我们可以看一看，做一个回顾，并提出改进建议 。再次看看我们的 <a href="/en-US/docs/Learn#Contact_us">联系方式</a> 板块以寻找最好的联系方式。</p> + +<p>完成文章的另一部分是把它放在学习区主导航菜单中。这个菜单是 <a href="/en-US/docs/Template:LearnSidebar">LearnSidebar 宏</a>生成的。 你需要特殊的权限来编辑，所以，再一次，让我们团队中的一个人把它添加进去。</p> + +<p>您至少应该将其添加到您的页面中，这是通过在页面顶部的段落中添加宏调用\{{LearnSidebar}}来完成的。</p> + +<ul> +</ul> + +<h2 id="推荐文章">推荐文章</h2> + +<p>您想做出贡献，但是您不知道该写什么?</p> + +<p>学习社区维护了一个要写文章的<a href="https://trello.com/b/LDggrYSV">Trello看板</a>。随意挑选一个，然后开始去写吧！</p> diff --git a/files/zh-cn/mdn/contribute/howto/write_for_seo/index.html b/files/zh-cn/mdn/contribute/howto/write_for_seo/index.html new file mode 100644 index 0000000000..c8bab8d102 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_for_seo/index.html @@ -0,0 +1,77 @@ +--- +title: 如何带着SEO的思维将MDN的Web文档写的更符合搜索引擎展现 +slug: MDN/Contribute/Howto/Write_for_SEO +tags: + - MDN内容贡献 + - MDN搜索优化 + - MDN搜索引擎优化 + - MDN文档 + - MDN的SEO优化 + - SEO + - 搜索引擎优化 +translation_of: MDN/Contribute/Howto/Write_for_SEO +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/zh-CN/docs/MDN")}}{{draft("为了更好的将MDN的文档符合SEO要求，我们在此提供了一些提升MDN搜索引擎优化的技术建议。本文是由MDN的志愿者们整理翻译完成的。 ")}}</div> + +<p><span class="seoSummary">本指南涵盖了我们对内容的基础要求、推荐和实践参考，以确保搜索引擎可以更好的对我们的内容进行分类和索引，同时确保用户可以轻松地获取到所需的内容。</span></p> + +<h2 id="简介">简介</h2> + +<p>MDN写作的首要目标是向开发者们阐明和指导开放的Web技术，以便他们能够快速找到他们想要的东西，或者为了优化自己的代码而寻找需要的细节，因此我们在MDN提供的内容可以被更容易的搜索到就非常重要了。</p> + +<p>由于绝大部分读者是通过搜索引擎搜索找到MDN的内容的，那么作为作者，我们就要始终记得内容对搜索引擎的友好程度这件事。为了对搜索引擎友好，我们撰写了SEO指引的内容以帮助MDN的作者和编辑们能够确保MDN上的每篇内容的设计、撰写和标记方式都符合SEO规范，以获得搜索引擎更好的收录索引和展现。</p> + +<h2 id="本文档的状态">本文档的状态</h2> + +<p>目前我们刚开始了改进MDN文档在搜索引擎优化({{Glossary("SEO")}}) 的长期项目的初期阶段。 我们最近完成了一系列小规模实验来测试能提升SEO的方法，并确定哪些内容能够作为SEO指南提供给我们的贡献者们。</p> + +<p>我们仍在编辑并更新本文，同时将其他贡献者提供的参考纳入到我们的发现中。</p> + +<h2 id="SEO_要点">SEO 要点</h2> + +<p>The following is a list of things you should check while writing and reviewing content to help ensure that the page and its neighbors will be indexed properly by search engines.</p> + +<ul> + <li>Make sure the page's contents are <a href="/en-US/docs/MDN/Contribute/Howto/Write_for_SEO#Ensure_pages_aren't_too_similar">different enough from other pages</a> that search engines don't assume they're about the same thing.</li> +</ul> + +<h2 id="避免过于相似的内容页面">避免过于相似的内容页面</h2> + +<p>Each article should be as unique as possible. Articles that look similar to one another textually will wind up being considered to be about roughly the same thing, even if they aren't. For example, if an interface has the properties <code>width</code> and <code>height</code>, it's easy for the text to be surprisingly similar, with just a few words swapped out, and using the same example. This makes it hard for search engines to know which is which, and they wind up sharing page rank, resulting in both being harder to find than they ought to be.</p> + +<p>Understandably, writers confronted with two related properties like <code>width</code> and <code>height</code> (or any other set of functionally related features) are tempted to write the article on <code>width</code>, then copy that article and paste it into the one on <code>height</code>, replacing a few words. Done!</p> + +<p>Unfortunately, the result is two pages that, as far as search engines are concerned, may as well be the same thing.</p> + +<p>It's important, then, to ensure that every page has its own content. Here are some suggestions to help you accomplish that:</p> + +<ul> + <li>Consider use cases where there might be more differences than one would think. For instance, in the case of <code>width</code> and <code>height</code>, perhaps consider ways horizontal space and vertical space are used differently, and provide a discussion about the appropriate concepts. Perhaps you mention the use of width in terms of making room for a sidebar, while using height to handle vertical scrolling or footers or similar. Including information about accessibility issues is a useful and important idea as well.</li> + <li>Use entirely different examples on each page. Examples in these situations are often even more similar than the body text, since the examples may use both (or all) of the similar methods or properties to begin with, thereby requiring no real changes when reused. So throw out the example and write a new one, or at least provide multiple examples, with at least some of them different.</li> + <li>Include descriptions of each example. Both an overview of what the example does as well as coverage of how it works, in an appropriate level of detail given the complexity of the topic and the target audience, should be included.</li> +</ul> + +<p>The easiest way to avoid being overly similar is of course to write each article from scratch if time allows.</p> + +<h2 id="避免页面内容过短">避免页面内容过短</h2> + +<p>如果文章过短，那么搜索引擎可能会难以甚至无法对其建立关键字索引。一般来说，文章的主体内容应该至少包含 250-300 个单词。但是也不要对内容确实很少的文章进行刻意的扩充，在可能的情况下尽量遵守该指导原则即可。</p> + +<ul> + <li>Keep an eye on the convenient word counter located in the top-right corner of the editor's toolbar on MDN. This is not an exact representation of the true word count, since the true word count is based on the rendered page, not the page as you see it in the editor. That means macros that add a lot of words will result in a higher word count, while macros that insert nothing but adjust formatting will result in a lower word count.</li> + <li>Obviously, if the article is a stub, or is missing material, add it. We try to avoid outright "stub" pages on MDN, although they do exist, but there are plenty of pages that are missing large portions of their content.</li> + <li>Generally review the page to ensure that it's structured properly for the <a href="/en-US/docs/MDN/Contribute/Structures/Page_types">type of page</a> it is. Be sure every section that it should have is present and has appropriate content.</li> + <li>Make sure every section is complete and up-to-date, with no information missing. Are all parameters listed and explained? Make sure any exceptions are covered (this is a particularly common place where content is missing).</li> + <li>Be sure everything is fully fleshed-out. It's easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Known restrictions that the reader might need to know about?</li> + <li>There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner through intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details and the handling of errors in examples; readers <em>will</em> copy and paste your example to use in their own projects, and your code <em>will</em> wind up used on production sites! See <a href="/en-US/docs/MDN/Contribute/Structures/Code_examples">Code examples</a> and our <a href="/en-US/docs/MDN/Contribute/Guidelines/Code_samples">Code sample guidelines</a> for more useful information.</li> + <li>If there are particularly common use cases for the feature being described, talk about them! Instead of assuming the reader will figure out that the method being documented can be used to solve a common development problem, actually add a section about that use case with an example and text explaining how the example works.</li> + <li>Include proper {{htmlattrxref("alt", "img")}} text on all images and diagrams; this text counts, as do captions on tables and other figures.</li> + <li>Do <em>not</em> descend into adding repetitive, unhelpful material or blobs of keywords, in an attempt to improve the page's size and search ranking. This does more harm than good, both to content readability and to our search results.</li> +</ul> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute">Contributing to MDN</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide">Writing style guide</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/如何添加或更新浏览器兼容性数据/index.html b/files/zh-cn/mdn/contribute/howto/如何添加或更新浏览器兼容性数据/index.html new file mode 100644 index 0000000000..8c0513d654 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/如何添加或更新浏览器兼容性数据/index.html @@ -0,0 +1,30 @@ +--- +title: 如何添加或更新浏览器兼容性数据 +slug: MDN/Contribute/Howto/如何添加或更新浏览器兼容性数据 +translation_of: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">如果你有浏览器在兼容Web特性方面的信息 —— 或者有意愿并有能力做一些这方面的研究和/或实验 —— 你可以帮助更新MDN的<a href="https://github.com/mdn/browser-compat-data/">浏览器兼容性数据库</a>（<abbr title="Browser Compatibility Database">BCD</abbr>）。</span></p> + +<ul> + <li>熟悉使用 Github</li> + <li>熟悉使用 JSON</li> + <li>了解有关、或有能力测试各种不同浏览器与网页标准及特性的兼容性</li> +</ul> + +<dl> + <dt>哪些地方需要做？</dt> + <dd> + <p>在MDN上你有这几种方法可以帮助改进浏览器兼容性方面的信息：</p> + + <ul> + <li>添加尚未收录在BCD仓库内的网页特性数据</li> + <li>依据浏览器新版本的变更内容、现有数据中的更正错误，或者某项技术的特性之最新变更等信息来更新现有数据</li> + <li>提交 pull requests 到 <a class="external external-icon" href="https://github.com/mdn/browser-compat-data/issues" rel="noopener">BCD issues filed on Github</a>.</li> + </ul> + </dd> + <dt>做这个任务你需要知道哪些知识？</dt> + <dt>做这个任务需要哪些步骤？</dt> + <dd>欲了解如何更新在GitHub上的组成BCD仓库的 <a class="glossaryLink" href="https://developer.mozilla.org/en-US/docs/Glossary/JSON" title="JSON: The JavaScript Object Notation (JSON) is a data-interchange format. Although not a strict subset, JSON closely resembles a subset of JavaScript syntax. Though many programming languages support JSON, JSON is especially useful for JavaScript-based apps, including websites and browser extensions.">JSON</a> 文件的详细信息，请参见<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">兼容性表格</a>页面。如要了解我们特别寻求帮助的问题列表，请到 <a class="external external-icon" href="https://github.com/mdn/browser-compat-data/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22" rel="noopener">Github issues with the "Help Wanted" tag</a>.</dd> + <dt> </dt> + <dt> </dt> +</dl> diff --git a/files/zh-cn/mdn/contribute/howto/学习_交互_在线_起步_开始/index.html b/files/zh-cn/mdn/contribute/howto/学习_交互_在线_起步_开始/index.html new file mode 100644 index 0000000000..91b8a8640d --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/学习_交互_在线_起步_开始/index.html @@ -0,0 +1,185 @@ +--- +title: 如何创建一个交互学习环境 +slug: MDN/Contribute/Howto/学习_交互_在线_起步_开始 +tags: + - MDN Meta + - 交互 + - 如何使用 + - 学习 + - 教程 +translation_of: MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web +--- +<div>{{MDNSidebar}}</div><p>动态的内容对于学习 Web 来说是重要的。 她能让学习的人更加积极主动。 这可以是练习，实例，任务，评价等等。总之，任何有助于学习理解的东西都行。</p> + +<p>这儿还没有能够直接创建动态的实例内容。但是一些第三方工具可以帮助你创建（如： <a href="https://jsfiddle.net/" rel="external">JSFiddle</a>，<a href="https://codepen.io/">CodePen</a>，<a href="http://dabblet.com/">Dabblet</a>，等），你可以将其链接放在 MDN 文章中。另外，你可以使用 WebMaker 项目的 <a href="https://thimble.mozilla.org/" rel="external">Thimble</a> 来创造更加高级的内容。</p> + +<p>目前，MDN 虽然没有能够轻易创建动态实例内容的工具。不过，如果你是工程师，可以使用当前 MDN 提供的功能创建自定义的主动学习内容，下面内容将告诉你如何操作。</p> + +<h2 id="MDN_live_samples">MDN live samples</h2> + +<p>MDN 有一个非常炫酷的功能：live samples。她是一种可以将 MDN 页面内任何 HTML, CSS, Javascript 代码等效执行的机制。在使用她以前，你最好通读一下 <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Using the live sample system</a>，这是我们关于她的完整文档。虽然她很容易使用，不过通过阅读文档，你会学到一些奇淫巧技。</p> + +<p>有意思的是，将任何类型的工具或实例嵌入到 MDN 页面中都可以通过调教她轻松做到。</p> + +<h3 id="隐藏代码">隐藏代码</h3> + +<p>通过实例创建主动学习内容的第一种方法是编辑要添加内容的页面。使用 Live Sample 功能创建内容，只构建你需要的功能，不要在乎代码的复杂度。当内容准备好之后，只需切换到编辑器视图，并用 class 为 <code>hidden </code>的 {{HTMLElement('div')}} 来包围你的代码。这样代码就会隐藏，不过实例依然可以访问和显示。</p> + +<p>看看这个简单的代码：</p> + +<div class="moreinfo"> +<p>点击这个方块提供随机色，或者直接输入色值</p> + +<div class="hidden"> +<h4 id="hidden_code_example">hidden code example</h4> + +<h5 id="HTML">HTML</h5> + +<pre class="brush: html"><div class="square"> + #<input class="color"> +</div></pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css">body { + padding: 10px; + margin : 0; +} + +.square { + width : 80px; + height : 80px; + padding: 10px; + background-color: black; + color: white; + text-align: center; +} + +.color { + width: 60px; + text-transform: uppercase; +} +</pre> + +<h5 id="JS">JS</h5> + +<pre class="brush: js">function setColor(color) { + document.querySelector('.square').style.backgroundColor = '#' + color; + document.querySelector('.color').value = color; +} + +function getRandomColor() { + var color = Math.floor(Math.random() * 16777215); + return color.toString(16); +} + +function getInputColor() { + var value = document.querySelector('.color').value; + var color = Number('0x' + color); + if (color === +color) { + return color.toString(16); + } + return value; +} + +document.addEventListener('click', function () { + setColor(getRandomColor()); +}); + +document.addEventListener('keyup', function () { + setColor(getInputColor()); +}); +</pre> +</div> +{{EmbedLiveSample('hidden_code_example', 120, 120)}}</div> + +<p>如果你使用 MDN 编辑器查看该页面代码，你会看到如下 HTML 代码：</p> + +<pre class="brush: html"><div class="moreinfo"> +<p>Click on the following square to randomly change its color or just type an hexadecimal code color</p> + +<div class="hidden"> +<h4 id="hidden_code_example">hidden code example</h4> + +<h5 id="HTML">HTML</h5> + +<pre class="brush: html"> +&lt;div class="square"&gt; + #&lt;input class="color"&gt; +&lt;/div&gt;</pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css"> +body { + padding: 10px; + margin : 0; +} + +.square { + width : 80px; + height : 80px; + padding: 10px; + background-color: black; + color: white; + text-align: center; +} + +.color { + width: 60px; + text-transform: uppercase; +} +</pre> + +<h5 id="JS">JS</h5> + +<pre class="brush: js"> +function setColor(color) { + document.querySelector('.square').style.backgroundColor = '#' + color; + document.querySelector('.color').value = color; +} + +function getRandomColor() { + var color = Math.floor(Math.random() * 16777215); + return color.toString(16); +} + +function getInputColor() { + var value = document.querySelector('.color').value; + var color = Number('0x' + color); + if (color === +color) { + return color.toString(16); + } + return value; +} + +document.addEventListener('click', function () { + setColor(getRandomColor()); +}); + +document.addEventListener('keyup', function () { + setColor(getInputColor()); +}); +</pre> +</div> + +\{{EmbedLiveSample('hidden_code_example', 120, 120)}} +</div></pre> + +<p>你可以在 <a href="/en-US/docs/Web/API/Canvas_API#JavaScript">the Canvas API page</a> 查看更多高级例子。</p> + +<h3 id="外部代码">外部代码</h3> + +<p>前面的例子在你想嵌入主动学习内容时是可行的。不过，如果你想要处理更加复杂的代码，这个 <code>hidden</code> 的 {{HTMLElement('div')}} 就比较麻烦。</p> + +<p>另外种方案是将内容写入 MDN 页面，然后嵌入另一个页面中。为此，我们可以使用 {{TemplateLink("EmbedDistLiveSample")}} 替代{{TemplateLink("EmbedLiveSample")}} 。</p> + +<p>我们学习配置这个模拟远程代码嵌入的实例：</p> + +<div class="moreinfo"> +<p>点击这个方块提供随机色，或者直接输入色值</p> +{{EmbedLiveSample('The_example', 120, 120, '', 'MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example')}}</div> + +<p>这下如果你继续使用 <a href="/en-US/docs/MDN/Contribute/Editor/Source_mode">MDN 编辑器</a>查看页面源码，将看不到隐藏元素。如果你需要看，则需要前往这个页面<a href="/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example">地址</a>。</p> + +<p>你可以在 <a href="/en-US/docs/Web/Guide/HTML/Forms/How_to_build_custom_form_widgets">HTML 表单教程</a>中查看更多高级例子，那里可以使用表单尝试。</p> diff --git a/files/zh-cn/mdn/contribute/howto/成为一名测试版试验员/index.html b/files/zh-cn/mdn/contribute/howto/成为一名测试版试验员/index.html new file mode 100644 index 0000000000..08693b3ff1 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/成为一名测试版试验员/index.html @@ -0,0 +1,53 @@ +--- +title: 如何成为一名测试版试验员 +slug: MDN/Contribute/Howto/成为一名测试版试验员 +tags: + - MDN Meta +translation_of: MDN/Contribute/Howto/Be_a_beta_tester +--- +<div>{{MDNSidebar}}</div> + +<p>随着MDN Kuma平台的开发人员不断地对站点进行更改，我们为那些选择成为测试版测试人员提供对这些新特性的早期访问。与任何“beta”测试一样，在某些情况下，一些功能可能无法正常工作。</p> + +<h2 id="参与beta测试">参与beta测试</h2> + +<ol> + <li>登录MDN，在顶部导航栏点击你的用户名。<br> + <img alt="Shows location of the user's profile link in the top navigation" src="https://mdn.mozillademos.org/files/15099/profile_link.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 59px; width: 383px;"><br> + 随后跳转到你的资料页。</li> + <li>点击<strong>编辑</strong>按钮。<br> + <img alt="Shows location of the button to edit a user's profile (which may vary depending on window dimensions" src="https://mdn.mozillademos.org/files/15093/profile_edit_link.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 144px; width: 387px;"><br> + 随后在编辑模式下打开资料页。</li> + <li>勾选复选框成为 <strong>Beta 测试者</strong>。<br> + <img alt="Shows the location of the Beta Tester checkbox" src="https://mdn.mozillademos.org/files/15095/profile_beta_checkbox.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 139px; width: 305px;"></li> + <li>点击资料页底部的<strong>发布</strong>按钮<br> + <img alt="Shows the location of the Publish button on a user's profile page" src="https://mdn.mozillademos.org/files/15097/profile_publish_button.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 218px; width: 477px;"></li> +</ol> + +<h2 id="退出Beta测试">退出Beta测试</h2> + +<ol> + <li>登录MDN，在顶部导航栏点击你的用户名。随后会跳转到你的资料页。</li> + <li>点击<strong>编辑</strong>按钮。随后在编辑模式下打开资料页。</li> + <li>取消 <strong>Beta 测试者</strong>的复选框</li> + <li>点击<strong>发布</strong>按钮.</li> +</ol> + +<h2 id="对beta测试给予反馈">对beta测试给予反馈</h2> + +<p>你有两种方式可以对 beta 测试进行反馈:</p> + +<ul> + <li>在MDN讨论组里分享质量反馈. 在 <a href="https://discourse.mozilla-community.org/t/beta-redesign-feedback/16544">Beta feedback thread</a> 发布一个帖子. 或者,</li> + <li>按照下面的步骤提交 bug:</li> +</ul> + +<ol> + <li>如果你还没有账号，创建一个 <a href="https://bugzilla.mozilla.org/createaccount.cgi">Bugzilla</a> 账号.</li> + <li>打开 <a href="https://bugzilla.mozilla.org/form.mdn#h=detail%7Cbug">bug report in Bugzilla for MDN</a>.</li> + <li>在“摘要”字段中包含 “beta” 一词，帮助 MDN开发人员过滤和区分传入的 bug。.</li> + <li>尽你所能填写 bug 报告. 越详细越好.</li> + <li>点击<strong>提交</strong>按钮.</li> +</ol> + +<p> </p> |