集成接入 Breaking Changes

> 3.x

> 3.x 版本的 Breaking Changes 请参考：https://github.com/opensumi/core/blob/main/CHANGELOG.md

---

由于某些原因，在 v2.x.y 版本中，x 位也可能会存在 Break Change。

本文档记录自 v2.14.0 版本开始后续的部分集成方升级中可能遇到的一些 Breaking Change 问题。

v2.20.9

TerminalContainerId 转为 TERMINAL_CONTAINER_ID

v2.20.3

请使用 v2.20.4

v2.20.0

1. 部分模块命令定义移动至 @opensumi/ide-core-browser

如 TERMINAL_COMMANDS, LAYOUT_COMMANDS, MARKER_COMMANDS, SCM_COMMANDS, QUICK_OPEN_COMMANDS 等公共依赖均移动至 common.command.ts 文件，使用时需要调整一下引入路径，建议统一通过下面路径引入：

import { TERMINAL_COMMANDS } from '@opensumi/ide-core-browser';

2. 部分面板 ContainerID 修改

移除了 ID 中的 ide- 前缀，使其与框架其他区域视图 ID 命名方式统一。

问题面板

- export const MARKER_CONTAINER_ID = 'ide-markers';
+ export const MARKER_CONTAINER_ID = 'markers';

输出面板

- const OUTPUT_CONTAINER_ID = 'ide-output';
+ const OUTPUT_CONTAINER_ID = 'output';

3. 采用 @parcel/watcher 作为文件服务新的监听库

为了进一步提升框架文件服务的监听性能以及准确性，我们在该版本替换 nsfw 依赖为了 @parcel/watcher。

建议全局替换相关版本依赖如下：

- "nsfw": "2.1.2"
+ "@parcel/watcher": "2.0.5"

同时，也需要将构建原生依赖中的 nsfw 替换为 @parcel/watcher，如在 webpack.node.config.ts 中：

