CartoCSS 技术文档

2024-12-24 09:19:47作者：何将鹤

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) {
    // 程序失败
    ...
}