Flutter日志记录插件log_me的使用

log_me 是一个具有可配置颜色和日志级别的简单日志工具，其底层使用了简单的 print 函数。需要注意的是，你的控制台必须支持 ANSI 转义码以便颜色可见。

目录

• 开始使用
• 使用方法
  • 文件输出
• 配置
• 路线图

开始使用

1. 添加依赖

在 pubspec.yaml 文件中添加 log_me 依赖：

dependencies:
  log_me: ^0.1.0

或者从 GitHub 拉取：

dependencies:
  log_me:
    git:
      url: https://github.com/lapuske/log_me.git

2. 导入并使用

导入 log_me 包并使用它：

import 'package:log_me/log_me.dart';

void main() {
  Log.print('Hello, world!');
}

或者使用别名：

import 'package:log_me/log_me.dart' as me;

void main() {
  me.Log.print('Hello, world!');
}

使用方法

详细的使用示例可以在 /example 目录中找到。

import 'package:log_me/log_me.dart';

void main() {
  // 可选配置。
  Log.options = LogOptions(level: LogLevel.all);

  // 打印带有 info 级别的消息。
  Log.info('Hello, world!');

  // 打印错误信息。
  Log.error('Error happened, sadly...');

  // 打印带有 debug 级别的消息。
  //
  // `toString()` 将被调用，因此你可以传递任何对象。
  Log.debug([0, 1, 2]);
}

文件输出

目前，通过 LogOptions.output 参数可以将日志输出到文件，例如：

Log.options = LogOptions(
  output: (record, options) {
    // 日志文件。
    final File file = File('log.txt');

    // 追加格式化后的记录到文件。
    file.writeAsStringSync(
      // 注意，你可以在不同的 `LogOptions` 中使用不同的选项，例如在控制台和文件中看到不同的输出。
      //
      // 记住，ANSI 转义码不会渲染颜色，这主要是控制台的功能，所以确保使用 `LogColors.none`。
      //
      // 注意，每个记录都会调用此函数，所以你需要自己检查 `LogLevel` 是否需要将此记录写入文件。
      '${record.format(options.copyWith(colors: LogColors.none))}\n',
      mode: FileMode.append,
    );

    // 调用默认输出（如果记录级别高于或等于设置的 `LogOptions.level` 则执行 `print`）。
    LogOptions.defaultOutput(record, options);
  },
);

配置

支持的颜色

• 白色
• 黑色
• 红色
• 黄色
• 蓝色
• 品红色
• 青色

日志级别

• 全部
• 致命
• 错误
• 警告
• 信息
• 调试
• 跟踪

日志记录器选项

/// 指示是否记录记录的日期。
///
/// 示例：
/// * `2023-09-30`
final bool dateStamp;

/// 指示是否记录记录的时间。
///
/// 示例：
/// * `06:53:45.000030`
final bool timeStamp;

/// 指示是否记录记录的日志级别。
///
/// 示例：
/// * `INFO`
/// * `SEVERE`
final bool levelStamp;

/// 指示日期和/或时间是否为 UTC。
///
/// 仅当 `[dateStamp]` 或 `[timeStamp]` 为 `true` 时才有意义。
final bool utc;

/// 最低 `[LogLevel]` 级别用于记录。
final LogLevel level;

/// 日志颜色。
final LogColors colors;

/// 当获取新的 `[LogRecord]` 时调用的回调。
///
/// 如果未指定，则日志记录器使用 `[defaultOutput]`。
///
/// 注意，你可以在该回调中调用 `[defaultOutput]`：
///
/// ```dart
/// output: (record, options) {
///   final File file = File('log.txt');
///
///   file.writeAsStringSync(
///     '${record.format(options.copyWith(colors: LogColors.none))}\n',
///     mode: FileMode.append,
///   );
///
///   LogOptions.defaultOutput(record, options);
/// }
/// ```
final void Function(LogRecord record, LogOptions options) output;

路线图

• ❌ Sentry 集成

示例代码

以下是一个完整的示例代码：

