From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../convert_code_samples_to_be_live/index.html | 30 ++ .../howto/create_an_mdn_account/index.html | 44 ++ .../howto/create_and_edit_pages/index.html | 186 +++++++ .../howto/do_a_technical_review/index.html | 57 +++ .../howto/do_an_editorial_review/index.html | 55 +++ files/zh-cn/mdn/contribute/howto/index.html | 16 + .../howto/link_a_github_account/index.html | 89 ++++ .../howto/set_the_summary_for_a_page/index.html | 59 +++ files/zh-cn/mdn/contribute/howto/tag/index.html | 536 +++++++++++++++++++++ .../howto/tag_javascript_pages/index.html | 69 +++ .../write_a_new_entry_in_the_glossary/index.html | 107 ++++ .../howto/write_an_api_reference/index.html | 446 +++++++++++++++++ .../index.html | 505 +++++++++++++++++++ .../index.html | 117 +++++ .../mdn/contribute/howto/write_for_seo/index.html | 77 +++ .../index.html" | 30 ++ .../index.html" | 185 +++++++ .../index.html" | 53 ++ 18 files changed, 2661 insertions(+) create mode 100644 files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/tag/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/write_for_seo/index.html create mode 100644 "files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" create mode 100644 "files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" create mode 100644 "files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" (limited to 'files/zh-cn/mdn/contribute/howto') 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 +--- +
{{MDNSidebar}}

MDN 拥有一套 "live sample" 系统，在那里页面上展示的代码示例将被直接使用，以显示该示例的输出结果。然而，许多现有文章的代码示例还没有使用这套系统，它们需要被转换。

+ +

实样让你可以看到示例输出的样子，让文档生动有益。这篇指南涵盖如何获取现有示例并添加上“实时的”功能性。

+ +
+
哪里需要完成它？
+
标记有 NeedsLiveSample 的文章。
+
做这项任务你需要知道哪些？
+
+
    +
  • 基于代码示例，对 HTML, CSS 和/或 JavaScript 的理解。
    • +
  • 能够在 MDN 文章中使用 KumaScript 宏。
    • +
+
+
做这项任务的步骤是什么？
+
+
    +
  1. 从标记 NeedsLiveSample 的文章列表中选取一篇文章，这篇文章里的代码示例是你熟悉的。
    2. +
  2. 转换代码示例为“实例的”。
    3. +
  3. 删除之前用于显示示例输出结果的任何代码或图像。
    4. +
+
+
+ +

关于创建和编辑实样的更多信息，见 Using the live sample system

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 +--- +
{{MDNSidebar}}
+ +

 要对MDN的内容进行任何更改，你需要一个MDN账户。别担心，如果你只是打算阅读或搜索MDN，就不需要一个账户！这个指南  将帮助你建立MDN账户。

+ +
+
+

为什么MDN需要我的电子邮件地址？

+ +

你的电子邮件地址用于帐户恢复；必要时，MDN管理员会通过它来联系您，讨论你的账户或在网站上的活动。

+ +

此外，你可以选择订阅通知（例如，当特定的页面被更改）和消息（例如，如果你选择加入我们的beta测试团队，你可能会收到关于待测试新功能的邮件）。

+ +

你的电子邮件地址永远不会显示在MDN，并只会按照我们的隐私政策使用。

+ +
如果你通过Github登录到MDN，并且你的Github账号使用了“noreply”的电子邮件地址，你将不会收到任何来自MDN的信息（包括你从页面订阅的通知）。
+
+
+ +
    +
  1. 在每个MDN页面的顶部都有一个登录按钮。将鼠标指向它（如果你在移动设备上使用，轻触即可），以显示支持的登录到MDN的认证服务列表。
    2. +
  2. 选择一项服务以登录。目前，我们只支持使用Github登录。值得注意的是如果你选择GitHub，你的MDN公开资料页上将显示一个链接，其指向你的GitHub个人资料页。
    3. +
  3. 按照Github的提示，将你的GitHub帐户绑定到MDN。
    4. +
  4. 从认证服务页面返回到MDN之后，MDN会提示你输入用户名和电子邮件地址。你的用户名会公开显示，以便展示你做过的工作。请不要将你的电子邮件地址作为用户名。
    5. +
  5. 点击创建我的MDN个人资料。
    6. +
  6. 如果你在步骤4中指定的电子邮件地址与认证服务所使用的不同，请检查这个邮箱，并点击我们发送的确认邮件中的链接。
    7. +
+ +

一切就绪！你已经拥有一个MDN帐户，并可以立即编辑页面！

+ +

你可以在任何MDN页面的顶部点击你的名字以查看账号的公开资料。从那里，你可以点击编辑按钮修改或更新你的个人资料。

+ +
+

注：新用户名不能包含空格或“@”字符。请记住，你的用户名将会公开显示，以标识你做过的工作！

+
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 +--- +

测试页面

+ +

需要帮助？ • 编者指南 • 风格指南

+ +

如何编辑一个页面: 

+ +
    +
  1. 登陆 MDN Web Docs 账号，若未注册请注册。
    2. +
  2. 如果你在只读版本的 MDN Web Docs（https://developer.mozilla.org），点击点击页面右上角的 Edit in wiki（在 wiki 编辑）按钮。这将带你进入可编辑的，wiki 版本的网页（https://wiki.developer.mozilla.org），但是这并没有真正地打开可编辑的界面。
    3. +
  3. 请点击 wiki 页面文章标题旁的 编辑 按钮。
    4. +
  4. 页面会重新加载具有规定格式的编辑页面，你可以直接在页面上新增或者删除内容。
    5. +
  5. 你可以新增段落，删除文本，插入标题，并且执行更多涉及编写和编辑的功能。
    6. +
+ +

通过查看MDN Editor guide里的Editor UI elements获得更多关于MDN内置编辑器的信息。

+ +

预览修改

+ +

查看你修改的内容：

+ + + +

注意！预览页面并不会保存你的修改内容，所以你在关闭编辑的页面前必须保存你的修改。

+ +

版本注释

+ +

当预览修改之后，你需要保存你的修改版本。在保存之前，查看页面文章下方的版本注释栏，留下一些注释信息来告诉其它贡献者你为什么要去修改它。例如，你可能新增加了一个章节，或修改了一些文字来使得术语表述的更加一致，亦或重构了一个段落使其语言更加易于理解，或者就是删除了一些冗余信息。

+ +

目录

+ +

一篇文章的“在本文中”部分是自动生成的页面上标题的链接列表。这些链接的措词可以通过编辑标题进行编辑。也可以通过选择“编辑页面标题和属性”和改变“TOC”下拉列表的值，从而删除目录，或减少链接数量。

+ +

标签

+ +

你可以新增或删除编辑区域下面的一些描述页面内容或者功能的标签。查看 如何正确标记页面 来了解如何为页面添加合适的标签。

+ +

需要复核？

+ +

保存之前，为了确保信息的准确性，你可以勾选技术复核（针对代码，API，或技术），编辑复核（针对文章，语法，和内容），或模板复核（针对KumaScript code）的选择框，来让专家或有经验的贡献者复核你的编辑信息。

+ +

附件

+ +

如果你想附加某个文件到一个现有的页面中来添加插图或作进一步说明的话，你可以在页面底部输入。当你上传图片时，请确保使用图片优化工具进行优化，以便我们的图片足够小，方便下载。这样便提高了页面加载速度，提升MDN的整体性能。有可能有你钟爱的工具，如果没有的话，我们推荐一款容易上手的Web工具：TinyPNG。

+ +

保存，放弃更改，继续编辑

+ +

当你完成编辑，并确认过预览界面，你可以点击标题右边或者文章底部的的绿色按钮“发布修改”来发布你的文章和注释。如果你想要继续编辑，可以选择点击按钮“发布并继续编辑”来保证在保存编辑的同时不离开编辑模式。

+ +

如果你改变主意，你也可以点击页面右侧的红色按钮“放弃”来放弃你的编辑，注意放弃更改是不可撤销返回的。

+ +

在版本注释区域点击 Enter 键和点击按钮“发布并继续编辑”具有相同的效果。

+ +
+

注意：当你尝试保存你编辑好的页面时发现你的编辑被视为无效操作而被拒绝了，若你编辑好的内容又确实是适合MDN的，此时你可以向MDN管理团队发送邮件来获得帮助。

+
+ +

获取新建页面的许可

+ +

出于对安全的考虑，最近创建的MDN账号是没有权限新建页面的。如果你尝试这样做，你将看到一个页面引导你如何创建新页面。有以下两种可选的方式：

+ + + +

新建一个页面

+ +

当你拥有创建新页面的权限之后，你就可以开始创建页面了。

+ +

找不到在哪里新建一个页面？别担心！你可以在任何地方新建一个页面，我们会找到它并把它归档或者合并到最合适的类别下。你也不用过多担心它不够完美，我们有热心的志愿者来帮你打理，让你的文章保持干净美观。 

+ +

下面是一些新建页面的方法：

+ + + +

“缺失页面”链接

+ +

和许多维基站点一样，在 MDN 也有可能创建一个链接，它指向一个尚不存在的页面。例如：一个作者可能创建了一个清单页面，该页面涵盖了某个API的所有成员，而这些成员对应的页面还没创建好。在 MDN，指向到缺失页面的链接通常显示为红色。

+ +

从“缺失页面”链接创建对应的页面需要：

+ +
    +
  1. 确认已登录进 MDN，并且拥有新建页面的权限。（若未登录就点击“缺失页面”链接，会得到一个404（找不到页面）的错误。）
    2. +
  2. 点击“缺失页面”链接。如果你拥有页面创建权限，MDN编辑器界面会自动打开，准备好让你创建缺失的页面。
    3. +
  3. 编写页面内容，然后保存。
    4. +
+ +

不需要链接的新页面

+ +

想要创建一个没有链接到其他页面的新页面时，你需要在你的浏览器中键入一个包含新页面名字段的URL。例如，如果你键入以下URL并回车：

+ +
https://developer.mozilla.org/en-US/docs/FooBar
+ +

MDN将创建一个标题为“FooBar”的新页面并且打开编辑器让你能够为新添加的页面添加内容。请参考本文中编辑一个已存在的页面的小节来学习如何使用编辑器模式。

+ +

要创建一个没有链接到其他页面的新页面需要：

+ +
    +
  1. 确保您已经登陆MDN，并且拥有创建新页面的权限。
    2. +
  2. 在您的浏览器中输入以下URL并回车。
    3. +
+ +
https://developer.mozilla.org/en-US/docs/new
+ +

此时，MDN 创建新页面时有一个地方专门用来填写标题，打开编辑器后您就可以添加内容到这个新页面。请参考本文中编辑一个已存在的页面的小节来学习如何使用编辑器模式。

+ +

已存在页面的子页面

+ +

在页面层次结构中的现有页面以下创建页面，需要：

