---
title: "@ray-js/robot-custom-log 自定义日志工具库"
summary: "扫地机自定义日志工具库，支持地图/路径/自定义日志记录、加密存储、分享导出及在线解析，便于问题排查。"
---

# @ray-js/robot-custom-log 自定义日志工具库
## 概述
`@ray-js/robot-custom-log`是为扫地机业务场景设计的一个自定义工具库，支持开发者便记录并导出设备上报的地图、路径等原始数据，便于排查问题。同时提供了配套的在线解析工具平台，大幅提升问题定位效率。
## 特性
- **多类型日志记录：** 支持地图数据、路径数据及自定义日志的独立记录

- **安全存储：** 日志内容加密后写入本地文件系统

- **实时监听：** 提供日志文件变更回调，支持动态更新日志列表

- **便捷分享：** 内置日志文件分享功能，便于数据导出

- **在线解析：** 支持将日志文件上传至涂鸦官方平台进行可视化解析与动态绘制

## 安装
```
yarn add @ray-js/robot-custom-log
```
## 快速开始
1. 记录日志
```typescript
import { logMapData, logPathData, logCustomData } from '@ray-js/robot-custom-log';

// 记录地图数据
logMapData(devId, mapData);

// 记录路径数据
logPathData(devId, pathData);

// 记录自定义日志
logCustomData(devId, customLog);
```
2. 监听与展示日志文件
```typescript
import React, { useState } from 'react';
import {
  registerLogFileChangeCallBack,
  shareLogFile,
  cleanAllLogFiles,
  authorizeFileWrite,
} from '@ray-js/robot-custom-log';
import type { LogFileInfo } from '@ray-js/robot-custom-log';

const LogManagement = ({ devId }) => {
  const [allLogList, setAllLogList] = useState<LogFileInfo[]>([]);

  // 注册日志文件变更监听
  React.useEffect(() => {
    registerLogFileChangeCallBack(devId, (fileList) => {
      setAllLogList([...fileList]);
    });
  }, [devId]);

  // 分享单个日志文件
  const handleShareLog = (fileId: string) => {
    shareLogFile(fileId);
  };

  return (
    <div>
      {allLogList.map((item) => (
        <div key={item.id} className="log-item">
          <div className="log-header">
            <span>文件编号: {item.fileIndex}</span>
            <span>
              更新时间: {new Date(item.lastModifiedTime).toLocaleString()}
            </span>
          </div>
          <div className="log-footer">
            <span>大小: {formatFileSize(item.fileSize)}</span>
            <button onClick={() => handleShareLog(item.id)}>
              分享日志
            </button>
          </div>
        </div>
      ))}
    </div>
  );
};
```

3. 文件管理

```typescript
// 申请文件写入权限（首次使用前调用）
authorizeFileWrite();

// 清理所有日志文件
cleanAllLogFiles();
```

## 日志解析平台
导出的日志文件可上传至涂鸦官方解析平台进行可视化分析：

- 平台地址：https://developer.tuya.com/tools/vacuum/

- 支持功能：

  - 日志内容解析与展示

  - 地图数据可视化渲染  

  - 路径数据动态绘制

  - 多类型数据关联分析

## 注意事项

1. 首次使用前需调用 `authorizeFileWrite()` 获取文件写入权限
2. 日志文件大小与数量受本地存储限制，建议定期清理
3. 生产环境建议默认关闭此功能，由业务侧自行控制，SDK不做处理

## API 参考

| 方法名 | 说明 | 参数 |
|--------|------|------|
| `logMapData` | 记录地图数据 | `devId: string, data: any` |
| `logPathData` | 记录路径数据 | `devId: string, data: any` |
| `logCustomData` | 记录自定义日志 | `devId: string, data: any` |
| `registerLogFileChangeCallBack` | 注册文件变更回调 | `devId: string, callback: (files: LogFileInfo[]) => void` |
| `shareLogFile` | 分享日志文件 | `fileId: string` |
| `cleanAllLogFiles` | 清理所有日志文件 | - |
| `authorizeFileWrite` | 申请文件写入权限 | - |

## 类型定义

```typescript
interface LogFileInfo {
  id: string;
  fileIndex: number;
  lastModifiedTime: number;
  fileSize: number;
}
```

---

通过本工具库，开发者可快速集成扫地机业务的数据记录与调试能力，有效提升问题排查效率。如有问题或建议，请参考官方文档或联系技术支持。