Cordova-Common 技术文档

本文档将详细介绍如何安装、使用以及 Cordova-Common 项目的 API 调用方法。

1. 安装指南

在开始使用 Cordova-Common 之前，您需要按照以下步骤安装它：

1. 克隆此存储库到您的本地计算机：

   git clone https://github.com/apache/cordova-common.git
   

2. 切换到 cordova-common 目录，安装依赖项并执行 npm-link：

   cd cordova-common && npm install && npm link
   

3. 切换到 cordova-lib 目录并将 cordova-common 链接：

   cd <cordova-lib 目录> && npm link cordova-common && npm install
   

2. 项目使用说明

Cordova-Common 项目提供了一些共享功能，被 cordova-lib 和 Cordova 平台使用。以下是项目中的主要功能模块及其用法：

events

events 模块是一个特殊的 NodeJS EventEmitter 实例，用于向 cordova-lib 和 cordova-cli 发送事件。

使用方法：

const { events } = require('cordova-common');
events.emit('warn', '警告信息');

以下是 cordova-cli 支持的事件：

• verbose
• log
• info
• warn
• error

CordovaError

CordovaError 是一个错误类，用于抛出 cordova 特定的错误。CordovaError 类从 Error 继承，因此它是 Error 的有效实例（instanceof 检查成功）。

使用方法：

const { CordovaError } = require('cordova-common');
throw new CordovaError('错误信息', 错误代码);

ConfigParser

ConfigParser 模块提供了处理 cordova 项目 config.xml 文件的功能。有关 ConfigParser API 的详细信息，请查看 ConfigParser Readme。

使用方法：

const { ConfigParser } = require('cordova-common');
const appConfig = new ConfigParser('path/to/cordova-app/config.xml');
console.log(`${appConfig.name()}:${appConfig.version()}`);

PluginInfoProvider 和 PluginInfo

PluginInfo 是 cordova 插件 plugin.xml 文件的包装器。这个类可以直接实例化，也可以通过 PluginInfoProvider 实例化。不同之处在于 PluginInfoProvider 会基于插件源目录缓存 PluginInfo 实例。

使用方法：

const { PluginInfo, PluginInfoProvider } = require('cordova-common');

// 以下实例相等
const plugin1 = new PluginInfo('path/to/plugin_directory');
const plugin2 = new PluginInfoProvider().get('path/to/plugin_directory');

console.log(`插件 ${plugin1.id} 的版本是 ${plugin1.version}`);

ActionStack

ActionStack 是一个用于处理顺序任务的实用模块。它提供了一组需要执行的任务，如果其中一个任务失败，则会回滚已经完成的任务。这个模块内部被 cordova-lib 和平台插件安装例程使用。

使用方法：

const { ActionStack } = require('cordova-common');

const stack = new ActionStack();
const action1 = stack.createAction(task1, [任务参数], task1_reverter, [回滚参数]);
const action2 = stack.createAction(task2, [任务参数], task2_reverter, [回滚参数]);

stack.push(action1);
stack.push(action2);

stack.process()
    .then(() => {
        // 所有任务成功
    })
    .catch(error => {
        // 有一个任务失败，错误信息
    });

superspawn

superspawn 模块用于创建具有高级逻辑的子进程。

使用方法：

const { superspawn } = require('cordova-common');

superspawn.spawn('adb', ['devices'])
    .progress(data => {
        if (data.stderr) console.error(`"adb devices" 出现错误: ${data.stderr}`);
    })
    .then(devices => {
        // 执行操作...
    });

xmlHelpers

xmlHelpers 是一组处理 XML 文件的实用方法。

使用方法：

const { xmlHelpers } = require('cordova-common');

const doc1 = xmlHelpers.parseElementtreeSync('some/xml/file');
const doc2 = xmlHelpers.parseElementtreeSync('another/xml/file');

xmlHelpers.mergeXml(doc1, doc2); // doc2 现在包含 doc1 中的所有节点

3. 项目 API 使用文档

以下是 Cordova-Common 项目中暴露的一些 API：

• events：事件发射器，用于发送事件。
• CordovaError：用于抛出 cordova 特定的错误。
• ConfigParser：用于处理 cordova 项目的 config.xml 文件。
• PluginInfoProvider 和 PluginInfo：用于处理 cordova 插件的 plugin.xml 文件。
• ActionStack：用于处理顺序任务。
• superspawn：用于创建子进程。
• xmlHelpers：用于处理 XML 文件。

更多详细信息，请参考相应的模块文档。