+ +
    +
  1. 在“父”页面，点击高级菜单（工具栏中的齿轮按钮），然后点击“新建子页面”。
    2. +
  2. 打开编辑器视图以创建新文档。
    3. +
  3. 在标题栏键入文档标题。
    4. +
  4. 需要的话，更改 Slug 字段（例如，若标题太长而你又想用较短的URL）。该字段由编辑器自动填充，替换掉标题处的空白下划线并且只更改文档对应的URL的最后一部分。
    5. +
  5. 在 TOC 字段，选择你想自动显示在页面目录中的标题级别，或者如果一个都不需要的话可以选择”无目录“。
    6. +
  6. 在编辑框中编写页面内容，然后保存您的修改。请参考本文中编辑一个已存在页面的小节来学习如何使用编辑器模式。
    7. +
+ +

克隆一个已存在的页面

+ +

如果你想应用一个已经存在的页面的版式，你可以“克隆”这个页面并且修改其内容。

+ +
    +
  1. 在原页面中，点击高级菜单（工具栏中的齿轮按钮），然后点击“克隆此文章”，一个编辑器视图就会被打开来创建新文档。
    2. +
  2. 更换一个合适的标题，当你在更改标题时，Slug 字段会自动更新。
    3. +
  3. +

    如果需要，更改 Slug 字段部分的路径，然后把新的文档放入文件夹的另一处（在大多数情况下这是没有必要的，因为克隆的页面与原始页面拥有相似的内容，因此克隆的页面应该与原始页面安排在相近的位置）。

    +
    4. +
  4. +

    在TOC字段中，选择你想让其显示在目录中的标题等级，或者选择“没有目录（No table of contents）”如果页面不需要的话。

    +
    5. +
  5. +

    在编辑面板输入页面的内容并保存您的修改。请参考本文中编辑一个已存在页面的小节来学习如何使用编辑器模式。

    +
    6. +
+ +

从现有页面链接到新页面

+ +

你可以在一个现有页面创建一个链接，然后点击这个链接来创建一个新页面：

+ +
    +
  1. 在现有页面上任意但合理的位置输入新页面的名字
    2. +
  2. 将名字设置为高亮显示并在编辑工具栏点击链接图标（也可能是简洁的锁链状）。“更新链接”对话框打开，高亮的文字会被显示在“链接文本”框中。 
    3. +
  3. "/en-US/docs/" 会被默认添加到URL的开头。在 "/en-US/docs/" 后输入此页面的名字。当然，链接文字和新页面的标题也可以不一样。
    4. +
  4. 点击“确认”来创建和插入这个链接。
    5. +
+ +

如果这个页面不存在，这个链接将会用红色显示。如果这个页面存在，这个链接将会用蓝色显示。如果你想创建一个新的页面，但是你想创建页面的标题被占用了，请考虑是否更应该去编辑和改进这个已经存在的页面。如果您认为创建一个新页面更有必要，可以选择一个不同的标题并创建它。请参考页面命名指南获得指导。

+ +

为了给您新建的页面添加内容，点击您刚刚创建的红色的链接（在保存并且关闭编辑器之后）。新的页面将进入编辑模式使您能够开始编写内容，请参考本文中编辑一个已存在的页面的小节来学习如何使用编辑器模式。

+ +

刷新页面内容

+ +

由于性能上原因，MDN对KumaScript 宏指令和将一个页面嵌入另一个页面中的支持有时候会稍微被页面缓存所妨碍。页面由它们的数据源编译，并且输出会被缓存起来用来将来的页面请求。从那时起，在该页面的任何宏指令（模板）或者嵌入（使用宏Page ）将不会展现由于宏，宏的输出，或者嵌入的原本内容所引起的变化。

+ + + +

更多参考

+ + 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 +--- +
{{MDNSidebar}}
+ +

技术复核包括审查一篇文章的技术准确性和完整性，并在必要的时候予以纠正。 如果一篇文章的作者需要其他人来对文章进行技术复核的话，就需要在编辑时勾选”技术复核“选项。通常情况下，作者会联系特定的工程师来执行技术审查，但是任何具有此领域专业技能的人都可以完成技术复核。

+ +

本文介绍如何进行技术复核，从而帮助确保MDN的内容的正确性。

+ +

任务是什么？

+ +

  审查和纠正文章的技术准确性和完整性。

+ +

什么地方需要技术审核？

+ +

  在被标记为需要技术审核的特定文章中。

+ +

开始做任务前你需要了解什么？

+ + + +

完成任务的步骤是什么？

+ +
    +
  1. 选取一篇需要复查的文章： +
      +
    1. 前往 technical reviews 页面。这里列出了所有需要技术复核的文章。
      2. +
    2. 选择一个你非常熟悉的领域的页面。
      3. +
    3. 点击该页面。
      4. +
    +
    2. +
  2. 在阅读这篇文章的时候注意文章里的所有技术细节：这篇文章的内容正确吗？是否缺少了一些细节？如果你觉得这篇文章不适合你，那么请毫不犹豫地换一篇文章。
    3. +
  3. 如果没有错误，你不需要重新编辑来把这篇文章标识为”已复核“，你只需要找到左边导航栏最下方的”快速复核“框。黄色背景的框里列出了所有等待复核的请求，像这样：
    4. +
  4. 去掉需要技术复核前面的勾，然后点保存。
    5. +
  5. 如果你发现了需要被修正的错误，你可以在编辑器里修改这篇文章的审核请求状态。以下是操作步骤： +
      +
    1. 点击页面顶部的编辑按钮，进入 MDN editor 页面，来编辑该页面。
      2. +
    2. 更正不正确的技术信息，还可以添加文章遗漏的任何重要信息。
      3. +
    3. 在文章的底部输入修改注释。这个注释简要地描述你的修改工作，比如“完成技术审查。”如果你更正了某些信息，将它们写进你的注释，比如“技术审查以及修复参数的相关描述。”这将帮助其他贡献者和网站编辑人员知道你修改的部分以及原因。如果你认为文章中有些不必要被审查的部分，也可以在注释中提出来。
      4. +
    4. 取消勾选“需要审查”下面的“技术”选项框了吗？它就在页面的审查注释区域。
      5. +
    5. 点击发布按钮。
      6. +
    +
    6. +
+ +

祝贺你，你已经完成了你的第一篇技术复核，感谢您的帮助！

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 +--- +
{{MDNSidebar}}
+ +
{{IncludeSubnav("/zh-CN/docs/MDN")}}
+ +

编辑审核的工作由修改文中排版错误，拼写、语法、用法等文本错误构成。并不是所有贡献者都是语言专家，但有了他们的共同努力，他们把那些需要编辑以及校对的文章转化为了极其有用的文章；这些都是在编辑审核的工作中完成的。

+ +

这篇文章描述了如何进行编辑审核，从而帮助实现 MDN 的内容精确。

+ +
+
任务是什么？
+
编辑并审核那些被标记为需要编辑审核的文章。
+
应该在何处处理它？
+
在特定的文章中会有标记有需要编辑审核的地方。
+
开始做任务前你需要了解什么？
+
你需要有好的中文语法和词汇技能。文章复核是要确保语法、用词都是正确的并且有意义，同时遵循 MDN 样式指南。
+
完成任务的步骤是什么？
+
+
    +
  1. 选择一篇文章来审核： +
      +
    1. 访问需要复核的文章列表。它陈列了所有请求编辑审核的页面。
      2. +
    2. 点击文章链接进入页面。
      + 注意：这个列表是自动生成的，但更新并不频繁，所以列表中的一些文章是不再需要编辑审核的。如果你选择的文章没有显示“这篇文章需要复核”，跳过这一篇文章，再选择其他的文章。
      3. +
    +
    2. +
  2. 仔细阅读文章，特别注意其中可能出现的排版、错字、语法或者词语使用错误。如果你觉得这篇文章不适合你，随时可以换一篇其它文章。
    3. +
  3. 如果文章中没有任何错误，你不需要进入编辑页面再把它标记为“已审核”。在页面的左侧边栏处可以找到“快速复核”对话框：
    + 文法复核边栏屏幕截图
    4. +
  4. 取消 文法 的勾选之后点击 保存 。
    5. +
  5. 如果你发现了需要改正的错误： +
      +
    1. 点击右上角蓝色的 编辑 按钮；它将带你进入 MDN 编辑器。
      2. +
    2. 更正所有你看到的的排版、错字、语法或者词语使用错误。你并不需要将所有问题都一次性改好，不过当完成整篇文章的时候你还觉得不确定是否完美，一定要保留文法复核的请求。
      3. +
    3. 在文本底部输入一段修订注释；比如 “文法符合：更改了排版，语法和用词错误。” 这有助于其他编辑者和网站管理员知道你更改了什么以及为什么做出更改。
      4. +
    4. 在 需要复核吗？ 下面取消 文法 的选择。这一项位于页面的 版本备注 当中。
      + 文法复核编辑模式屏幕截图
      5. +
    5. 点击 发布 按钮。
      6. +
    +
    6. +
+ +
+

你所做出的更改在保存后不一定立即可见，页面保存和处理过程可能出现一些延迟。

+
+
+
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 +--- +

<% //插入当前页面的子页面的定义列表，每个 //页面的标题为

+ +
+
术语，其 SEO 摘要为
+
术语。的 //如果可能，列表以两列视图显示。 // //参数： //没有 var html = 等待模板 （[子页与摘要] ); //现在，我们有了HTML中的整个列表。让我们通过它，并尝试用力把它分成两列。 %> <%-等待模板（"MakeColumnsForDL"，[html]）%>
+
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 +--- +
{{MDNSidebar}}
+ +
{{IncludeSubnav("/zh-CN/docs/MDN")}}
+ +
+

Note: 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 file an "Account Help" bug on Bugzilla. For further reading about the end of life of Persona, see: Persona shutdown guidelines.

+
+ + +

由于Mozilla的 Persona 身份认证系统将会于2016年11月30日起关闭，所有希望为MDN做贡献的用户都需要用其他手段来登录到 MDN。当前，我们支持的唯一选择就是 GitHub，所以您需要在截止日期过后使用 GitHub 账户登入并编辑 MDN。这篇文章讲述了如何将 GitHub 身份认证添加到您的MDN账户中。

+ +
+

您必须在2016年11月30日前完成此操作，否则您将再也无法登录 MDN！

+
+ +

概述

+ +

将GitHub身份认证添加到您的账户中并不难。下面我们将进一步讨论细节，但首先，先看一下步骤概述：

+ +
    +
  1. 登录您的 MDN 账户
    2. +
  2. 转到 账户关联 页面
    3. +
  3. 添加 GitHub 身份认证。
    4. +
+ +

详细指南

+ +

下面是一个手把手的教程，教您如何完成您需要知道的事情。

+ +

登入您的 MDN 账户

+ +
    +
  1. 在任意MDN页面的顶端，将鼠标悬浮于或点击登录框。它会显示可用的身份认证方式：Persona 或 GitHub 。
    + Sign in box on MDN, showing Persona and Github.
    2. +
  2. 选择 Persona ，然后用您常用的登录凭据登入。
    3. +
+ +

转到账户关联页面

+ +

有两种方法转到账户关联页面。

+ +

一种方法就是点击下面的链接。

+ + +

还有一种方法就是完成下列步骤：

+ +
    +
  1. 在任意 MDN 的页面顶端单击您的用户名（就是您未登录时登入框的位置）。这将带您到您的资料页面。
    2. +
  2. 点击“齿轮”菜单，然后单击 Account connections （账户关联）。
    + Gear menu in profile, showing the "Account connections" option
    3. +
+ +

添加 GitHub 身份认证

+ +

您现在位于"Account connections"（账户关联）页面，它罗列了您已连接到您的 MDN 个人资料的外部账户。如果 GitHub 账户已经列出，那么恭喜你！您已经完成了！但为了测试一下您是否牢记您的密码，可以登出 MDN，再使用您的 GitHub 身份凭证登入。

+ +

如果 Github 没有列出，请看看页面底部的已连接账户列表。您可以看到连接一个新的账号小节，这里列出了您可以与您的 MDN 个人资料建立连接的账户。如下图：

+ +

+ +

要想添加 GitHub：

+ +
    +
  1. 点击 连接 Github。MDN 将会向 Github 请求权限连接这两个账户。如果您还未登录 Github，登录页面将会显示出来：
    + Screenshot of GitHub sign in window.
    2. +
  2. 如果您为您的 Github 账户开通了两步验证，您须要输入您的验证码：
    + Screenshot of GitHub's Two-factor authentication window.
    3. +
  3. 现在您登录您的 Github 账户了。您可以进行授权，以连接 Github 与 MDN 账户（除非您曾经因某些原因授权过）。此页面如下图：
    + Screenshot of GitHub "Authorize application" window.
    + 点击绿色的 Authorize application（授权应用） 按钮授予您的 MDN 账户访问您的 Github 账户的权限。当您的 Github 账户成功与 MDN 账户建立连接时，您将看到这一信息：
    + Account successfully created.
    4. +
+ +

现在您不仅可用 GitHub 登录 MDN，还已经使用 GitHub 身份认证登入了！您已经准备好应对 Persona 关闭了。如有必要，您应该确定已经更新了安装的所有密码管理器。

+ +

相关链接

+ + 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 +--- +
{{MDNSidebar}}
+ +

您可以在MDN的每一个页面上定义概要，它可以在很多方面起到作用，如包含在搜索引擎的搜索结果中，或者在其他MDN页面如热门话题页或者工具提示页。它应该概括的描述该页面的所有内容，并且当在其他页面显示时，不包含页面内容的无关部分。

+ +
+

一个概要可以被明确的定在在一个页面中。如果概要没有被明确的定义，通常会使用该页面内容的第一句话作为概要，而它往往不是该页面最精确的描述。

+
+ + + + + + + + + + + + + + + + + + + + +
任务是什么？标记应被用作其在其他情况下摘要页面中的文本;这项任务可能包括在需要写相应的文本。
哪些地方需要它？在缺乏一个总结或总结不太好的页面。
完成任务需要什么？能够使用MDN编辑器的能力;良好的英语写作能力;对网页的主题足够熟悉，以便于能写一个很好的总结。
怎样完成任务？ +
    +
  1. 选择一个页面来设置总结: +
      +
    1. 在MDN documentation status 页面上的section中, 点击你所了解的话题。
      2. +
    2. 在主题的文档状态页面，单击汇总表中的页头。这需要你在该主题区段的所有网页的索引;它示出了在左侧列中的页面的链接，以及在右栏中的标签和摘要。
      3. +
    3. 挑选缺少一个总结页面，或者说有一个较差的总结的页面。
      4. +
    +
    2. +
+ +
+

点击链接进入该页面。

+
+ +
    +
  1. 单击编辑在MDN编辑器中打开该页面。
    2. +
  2. 找一两句话，作为一个总结。如果需要，可以编辑现有的内容来创建或修改的句子来做一个很好的总结。
    3. +
  3. 选择要使用的摘要文本。
    4. +
  4. 在样式插件的编辑器工具栏，选择搜索引擎优化摘要。 (In the page source, this creates a {{HTMLElement("span")}} element with class="seoSummary" around the selected text.)
    5. +
  5. 保存你的更改，并附上类似“设置页面总结”的修改意见。修改意见是可选的，但我们鼓励你添加一个。这样便于其他人了解变更的情况。
    6. +
+
+ +

完成这样的一份任务后，你就是MDN的一员。

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 +--- +
{{MDNSidebar}}
+ +

文章标签是一个让游客接触到有用内容的重要方式。每一个页面通常都应该有几个标签来保持其内容的组织性。  这一页解释了标记页面的最好方法，以使我们的读者可以找到信息和让我们的页面保持组织有序。

+ +

对于编辑标签的用户界面的帮助, 请看我们的编辑者指南里的标记部分。

+ +

请根据下面所解释的来合理的使用标签。 如果你没有这么做, 我们的自动化工具将不能正确的生成内容列表，着陆页面和文章的交叉链接。

+ +

MDN如何使用标签

+ +

MDN有这么几种方法来使用标签：

+ +
+
文档分类：
+
这个文档是什么类型的？是一篇参考？一篇教程？还是一篇着陆页？我们的游客可以使用这些标签来过滤搜索，所以它们真的很重要！
+
主题识别
+
这篇文章是关于什么的？关于API？DOM？图形？重申一遍，这些标签很重要，因为它们可以用来过滤搜索。
+
技术现状
+
这门技术的现状是什么？它是非标准的？过时的还是已经被弃用了的？还是处于实验性的？
+
技术水平
+
教程和指南，这篇文章中涵盖的内容有多先进？
+
文档元数据
+
写作社区使用标签来跟踪哪些页面需要什么样的工作。
+
+ +

标签类型指南

+ +

这里是关于标签类型的快速指南和它们可能用到的值。

+ +

文档类别

+ +

当你使用这些类别中的一个来标记文章的时候, 你帮助了自动化工具更准确的生成着陆页面，内容表，和更多。我们新的搜索系统也可以使用这些来让我们的游客更好的根据他们的意愿来定位参考和指南。

+ +
+
+

我们使用以下类别名称作为标准标记术语：

+
+
+ +
+
{{Tag("Intro")}}
+
+
+
+

这篇文章提供了一个有关主题的介绍材料。最理想的是每一个技术领域应该只能有一个“Intro”标签。

+
+
+
+
{{Tag("Featured")}}
+
+
+
+

这篇文章是至关重要的，将在登陆页面上显示在突出的位置上。有节制地使用这个标签（每个文件区不要超过三个）。

+
+
+
+
{{Tag("Reference")}}
+
这篇文章包含API、元素、属性、等的参考资料。
+
{{Tag("Landing")}}
+
这是一个着陆页面。
+
{{Tag("Guide")}}
+
这篇文章是一个告诉如何做或者指南的页面。
+
{{Tag("Example")}}
+
这是代码示例页面，或者有代码示例（那是有用的代码实例，而不是一行“语法例子”）。
+
+ +

主题

+ +
+
+

通过确定文章的主题区域，您可以帮助产生更好的搜索结果（以及着陆页和导航）。

+
+
+ +
+
+

虽然在这里有一些灵活的空间可以识别新的主题领域，但我们试着将自己限制在API和技术的名字上，一些有用的例子：

+
+
+ + + +
+
+

一般而言，您的主题标识标签应该是一个接口的名称，和相关的页面（如Node，它的各种属性和方法有很多页），或一个整体的技术类型的名称。你可以对图形、WebGL和WebGL设置页面标签，而不仅是一个关于{{HTMLElement("canvas")}} 与HTML、元素，Canvas，和图形。

+ +

Mozilla 特定内容

+ +

这些标签只用于Mozilla特定内容:

+ +
    +
  • {{Tag("Mozilla")}}
    • +
  • {{Tag("Firefox")}}
    • +
  • {{Tag("Firefox OS")}}
    • +
  • {{Tag("Gecko")}}
    • +
  • {{Tag("XUL")}}
    • +
  • {{Tag("XPCOM")}}
    • +
+ + + +

API 标识

+ +

在API引用中, 每篇文章都应该标明它覆盖了哪部分API:

+ +
+
{{tag("Interface")}}
+
一个接口的主要文章应该有这样的标签. 例如, {{DOMxRef("RTCPeerConnection")}}.
+
{{tag("Constructor")}}
+
每个接口最多可以有一个页面标记为“构造函数”（接口的构造函数）。页面应该有和接口一样的名字，如{{DOMxRef("RTCPeerConnection.RTCPeerConnection()","RTCPeerConnection()")}}.
+
{{tag("Property")}}
+
每一篇描述接口内特定属性的文章都需要这样的标记。以{{DOMxRef("RTCPeerConnection.connectionState")}}, 为例。
+
{{tag("Method")}}
+
每一篇记录接口方法的文章都需要这样的标记。以 {{DOMxRef("RTCPeerConnection.createOffer()")}}为例。
+
+ +

此外，引用页面需要在其标记中包含接口、属性和方法名称。一些例子如下：

+ +
+
接口 {{DOMxRef("RTCPeerConnection")}}
+
包含标签 "RTCPeerConnection" 以及其他相关标记 （"Interface"，"WebRTC"，"WebRTC API"，"API"，"Reference"等）。
+
方法{{DOMxRef("RTCPeerConnection.createOffer()")}}
+
包括标记 "RTCPeerConnection"和 "createOffer" (注意标记名中没有括号！) 以及其他相关标记，包括 "WebRTC"，"WebRTC API"，"API"，"Reference"等。考虑包含像 "Offer"和 "SDP"这些内容，它们在这里也是相关的。
+
属性{{DOMxRef("RTCPeerConnection.iceConnectionState")}}
+
包括标记"RTCPeerConnection"和"iceConnectionState"以及其他相关标记，包括 "WebRTC"，"WebRTC API"，"API"和"Reference"。也需要考虑包括 "ICE"。
+
+ + + +
    +
+
+
+ +

技术状况

+ +

为了帮助读者了解可行的技术是怎样的，我们使用标签来标记页面的技术规范的状态。这并不像实际解释规格是什么，以及技术在规范过程中出现了多少（这正是规格表的用途），但它有助于读者判断，乍一看之下，使用在文章中描述的技术是否是一个好主意。

+ +

这些标记是一些可能的值：

+ +
+
{{Tag("Non-standard")}}
+
+
+
+

表示页面中描述的技术或应用接口不是标准的一部分，但是在任何实现浏览器中都是稳定的。如果你不使用这个标签，你的读者会认为这是标准的技术。页面上的兼容性表应该说明该技术或API的支持。

+
+
+
+
{{Tag("Deprecated")}}
+
+
+
+

网页上的技术或API被标记为过时的规范，并有可能最终被删除，但一般仍可用在当前版本的浏览器。

+
+
+
+
{{Tag("Obsolete")}}
+
+
+
+

该技术或API已被认为已经过时，并已经在所有或大多数当前浏览器中被删除（或正在积极被删除）。

+
+
+
+
{{Tag("Experimental")}}
+
+
+
+

技术不是规范，而是一个实验性的技术或API，可能会或可能不会成为标准的一部分。它可能在浏览器的实现上被改变。

+
+
+
+
{{Tag("Needs Privileges")}}
+
+
+
+

该接口要求访问该设备在该设备上运行的权限。

+
+
+
+
{{Tag("Certified Only")}}
+
该API仅适用于认证码。
+
+ +