externals: [
  ({ context, request }, callback) => {
-   if (['node-pty', 'nsfw', 'spdlog', '@opensumi/vscode-ripgrep', 'vm2', 'keytar'].indexOf(request || '') !== -1) {
+   if (['node-pty', '@parcel/watcher', 'spdlog', '@opensumi/vscode-ripgrep', 'vm2', 'keytar'].indexOf(request || '') !== -1) {
      return callback(undefined, `commonjs ${request}`);
    }
    callback();
  },
],

其他修改同理，建议直接在项目仓库中搜索 nsfw 逐个进行替换。

4. 终端相关

修正 TerminalServiceClientImpl.create2 返回的 INodePtyInstance 对象中的 typo opensumi/core/pull/1528

// packages/terminal-next/src/node/terminal.service.client.ts
export interface INodePtyInstance {
  id: string;
  name: string;
  pid: number;
-  proess: string;
+  process: string;
  shellPath?: string;
}

移除 ITerminalClientFactory，请替换为 ITerminalClientFactory2，用法保持一致 opensumi/core/pull/1528

-  @Autowired(ITerminalClientFactory)
-  protected readonly clientFactory: ITerminalClientFactory;
+  @Autowired(ITerminalClientFactory2)
+  protected readonly clientFactory2: ITerminalClientFactory2;

createTerminal() {
- const client = await this.clientFactory(widget, /** @type TerminalOptions */ options);
+ const client = await this.clientFactory2(widget, /** @type ICreateTerminalOptions */ options);
}

ITerminalController 创建终端的 API 有变更 opensumi/core/pull/1528

• createClientWithWidget2 重命名为 createTerminalWithWidgetByTerminalOptions
• 移除 createClientWithWidget

因为可以通过不同 interface 的入参来创建 Terminal，所以在方法命名展示出来：

  createTerminal(options: ICreateTerminalOptions): Promise<ITerminalClient>;
  createTerminalWithWidget(options: ICreateTerminalOptions): Promise<ITerminalClient>;
  createTerminalWithWidgetByTerminalOptions(options: ICreateClientWithWidgetOptions): Promise<ITerminalClient>;

如果以前使用的是 createClientWithWidget，可以改为：

- this.terminalController.createClientWithWidget({
-   name: terminalName,
-   shellArgs: ['-c', ...args],
-   cwd: cwd,
- })
+ this.terminalController.createTerminalWithWidgetByTerminalOptions({
+   terminalOptions: {
+     name: terminalName,
+     shellArgs: ['-c', ...args],
+     cwd: cwd,
+   },
+ });

ITerminalClient 移除 options 属性增加 launchConfig 属性 opensumi/core/pull/1528

TerminalOptions 这个类型原本只是给插件 API 用作创建终端的入参，我们在整个 OpenSumi 内部需要使用 IShellLaunchConfig 来进行终端的创建。 我们在 v2.15.0 上实现了 IShellLaunchConfig，并且兼容了之前的 TerminalOptions 写法。

并且 ITerminalClient 有一个属性 _terminalOptions 来保存自己被创建时的参数，外部可以通过 options 这个 getter 来拿到该值。自 v2.20.0 开始，我们移除掉了 ITerminalClient 内部的所有 TerminalOptions 逻辑，变更如下：

class TerminalClient {
-   get options() {
-    return this._terminalOptions;
-   }
-   updateOptions(options: TerminalOptions) {
-     // ...
-   }
-
+   get launchConfig(): IShellLaunchConfig {
+     return this._launchConfig;
+   }
+   updateLaunchConfig(launchConfig: IShellLaunchConfig) {
+     // ...
+   }
+   updateTerminalName(options: ITerminalNameOptions) {
+     // ...
+   }
}

比如在 Task 中对于 TerminalClient 的取值有用到 .options，现在全部改为了 .launchConfig，变更可见： opensumi/core/pull/1528。

5. IWorkspaceService 和 IMainLayoutService 定义位置移动

修改下面的代码引入方式：

- import { IWorkspaceService } from '@opensumi/ide-workspace/lib/common/workspace-defination';
+ import { IWorkspaceService } from '@opensumi/ide-workspace';

- import { IMainLayoutService } from '@opensumi/ide-main-layout/lib/common/main-layout.defination';
+ import { IMainLayoutService } from '@opensumi/ide-main-layout';

6. 升级 vscode-textmate 及 vscode-oniguruma

由于更新了 Monaco Editor 版本，需要将依赖的 vscode-textmate 及 vscode-origuruma 升级到最新版本

- "vscode-textmate": "5.4.0"
+ "vscode-textmate": "7.0.1"

- "vscode-oniguruma": "1.5.1"
+ "vscode-oniguruma": "1.6.1"

7. 升级 xterm

升级 xterm 到 5.0.0-beta.36 如果你在代码中也使用到了，变更见：

• https://github.com/xtermjs/xterm.js/releases
• https://github.com/opensumi/core/pull/1636

v2.19.0

@opensumi/ide-utils 中引用的路径变更

以下文件有变更：

• packages/utils/src/promise-util.ts → packages/utils/src/promises.ts

v2.18.0 及以前

修改 Schemas 为 Schemes

自 v2.18.0 版本起，见 #1013

修改错误的拼写问题，同时让 Schemes 作为全局的 scheme 定义变量，方便复用

修改 ExplorerContainerId 为 EXPLORER_CONTAINER_ID

自 v2.18.0 版本起，见 #784

由于全局视图 ID 存在多种写法，后续所有视图 ID 均统一为全大写格式，如 EXPLORER_CONTAINER_ID, 使用到的集成方需要用如下方式引用：

import { EXPLORER_CONTAINER_ID } from '@opensumi/ide-explorer/lib/browser/explorer-contribution';

新增 @opensumi/ide-utils 模块，部分工具方法引入方式调整

自 v2.18.0 版本起，见 #784

由于 opensumi 中的工具方法存在较多的重复性，该版本我们对 utils 相关的代码进行了归纳整理，移除了大部分非必要方法，抽取出了 @opensumi/ide-utils 模块，开发者依旧可以从 @opensumi/ide-core-common， @opensumi/ide-core-browser， @opensumi/ide-core-node 中引入相应的工具方法。同时使用上有下列变化：

1. 部分工具方法使用方式调整

针对部分工具方法可能存在重复方法问题，如 strings, objects, arrays, path 等方法，后续需要通过如下方式获取具体的方法：

import { path } from '@opensumi/ide-core-common';

const { Path } = path;

详细改动见：utils/src/index.ts

2. 替换 glob 中的 parse 方法

将 glob 工具方法中的 parse 方法替换为了 parseGlob 更明确的写法

3. 移除了 platform 中定义的冗余 OS.type

后续 platform.ts 及 os.ts 文件中使用相同的 OperatingSystem 定义，同时，在 ICommonService 中使用 getBackendOS 方法返回类型将不会是 OS.type 而是 OperatingSystem。

RecycleTree 使用方法调整

自 v2.17.0 版本起，见 #866

1. 创建节点的方式更简单，无需再顾虑缓存及 ID 创建问题，相关逻辑已在 Tree 内部逻辑处理
2. 调用 Refresh, expandNode/collapseNode, ensureVisible 等文件操作方法无需顾虑时序问题，内部处理
3. 自定义的节点需要保证 name 的值在同一层级下的唯一性，默认会使用唯一的 id 作为 name，如果有根据路径查找节点的需求需要自定义节点 path 的生成路径（以文件树为例子，为了保证节点路径可索引及唯一性，可以使用 uri 作为节点 name 的值）, 大部分场景下，尽量以 displayName 作为渲染的内容是最稳妥的做法
4. 如果需要创建默认展开的树节点，支持如下两种方式：

[1] 通过设置节点 expanded = true 的方式，这种方式设置后节点将不能被折叠，伪代码如下：

Class DemoTreeNode extends TreeNode {
  ...
  get expanded() {
    return true;
  }
  ...

}

[2] 通过设置节点 isExpanded = true 的方式，这种方式设置后节点能正常被折叠展开，只是默认为展开状态，伪代码如下：

Class DemoTreeNode extends TreeNode {
  ...
  constructor() {
    this.isExpanded = true;
  }
  ...

}

部分模块导出结构调整

自 v2.17.0 版本起，见 #639

部分模块，如 ExtensionModule, ProcessModule, ExpressFileServerModule, SearchModule 不再导出 node 层内容，集成方需要进行修改，将下面的引入结构：

import { ExtensionModule } from '@opensumi/ide-extension';
import { ProcessModule } from '@opensumi/ide-process';
import { ExpressFileServerModule } from '@opensumi/ide-express-file-server';
import { SearchModule } from '@opensumi/ide-search';

修改为:

import { ExtensionModule } from '@opensumi/ide-extension/lib/node';`
import { ProcessModule } from '@opensumi/ide-process/lib/node';
import { ExpressFileServerModule } from '@opensumi/ide-express-file-server/lib/node';
import { SearchModule } from '@opensumi/ide-search/lib/node';

Connection 模块中不再默认导出 createSocketConnection 方法

自 v2.15.0 版本起，见 #551

集成方如果集成中遇到了在 @opensumi/ide-connection 中找不到 createSocketConnection 的问题。

前端导出方法代码需修改为：

import { createSocketConnection } from '@opensumi/ide-connection/lib/browser';

后端导出方法代码需修改为：

import { createSocketConnection } from '@opensumi/ide-connection/lib/node';

[待定] v3.0.0

@opensumi/ide-file-search 包已被废弃 #1189

在 v2.18 及以前，存在两个功能相同的包：@opensumi/ide-file-search 和 @opensumi/ide-search，并且存在了大量重复代码。

变更接入方案：

1. 直接将代码中的 @opensumi/ide-file-search 依赖替换为 @opensumi/ide-search。
2. 将 package.json 中的 @opensumi/ide-file-search 依赖替换为 @opensumi/ide-search。
3. 将从 @opensumi/ide-file-search 引入的 FileSearchModule 替换为从 @opensumi/ide-search 引入的 SearchModule。

- import { FileSearchModule } from '@opensumi/ide-file-search/lib/node';
import { SearchModule } from '@opensumi/ide-search/lib/node';

startServer([
-  FileSearchModule,
  SearchModule,
])

重要依赖变更 (@opensumi/vscode-ripgrep -> @opensumi/ripgrep) #1189

变更接入方案：

1. 将代码中的依赖 @opensumi/vscode-ripgrep 依赖替换为 @opensumi/ripgrep。
2. 请检查你的 webpack 配置中的 externals 属性配置是否变为 @opensumi/ripgrep。
3. 请检查你的 electron 打包脚本中是否有设置 asarUnpack 属性为新的 @opensumi/ripgrep