initial commit

1 files changed, 160 insertions, 0 deletions

diff --git a/files/ja/mozilla/add-ons/webextensions/working_with_files/index.html b/files/ja/mozilla/add-ons/webextensions/working_with_files/index.html
new file mode 100644
index 0000000000..299643f95c
--- /dev/null
+++ b/files/ja/mozilla/add-ons/webextensions/working_with_files/index.html
@@ -0,0 +1,160 @@
+---
+title: ファイルの操作
+slug: Mozilla/Add-ons/WebExtensions/Working_with_files
+tags:
+  - Guide
+  - WebExtensions
+translation_of: Mozilla/Add-ons/WebExtensions/Working_with_files
+---
+<div>{{AddonSidebar()}}</div>
+
+<p>拡張機能にて完全な機能を提供するのにファイルを操作する必要があるかもしれません。この記事ではファイルを扱うための 5 つのメカニズムを見ていきます:</p>
+
+<ul>
+ <li>ユーザーが選択したファイルをダウンロードフォルダーにダウンロードする</li>
+ <li>ウェブページのファイルピッカーを使ってファイルを開く</li>
+ <li>ウェブページへのドラッグアンドドロップを使ってファイルを開く</li>
+ <li>idb-file-storage ライブラリーを使ってファイルや blob を IndexedDB に保管する</li>
+ <li>ユーザーのコンピューター上のネイティブアプリケーションにファイルを渡す</li>
+</ul>
+
+<p>それぞれのメカニズムに対し、各 API ドキュメンテーションやガイド、対応する API の使用法の例のリファレンスと一緒に、使い方を紹介します。</p>
+
+<h2 id="Download_files_using_the_downloads_API" name="Download_files_using_the_downloads_API">ダウンロード API を使ってファイルをダウンロード</h2>
+
+<p>この仕組みでは、あなたのウェブサイト(や URL で決められたあらゆる場所)からユーザーのコンピューターにファイルを入手できます。主要なメソッドは {{WebExtAPIRef("downloads.download()")}} で、その簡単なフォームで URL を受け付けて、その URL からユーザーの既定のダウンロードフォルダーにファイルをダウンロードします:</p>
+
+<pre class="brush: js">browser.downloads.download({url: "https://example.org/image.png"})</pre>
+
+<p>ユーザーが <code>saveAs</code> パラメーターで指定した場所にダウンロードさせることもできます。</p>
+
+<div class="note">
+<p>Using <a href="https://developer.mozilla.org/ja/docs/Web/API/URL/createObjectURL">URL.createObjectURL()</a> you can also download files and blobs defined in your JavaScript, which can include local content retrieved from IndexedDB.</p>
+</div>
+
+<p>ダウンロード API はダウンロードをキャンセル、停止、再開、消去、削除することもできます; ダウンロードマネージャーでダウンロード済みのファイルを探します; コンピューターのファイルマネージャーでダウンロード済みのファイルを表示します; 関連付けられたアプリケーションでそのファイルを開きます。</p>
+
+<p>この API を使うには <a href="/ja/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> ファイルにて "downloads"<a href="/ja/docs/Web/API/Permissions#API_permissions"> API パーミッション</a>が必要です。</p>
+
+<p>例: <a href="https://github.com/mdn/webextensions-examples/tree/master/latest-download">Latest download</a><br>
+ API リファレンス: <a href="/ja/docs/Mozilla/Add-ons/WebExtensions/API/downloads">downloads API</a></p>
+
+<h2 id="Open_files_in_an_extension_using_a_file_picker" name="Open_files_in_an_extension_using_a_file_picker">ファイルピッカーを使って拡張機能でファイルを開く</h2>
+
+<p>ユーザーのコンピューターからのファイルを扱いたい場合、1 つの選択はコンピューターのファイルブラウザーを使ってユーザーがファイル選択できるようにすることです。新しいページを作るか既存のページにコードを挿入して、ファイルピッカーをユーザーに提供するため HTML <code>input</code> 要素の <code>file</code> タイプを使います。ユーザーがファイルを選ぶと、ページに関連付けられたスクリプトにより、<a href="/ja/docs/Web/API/File">DOM File API</a> を使ってウェブアプリケーションと同様な方法でファイルの中身にページからアクセスできます。</p>
+
+<p>例: <a href="https://github.com/mdn/webextensions-examples/tree/master/imagify">Imagify</a><br>
+ ガイド: <a href="/ja/docs/Using_files_from_web_applications">Using files from web applications</a><br>
+ API リファレンス: <a href="/ja/docs/Web/HTML/Element/input/file">HTML input element</a> | <a href="/ja/docs/Web/API/File">DOM File API</a></p>
+
+<div class="note">
+<p>選択したフォルダーの全ファイルにアクセスや処理したい場合、<code>&lt;input type="file" </code><code>webkitdirectory="true"/&gt;</code> を使ってフォルダーを選択して、そこにある全ファイルを返すようにできます。</p>
+</div>
+
+<h2 id="Open_files_in_an_extension_using_drag_and_drop" name="Open_files_in_an_extension_using_drag_and_drop">ドラッグアンドドロップを使って拡張機能でファイルを開く</h2>
+
+<p>Web Drag and Drop API では別のファイルピッカーがあります。このメソッドを使うには、UI にフィットする ‘drop zone’ を設置して、<a href="/ja/docs/Web/Events/dragenter">dragenter</a>,<a href="/ja/docs/Web/Events/dragover"> dragover</a>, <a href="/ja/docs/Web/Events/drop">drop</a> イベントのリスナーを要素に追加します。ドロップイベントのハンドラーでは、<a href="/ja/docs/Web/API/DataTransfer/files">DataTransfer.files</a> を使って dataTransfer プロパティから提供されたオブジェクトからユーザーにドロップされたあらゆるファイルに、コードからアクセスできます。すると <a href="/ja/docs/Web/API/File">DOM File API</a> を使ってファイルにアクセス・操作することができます。</p>
+
+<p>例: <a href="https://github.com/mdn/webextensions-examples/tree/master/imagify">Imagify</a><br>
+ ガイド: <a href="/ja/docs/Using_files_from_web_applications">Using files from web applications</a> | <a href="/ja/docs/Web/API/HTML_Drag_and_Drop_API/File_drag_and_drop">File drag and drop</a><br>
+ API リファレンス: <a href="/ja/docs/Web/API/File">DOM File API</a></p>
+
+<h2 id="Store_files_data_locally_using_the_IndexedDB_file_storage_library" name="Store_files_data_locally_using_the_IndexedDB_file_storage_library"> IndexedDB ファイルストレージライブラリーを使ってローカルにファイル保存する</h2>
+
+<p>拡張機能がローカルにファイル保存する必要がある場合、<a href="https://www.npmjs.com/package/idb-file-storage">idb-file-storage ライブラリー</a>は 完結な Promiseベースの<a href="/ja/docs/Web/API/IndexedDB_API">IndexedDB API</a>ラッパーであり、ストレージやファイルやblobの取得を助けます。</p>
+
+<p>Firefoxでは、このライブラリーは非標準の IDBMutableFile APIのラッパーとしてPromiseベースのAPIも提供します (IDBMutableFile API を使うと、拡張機能はIndexedDB データベースファイルオブジェクトの作成と保存ができて、それによりメモリーにファイルを読み込むことなくファイルの中身を読み書きできるAPIが提供されます)</p>
+
+<p>このライブラリーのキーとなる機能は:</p>
+
+<ul>
+ <li>IDBFileStorageインスタンスを返す <a href="https://rpl.github.io/idb-file-storage/function/index.html#static-function-getFileStorage">getFileStorage</a>。名前付きストレージが存在しない場合には作成します。</li>
+ <li><a href="https://rpl.github.io/idb-file-storage/class/src/idb-file-storage.js~IDBFileStorage.html">IDBFileStorage</a>。これはファイルを保存したり取得するメソッドを提供します、例えば次のもの:
+  <ul>
+   <li>データベース内の(フィルターされた)ファイルのlist</li>
+   <li>データベースにファイルやblobを追加するput</li>
+   <li>データベースからファイルやblobを取得するget</li>
+   <li>データベースからファイルやblobを削除するremove</li>
+  </ul>
+ </li>
+</ul>
+
+<p><a href="https://github.com/mdn/webextensions-examples/tree/master/store-collected-images/webextension-plain">Store Collected Images</a> の例ではこの機能の大半の使い方を示します。(IDBMutableFile は含まれていませんが、<a href="https://rpl.github.io/idb-file-storage/examples/">idb-file-storage examples</a> にて、ライブラリーの他の多くの例と一緒に見ることができます)。</p>
+
+<p>Store Collected Images の例では、画像コンテキストメニューを使ってユーザーが画像を追加できます。選択された画像はポップアップメニューに集められて、名前付きコレクションに保存されます。ツールバーボタンの({{WebExtAPIRef("browserAction")}}) ナビゲートコレクションのページを開き、そこでユーザーは選択を狭められるフィルターオプションを使って、保存された画像を見たり消去したりできます。<a href="https://youtu.be/t6aVqMMe2Rc">この例を見てください</a>。</p>
+
+<p>/utils/ 内の <a href="https://github.com/mdn/webextensions-examples/blob/master/store-collected-images/webextension-plain/utils/image-store.js">image-store.js</a> を見てライブラリーの動作を理解できます:</p>
+
+<h3 id="Creating_the_store_and_saving_the_images" name="Creating_the_store_and_saving_the_images">store を作成して画像を保存する</h3>
+
+<pre class="brush: js">async function saveCollectedBlobs(collectionName, collectedBlobs) {
+ const storedImages = await getFileStorage({name: "stored-images"});
+
+ for (const item of collectedBlobs) {
+    await storedImages.put(`${collectionName}/${item.uuid}`, item.blob);
+ }
+}</pre>
+
+<p><code>saveCollectedBlobs</code> is called when the user clicks save in the popup and has provided a name for the image collection. First, <code>getFileStorage</code> creates, if it does not exist already, or retrieves the IndexedDB database “stored-images” to the object <code>storedImages</code>. <code>storedImages.put</code> then adds each collected image to the database, under the collection name, using the blob’s unique id (the file name). If the image being store has the same name as one already in the database, it is overwritten. If you want to avoid this, query the database first using <code>imagesStore.list()</code> with a filter for the file name, and, if the list returns a file, add a suitable suffix to the name of the new image to store a separate item.</p>
+
+<h3 id="Retrieving_stored_images_for_display" name="Retrieving_stored_images_for_display">保管された画像を表示用に取得する</h3>
+
+<pre class="brush: js">export async function loadStoredImages(filter) {
+ const imagesStore = await getFileStorage({name: "stored-images"});
+ let listOptions = filter ? {includes: filter} : undefined;
+ const imagesList = await imagesStore.list(listOptions);
+ let storedImages = [];
+ for (const storedName of imagesList) {
+    const blob = await imagesStore.get(storedName);
+    storedImages.push({storedName, blobUrl: URL.createObjectURL(blob)});
+ }
+ return storedImages;
+}
+</pre>
+
+<p><code>loadStoredImages</code> is called when the user clicks view or reload in the navigate collection page. <code>getFileStorage</code> opens the “stored-images” database, then <code>imagesStore.list</code> gets a filtered list of the stored images. This list is then used to retrieve images with <code>imagesStore.get</code> and build a list to return to the UI.</p>
+
+<p>Note the use of <a href="/ja/docs/Web/API/URL/createObjectURL">URL.createObjectURL(blob)</a> to create a URL that references the image blob. This URL is then used in the UI (<a href="https://github.com/mdn/webextensions-examples/blob/master/store-collected-images/webextension-plain/navigate-collection.js">navigate-collection.js</a><a href="https://github.com/mdn/webextensions-examples/blob/master/store-collected-images/webextension-plain/navigate-collection.js">collection.js</a>) to display the image.</p>
+
+<h3 id="Delete_collected_images" name="Delete_collected_images">集まった画像を削除する</h3>
+
+<pre class="brush: js">async function removeStoredImages(storedImages) {
+ const imagesStore = await getFileStorage({name: "stored-images"});
+ for (const storedImage of storedImages) {
+    URL.revokeObjectURL(storedImage.blobUrl);
+    await imagesStore.remove(storedImage.storedName);
+ }
+}
+</pre>
+
+<p><code>removeStoredImages</code> is called when the user clicks delete in the navigate collection page. Again, <code>getFileStorage</code> opens the “stored-images” database then <code>imagesStore.remove</code> removes each image from the filtered list of images.</p>
+
+<p>Note the use of <a href="/ja/docs/Web/API/URL/revokeObjectURL">URL.revokeObjectURL()</a> to explicitly revoke the blob URL. This enables the garbage collector to free the memory allocated to the URL. If this is not done, the memory will not get returned until the page on which it was created is closed. If the URL was created in an extension’s background page, this is not unloaded until the extension is disabled, uninstalled, or reloaded, so holding this memory unnecessarily could affect browser performance. If the URL is created in an extension’s page (new tab, popup, or sidebar) the memory is released when the page is closed, but it is still a good practice to revoke the URL when it is no longer needed.</p>
+
+<p>Once the blob URL has been revoked any attempt to load it will result in an error. 例えば、if the blob url was used as the <code>SRC</code> attribute of an <code>IMG</code> tag, the image will not load and will not be visible. It is therefore good practice to remove any revoked blob urls from generated HTML elements when the blob URL is revoked.</p>
+
+<p>Example: <a href="https://github.com/mdn/webextensions-examples/tree/master/store-collected-images/webextension-plain">Store Collected Images</a><br>
+ API References:  <a href="https://rpl.github.io/idb-file-storage/">idb-file-storage library</a></p>
+
+<div class="note">
+<p>Note: You can also use the full Web <a href="https://developer.mozilla.org/ja/docs/Web/API/IndexedDB_API">IndexedDB API</a> to store data from your extension. This can be useful where you need to store data that isn’t handled well by the simple key/value pairs offered by the DOM <a href="https://developer.mozilla.org/ja/Add-ons/WebExtensions/API/Storage">Storage API</a>.</p>
+</div>
+
+<h2 id="Process_files_in_a_local_app" name="Process_files_in_a_local_app">ローカルアプリでファイルを処理する</h2>
+
+<p>Where you have a native app or want to deliver additional native features for file processing, use native messaging to pass a file to a native app for processing.</p>
+
+<p>You have two options:</p>
+
+<ul>
+ <li>Connection-based messaging. Here you trigger the process with runtime.connectNative(), which returns a <a href="https://developer.mozilla.org/ja/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a> object. You can then pass a JSON message to the native application using the postMessage() function of Port. Using the onMessage.addListener() function of Port you can listen for messages from the native application. The native application is opened if it is not running when runtime.connectNative() is called and the application remains running until the extension calls Port.disconnect() or the page that connected to it is closed.</li>
+ <li>Connectionless messaging. Here you use runtime.sendNativeMessage() to send a JSON message to a new, temporary instance of the native application. The browser closes the native application after receiving any message back from the native application.</li>
+</ul>
+
+<p>To add the file or blob you want the native application to process use <a href="https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify">JSON.stringify()</a>.</p>
+
+<p>To use this method the extension must request the "nativeMessaging"<a href="https://developer.mozilla.org/ja/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions"> permission</a> in its manifest.json file. Reciprocally, the native application must grant permission for the extension by including its ID in the "allowed_extensions" field of the app manifest.</p>
+
+<p>Example: <a href="https://github.com/mdn/webextensions-examples/tree/master/native-messaging">Native Messaging</a> (illustrates simple messaging only)<br>
+ Guides: <a href="https://developer.mozilla.org/ja/Add-ons/WebExtensions/Native_messaging">Native messaging</a><br>
+ API references: <a href="https://developer.mozilla.org/ja/Add-ons/WebExtensions/API/runtime">runtime API</a></p>