这些标签没有理由离开你文章中的 兼容性表 ！

+ +

技术水平

+ +
+
+

指南或教程的技术水平标签类型（那是，被标记的指南）帮助用户来基于他们的熟悉程度来选择教程，这里有三个值：

+
+
+ +
+
{{Tag("Beginner")}}
+
介绍读者到一个从未使用过的技术或仅仅是一种熟悉的技术。
+
{{Tag("Intermediate")}}
+
+
+
+

已经开始使用该技术的用户的文章，但不是专家。

+
+
+
+
{{Tag("Advanced")}}
+
关于拓展技术和读者能力的文章。
+
+ +

文档元数据

+ +
+
+

写作社区要求根据特定类型的工作来使用标签标记文章。以下是我们最常用的一个列表：

+
+
+ +
+
{{Tag("Draft")}}
+
文章不完整，至少在理论上仍在积极更新（尽管它也有可能被遗忘）。在进行更改之前，请尝试与最新的贡献者进行检查，以避免潜在的内容冲突。
+
{{Tag("NeedsCompatTable")}}
+
文章需要一个表来指定跨浏览器特性的兼容性，有关促进浏览器兼容性的指南参见此处。
+
+ +
+
{{Tag("NeedsContent")}}
+
+
+
+

文章是一个存根，或者是缺乏其他信息。这个标签意味着有人应该审查的内容，并添加更多的细节和/或完成写作的文章。

+
+
+
+
{{Tag("NeedsExample")}}
+
+
+
+

文章需要一个或多个例子来帮助说明文章的要点。这些例子应该使用实时示例系统.

+
+
+
+
{{Tag("NeedsLiveSamples")}}
+
+
+
+

本文有一个或多个实例，需要使用 在线样本系统更新。

+
+
+
+
{{Tag("NeedsUpdate")}}
+
内容过时，需要更新。
+
{{Tag("l10n:exclude")}}
+
+
+
+

内容是不真正值得本地化，不会出现在本地化状态页。

+
+
+
+
{{Tag("l10n:priority")}}
+
+
+
+

内容重要，应该被MDN标记为优先翻译。在本地化状态页上显示了一个额外的优先级表。

+
+
+
+
+ +

Web Literacy Map

+ +

The WebMaker project, through the Web Literacy Map, 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:

+ +
+
{{Tag("Navigation")}}
+
文章包含关于在web上如何搜索的信息。
+
{{Tag("WebMechanics")}}
+
内容有关于web如何组织和如何工作的信息。
+
{{Tag("Search")}}
+
文章解释了如何在web上寻找信息、人和资源。
+
{{Tag("Credibility")}}
+
文章中的信息帮助读者理解怎样批判性的评估他们在web上找到的信息。
+
{{Tag("Security")}}
+
文章提供有关如何保持系统、身份和内容安全的信息。
+
{{Tag("Composing")}}
+
文档解释如何创建和curate web上的内容。
+
{{Tag("Remixing")}}
+
文章讲授如何修改existing的网络资源来创建新的东西。
+
{{Tag("Design")}}
+
文档解释如何提高视觉和其他用户体验。
+
{{Tag("Accessibility")}}
+
文档描述如何用universally-recognizable的方式交流。
+
{{Tag("CodingScripting")}}
+
如何在网络上写代码和（或）创造交互式的用户体验。
+
{{Tag("Infrastructure")}}
+
文档解释Internet's technical stack是如何工作的。
+
{{Tag("Sharing")}}
+
文章内容包含与他人一起创造资源的方式。
+
{{Tag("Collaborating")}}
+
文档提供关于如何与他人一同工作的信息。
+
{{Tag("Community")}}
+
文章详细说明如何参与网络社区并理解他们如何工作。
+
{{Tag("Privacy")}}
+
材料帮助检查在网络上分享数据的后果。
+
{{Tag("OpenPractices")}}
+
文章provid=deshow帮助保持人人可以连接网络。
+
+ +

把它们放到一起

+ +

就可以从几种标签种类中搜索你标记的网页，例如

+ +
+
A tutorial about WebGL for beginners
+
WebGL, Graphics, Guide, Beginner
+
Reference page for {{HTMLElement("canvas")}}
+
Canvas, HTML, Element, Graphics, Reference
+
A landing page for Firefox OS developer tools
+
Tools, Firefox OS, Landing
+
+ +

标签和搜索过滤

+ +

只有我们正确地标记网页，搜索过滤才能正确工作。这是一个搜索过滤和它们寻找的标签的表格。

+ +
+

注意：Note: 如果多个标签被列在“tag name”下，那说明，为了搜索，任何一个或更多的标签必须在文章中。

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Filter groupSearch filter nameTag name
TopicOpen Web Apps{{Tag("Apps")}}
HTML{{Tag("HTML")}}
CSS{{Tag("CSS")}}
JavaScript{{Tag("JavaScript")}}
APIs and DOM{{Tag("API")}}
Canvas{{Tag("Canvas")}}
SVG{{Tag("SVG")}}
MathML{{Tag("MathML")}}
WebGL{{Tag("WebGL")}}
XUL{{Tag("XUL")}}
Marketplace{{Tag("Marketplace")}}
Firefox{{Tag("Firefox")}}
Firefox for Android{{Tag("Firefox Mobile")}}
Firefox for Desktop{{Tag("Firefox Desktop")}}
Firefox OS{{Tag("Firefox OS")}}
Mobile{{Tag("Mobile")}}
Web Development{{Tag("Web Development")}}
Add-ons & Extensions{{Tag("Add-ons ")}}|| {{Tag("Extensions")}} || {{Tag("Plugins")}} || {{Tag("Themes")}}
Games{{Tag("Games")}}
Skill levelI'm an Expert{{Tag("Advanced")}}
Intermediate{{Tag("Intermediate")}}
I'm Learning{{Tag("Beginner")}}
Document typeDocsThis restricts the search to docs content, leaving out Hacks and other MDN content.
DemosThis includes Demo Studio content in the search results.
Tools{{Tag("Tools")}}
Code Samples{{Tag("Example")}}
How-To & Tutorial{{Tag("Guide")}}
Developer ProfilesThis includes developer profiles from the MDN site in the search results.
External ResourcesThe dev team is still figuring this out...
+ +

你可以修改的标签的错误

+ +

这些种类的标签错误你可以帮助修改：

+ +
+
没有标签
+
一般来说文章应该至少有一个 "category" 标签和一个 "topic"标签. 虽然有其他标签也好, 但是如果你能帮我们提供最基本的标签（前文所说的category和topic标签）, 你将会是一名（维护）文档的英雄!
+
不符合我们标签标准的标签
+
请修正一切含有不合标准标签的文档.请注意由于Kuma的一个bug, 一些本地化的标签(比如 Référence) 可能会出现在一些英语页面上. 这些标签还有可能反复出现,即使你已经吧它们删除; 请耐心处理这些问题直到kuma的那个bug被修复.
+
不正确的标签
+
如果你正在看一篇关于HTML的文章并且发现它被标上了"JavaScript"的标签, 那很有可能这是一个错误标签! 同理, 如果一篇文章在讨论Mozilla internals 但是有一个"Web"标签, 那也有可能是错误的. 删除这些错误的标签并且如果还没有合适标签的话，加上正确的标签. 同样请更正拼写错误的标签(e.g., 因为标签是大小写敏感的, 所以"Javascript" 仍然匹配, 但是我们还是不要马虎对待!).
+
缺失的标签
+
如果一篇文章有标签但是不全面, 请补全. 比如, 一页JavaScript 的参考文档被(正确) 标签为 "JavaScript" 但是除此之外什么也没有了, 请你就为它标上"参考"的标签!
+
垃圾标签
+
这只潜伏的怪兽是所有标签问题中最让人讨厌的: 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")}}.
+
+ +

如果你发现了以上问题, 请登录MDN点击MDN窗口右上方的 EDIT按钮. 等编辑器载入完成后, 到页面底部, 你就会看到标签. 想了解标签操作界面的更多信息, 请参看 "The tags box" in the MDN editor guide.

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 +--- +
{{MDNSidebar}}

标记工作包括给页面添加元信息，使得这些页面的相关内容能被搜索工具等正确的分拣。

+ +
+
哪里需要做这件事?
+
那些特定的没有标签的JavaScript相关的页面
+
开始标记任务前你需要知道些什么？
+
一些基本的JavaScript编程知识，比如javascript中的方法和属性都是些什么。
+
你的工作有以下几个步骤
+
+
    +
  1. 选择下面列举的某篇文章。
    2. +
  2. 点击该文章所对应的链接，载入页面。
    3. +
  3. 当页面载入完毕时，点击顶部附近的EDIT按钮，就会进入MDN编辑模式。
    4. +
  4. 最后就是添加Javascript相关的标签了，我们提供了如下可选的标签。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    标签名适用于含有哪些内容的页面
    Method方法
    Property属性
    Prototype原型
    Object type name所述对象的名字，例如String.fromCharCode就应该有String标签
    ECMAScript6 and Experimental在新版ECMAScript标准中增加的特性
    Deprecated不赞成使用的特性（那些不鼓励使用但仍然被浏览器支持的特性）
    Obsolete被废弃的特性（那些不再被浏览器支持的特性）
    others查看 MDN 标签规则 中其他可选标签
    +
    5. +
  5. 添加备注信息并保存你的修改。
    6. +
  6. 你做到了！
    7. +
+
+
+ +

 

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 +--- +
{{MDNSidebar}}
+ +

MDN 术语表 是一个定义所有被用于文档和编码的术语、行话和缩写的地方。对词汇表做出贡献是使Web更易于理解的简单方法。您不需要高水平的技术技能来编写词汇表条目，因为它们应该保持简单直接。

+ +

如何写一个条目

+ +

如果您正在寻找需要词汇表条目的主题，请查看词汇表首页末尾的未撰写文档的条目清单。请单击您希望创建的词汇条目的链接，进入”新的词汇表页面“准备新条目的创建。然后按照后面的步骤操作。

+ +

如果您有添加新的词汇表条目的想法，只需在新选项卡中打开以下按钮，然后按照按钮下方的步骤操作：

+ +

向术语表中添加一个新条目

+ +

第一步: 写概要

+ +

任何词汇表页面的第一段是对该术语的简单和简短描述（最好不超过两个句子）。 确保阅读说明的人能够立即了解定义的术语。

+ +
+

注意: 请不要直接从其他地方复制和粘贴定义（尤其是维基百科，因为许可证版本范围较小，因此与MDN不兼容）。确保条目内容简单易懂是很重要的。值得花一些时间来撰写定义，而不是简单盲目地窃取其他地方的内容。 这个词汇表应该是有用的新内容，而不是和别处重复的。

+
+ +

使用“链接到词汇表条目”工具可以方便读者直接看到词汇条目中的定义，不需要读者跳转到词汇条目的页面。（更多内容请浏览如何使用 \{{Glossary}} 宏插入词汇表条目的链接。）

+ +

如果需要的话，你可以添加少量额外的段落，但是这很容易导致你写了一整篇文章的情况发生。写一个完整的文章很棒，但是请不要把它们整个放在词汇表中。如果你不确定这里是否适合放你的文章，你就要随时在这里讨论。

