@rontian/roh5-api

为 vscode-roh5 项目插件提供 TypeScript 类型声明。运行时由 VS Code 扩展加载项目插件；本包只提供开发期 API 契约。

安装

npm install -D @rontian/roh5-api typescript

插件结构

.roh5/plugins/my-plugin/
├─ roh5.plugin.json
├─ package.json
└─ dist/index.cjs

roh5.plugin.json 最小示例：

{
  "schemaVersion": 1,
  "id": "my-plugin",
  "displayName": "我的项目插件",
  "version": "1.0.0",
  "enabled": true,
  "entry": "./dist/index.cjs",
  "contributes": { "language": {} },
  "permissions": ["workspace.read", "workspace.write"]
}

入口

入口导出 createPlugin。可实现一个或多个能力：language、translation、skin、commands。

import type { PluginFactory } from "@rontian/roh5-api";

export const createPlugin: PluginFactory = async context => ({
  language: {
    async resolveText({ text }) {
      context.log(`处理文本：${text}`);
      return { id: 10001, expression: "I18n.t(10001)" };
    }
  }
});

能力接口

language

• resolveText({ text, document, mode })：查询或创建语言条目；返回 { id, expression, edits? }。 mode 为 expression 或 id。edits 是完整文件文本替换列表，由主扩展统一应用。
• findById({ id, document })：返回语言条目定义位置，供“转到定义”使用。
• isExcluded({ id, document })：返回 true 时隐藏跳转与排除代码操作。

translation

• translate({ text, document, sourceLanguage?, targetLanguage?, signal? })：返回 { translation, origin?, web? }，或无结果时返回 null。
• 使用 context.secrets 前，manifest 必须声明 secrets.read；首次加载会请求用户确认。

skin

• resolveSkin({ skinName, projectPath })：返回实际 EXML URI。
• extractVariables({ skinText })：返回变量列表 { id, component?, decorators? }。
• renderVariables({ skinName, variables, indent })：返回写入 class body 的完整声明文本。 核心仍负责 //@skin、AST 定位、static 后插入、缩进、空行和旧块替换。

commands

返回 PluginCommand[]。每项含 id、title、execute({ document, selection })。 用户通过“运行项目插件命令”选择当前 workspace folder 已加载的命令。

权限

可声明：workspace.read、workspace.write、secrets.read、network。 其中敏感权限会在首次加载时向用户确认。插件仅应通过 API 上下文完成敏感操作；不要把凭据写入仓库。

完整运行时、CLI、隔离和发布流程见 项目插件与 CLI 文档。