Révision 40011 sur Utiliser Application Cache

  • Raccourci de la révision : Utiliser_Application_Cache
  • Titre de la révision : Utiliser Application Cache
  • ID de la révision : 40011
  • Créé :
  • Créateur : whoshallsucceed
  • Version actuelle ? Non
  • Commentaire page created, 2575 words added

Contenu de la révision

HTML5 supporte la mise en cache hors-ligne de ressources d'applications web; les fichiers sont stockés dans application cache - une collection de ressources obtenues depuis un fichier manifest (*.appcache) inclue dans une application web.

AppCache

Chaque manifest d'une application web a son propre cache. Depuis que les applications peuvent partager des ressources (et même la même URI de manifest), chaque cache d'une application a une copie séparée de toutes les ressources. Ces caches sont versionnés; à chaque fois que l'application web est visitée en étant connecté, une nouvelle version de l'application peut être synchronisée dans application cache si des mises à jour sont disponibles. Cette nouvelle version sera ensuite utilisée à la prochaine visite.

Comment fonctionne AppCache

AppCache modifie le processus habituel de chargement de fichier; si un cache existe déjà, les ressources sont directement chargées depuis ce cache, sans accéder au réseau, accélérant le chargement de la page. L'application web vérifie ensuite si le manifest a été mis à jour sur le serveur et le cas échéant, une nouvelle version du cache est téléchargée. Tout ceci se fait en tâche de fond et n'affecte pas les performances de manière significative.

Les caches peuvent aussi devenir obsolètes. Si le manifest est supprimé du serveur, le navigateur supprime tous les caches qui utilise ce manifest, puis envoie un évènement "obsoleted" à l'objet application cache. Enfin, le statut du cache est défini comme OBSOLETE.

Les états

Chaque cache a un statut qui indique la condition actuelle du cache. Les caches qui partagent la même URI de manifest partagent le même statut, qui est un des suivants :

UNCACHED
Une valeur spéciale qui indique qu'un object application cache n'est pas complètement initialisée.
IDLE
Le cache n'est pas en cours de mise à jour.
CHECKING
Le manifest est en train d'être contrôlé pour d'éventuelles mises à jour.
DOWNLOADING
Des ressources sont en train d'être téléchargées pour être ajoutées au cache, dû à un changement du manifest.
UPDATEREADY
Il y a une nouvelle version du cache disponible. Il y a un évènement updateready correspondant, qui est lancé au lieu de l'évènement cached quand une nouvelle mise à jour a été téléchargée mais pas encore activée via la méthode swapCache().
OBSOLETE
Le groupe de caches est maintenant obsolète.

Les ressources dans AppCache