+ +

第二步: 扩展链接

+ +

最后，一个词汇表的条目应该总是有“了解更多”这个部分。这个部分应该包含帮助读者看得更深入的链接：探索发现更多细节、学习使用相关技术等。

+ +

我们建议您将链接分为以下三组：

+ +
+
基础知识
+
提供更多一般信息的链接。如：到维基百科的链接是一个很棒的点。 
+
技术参考
+
链接到更深入的技术信息，在MDN或其他地方。
+
学习它
+
链接到教程、练习或任何其他材料，帮助读者学习使用定义术语背后的技术。
+
+ +

小建议

+ +

所以你想贡献，但你不知道需要定义哪些术语？ 这里是是建议列表。点击一下，开始吧！

+ +

消除歧义

+ +

有时，根据上下文，术语有几个含义。 要解决歧义，您必须遵循以下准则：

+ + + +

我们以一个例子来说明。signature 条目在至少三种不同的语境中具有不同的含义： 安全、函数 和 电子邮件。

+ +
    +
  1. Glossary/Signature 页面是使用了 {{TemplateLink("GlossaryDisambiguation")}} 宏的消歧页面；
    2. +
  2. Glossary/Signature/Security 页面是定义安全上下文中签名的条目页面；
    3. +
  3. Glossary/Signature/Function 页面是定义函数签名的条目页面；
    4. +
  4. Glossary/Signature/Email 页面是定义电子邮件签名的条目页面。
    5. +
+ +

如何使用 \{{Glossary}} 宏

+ +

当人们可以在另一个文档访问到词汇的定义，而无需他们从正在阅读的内容进行跳转阅读词汇定义时，词汇表是最好用的。因此，我们敦促您随时使用 {{TemplateLink("Glossary")}} 宏将词汇链接到词汇表：

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
宏结果备注
\{{Glossary("browser")}}{{Glossary("browser")}}当文本与要定义的术语匹配时，只需直接使用宏（不区分大小写）
\{{Glossary("browser", "Web浏览器")}}{{Glossary("browser","Web浏览器")}}要显示替代文本，请使用第二个参数来指定该文本
\{{Glossary("browser", "Web浏览器", 1)}}{{Glossary("browser","Web浏览器",1)}}指定 1 作为可选的第三个参数，将链接显示为常规链接，而不是单纯的提示文本的样式
+ +

使用 \{{Glossary}} 宏创建的链接将总是展示一个包含了词汇表条目的概要段落的提示文本（tooltip）。

+ +

使用方针

+ +

在许多情况下，在MDN上的任何地方使用该宏是非常安全的。 但是，您应该谨慎处理的几种情况：

+ + 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 +--- +
{{MDNSidebar}}
+ +
+

This guide takes you through all you need to know to write an API reference on MDN.

+
+ +

Getting prepared

+ +

Before starting to document an API, there are some things you should prepare and plan in advance of starting to actually write.

+ +

Prerequisite knowledge

+ +

It is assumed that before reading this guide you have a reasonable knowledge of:

+ + + +

Everything else can be learned along the way.

+ +

Prerequisite resources

+ +

Before starting to document an API, you should have available:

+ +
    +
  1. 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.
    2. +
  2. The latest modern web browsers: These should be experimental/alpha builds such as Firefox Nightly/Chrome Canary that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a nascent/experimental API.
    3. +
  3. Demos/blog posts/other info: Find as much info as you can.
    4. +
  4. 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: +
      +
    • Your internal company address book, if you work for a relevant company.
      • +
    • A public mailing list that is involved in the discussion of that API,  such as Mozilla's dev-platform or dev-webapi lists, or a W3C list like public-webapps.
      • +
    • The spec itself. For example, the Web Audio API spec lists the authors and their contact details at the top.
      • +
    +
    5. +
+ +

Take some time to play with the API

+ +

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.

+ +

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.

+ +
+

Note: 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.

+
+ +

Create the list of documents you need to write or update

+ +

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.

+ +

Overview page

+ +

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 (https://developer.mozilla.org/en-US/docs/Web/API)

+ + + +

Note that most API have a special sidebar with quicklinks. This sidebar lists all interfaces, and possibly tutorials and related API.

+ +

Interfaces

+ +

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 (https://developer.mozilla.org/en-US/docs/Web/API)

+ + + + + +
+

Note: We document every property and interface appearing in the prototype of an object implementing this interface. This has the following consequences:

+ + +
+ +

Properties

+ +

The set of properties of a given interface can be found on its WebIDL. 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:

+ + + +
+

Note: Event handlers properties (onXYZ properties) are also listed: they'll have their individual subpage, like any other property.

+
+ +

Methods

+ +

Like for properties, methods are listed on the interface's WebIDL 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:

+ + + +

Constructors

+ +

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.

+ + + +

Events

+ +

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:

+ + + +

Listing them all

+ +

Creating a list of all these subpages is a good way to track them. For example:

+ + + +

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.

+ +

For example, given the list above, the {{domxref("AudioContext")}} interface is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext

+ +

Create the overview page

+ +

Now create the overview (API landing) page:

+ +
    +
  1. Go to https://developer.mozilla.org/en-US/docs/Web/API and, making sure you are logged in, select the Cog icon > New sub-page. You should now be in an editor for a new page.
    2. +
  2. 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".
    3. +
  3. The Slug should be auto-filled, with underscores in the place of spaces. If it isn't, correct it.
    4. +
  4. Enter some dummy content into the large content area, such as "TBD" or "Content", then click Save Changes. Or just soar right on into the section {{anch("Overview page")}} and start filling out the real content right away.
    5. +
+ +

Your landing page now exists! Now all you have to do is fill it in, which is discussed in the next section.

+ +

Structure of an overview page

+ +
+

Important: This section is still a proposal, without consensus yet reached. Don't use it yet.

+
+ +

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 https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API for an example of a big landing page.

+ +

The features of a landing page are outlined below:

+ +
    +
  1. Description: the first paragraph of the landing page should provide a short, concise description of the API's overarching purpose.
    2. +
  2. Concepts and usage section: 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.
    3. +
  3. List of interfaces: 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.
    4. +
  4. Obsolete interfaces: This section lists obsolete interfaces. Ed. note: should this be a subsection of the main "Interfaces" section above?
    5. +
  5. List of mixins: If any mixins are defined on the API spec, list them under a separate section, as they aren't interfaces as such.
    6. +
  6. Example: This section should show a simple use case for the API.
    7. +
  7. Specifications table: At this point you need to include a  specifications table — see the "Creating a spec reference table"  section for more details.
    8. +
  8. Browser compatibility: Now you need to include a browser compatibility table. See Compatibility tables for details.
    9. +
  9. See also: 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.
    10. +
  10. Tags: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.
    11. +
+ +

Structure of an interface page

+ +

Now you should be ready to start writing your interface pages. Each interface reference page should observe the following structure:

+ +
    +
  1. \{{APIRef}}: 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 GroupData 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.
    + This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro
    2. +
  2. Standardization status: The banner indicating the standardization status should be added next (these can be placed on the same line as the \{{APIRef}} macro.): +
      +
    • \{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
      • +
    • \{{Deprecated_header}}
      • +
    • \{{Obsolete_header}}
      • +
    • \{{Non-standard_header}}
      • +
    +
    3. +
  3. Description: 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".
    4. +
  4. Inheritance diagram: 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.
    5. +
  5. +

    List of properties, List of methods: 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.
    +
    + At the beginning of both sections, before the beginning of the list of properties/methods, indicate inheritance using the appropriate sentence, in italics:
    + This interface doesn't implement any specific properties, but inherits properties from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.
    + This interface also inherits properties from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.
    + This interface doesn't implement any specific methods, but inherits methods from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.
    + This interface also inherits methods from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.

    + +
    +

    Note: If the interface features event handlers, put these inside the "Properties" section (they are a type of property) under a subheading of "Event handlers".

    +
    + +
    +

    Note:  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.

    +
    +
    6. +
  6. Example: 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 Github repo containing the full example, and you could  also link to a live example created using the Github gh-pages feature (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN Live Sample feature to make it live and playable in the page. +
    +

    Note: More details about writing code examples can be found in the "Examples" section.

    +
    +
    7. +
  7. Specifications table: At this point you need to include a specifications table — see the "Creating a spec reference table" section  for more details.
    8. +
  8. Browser compatibility: Now you need to include a browser compatibility table. See Compatibility tables for details.
    9. +
  9. Polyfill: 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.
    10. +
  10. See also: 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: +
      +
    • Do not include pages with the same information as another page in the MDN; link to that page instead.
      • +
    • Do not put author names — we are a writer-neutral documentation site. Link to the document; the author name will be displayed there.
      • +
    • 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.
      • +
    • 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).
      • +
    +
    11. +
  11. Tags: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.
    12. +
+ +

Interface page examples

+ +

The following are exemplary examples of Interface pages:

+ + + +

Structure of a property page

+ +

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.

+ +

Edit the property page name to follow the Interface.property_name convention.

+ +

Property pages must have the following sections:

+ +
    +
  1. Title: the title of the page must be InterfaceName.propertyName. 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 .prototype. in the title, like we do in the JavaScript reference.
    2. +
  2. \{{APIRef}}: 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 GroupData 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.
    + This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro
    3. +
  3. Standardization status: 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): +
      +
    • \{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
      • +
    • \{{Deprecated_header}}
      • +
    • \{{Obsolete_header}}
      • +
    • \{{Non-standard_header}}
      • +
    +
    4. +
  4. Description: 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: +
    +
    For read-only properties
    +
    The InterfaceName.property read-only property returns a \{{domxref("type")}} that...
    +
    For other properties
    +
    The InterfaceName.property property is a \{{domxref("type")}} that…
    +
    + +
    Note: InterfaceName.property should be in <code>, and should additionally be in bold (<strong>) the first time it's used.
    +
    5. +
  5. Syntax: The syntax section should show how to get the property, and how to set it, if it's not read only. Use the syntaxbox class for it and italics for part to be replaced by the actual variable name. For example: + 
    var myType = oscillator.type;
+oscillator.type = aType;
+
    + 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")}}
    6. +
  6. +

    Example: 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 Github repo containing the full example, and you could also link to a live example created using the github gh-pages feature (so long as it uses only client-side code of course.) You can also make use of the MDN Sample Server, which is particularly helpful for more complex samples. If the example is visual, you could also use the MDN Live Sample feature to make it live and playable in the page.

    + +
    Note: If you make use of Github, the example must live under github.com/mdn. See the "Examples" section for more details.
    +
    7. +
  7. Specifications table: At this point you need to include a specifications table — see the "Creating a spec reference table"  section for more details.
    8. +
  8. Browser compatibility: Now you need to include a browser compatibility table. See Compatibility tables for details.
    9. +
  9. See also: 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.
    10. +
  10. Tags: There is a set of standard tags you should include for each property page — see the "Tags" section for more.
    11. +
+ +

Property page examples

+ +

The following are exemplary examples of property pages:

+ + + +

Structure of a method page

+ +

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.

+ +

Method pages need the following sections:

+ +
    +
  1. Title: the title of the page must be InterfaceName.method() (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 .prototype. in the title, like we do in the JavaScript reference.
    2. +
  2. \{{APIRef}}: 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 GroupData 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.
    + This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro
    3. +
  3. Standardization status: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \{{APIRef}} macro): +
      +
    • \{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
      • +
    • \{{Deprecated_header}}
      • +
    • \{{Obsolete_header}}
      • +
    • \{{Non-standard_header}}
      • +
    +
    4. +
  4. Description: 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. +
    +
    The beginning of the first sentence must follow the following structure:
    +
    The InterfaceName.method() method interface ...
    +
    + +
    Note: InterfaceName.method() should be in <code>, and should also be in bold (<strong>) the first time it's used.
    +
    5. +
  5. Syntax: The syntax section should include a 2–3 line example — usually just construction of the  interface, then calling of the interface method. +
    +
    The syntax should be of the form:
    +
    var  <em>returnValue</em> =  <em>ifName</em>.method(<em>param1</em>,  <em>param2</em>, ...)
    +
    If the method has no return value (void as return value in the webidl), use:
    +
    <em>ifName</em>.method(<em>param1</em>,  <em>param2</em>, ...)
    +
    + The syntax section should include three subsections (see {{domxref("SubtleCrypto.sign()")}} for an example): + +
      +
    • "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.
      • +
    • "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")}}).
      • +
    • "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.
      • +
    +
    6. +
  6. Example: 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 Github repo containing the full example, and you could also link to a live example created using the Github gh-pages feature (so long as it uses only client-side code of course.) You can also make use of the MDN Sample Server, 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 Live Sample feature to make it live and playable in the page.
    7. +
  7. Specifications table: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.
    8. +
  8. Browser compatibility: Now you need to include a browser compatibility table. See Compatibility tables for details.
    9. +
  9. Polyfill: 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.
    10. +
