diff options
Diffstat (limited to 'files/zh-tw/web/api/file_handle_api/index.html')
| -rw-r--r-- | files/zh-tw/web/api/file_handle_api/index.html | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/file_handle_api/index.html b/files/zh-tw/web/api/file_handle_api/index.html new file mode 100644 index 0000000000..bd603fe78a --- /dev/null +++ b/files/zh-tw/web/api/file_handle_api/index.html @@ -0,0 +1,233 @@ +--- +title: FileHandle API +slug: Web/API/File_Handle_API +translation_of: Web/API/File_Handle_API +--- +<p>FileHandle API 可操作檔案，例如建立檔案、修改檔案內容 (不同於 <a href="https://developer.mozilla.org/en-US/docs/DOM/File" title="DOM/File">File</a> API)。而正在編輯中的部分，將使用回合制的鎖定機制，以避免發生競態 (Race) 問題。</p> +<h2 id="API">API</h2> +<h3 id="建立_FileHandle">建立 FileHandle</h3> +<p>若要建立 FileHandle 物件，則需要 <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBFactory#open" title="IndexedDB/IDBFactory#open">IndexedDB Database</a>。</p> +<div style="overflow: hidden;"> + <pre class="brush: js">var idbreq = indexedDB.open("MyTestDatabase"); + +idbreq.onsuccess = function(){ + var db = idbreq.result; + var handleReq = db.mozCreateFileHandle("test.bin", "binary"); + + handleReq.onsuccess = function(){ + var handle = handleReq.result; + console.log('handle', handle); + }; +}; +</pre> +</div> +<p><code>mozCreateFileHandle() </code><code>共使用 </code>2<code> 組參數</code> (Argument)：1 組名稱與 1 組檔案類別 (Optional type)。但這 2 組<code>參</code>數均只屬於敘述性<code>參</code>數，不會用於資料庫。舉例來說，名稱可能是空白字串，而且不需為專屬字串。所以 API 根本不會注意這些參數值。</p> +<p>另請注意，上列程式碼僅會建立「暫時性檔案」，亦即當你保留 FileHandle 物件時，該檔案才會存在。如果你要在重新整理頁面/重新啟動 App 之後，仍能保留檔案，則必須將 Handle 儲存於更永久性的位置 (如資料庫本身之內) 中。</p> +<pre class="brush: js">var transaction = db.transaction(["test"], "readwrite"); +var objectStore = transaction.objectStore("test"); +objectStore.add(myFile, myKey).onsuccess = function(event) { + // The file is now referenced from database too. +} +</pre> +<h3 id="FileHandle_介面">FileHandle 介面</h3> +<pre>interface FileHandle +{ + LockedFile open(optional DOMString mode); + DOMRequest getFile() + readonly attribute DOMString name; + readonly attribute DOMString type; + attribute Function? onabort; + attribute Function? onerror; +};</pre> +<dl> + <dt> + open([mode="readonly"])</dt> + <dd> + 可回傳 <a href="#LockedFile_interface">LockedFile</a>。<code>mode</code> 可為「<code>readonly」或「</code><code>readwrite」。</code></dd> + <dt> + getFile()</dt> + <dd> + 針對檔案而回傳 <a href="/en-US/docs/DOM/DOMRequest" title="/en-US/docs/DOM/DOMRequest">DOMRequest</a>。若成功，就會收到以 <a href="https://developer.mozilla.org/en-US/docs/DOM/File" title="DOM/File">File</a> 物件形式呈現的唯讀「snapshot」檔案內容 (可用於任何接受 <a href="https://developer.mozilla.org/en-US/docs/DOM/Blob" title="DOM/Blob">Blob</a> 的地方，如 <a href="https://developer.mozilla.org/en-US/docs/DOM/FileReader" title="DOM/FileReader">FileReader</a> 或 <a href="https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest" title="DOM/XMLHttpRequest">XMLHttpRequest</a> 等)。 + <pre class="brush: js">myFile.getFile().onsuccess = function(event) { + var file = event.target.result; + var transcation = myDatabase.transaction(["snapshots"], "readwrite"); + var objectStore = transaction.objectStore("snapshots"); + objectStore.add(file, snapshotKey).onsuccess = function(event) { + // A new readonly copy of the file has been created. + } +} +</pre> + </dd> + <dt> + name</dt> + <dd> + 檔案名稱。</dd> + <dt> + type</dt> + <dd> + 代表 content-type。</dd> + <dt> + abort event</dt> + <dd> + 放棄已鎖定的檔案，就會發生此事件。</dd> + <dt> + error event</dt> + <dd> + 任何內部錯誤，都會發生此事件。</dd> +</dl> +<h3 id="LockedFile_介面">LockedFile 介面</h3> +<pre>interface LockedFile +{ + readonly attribute FileHandle fileHandle; + readonly attribute DOMString mode; + readonly attribute boolean active; + attribute any? location; + FileRequest getMetadata(optional FileMetadataParameters parameters); + FileRequest readAsArrayBuffer(unsigned long long size); + FileRequest readAsText(unsigned long long size, optional DOMString encoding); + FileRequest write(DOMString or ArrayBuffer or Blob value); + FileRequest append(DOMString or ArrayBuffer or Blob value); + FileRequest truncate(optional unsigned long long size); + FileRequest flush(); + void abort(); + attribute Function? oncomplete; + attribute Function? onabort; + attribute Function? onerror; +};</pre> +<dl> + <dt> + fileHandle</dt> + <dd> + 來自於解鎖的 FileHandle 物件。</dd> + <dt> + mode</dt> + <dd> + <code>「readonly」或「</code><code>readwrite」。</code></dd> + <dt> + active</dt> + <dd> + 一旦建立之後，就隨即啟動 LockedFile。此 LockedFile 是「可寫入存取 (Write access) 實際底層檔案」的唯一物件。LockedFile 上的作業，均於 <a href="http://en.wikipedia.org/wiki/Isolation_%28database_systems%29" title="http://en.wikipedia.org/wiki/Isolation_%28database_systems%29">isolation</a> 之中執行；也就是說，只要啟動了 LockedFile，則此 LockedFile 的所有作業都一定會在底層檔案上依序執行，而不會與其他 LockedFiles 的作業交錯執行。</dd> + <dd> + 若停用了 LockedFile，則只要在同樣的 LockedFile 上執行讀/寫作業，都會丟出錯誤訊息。</dd> +</dl> +<dl> + <dt> + location</dt> + <dd> + 檔案中的位置 (Offset)。每次讀/寫作業之後，此數值均將自動變更。讀寫作業均從該 location 開始，而 null 代表檔案末端。</dd> + <dt> + getMetadata(parameters)</dt> + <dd> + 針對後設資料 (Metadata) 而回傳 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。此<code>參</code>數亦屬於物件，其中將參數名稱作為物件鍵值，布林值作為數值，進而非同步檢索既有的屬性。無數值則代表 <code>true</code>。目前僅有 <code>size</code> 與 <code>lastModified</code> 為可能的參數。</dd> + <dt> + readAsArrayBuffer(size)</dt> + <dd> + 針對既有<code> size </code>的 <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="JavaScript/Typed_arrays/ArrayBuffer">ArrayBuffer</a>，回傳 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。此作業均從 <code>location</code> 開始，另根據讀取位元組的數目，移動 <code>location</code>。</dd> + <dt> + readAsText(size [, encoding])</dt> + <dd> + 針對既有 <code>size</code> 的字串，以既定的<code> encoding</code> 回傳 <a href="/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。此作業均從 <code>location</code> 開始，另根據讀取位元組的數目，移動 <code>location</code>。<a href="https://developer.mozilla.org/en-US/docs/DOM/FileReader" title="DOM/FileReader">FileReader</a> API 中的對等函式，也以相同方式運作。 + <pre class="brush: js">var lockedFile = myFile.open(); +var request = lockedFile.readAsText(3); +request.onsuccess = function(event) { + var text = request.result; + // 3 characters have been read. +} +</pre> + </dd> + <dt> + write(value)</dt> + <dd> + 針對成功/失敗的寫入作業，回傳 <a href="/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。寫入作業將從 <code>location</code> 開始，另根據寫入位元組的數目，移動位置。 + <pre class="brush: js">var lockedFile = myFile.open("readwrite"); +var request = lockedFile.write("foo"); +request.onsuccess = function(event) { + // The string "foo" has been written. +} +</pre> + </dd> + <dt> + append(value)</dt> + <dd> + 針對成功/失敗的附加 (Append) 作業，回傳 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest</a>。不論 <code>location</code> 為何，該數值均附加於檔案末端。在附加資料完畢後，<code>location</code> 隨即設定為 <code>null</code>。</dd> + <dt> + truncate([size])</dt> + <dd> + 針對成功/失敗的截斷 (Truncate) 作業，回傳 <a href="/en-US/docs/WebAPI/FileHandle_API#FileRequest_interface" title="WebAPI/FileHandle_API#FileRequest_interface">FileRequest。</a></dd> + <dd> + 如果是以單一<code>參</code>數呼叫該函式，則截斷成功之後，則<strong>不論</strong><code> location</code> 為何，檔案將剩下第一個 <code>size</code> 的位元組。</dd> + <dd> + 若沒有用任何<code>參</code>數呼叫該函式，則檔案將剩下 <code>location</code> 的第一個位元組。</dd> + <dt> + flush()</dt> + <dd> + 強制移轉緩衝過的資料至磁碟上，作業成功之後將回傳 FileRequest。此時即便 App 當機或非刻意中止，都能確保資料已經位於磁碟上了。</dd> + <dt> + abort()</dt> + <dd> + 停用 LockedFile 並取消全部尚未執行的作業。</dd> + <dt> + complete, abort, error events</dt> +</dl> +<h3 id="FileRequest_介面">FileRequest 介面</h3> +<p>此類型的物件，均是由 LockedFile 介面的所有非同步作業所回傳。此介面繼承了 <a href="https://developer.mozilla.org/en-US/docs/DOM/DOMRequest" title="DOM/DOMRequest">DOMRequest</a> 並類似 <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBRequest" title="IndexedDB/IDBRequest">IDBRequest</a>，同時還擁有 <code>onprogress </code><code>事件。在成功之後，則可透過</code> <code>result </code><code>屬性而取得必要檔案作業的結果。</code></p> +<pre>interface FileRequest : DOMRequest +{ + readonly attribute LockedFile lockedFile; + attribute Function? onprogress; +};</pre> +<dl> + <dt> + </dt> +</dl> +<h2 id="說明">說明</h2> +<h3 id="API_與_FileWriter_的差異？">API 與 FileWriter 的差異？</h3> +<p><a href="http://dev.w3.org/2009/dap/file-system/file-writer.html" title="http://dev.w3.org/2009/dap/file-system/file-writer.html">FileWriter 規格</a>定義了 FileWriter，也就是用以呈現「可編輯的檔案」的物件。<a href="http://lists.w3.org/Archives/Public/public-webapps/2012JanMar/0886.html" title="http://lists.w3.org/Archives/Public/public-webapps/2012JanMar/0886.html">Public-webapps 討論串</a>則下了結論：若單一檔案同時寫入不同的實體 (Entity)，將導致 API 成效不彰。最後就是 FileHandle API 應具備自己的 LockedFile 與交易機制。</p> +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> +<div> + {{CompatibilityTable}}</div> +<div id="compat-desktop"> + <table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>15</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> + </table> +</div> +<div id="compat-mobile"> + <table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>15</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> + </table> +</div> +<p> </p> |