diff options
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html')
| -rw-r--r-- | files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html b/files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html new file mode 100644 index 0000000000..505ba9a16a --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html @@ -0,0 +1,326 @@ +--- +title: 与本地应用通信 +slug: Mozilla/Add-ons/WebExtensions/Native_messaging +translation_of: Mozilla/Add-ons/WebExtensions/Native_messaging +--- +<div>{{AddonSidebar}}</div> + +<p>Native messaging 可以让 extension 与安装在用户计算机上的原生应用交换信息。 原生应用仅需给 extension 提供服务，而无需在网页中可访问。 一个常见的例子是密码管理器: 原生应用负责存储和加密你的密码，并且和 extension 通信来填充网页中的表单字段。Native messaging 可以让 extension 拥有那些WebExtensions APIs 所没有的功能，比如访问某些特定的硬件。</p> + +<p>原生应用的安装与管理并不是在浏览器当中的： 它应该是使用操作系统进行安装，和其他的原生应用一样。然后你需要将你的原生应用安装在指定位置，并提供一个清单。清单中描述了浏览器如何连接到你的原生应用。</p> + +<p>extension 必须在 manifest.json 中获得"nativeMessaging" <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>。 同时，原生应用也需要在其清单中的 "allowed_extensions" 字段中包含 extension 的ID来表示允许该 extension 与自己进行通信。</p> + +<p>经过上述操作，extension 就可以通过 {{WebExtAPIRef("runtime")}} API 与原生应用进行JSON数据通信了。原生应用可以通过标准输入/输出来接受/返回数据与 extension 通信。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13833/native-messaging.png" style="display: block; height: 548px; margin-left: auto; margin-right: auto; width: 672px;"></p> + +<p>和 Chrome 相比，WebExtensions 所支持的 native messaging 有2个主要区别：</p> + +<ul> + <li>在 WebExtensions 中，原生应用的清单中的 "allowed_extensions" 字段是一个由 extension ID 组成的数组，而在 Chrome 中，清单中的 "allowed_origins" 字段是一个由 "chrome-extension" URLs 组成的数组</li> + <li>原生应用清单的存储位置不一样</li> +</ul> + +<p>Github 中的 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples 仓库</a>有一个<a href="https://github.com/mdn/webextensions-examples/tree/master/native-messaging">完整的关于 native messaging 的例子</a>，文章中的大部分代码片段均出于此。</p> + +<h2 id="安装">安装</h2> + +<h3 id="Extension_的_manifest.json">Extension 的 manifest.json</h3> + +<p>如果你想让你的 extension 与原生应用进行通信，你需要：</p> + +<ul> + <li>你必须在 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 中申请 "nativeMessaging" 的 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a> 。</li> + <li>你可能需要明确自己 extension 的ID（因为在原生应用的清单中，extension ID将会在被用来识别此 extension 是否被允许与原生应用通信）</li> +</ul> + +<p>这有一个 manifest.json 的例子:</p> + +<pre class="brush: json">{ + + "description": "Native messaging example extension", + "manifest_version": 2, + "name": "Native messaging example", + "version": "1.0", + "icons": { + "48": "icons/message.svg" + }, + + "applications": { + "gecko": { + "id": "ping_pong@example.org", + "strict_min_version": "50.0" + } + }, + + "background": { + "scripts": ["background.js"] + }, + + "browser_action": { + "default_icon": "icons/message.svg" + }, + + "permissions": ["nativeMessaging"] + +}</pre> + +<h3 id="原生应用清单">原生应用清单</h3> + +<p>原生应用清单描述了浏览器如何与原生应用进行连接。</p> + +<p>原生应用清单需要与原生应用一起安装，浏览器仅会查阅清单而不会安装或管理原生应用。因此，何时采用何种方式来安装或更新这些文件的安全模型比起使用WebExtensions APIs 更像原生应用 。（我也搞不懂这句啥意思，原文：Thus the security model for when and how these files are installed and updated is much more like that for native applications than that for extensions using WebExtension APIs.）</p> + +<p>关于原生应用清单的详细语法和路径规则，可参考 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests">原生应用清单</a>。</p> + +<blockquote> +<div class="warning"> +<p>除清单外，原生应用还<strong>必需</strong>配置路径规则，你可以参考 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests">原生应用清单 </a>来配置路径。</p> +</div> +</blockquote> + +<p>这有一个例子，是关于 "ping_pong" 原生应用的清单：</p> + +<pre class="brush: json">{ + "name": "ping_pong", + "description": "Example host for native messaging", + "path": "/path/to/native-messaging/app/ping_pong.py", + "type": "stdio", + "allowed_extensions": [ "ping_pong@example.org" ] +}</pre> + +<p>上面的清单代表：</p> + +<ul> + <li>这个原生应用允许ID为 "ping_pong@example.org" 的 extension 连接，并通过{{WebExtAPIRef("runtime")}} API来传入信息</li> + <li>这个原生应用本身存放在本机的 "/path/to/native-messaging/app/ping_pong.py" 中</li> +</ul> + +<div class="note"> +<p><strong>对于Windows</strong>: 在上面的例子中，原生应用是一个Python脚本，它在Windows下可能是无法运行的。一个代替方案是提供一个 .bat 文件，并且在清单中指向这个 .bat 文件：</p> + +<pre class="brush: json">{ + "name": "ping_pong", + "description": "Example host for native messaging", + "path": "c:\\path\\to\\native-messaging\\app\\ping_pong_win.bat", + "type": "stdio", + "allowed_extensions": [ "ping_pong@example.org" ] +}</pre> + +<p>在 .bat 文件中调用 Python 脚本：</p> + +<pre class="brush: bash">@echo off + +python -u "c:\\path\\to\\native-messaging\\app\\ping_pong.py"</pre> + +<p> </p> +</div> + +<ul> +</ul> + +<h2 id="交换信息">交换信息</h2> + +<p>根据上面的配置，extension已经可以和原生应用交换JSON信息了。</p> + +<h3 id="Extension_端">Extension 端</h3> + +<p>你使用过 <a href="/zh-CN/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">messaging APIs</a> 与 content script 通信，与原生应用通信你应该非常熟悉，有2种方式：</p> + +<ul> + <li>基于连接的通信</li> + <li>无连接的通信（请求/响应 模式）</li> +</ul> + +<h4 id="基于连接的通信">基于连接的通信</h4> + +<p>在这种方式下，你需要调用 {{WebExtAPIRef("runtime.connectNative()")}} 并传入原生应用的名称（名称在原生应用清单中的 "name" 字段定义）。这个操作将会运行原生应用（如果它之前没在运行的话）并返回一个 {{WebExtAPIRef("runtime.Port")}} 。</p> + +<p>当原生应用启动后，它被会传入2个参数：</p> + +<ul> + <li>到原生应用清单的完整路径</li> + <li>（Firefox 55+）启动它的<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications"> extension ID</a></li> +</ul> + +<p>原生应用会一直保持运行，直到 extension 调用 <code>Port.disconnect()</code> 或连接它的记录被结束。</p> + +<p>使用 <code>Port</code> ，调用 <code>postMessage()</code> 传入一个JSON来发送消息，使用 <code>onMessage.addListener()</code> 来接收消息。</p> + +<p>下面是一个例子：background script 建立与 ping_pong 原生应用的链接，并监听原生应用发来的消息。每当browser action 点击时，发送一个 ping 的消息给原生应用。</p> + +<pre class="brush: js">/* +启动，连接 ping_pong 原生应用 +*/ +var port = browser.runtime.connectNative("ping_pong"); + +/* +监听从原生应用发来的消息 +*/ +port.onMessage.addListener((response) => { + console.log("Received: " + response); +}); + +/* +每当 browser action 被点击时，发送一条消息给原生应用 +*/ +browser.browserAction.onClicked.addListener(() => { + console.log("Sending: ping"); + port.postMessage("ping"); +});</pre> + +<h4 id="无连接的通信">无连接的通信</h4> + +<p>在这种模式下你需要调用 {{WebExtAPIRef("runtime.sendNativeMessage()")}} 传入如下参数：</p> + +<ul> + <li>原生应用的名字</li> + <li>要发送是JSON数据</li> + <li>（可选）一个回调函数</li> +</ul> + +<p>每个消息都会创建一个新的原生应用实例。当原生应用启动时会被传入2个参数：</p> + +<ul> + <li>到原生应用清单的完整路径</li> + <li>（Firefox 55+）启动它的<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications"> extension ID</a></li> +</ul> + +<p>原生应用发送的第一条消息将会被作为对 <code>sendNativeMessage()</code> 响应，将会被传入回调函数中。</p> + +<p>这有一个例子，对在上方的代码片段进行重写，改成使用 <code>runtime.sendNativeMessage()</code> 的方式：</p> + +<pre class="brush: js">function onResponse(response) { + console.log("Received " + response); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +/* +每当 browser action 被点击时，发送一条消息给原生应用 +*/ +browser.browserAction.onClicked.addListener(() => { + console.log("Sending: ping"); + var sending = browser.runtime.sendNativeMessage( + "ping_pong", + "ping"); + sending.then(onResponse, onError); +}); +</pre> + +<h3 id="原生应用端">原生应用端</h3> + +<p>在原生应用端，使用标准输入来接受消息，使用标准输出来发送消息。</p> + +<p>每条消息将会被序列化成UTF-8格式的JSON数据，并且在消息前面有一个32位的值来表示该条消息使用本地字节序的长度。</p> + +<p>发送给原生应用的单条消息最大是1MB，总消息不得超越4GB。</p> + +<p>下面是一个用 Python 写的原生应用例子。监听 extensions 发送的消息，如果消息是 ping，则回复 pong：</p> + +<pre class="brush: python">#!/usr/bin/python -u +# Note that running python with the `-u` flag is required on Windows, +# in order to ensure that stdin and stdout are opened in binary, rather +# than text, mode. + +import sys, json, struct + +# 从 stdin 读取解码消息 +def getMessage(): + rawLength = sys.stdin.read(4) + if len(rawLength) == 0: + sys.exit(0) + messageLength = struct.unpack('@I', rawLength)[0] + message = sys.stdin.read(messageLength) + return json.loads(message) + +# 为了能被传输，对给定的内容进行编码 +def encodeMessage(messageContent): + encodedContent = json.dumps(messageContent) + encodedLength = struct.pack('@I', len(encodedContent)) + return {'length': encodedLength, 'content': encodedContent} + +# 向 stdout 发送一个已编码的消息 +def sendMessage(encodedMessage): + sys.stdout.write(encodedMessage['length']) + sys.stdout.write(encodedMessage['content']) + sys.stdout.flush() + +while True: + receivedMessage = getMessage() + if (receivedMessage == "ping"): + sendMessage(encodeMessage("pong")) +</pre> + +<h2 id="关闭原生应用">关闭原生应用</h2> + +<p>如果你通过 <code>runtime.connectNative()</code> 连接原生应用，则原生应用会一直保持运行，直到 extension 调用 <code>Port.disconnect()</code> 或连接它的记录被结束。 如果你通过 <code>runtime.sendNativeMessage()</code> 向原生应用发消息，原生应用会在回复消息后被关闭。</p> + +<p>关闭原生应用的过程：</p> + +<ul> + <li>在 *nix 系统比如 OS X 和Linux 中，浏览器会向原生应用发送 SIGTERM 信号让其可以优雅的退出，然后再发送 SIGKILL 信号。这些信号将会传递给每一个子进程，除非它们分裂成一个新的进程组。</li> + <li>在 Windows 中，浏览器会向原生应用的进程发送一个 <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms684161(v=vs.85).aspx">Job object</a> 并杀死任务，如果原生应用启动任何的额外进程并希望它们能在原生应用被杀死后继续保持运行，原生应用需要在启动进程时使用 <code><a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx">CREATE_BREAKAWAY_FROM_JOB</a></code> 标记。</li> +</ul> + +<h2 id="常见问题_Troubleshooting">常见问题 Troubleshooting</h2> + +<p>如果有什么地方出错，可以检查<a href="/en-US/Add-ons/WebExtensions/Debugging#Viewing_log_output">浏览器控制台</a>。原生应用发送的任何 stderr 都会被反应在浏览器控制台中。所以如果你已经运行了原生应用，你可以看到原生应用发出的所有错误信息。</p> + +<p>如果你没有配置好原生应用，你应该会看到一些错误信息。</p> + +<pre>"No such native application <name>"</pre> + +<ul> + <li>检查 <code>runtime.connectNative()</code> 传入的名称与应用程序清单中的名称一致</li> + <li>OS X/Linux：检查原生应用清单文件的名称是 <name>.json</li> + <li>Windows：检查注册表是否在正确的位置，并且它的名称是否与应用程序清单中的名称一致</li> + <li>Windows：检查注册中给出的路径是否指向的是原生应用清单</li> +</ul> + +<pre>"Error: Invalid application <name>"</pre> + +<ul> + <li>检查原生应用的名称是否有非法字符</li> +</ul> + +<pre>"'python' is not recognized as an internal or external command, ..."</pre> + +<ul> + <li>Windows：如果你的应用是一个Python script，检查你是否已经安装过Python，并为其配置好路径</li> +</ul> + +<pre>"File at path <path> does not exist, or is not executable"</pre> + +<ul> + <li>如果你看见它，意味着应用程序清单已经被找到了</li> + <li>检查应用程序清单的 path 字段是正确的</li> + <li>Windows：检查你是否已经转移过了路径分隔符 ("c:\\path\\to\\file")</li> + <li>检查原生应用是否在原生应用清单中的 path 字段中指向的本地路径</li> + <li>检查原生应用是否可执行</li> +</ul> + +<pre>"This extension does not have permission to use native application <name>"</pre> + +<ul> + <li>检查原生应用清单中的 "allowed_extensions" 字段中是否包含了 extension 的 ID。</li> +</ul> + +<pre>"TypeError: browser.runtime.connectNative is not a function"</pre> + +<ul> + <li>检查 extension 是否已经拥有了 nativeMessaging 权限</li> +</ul> + +<pre>"[object Object] NativeMessaging.jsm:218"</pre> + +<ul> + <li>这是一个启动原生应用时的问题。</li> +</ul> + +<h2 id="与_Chrome_的兼容问题">与 Chrome 的兼容问题</h2> + +<p>{{Page("Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities", "Native_messaging")}}</p> |