+ +

Method page examples

+ +

The following are exemplary examples of Interface pages:

+ + + +

Tagging

+ +

For API reference pages, there are standard tags that all pages should have:

+ + + +

For Interface pages, also add:

+ + + +

For method pages, also add:

+ + + +

For property pages, also add:

+ + + +

In all cases, also add a keyword indicating the standardization status:

+ + + +

These tags will be used to generate correct quicklinks, with nice icons. See How to properly tag pages for additional information on tagging, as well as about other tags you may find useful.

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 +--- +
+

{{MDNSidebar}}

+ +

在编写有关API的文档时，信息来源很多：规范描述了应该实现的内容以及模型，实现描述了实际放在浏览器中的内容。WebIDL文件是一种非常简洁的方式，可以提供很多（但不是全部）有关API的信息。本文档提供了有助于理解WebIDL语法的参考。

+ +

IDL代表接口定义语言，它用于描述API。在更广泛的计算领域，有几种IDL。在浏览器领域，我们使用的IDL称为WebIDL。有两种WebIDL可用：WebIDL规范中给出的一种，以及在浏览器中实现的一种。规范是规范引用，浏览器WebIDL描述了在特定浏览器中实际实现的内容，并包含其他内容，例如注释和有关非标准元素的信息。

+
+ +

 

+ +

在哪里可以找到WebIDL文件

+ +

WebIDL可以在多个位置找到：

+ + + +

Different dialects of WebIDL

+ +

WebIDL is defined in its specification. But it has been designed to be extended to convey more information, and browser vendors have done so:

+ + + +
+

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.

+
+ +

Interfaces

+ +

This section explains the WebIDL syntax that describes overall API features.

+ +

Name of the interface

+ +

The interface name is the string that appears after the keyword interface and before the next opening bracket ('{') or colon (':').

+ +
interface URL {};
+ +

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.

+ +

Inheritance chain

+ +

The parent, if any, of a given interface is defined after the interface name, following a colon (':'). There can be only one parent per interface.

+ +
interface HTMLMediaElement : HTMLElement {…}
+ +

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}}.

+ +

Mixins

+ +

Some properties or methods are available to several interfaces. To prevent redefinition they are defined in special WebIDL interfaces called mixins. In the WebIDL, they are prefixed using the [NoInterfaceObject] annotation. The name of a mixin, Body in the following example, doesn't appear in JavaScript.

+ +
[NoInterfaceObject]
+   interface Body {…}
+ +

For documentation purposes, we create a mixin page, with the same structure as an interface page. As they are not true interfaces, the word interface is not used — mixin is used instead.

+ +

Mixin methods and properties are listed in the same way as regular methods and properties:

+ + + +

Mixins implemented on an interface are defined using the implements keyword.

+ +
Request implements Body;
+Response implements Body;
+ +
+

Note: 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.)

+
+ +

Availability in workers

+ +

Availability in Web workers (of any type) and on the Window scope is defined using an annotation: [Exposed=(Window,Worker)]. The annotation applies to the partial interface it is listed with. If no annotation is available, the default value is Window.

+ +
[Exposed=(Window,Worker)]
+interface Performance {
+   [DependsOn=DeviceState, Affects=Nothing]
+   DOMHighResTimeStamp now();
+};
+
+[Exposed=Window]
+partial interface Performance {
+   [Constant]
+   readonly attribute PerformanceTiming timing;
+   [Constant]
+   readonly attribute PerformanceNavigation navigation;
+
+   jsonifier;
+};
+ +

In this case Performance.now() is available on the Window scope and to any worker, while Performance.timing, Performance.navigation and Performance.toJSON() are not available to Web workers.

+ +

The most common values for the [Exposed] are:

+ +
+
Window
+
The partial interface is available to the {{domxref('Window')}} global scope.
+
Worker
+
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 ChromeWorker, but we don't document this as they are not visible on the Web and are internal to Firefox.)
+
DedicatedWorker
+
The partial interface is available to the {{domxref('DedicatedWorkerGlobalScope')}} only.
+
SharedWorker
+
The partial interface is available to the {{domxref('SharedWorkerGlobalScope')}} only.
+
ServiceWorker
+
The partial interface is available to the {{domxref('ServiceWorkerGlobalScope')}} only.
+
+ +

Another value is possible, like System, but this has a special meaning and doesn't need to be documented.

+ +

Note that these possible values are themselves defined in WebIDL files. Interfaces may have a [Global=xyz] annotation. It means that when an object of this type is used as a global scope, any interface, property or method, with xyz as a value of [Exposed] is available.

+ +
[Global=(Worker,DedicatedWorker), Exposed=DedicatedWorker]
+interface DedicatedWorkerGlobalScope : WorkerGlobalScope {…}
+ +

Here, it is defined that when the global scope is of type DedicatedWorkerGlobalScope, that is if we are in a dedicated worker, any interface, property or method exposed – using the [Exposed] annotation – to Worker or DedicatedWorker is available.

+ +

Even the primary global is defined in WebIDL. The primary global is the value of an [Exposed] annotation when not present. This is defined using the [PrimaryGlobal] annotation and is present on {{domxref('Window')}}:

+ +
[PrimaryGlobal, NeedResolve]
+/*sealed*/ interface Window : EventTarget {…}
+ +

Preferences

+ +
+

Note: this information is specific to Gecko and should only be used in the Browser compatibility section.

+
+ +

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.

+ +
[Pref="media.webspeech.synth.enabled"]
+interface SpeechSynthesis {
+   readonly attribute boolean pending;
+   readonly attribute boolean speaking;
+   readonly attribute boolean paused;
+};
+ +

Here media.webspeech.synth.enabled controls the SpeechSynthesis interface and its properties (the full listing has more than 3.)

+ +
+

Note: the default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)

+
+ +

Properties

+ +

You can recognize the definition of a property by the presence of the attribute keyword.

+ +

Name of the property

+ +
readonly attribute MediaError? error;
+ +

In the above example the name of the property is error; in the docs we will refer to it as HTMLMediaElement.error as it belongs to the HTMLMediaElement interface. Linking to the page is either done with the interface prefix using \{{domxref('HTMLMediaElement.error')}} or without the prefix using \{{domxref('HTMLMediaElement.error', 'error')}} when the context is obvious and unambiguous.

+ +

Type of the property

+ +
readonly attribute MediaError? error;
+ +

The property value is an object of type MediaError. The question mark ('?') indicates that it can take a value of null, and the documentation must explain when this may occur. If no question mark is present, the error property can't be null.

+ +

Writing permissions on the property

+ +
readonly attribute MediaError? error;
+ +

If the keyword readonly is present, the property can't be modified. It must be marked as read-only:

+ + + +
+

Note: Only read-only properties can be described as 'returning' a value. Non read-only properties can also be used to set a value.

+
+ + + +

Throwing exceptions

+ +
[SetterThrows]
+            attribute DOMString src;
+ +

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 [SetterThrows] annotation. When this happens, the Syntax section of the property page must 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.

+ +

Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. Trying to set an illegal enumerated value (mapped to a JavaScript {{jsxref('String')}}) raises a {{exception('TypeError')}} exception. This must be documented, but is only implicitly marked in the WebIDL document.

+ +

It is uncommon to have getters throwing exceptions, though it happens in a few cases. In this case the [GetterThrows] annotation is used. Here also, the Syntax section of the property page must have an Exceptions subsection.

+ +
partial interface Blob {
+  [GetterThrows]
+  readonly attribute unsigned long long size;
+};
+
+ +

Not throwing exceptions

+ +

When the semantics of Webidl is not followed, an exception is often thrown, even without [SetterThrows] or [GetterThrows] 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.

+ +

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 [LenientSetter] annotation can be used.

+ +
partial interface Document {
+  [LenientSetter]
+  readonly attribute boolean fullscreen;
+  [LenientSetter]
+  readonly attribute boolean fullscreenEnabled;
+};
+
+ +

In these cases, an extra sentence is added to the description of the property. E.g

+ +

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.

+ +

New objects or references

+ +

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.

+ +

Basic objects with types like {{jsxref("String")}} (being an IDL DOMString, or other), {{jsxref("Number")}} (being an IDL byte, octet, unsigned int, 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.)

+ +

For interface objects, the default is to return a reference 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.

+ +
+

