API de Storage

Casi todos los aspectos del desarrollo de apps involucran algún elemento de envío o recepción de datos. Iniciando con los aspectos básicos, debes usar un framework MVC para diseñar e implementar tu app de modo que Los datos están completamente separados de la vista de la app sobre ellos (consulta Arquitectura de MVC).

También debes pensar en cómo se manejan los datos cuando la app está sin conexión (consulta Sin conexión primero). En este documento, se presentan brevemente las opciones de almacenamiento para enviar, recibir y guardar datos de forma local. el el resto del documento te muestra cómo utilizar las APIs del sistema de archivos de sincronización y del sistema de archivos de Chrome (consulta también la API de fileSystem y la API de syncFileSystem).

Opciones de almacenamiento

Las apps empaquetadas usan muchos mecanismos diferentes para enviar y recibir datos. Para datos externos (recursos, páginas web), debes conocer la Política de Seguridad del Contenido (CSP). Similares a Chrome Puedes usar XMLHttpRequests de origen cruzado para comunicarte con servidores remotos. Tú también puede aislar páginas externas, de modo que el resto de la app esté protegido (consulta Incorporar contenido web externo páginas).

Al guardar datos de forma local, puedes usar la API de Chrome Storage para guardar pequeñas cantidades de cadenas IndexedDB y datos para guardar datos estructurados. Con IndexedDB, puedes conservar objetos JavaScript en una almacenar objetos y usar los índices del almacén para consultar datos (para obtener más información, consulte la guía Simple Todo pendiente de HTML5 Rock) Instructivo de la lista). Para todos los demás tipos de datos, como datos binarios, usa Sistema de archivos y Sincronización. APIs del sistema de archivos.

Las APIs del sistema de archivos de sincronización y del sistema de archivos de Chrome extienden la API de HTML5 FileSystem. Con Chrome's Filesystem API, las aplicaciones pueden crear, leer, navegar y escribir en una sección de zona de pruebas del un sistema de archivos local. Por ejemplo, una aplicación para compartir fotos puede usar la API de Filesystem para leer y escribir cualquier fotos que un usuario selecciona.

Con la API de Sync Filesystem de Chrome, las apps pueden guardar y sincronizar datos en el Google Drive de un usuario para que los mismos datos pueden estar disponibles en distintos clientes. Por ejemplo, un texto respaldado por la nube editor puede sincronizar automáticamente los nuevos archivos de texto con la cuenta de Google Drive de un usuario. Cuando el usuario abre el editor de texto en un nuevo cliente, Google Drive envía los archivos de texto nuevos a esa instancia de el editor de texto.

Cómo usar la API del sistema de archivos de Chrome

Agrega un permiso del sistema de archivos

Para usar la API de File System de Chrome, debes agregar "fileSystem" permiso al manifiesto, así que que puede obtener permiso del usuario para almacenar datos persistentes.

"permissions": [
  "...",
  "fileSystem"
]

Opciones del usuario para seleccionar archivos

Los usuarios esperan seleccionar archivos de la misma forma en que lo hacen siempre. Como mínimo, esperan una "file" y el selector de archivos estándar. Si tu app hace un uso intensivo del manejo de archivos, también debes implementa la función de arrastrar y soltar (consulta a continuación y también consulta Arrastrar y soltar en HTML5 nativos).

Obtén la ruta de acceso de un fileEntry

Para obtener la ruta completa del archivo que seleccionó el usuario, fileEntry, llama a getDisplayPath():

function displayPath(fileEntry) {
  chrome.fileSystem.getDisplayPath(fileEntry, function(path) {
    console.log(path)
  });
}

Cómo implementar la función de arrastrar y soltar

Si necesitas implementar la selección de arrastrar y soltar, el controlador de archivos de arrastrar y soltar (dnd.js) en La muestra filesystem-access es un buen punto de partida. El controlador crea una entrada de archivo desde un DataTransferItem a través de la opción de arrastrar y soltar. En este ejemplo, fileEntry se establece en la primera elemento soltado.

