Cordova - Config.xml 文件

Cordova - 理解 config.xml 文件

config.xml 文件是一个必需的全局配置文件，位于 Cordova 项目的根目录中。它控制着应用行为、外观和元数据的许多方面。它是一个基于 W3C Packaged Web Apps (Widgets) 规范的 XML 文档，并包含 Cordova 特有的扩展。

当您创建一个 Cordova 项目（例如，使用 cordova create）时，会生成一个默认的 config.xml 文件。您将修改此文件来定制您的应用。

核心 config.xml 元素 (Elements)

以下是您将在 config.xml 中找到并使用的基本元素概览：

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.example.myapp" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>MyAwesomeApp</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="http://cordova.io">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <access origin="*" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
    <allow-intent href="tel:*" />
    <allow-intent href="sms:*" />
    <allow-intent href="mailto:*" />
    <allow-intent href="geo:*" />

    <platform name="android">
        <allow-intent href="market:*" />
        <!-- Android-specific preferences and configurations -->
        <!-- Android 特定的首选项和配置 -->
        <preference name="ScrollEnabled" value="false" />
    </platform>
    <platform name="ios">
        <allow-intent href="itms:*" />
        <allow-intent href="itms-apps:*" />
        <!-- iOS-specific preferences and configurations -->
        <!-- iOS 特定的首选项和配置 -->
        <preference name="BackupWebStorage" value="cloud" />
    </platform>

    <!-- Preferences (global or platform-specific) -->
    <!-- 首选项（全局或特定于平台） -->
    <preference name="DisallowOverscroll" value="true" />
    <preference name="Orientation" value="default" />

    <!-- Plugins are typically added here automatically by 'cordova plugin add' -->
    <!-- 插件通常由 'cordova plugin add' 自动添加到此处 -->
    <!-- Example of a manually declared plugin (less common now) -->
    <!-- 手动声明插件的示例（现在不太常见） -->
    <!-- <plugin name="cordova-plugin-device" spec="~2.0.3" /> -->

    <!-- Icons and Splash Screens -->
    <!-- 图标和启动画面 -->
    <icon src="res/icon.png" />
    <platform name="android">
        <icon density="ldpi" src="res/android/icon-ldpi.png" />
        <icon density="mdpi" src="res/android/icon-mdpi.png" />
        <!-- ... more densities -->
        <!-- ... 更多密度 -->
        <splash density="land-hdpi" src="res/screen/android/splash-land-hdpi.png" />
        <!-- ... more splash screens -->
        <!-- ... 更多启动画面 -->
    </platform>
    <platform name="ios">
        <icon height="57" platform="ios" src="res/ios/icon-57.png" width="57" />
        <!-- ... more icon sizes -->
        <!-- ... 更多图标尺寸 -->
        <splash height="480" platform="ios" src="res/screen/ios/splash-iphone-portrait.png" width="320" />
        <!-- ... more splash screens -->
        <!-- ... 更多启动画面 -->
    </platform>
</widget>

关键元素解释

元素 / 属性 (Element / Attribute)	描述与用途 (Description & Purpose)
<widget>	config.xml 文件的根元素。关键属性：
id	您的应用的反向域名式标识符（例如 com.example.myapp）。这对于应用商店提交至关重要。
version	您的应用的 版本号 (version number)（例如 1.0.0）。遵循 语义化版本控制 (semantic versioning) (Major.Minor.Patch)。
xmlns	W3C widget 的 XML 命名空间 (http://www.w3.org/ns/widgets)。
xmlns:cdv	Cordova 特有扩展的 XML 命名空间 (http://cordova.apache.org/ns/1.0)。
<name>	应用的 显示名称 (display name)，显示在设备主屏幕或应用列表中。
<description>	应用的简短描述。可能用于应用商店列表。
<author>	关于应用作者的信息。属性：email, href (网站)。
<content src=”…” />	指定应用的起始页面 (entry point)。通常是位于 www 目录中的 index.html。
<access origin=”…” />	控制应用允许发起的网络请求（域名）。origin=”*” 允许访问任何域名。为了更好的安全性，请将其限制为您的应用所需的域名。这与 cordova-plugin-whitelist 和 CSP meta 标签协同工作。（已弃用，推荐使用 allow-navigation 进行顶层导航，但对于 XHR/Fetch 等子请求仍然相关）。
<allow-intent href=”…” />	定义应用允许系统打开的 URL。例如，tel: 允许启动拨号器，http:/// 和 https:///* 允许在系统浏览器中打开网页链接（不在应用的 WebView 内）。
<allow-navigation href=”…” />	控制 WebView 本身可以导航到的 URL。如果未指定，则只允许导航到 file:// URL。使用此标签允许在应用内导航到远程 HTTP/HTTPS 网站。例如：<allow-navigation href=“https://.mycompany.com/” />。
<platform name=”…”> … </platform>	特定平台配置的容器。常见平台：android, ios, browser, windows。
<preference name=”…” value=”…” />	设置应用的各种选项。首选项可以是全局的（直接在 <widget> 下）或特定于平台的（在 <platform> 块内部）。示例：
<plugin name=”…” spec=”…” />	声明项目使用的插件。虽然您主要使用 cordova plugin add/rm …（它会更新 package.json 和 config.xml 或 plugin_list.json），但此元素显示已安装的插件。spec 可以是版本号、git URL 或本地路径。
<icon src=”…” /> 和 <splash src=”…” />	定义应用图标 (icons) 和启动画面 (splash screens)。您可以指定默认图标/启动画面，然后使用 platform, density, width, height 等属性指定不同尺寸、密度 (density) 或方向 (orientation) 的特定平台版本。
<edit-config file=”…” target=”…” mode=”…”> … </edit-config>	允许直接从 config.xml 修改特定平台配置文件，例如 AndroidManifest.xml (Android) 或 *-Info.plist (iOS)。对于设置标准首选项未覆盖的属性或添加元素很有用。
<resource-file src=”…” target=”…” />	在 prepare 过程中将文件从您的 Cordova 项目复制到原生平台项目。对于向原生构建 (native build) 添加自定义资源、声音文件或配置文件很有用。

最佳实践与技巧

• 版本控制 (Version Control)：始终将 config.xml 置于版本控制下（例如 Git）。
• 特定平台设置：使用 <platform name=”…”> 块来存放仅适用于某个平台的设置。
• 首选项：查阅 Cordova 文档，获取所有可用的全局和特定平台首选项的完整列表。常见的包括控制方向、全屏模式、 webview 行为等。
• 图标和启动画面：为各种分辨率 (resolutions) 和设备类型提供图标和启动画面对于专业的应用外观至关重要。像 cordova-res 这样的工具可以帮助自动化生成它们。
• 白名单 (Whitelist) 和 CSP：密切关注 <access>, <allow-intent> 和 <allow-navigation> 标签，以及 index.html 中的 内容安全策略 (CSP) <meta> 标签。这些对于安全性至关重要，它们控制着您的应用可以访问什么以及可以加载什么资源。
• 自动与手动编辑：Cordova CLI 命令（如 cordova plugin add 或 cordova platform add）通常会自动修改 config.xml。手动编辑时要小心，尤其是在 CLI 管理的部分。
• 阅读文档：Cordova 官方关于 config.xml 的文档是关于所有元素、属性和特定平台行为的权威来源：Config.xml 参考。

配置良好的 config.xml 对于构建强大且精美的 Cordova 应用至关重要。花时间理解其元素及其如何影响应用的 构建 (build) 和 运行时 (runtime) 行为。