1<!---
  2    Licensed to the Apache Software Foundation (ASF) under one
  3    or more contributor license agreements.  See the NOTICE file
  4    distributed with this work for additional information
  5    regarding copyright ownership.  The ASF licenses this file
  6    to you under the Apache License, Version 2.0 (the
  7    "License"); you may not use this file except in compliance
  8    with the License.  You may obtain a copy of the License at
  9
 10      http://www.apache.org/licenses/LICENSE-2.0
 11
 12    Unless required by applicable law or agreed to in writing,
 13    software distributed under the License is distributed on an
 14    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 15    KIND, either express or implied.  See the License for the
 16    specific language governing permissions and limitations
 17    under the License.
 18-->
 19
 20# Примечания для разработчиков плагинов
 21
 22Эти примечания предназначены прежде всего для Android и iOS разработчиков, которые хотят писать плагины какой интерфейс с файловой системой, с помощью файла плагина.
 23
 24## Работа с Кордова файловой системы URL
 25
 26Начиная с версии 1.0.0, этот плагин использует URL-адресов с `cdvfile` схема для всех коммуникации через мост, а не подвергая пути файловой системы raw устройства для JavaScript.
 27
 28На стороне JavaScript это означает, что объекты DirectoryEntry и FileEntry fullPath атрибут, который является по отношению к корневой файловой системе HTML. Если ваш плагин JavaScript API принимает объект DirectoryEntry или FileEntry, необходимо вызвать `.toURL()` для этого объекта перед передачей их через мост в машинный код.
 29
 30### Преобразование cdvfile: / / URL-адреса в пути fileystem
 31
 32Плагины, которые нужно написать в файловой системе может потребоваться преобразовать URL-адреса системы полученный файл в место фактической файловой системы. Существует несколько способов сделать это, в зависимости от родной платформе.
 33
 34Важно помнить, что не все `cdvfile://` URL-адреса являются отображаемыми файлами на устройстве. Некоторые URL может относиться к активам на устройстве, которые не представлены файлы, или может даже обратиться к удаленным ресурсам. Из-за эти возможности плагины следует всегда проверять ли они получают результат обратно при попытке преобразовать URL-адреса в пути.
 35
 36#### Android
 37
 38На Android, самый простой способ для преобразования `cdvfile://` URL-адрес к пути файловой системы заключается в использовании `cordova-plugin-CordovaResourceApi` . `CordovaResourceApi`Есть несколько методов, которые можно обработать `cdvfile://` URL-адреса:
 39
 40    // webView is a member of the Plugin class
 41    CordovaResourceApi resourceApi = webView.getResourceApi();
 42    
 43    // Obtain a file:/// URL representing this file on the device,
 44    // or the same URL unchanged if it cannot be mapped to a file
 45    Uri fileURL = resourceApi.remapUri(Uri.parse(cdvfileURL));
 46    
 47
 48Это также можно использовать плагин файл непосредственно:
 49
 50    import cordova-plugin-file.FileUtils;
 51    import cordova-plugin-file.FileSystem;
 52    import java.net.MalformedURLException;
 53    
 54    // Get the File plugin from the plugin manager
 55    FileUtils filePlugin = (FileUtils)webView.pluginManager.getPlugin("File");
 56    
 57    // Given a URL, get a path for it
 58    try {
 59        String path = filePlugin.filesystemPathForURL(cdvfileURL);
 60    } catch (MalformedURLException e) {
 61        // The filesystem url wasn't recognized
 62    }
 63    
 64
 65Для преобразования пути к `cdvfile://` URL-адрес:
 66
 67    import cordova-plugin-file.LocalFilesystemURL;
 68    
 69    // Get a LocalFilesystemURL object for a device path,
 70    // or null if it cannot be represented as a cdvfile URL.
 71    LocalFilesystemURL url = filePlugin.filesystemURLforLocalPath(path);
 72    // Get the string representation of the URL object
 73    String cdvfileURL = url.toString();
 74    
 75
 76Если ваш плагин создает файл, и вы хотите вернуть объект FileEntry для него, используйте файл плагина:
 77
 78    // Return a JSON structure suitable for returning to JavaScript,
 79    // or null if this file is not representable as a cdvfile URL.
 80    JSONObject entry = filePlugin.getEntryForFile(file);
 81    
 82
 83#### iOS
 84
 85Кордова на iOS не использовать те же `CordovaResourceApi` понятие, как Android. На iOS вы должны использовать файл плагин для преобразования URL-адреса и пути файловой системы.
 86
 87    // Get a CDVFilesystem URL object from a URL string
 88    CDVFilesystemURL* url = [CDVFilesystemURL fileSystemURLWithString:cdvfileURL];
 89    // Get a path for the URL object, or nil if it cannot be mapped to a file
 90    NSString* path = [filePlugin filesystemPathForURL:url];
 91    
 92    
 93    // Get a CDVFilesystem URL object for a device path, or
 94    // nil if it cannot be represented as a cdvfile URL.
 95    CDVFilesystemURL* url = [filePlugin fileSystemURLforLocalPath:path];
 96    // Get the string representation of the URL object
 97    NSString* cdvfileURL = [url absoluteString];
 98    
 99
100Если ваш плагин создает файл, и вы хотите вернуть объект FileEntry для него, используйте файл плагина:
101
102    // Get a CDVFilesystem URL object for a device path, or
103    // nil if it cannot be represented as a cdvfile URL.
104    CDVFilesystemURL* url = [filePlugin fileSystemURLforLocalPath:path];
105    // Get a structure to return to JavaScript
106    NSDictionary* entry = [filePlugin makeEntryForLocalURL:url]
107    
108
109#### JavaScript
110
111В JavaScript, чтобы получить `cdvfile://` URL от объекта DirectoryEntry или FileEntry, просто позвоните `.toURL()` на него:
112
113    var cdvfileURL = entry.toURL();
114    
115
116В плагин обработчики ответ для преобразования из возвращаемой структуры FileEntry объект фактического вступления, код обработчика следует импортировать файл плагина и создайте новый объект:
117
118    // create appropriate Entry object
119    var entry;
120    if (entryStruct.isDirectory) {
121        entry = new DirectoryEntry(entryStruct.name, entryStruct.fullPath, new FileSystem(entryStruct.filesystemName));
122    } else {
123        entry = new FileEntry(entryStruct.name, entryStruct.fullPath, new FileSystem(entryStruct.filesystemName));
124    }