var dnd = new DnDFileController('body', function(data) {
  var fileEntry = data.items[0].webkitGetAsEntry();
  displayPath(fileEntry);
});

Lee un archivo

El siguiente código abre el archivo (solo lectura) y lo lee como texto con un objeto FileReader. Si Si el archivo no existe, se mostrará un error.

var chosenFileEntry = null;

chooseFileButton.addEventListener('click', function(e) {
  chrome.fileSystem.chooseEntry({type: 'openFile'}, function(readOnlyEntry) {

    readOnlyEntry.file(function(file) {
      var reader = new FileReader();

      reader.onerror = errorHandler;
      reader.onloadend = function(e) {
        console.log(e.target.result);
      };

      reader.readAsText(file);
    });
    });
});

Escribe un archivo

Los dos casos de uso comunes para escribir un archivo son "Guardar". y "Guardar como". El siguiente código crea un writableEntry del chosenFileEntry de solo lectura y escribe en él el archivo seleccionado.

 chrome.fileSystem.getWritableEntry(chosenFileEntry, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = callback;

    chosenFileEntry.file(function(file) {
      writer.write(file);
    });
  }, errorHandler);
});

El siguiente código crea un archivo nuevo con "Guardar como" y escribe el nuevo BLOB en la con el método writer.write().

chrome.fileSystem.chooseEntry({type: 'saveFile'}, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = function(e) {
        console.log('write complete');
      };
      writer.write(new Blob(['1234567890'], {type: 'text/plain'}));
    }, errorHandler);
});

Cómo usar la API de Chrome Sync Filesystem

Mediante el almacenamiento de archivos sincronizable, se pueden operar los objetos de datos devueltos del mismo modo que los locales. sistemas de archivos sin conexión en la API de FileSystem, pero con la sincronización agregada (y automática) de estos a Google Drive.

Agrega un permiso de sincronización del sistema de archivos

Para usar la API de Sync Filesystem de Chrome, debes agregar "syncFileSystem" permiso al de modo que puedas obtener permiso del usuario para almacenar y sincronizar datos persistentes.

"permissions": [
  "...",
  "syncFileSystem"
]

Se está iniciando el almacenamiento de archivos sincronizables

Para iniciar el almacenamiento de archivos sincronizables en tu app, simplemente llama a syncFileSystem.requestFileSystem. Este método muestra un sistema de archivos sincronizable respaldado por Google Drive, por ejemplo:

chrome.syncFileSystem.requestFileSystem(function (fs) {
   // FileSystem API should just work on the returned 'fs'.
   fs.root.getFile('test.txt', {create:true}, getEntryCallback, errorCallback);
});

Información sobre el estado de sincronización de archivos

Usa syncFileSystem.getFileStatus para obtener el estado de sincronización de un archivo actual:

chrome.syncFileSystem.getFileStatus(entry, function(status) {...});

Los valores de estado de sincronización de archivos pueden ser uno de los siguientes: 'synced', 'pending' o 'conflicting'. Sincronizado significa que el archivo está completamente sincronizado. no hay cambios locales pendientes que no se hayan sincronizada con Google Drive. Sin embargo, puede haber cambios pendientes en Google Drive que aún no se recuperaron.

“Pendiente” significa que el archivo tiene cambios pendientes que aún no se han sincronizado con Google Drive. Si la app es que se ejecuta en línea, los cambios locales se sincronizan (casi) inmediatamente con Google Drive, y El evento syncFileSystem.onFileStatusChanged se activa con el estado 'synced' (consulta a continuación más detalles).

syncFileSystem.onFileStatusChanged se activa cuando el estado de un archivo cambia a 'conflicting' "En conflicto" significa que hay cambios conflictivos tanto en el almacenamiento local Google Drive Un archivo puede estar en este estado solo si se establece la política de resolución de conflictos en 'manual' La política predeterminada es 'last_write_win' y los conflictos se resuelven automáticamente: política simple de última escritura para ganar. La política de resolución de conflictos del sistema puede modificarse syncFileSystem.setConflictResolutionPolicy.

