initial commit

2 files changed, 268 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/channel_messaging_api/index.html b/files/zh-cn/web/api/channel_messaging_api/index.html
new file mode 100644
index 0000000000..6e7591d531
--- /dev/null
+++ b/files/zh-cn/web/api/channel_messaging_api/index.html
@@ -0,0 +1,89 @@
+---
+title: Channel Messaging API
+slug: Web/API/Channel_Messaging_API
+translation_of: Web/API/Channel_Messaging_API
+---
+<p>{{DefaultAPISidebar("Channel Messaging API")}}</p>
+
+<p class="summary"><strong>Channel Messaging API </strong>允许两个不同的脚本运行在同一个文档的不同浏览器上下文（比如两个 iframe，或者文档主体和一个 iframe，使用 {{domxref("SharedWorker")}} 的两个文档，或者两个 worker）来直接通讯，在每端使用一个端口（port）通过双向频道（channel）向彼此传递消息。</p>
+
+<p>{{AvailableInWorkers}}</p>
+
+<h2 id="Channel_通信的概念和用法">Channel 通信的概念和用法</h2>
+
+<p>使用 {{domxref("MessageChannel.MessageChannel", "MessageChannel()")}} 构造函数来创建通讯信道。一旦创建，信道的两个端口即可通过 {{domxref("MessageChannel.port1")}} 和 {{domxref("MessageChannel.port2")}} 属性进行访问（都会返回 {{domxref("MessagePort")}}  对象）。创建信道的应用程序使用 <code>port1</code>，在另一端的程序使用 <code>port2</code> —— 你向 <code>port2</code> 发送信息，然后携带 2 个参数（需要传递的消息，要传递所有权的对象，在这里是 port 自身）调用 {{domxref("window.postMessage")}} 方法将端口信息传递到另一个浏览器上下文。</p>
+
+<p>当这些可传递的对象被传递后，他们就从之前所属的上下文中消失了。比如一个 port，一旦被发送，在原本的上下文中就再也不可用了。注意当前仅有 {{domxref("ArrayBuffer")}} 和 {{domxref("MessagePort")}} 对象可以被发送。</p>
+
+<p>另一个浏览器上下文可以使用 {{domxref("MessagePort.onmessage")}} 监听信息，并使用事件的 <code>data</code> 属性获取消息内容。你可以通过 {{domxref("MessagePort.postMessage")}} 向原来的文档发送应答消息。</p>
+
+<p>当你想要停止通过信道发送消息时，你可以调用来关闭 {{domxref("MessagePort.close")}} 端口。</p>
+
+<p>更多使用这个 API 的资料参见：<a href="/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging">Using channel messaging</a> 。</p>
+
+<h2 id="Channel_通信接口">Channel 通信接口</h2>
+
+<dl>
+ <dt>{{domxref("MessageChannel")}}</dt>
+ <dd>创建一个新的发送消息的信道。</dd>
+ <dt>{{domxref("MessagePort")}}</dt>
+ <dd>控制消息信道的端口，允许从一个端口发送消息，并监听另一端消息的到来。</dd>
+ <dt>{{domxref("PortCollection")}}</dt>
+ <dd><code>MessagePort</code> 数组，一种同时向多个端口广播消息的实验性解决方案。</dd>
+</dl>
+
+<h2 id="例子">例子</h2>
+
+<ul>
+ <li>我们在 Github 上发布了 <a href="https://github.com/mdn/dom-examples/tree/master/channel-messaging-basic">channel messaging basic demo</a>，在<a href="http://mdn.github.io/dom-examples/channel-messaging-basic/">这里</a>直接尝试。这个例子展示了一次页面和嵌入 {{htmlelement("iframe")}} 间的真实而简易的消息传递。</li>
+ <li>你也可以参考 <a href="https://github.com/mdn/dom-examples/tree/master/channel-messaging-multimessage">多个消息 demo</a> (<a href="http://mdn.github.io/dom-examples/channel-messaging-multimessage/">在线演示</a>)。这个例子展示了稍微复杂些的设置，可以在主页面和 IFrame 之间传递多条消息。</li>
+</ul>
+
+<h2 id="规格">规格</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">规格</th>
+   <th scope="col">状态</th>
+   <th scope="col">补充</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('HTML WHATWG', 'web-messaging.html#channel-messaging', 'Channel messaging')}}</td>
+   <td>{{Spec2('HTML WHATWG')}}</td>
+   <td> </td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="浏览器兼容性">浏览器兼容性</h2>
+
+<div>
+<h3 id="MessageChannel"><code>MessageChannel</code></h3>
+
+<div>
+
+
+<p>{{Compat("api.MessageChannel", 0)}}</p>
+
+<h3 id="MessagePort"><code>MessagePort</code></h3>
+
+<div>
+<div class="hidden">The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.MessagePort", 0)}}</p>
+</div>
+</div>
+</div>
+
+<h2 id="参考">参考</h2>
+
+<ul>
+ <li><a href="/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging">Using channel messaging</a></li>
+ <li><a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers API</a></li>
+ <li><a href="/en-US/docs/Web/API/Broadcast_Channel_API">Broadcast Channel API</a></li>
+</ul>
+
+<p>
+ <audio style="display: none;"> </audio>
+</p>
diff --git a/files/zh-cn/web/api/channel_messaging_api/使用_channel_messaging/index.html b/files/zh-cn/web/api/channel_messaging_api/使用_channel_messaging/index.html
new file mode 100644
index 0000000000..8ddfa8df8e
--- /dev/null
+++ b/files/zh-cn/web/api/channel_messaging_api/使用_channel_messaging/index.html
@@ -0,0 +1,179 @@
+---
+title: 使用 channel messaging
+slug: Web/API/Channel_Messaging_API/使用_channel_messaging
+tags:
+  - API
+  - Channel messaging
+  - HTML5
+  - MessageChannel
+  - MessagePort
+  - 指南
+translation_of: Web/API/Channel_Messaging_API/Using_channel_messaging
+---
+<p>{{DefaultAPISidebar("Channel Messaging API")}}</p>
+
+<p><span class="seoSummary"><a href="/en-US/docs/Web/API/Channel_Messaging_API">Channel Messaging API</a> 可以让运行在不同浏览器上下文中的独立脚本，连接到同一份文档（比如：两个 IFrame, 或者主文档和一个 IFrame, 或者使用同一个 {{domxref("SharedWorker")}} 的两份文档），并直接通信，通过每端一个 port 的双向频道（或管道）在两者之间传递消息。</span></p>
+
+<p>在文本中，我们将探索这项技术的基本用法。</p>
+
+<p>{{AvailableInWorkers}}</p>
+
+<h2 id="用例">用例</h2>
+
+<p>Channel messaging 在这样的场景中特别有用：假如你有一个社交站点，它在主界面中通过 IFrame 内嵌了来自其他站点的内容，比如游戏，通讯录或者一个音乐播放器，有着个性化的音乐选择。当这些内容作为独立的单元时，一切都是 OK 的，但是当你想在主站点和 IFrame, 或者在不同的 IFrame 中交互时，困难就出现了。举例来说，假如你想从主站点向通讯录里添加一个联系人；或者想从游戏里，把最高分加入到个人资料；又或者，希望从音频播放器里，添加新的背景音乐到游戏中？因为浏览器使用的安全模型，使用传统的 web 技术来做这些事并不容易。你必须去考虑不同的源之间彼此是否信任，以及如何传递消息。</p>
+
+<p>换个角度说，Message Channels 可以提供一个安全的通道让你在不同的浏览器上下文间传递数据。</p>
+
+<div class="note">
+<p><strong>提示</strong>: 要了解更多信息和思考，规范的 <a href="https://html.spec.whatwg.org/multipage/comms.html#ports-as-the-basis-of-an-object-capability-model-on-the-web">Ports 作为 Web 上一个对象兼容模型的基础</a> 章节值得一读。</p>
+</div>
+
+<h2 id="简单的例子">简单的例子</h2>
+
+<p>为了帮助你开始，我们在 Github 上传了一些 demo. 一开始可以先看我们的 <a href="https://github.com/mdn/dom-examples/tree/master/channel-messaging-basic">channel messaging 基本示例</a> (<a href="https://mdn.github.io/dom-examples/channel-messaging-basic/">也可以在线运行</a>)，它展示了一个非常简单的消息传递，发生在页面和内嵌 {{htmlelement("iframe")}} 之间。 </p>
+
+<p>然后，看看我们的 <a href="https://github.com/mdn/dom-examples/tree/master/channel-messaging-multimessage">multimessaging demo</a> (<a href="https://mdn.github.io/dom-examples/channel-messaging-multimessage/">在线运行</a>)，它展示了一个稍微复杂一点的例子，可以在主页面和 IFrame 之间发送多条消息。</p>
+
+<p>本文中，我们重点说后面的这个例子。它看起来像是这样：</p>
+
+<p><img alt="" src="https://mdn.mozillademos.org/files/10075/channel-messaging-demo.png" style="display: block; height: 744px; margin: 0px auto; width: 690px;"></p>
+
+<h2 id="创建_channel">创建 channel</h2>
+
+<p>在例子的主页面，我们有一个简单的表单，内含一个文本输入框，用来输入要发送到 {{htmlelement("iframe")}} 的消息。我们还有一个段落，我们在稍后将会用它来显示 {{htmlelement("iframe")}} 回传回来的确认消息。</p>
+
+<pre class="brush: js notranslate">var input = document.getElementById('message-input');
+var output = document.getElementById('message-output');
+var button = document.querySelector('button');
+var iframe = document.querySelector('iframe');
+
+var channel = new MessageChannel();
+var port1 = channel.port1;
+
+// 等待 iframe 加载
+iframe.addEventListener("load", onLoad);
+
+function onLoad() {
+  // 监听按钮点击
+  button.addEventListener('click', onClick);
+
+  // 在 port1 监听消息
+  port1.onmessage = onMessage;
+
+  // 把 port2 传给 iframe
+  iframe.contentWindow.postMessage('init', '*', [channel.port2]);
+}
+
+// 当按钮点击时，在 port1 上发送一个消息
+function onClick(e) {
+  e.preventDefault();
+  port1.postMessage(input.value);
+}
+
+// 处理 port1 收到的消息
+function onMessage(e) {
+  output.innerHTML = e.data;
+  input.value = '';
+}</pre>
+
+<p>我们从使用 {{domxref( "MessageChannel.MessageChannel","MessageChannel()")}} 构造函数创建了一个 message channel 开始。</p>
+
+<p>当 IFrame 加载完成，我们在按钮上注册了<code>onclick</code> 事件处理函数，在 {{domxref("MessageChannel.port1")}} 注册了 <code>onmessage</code> 事件处理函数。最后，我们使用 {{domxref("window.postMessage")}} 方法把 {{domxref("MessageChannel.port2")}} 传给 IFrame.</p>
+
+<p>让我们来了解一下 <code>iframe.contentWindow.postMessage</code> 更多的工作细节。它接受三个参数：</p>
+
+<ol>
+ <li>被发送的消息。对于一开始的 port 传递，这个消息可以是个空字符串，但是在例子里，我们传了 <code>'init'</code>.</li>
+ <li>消息将被发送到的源（origin）。 <code>*</code> 意思是 "任何源".</li>
+ <li>一个对象，它的所有权会被传给接受的浏览器上下文。在本例中，我们把 {{domxref("MessageChannel.port2")}} 传给了 IFrame, 然后它就可以用于与主页面通信了。</li>
+</ol>
+
+<p>当我们的按钮被点击时，我们阻止了默认的表单提交，然后把输入到输入框里的内容通过 {{domxref("MessageChannel")}} 发送给 IFrame.</p>
+
+<h2 id="在_IFrame_里接收_port_和消息">在 IFrame 里接收 port 和消息</h2>
+
+<p>在 IFrame 里，我们有下面的 JavaScript:</p>
+
+<pre class="brush: js notranslate">var list = document.querySelector('ul');
+var port2;
+
+// 监听初始的 port 传递消息
+window.addEventListener('message', initPort);
+
+// 设置传过来的 port
+function initPort(e) {
+  port2 = e.ports[0];
+  port2.onmessage = onMessage;
+}
+
+// 处理 port2 收到的消息
+function onMessage(e) {
+  var listItem = document.createElement('li');
+  listItem.textContent = e.data;
+  list.appendChild(listItem);
+  port2.postMessage('Message received by IFrame: "' + e.data + '"');
+}
+</pre>
+
+<p>当收到从主页面通过 {{domxref("window.postMessage")}} 方法传来的初始化消息时，我们运行 <code>initPort</code> 函数。它会保存传来的 port, 并且注册了一个 <font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">onmessage</span></font> 事件处理器，每当有消息通过我们的 {{domxref("MessageChannel")}} 传来时，它都会被调用。</p>
+
+<p>当收到从主页面发来的消息时，我们创建一个列表项，并把它插入到这个无序列表中，然后把这个列表项的 {{domxref("Node.textContent","textContent")}} 设置为事件的 <code>data</code> 属性（里面包含真正的消息）。</p>
+
+<p>然后，我们通过在初始化时传到 IFrame 的 {{domxref("MessageChannel.port2")}} 上调用 {{domxref("MessagePort.postMessage")}} 来使用 message channel 发送一个确认消息给主页面。</p>
+
+<h2 id="在主页面中接收确认消息">在主页面中接收确认消息</h2>
+
+<p>回到主页面，我们来一起看看 onmessage 事件处理函数。</p>
+
+<pre class="brush: js notranslate">// 处理 port1 上收到的消息
+function onMessage(e) {
+  output.innerHTML = e.data;
+  input.value = '';
+}</pre>
+
+<p>当收到从 IFrame 发来的确认消息，说明原始消息被成功接收时，它把确认消息输出到段落中，并清空输入框，为输入下一个要被发送的消息做准备。</p>
+
+<h2 id="规范">规范</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('HTML WHATWG', 'web-messaging.html#channel-messaging', 'Channel messaging')}}</td>
+   <td>{{Spec2('HTML WHATWG')}}</td>
+   <td></td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="浏览器兼容性">浏览器兼容性</h2>
+
+<div>
+<h3 id="MessageChannel"><code>MessageChannel</code></h3>
+
+<div>
+
+
+<p>{{Compat("api.MessageChannel", 0)}}</p>
+
+<h3 id="MessagePort"><code>MessagePort</code></h3>
+
+<div>
+<div class="hidden">The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.MessagePort", 0)}}</p>
+</div>
+</div>
+</div>
+
+<h2 id="参见">参见</h2>
+
+<ul>
+ <li><a href="/en-US/docs/Web/API/Channel_Messaging_API">Channel Messaging API</a></li>
+ <li><a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers API</a></li>
+ <li><a href="/en-US/docs/Web/API/Broadcast_Channel_API">Broadcast Channel API</a></li>
+</ul>