Archive - 文件读取

archive 命名空间提供了读取插件内部文件的能力，适用于多文件插件（目录插件/压缩包插件）。通过此 API，插件可以读取自身包内的配置文件、模板文件、静态资源等。

版本要求

Archive API 在 SDK v0.3.2 中引入。需要 EasyBot 2.1.0-dev.6 或更高版本。

单文件插件限制

对于单文件插件（仅一个 .js 文件），supportReadFile() 将返回 false，调用任何读取方法都会返回 null。

API 参考

declare namespace archive {
    function supportReadFile(): boolean;

    function readString(path: string): string | null;
    function readStringAsync(path: string): Promise<string | null>;

    function readBytes(path: string): Uint8Array | null;
    function readBytesAsync(path: string): Promise<Uint8Array | null>;

    function getFiles(directory: string): ArrayLike<string>;
    function getDirectories(directory: string): ArrayLike<string>;
}

方法详解

supportReadFile()

功能描述：检查当前插件是否支持文件读取。

语法：

archive.supportReadFile(): boolean

返回值：

• true：当前为多文件插件，支持读取文件
• false：当前为单文件插件，不支持文件读取

使用示例：

if (!archive.supportReadFile()) {
    logger.warning("当前为单文件插件，不支持文件读取");
    return;
}

---

readString() / readStringAsync()

功能描述：同步/异步读取文本文件内容（UTF-8 编码）。

语法：

// 同步
archive.readString(path: string): string | null

// 异步
archive.readStringAsync(path: string): Promise<string | null>

参数：

• path：文件在插件包内的相对路径

返回值：文件内容字符串，文件不存在或不支持读取时返回 null

使用示例：

// 同步读取配置
const configText = archive.readString("config/settings.json");
if (configText) {
    const settings = JSON.parse(configText);
    logger.info(`读取到配置: ${settings.appName}`);
}

// 异步读取模板
const template = await archive.readStringAsync("templates/message.html");
if (template) {
    const rendered = template.replace("{{name}}", playerName);
    // 使用渲染后的模板...
}

---

readBytes() / readBytesAsync()

功能描述：同步/异步读取二进制文件内容。

语法：

// 同步
archive.readBytes(path: string): Uint8Array | null

// 异步
archive.readBytesAsync(path: string): Promise<Uint8Array | null>

参数：

• path：文件在插件包内的相对路径

返回值：二进制数据，文件不存在或不支持读取时返回 null

使用示例：

// 读取图片文件
const imageBytes = await archive.readBytesAsync("assets/logo.png");
if (imageBytes) {
    logger.info(`读取到图片，大小: ${imageBytes.length} 字节`);
}

---

getFiles()

功能描述：获取指定目录下的所有文件路径。

语法：

archive.getFiles(directory: string): ArrayLike<string>

参数：

• directory：目录路径

返回值：文件路径数组，不支持读取时返回空数组

使用示例：

// 列出所有模板文件
const files = archive.getFiles("templates");
for (let i = 0; i < files.length; i++) {
    logger.info(`模板文件: ${files[i]}`);
}

---

getDirectories()

功能描述：获取指定目录下的所有子目录路径。

语法：

archive.getDirectories(directory: string): ArrayLike<string>

参数：

• directory：目录路径

返回值：目录路径数组，不支持读取时返回空数组

使用示例：

// 列出所有子目录
const dirs = archive.getDirectories(".");
for (let i = 0; i < dirs.length; i++) {
    logger.info(`子目录: ${dirs[i]}`);
}

最佳实践

读取 JSON 配置文件

function loadPluginConfig() {
    if (!archive.supportReadFile()) {
        logger.warning("单文件插件不支持文件读取，使用默认配置");
        return getDefaultConfig();
    }

    const json = archive.readString("config.json");
    if (!json) {
        logger.warning("未找到 config.json，使用默认配置");
        return getDefaultConfig();
    }

    try {
        return JSON.parse(json);
    } catch (e) {
        logger.error(`配置文件解析失败: ${e}`);
        return getDefaultConfig();
    }
}

动态加载 HTML 模板

async function renderTemplate(templateName, data) {
    if (!archive.supportReadFile()) return null;

    let html = await archive.readStringAsync(`templates/${templateName}`);
    if (!html) return null;

    // 简单模板替换
    for (const key in data) {
        html = html.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), data[key]);
    }

    return html;
}

// 使用
const page = await renderTemplate("welcome.html", {
    name: "玩家",
    server: "生存服"
});

注意事项

• 路径分隔符使用 /（正斜杠），即使在 Windows 上
• 所有路径相对于插件包的根目录
• 单文件插件无法使用此 API，建议在插件加载时检查 supportReadFile()
• 大文件读取建议使用异步方法避免阻塞