pd_log

当前版本：v0.7.3（2025-10-24）

轻量、跨平台的 Flutter 日志插件，支持 Dart 统一文件缓冲写入与平台事件监听。

特性概览

• 级别日志与样式：PDLog.v/d/i/w/e、JSON 美化打印、ANSI 样式。
• Dart 文件缓冲：跨平台统一的写线程缓冲与定时/阈值刷新；平台侧提供控制台输出、根路径与目录事件监听。
• 文件查询与维护：列出/删除日志、滚动清理、按年/月/日组织。
• 元数据追踪：事件账本（NDJSON）与快照（JSON）自动维护。
• 统一跨平台：Web 控制台输出（不执行文件写入），接口一致。

安装与快速使用

dependencies:
  pd_log: ^0.7.3

import 'package:pd_log/pd_log.dart';

void main() {
  PDLog.configure(const PDLogConfig(
    minLevel: LogLevel.debug,
    
    // 控制台颜色：默认关闭
    ansiEnabled: true,
    nativeFileLoggingEnabled: true,
  ));
  PDLog.i('pd_log is ready');
}

开关说明：

• nativeFileLoggingEnabled: 开启本地文件写入（Dart 管理、统一缓冲与刷盘）；在 Web 端无效。
• ansiEnabled: 是否为控制台/平台输出包裹 ANSI 颜色（默认 false）。文件写入始终为纯文本。

示例：在 Apple 控制台关闭 ANSI（纯文本输出）：

import 'dart:io';
PDLog.updateConfigure(ansiEnabled: !(Platform.isIOS || Platform.isMacOS));

关键 API（精选）

• 输出日志：PDLog.v/d/i/w/e(Object? message, {String? tag})
• 刷新缓冲：PDLog.flushNativeLogs()（触发 Dart 写入器刷盘；平台侧为占位）
• 查询日志：PDLog.listLogFiles(...)、listLogFilesByYear(...)、listLogFilesByYearMonth(...)（支持 ListOptions 排序与分页）
• 文件路径：PDLog.logFilePathIfExists(DateTime date)
• 读取文件：PDLog.readLogFileContent(String path)（Dart 文件读取）
• 元数据查看：PDLog.metaLedgerContent()、PDLog.metaSummaryContent()
• 目录结构：PDLog.fileTreeString({int maxDepth = 6})

文档

说明当前架构：由 Dart 统一管理文件写入与缓冲；平台侧提供控制台输出、日志根路径与文件事件监听。文件枚举与删除由 Dart 实现，平台方法返回占位默认值以保持接口一致。

详细使用说明、注意事项与最佳实践已迁移至文档模块：

• 查看文档目录：doc/README.md
• 具体文档链接：
  • 入门指南
  • 配置说明
  • 文件存储与滚动清理
  • 查询与分页
  • 元数据与历史
  • Web 平台差异
  • 样式与格式化
  • 文件读取工具
  • 缓冲刷新与事件监听

示例项目

最小示例位于 example/ 目录，可直接运行 flutter run。

许可证

MIT（见根目录 LICENSE）。