Note: The keyword readonly used with a property returning an object applies to the reference (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.

+
+ +

Sometimes an API must return a new object, or a copy of an internal one. This case is indicated in the WebIDL using the [NewObject] annotation.

+ +
[NewObject]
+   readonly attribute TimeRanges buffered;
+ +

In this case, each call to buffered 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 new next to object:

+ +

The HTMLMediaElement.buffered read-only property returns a new \{{domxref("TimeRanges")}} object that…

+ +

and

+ +
+
\{{domxref("HTMLMediaElement.buffered")}}\{{readonlyinline}}
+
Returns a new \{{domxref("TimeRanges")}} object that …
+
+ +

In the case of a reference to a collection object (like HTMLCollection, HTMLFormElementsCollection, or HTMLOptionsCollection, always without [NewObject]), 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 live HTMLCollection (or HTMLFormElementsCollections, or HTMLOptionsCollection), both in the interface description and in the subpage.

+ +

E.g.

+ +
+
\{{domxref("HTMLFormElement.elements")}}\{{readonlyinline}}
+
Returns a live \{{domxref("HTMLFormControlsCollection")}} containing…
+
+ +

Availability in workers

+ +

Individual property availability in workers is also found in the WebIDL. For a property, the default is the same availability as the interface (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the partial interface it is defined in.

+ +

For documentation, the subpage must contain a sentence indicating if it is available or not in Web workers, right before the "Syntax" section.

+ +

Preferences

+ +
+

This information is specific to Gecko and should only be used in the Browser compatibility section.

+
+ +

In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.

+ +
[Pref="media.webvtt.enabled"]
+    readonly attribute TextTrackList? textTracks;
+ +

Here media.webvtt.enabled controls the textTracks property.

+ +
+

The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another).

+
+ +

Methods

+ +

You can recognize the definition of a method by the presence of parentheses after the name.

+ +

Name of the method

+ +
DOMString canPlayType(DOMString type);
+ +

The name of the method is canPlayType, and we will refer to it as HTMLMediaElement.canPlayType() (with the parentheses that indicate that it is a method) in the docs, as it belongs to the HTMLMediaElement interface. Linking to the page is either done with the interface prefix using \{{domxref('HTMLMediaElement.canPlayType()')}}, or without the prefix using \{{domxref('HTMLMediaElement.canPlayType', 'canPlayType()')}} when the context is obvious and unambiguous. The parentheses should always be included.

+ +

Parameters

+ +
TextTrack addTextTrack(TextTrackKind kind,
+                       optional DOMString label = "",
+                       optional DOMString language = "");
+ +

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 '?' means that the null value is valid.) If marked optional, 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 ('=').

+ +

Type of the return value

+ +
DOMString canPlayType(DOMString type);
+ +

The return value type is indicated first inside the parentheses — in the above case the value is an object of type DOMString. if followed by a question mark ('?'), a value of null can be returned too, and the documentation must explain when this may happen. If no question mark is present, like here,  the return value can't be null.

+ +

The keyword void means that there is no return value. It is not a return value type. If the WebIDL entry reads void, the Return value section in the docs should contain only a simple None.

+ +

Throwing exceptions

+ +
[Throws]
+   void fastSeek(double time);
+ +

Some methods can throw exceptions. This is marked using the [Throws] annotation. When this happens, the Syntax section of the method page must 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.