Si la política de resolución de conflictos se establece en 'manual' y un archivo tiene el estado 'conflicting', la app aún puede leer y escribir el archivo como un archivo local sin conexión, pero los cambios no se sincronizan y el archivo se mantendrá separado de los cambios remotos realizados en otros clientes hasta que se resuelva el conflicto. resuelto. La forma más fácil de resolver un conflicto es eliminar o cambiar el nombre de la versión local del archivo. Esto fuerza la sincronización de la versión remota, el estado conflictivo se resuelve y el Se activa el evento onFileStatusChanged con el estado 'synced'.

Escuchando cambios en el estado sincronizado

El evento syncFileSystem.onFileStatusChanged se activa cuando cambia el estado de sincronización de un archivo. Por ejemplo, supongamos que un archivo tiene cambios pendientes y se encuentra en estado “pendiente”. para cada estado. Es posible que la app se haya sin conexión, de modo que el cambio está a punto de sincronizarse. Cuando el servicio de sincronización detecta la cambio local pendiente y sube el cambio a Google Drive, el servicio activa Evento onFileStatusChanged con los siguientes valores: { fileEntry:a fileEntry for the file, status: 'synced', action: 'updated', direction: 'local_to_remote' }

Asimismo, independientemente de las actividades locales, el servicio de sincronización puede detectar cambios remotos realizados por a otro cliente y descarga los cambios de Google Drive en el almacenamiento local. Si el control remoto para agregar un archivo nuevo, se activa un evento con los siguientes valores: { fileEntry: a fileEntry for the file, status: 'synced', action: 'added', direction: 'remote_to_local' }

Si tanto el lado local como el remoto tienen cambios conflictivos para el mismo archivo y si hay un conflicto de resolución establecida en 'manual', el estado del archivo cambia a conflicting, el desvinculado del servicio de sincronización y no se sincronizará hasta que se resuelva el conflicto. En este En caso de que se active un evento con los siguientes valores: { fileEntry: a fileEntry for the file, status: 'conflicting', action: null, direction: null }

Puedes agregar un objeto de escucha para este evento que responda a cualquier cambio de estado. Por ejemplo, el La aplicación Chrome Music Player escucha todas las canciones nuevas sincronizadas desde Google Drive, pero todavía no. al almacenamiento local del usuario en un cliente en particular. La música que se encuentre se sincronizará con ella cliente:

chrome.syncFileSystem.onFileStatusChanged.addListener(function(fileInfo) {
  if (fileInfo.status === 'synced') {
    if (fileInfo.direction === 'remote_to_local') {
      if (fileInfo.action === 'added') {
        db.add(fileInfo.fileEntry);
      } else if (fileInfo.action === 'deleted') {
        db.remove(fileInfo.fileEntry);
      }
    }
  }
});

Verifica el uso de la API

Para comprobar la cantidad de datos que utiliza la API, consulta el directorio de zona de pruebas local de la app o la bytes de uso que muestra syncFileSystem.getUsageAndQuota:

chrome.syncFileSystem.getUsageAndQuota(fileSystem, function (storageInfo) {
   updateUsageInfo(storageInfo.usageBytes);
   updateQuotaInfo(storageInfo.quotaBytes);
});

También puedes consultar el almacenamiento del servicio de backend de sincronización del usuario (en Google Drive). Los archivos sincronizados son se guardó en una carpeta oculta de Google Drive, Sistema de archivos sincronizable de Chrome. La carpeta no se mostrará en tu unidad de “Mi unidad” pero se puede acceder buscando el nombre de la carpeta en el cuadro de búsqueda. (Ten en cuenta que no se garantiza que el diseño de la carpeta remota siga siendo retrocompatible entre versiones).