Les ressources dans le cache sont spécifiées par une URI qui pointe sur un fichier manifest (un fichier avec l'extension *.appcache). Ce fichier est référencé par l'attribut manifest dans l'élément html. Un manifest est téléchargé et traité pendant le processus de mise à jour d'AppCache. Les entrées doit avoir le même schéma, hôte et port que le manifest. Le cache inclue toujours au moins une ressource, identifiée par URI. Toutes les ressources répondent à une des catégories suivantes :

Master entries
Il s'agit de ressources ajoutées au cache parce qu'un contexte de navigation visité par l'utilisateur incluait un document qui indiquait que ces ressources étaient dans le cache en utilisant son attribut manifest.
Explicit entries
Il s'agit de ressources listées dans le manifest du cache.
Fallback entries
Il s'agit de ressources listées dans le manifest du cache comme entrées de fallback. {{ fx_minversion_inline("3") }}
Note : Les ressources peuvent être marquées dans plusieurs catégories, et peuvent donc être catégorisées comme des entrées multiples. Par exemple, une entrée peut être à la fois une entrée explicite et une entrée de fallback.

Master entries

Ce sont n'importe quels fichiers HTML qui inclue un attribut {{ htmlattrxref("manifest","html") }} dans leur élément {{ HTMLElement("html") }}. Par exemple, disons que nous avons le fichier http://www.example.com/entry.html, qui ressemble à ça :

<html manifest="example.appcache">
  <h1>Application Cache Example</h1>
</html>

Si entry.html n'est pas inclue dans le manifest, visiter la page entry.html provoquera l'ajout de la page entry.html dans le cache de l'application comme une master entry.

Fallback entries

Les entrées de fallback sont utilisées quand une tentative de chargement d'une ressource échoue. Par exemple, imaginons qu'il y a un fichier manifest situé à http://www.example.com/example.appcache, et qui contient :

CACHE MANIFEST
FALLBACK:
example/bar/ example.html

Toute requête vers http://www.example.com/example/bar/ ou n'importe lequel de ses sous-répertoires et contenus provoquera une tentative de chargement de la ressource demandée. Si la tentative échoue, soit à cause d'un échec réseau ou d'une erreur serveur quelle qu'elle soit, le contenu du fichier example.html sera chargé à la place.

Network entries

Les entrées listées dans NETWORK : peuvent contenir plusieurs ou aucune ressource que l'application requiert lors d'un accès en ligne. C'est principalement une liste blanche en ligne. Les URIS spécifiées dans la section NETWORK sont chargées depuis le serveur plutôt que depuis le cache. Cela permet au modèle de sécurité du navigateur de protéger l'utilisateur de possibles brèches de sécurité en limitant l'accès aux seules ressources approuvées.

Note : La liste blanche en ligne est ignorée pour les versions de Firefox antérieures à 3.5.

Vous pouvez l'utiliser pour, par exemple, charger et exécuter des scripts et d'autres codes depuis le serveur au lieu du cache. :

CACHE MANIFEST
NETWORK:
/api

Ceci assure que les requêtes téléchargent les ressources contenues dans http://www.example.com/api/ viendront toujours du réseau sans essayer d'accéder au cache.

Note : Juste omettre les master entries (les fichiers qui ont l'attribut manifest défini dans l'élément html) dans le manifest n'aurait pas le même comportement parce que les master entries seront ajoutées — et donc servies depuis— le cache. 

Le Manifest

Les fichiers manifests doivent être servis avec le type MIME text/cache-manifest, et toutes les ressources servies en utilisant ce type MIME doivent respecter la syntaxe d'un manifest, comme défini ici. Les manifests sont des fichiers textes au format UTF-8 et peuvent, éventuellement, inclure un caractère BOM. Les nouvelles lignes peuvent être représentés par saut de ligne (U+000A), retour chariot (U+000D), ou les deux.

La première ligne du manifest doit être la chaine CACHE MANIFEST (séparé par un simple espace U+0020), suivi par aucun ou plusieurs espaces ou tabulations. Tout autre texte sur la ligne sera ignoré.

Le reste du manifest peut contenir 0 ou plusieurs lignes :

Blank line
Vous pouvez utiliser les lignes vides comprenant 0 ou plusieurs espaces ou tabulations.
Comment
Les commentaires consistent en 0 ou plusieurs espaces ou tabulations suivis du caractère #, suivi de 0 ou plusieurs caractères de texte. Les commentaires devraient être utilisés seulement sur leur propre ligne, et ne devrait pas être ajoutés à d'autres lignes. This also means that you cannot specify fragment identifiers.
Section header
Section headers specify which section of the cache manifest is being manipulated. There are three possible section headers:
Section header Description
CACHE: Switches to the explicit section. This is the default section.
FALLBACK: Switches to the fallback section.

{{ fx_minversion_note("3") }}

NETWORK: Switches to the online whitelist section.

{{ fx_minversion_note("3") }}

The section header line may include whitespaces, but must include the colon (:) in the section name.
Section data
The format for lines of data varies from section to section. In the explicit (CACHE:) section, each line is a valid URI or IRI reference to a resource to cache (no wildcard characters are allowed in this sections). Whitespace is allowed before and after the URI or IRI on each line. In the Fallback section each line is a valid URI or IRI reference to a resource, followed by a fallback resource that is to be served up when a connection with the server cannot be made. In the network section, each line is a a valid URI or IRI reference to a resource to fetch from the network (the wildcard * is allowed in this section).

Cache manifests may switch back and forth from section to section at will (each section header can be used more than once), and sections are allowed to be empty.

Note: Relative URIs are relative to the cache manifest's URI, not to the URI of the document referencing the manifest.

A sample cache manifest

The following is a simple cache manifest example.appcache for an imaginary web site at www.example.com.

CACHE MANIFEST
# v1 - 2011-08-13
# This is a comment.
http://www.example.com/index.html
http://www.example.com/header.png
http://www.example.com/blah/blah

In this example, thee is no section header, so all data lines are assumed to be in the explicit (CACHE:) section. You can also specify relative URLs (index.html, etc.)

The "v1" comment is there for a good reason. Because the cache is only updated when the manifest changes, byte for byte. If you change the resources (for example, updating the header.png image with new content), you need to change the manifest file contents in order to let the browser know that it needs to refresh the cache (and since header.png is already in the manifest file, you need to change something else). You can do this by any change to the manifest, but having a version number is the recommended best practice.

Important: Do not specify the manifest itself in the cache manifest file otherwise it will be nearly impossible to inform the browser a new manifest is available.

The following is a more complete cache manifest for the same, imaginary web site at www.example.com. This example also uses the FALLBACK and NETWORK sections to specify that the network.html page must always be retrieved from the network and that the fallback.html page should be served as a fallback resource. For example, in case a connection to the server cannot be established.

CACHE MANIFEST
# v1 2011-08-14
# This is another comment
index.html
cache.html
style.css
image1.png

# Fallback content
FALLBACK:
/ fallback.html

# Use from network if available
NETWORK:
network.html

 

Specifying a cache manifest

To use application cache, you need to use the manifest attribute in the html element as shown in the following example:

<html manifest="example.appcache"> 
  ...
</html>

Some browsers like Firefox will display a notification bar the first time the user loads your application saying "This website (www.example.com) is asking to store data on your computer for offline use. [Allow] [Never for This Site] [Not Now]". The term "Offline(-enabled) applications" sometimes refers specifically to applications allowed by the user to use the offline capabilities.

The update process

  1. When the browser visits a document that includes a manifest attribute and if no application cache exists yet, it will load the document and then fetch all the entries listed in the manifest file, creating the first version of the application cache. 
  2. Subsequent visits to that document will trigger the browser to load the document and other assets specified in the manifest file from the application cache (not from the server) and in addition the browser will also send a checking event to the window.applicationCache object, then fetches the manifest file, following the appropriate HTTP caching rules. If the currently-cached copy of the manifest is up-to-date, the noupdate event is sent to the applicationCache, and the update process is complete. (This is why if you change any resources on the server, you need to also change the manifest file so the browser knows it needs to fetch all the resources again.
  3. If the manifest file has changed, all files in the manifest—as well as those added to the cache by calling applicationCache.add()—are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into this temporary cache, a progress event is sent to the applicationCache object. If any errors occur, an error event is sent, and the update halts.
  4. Once all the files have been successfully retrieved, they are moved into the real offline cache atomically, and a cached event is sent to the applicationCache object. Since the document has already been loaded into the browser from the cache, the updated document won't be rendered until the document is reloaded (either manually or programatically).

Testing for updates

Testing to see if an application has an updated cache manifest available can be done programmatically through Javascript. Since the cache may have been updated before any script using events to test for updates, scripts should always test window.applicationCache.status.

function onUpdateReady() {
  alert('found new version!');
}
window.applicationCache.addEventListener('updateready', onUpdateReady);
if(window.applicationCache.status === window.applicationCache.UPDATEREADY) {
  onUpdateReady();
}

 To manually start testing for a new manifest you can use window.applicationCache.update().

Gotchas

  • Since applications are using a cache, simply updating the files served under web pages is not enough to update files that have been cached. Updating the manifest will be required before the files are using their new source. This can be done programmatically through window.applicationCache.swapCache(), but already loaded resources will not be affected. In order to ensure resources are loaded from new version of the application cache refreshing the page is ideal.
  • it is a good idea to set expires headers on your web server for *.appcache files to expire immediately to avoid the risk of caching the manifest files. For example, in Apache you can configure this as follows:
    ExpiresByType text/cache-manifest "access plus 0 seconds"

Storage location and clearing the offline cache

In Chrome you can clear the offline cache by selecting "Clear browsing data..." in the preferences or by visiting chrome://appcache-internals/. Safari has a similar "Empty cache" setting in its preferences but a browser restart may also be required.

In Firefox, the offline cache data is stored separately from the Firefox profile—next to the regular disk cache:

  • Windows Vista/7: C:\Users\<username>\AppData\Local\Mozilla\Firefox\Profiles\<salt>.<profile name>\OfflineCache
  • Mac/Linux: /Users/<username>/Library/Caches/Firefox/Profiles/<salt>.<profile name>/OfflineCache

In Firefox the current status of the offline cache can be inspected on the about:cache page (under the "Offline cache device" heading).

The offline cache is not cleared via Tools -> Clear Recent History (bug 538595)
The offline cache is not cleared via Tools -> Options -> Advanced -> Network -> Offline data -> Clear Now (bug 538588).
The offline cache can be cleared for each site separately using the "Remove..." button in Tools -> Options -> Advanced -> Network -> Offline data.

See also clearing the DOM Storage data.

Browser Compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 4.0 3.5 10.0 10.6 4.0
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 2.1 {{ CompatUnknown() }} {{ CompatNo() }} 11.0 3.2

 

See also

{{ HTML5ArticleTOC() }}

{{ languages( { "es": "es/Recursos_offline_en_firefox", "fr": "fr/Ressources_hors_ligne_dans_Firefox", "ja": "ja/Offline_resources_in_Firefox", "pl": "pl/Zasoby_offline_w_Firefoksie", "zh-tw": "zh_tw/Offline_resources_on_Firefox" } ) }}

Source de la révision

<p>HTML5 supporte la mise en cache hors-ligne de ressources d'applications web; les fichiers sont stockés dans <strong>application cache</strong> - une collection de ressources obtenues depuis un fichier <strong>manifest</strong> (<code>*.appcache</code>) inclue dans une application web.</p>
<div> <h2>AppCache</h2> <p>Chaque manifest d'une application web a son propre cache. Depuis que les applications peuvent partager des ressources (et même la même URI de manifest), chaque cache d'une application a une copie séparée de toutes les ressources. Ces caches sont versionnés; à chaque fois que l'application web est visitée en étant connecté, une nouvelle version de l'application peut être synchronisée dans <strong>application cache</strong> si des mises à jour sont disponibles. Cette nouvelle version sera ensuite utilisée à la prochaine visite.</p> <h3>Comment fonctionne AppCache</h3> <p>AppCache modifie le processus habituel de chargement de fichier; si un cache existe déjà, les ressources sont directement chargées depuis ce cache, sans accéder au réseau, accélérant le chargement de la page. L'application web vérifie ensuite si le manifest a été mis à jour sur le serveur et le cas échéant, une nouvelle version du cache est téléchargée. Tout ceci se fait en tâche de fond et n'affecte pas les performances de manière significative.</p> <p>Les caches peuvent aussi devenir obsolètes. Si le manifest est supprimé du serveur, le navigateur supprime tous les caches qui utilise ce manifest, puis envoie un évènement "obsoleted" à l'objet <em>application cache</em>. Enfin, le statut du cache est défini comme <code>OBSOLETE</code>.</p> <h4>Les états</h4> <p>Chaque cache a un statut qui indique la condition actuelle du cache. Les caches qui partagent la même URI de manifest partagent le même statut, qui est un des suivants :</p> <dl> <dt><code>UNCACHED</code></dt> <dd>Une valeur spéciale qui indique qu'un object <em>application cache</em> n'est pas complètement initialisée.</dd> <dt><code>IDLE</code></dt> <dd>Le cache n'est pas en cours de mise à jour.</dd> <dt><code>CHECKING</code></dt> <dd>Le manifest est en train d'être contrôlé pour d'éventuelles mises à jour.</dd> <dt><code>DOWNLOADING</code></dt> <dd>Des ressources sont en train d'être téléchargées pour être ajoutées au cache, dû à un changement du manifest.</dd> <dt><code>UPDATEREADY</code></dt> <dd>Il y a une nouvelle version du cache disponible. Il y a un évènement <code>updateready</code> correspondant, qui est lancé au lieu de l'évènement <code>cached</code> quand une nouvelle mise à jour a été téléchargée mais pas encore activée via la méthode <code>swapCache()</code>.</dd> <dt><code>OBSOLETE</code></dt> <dd>Le groupe de caches est maintenant obsolète.</dd> </dl> <h3>Les ressources dans AppCache</h3> <p>Les ressources dans le cache sont spécifiées par une URI qui pointe sur un fichier manifest (un fichier avec l'extension <code>*.appcache</code>). Ce fichier est référencé par l'attribut <code>manifest</code> dans l'élément <code>html</code>. Un manifest est téléchargé et traité pendant le processus de mise à jour d'AppCache. Les entrées doit avoir le même schéma, hôte et port que le manifest. Le cache inclue toujours au moins une ressource, identifiée par URI. Toutes les ressources répondent à une des catégories suivantes :</p> <dl> <dt>Master entries</dt> <dd>Il s'agit de ressources ajoutées au cache parce qu'un contexte de navigation visité par l'utilisateur incluait un document qui indiquait que ces ressources étaient dans le cache en utilisant son attribut <code>manifest</code>.</dd> <dt>Explicit entries</dt> <dd>Il s'agit de ressources listées dans le manifest du cache.</dd> <dt>Fallback entries</dt> <dd>Il s'agit de ressources listées dans le manifest du cache comme entrées de fallback. {{ fx_minversion_inline("3") }}</dd> </dl> <div class="note"><strong>Note : </strong>Les ressources peuvent être marquées dans plusieurs catégories, et peuvent donc être catégorisées comme des entrées multiples. Par exemple, une entrée peut être à la fois une entrée explicite et une entrée de fallback.</div> <h4>Master entries</h4> <p>Ce sont n'importe quels fichiers HTML qui inclue un attribut {{ htmlattrxref("manifest","html") }} dans leur élément {{ HTMLElement("html") }}. Par exemple, disons que nous avons le fichier <code><a class="linkification-ext external" href="http://www.foo.bar/entry.html" title="Linkification: http://www.foo.bar/entry.html">http://www.example.com/entry.html</a></code>, qui ressemble à ça :</p> <pre>&lt;html manifest="example.appcache"&gt;
  &lt;h1&gt;Application Cache Example&lt;/h1&gt;
&lt;/html&gt;
</pre> <p>Si <code>entry.html</code> n'est pas inclue dans le manifest, visiter la page <code>entry.html</code> provoquera l'ajout de la page <code>entry.html</code> dans le cache de l'application comme une master entry.</p> <h4>Fallback entries</h4> <p>Les entrées de fallback sont utilisées quand une tentative de chargement d'une ressource échoue. Par exemple, imaginons qu'il y a un fichier manifest situé à <code><a class=" external" href="http://www.example.com/example.appcache" rel="freelink">http://www.example.com/example.appcache</a></code>, et qui contient :</p> <pre>CACHE MANIFEST
FALLBACK:
example/bar/ example.html
</pre> <p>Toute requête vers <code><a class=" external" href="http://www.example.com/example/bar/" rel="freelink">http://www.example.com/example/bar/</a></code> ou n'importe lequel de ses sous-répertoires et contenus provoquera une tentative de chargement de la ressource demandée. Si la tentative échoue, soit à cause d'un échec réseau ou d'une erreur serveur quelle qu'elle soit, le contenu du fichier <code>example.html</code> sera chargé à la place.</p> <h4>Network entries</h4> <p>Les entrées listées dans <code>NETWORK :</code> peuvent contenir plusieurs ou aucune ressource que l'application requiert lors d'un accès en ligne. C'est principalement une <em>liste blanche en ligne</em>. Les URIS spécifiées dans la section <code>NETWORK</code> sont chargées depuis le serveur plutôt que depuis le cache. Cela permet au modèle de sécurité du navigateur de protéger l'utilisateur de possibles brèches de sécurité en limitant l'accès aux seules ressources approuvées.</p> <div class="note"><strong>Note :</strong> La <em>liste blanche en ligne</em> est ignorée pour les versions de Firefox antérieures à 3.5.</div> <p>Vous pouvez l'utiliser pour, par exemple, charger et exécuter des scripts et d'autres codes depuis le serveur au lieu du cache. :</p> <pre>CACHE MANIFEST
NETWORK:
/api
</pre> <p>Ceci assure que les requêtes téléchargent les ressources contenues dans <code><a class=" external" href="http://www.example.com/api/" rel="freelink">http://www.example.com/api/</a></code> viendront toujours du réseau sans essayer d'accéder au cache.</p> <div class="note"><strong>Note </strong>: Juste omettre les <em>master entries</em> (les fichiers qui ont l'attribut <code>manifest</code> défini dans l'élément <code>html</code>) dans le manifest n'aurait pas le même comportement parce que les <em>master entries</em> seront ajoutées — et donc servies depuis— le cache. </div> <h2>Le Manifest</h2> <p>Les fichiers manifests doivent être servis avec le type MIME <code>text/cache-manifest</code>, et toutes les ressources servies en utilisant ce type MIME doivent respecter la syntaxe d'un manifest, comme défini ici. Les manifests sont des fichiers textes au format UTF-8 et peuvent, éventuellement, inclure un caractère BOM. Les nouvelles lignes peuvent être représentés par saut de ligne (<code>U+000A</code>), retour chariot (<code>U+000D</code>), ou les deux.</p> <p>La première ligne du manifest doit être la chaine <code>CACHE MANIFEST</code> (séparé par un simple espace <code>U+0020</code>), suivi par aucun ou plusieurs espaces ou tabulations. Tout autre texte sur la ligne sera ignoré.</p> <p>Le reste du manifest peut contenir 0 ou plusieurs lignes :</p> <dl> <dt>Blank line</dt> <dd>Vous pouvez utiliser les lignes vides comprenant 0 ou plusieurs espaces ou tabulations.</dd> <dt>Comment</dt> <dd>Les commentaires consistent en 0 ou plusieurs espaces ou tabulations suivis du caractère <code>#</code>, suivi de 0 ou plusieurs caractères de texte. Les commentaires devraient être utilisés seulement sur leur propre ligne, et ne devrait pas être ajoutés à d'autres lignes. This also means that you cannot specify fragment identifiers.</dd> <dt>Section header</dt> <dd>Section headers specify which section of the cache manifest is being manipulated. There are three possible section headers:</dd> </dl> <blockquote> <table class="standard-table"> <tbody> <tr> <th>Section header</th> <th>Description</th> </tr> <tr> <td><code>CACHE:</code></td> <td>Switches to the explicit section. This is the default section.</td> </tr> <tr> <td><code>FALLBACK:</code></td> <td>Switches to the fallback section. <p>{{ fx_minversion_note("3") }}</p> </td> </tr> <tr> <td><code>NETWORK:</code></td> <td>Switches to the online whitelist section. <p>{{ fx_minversion_note("3") }}</p> </td> </tr> </tbody> </table> </blockquote> <dl> <dd>The section header line may include whitespaces, but must include the colon (<code>:</code>) in the section name.</dd> <dt>Section data</dt> <dd>The format for lines of data varies from section to section. In the explicit (<code>CACHE:</code>) section, each line is a valid URI or IRI reference to a resource to cache (no wildcard characters are allowed in this sections). Whitespace is allowed before and after the URI or IRI on each line. In the Fallback section each line is a valid URI or IRI reference to a resource, followed by a fallback resource that is to be served up when a connection with the server cannot be made. In the network section, each line is a a valid URI or IRI reference to a resource to fetch from the network (the wildcard * is allowed in this section).</dd> </dl> <p>Cache manifests may switch back and forth from section to section at will (each section header can be used more than once), and sections are allowed to be empty.</p> <div class="note"><strong>Note: </strong>Relative URIs are relative to the cache manifest's URI, not to the URI of the document referencing the manifest.</div> <h4 name="A_sample_cache_manifest">A sample cache manifest</h4> <p>The following is a simple cache manifest <code>example.appcache</code> for an imaginary web site at <span class="nowiki">www.example.com</span>.</p> <pre class="eval">CACHE MANIFEST
# v1 - 2011-08-13
# This is a comment.
<span class="nowiki">http://www.example.com/index.html</span>
<span class="nowiki">http://www.example.com/header.png</span>
<span class="nowiki">http://www.example.com/blah/blah</span>
</pre> <p>In this example, thee is no section header, so all data lines are assumed to be in the explicit (<code>CACHE:</code>) section. You can also specify relative URLs (<code>index.html</code>, etc.)</p> <p>The "v1" comment is there for a good reason. Because the cache is only updated when the manifest changes, byte for byte. If you change the resources (for example, updating the <code>header.png</code> image with new content), you need to change the manifest file contents in order to let the browser know that it needs to refresh the cache (and since <code>header.png</code> is already in the manifest file, you need to change something else). You can do this by any change to the manifest, but having a version number is the recommended best practice.</p> <div class="warning"><strong>Important:</strong> Do not specify the manifest itself in the cache manifest file otherwise it will be nearly impossible to inform the browser a new manifest is available.</div> <p>The following is a more complete cache manifest for the same, imaginary web site at <span class="nowiki">www.example.com</span>. This example also uses the <code>FALLBACK</code> and <code>NETWORK</code> sections to specify that the <code>network.html</code> page must always be retrieved from the network and that the <code>fallback.html</code> page should be served as a fallback resource. For example, in case a connection to the server cannot be established.</p> <pre class="eval">CACHE MANIFEST
# v1 2011-08-14
# This is another comment
index.html
cache.html
style.css
image1.png

# Fallback content
FALLBACK:
/ fallback.html

# Use from network if available
NETWORK:
network.html
</pre> <p> </p> <h2>Specifying a cache manifest</h2> <p>To use application cache, you need to use the <code>manifest</code> attribute in the <code>html</code> element as shown in the following example:</p> <pre class="eval"><span class="nowiki">&lt;html manifest="example.appcache"&gt; </span>
  ...
&lt;/html&gt;
</pre> <p>Some browsers like Firefox will display a notification bar the first time the user loads your application saying "This website (<code>www.example.com</code>) is asking to store data on your computer for offline use. [Allow] [Never for This Site] [Not Now]". The term "Offline(-enabled) applications" sometimes refers specifically to applications allowed by the user to use the offline capabilities.</p> <h2>The update process</h2> <ol> <li>When the browser visits a document that includes a <code>manifest</code> attribute and if no application cache exists yet, it will load the document and then fetch all the entries listed in the manifest file, creating the first version of the application cache. </li> <li>Subsequent visits to that document will trigger the browser to load the document and other assets specified in the manifest file from the application cache (not from the server) and in addition the browser will also send a <code>checking</code> event to the <code><a href="/en/DOM/window.applicationCache" title="en/DOM/window.applicationCache">window.applicationCache</a></code> object, then fetches the manifest file, following the appropriate HTTP caching rules. If the currently-cached copy of the manifest is up-to-date, the <code>noupdate</code> event is sent to the <code>applicationCache</code>, and the update process is complete. (This is why if you change any resources on the server, you need to also change the manifest file so the browser knows it needs to fetch all the resources again.</li> <li>If the manifest file <em>has</em> changed, all files in the manifest—as well as those added to the cache by calling <code><a href="/en/nsIDOMOfflineResourceList#add.28.29" title="en/nsIDOMOfflineResourceList#add.28.29">applicationCache.add()</a></code>—are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into this temporary cache, a <code>progress</code> event is sent to the <code>applicationCache</code> object. If any errors occur, an <code>error</code> event is sent, and the update halts.</li> <li>Once all the files have been successfully retrieved, they are moved into the real offline cache atomically, and a <code>cached</code> event is sent to the <code>applicationCache</code> object. Since the document has already been loaded into the browser from the cache, the updated document won't be rendered until the document is reloaded (either manually or programatically).</li> </ol> <h2>Testing for updates</h2> <p>Testing to see if an application has an updated cache manifest available can be done programmatically through Javascript. Since the cache may have been updated before any script using events to test for updates, scripts should always test <code>window.applicationCache.status</code>.</p> <pre class="brush: js">function onUpdateReady() {
  alert('found new version!');
}
window.applicationCache.addEventListener('updateready', onUpdateReady);
if(window.applicationCache.status === window.applicationCache.UPDATEREADY) {
  onUpdateReady();
}</pre> <p> To manually start testing for a new manifest you can use <code>window.applicationCache.update()</code>.</p> <h2>Gotchas</h2> <ul> <li>Since applications are using a cache, simply updating the files served under web pages is not enough to update files that have been cached. Updating the manifest will be required before the files are using their new source. This can be done programmatically through <code>window.applicationCache.swapCache()</code>, but already loaded resources will not be affected. In order to ensure resources are loaded from new version of the application cache refreshing the page is ideal.</li> <li>it is a good idea to set expires headers on your web server for <code>*.appcache</code> files to expire immediately to avoid the risk of caching the manifest files. For example, in Apache you can configure this as follows:<br> <code>ExpiresByType text/cache-manifest "access plus 0 seconds"</code></li> </ul> <h2>Storage location and clearing the offline cache</h2> <p>In Chrome you can clear the offline cache by selecting "Clear browsing data..." in the preferences or by visiting <a class="external" href="chrome://appcache-internals/" title="chrome://appcache-internals/">chrome://appcache-internals/</a>. Safari has a similar "Empty cache" setting in its preferences but a browser restart may also be required.</p> <p>In Firefox, the offline cache data is stored separately from the Firefox profile—next to the regular disk cache:</p> <ul> <li>Windows Vista/7: <code>C:\Users\&lt;username&gt;\AppData\<strong>Local</strong>\Mozilla\Firefox\Profiles\&lt;salt&gt;.&lt;profile name&gt;\OfflineCache</code></li> <li>Mac/Linux: <code>/Users/&lt;username&gt;/Library/Caches/Firefox/Profiles/&lt;salt&gt;.&lt;profile name&gt;/OfflineCache</code></li> </ul> <p>In Firefox the current status of the offline cache can be inspected on the <code>about:cache</code> page (under the "Offline cache device" heading).</p> <p>The offline cache is <strong>not</strong> cleared via Tools -&gt; Clear Recent History (<a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=538595" title="https://bugzilla.mozilla.org/show_bug.cgi?id=538595">bug 538595</a>)<br> The offline cache is <strong>not</strong> cleared via Tools -&gt; Options -&gt; Advanced -&gt; Network -&gt; Offline data -&gt; Clear Now (<a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=538588" title="https://bugzilla.mozilla.org/show_bug.cgi?id=538588">bug 538588</a>).<br> The offline cache can be cleared for each site separately using the "Remove..." button in Tools -&gt; Options -&gt; Advanced -&gt; Network -&gt; Offline data.</p> <p>See also <a href="/en/DOM/Storage#Storage_location_and_clearing_the_data" title="en/DOM/Storage#Storage location and clearing the data">clearing the DOM Storage data</a>.</p> <h2>Browser Compatibility</h2> <p>{{ CompatibilityTable() }}</p> <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>4.0</td> <td>3.5</td> <td>10.0</td> <td>10.6</td> <td>4.0</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>2.1</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>11.0</td> <td>3.2</td> </tr> </tbody> </table> </div> <p> </p> <h2>See also</h2> <ul> <li><a class="external" href="http://www.html5rocks.com/en/tutorials/appcache/beginner/" title="http://www.html5rocks.com/en/tutorials/appcache/beginner/">HTML5Rocks - A Beginner's Guide to Using the Application Cache</a></li> <li><a class="external" href="http://appcachefacts.info/" title="http://appcachefacts.info/">appcachefacts.info</a> - detailed information on AppCache idiosyncrasies</li> <li><a class="external" href="http://hacks.mozilla.org/2010/01/offline-web-applications/" title="http://hacks.mozilla.org/2010/01/offline-web-applications/">offline web applications</a> at hacks.mozilla.org - showcases an offline app demo and explains how it works.</li> <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/offline.html#offline" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/offline.html#offline">HTML 5 working draft: Offline web applications</a></li> <li><a class="external" href="http://developer.teradata.com/blog/js186040/2011/11/html5-cache-manifest-an-off-label-usage" title="http://developer.teradata.com/blog/js186040/2011/11/html5-cache-manifest-an-off-label-usage">HTML5 Cache Manifest: An Off-label Usage</a></li> <li>{{ interface("nsIApplicationCache") }}</li> <li>{{ interface("nsIApplicationCacheNamespace") }}</li> <li>{{ interface("nsIApplicationCacheContainer") }}</li> <li>{{ interface("nsIApplicationCacheChannel") }}</li> <li>{{ interface("nsIApplicationCacheService") }}</li> <li>{{ interface("nsIDOMOfflineResourceList") }}</li> <li><a class="external" href="http://www.ibm.com/developerworks/web/library/wa-ffox3/">Get ready for Firefox 3.0 - A Web developer's guide to the many new features in this popular browser, especially the offline application features</a> (IBM developerWorks)</li> </ul> <p>{{ HTML5ArticleTOC() }}</p> <p>{{ languages( { "es": "es/Recursos_offline_en_firefox", "fr": "fr/Ressources_hors_ligne_dans_Firefox", "ja": "ja/Offline_resources_in_Firefox", "pl": "pl/Zasoby_offline_w_Firefoksie", "zh-tw": "zh_tw/Offline_resources_on_Firefox" } ) }}</p>
</div>
Revenir à cette révision