# pd_log

**Repository Path**: pedro-labs/pd_log

## Basic Information

- **Project Name**: pd_log
- **Description**: Flutter框架的日志插件
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-10
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Flutter, IOS, Android, macOS, Windows

## README

# pd_log

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

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

## 特性概览

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

## 安装与快速使用

```yaml
dependencies:
  pd_log: ^0.7.3
```

```dart
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（纯文本输出）：

```dart
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](doc/README.md)
- 具体文档链接：
  - [入门指南](doc/getting_started.md)
  - [配置说明](doc/configuration.md)
  - [文件存储与滚动清理](doc/file_storage_and_rotation.md)
  - [查询与分页](doc/query_and_pagination.md)
  - [元数据与历史](doc/metadata_and_history.md)
  - [Web 平台差异](doc/web_platform.md)
  - [样式与格式化](doc/styling_and_formatting.md)
  - [文件读取工具](doc/file_reading_and_tools.md)
  - [缓冲刷新与事件监听](doc/native_bridge_and_flush.md)

## 示例项目

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

## 许可证

MIT（见根目录 `LICENSE`）。