# v2.23.0 升级指南

本文将介绍 Express Flutter 平台 SDK 版本升级至 v2.23.0 版本时的说明和注意事项。

## 变更说明

为方便用户使用渲染功能，自 v2.23.0 版本起，决定删除 [ZegoExpressTextureRenderUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils.html) 和 [ZegoExpressPlatformViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils.html) 接口。

因此在从旧版本升级至 v2.23.0 版本时，开发者需要迁移至新的 [ZegoExpressCanvasViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils.html) 接口使用渲染功能。

[ZegoExpressCanvasViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils.html) 接口可以同时支持 [外接纹理\|_blank](https://api.flutter.dev/flutter/widgets/Texture-class.html) 和 [PlatformView\|_blank](https://docs.flutter.dev/development/platform-integration/android/platform-views) 渲染方式。

## 变更原因

Express SDK 支持两种渲染方式：[外接纹理\|_blank](https://api.flutter.dev/flutter/widgets/Texture-class.html) 和 [PlatformView\|_blank](https://docs.flutter.dev/development/platform-integration/android/platform-views)，在 v2.22.0 版本前两种渲染方式分别对应两套 API。由于部分平台 Flutter 仅支持其中一种渲染方式，开发者需要自行判断对应平台可使用哪套 API：

- 外接纹理：[ZegoExpressTextureRenderUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils.html)
  - [createTextureRenderer\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils/createTextureRenderer.html)
  - [destroyTextureRenderer\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils/destroyTextureRenderer.html)
  - [updateTextureRendererSize\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils/updateTextureRendererSize.html)
- PlatformView：[ZegoExpressPlatformViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils.html)
  - [createPlatformView\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils/createPlatformView.html)
  - [destroyPlatformView\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils/destroyPlatformView.html)

为降低用户的使用成本，因此在 v2.22.0 版本推出了全新的 API：

- [ZegoExpressCanvasViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils.html)
  - [createCanvasView\|_blank](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils/createCanvasView.html)
  - [destroyCanvasView\|_blank](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils/destroyCanvasView.html)

这套 API 屏蔽了之前两种渲染方式在使用上的差异，可以同时支持 [外接纹理\|_blank](https://api.flutter.dev/flutter/widgets/Texture-class.html) 和 [PlatformView\|_blank](https://docs.flutter.dev/development/platform-integration/android/platform-views) 渲染方式。

- 对于两种渲染方式都支持的平台，会根据调用 [createEngineWithProfile\|_blank](https://pub.dev/documentation/zego_express_engine/latest/zego_express_engine/ZegoExpressEngine/createEngineWithProfile.html) 时 [enablePlatformView\|_blank](https://pub.dev/documentation/zego_express_engine/2.21.0/zego_express_engine/ZegoEngineProfile/enablePlatformView.html) 参数来决定是使用 [PlatformView\|_blank](https://docs.flutter.dev/development/platform-integration/android/platform-views) 还是 [外接纹理\|_blank](https://api.flutter.dev/flutter/widgets/Texture-class.html)。

- 对于仅支持一种渲染方式的平台，会自动使用唯一支持的渲染方式，此时 [enablePlatformView\|_blank](https://pub.dev/documentation/zego_express_engine/2.21.0/zego_express_engine/ZegoEngineProfile/enablePlatformView.html) 参数无效，即 [enablePlatformView\|_blank](https://pub.dev/documentation/zego_express_engine/2.21.0/zego_express_engine/ZegoEngineProfile/enablePlatformView.html) 参数的行为模式是 `偏好` 而不是 `指定`。

在 v2.23.0 版本 SDK 正式支持了 macOS 和 Windows，当前 v2.23.0 版本支持的渲染方式及平台情况如下：

渲染方式\平台 | Android | iOS | macOS | Windows | Web | Linux
------------|---------|-----|-------|---------|-----|-------
外接纹理      | ✔️       | ✔️   | ✔️     | ✔️       | ✖   | ✖
PlatformView | ✔️       | ✔️   | ✖     | ✖       | ✔️   | ✖

v2.23.0 版本为了支持 `CanvasView`，重构了视频画面渲染的功能实现，提升了性能和画面的流畅度，但同时也破坏了原来 [ZegoExpressTextureRenderUtils](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils.html) 的行为（view mode 异常）。

为了避免此次改动影响用户体验，现决定删除上述的 [ZegoExpressTextureRenderUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils.html) 和 [ZegoExpressPlatformViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils.html) 接口。

开发者需要迁移至新的 [ZegoExpressCanvasViewUtils\|_blank](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils.html) 接口，具体接口变动情况如下：

旧接口 | 新接口
----|-----
[createTextureRenderer](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils/createTextureRenderer.html) | [createCanvasView](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils/createCanvasView.html)
[destroyTextureRenderer](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils/destroyTextureRenderer.html) | [destroyCanvasView](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils/destroyCanvasView.html)
[updateTextureRendererSize](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressTextureRenderUtils/updateTextureRendererSize.html) | 无需调用，SDK 内部自动处理
[createPlatformView](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils/createPlatformView.html) | [createCanvasView](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils/createCanvasView.html)
[destroyPlatformView](https://pub.dev/documentation/zego_express_engine/2.22.0/zego_express_engine/ZegoExpressPlatformViewUtils/destroyPlatformView.html) | [destroyCanvasView](https://pub.dev/documentation/zego_express_engine/2.23.0/zego_express_engine/ZegoExpressCanvasViewUtils/destroyCanvasView.html)

## 示例代码

您可以参考以下示例代码进行接口变更，也可以参考最新的 [示例 Demo\|_blank](https://github.com/zegoim/zego-express-flutter-sdk/tree/main/example) 进行接口变更。

### v2.23.0 版本前

- 外接纹理

```dart
// TextureRenderer

late int _viewID;
Widget? _viewWidget;

void start() {
  ZegoExpressEngine.instance.createTextureRenderer(width, height).then((viewID) {
    _viewID = viewID;
    setState(() {
      _viewWidget = Texture(textureId: viewID)
    });
    ZegoCanvas canvas = ZegoCanvas.view(viewID);
    // 调用 [startPreview] 或 [startPlayingStream] 接口
    // ......
  });
}

void stop() {
  // 调用 [stopPreview] 或 [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyTextureRenderer(_viewID);
}
```

- PlatformView

```dart
// PlatformView  

late int _viewID;
Widget? _viewWidget;

void start() {
  setState(() {
    _viewWidget = ZegoExpressEngine.instance.createPlatformView((viewID) {
      _viewID = viewID;
      ZegoCanvas canvas = ZegoCanvas.view(viewID);
      // 调用 [startPreview] 或 [startPlayingStream]
      // ......
    });
  });
}

void stop() {
  // 调用 [stopPreview] 或 [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyPlatformView(_viewID);
}
```

### v2.23.0 版本

```dart
// CanvasView 

late int _viewID;
Widget? _viewWidget;

void start() {
  ZegoExpressEngine.instance.createCanvasView((viewID) {
    _viewID = viewID;
    // 调用 [startPreview] 或 [startPlayingStream]
    // ......
  }).then((widget) {
    setState(() {
      _viewWidget = widget;
    });
  });
}

void stop() {
  // 调用 [stopPreview] 或 [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyCanvasView(_viewID);
}
```