import 'package:log_me/log_me.dart';
import 'dart:io';

void main() {
  // 设置选项（可选）。
  Log.options = LogOptions(
    level: LogLevel.all, // 默认是 `[LogLevel.info]`。
    timeStamp: false, // 默认是 `true`。
    dateStamp: false, // 默认是 `true`。
    levelStamp: false, // 默认是 `true`。
    colors: LogColors(
      fatal: LogColor.red, // 默认是 `[LogColor.red]`。
      error: LogColor.red, // 默认是 `[LogColor.red]`。
      warning: LogColor.yellow, // 默认是 `[LogColor.yellow]`。
      info: LogColor.black, // 默认是 `[LogColor.green]`。
      debug: LogColor.blue, // 默认是 `[LogColor.blue]`。
      trace: LogColor.magenta, // 默认是 `[LogColor.magenta]`。
    ),
    output: (record, options) {
      // 这是默认输出。
      //
      // 你可以在这个回调中对记录进行操作，或者通过不同的媒介（如文件）输出。
      LogOptions.defaultOutput(record, options);
    },
  );

  // 无时间戳和日期，只有消息。
  Log.info('无时间戳和日期，只有黑色消息');

  // 在运行时设置不同的选项。
  Log.options = LogOptions(
    level: LogLevel.all, // 默认是 `[LogLevel.info]`。
    timeStamp: true, // 默认是 `true`。
    dateStamp: false, // 默认是 `true`。
    levelStamp: false, // 默认是 `true`。
  );

  // 07:22:45.000621 [标签]：时间戳和消息
  Log.info('时间戳和消息', '标签');

  // 在运行时设置不同的选项。
  Log.options = LogOptions(
    level: LogLevel.all, // 默认是 `[LogLevel.info]`。
    timeStamp: true, // 默认是 `true`。
    dateStamp: true, // 默认是 `true`。
    levelStamp: false, // 默认是 `true`。
  );

  // 2023-09-30 07:23:13.000396 [标签]：时间戳和消息
  Log.info('时间戳和消息', '标签');

  // 在运行时设置不同的选项。
  Log.options = LogOptions(
    level: LogLevel.all, // 默认是 `[LogLevel.info]`。
    utc: false, // 默认是 `true`。
    output: (record, options) {
      // 文件来记录记录。
      final File file = File('log.txt');

      // 追加格式化后的记录到文件。
      file.writeAsStringSync(
        // 注意，你可以在这里使用不同的 `[LogOptions]`，例如在控制台和文件中看到不同的输出。
        //
        // 只要记住，ANSI 转义码不会渲染颜色，这主要是控制台的功能，所以确保使用 `[LogColors.none]`。
        //
        // 注意，每个记录都会调用此函数，所以你需要自己检查 `[LogLevel]` 是否需要将此记录写入文件。
        '${record.format(options.copyWith(colors: LogColors.none))}\n',
        mode: FileMode.append,
      );

      // 调用默认输出（如果记录级别高于或等于设置的 `[LogOptions.level]` 则执行 `print`）。
      LogOptions.defaultOutput(record, options);
    },
  );

  // 2023-09-30 10:23:50.000019 INFO [标签]：时间戳和消息
  Log.info('时间戳和消息', '标签');

  // 在运行时设置不同的选项。
  Log.options = LogOptions(level: LogLevel.all);

  // 2023-09-30 07:19:55.000059 FATAL: 致命错误发生
  Log.fatal('致命错误发生');

  // 2023-09-30 07:19:55.000101 ERROR: 错误发生
  Log.error('错误发生');

  // 2023-09-30 07:30:14.000829 WARNING: 需要注意的警告
  Log.warning('需要注意的警告');

  // 2023-09-30 07:19:55.000117 INFO: 信息
  Log.info('信息');

  // 2023-09-30 07:19:55.000154 DEBUG: 调试特定日志
  Log.debug('调试特定日志');

  // 2023-09-30 07:19:55.000196 TRACE: 跟踪特定日志
  Log.trace('跟踪特定日志');
}