CartoCSS 技术文档

1. 安装指南

如果您使用的是地图设计应用程序，如 Kosmtik、Mapbox Studio Classic 或 Tilemill，您已经预装了 CartoCSS，并可能对语言参考更感兴趣。

否则，您可以通过运行以下命令，使用 NPM 安装 carto 二进制文件：

npm install -g carto

您可以考虑使用 Node.js 版本管理器，例如 NVM。可选地，您还可能希望安装 millstone，这对于在 mml 文件中解析数据与 Mapbox Studio Classic 保持一致是必需的：

npm install -g millstone

安装 millstone 可以特别启用对本地化外部资源（URL 和本地文件）的支持，以及检测投影（使用 node-srs）。

2. 项目使用说明

安装 Carto 后，您应该拥有一个可在 CartoCSS 项目上运行的命令行工具 carto：

carto project.mml > mapnik.xml

可用参数：

• -a / --api VERSION：指定 Mapnik API 版本（例如 --api 3.0.10）（默认：最新的 Mapnik API 版本）
• -b / --benchmark：输出总编译时间
• -f / --file：输出到指定的文件而不是 stdout
• -h / --help：显示帮助信息
• -l / --localize：在加载 MML 时使用 millstone 进行本地化（默认：关闭）
• -n / --nosymlink：使用绝对路径而不是符号链接文件
• -o / --output：指定输出格式，可能的值为 mapnik 和 json（默认：mapnik）
• -ppi RESOLUTION：每英寸像素数，用于将 m、mm、cm、in、pt、pc 转换为像素（默认：90.714）
• -q / --quiet：不输出任何警告（默认：关闭）
• -v / --version：显示版本信息

此外，Carto 可以从 JavaScript 中使用。Renderer 接口是开发者的主要 API，它接受一个 MML 文件字符串作为输入。

// 定义变量：
// - input（正在解析的文件的名称或标识符）
var carto = require('carto');

try {
    var data = fs.readFileSync(input, 'utf-8');
    var mml = new carto.MML({});
    mml.load(path.dirname(input), data, function (err, data) {
        var output = {};

        if (!err) {
            output = new carto.Renderer({
                filename: input
            }).render(data);
        }

        if (output.msg) {
            output.msg.forEach(function (v) {
                if (v.type === 'error') {
                    console.error(carto.Util.getMessageToPrint(v));
                }
                else if (v.type === 'warning') {
                    console.warn(carto.Util.getMessageToPrint(v));
                }
            });
        }

        // 输出内容（如果没有错误）
        if (output.data) {
            console.log(output.data);
        }
    });
} catch (err) {
    // 程序失败
    ...
}

如果您想在浏览器中使用 CartoCSS，您不应通过 carto.MML.load 加载 MML。相反，您应该直接将 MML 的 JSON 包括样式表字符串传递给 carto.Renderer.render。

3. 项目 API 使用文档

Carto 的主要 API 是 Renderer 接口，它接受一个 MML 文件的字符串作为输入。具体的使用方法和示例代码，请参考上文中的“项目使用说明”。

4. 项目安装方式

CartoCSS 的安装方式如下：

• 通过 NPM 安装 carto 二进制文件。
• 可选安装 millstone 以支持本地化资源和投影检测。

具体的安装命令请参考上文中的“安装指南”。