+ +

Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. Trying to set an illegal enumerated value (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.

+ +

Have a look at one of these Exceptions sections.

+ +

Availability in workers

+ +

Individual method availability in workers is also found in the WebIDL. For a method, the default is the same availability as the interface (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the partial interface it is defined it.

+ +

For the documentation, the sub-page must contain a sentence indicating if it is available in Web workers, right before the Syntax section.

+ +

Preferences

+ +
+

Note: this information is specific to Gecko and should only be used in the Browser compatibility section.

+
+ +

In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.

+ +
[Pref="media.webvtt.enabled"]
+   TextTrack addTextTrack(TextTrackKind kind,
+                          optional DOMString label = "",
+                          optional DOMString language = "");
+ +

Here media.webvtt.enabled controls the addTextTrack() method.

+ +
+

Note: The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)

+
+ +

 

+ +

Special methods

+ +

Some methods are not listed as regular methods in WebIDL but instead as special keywords, which translate to specific standard JavaScript methods.

+ +

toString() and toJSON()

+ +

A stringifier is mapped to toString() and defined as:

+ +
stringifier;
+ +

The toString() method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Range.toString()")}})

+ +

A jsonifier is mapped to toJSON() and defined as:

+ +
jsonifier; // Gecko version
+serializer; // Standard version
+
+ +

The toJSON() method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Performance.toJSON()")}})

+ +
+

Note: the WebIDL specification uses serializer instead of jsonifier. This is not used in Gecko — only the non-standard likely early proposal jsonifier is found in mozilla-central.

+
+ +

 

+ +

Iterator-like methods

+ +

An interface may be defined as iterable, meaning that it will have the following methods: entries(), keys(), values() and forEach(). They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface.

+ +

There are two kinds of iteration possible: the value iterator and the pair iterator.

+ +

Value iterator

+ +
iterable<valueType>
+ +

The iterator will iterate over values of type valueType. The generated methods will be:

+ + + +

Such an iterator allows to use the syntax for (var p in object) as a shorthand of for (var p in object.entries()). We add a sentence about it in the interface description.

+ +
+

Note: the value pairs to iterate over can be defined in two different ways:

+ +
    +
  1. Outside the webidl file, in the prose accompanying it. Such a prose is in the spec and usually starts with: "The values to iterate over…".
    2. +
  2. In the webidl file, implicitly, if the interface supports indexed properties, that is when the interface has a getter methods with a parameter of type unsigned long.
    3. +
+
+ +

Pair iterator

+ +
iterable<keyType, valueType>
+ +

The iterator will iterate over values of type valueType, with keys of type keyType. The generated methods will be:

+ + + +

Such an iterator allows to use the syntax for (var p in object) as a shorthand of for (var p in object.entries()). We add a sentence about it in the interface description. E.g. {{domxref('FormData')}}.

+ +
+

Note: the value pairs to iterate over are not defined in the webidl file, but in the prose accompanying it. Such a prose is in the spec and usually starts with: "The value pairs to iterate over…"
+ E.g, for {{domxref('FormData')}} you find in the spec: "The value pairs to iterate over are the entries with the key being the name and the value the value. "

+
+ +

Set-like methods

+ +

An interface may be defined as set-like, meaning that it represents an ordered set of values will have the following methods: entries(), keys(),  values(), forEach(), and has() (it also has the size 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 readonly or not. If not read-only, the methods to modify the set are also implemented: add(), clear(), and delete().

+ +
setlike<valueType>
+ +

The generated properties will be:

+ + + +

In the case, the set-like declaration is not prefixed by read-only, the following methods are also generated:

+ + + +

Such an set interface also allows to use the syntax for (var p in object) as a shorthand of for (var p in object.entries()). We add a sentence about it in the interface description. E.g. {{domxref('FontFaceSet')}}.

+ +

 

+ +

Constructors

+ +

Constructors are a little bit hidden in WebIDL: they are listed as annotations of the main interface.

+ +

Unnamed constructors

+ +

This is the most common case for constructors. The constructor of a given interface A, can be used as a = new A(parameters);

+ +
 [Constructor, Func="MessageChannel::Enabled",
+  Exposed=(Window,Worker)]
+    interface MessageChannel {…};
+ +

A constructor with the same interface is defined using the Constructor 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 Web/API/MessageChannel/MessageChannel and the title MessageChannel().

+ +

Another example of an unnamed constructor, with parameters:

+ +
[Constructor(DOMString type, optional MessageEventInit eventInitDict),
+ Exposed=(Window,Worker,System)]
+   interface MessageEvent : Event {…};
+ +

There can also be several unnamed constructors, differing by their parameter lists. All syntax is documented in one single sub-page.

+ +
[Constructor(DOMString url, URL base),
+ Constructor(DOMString url, optional DOMString base),
+ Exposed=(Window,Worker)]
+    interface URL {};
+ +

Named constructors

+ +
[NamedConstructor=Image(optional unsigned long width, optional unsigned long height)]
+    interface HTMLImageElement : HTMLElement {…
+ +

A named constructor is a constructor that has a different name than that of its interface. For example new Image(…) creates a new HTMLImageElement object. They are defined in the WebIDL using the NamedConstructor annotation on the interface, followed by the name of the constructor after the equality sign ('=') and the parameter inside the parenthesis, in the same format as you'll see for methods.

+ +

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.

+ +

Availability in workers

+ +

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.

+ +

Preferences

+ +

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.

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 +--- +
{{MDNSidebar}}
+ +

MDN 的学习区是我们给新手开发者介绍 Web 概念的大本营。因为它的内容主要面对初学者，这是你分享知识，帮助新手逐渐了解 Web 的绝佳地点。确保新手开发者能够跟上这里的内容是很重要的，所以我们格外重视学习区。

+ +

这篇文章解释了如何给学习区写文章。

+ +

如何写学习社区的文章

+ +

要开始贡献你的知识，只需点击绿色大按钮，然后按照下面的五个步骤。如果你想找点子，请看一下我们的团队 Trello ！

+ +
写一篇新的学习文章 + +
+
+ +

这篇文章可能不会在正确的地方出现，但至少是在MDN上。如果你需要找人谈谈把它搬到正确的地方，请联系我们。

+ +

第一步：写两行

+ +

你文章的第一句话需要总结一下你将要涉及的主题，第二句话应该更详细地介绍你要放在文章中的内容（项目）。例如：

+ +
+

 {{glossary("HTML")}} 文件包含的结构和内容, {{Glossary("CSS")}}以及其他主要的Web技术，使内容看起来像你想要的那样。在本文中，我们将介绍这项技术是如何工作的，以及如何编写你自己的基本示例。

+
+ +

注意示例如何简要说明CSS是用于样式化页面的核心Web技术。 这足以使读者很好地了解本文所涵盖的内容。

+ +

因为学习区域的文章主要是针对初学者的，所以每篇文章都应该涵盖一个简单的主题，以免给读者带来太多的新信息。如果你不能在一句话中总结这篇文章，那么你可能在一篇文章中做得太多了!

+ +

第二步：添加一个顶部框

+ +

然后添加一个顶框，以帮助读者了解他们在学习过程中的位置。 这是“了解URL及其结构 ”顶部框的示例。 您可以在编写自己的文章时将其用作模型。

+ + + + + + + + + + + + +
必要条件:您首先必须清楚Internet的工作方式，Web服务器是什么，与Web链接背后的所有概念。
目标:您将了解什么是URL以及它如何在Web上工作
+ +
+
必要条件
+
读者首先必须知道什么东西才能读懂你的一篇文章?在有可能的状况下，让每一个前提条件链接到另一篇涵盖概念的学习领域的一篇文章(除了您写的是是一篇完全不需要首先先验知识的无比基础的文章)。
+
目标
+
这一章节粗略说明了您的读者在阅读学习这篇文章的过程中会学到（并学会）什么。这与一行程序有点不同;一行代码总结了文章的主题，而目标部分专门列出了读者在阅读文章过程中所希望完成的全部内容。
+
+ +
+

注意:要创建此表，您可以复制并粘贴上面的示例表，或者使用MDN的编辑器 台式工具。如果选择使用table工具，则需要在默认的standard-table类之外特别添加learn-box CSS类。为此，当您创建或编辑表的属性时，请转到“Advanced”面板并将样式表类字段设置为“standard-table learn-box”。

+
+ +

第三步:写一个完整的描述

+ +

接下来，写一个更长的描述，提供更全面的文章概述，突出最重要的概念。不要忘记解释为什么读者要花时间来学习这个主题并阅读你的文章！

+ +

第四步：更深一步

+ +
当你完成了所有这些，你终于可以深入到主题。你可以根据自己的喜好来组织文章的这一部分(尽管您能够随时咨询我们的 设计指南)。这是你闪耀的机会!详细解释你要写的主题。提供指向完整参考文档的链接，详细解释该技术的工作原理，提供语法和用法细节，等等。由你决定 + +
+
+ + + +

看一看我们的函数的前几节可重用代码块文章 ，有一些很好的描述部分。

+ +

第五步:提供“主动学习”材料

+ +

为了阐明本文并帮助读者更好地理解他们正在学习的内容，请确保提供练习、教程和需要完成的任务。通过让他们积极地、实际地使用和试验你文章中解释的概念，你可以帮助他们将信息“锁定”在大脑中。

+ +

您可以选择在页面中直接包含这些示例作为 实时实例,或者直接链接到它们。 （如果它们不能作为实时实例。） 如果你有兴趣帮助创造这些有价值的东西 ，请参阅《创建一个交互式的练习来帮助学习网络》

+ +

如果您不能提供到现有活动学习材料的链接(您不知道或者没有时间创建它们)，那么您应该在文章中添加标记{{tag ("NeedsActiveLearning")}}。这样，其他贡献者就可以找到需要积极学习材料的文章，并可能帮助你找到它们。

+ +

看看《主动学习:选择不同的元素》进行现场互动学习练习或者《主动学习: 玩转范围》或者另一种不同风格的练习，要求它们在本地下载模板并按照提供的步骤更改

+ +

+ +

                                                                                         

+ +

第六步：查看文章，并放入学习区域导航菜单

+ +

在你写完你的文章后，让我们知道，这样我们可以看一看，做一个回顾，并提出改进建议 。再次看看我们的 联系方式 板块以寻找最好的联系方式。

+ +

完成文章的另一部分是把它放在学习区主导航菜单中。这个菜单是 LearnSidebar 宏生成的。 你需要特殊的权限来编辑，所以，再一次，让我们团队中的一个人把它添加进去。

+ +

您至少应该将其添加到您的页面中，这是通过在页面顶部的段落中添加宏调用\{{LearnSidebar}}来完成的。

+ + + +

推荐文章

+ +

您想做出贡献，但是您不知道该写什么?

+ +

学习社区维护了一个要写文章的Trello看板。随意挑选一个，然后开始去写吧！

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 +--- +
{{MDNSidebar}}
{{IncludeSubnav("/zh-CN/docs/MDN")}}{{draft("为了更好的将MDN的文档符合SEO要求，我们在此提供了一些提升MDN搜索引擎优化的技术建议。本文是由MDN的志愿者们整理翻译完成的。 ")}}
+ +

本指南涵盖了我们对内容的基础要求、推荐和实践参考，以确保搜索引擎可以更好的对我们的内容进行分类和索引，同时确保用户可以轻松地获取到所需的内容。

+ +

简介

+ +

MDN写作的首要目标是向开发者们阐明和指导开放的Web技术，以便他们能够快速找到他们想要的东西，或者为了优化自己的代码而寻找需要的细节，因此我们在MDN提供的内容可以被更容易的搜索到就非常重要了。

+ +

由于绝大部分读者是通过搜索引擎搜索找到MDN的内容的，那么作为作者，我们就要始终记得内容对搜索引擎的友好程度这件事。为了对搜索引擎友好，我们撰写了SEO指引的内容以帮助MDN的作者和编辑们能够确保MDN上的每篇内容的设计、撰写和标记方式都符合SEO规范，以获得搜索引擎更好的收录索引和展现。

+ +

本文档的状态

+ +

目前我们刚开始了改进MDN文档在搜索引擎优化({{Glossary("SEO")}}) 的长期项目的初期阶段。 我们最近完成了一系列小规模实验来测试能提升SEO的方法，并确定哪些内容能够作为SEO指南提供给我们的贡献者们。

+ +

我们仍在编辑并更新本文，同时将其他贡献者提供的参考纳入到我们的发现中。

+ +

SEO 要点

+ +

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.

+ + + +

避免过于相似的内容页面

+ +

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 width and height, 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.

+ +

Understandably, writers confronted with two related properties like width and height (or any other set of functionally related features) are tempted to write the article on width, then copy that article and paste it into the one on height, replacing a few words. Done!

+ +

Unfortunately, the result is two pages that, as far as search engines are concerned, may as well be the same thing.

+ +

It's important, then, to ensure that every page has its own content. Here are some suggestions to help you accomplish that:

+ + + +

The easiest way to avoid being overly similar is of course to write each article from scratch if time allows.

+ +

避免页面内容过短

+ +

如果文章过短，那么搜索引擎可能会难以甚至无法对其建立关键字索引。一般来说，文章的主体内容应该至少包含 250-300 个单词。但是也不要对内容确实很少的文章进行刻意的扩充，在可能的情况下尽量遵守该指导原则即可。

+ + + +

See also

+ + diff --git "a/files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" "b/files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" new file mode 100644 index 0000000000..8c0513d654 --- /dev/null +++ "b/files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" @@ -0,0 +1,30 @@ +--- +title: 如何添加或更新浏览器兼容性数据 +slug: MDN/Contribute/Howto/如何添加或更新浏览器兼容性数据 +translation_of: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data +--- +
{{MDNSidebar}}

如果你有浏览器在兼容Web特性方面的信息 —— 或者有意愿并有能力做一些这方面的研究和/或实验 —— 你可以帮助更新MDN的浏览器兼容性数据库（BCD）。

+ + + +
+
哪些地方需要做？
+
+

在MDN上你有这几种方法可以帮助改进浏览器兼容性方面的信息：

+ +
    +
  • 添加尚未收录在BCD仓库内的网页特性数据
    • +
  • 依据浏览器新版本的变更内容、现有数据中的更正错误，或者某项技术的特性之最新变更等信息来更新现有数据
    • +
  • 提交 pull requests 到 BCD issues filed on Github.
    • +
+
+
做这个任务你需要知道哪些知识？
+
做这个任务需要哪些步骤？
+
欲了解如何更新在GitHub上的组成BCD仓库的 JSON 文件的详细信息，请参见兼容性表格页面。如要了解我们特别寻求帮助的问题列表，请到 Github issues with the "Help Wanted" tag.
+
 
+
 
+
diff --git "a/files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" "b/files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" new file mode 100644 index 0000000000..91b8a8640d --- /dev/null +++ "b/files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/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 +--- +
{{MDNSidebar}}

动态的内容对于学习 Web 来说是重要的。 她能让学习的人更加积极主动。 这可以是练习，实例，任务，评价等等。总之，任何有助于学习理解的东西都行。

+ +

这儿还没有能够直接创建动态的实例内容。但是一些第三方工具可以帮助你创建（如： JSFiddle，CodePen，Dabblet，等），你可以将其链接放在 MDN 文章中。另外，你可以使用 WebMaker 项目的 Thimble 来创造更加高级的内容。

+ +

目前，MDN 虽然没有能够轻易创建动态实例内容的工具。不过，如果你是工程师，可以使用当前 MDN 提供的功能创建自定义的主动学习内容，下面内容将告诉你如何操作。

+ +

MDN live samples

+ +

MDN 有一个非常炫酷的功能：live samples。她是一种可以将 MDN 页面内任何 HTML, CSS, Javascript 代码等效执行的机制。在使用她以前，你最好通读一下 Using the live sample system，这是我们关于她的完整文档。虽然她很容易使用，不过通过阅读文档，你会学到一些奇淫巧技。

+ +

有意思的是，将任何类型的工具或实例嵌入到 MDN 页面中都可以通过调教她轻松做到。

+ +

隐藏代码

+ +

通过实例创建主动学习内容的第一种方法是编辑要添加内容的页面。使用 Live Sample 功能创建内容，只构建你需要的功能，不要在乎代码的复杂度。当内容准备好之后，只需切换到编辑器视图，并用 class 为 hidden 的 {{HTMLElement('div')}} 来包围你的代码。这样代码就会隐藏，不过实例依然可以访问和显示。

+ +

看看这个简单的代码：

+ +
+

点击这个方块提供随机色，或者直接输入色值

+ + +{{EmbedLiveSample('hidden_code_example', 120, 120)}}
+ +

如果你使用 MDN 编辑器查看该页面代码，你会看到如下 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>
+ +

你可以在 the Canvas API page 查看更多高级例子。

+ +

外部代码

+ +

前面的例子在你想嵌入主动学习内容时是可行的。不过，如果你想要处理更加复杂的代码，这个 hidden 的 {{HTMLElement('div')}} 就比较麻烦。

+ +

另外种方案是将内容写入 MDN 页面，然后嵌入另一个页面中。为此，我们可以使用 {{TemplateLink("EmbedDistLiveSample")}} 替代{{TemplateLink("EmbedLiveSample")}} 。

+ +

我们学习配置这个模拟远程代码嵌入的实例：

+ +
+

点击这个方块提供随机色，或者直接输入色值

+{{EmbedLiveSample('The_example', 120, 120, '', 'MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example')}}
+ +

这下如果你继续使用 MDN 编辑器查看页面源码，将看不到隐藏元素。如果你需要看，则需要前往这个页面地址。

+ +

你可以在 HTML 表单教程中查看更多高级例子，那里可以使用表单尝试。

diff --git "a/files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" "b/files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" new file mode 100644 index 0000000000..08693b3ff1 --- /dev/null +++ "b/files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" @@ -0,0 +1,53 @@ +--- +title: 如何成为一名测试版试验员 +slug: MDN/Contribute/Howto/成为一名测试版试验员 +tags: + - MDN Meta +translation_of: MDN/Contribute/Howto/Be_a_beta_tester +--- +
{{MDNSidebar}}
+ +

随着MDN Kuma平台的开发人员不断地对站点进行更改，我们为那些选择成为测试版测试人员提供对这些新特性的早期访问。与任何“beta”测试一样，在某些情况下，一些功能可能无法正常工作。

+ +

参与beta测试

+ +
    +
  1. 登录MDN，在顶部导航栏点击你的用户名。
    + Shows location of the user's profile link in the top navigation
    + 随后跳转到你的资料页。
    2. +
  2. 点击编辑按钮。
    + Shows location of the button to edit a user's profile (which may vary depending on window dimensions
    + 随后在编辑模式下打开资料页。
    3. +
  3. 勾选复选框成为 Beta 测试者。
    + Shows the location of the Beta Tester checkbox
    4. +
  4. 点击资料页底部的发布按钮
    + Shows the location of the Publish button on a user's profile page
    5. +
+ +

退出Beta测试

+ +
    +
  1. 登录MDN，在顶部导航栏点击你的用户名。随后会跳转到你的资料页。
    2. +
  2. 点击编辑按钮。随后在编辑模式下打开资料页。
    3. +
  3. 取消 Beta 测试者的复选框
    4. +
  4. 点击发布按钮.
    5. +
+ +

对beta测试给予反馈

+ +

你有两种方式可以对 beta 测试进行反馈:

+ + + +
    +
  1. 如果你还没有账号，创建一个 Bugzilla 账号.
    2. +
  2. 打开 bug report in Bugzilla for MDN.
    3. +
  3. 在“摘要”字段中包含 “beta” 一词，帮助 MDN开发人员过滤和区分传入的 bug。.
    4. +
  4. 尽你所能填写 bug 报告. 越详细越好.
    5. +
  5. 点击提交按钮.
    6. +
+ +

 

-- cgit v1.2.3-54-g00ecf