# 插件上下文（PluginContext）

插件上下文是插件运行时的核心接口，提供插件运行所需的环境和资源访问能力。通过 PluginContext 可以获取插件信息、本地化文本、配置存储、资源文件等，还可以显示提示消息、打开浏览器、操作剪贴板、记录日志等。

# 接口概览

方法	说明
`getPluginId()`	获取插件唯一标识符
`getPluginName()`	获取插件名称
`getPluginVersionCode()`	获取插件版本代码
`getPluginVersionName()`	获取插件版本名称
`getPluginSdkVersion()`	获取插件 SDK 版本
`getMTPackageName()`	获取 MT 管理器包名
`getMTVersionName()`	获取 MT 管理器版本名称
`getMTVersionCode()`	获取 MT 管理器版本号
`getString()`	获取本地化文本
`getStringNullable()`	获取本地化文本，未找到返回 null
`getStringList()`	批量获取本地化文本（返回 List）
`getStringArray()`	批量获取本地化文本（返回数组）
`getLanguage()`	获取语言代码
`getCountry()`	获取国家/地区代码
`getLanguageCountry()`	获取语言和国家代码组合
`getPreferences()`	获取配置存储对象
`getFilesDir()`	获取插件私有目录
`getAssetsAsStream()`	读取 assets 资源文件
`showToast()`	显示 Toast 消息（短）
`showToastL()`	显示 Toast 消息（长）
`cancelToast()`	取消 Toast 消息
`openBrowser()`	打开系统浏览器
`openBuiltinBrowser()`	打开内置浏览器
`hasClipboardText()`	判断剪贴板是否有文本
`getClipboardText()`	获取剪贴板文本
`setClipboardText()`	设置剪贴板文本
`log()`	写入日志
`openLogViewer()`	打开日志查看器
`openPreference()`	打开设置界面

# SDK 版本

int SDK_VERSION = 3;

当前 SDK 版本为 3，可通过 PluginContext.SDK_VERSION 获取。

# 获取插件信息

# getPluginId

String getPluginId()

获取当前插件的唯一标识符。

返回值： 插件 ID 字符串，例如 "com.example.myplugin"

# getPluginName

String getPluginName()

获取当前插件名称。

返回值： 插件名称

# getPluginSdkVersion

int getPluginSdkVersion()

获取当前插件所使用的 SDK 版本号，该值在插件安装包的 manifest.json 文件中定义。

返回值： 插件 SDK 版本号

# getPluginVersionCode

int getPluginVersionCode()

获取插件的版本代码（数字版本），用于版本比较和更新检测。

返回值： 插件版本代码，通常为递增的整数

# getPluginVersionName

String getPluginVersionName()

获取插件的版本名称（可读版本），用于向用户显示版本信息。

返回值： 插件版本名称，例如 "1.0.0"、"2.1-beta" 等

# 示例

// 显示插件基本信息
String info = "SDK版本: " + PluginContext.SDK_VERSION + "\n" +
        "插件ID: " + context.getPluginId() + "\n" +
        "插件名称: " + context.getPluginName() + "\n" +
        "版本代码: " + context.getPluginVersionCode() + "\n" +
        "版本名称: " + context.getPluginVersionName();
context.showToastL(info);

# 获取 MT 管理器信息

# getMTPackageName

String getMTPackageName()

获取当前正在运行的 MT 管理器包名。可用于区分正式版和测试版等不同版本的 MT 管理器。

返回值： MT 管理器的包名，例如 "bin.mt.plus"

# getMTVersionName

String getMTVersionName()

获取当前正在运行的 MT 管理器版本名称，用于向用户显示 MT 版本信息。

返回值： MT 管理器版本名称，例如 "2.19.4"

# getMTVersionCode

int getMTVersionCode()

获取当前正在运行的 MT 管理器版本号，可用于插件进行版本兼容性判断。

返回值： MT 管理器版本代码，例如 25121085

# 示例

// 显示 MT 管理器信息
String mtInfo = "MT 包名: " + context.getMTPackageName() + "\n" +
        "MT 版本名称: " + context.getMTVersionName() + "\n" +
        "MT 版本号: " + context.getMTVersionCode();
context.showToastL(mtInfo);

// 版本兼容性检查
int mtVersion = context.getMTVersionCode();
if (mtVersion < 26010800) {
    context.showToast("此功能需要 MT 管理器 2.xx.x 或更高版本");
    return;
}

# 获取本地化文本

# getString

String getString(@NonNull String key)

根据 key 获取本地化文本。

参数：

key - 本地化文本的键值，支持以下格式：
- "key" - 从 strings 语言包获取，未找到则回退到 MT 内置语言包
- "pack:key" - 从指定的 pack 语言包获取，无回退机制
- "{key}" - 等价于 "key"
- "{pack:key}" - 等价于 "pack:key"

返回值： 对应的本地化文本

异常： IllegalArgumentException - 找不到对应的本地化文本

# getString（带格式化参数）

String getString(@NonNull String key, Object... formatArgs)

获取本地化文本并进行格式化，使用 String.format() 方法处理占位符。

参数：

key - 本地化文本的键值
formatArgs - 格式化参数，用于替换 %s、%d 等占位符

返回值： 格式化后的本地化文本

# getStringNullable

@Nullable
String getStringNullable(@NonNull String key)

根据 key 获取本地化文本，找不到时返回 null 而非抛出异常。

参数：

key - 本地化文本的键值

返回值： 对应的本地化文本，未找到则返回 null

# getStringList / getStringArray

List<String> getStringList(@NonNull String... keys)
String[] getStringArray(@NonNull String... keys)

批量获取多个本地化文本。

参数：

keys - 本地化文本的键值数组

返回值： 包含所有本地化文本的集合/数组，顺序与传入的 keys 一致

# 示例

// 获取本地化文本
String pluginName = context.getString("plugin_name");

// 使用花括号格式（等价写法）
String text = context.getString("{plugin_name}");

// 从指定语言包获取
String commonOk = context.getString("common:ok");

// 带格式化参数
String message = context.getString("hello_format", "World");
// 假设 hello_format = "Hello, %s!"，结果为 "Hello, World!"

// 批量获取
List<String> items = context.getStringList("{item0}", "{item1}", "{item2}");

提示：{key} 格式的本地化文本在 UI 组件中也可直接使用，如 builder.addTextView().text("{plugin_name}")

更多介绍请查看本地化文本章节

# 获取语言环境

# getLanguage

String getLanguage()

获取当前系统的本地语言代码。

返回值： 语言代码，例如 "zh"（中文）、"en"（英文）、"ru"（俄文）等

# getCountry

String getCountry()

获取当前系统的国家/地区代码。

返回值： 国家代码，例如 "CN"（中国）、"US"（美国）等，可能为空字符串

# getLanguageCountry

String getLanguageCountry()

获取语言和国家代码的组合字符串。

返回值： 组合后的语言环境标识

示例：

Language 为 "zh"，Country 为 "CN" → 返回 "zh-CN"
Language 为 "en"，Country 为空 → 返回 "en"

# 配置存储

# getPreferences

SharedPreferences getPreferences()

获取插件专用的配置存储对象，可以自由进行增删查改操作，数据会持久化保存。当插件被卸载时，相关数据会被自动删除。

返回值： Android 标准的 SharedPreferences 实例

# 示例

SharedPreferences prefs = context.getPreferences();

// 读取配置
String apiKey = prefs.getString("api_key", "");
boolean enabled = prefs.getBoolean("enabled", true);
int count = prefs.getInt("count", 0);

// 保存配置
prefs.edit()
    .putString("api_key", "your-api-key")
    .putBoolean("enabled", false)
    .putInt("count", 10)
    .apply();

# 文件操作

# getFilesDir

File getFilesDir()

获取插件专用的文件存储目录。该目录会在插件卸载时被自动删除，建议将所有插件文件存储在此目录，可有效防止卸载后产生残留文件。

返回值： 插件专用文件目录的 File 对象

# getAssetsAsStream

InputStream getAssetsAsStream(String name)

获取插件安装包 assets 文件夹内指定文件的输入流。

参数：

name - 文件相对路径，例如文件位于 assets/data/config.txt，则参数为 "data/config.txt"

返回值： 文件输入流，如果文件不存在则返回 null

# 示例

// 读取 assets 文件内容
try (InputStream is = context.getAssetsAsStream("config.json")) {
    if (is != null) {
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        byte[] buffer = new byte[1024];
        int len;
        while ((len = is.read(buffer)) != -1) {
            baos.write(buffer, 0, len);
        }
        String content = baos.toString("UTF-8");
        // 处理文件内容...
    }
} catch (IOException e) {
    context.log("读取文件失败", e);
}

# 提示消息

所有 Toast 方法都可以在非 UI 线程调用。

# showToast

void showToast(CharSequence msg)
void showToast(CharSequence msg, Object... formatArgs)

显示短时间的 Toast 提示消息。

参数：

msg - 要显示的消息内容，支持 {key} 格式的本地化文本
formatArgs - 格式化参数

# showToastL

void showToastL(CharSequence msg)
void showToastL(CharSequence msg, Object... formatArgs)

显示长时间的 Toast 提示消息。

参数：

msg - 要显示的消息内容，支持 {key} 格式的本地化文本
formatArgs - 格式化参数

# cancelToast

void cancelToast()

取消当前正在显示的 Toast 提示消息。

# 示例

// 简单提示
context.showToast("操作成功");

// 使用本地化文本
context.showToast("{operation_success}");

// 带格式化参数
context.showToastL("已处理 %d 个文件", fileCount);

// 组合使用
context.showToast("{hello_format}", userName);

# 浏览器

# openBrowser

void openBrowser(String url)

调用系统外部浏览器打开指定 URL。

参数：

url - 要跳转的 URL 地址，应为有效的 HTTP/HTTPS 链接

# openBuiltinBrowser

void openBuiltinBrowser(String url, boolean showTitleBar)

调用 MT 内置浏览器打开指定 URL。内置浏览器的特点是不论跳转了多少页面，按返回键都是直接退出浏览器，不会返回上一级网页，适合仅展示信息、没有多层页面跳转的场景。

参数：

url - 要跳转的 URL 地址
showTitleBar - 是否显示顶部标题栏

# 示例

// 打开系统浏览器
context.openBrowser("https://mt2.cn");

// 打开内置浏览器（不显示标题栏）
context.openBuiltinBrowser("https://mt2.cn/guide/", false);

// 打开内置浏览器（显示标题栏）
context.openBuiltinBrowser("https://mt2.cn/guide/", true);

# 剪贴板操作

# hasClipboardText

boolean hasClipboardText()

判断剪贴板内是否有文本内容。

返回值： true 表示有可用文本，false 表示剪贴板为空或不包含文本

# getClipboardText

@NonNull
CharSequence getClipboardText()

获取剪贴板中的文本内容。

返回值： 剪贴板中的文本，如果获取失败或剪贴板为空则返回空字符串（非 null）

# setClipboardText

boolean setClipboardText(CharSequence text)
boolean setClipboardText(CharSequence text, @Nullable String successMessage)

将文本设置到剪贴板。

参数：

text - 要复制到剪贴板的文本内容
successMessage - 复制成功时弹出的信息，为 null 则不弹出

返回值： true 表示设置成功，false 表示设置失败（比如文本太大）

注意：默认的 setClipboardText(text) 成功时会自动弹出"已复制到剪贴板"，失败时会弹出具体错误信息。

# 示例

// 检查剪贴板
if (context.hasClipboardText()) {
    CharSequence text = context.getClipboardText();
    context.showToast("剪贴板内容: " + text);
}

// 复制文本（使用默认提示）
context.setClipboardText("Hello World");

// 复制文本（自定义提示）
context.setClipboardText("Hello World", "内容已复制");

// 复制文本（不弹出提示）
context.setClipboardText("Hello World", null);

# 日志

日志内容可以在 MT 插件管理界面中查看，便于调试和问题排查。

# log

void log(String msg)
void log(String msg, Throwable e)
void log(Throwable e)

写入日志消息。

参数：

msg - 日志消息内容
e - 异常对象，会记录异常的堆栈信息

# openLogViewer

void openLogViewer()

打开插件日志查看器。

# 示例

// 记录普通日志
context.log("用户点击了按钮");

// 记录异常日志
try {
    // 可能出错的代码
} catch (Exception e) {
    context.log("操作失败", e);
}

// 打开日志查看器
context.openLogViewer();

# 设置界面

# openPreference

void openPreference(@Nullable Class<? extends PluginPreference> clazz)

跳转并显示设置界面。

参数：

clazz - 设置界面类，需实现 PluginPreference 接口，为 null 则表示主设置界面类

# 示例

// 打开主设置界面
context.openPreference(null);

// 打开指定设置界面
context.openPreference(AdvancedSettings.class);

← 开发环境 API - 本地化文本 →