Apache Cordova : config.xml

by karim

Le fichier config.xml de plate-forme agnostique est formaté selon spécification Emballés Web Applications (Widgets) de la W3C et étendu pour spécifier les paramètres spécifiques à la plateforme, plugins et principales fonctionnalités API Cordova.

Pour les projets créés avec l'interface en ligne de commande de Cordova (décrite dans le paragraphe "L'interface en Ligne de Commande"), ce fichier peut être trouvé dans le répertoire www à la racine du projet. L'utilisation du CLI pour créer un projet régénérera ce fichier dans les différents sous-dossiers dans platforms . Si vous utilisez le CLI pour créer un projet, mais qu'ensuite vous changez pour un SDK, le fichier spécifique à la plateforme servira de source.

Cette section décrit en détail les options de configuration globale et multi-plateforme. Consultez les sections suivantes pour les options spécifiques à la plateforme :

  • Configuration iOS
  • Configuration Android
  • Configuration BlackBerry

Outre les diverses options de configuration détaillées ci-dessous, vous pouvez également configurer ensemble de base d'une application d'images pour chaque plate-forme cible. Pour plus d'informations, consultez icônes et écrans de démarrage.

Éléments de configuration de base

Cet exemple affiche la valeur par défaut config.xml généré par le CLI create commande, décrite dans l'Interface de ligne de commande :

<widget id="com.example.hello" version="0.0.1">
<name>HelloWorld</name>
<description>
A sample Apache Cordova application that responds to the deviceready event.
</description>
<author email="dev@callback.apache.org" href="http://cordova.io">
Apache Cordova Team
</author>
<content src="index.html" />
<access origin="*" />
<preference name="Fullscreen" value="true" />
<preference name="WebViewBounce" value="true" />
</widget>

Les éléments de configuration suivants apparaissent dans le premier niveau config.xml du fichier et sont pris en charge sur toutes les plateformes prises en charge de Cordoue :

  • La <widget> de l'élément id attribut fournit l'identificateur de domaine inverse du PPA et les version son numéro de version complet exprimé en notation majeur/mineur/patch.
  • L'élément <name> spécifie le nom formel de l'application, tel qu'il apparaît sur l'écran d'accueil de l'appareil et dans le app-store.
  • Le <description> et <author> éléments spécifient les métadonnées et les informations de contact qui peuvent apparaître au sein de l'app-store listings.
  • Le paramètre optionnel <content> élément définit la page de démarrage de votre application dans le répertoire actif de web de niveau supérieur. La valeur par défaut est index.html , qui apparaît habituellement dans le dossier de niveau supérieur du projet, www.
  • Les éléments <access> définissent l'ensemble des domaines externes avec lesquels l'application est autorisée à communiquer. La valeur par défaut ci-dessus permet d'accéder à n'importe quel serveur. Consultez le Guide de liste blanche de domaine pour plus de détails.
    • La balise <preference> définit différentes options sous forme de paires d'attributs name / value. Le name de chaque préférence est insensible à la casse. Plusieurs préférences sont spécifiques à certaines plateformes, comme indiqué en haut de cette page. Les sections suivantes détaillent les préférences qui s'appliquent à plus d'une plateforme.

Gestion des versions supplémentaires

Fois, Android et iOS prend en charge une deuxième chaîne de la version (ou nombre) en plus de celui visible dans l'app store, versionCode pour Android et CFBundleVersion pour iOS. Voici un exemple qui définit explicitement versionCode et CFBundleVersion <widget id="io.cordova.hellocordova"
version="0.0.1"
android-versionCode="7"
ios-CFBundleVersion="3.3.3"> Si la version alternative n'est pas spécifiée, les paramètres par défaut suivants seront utilisés : // assuming version = MAJOR.MINOR.PATCH-whatever
versionCode = PATCH + MINOR * 100 + MAJOR * 10000
CFBundleVersion = "MAJOR.MINOR.PATCH"

Préférences globales

Les préférences globales suivantes s'appliquent à toutes les plateformes :
  • Fullscreen permet de masquer la barre d'état en haut de l'écran. La valeur par défaut est false . Exemple : <preference name="Fullscreen" value="true" />
  • Orientation permet de verrouiller l'orientation et d'empêcher toute rotation en réponse aux changements dans l'orientation de l'interface. Les valeurs possibles sont default , landscape , ou portrait . Exemple : <preference name="Orientation" value="landscape" />
Remarque : La valeur default signifie les orientations portrait et paysage sont toutes les deux activées. Si vous souhaitez utiliser les paramètres par défaut de chaque plateforme (habituellement portrait uniquement), effacez cette balise du fichier config.xml. Aussi, BlackBerry utilise auto au lieu de default dans son fichier config.xml. Si vous spécifiez default dans le fichier config.xml global, cela se traduit par auto lors de la compilation pour BlackBerry.

La fonctionnalité élément

Si vous utilisez la CLI pour créer des applications, vous utilisez la commande plugin pour activer le dispositif API. Cela ne modifie pas le fichier de niveau supérieur config.xml , aussi l'élément < feature > ne s'applique pas à votre flux de travail. Si vous êtes travaillant directement dans un kit de développement logiciel et à l'aide de la plate-forme spécifique config.xml fichier source, vous utilisez le tag pour permettre aux API de niveau périphérique et des plugins externes. Elles apparaissent souvent avec des valeurs personnalisées dans les fichiers spécifiques à une plateforme config.xml .
Par exemple, voici comment spécifier l'API Device pour les projets Android <feature name="Device">
   <param name="android-package" value="org.apache.cordova.device.Device" />
</feature> Voici l'apparence de l'élément pour les projets d'iOS : <feature name="Device">
   <param name="ios-package" value="CDVDevice" />
</feature> Voir la référence de l'API pour plus d'informations sur la façon de spécifier chaque fonctionnalité. Consultez le Guide de développement de Plugin pour plus d'informations sur les plugins.

La plate-forme élément

Lorsque vous utilisez l'interface CLI pour créer des applications, il est parfois nécessaire de spécifier les préférences ou autres éléments spécifiques à une plate-forme particulière. Utilisez l'élément < platform > pour spécifier la configuration qui doit uniquement apparaître dans un fichier unique spécifique à la plateforme config.xml.
Par exemple, voici comment spécifier que seul android devrait utiliser les préférences de plein écran : <platform name="android">
   <preference name="Fullscreen" value="true" />
</platform>

Le hook élément

Représente votre script personnalisé qui sera appelé par Cordova en cas de certaines actions (par exemple, est appelé après plugin est ajouté ou plate-forme préparer logique). Ceci est utile lorsque vous avez besoin d'étendre les fonctionnalités de Cordoue par défaut. Voir Guide de crochets pour plus d'informations. <hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />