Less - 程序化使用

Less - Programmatic Usage

Less 可以在 Node.js 环境中以编程方式编译，这对于将其集成到构建系统（build systems）和自动化工作流程（automated workflows）中至关重要。核心函数是 less.render。

使用 `less.render`

less.render 函数接受 Less 代码字符串、一个可选的选项对象（options object），并且可以与 Promise（推荐）或回调函数（callback）一起使用。

基于 Promise（推荐）：

less.render(lessInputString, options)
    .then(function(output) {
        // output.css = string of compiled CSS
        // output.map = string of sourcemap (if generated)
        // output.imports = array of imported filenames
        console.log(output.css);
    })
    .catch(function(error) {
        // error object with message, line, column, etc.
        console.error(error);
    });

使用 async/await 使异步代码更整洁：

async function compileLess(lessInputString, options) {
  try {
    const output = await less.render(lessInputString, options);
    console.log('CSS:', output.css);
    if (output.map) {
      console.log('Source Map:', output.map);
    }
    // Use output.css and output.map
  } catch (error) {
    console.error('Less Compilation Error:', error);
  }
}

回调风格：

less.render(lessInputString, options, function(error, output) {
    if (error) {
        console.error(error);
        return;
    }
    // output.css, output.map, output.imports
    console.log(output.css);
});

参数

lessInputString: 包含要编译的 Less 代码的字符串。
options: 配置编译过程的可选对象。关键选项包括：
filename: (String) 输入 Less 代码的文件名。对于错误报告、解析相对的 @import 路径以及生成 source map 至关重要。
paths: (Array of Strings) 用于查找 @import 导入文件的路径列表。
plugins: (Array) 要使用的 Less 插件（plugins）。
sourceMap: (Object) 用于生成 source map 的选项（例如，sourceMapFileInline: true 将 source map 嵌入到 CSS 中）。
javascriptEnabled: (Boolean) 设置为 false 可禁用 Less 文件中的内联 JavaScript 执行（出于安全考虑推荐）。
math: (String) 设置数学计算的严格性，例如 strict（以前是 strictMath: true）。详情请参阅命令行选项。

自定义日志记录器

要捕获来自 Less 编译器的日志消息（例如，警告warnings、调试信息debug info），可以添加自定义日志记录器（logger）：

less.logger.addListener({
    debug: function(message) { console.debug('[LESS DEBUG]', message); },
    info: function(message) { console.info('[LESS INFO]', message); },
    warn: function(message) { console.warn('[LESS WARN]', message); },
    error: function(message) { console.error('[LESS ERROR]', message); }
});

监听器函数（debug, info, warn, error）都是可选的。如果发生编译错误且未被自定义错误日志记录器处理，它将被传递给 error 回调或拒绝 less.render 返回的 Promise。

示例：编译文件

这是一个读取 Less 文件并编译的简单示例：

// Assuming 'less' and 'fs' (Node.js file system module) are required
// const less = require('less');
// const fs = require('fs').promises;

async function compileMyLessFile(filePath, outputPath) {
  try {
    const lessInput = await fs.readFile(filePath, 'utf8');
    const options = {
      filename: filePath, // Important for imports and error reporting
      sourceMap: {
        sourceMapFileInline: true // Example: Embed sourcemap in CSS
      }
    };
    const output = await less.render(lessInput, options);
    await fs.writeFile(outputPath, output.css, 'utf8');
    console.log(`Successfully compiled ${filePath} to ${outputPath}`);
    // if (output.map && !options.sourceMap.sourceMapFileInline) {
    //   await fs.writeFile(outputPath + '.map', output.map, 'utf8');
    // }
  } catch (error) {
    console.error('Less compilation error details:', error);
    // For more structured error output:
    // console.error(`Message: ${error.message}`);
    // console.error(`File: ${error.filename}:${error.line}:${error.column}`);
  }
}

// Usage:
// compileMyLessFile('src/styles.less', 'dist/styles.css');

实际场景与进一步阅读

构建系统（Build Systems）： 程序化使用是 Less 集成到现代构建工具（如 Webpack (使用 less-loader)、Gulp (使用 gulp-less) 或 Parcel (通常内置支持 Less)）中的关键。这些工具管理编译、文件监听（watching files）以及其他资产处理。
动态主题（Dynamic Theming）： 服务器端应用程序可以使用程序化 Less 编译来根据用户偏好或运行时数据（例如，通过 less.render 中的 globalVars 或 modifyVars 选项传递变量）动态生成 CSS。
错误处理（Error Handling）： 在 catch 块或错误回调函数中进行稳健的错误处理对于在开发过程中提供有用的反馈非常重要。来自 Less 的错误对象包含详细信息，如文件名（filename）、行号（line number）和列号（column）。
官方 API 文档： 有关所有选项和功能的最新、最详细信息，请参阅 Less 官方 API 文档：http://lesscss.org/usage/#programmatic-usage