# 引擎适配要求

客服功能需要完成引擎适配后,再使用 CSDK 插件提供的浏览器控件接入。以下以 UE 5.6.1 源码引擎为例;使用其他引擎版本时,请参照本文的修改位置和实现逻辑,结合对应版本进行适配。

请先完成公共修改及目标平台的全部修改,再按本章末尾“修改完成后的编译与打包”统一处理。

以下按文件列出需要新增或修改的内容。新增文件使用文中完整代码;修改已有文件时,按函数名定位并合并。其他引擎版本请参照修改位置和实现逻辑适配。

适配范围 内容
公共修改 新增状态辅助文件和原生输入接口
Windows 配套 CEF 运行库与文件选择修复
Android 原生 WebView、显隐与输入处理、Java/UPL 打包接入
iOS 原生输入控制、透明背景与权限/语言配置
鸿蒙 状态同步、导航时序、组件标识、透明背景与输入绑定

# 公共修改

先完成下列两个状态辅助文件的新增,以及原生输入公共接口的修改。

# 新增状态辅助文件

在引擎中新增以下两个文件,文件内容如下:

Engine/Source/Runtime/WebBrowser/Public/WebBrowserWidgetState.h
Engine/Source/Runtime/WebBrowser/Private/WebBrowserWidgetState.cpp
1
2

头文件最终内容:

#pragma once
#include "CoreMinimal.h"
class SWidget;
struct FWebBrowserWidgetState
{
    bool bVisible = false;
    bool bInteractive = false;
};
/** Resolve the active arranged path, including ancestor WidgetSwitchers. */
WEBBROWSER_API FWebBrowserWidgetState GetWebBrowserWidgetState(const TSharedPtr<SWidget>& Widget, bool bForDescendant = false);
1
2
3
4
5
6
7
8
9
10

实现文件最终内容:

#include "WebBrowserWidgetState.h"
#include "Framework/Application/SlateApplication.h"
#include "Layout/WidgetPath.h"

FWebBrowserWidgetState GetWebBrowserWidgetState(const TSharedPtr<SWidget>& Widget, bool bForDescendant)
{
    FWebBrowserWidgetState State;
    if (!Widget.IsValid() || !FSlateApplication::IsInitialized()) return State;
    FWidgetPath Path;
    if (!FSlateApplication::Get().GeneratePathToWidgetUnchecked(Widget.ToSharedRef(), Path)
        || !Path.IsValid() || (!Path.GetWindow()->IsVirtualWindow() && !Path.GetWindow()->IsVisible())) return State;
    const FVector2D Size = Path.Widgets.Last().Geometry.GetLocalSize();
    if (Size.X <= 0 || Size.Y <= 0) return State;
    State.bVisible = true;
    State.bInteractive = true;
    for (int32 Index = 0; Index < Path.Widgets.Num(); ++Index)
    {
        const TSharedRef<SWidget>& Entry = Path.Widgets[Index].Widget;
        if (Entry->GetRenderOpacity() <= 0) State.bVisible = false;
        const EVisibility Visibility = Entry->GetVisibility();
        State.bInteractive &= Entry->IsEnabled() && (!bForDescendant && Index + 1 == Path.Widgets.Num()
            ? Visibility.IsHitTestVisible() : Visibility.AreChildrenHitTestVisible());
    }
    State.bInteractive &= State.bVisible;
    return State;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 原生输入公共接口

文件:Engine/Source/Runtime/WebBrowser/Public/IWebBrowserWindow.h。在 SetIsDisabled() 声明后新增以下接口:

virtual void SetIsDisabled(bool bValue) = 0;
// ===== 新增代码开始 =====
/** Gate native overlay input without hiding its contents. */
virtual void SetNativeInputEnabled(bool bEnabled) {}
// ===== 新增代码结束 =====
virtual TSharedPtr<class SWindow> GetParentWindow() const = 0;
1
2
3
4
5
6

# Windows

# 整套替换 CEF 运行库

下载配套的 Windows Win64 CEF 运行库 (opens new window),关闭编辑器及相关程序,备份并移走原有运行库目录,再使用压缩包中的完整 Win64 运行库目录替换:

Engine/Binaries/ThirdParty/CEF3/Win64/
1

必须整体替换该目录,包含所有动态库、资源文件及子目录;不能只替换 libcef.dll,也不要与旧文件混用。 解压后确认目录层级,不要形成 Win64/Win64/。该包用于配套的 UE5 Win64 引擎,其他引擎版本或架构需确认匹配后使用。

# 解除附件文件选择拦截

FCEFWebBrowserWindow::OnFileDialog()

文件:CEFWebBrowserWindow.cpp;修改函数:FCEFWebBrowserWindow::OnFileDialog()。

引擎相对路径:

Engine/Source/Runtime/WebBrowser/Private/CEF/CEFWebBrowserWindow.cpp
1

搜索 FCEFWebBrowserWindow::OnFileDialog(),保留目标引擎原有函数签名,删除阻止文件选择的日志及 return true,改为返回 false。

修改位置与前后对照(保留对应引擎版本的函数签名):

// ===== 删除代码开始(原实现) =====
    // UE_LOG(LogWebBrowser, Error, TEXT("FileDialogs are prevented."));
    // return true;
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    return false;
    // ===== 新增代码结束 =====
1
2
3
4
5
6
7
8

# Android

为支持客服网页显隐、文件选择和视频全屏,需要在引擎中新增和修改以下文件。完整新增代码与现有文件修改内容均列在本节。

引擎文件 修改位置与作用
Source/Runtime/WebBrowser/Public/IWebBrowserSingleton.h 创建设置增加 bool bUseNativeAndroidOverlay = false;CSDK 在 Android 创建时设为 true
Source/Runtime/WebBrowser/Private/WebBrowserSingleton.cpp Android 构造调用末尾传递 WindowSettings.bUseNativeAndroidOverlay
Source/Runtime/WebBrowser/Private/Android/AndroidWebBrowserWindow.h/.cpp 构造参数和成员、CreateWidget()、导航/脚本/关闭转发、原生输入及 CheckTickActivity()
Source/Runtime/WebBrowser/Private/Android/AndroidNativeWebBrowser.h/.cpp 新增 JNI 桥接;按游戏线程管理实例,事件回到游戏线程
Source/Runtime/WebBrowser/Private/Android/SAndroidNativeWebBrowser.h/.cpp 新增布局占位控件,将 Slate 位置尺寸转为 Android 像素
Build/Android/Java/src/com/epicgames/unreal/NativeWebViewControl.java 新增原生实现,提供上传、全屏视频、透明背景、前后台及输入处理
Source/Runtime/WebBrowser/Private/Android/NativeWebView_UPL.xml 新增 Activity 结果、暂停/恢复/销毁回调和混淆保留规则
Source/Runtime/WebBrowser/WebBrowser.Build.cs Android 分支注册上述 UPL

以上路径均以 Engine/ 为前缀。下方“新增文件”展示完整代码;“修改文件”只展示改动函数及必要上下文,用“新增代码开始/结束”“删除代码开始/结束”明确标记修改范围,并保留修改位置上下的原代码作为定位依据。函数名称在代码块外标明;代码块只保留修改内容及上下可定位的原代码,请在原函数中对应位置修改。

重点修改 FAndroidWebBrowserWindow::CreateWidget()、CheckTickActivity()、SetNativeInputEnabled() 及导航转发,使原生 WebView 随控件及祖先显示状态更新。隐藏保留页面;禁用输入不隐藏内容,触摸应按命中规则传递给下层 UE。

修改 FAndroidWebBrowserWindow::IsLoading():仅在 DocumentState == EWebBrowserDocumentState::Loading 时返回 true。

# 新增文件完整代码

新增文件:Engine/Source/Runtime/WebBrowser/Private/Android/AndroidNativeWebBrowser.h(完整代码)

#pragma once

#include "CoreMinimal.h"

#if PLATFORM_ANDROID
#include "Android/AndroidJavaEnv.h"

/** Game-thread owner of one native WebView. Java commands are serialized on the UI thread. */
class FAndroidNativeWebBrowser : public TSharedFromThis<FAndroidNativeWebBrowser>
{
public:
    using FEvent = TFunction<void(int32, const FString&, const FString&, int32)>;
    static TSharedPtr<FAndroidNativeWebBrowser> Create(const FString& Url, bool bTransparent, FEvent Event);
    ~FAndroidNativeWebBrowser();
    void SetActive(bool bActive);
    void UpdateBounds(int32 X, int32 Y, int32 Width, int32 Height);
    void LoadUrl(const FString& Url);
    void ExecuteJavascript(const FString& Script);
    void LoadString(const FString& Contents, const FString& BaseUrl);
    void SetInputEnabled(bool bEnabled);
    void Command(int32 Command);
    bool CanGoBack() const { return bCanGoBack; }
    bool CanGoForward() const { return bCanGoForward; }
    void Destroy();
    FString GetUrl() const { return CurrentUrl; }
    static void Dispatch(int64 Id, int32 Event, FString Text, FString Detail, int32 Number);

private:
    bool Initialize(const FString& Url, bool bTransparent);
    void Call(jmethodID Method, const jvalue* Arguments);
    int64 Id = 0;
    jclass JavaClass = nullptr;
    jmethodID CreateMethod = nullptr, ActiveMethod = nullptr, BoundsMethod = nullptr;
    jmethodID UrlMethod = nullptr, DestroyMethod = nullptr;
    jmethodID ScriptMethod = nullptr, StringMethod = nullptr, InputMethod = nullptr, CommandMethod = nullptr;
    bool bCanGoBack = false, bCanGoForward = false;
    bool bInputEnabled = true;
    FEvent OnEvent;
    FString CurrentUrl;
    FIntRect Bounds;
    bool bHasBounds = false;
    bool bActive = false;
};
#endif
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

新增文件:Engine/Source/Runtime/WebBrowser/Private/Android/AndroidNativeWebBrowser.cpp(完整代码)

#include "AndroidNativeWebBrowser.h"

#if PLATFORM_ANDROID
#include "Android/AndroidApplication.h"
#include "Async/Async.h"

namespace
{
TMap<int64, TWeakPtr<FAndroidNativeWebBrowser>> Instances;
int64 NextBrowserId = 0;
}

TSharedPtr<FAndroidNativeWebBrowser> FAndroidNativeWebBrowser::Create(const FString& Url,
    bool bTransparent, FEvent Event)
{
    check(IsInGameThread());
    auto Browser = MakeShared<FAndroidNativeWebBrowser>();
    Browser->Id = ++NextBrowserId;
    Browser->OnEvent = MoveTemp(Event);
    Instances.Add(Browser->Id, Browser);
    if (!Browser->Initialize(Url, bTransparent))
    {
        Browser->Destroy();
        return nullptr;
    }
    return Browser;
}

bool FAndroidNativeWebBrowser::Initialize(const FString& Url, bool bTransparent)
{
    JNIEnv* Env = FAndroidApplication::GetJavaEnv();
    if (!Env) return false;
    JavaClass = AndroidJavaEnv::FindJavaClassGlobalRef("com/epicgames/unreal/NativeWebViewControl");
    if (Env->ExceptionCheck()) { Env->ExceptionDescribe(); Env->ExceptionClear(); }
    if (!JavaClass) return false;
    CreateMethod = Env->GetStaticMethodID(JavaClass, "create", "(JLjava/lang/String;Z)V");
    ActiveMethod = Env->GetStaticMethodID(JavaClass, "setActive", "(JZ)V");
    BoundsMethod = Env->GetStaticMethodID(JavaClass, "updateBounds", "(JIIII)V");
    UrlMethod = Env->GetStaticMethodID(JavaClass, "loadUrl", "(JLjava/lang/String;)V");
    DestroyMethod = Env->GetStaticMethodID(JavaClass, "destroy", "(J)V");
    if (Env->ExceptionCheck()) { Env->ExceptionDescribe(); Env->ExceptionClear(); return false; }
    ScriptMethod = Env->GetStaticMethodID(JavaClass, "executeJavascript", "(JLjava/lang/String;)V");
    StringMethod = Env->GetStaticMethodID(JavaClass, "loadString", "(JLjava/lang/String;Ljava/lang/String;)V");
    InputMethod = Env->GetStaticMethodID(JavaClass, "setInputEnabled", "(JZ)V");
    CommandMethod = Env->GetStaticMethodID(JavaClass, "command", "(JI)V");
    if (Env->ExceptionCheck()) { Env->ExceptionDescribe(); Env->ExceptionClear(); return false; }
    if (!CreateMethod || !ActiveMethod || !BoundsMethod || !UrlMethod || !DestroyMethod
        || !ScriptMethod || !StringMethod || !InputMethod || !CommandMethod) return false;
    CurrentUrl = Url;
    auto JavaUrl = FJavaHelper::ToJavaString(Env, Url);
    jvalue Args[3] = {}; Args[0].j = Id; Args[1].l = *JavaUrl; Args[2].z = bTransparent;
    Call(CreateMethod, Args);
    return true;
}

void FAndroidNativeWebBrowser::Call(jmethodID Method, const jvalue* Arguments)
{
    check(IsInGameThread());
    if (JavaClass && Method)
    {
        if (JNIEnv* Env = FAndroidApplication::GetJavaEnv())
        {
            Env->CallStaticVoidMethodA(JavaClass, Method, Arguments);
            if (Env->ExceptionCheck())
            {
                Env->ExceptionDescribe(); Env->ExceptionClear();
                UE_LOG(LogTemp, Error, TEXT("CsdkWebBrowser: Android bridge call failed."));
            }
        }
    }
}

void FAndroidNativeWebBrowser::SetActive(bool bActive)
{
    if (this->bActive == bActive) return;
    this->bActive = bActive;
    if (bActive) bHasBounds = false;
    jvalue Args[2] = {}; Args[0].j = Id; Args[1].z = bActive;
    Call(ActiveMethod, Args);
}

void FAndroidNativeWebBrowser::UpdateBounds(int32 X, int32 Y, int32 Width, int32 Height)
{
    const FIntRect NewBounds(X, Y, X + Width, Y + Height);
    if (bHasBounds && Bounds == NewBounds) return;
    Bounds = NewBounds; bHasBounds = true;
    jvalue Args[5] = {}; Args[0].j = Id; Args[1].i = X; Args[2].i = Y;
    Args[3].i = Width; Args[4].i = Height;
    Call(BoundsMethod, Args);
}

void FAndroidNativeWebBrowser::LoadUrl(const FString& Url)
{
    JNIEnv* Env = FAndroidApplication::GetJavaEnv();
    if (!Env) return;
    CurrentUrl = Url;
    auto Value = FJavaHelper::ToJavaString(Env, Url);
    jvalue Args[2] = {}; Args[0].j = Id; Args[1].l = *Value;
    Call(UrlMethod, Args);
}

void FAndroidNativeWebBrowser::ExecuteJavascript(const FString& Script)
{
    if (JNIEnv* Env = FAndroidApplication::GetJavaEnv())
    {
        auto Value = FJavaHelper::ToJavaString(Env, Script);
        jvalue Args[2] = {}; Args[0].j = Id; Args[1].l = *Value;
        Call(ScriptMethod, Args);
    }
}
void FAndroidNativeWebBrowser::LoadString(const FString& Contents, const FString& BaseUrl)
{
    if (JNIEnv* Env = FAndroidApplication::GetJavaEnv())
    {
        auto Html = FJavaHelper::ToJavaString(Env, Contents);
        auto Url = FJavaHelper::ToJavaString(Env, BaseUrl);
        jvalue Args[3] = {}; Args[0].j = Id; Args[1].l = *Html; Args[2].l = *Url;
        Call(StringMethod, Args);
    }
}
void FAndroidNativeWebBrowser::SetInputEnabled(bool bEnabled)
{
    if (bInputEnabled == bEnabled) return;
    bInputEnabled = bEnabled;
    jvalue Args[2] = {}; Args[0].j = Id; Args[1].z = bEnabled;
    Call(InputMethod, Args);
}
void FAndroidNativeWebBrowser::Command(int32 Command)
{
    jvalue Args[2] = {}; Args[0].j = Id; Args[1].i = Command;
    Call(CommandMethod, Args);
}

void FAndroidNativeWebBrowser::Destroy()
{
    check(IsInGameThread());
    Instances.Remove(Id);
    if (Id)
    {
        jvalue Args[1] = {}; Args[0].j = Id;
        Call(DestroyMethod, Args);
        Id = 0;
    }
    OnEvent = nullptr;
    if (JavaClass)
    {
        if (JNIEnv* Env = FAndroidApplication::GetJavaEnv()) Env->DeleteGlobalRef(JavaClass);
        JavaClass = nullptr;
    }
}

FAndroidNativeWebBrowser::~FAndroidNativeWebBrowser() { Destroy(); }

void FAndroidNativeWebBrowser::Dispatch(int64 Id, int32 Event, FString Text, FString Detail, int32 Number)
{
    AsyncTask(ENamedThreads::GameThread, [Id, Event, Text = MoveTemp(Text), Detail = MoveTemp(Detail), Number]()
    {
        const auto* Weak = Instances.Find(Id);
        auto Browser = Weak ? Weak->Pin() : nullptr;
        if (!Browser) return;
        if (Event == 0) Browser->CurrentUrl = Text;
        if (Event == 8) { Browser->bCanGoBack = (Number & 1) != 0; Browser->bCanGoForward = (Number & 2) != 0; }
        if (Browser->OnEvent) Browser->OnEvent(Event, Text, Detail, Number);
    });
}

JNI_METHOD void Java_com_epicgames_unreal_NativeWebViewControl_nativeOnEvent(
    JNIEnv* Env, jclass, jlong Id, jint Event, jstring Text, jstring Detail, jint Number)
{
    FAndroidNativeWebBrowser::Dispatch(Id, Event, FJavaHelper::FStringFromParam(Env, Text),
        FJavaHelper::FStringFromParam(Env, Detail), Number);
}
#endif
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

新增文件:Engine/Source/Runtime/WebBrowser/Private/Android/SAndroidNativeWebBrowser.h(完整代码)

#pragma once

#include "CoreMinimal.h"
#include "Widgets/SLeafWidget.h"

#if PLATFORM_ANDROID
class FAndroidNativeWebBrowser;

/** Reserves UMG space and synchronizes it with a native Android overlay. */
class SAndroidNativeWebBrowser : public SLeafWidget
{
public:
    SLATE_BEGIN_ARGS(SAndroidNativeWebBrowser) {} SLATE_END_ARGS()
    void Construct(const FArguments&, TSharedRef<FAndroidNativeWebBrowser> InBrowser);
    virtual void Tick(const FGeometry& Geometry, double Time, float DeltaTime) override;
    virtual FVector2D ComputeDesiredSize(float) const override { return FVector2D(300, 150); }
    virtual int32 OnPaint(const FPaintArgs&, const FGeometry&, const FSlateRect&,
        FSlateWindowElementList&, int32 LayerId, const FWidgetStyle&, bool) const override { return LayerId; }
private:
    TWeakPtr<FAndroidNativeWebBrowser> Browser;
};
#endif
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

新增文件:Engine/Source/Runtime/WebBrowser/Private/Android/SAndroidNativeWebBrowser.cpp(完整代码)

#include "SAndroidNativeWebBrowser.h"

#if PLATFORM_ANDROID
#include "AndroidNativeWebBrowser.h"
#include "Android/AndroidWindow.h"

void SAndroidNativeWebBrowser::Construct(const FArguments&, TSharedRef<FAndroidNativeWebBrowser> InBrowser)
{
    Browser = InBrowser;
}

void SAndroidNativeWebBrowser::Tick(const FGeometry& Geometry, double, float)
{
    auto Native = Browser.Pin();
    if (!Native) return;
    const FPlatformRect Screen = FAndroidWindow::GetScreenRect();
    int32 ScreenWidth = 0, ScreenHeight = 0;
    FAndroidWindow::CalculateSurfaceSize(ScreenWidth, ScreenHeight);
    if (Screen.Bottom <= Screen.Top || ScreenHeight <= 0) return;
    // Match the engine Android browser's conversion from Slate surface coordinates to pixels.
    const float Scale = float(ScreenHeight) / (Screen.Bottom - Screen.Top);
    const FVector2D Position = Geometry.GetAccumulatedRenderTransform().GetTranslation() * Scale;
    const FVector2D Size = TransformVector(Geometry.GetAccumulatedRenderTransform(), Geometry.GetLocalSize()) * Scale;
    const int32 X = FMath::RoundToInt(Position.X), Y = FMath::RoundToInt(Position.Y);
    Native->UpdateBounds(X, Y, FMath::Max(0, FMath::RoundToInt(Position.X + Size.X) - X),
        FMath::Max(0, FMath::RoundToInt(Position.Y + Size.Y) - Y));
}
#endif
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

新增文件:Engine/Build/Android/Java/src/com/epicgames/unreal/NativeWebViewControl.java(完整代码)

package com.epicgames.unreal;

import android.app.Activity;
import android.app.Dialog;
import android.content.ClipData;
import android.content.Intent;
import android.content.res.AssetFileDescriptor;
import android.net.Uri;
import android.graphics.Bitmap;
import android.graphics.Color;
import android.net.http.SslError;
import android.os.Handler;
import android.os.Looper;
import android.os.Message;
import android.util.Log;
import android.view.View;
import android.view.MotionEvent;
import android.view.ViewGroup;
import android.view.Window;
import android.view.WindowManager;
import android.view.inputmethod.InputMethodManager;
import android.webkit.ConsoleMessage;
import android.webkit.MimeTypeMap;
import android.webkit.ValueCallback;
import android.webkit.SslErrorHandler;
import android.webkit.WebChromeClient;
import android.webkit.WebResourceError;
import android.webkit.WebResourceRequest;
import android.webkit.WebResourceResponse;
import android.webkit.WebSettings;
import android.webkit.WebView;
import android.webkit.WebViewClient;
import android.widget.FrameLayout;
import com.epicgames.unreal.GameActivity;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashSet;
import java.util.Locale;
import java.util.Map;

/** Owns only CSDK WebViews. All instance state and view operations live on Android's UI thread. */
public final class NativeWebViewControl {
    private static final String TAG = "CsdkWebBrowser";
    private static final Handler UI = new Handler(Looper.getMainLooper());
    private static final Map<Long, NativeWebViewControl> INSTANCES = new HashMap<>();
    private static boolean activityPaused;
    private static int nextFileRequest = 0xC5D0;
    private static FileSelection fileSelection;
    private static NativeWebViewControl fullscreenOwner;

    private static final class FileSelection {
        final long browserId;
        final int requestCode;
        final boolean multiple;
        ValueCallback<Uri[]> callback;
        FileSelection(long owner, boolean allowMultiple, ValueCallback<Uri[]> result) {
            browserId = owner;
            multiple = allowMultiple;
            callback = result;
            requestCode = nextFileRequest++;
            if (nextFileRequest > 0xC5FF) nextFileRequest = 0xC5D0;
        }
        void complete(Uri[] result) {
            ValueCallback<Uri[]> pending = callback;
            callback = null;
            if (pending != null) pending.onReceiveValue(result);
        }
    }
    private final long id;
    private final GameActivity activity;
    private final FrameLayout container;
    private final WebView webView;
    private final ArrayList<WebView> popups = new ArrayList<>();
    private Dialog fullscreenDialog;
    private FrameLayout fullscreenContainer;
    private WebChromeClient.CustomViewCallback fullscreenCallback;
    private boolean active, registered, destroyed, hasBounds, mainFrameFailed;
    private boolean inputEnabled = true;
    private int x, y, width, height;

    private static native void nativeOnEvent(long id, int event, String text, String detail, int number);

    private void event(int type, String text, String detail, int number) {
        if (!destroyed) nativeOnEvent(id, type, text == null ? "" : text, detail == null ? "" : detail, number);
    }

    private interface Action { void run(NativeWebViewControl browser); }
    private static void enqueue(long id, Action action) {
        UI.post(() -> {
            NativeWebViewControl browser = INSTANCES.get(id);
            if (browser == null || browser.destroyed) return;
            try { action.run(browser); }
            catch (RuntimeException error) {
                Log.e(TAG, "WebView command failed", error);
                browser.event(3, error.toString(), "", -1);
            }
        });
    }

    private NativeWebViewControl(long browserId, GameActivity owner, boolean transparent) {
        id = browserId;
        activity = owner;
        container = new FrameLayout(activity) {
            @Override public boolean dispatchTouchEvent(MotionEvent event) {
                // HitTestInvisible/disabled native overlays must not intercept the UE UI below.
                return inputEnabled && super.dispatchTouchEvent(event);
            }
        };
        container.setClickable(false);
        container.setFocusable(false);
        container.setClipChildren(true);
        webView = new WebView(activity);
        webView.setBackgroundColor(transparent ? Color.TRANSPARENT : Color.WHITE);
        WebSettings settings = webView.getSettings();
        settings.setJavaScriptEnabled(true);
        settings.setDomStorageEnabled(true);
        settings.setSupportMultipleWindows(true);
        settings.setJavaScriptCanOpenWindowsAutomatically(true);
        settings.setAllowFileAccess(false);
        settings.setAllowContentAccess(true);
        settings.setMixedContentMode(WebSettings.MIXED_CONTENT_NEVER_ALLOW);
        settings.setMediaPlaybackRequiresUserGesture(true);
        settings.setUserAgentString(WebSettings.getDefaultUserAgent(activity) + " CsdkWebBrowser");
        webView.setFocusableInTouchMode(true);
        webView.setWebViewClient(new WebViewClient() {
            @Override public void doUpdateVisitedHistory(WebView view, String url, boolean reload) {
                event(8, url, "", (view.canGoBack() ? 1 : 0) | (view.canGoForward() ? 2 : 0));
            }
            @Override public void onPageStarted(WebView view, String url, Bitmap favicon) {
                hideFullscreen();
                cancelFileSelection();
                mainFrameFailed = false;
                event(0, url, "", 0);
                event(5, url, "", 0);
            }
            @Override public void onPageFinished(WebView view, String url) {
                event(0, url, "", 0);
                if (!mainFrameFailed) event(4, url, "", 0);
            }
            @Override public void onReceivedError(WebView view, WebResourceRequest request, WebResourceError error) {
                if (request.isForMainFrame()) {
                    mainFrameFailed = true;
                    event(3, error.getDescription().toString(), request.getUrl().toString(), error.getErrorCode());
                }
            }
            @Override public void onReceivedHttpError(WebView view, WebResourceRequest request, WebResourceResponse response) {
                if (request.isForMainFrame()) {
                    mainFrameFailed = true;
                    event(3, "HTTP " + response.getStatusCode(), request.getUrl().toString(), response.getStatusCode());
                }
            }
            @Override public void onReceivedSslError(WebView view, SslErrorHandler handler, SslError error) {
                handler.cancel();
                mainFrameFailed = true;
                event(3, "SSL certificate validation failed", error.getUrl(), error.getPrimaryError());
            }
            @Override public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
                String scheme = request.getUrl().getScheme();
                if ("http".equalsIgnoreCase(scheme) || "https".equalsIgnoreCase(scheme)
                        || "about".equalsIgnoreCase(scheme)) return false;
                event(6, request.getUrl().toString(), "", 0);
                return true;
            }
        });
        webView.setWebChromeClient(new WebChromeClient() {
            @Override public void onShowCustomView(View view, CustomViewCallback callback) {
                showFullscreen(view, callback);
            }
            @Override public void onHideCustomView() {
                hideFullscreen();
            }
            @Override public void onReceivedTitle(WebView view, String title) { event(7, title, "", 0); }
            @Override public boolean onShowFileChooser(WebView view, ValueCallback<Uri[]> callback,
                    FileChooserParams params) {
                showFileChooser(callback, params);
                return true;
            }
            @Override public boolean onConsoleMessage(ConsoleMessage message) {
                event(2, message.message(), message.sourceId(), message.lineNumber());
                return true;
            }
            @Override public boolean onCreateWindow(WebView view, boolean dialog, boolean gesture, Message result) {
                // Capture the popup URL for the existing BP event; do not create unowned overlay windows.
                WebView popup = new WebView(activity);
                popups.add(popup);
                popup.setWebViewClient(new WebViewClient() {
                    private boolean handled;
                    private void capture(String url) {
                        if (handled || "about:blank".equals(url)) return;
                        handled = true;
                        event(6, url, "", 0);
                        UI.post(() -> { if (popups.remove(popup)) { popup.stopLoading(); popup.destroy(); } });
                    }
                    @Override public boolean shouldOverrideUrlLoading(WebView v, WebResourceRequest request) {
                        capture(request.getUrl().toString()); return true;
                    }
                    @Override public void onPageStarted(WebView v, String url, Bitmap icon) { capture(url); }
                });
                ((WebView.WebViewTransport) result.obj).setWebView(popup);
                result.sendToTarget();
                return true;
            }
        });
        container.addView(webView, new FrameLayout.LayoutParams(0, 0));
    }

    private void showFullscreen(View view, WebChromeClient.CustomViewCallback callback) {
        if (destroyed || !active || activityPaused || !hasBounds || fullscreenDialog != null
                || activity.isFinishing() || activity.isDestroyed() || view.getParent() != null) {
            callback.onCustomViewHidden();
            return;
        }
        if (fullscreenOwner != null) fullscreenOwner.hideFullscreen();
        // Use a separate full-window host: the normal WebView remains constrained to UMG bounds.
        // The dialog also consumes Back without forwarding it to Unreal's game input.
        fullscreenDialog = new Dialog(activity, android.R.style.Theme_Black_NoTitleBar_Fullscreen);
        fullscreenContainer = new FrameLayout(activity);
        fullscreenContainer.setBackgroundColor(Color.BLACK);
        fullscreenContainer.addView(view, new FrameLayout.LayoutParams(
                ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
        fullscreenCallback = callback;
        fullscreenOwner = this;
        fullscreenDialog.setContentView(fullscreenContainer);
        fullscreenDialog.setCanceledOnTouchOutside(false);
        fullscreenDialog.setOnDismissListener(dialog -> hideFullscreen());
        try {
            Window window = fullscreenDialog.getWindow();
            window.addFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN
                    | WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED);
            window.getDecorView().setSystemUiVisibility(activity.getWindow().getDecorView()
                    .getSystemUiVisibility() | View.SYSTEM_UI_FLAG_FULLSCREEN
                    | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);
            fullscreenDialog.show();
            window.setLayout(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT);
            view.requestFocus();
            Log.d(TAG, "Video fullscreen entered");
        } catch (RuntimeException error) {
            hideFullscreen();
            Log.e(TAG, "Cannot show video fullscreen", error);
        }
    }

    private void hideFullscreen() {
        if (fullscreenDialog == null) return;
        Dialog dialog = fullscreenDialog;
        FrameLayout host = fullscreenContainer;
        WebChromeClient.CustomViewCallback callback = fullscreenCallback;
        // Clear ownership before dismiss/callback, both of which can re-enter this method.
        fullscreenDialog = null;
        fullscreenContainer = null;
        fullscreenCallback = null;
        if (fullscreenOwner == this) fullscreenOwner = null;
        dialog.setOnDismissListener(null);
        host.removeAllViews();
        dialog.dismiss();
        if (callback != null) callback.onCustomViewHidden();
        Log.d(TAG, "Video fullscreen exited");
    }

    private void cancelFileSelection() {
        // Keep the request as a tombstone until Android returns its result. A late result
        // must never be delivered to a different page or a newly opened chooser.
        if (fileSelection != null && fileSelection.browserId == id) fileSelection.complete(null);
    }

    private void showFileChooser(ValueCallback<Uri[]> callback, WebChromeClient.FileChooserParams params) {
        if (destroyed || !active || activityPaused || fileSelection != null
                || activity.isFinishing() || activity.isDestroyed()
                || (params.getMode() != WebChromeClient.FileChooserParams.MODE_OPEN
                    && params.getMode() != WebChromeClient.FileChooserParams.MODE_OPEN_MULTIPLE)) {
            callback.onReceiveValue(null);
            return;
        }
        FileSelection selection = new FileSelection(id,
                params.getMode() == WebChromeClient.FileChooserParams.MODE_OPEN_MULTIPLE, callback);
        fileSelection = selection;
        try {
            LinkedHashSet<String> types = new LinkedHashSet<>();
            for (String accept : params.getAcceptTypes()) {
                if (accept == null) continue;
                for (String entry : accept.split(",")) {
                    String type = entry.trim().toLowerCase(Locale.ROOT);
                    if (type.startsWith(".")) {
                        type = MimeTypeMap.getSingleton().getMimeTypeFromExtension(type.substring(1));
                    }
                    if (type != null && type.matches("[a-z0-9!#$&^_.+-]+/(\\*|[a-z0-9!#$&^_.+-]+)")) {
                        types.add(type);
                    } else if ("*/*".equals(type)) {
                        types.clear();
                        types.add("*/*");
                        break;
                    }
                }
                if (types.contains("*/*")) break;
            }
            Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
            intent.addCategory(Intent.CATEGORY_OPENABLE);
            intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
            intent.setType(types.size() == 1 ? types.iterator().next() : "*/*");
            if (types.size() > 1) intent.putExtra(Intent.EXTRA_MIME_TYPES, types.toArray(new String[0]));
            intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, selection.multiple);
            activity.startActivityForResult(intent, selection.requestCode);
        } catch (RuntimeException error) {
            fileSelection = null;
            selection.complete(null);
            Log.e(TAG, "Cannot open Android file picker", error);
            event(3, "Cannot open file picker: " + error, webView.getUrl(), -1);
        }
    }

    /** Called synchronously from the generated GameActivity on its UI thread. */
    public static boolean onActivityResult(int requestCode, int resultCode, Intent data) {
        FileSelection selection = fileSelection;
        if (selection == null || selection.requestCode != requestCode) return false;
        fileSelection = null;
        NativeWebViewControl browser = INSTANCES.get(selection.browserId);
        if (selection.callback == null) return true;
        if (resultCode != Activity.RESULT_OK || data == null || browser == null
                || browser.destroyed || !browser.active) {
            selection.complete(null);
            return true;
        }
        LinkedHashSet<Uri> candidates = new LinkedHashSet<>();
        ClipData clip = data.getClipData();
        if (clip != null) {
            for (int index = 0; index < clip.getItemCount(); ++index) {
                candidates.add(clip.getItemAt(index).getUri());
                if (!selection.multiple) break;
            }
        }
        if (candidates.isEmpty() && data.getData() != null) candidates.add(data.getData());
        ArrayList<Uri> readable = new ArrayList<>();
        for (Uri uri : candidates) {
            if (uri == null || !"content".equalsIgnoreCase(uri.getScheme())) continue;
            try (AssetFileDescriptor descriptor = browser.activity.getContentResolver()
                    .openAssetFileDescriptor(uri, "r")) {
                if (descriptor != null) readable.add(uri);
            } catch (Exception error) {
                Log.w(TAG, "Cannot read selected file URI", error);
            }
        }
        selection.complete(readable.isEmpty() ? null : readable.toArray(new Uri[0]));
        return true;
    }

    public static void create(long id, String url, boolean transparent) {
        UI.post(() -> {
            if (INSTANCES.containsKey(id)) return;
            GameActivity activity = GameActivity.Get();
            if (activity == null || activity.isFinishing() || activity.isDestroyed()) {
                nativeOnEvent(id, 3, "No active Android activity", "", -1);
                return;
            }
            NativeWebViewControl browser = null;
            try {
                browser = new NativeWebViewControl(id, activity, transparent);
                INSTANCES.put(id, browser);
                // Created detached. Only an explicit activation plus valid UMG bounds can attach it.
                browser.webView.loadUrl(url);
            } catch (RuntimeException error) {
                if (browser != null) { INSTANCES.remove(id); browser.dispose(); }
                nativeOnEvent(id, 3, error.toString(), "", -1);
                Log.e(TAG, "WebView creation failed", error);
            }
        });
    }

    public static void setActive(long id, boolean value) {
        enqueue(id, browser -> {
            if (value && !browser.active) browser.hasBounds = false;
            browser.active = value;
            if (!value) browser.cancelFileSelection();
            browser.applyState();
        });
    }
    public static void updateBounds(long id, int x, int y, int width, int height) {
        enqueue(id, browser -> {
            browser.x = x; browser.y = y;
            browser.width = Math.max(0, width); browser.height = Math.max(0, height);
            browser.hasBounds = width > 0 && height > 0;
            browser.applyState();
        });
    }
    public static void setInputEnabled(long id, boolean value) {
        enqueue(id, browser -> {
            if (browser.inputEnabled == value) return;
            browser.inputEnabled = value;
            if (!value) {
                browser.hideFullscreen();
                browser.cancelFileSelection();
                InputMethodManager keyboard = (InputMethodManager) browser.activity.getSystemService(Activity.INPUT_METHOD_SERVICE);
                if (browser.webView.hasFocus() && keyboard != null)
                    keyboard.hideSoftInputFromWindow(browser.webView.getWindowToken(), 0);
                browser.webView.clearFocus();
            }
            browser.applyState();
        });
    }
    public static void executeJavascript(long id, String script) {
        enqueue(id, browser -> browser.webView.evaluateJavascript(script, null));
    }
    public static void loadString(long id, String html, String baseUrl) {
        enqueue(id, browser -> browser.webView.loadDataWithBaseURL(baseUrl, html, "text/html", "utf-8", null));
    }
    public static void command(long id, int command) {
        enqueue(id, browser -> {
            switch (command) {
                case 0: browser.webView.stopLoading(); break;
                case 1: browser.webView.reload(); break;
                case 2: browser.webView.goBack(); break;
                case 3: browser.webView.goForward(); break;
            }
        });
    }
    public static void loadUrl(long id, String url) { enqueue(id, browser -> browser.webView.loadUrl(url)); }

    private void applyState() {
        if (!active || activityPaused || !hasBounds || activity.isFinishing() || activity.isDestroyed()) {
            detach(); return;
        }
        FrameLayout.LayoutParams layout = new FrameLayout.LayoutParams(width, height);
        layout.leftMargin = x; layout.topMargin = y;
        webView.setLayoutParams(layout);
        if (container.getParent() == null) {
            activity.addContentView(container, new ViewGroup.LayoutParams(
                ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
        }
        webView.setEnabled(inputEnabled);
        webView.setVisibility(View.VISIBLE);
        container.setVisibility(View.VISIBLE);
        if (!registered) {
            activity.AddExtraIgnoreView(webView);
            registered = true;
        }
        // Deliberately do not request focus or force the keyboard open on resume.
        // A user tap on an HTML input gives the native WebView its InputConnection.
    }

    private void detach() {
        hideFullscreen();
        if (registered) { activity.RemoveExtraIgnoreView(webView); registered = false; }
        View focused = activity.getCurrentFocus();
        boolean ownsFocus = focused == webView;
        for (View view = focused; view != null && !ownsFocus;) {
            if (!(view.getParent() instanceof View)) break;
            view = (View) view.getParent();
            ownsFocus = view == webView;
        }
        if (ownsFocus) {
            InputMethodManager keyboard = (InputMethodManager) activity.getSystemService(Activity.INPUT_METHOD_SERVICE);
            if (keyboard != null) keyboard.hideSoftInputFromWindow(webView.getWindowToken(), 0);
        }
        webView.clearFocus();
        webView.setEnabled(false);
        container.setVisibility(View.GONE);
        if (container.getParent() instanceof ViewGroup) ((ViewGroup) container.getParent()).removeView(container);
        // Keep the WebView attached to its detached container. Do not clear URL, storage or JS timers.
    }

    private void dispose() {
        if (destroyed) return;
        cancelFileSelection();
        detach();
        destroyed = true;
        webView.stopLoading();
        webView.setWebChromeClient(null);
        webView.setWebViewClient(null);
        for (WebView popup : new ArrayList<>(popups)) { popup.stopLoading(); popup.destroy(); }
        popups.clear();
        container.removeAllViews();
        webView.destroy();
    }

    public static void destroy(long id) {
        UI.post(() -> {
            NativeWebViewControl browser = INSTANCES.remove(id);
            if (browser != null) browser.dispose();
        });
    }
    public static void onActivityPause() {
        UI.post(() -> { activityPaused = true; for (NativeWebViewControl b : INSTANCES.values()) b.applyState(); });
    }
    public static void onActivityResume() {
        UI.post(() -> { activityPaused = false; for (NativeWebViewControl b : INSTANCES.values()) b.applyState(); });
    }
    public static void onActivityDestroy() {
        UI.post(() -> {
            for (NativeWebViewControl b : INSTANCES.values()) b.dispose();
            INSTANCES.clear();
            fileSelection = null;
        });
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493

新增文件:Engine/Source/Runtime/WebBrowser/Private/Android/NativeWebView_UPL.xml(完整代码)

<?xml version="1.0" encoding="utf-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">
    <androidManifestUpdates>
        <addPermission android:name="android.permission.INTERNET" />
    </androidManifestUpdates>
    <proguardAdditions>
        <insert>
-keep class com.epicgames.unreal.NativeWebViewControl { *; }
-keep class com.epicgames.unreal.NativeWebViewControl$* { *; }
        </insert>
    </proguardAdditions>
    <gameActivityOnPauseAdditions>
        <insert>com.epicgames.unreal.NativeWebViewControl.onActivityPause();</insert>
    </gameActivityOnPauseAdditions>
    <gameActivityOnActivityResultAdditions>
        <insert>
if (com.epicgames.unreal.NativeWebViewControl.onActivityResult(requestCode, resultCode, data)) return;
        </insert>
    </gameActivityOnActivityResultAdditions>
    <gameActivityOnResumeAdditions>
        <insert>com.epicgames.unreal.NativeWebViewControl.onActivityResume();</insert>
    </gameActivityOnResumeAdditions>
    <gameActivityOnDestroyAdditions>
        <insert>com.epicgames.unreal.NativeWebViewControl.onActivityDestroy();</insert>
    </gameActivityOnDestroyAdditions>
</root>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 已有文件修改内容

修改文件:Engine/Source/Runtime/WebBrowser/Private/WebBrowserSingleton.cpp

FWebBrowserSingleton::CreateBrowserWindow():修改位置与前后对照

定位 Android 条件分支中的 new FAndroidWebBrowserWindow(...) 调用,只替换标记内的末尾参数;下方注册窗口代码是原有上下文。

    // Create new window
    TSharedPtr<FAndroidWebBrowserWindow> NewBrowserWindow = MakeShareable(new FAndroidWebBrowserWindow(
        WindowSettings.InitialURL,
        WindowSettings.ContentsToLoad,
        WindowSettings.bShowErrorMessage,
        WindowSettings.bThumbMouseButtonNavigation,
        WindowSettings.bUseTransparency,
        bJSBindingsToLoweringEnabled,
// ===== 删除代码开始(原实现) =====
//      {}));
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
        {},
        WindowSettings.bUseNativeAndroidOverlay));
// ===== 新增代码结束 =====

    {
        FScopeLock Lock(&WindowInterfacesCS);
        WindowInterfaces.Add(NewBrowserWindow);
    }
    return NewBrowserWindow;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

修改文件:Engine/Source/Runtime/WebBrowser/Public/IWebBrowserSingleton.h

修改位置:在下列原有类成员之间插入标记内的声明;不要把不同成员位置的代码拼接到一起。

    void* OSWindowHandle;
    FString InitialURL;
    bool bUseTransparency;
    // ===== 新增代码开始 =====
    /** Native Android overlay with file upload and fullscreen video support. */
    bool bUseNativeAndroidOverlay = false;
    // ===== 新增代码结束 =====
    bool bInterceptLoadRequests;
    bool bThumbMouseButtonNavigation;
    TOptional<FString> ContentsToLoad;
1
2
3
4
5
6
7
8
9
10

修改文件:Engine/Source/Runtime/WebBrowser/WebBrowser.Build.cs

修改 WebBrowser 模块构造函数中的 Android 配置:

        if (Target.Platform == UnrealTargetPlatform.Android)
        {
            PublicSystemLibraries.Add("libjnigraphics");
// ===== 新增代码开始 =====
            AdditionalPropertiesForReceipt.Add("AndroidPlugin", Path.Combine(ModuleDirectory, "Private", "Android", "NativeWebView_UPL.xml"));
// ===== 新增代码结束 =====
        }
1
2
3
4
5
6
7

修改文件:Engine/Source/Runtime/WebBrowser/Private/Android/AndroidWebBrowserWindow.cpp

文件顶部头文件引用:

#include "AndroidWebBrowserDialog.h"
// ===== 新增代码开始 =====
#include "AndroidNativeWebBrowser.h"
#include "SAndroidNativeWebBrowser.h"
#include "WebBrowserWidgetState.h"
#include "Widgets/Layout/SBox.h"
// ===== 新增代码结束 =====
#include "AndroidWebBrowserWidget.h"
#include "Android/AndroidApplication.h"
1
2
3
4
5
6
7
8
9

FAndroidWebBrowserWindow::FAndroidWebBrowserWindow():修改位置与前后对照

分两处修改:构造定义的参数列表增加末尾参数,再在函数体开头插入代码。

构造函数参数末尾增加 bool bInUseNativeOverlay;声明处同步增加该参数并默认设为 false。以下在构造函数体开头插入:

// ===== 新增代码开始 =====
    bUseNativeOverlay = bInUseNativeOverlay;
// ===== 新增代码结束 =====
    bool bInjectJSOnPageStarted = false;
    GConfig->GetBool(TEXT("Browser"), TEXT("bInjectJSOnPageStarted"), bInjectJSOnPageStarted, GEngineIni);
1
2
3
4
5

FAndroidWebBrowserWindow::LoadURL():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::LoadURL(FString NewURL)
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->LoadUrl(NewURL); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->LoadURL(NewURL);
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::LoadString():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::LoadString(FString Contents, FString DummyURL)
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->LoadString(Contents, DummyURL); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->LoadString(Contents, DummyURL);
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::CreateWidget():修改位置与前后对照

定位该方法的原定义,在下面原代码所示位置操作;仅修改开始/结束标记之间的内容,代码块不是整个文件的替换内容。

// ===== 新增代码开始 =====
    if (bUseNativeOverlay)
    {
        Scripting->SetWindow(SharedThis(this));
        const TWeakPtr<FAndroidWebBrowserWindow> Weak = SharedThis(this);
        NativeBrowser = FAndroidNativeWebBrowser::Create(CurrentUrl, bUseTransparency,
            [Weak](int32 Event, const FString& Text, const FString& Detail, int32 Number)
            {
                const auto Self = Weak.Pin();
                if (!Self) return;
                switch (Event)
                {
                case 0:
                    if (Self->CurrentUrl != Text) { Self->CurrentUrl = Text; Self->OnUrlChanged().Broadcast(Text); }
                    break;
                case 2: Self->OnConsoleMessage().ExecuteIfBound(Text, Detail, Number, EWebBrowserConsoleLogSeverity::Default); break;
                case 3: Self->NotifyDocumentError(Detail, Number); break;
                case 4: Self->NotifyDocumentLoadingStateChange(Text, false); break;
                case 5: Self->NotifyDocumentLoadingStateChange(Text, true); break;
                case 6:
                    if (Self->OnBeforePopup().IsBound()) Self->OnBeforePopup().Execute(Text, Detail);
                    break;
                case 7: Self->SetTitle(Text); break;
                }
            });
        if (NativeBrowser)
        {
            NativeWidget = SNew(SAndroidNativeWebBrowser, NativeBrowser.ToSharedRef());
            if (ContentsToLoad.IsSet()) NativeBrowser->LoadString(ContentsToLoad.GetValue(), CurrentUrl);
            return NativeWidget.ToSharedRef();
        }
        NativeWidget = SNew(SBox);
        return NativeWidget.ToSharedRef();
    }
// ===== 新增代码结束 =====
    TSharedRef<SAndroidWebBrowserWidget> BrowserWidgetRef =
        SNew(SAndroidWebBrowserWidget)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

FAndroidWebBrowserWindow::IsValid():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

bool FAndroidWebBrowserWindow::IsValid() const
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) return NativeBrowser.IsValid();
    // ===== 新增代码结束 =====
    return BrowserWidget.IsValid();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::CanGoBack():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

bool FAndroidWebBrowserWindow::CanGoBack() const
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) return NativeBrowser && NativeBrowser->CanGoBack();
    // ===== 新增代码结束 =====
    return BrowserWidget->CanGoBack();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::GoBack():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::GoBack()
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->Command(2); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->GoBack();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::CanGoForward():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

bool FAndroidWebBrowserWindow::CanGoForward() const
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) return NativeBrowser && NativeBrowser->CanGoForward();
    // ===== 新增代码结束 =====
    return BrowserWidget->CanGoForward();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::GoForward():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::GoForward()
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->Command(3); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->GoForward();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::IsLoading():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

bool FAndroidWebBrowserWindow::IsLoading() const
{
    // ===== 删除代码开始(原实现) =====
//  return DocumentState != EWebBrowserDocumentState::Loading;
    // ===== 删除代码结束 =====
    // ===== 新增代码开始 =====
    return DocumentState == EWebBrowserDocumentState::Loading;
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9

FAndroidWebBrowserWindow::Reload():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::Reload()
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->Command(1); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->Reload();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::StopLoad():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::StopLoad()
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->Command(0); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->StopLoad();
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::SetIsDisabled():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::SetIsDisabled(bool bValue)
{
bIsDisabled = bValue;
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) CheckTickActivity();
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::SetNativeInputEnabled():修改位置与前后对照

这是新增方法:在下文指定位置添加函数定义,函数签名在外部列出,代码块展示完整函数。

新增位置:在 AndroidWebBrowserWindow.cpp 中,FAndroidWebBrowserWindow::SetIsDisabled() 定义之后、GetParentWindow() 定义之前新增。

新增函数的定义签名为 void FAndroidWebBrowserWindow::SetNativeInputEnabled(bool bEnabled),下方展示完整函数:

void FAndroidWebBrowserWindow::SetNativeInputEnabled(bool bEnabled)
{
    // ===== 新增代码开始 =====
    if (bNativeInputEnabled == bEnabled) return;
    bNativeInputEnabled = bEnabled;
    if (bUseNativeOverlay) CheckTickActivity();
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8

FAndroidWebBrowserWindow::ShowFloatingCloseButton():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::ShowFloatingCloseButton(bool bShow, bool bDraggable)
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) return;
    // ===== 新增代码结束 =====
    BrowserWidget->ShowFloatingCloseButton(bShow, bDraggable);
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::ExecuteJavascript():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::ExecuteJavascript(const FString& Script)
{
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay) { if (NativeBrowser) { NativeBrowser->ExecuteJavascript(Script); } return; }
    // ===== 新增代码结束 =====
    BrowserWidget->ExecuteJavascript(Script);
}
1
2
3
4
5
6
7

FAndroidWebBrowserWindow::CloseBrowser():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

void FAndroidWebBrowserWindow::CloseBrowser(bool bForce, bool bBlockTillClosed /* ignored */)
{
    // ===== 删除代码开始(原实现) =====
//  BrowserWidget->Close();
    // ===== 删除代码结束 =====
    // ===== 新增代码开始 =====
    if (bUseNativeOverlay)
    {
        if (NativeBrowser) NativeBrowser->Destroy();
        NativeWidget.Reset(); NativeBrowser.Reset(); return;
    }
    if (BrowserWidget) BrowserWidget->Close();
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

FAndroidWebBrowserWindow::CheckTickActivity():修改位置与前后对照

定位该方法的原定义,在下面原代码所示位置操作;仅修改开始/结束标记之间的内容,代码块不是整个文件的替换内容。

// ===== 新增代码开始 =====
    if (bUseNativeOverlay)
    {
        const FWebBrowserWidgetState State = GetWebBrowserWidgetState(NativeWidget);
        bIsVisible = State.bVisible && !bIsDisabled;
        if (NativeBrowser)
        {
            NativeBrowser->SetInputEnabled(bIsVisible && State.bInteractive && bNativeInputEnabled);
            NativeBrowser->SetActive(bIsVisible);
        }
        return;
    }
// ===== 新增代码结束 =====
    if (bIsVisible != bTickedLastFrame)
    {
        bIsVisible = bTickedLastFrame;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

修改文件:Engine/Source/Runtime/WebBrowser/Private/Android/AndroidWebBrowserWindow.h

第一处:新增前向声明。 在文件顶部原有 SWebBrowserView 声明后新增:

class SAndroidWebBrowserWidget;
class SWebBrowserView;
// ===== 新增代码开始 =====
class FAndroidNativeWebBrowser;
// ===== 新增代码结束 =====
1
2
3
4
5

第二处:修改 FAndroidWebBrowserWindow 的构造函数声明。 在类的 private 构造声明处增加末尾参数;下方 CreateWidget() 为原有方法声明。

// ===== 删除代码开始(原声明) =====
// FAndroidWebBrowserWindow(FString Url, TOptional<FString> ContentsToLoad, bool bShowErrorMessage, bool bThumbMouseButtonNavigation, bool bUseTransparency, bool bJSBindingToLoweringEnabled, const FString& InUserAgentApplication);
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
FAndroidWebBrowserWindow(FString Url, TOptional<FString> ContentsToLoad, bool bShowErrorMessage, bool bThumbMouseButtonNavigation, bool bUseTransparency, bool bJSBindingToLoweringEnabled, const FString& InUserAgentApplication, bool bInUseNativeOverlay = false);
// ===== 新增代码结束 =====
TSharedRef<SWidget> CreateWidget();
1
2
3
4
5
6
7

第三处:新增原生输入接口声明。 在类中搜索 SetIsDisabled(),在它与 GetParentWindow() 之间插入:

virtual int GetLoadError() override;
virtual void SetIsDisabled(bool bValue) override;
// ===== 新增代码开始 =====
virtual void SetNativeInputEnabled(bool bEnabled) override;
// ===== 新增代码结束 =====
virtual TSharedPtr<SWindow> GetParentWindow() const override;
1
2
3
4
5
6

第四处:新增原生浏览器成员。 搜索原有 BrowserWidget 成员,在其后、Title 字段之前插入:

TSharedPtr<SAndroidWebBrowserWidget> BrowserWidget;
// ===== 新增代码开始 =====
bool bUseNativeOverlay = false;
bool bNativeInputEnabled = true;
TSharedPtr<FAndroidNativeWebBrowser> NativeBrowser;
TSharedPtr<SWidget> NativeWidget;
// ===== 新增代码结束 =====
FString Title;
1
2
3
4
5
6
7
8

# iOS

# 原生输入独立于显示

文件:Engine/Source/Runtime/WebBrowser/Private/IOS/IOSPlatformWebBrowser.h。在 FWebBrowserWindow 类中,紧接 SetIsDisabled() 声明后、GetParentWindow() 声明前新增:

virtual void SetIsDisabled(bool bValue) override;
// ===== 新增代码开始 =====
virtual void SetNativeInputEnabled(bool bEnabled) override;
// ===== 新增代码结束 =====
virtual TSharedPtr<SWindow> GetParentWindow() const override;
1
2
3
4
5

文件:Engine/Source/Runtime/WebBrowser/Private/IOS/IOSPlatformWebBrowser.cpp。在 SIOSWebBrowserWidget 类内部、原有 SetWebBrowserVisibility(bool InIsVisible) 方法之前新增以下完整方法。不要放到 IOSWebViewWrapper 或类外:

// ===== 新增代码开始 =====
void SetNativeInputEnabled(bool bEnabled)
{
#if !PLATFORM_TVOS
    auto Wrapper = WebViewWrapper;
    dispatch_async(dispatch_get_main_queue(), ^{
        Wrapper.WebView.userInteractionEnabled = bEnabled ? YES : NO;
    });
#endif
}
// ===== 新增代码结束 =====
1
2
3
4
5
6
7
8
9
10
11

同一文件在类外的 FWebBrowserWindow::SetIsDisabled(bool bValue) 定义之前新增以下窗口转发函数:

void FWebBrowserWindow::SetNativeInputEnabled(bool bEnabled)
{
    if (BrowserWidget) BrowserWidget->SetNativeInputEnabled(bEnabled);
}
1
2
3
4

# 按实例设置透明背景

文件:Engine/Source/Runtime/WebBrowser/Private/IOS/IOSPlatformWebBrowser.cpp。修改创建 WKWebView 的 create:...useTransparency:... 函数。修改位置与前后对照如下:

WKWebView 创建函数:修改位置与前后对照

WebView.scrollView.bounces = NO;

    // ===== 删除代码开始(原实现) =====
    // if (InUseTransparency)
    // {
    //     [self.WebView setOpaque : NO];
    //     [self.WebView setBackgroundColor : [UIColor clearColor]];
    // }
    // else
    // {
    //     [self.WebView setOpaque : YES];
    // }
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    UIColor* BrowserBackground = InUseTransparency
        ? [UIColor clearColor]
        : [UIColor whiteColor];
    self.WebView.opaque = InUseTransparency ? NO : YES;
    self.WebViewContainer.backgroundColor = BrowserBackground;
    self.WebView.backgroundColor = BrowserBackground;
    self.WebView.scrollView.backgroundColor = BrowserBackground;
    if (@available(iOS 15.0, *))
    {
        self.WebView.underPageBackgroundColor = BrowserBackground;
    }
    // ===== 新增代码结束 =====

if (bEnableFloatingCloseButton)
{
    CloseButton = MakeCloseButton();
    [self.WebView addSubview : CloseButton];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 权限与语言配置

使用客服拍照、录制带声音的视频等功能时,应用最终生成的 Info.plist 需包含对应权限用途声明。请先检查现有打包配置;已有正确声明时无需重复添加。接入方可沿用自身的配置或打包注入方式,不限定必须通过 Config/DefaultEngine.ini 配置。

配置项 用途
NSCameraUsageDescription 使用拍照或录制视频功能时,提供相机用途说明
NSMicrophoneUsageDescription 使用视频录音或语音消息功能时,提供麦克风用途说明
CFBundleLocalizations 声明应用支持的语言,供系统选择本地化界面语言;具体语言由接入项目决定

权限用途文案按产品实际用途调整;这些声明不代表用户已经授权,实际授权在使用相应功能时完成。

CFBundleLocalizations 用于系统界面的语言选择。权限提示文案的多语言由接入项目按产品需求配置。

# 尚未配置时的建议方式

在项目 Config/DefaultEngine.ini 的 iOS 设置中,通过 AdditionalPlistData 添加所需的语言、相机及麦克风用途配置。以下为示例,按项目实际情况调整:

[/Script/IOSRuntimeSettings.IOSRuntimeSettings]
AdditionalPlistData=<key>CFBundleLocalizations</key><array><string>en</string><string>zh-Hans</string></array><key>NSCameraUsageDescription</key><string>用于拍摄照片或视频并上传至客服。</string><key>NSMicrophoneUsageDescription</key><string>用于录制待上传客服的视频声音及发送语音消息。</string>
1
2

CFBundleLocalizations 数组中,每种支持语言对应一个 string。示例中的 en、zh-Hans 仅用于展示配置格式,不是 SDK 的固定要求;请按项目实际支持的语言增减或替换。

已有 AdditionalPlistData 时,将所需 XML 项合并至原值,不覆盖其他配置;已有相同键时调整原值,不重复添加。

# 鸿蒙

在鸿蒙引擎中按下列文件完成修改。WebView.ts 的方法对照、UeWebview.ets 的四处局部修改及 C++ 输入转发修改见本节末尾。

文件(引擎相对路径) 修改内容
Engine/Build/OpenHarmony/entry/src/main/ets/common/AkiJSBind.ets.template MainThreadBindAki() 注册 WebView.setVisible、WebView.setInputEnabled
Engine/Build/OpenHarmony/entry/src/main/ets/pages/Index.ets.template ForEach 仅用固定 viewTag 作为 key,不包含位置尺寸
Engine/Build/OpenHarmony/entry/src/main/ets/webview/WebView.ts @Observed、原地更新状态、导航队列、透明及每实例输入状态
Engine/Build/OpenHarmony/entry/src/main/ets/webview/UeWebview.ets @ObjectLink、固定空 src、挂载回调、背景/显隐/输入绑定
Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyArkTSWebBrowser.h/.cpp 透明参数传递、显隐绑定检查、输入函数调用
Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyWebBrowserWidget.h/.cpp 原生输入开关向 ArkTS 桥接层转发
Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyWebBrowserWindow.h/.cpp 覆盖公共原生输入接口并转发

# 绑定与组件标识

修改文件:Engine/Build/OpenHarmony/entry/src/main/ets/common/AkiJSBind.ets.template

修改函数:AkiJSBind.MainThreadBindAki()。搜索原有的 WebView.reload 绑定,在其后、Vibrator.Vibrate 绑定之前新增两项注册。下方上下两条绑定均为原代码:

nativeRender.JSBind.bindFunction("WebView.reload", WebView.reload);

// ===== 新增代码开始 =====
nativeRender.JSBind.bindFunction("WebView.setVisible", WebView.setVisible);
nativeRender.JSBind.bindFunction("WebView.setInputEnabled", WebView.setInputEnabled);
// ===== 新增代码结束 =====

nativeRender.JSBind.bindFunction("Vibrator.Vibrate", Vibrator.Vibrate);
1
2
3
4
5
6
7
8

修改文件:Engine/Build/OpenHarmony/entry/src/main/ets/pages/Index.ets.template

修改函数:Index.build()。搜索 ForEach(this.webViewArray,只替换它的 key 生成表达式;UeWebView({ viewInfo: item }) 和后续启动图布局作为原代码定位依据:

ForEach(this.webViewArray, (item: WebViewInfo) => {
    UeWebView({ viewInfo: item })
},
// ===== 删除代码开始(原实现) =====
// (item: WebViewInfo) => (item.viewTag + item.x + item.y + item.w + item.h).toString())
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
(item: WebViewInfo) => item.viewTag.toString())
// ===== 新增代码结束 =====
}
Image($r('app.media.splashscreen_landscape'))
    .objectFit(ImageFit.Contain)
1
2
3
4
5
6
7
8
9
10
11
12

以上 ForEach 后的右花括号来自原有外层布局,保持原位置;修改范围仅为开始/结束标记之间的 key 表达式。

# 状态更新与导航时序

修改文件:Engine/Build/OpenHarmony/entry/src/main/ets/webview/WebView.ts

修改位置一:搜索 export class WebViewInfo,在类声明前新增 @Observed。保留原导入和坐标字段:

import { BusinessError } from '@ohos.base';

// ===== 新增代码开始 =====
@Observed
// ===== 新增代码结束 =====
export class WebViewInfo {
    public x: number = 0;
    public y: number = 0;
1
2
3
4
5
6
7
8

修改位置二:在 WebViewInfo 的原有 url、isUrl 字段之后、viewTag 字段之前新增导航状态:

public url: string = '';
public isUrl: boolean = true;

// ===== 新增代码开始 =====
public controllerAttached: boolean = false;
public destroyed: boolean = false;
public navigationRevision: number = 0;
public pendingNavigation: (() => void) | undefined = undefined;
// ===== 新增代码结束 =====

public viewTag: number = 0;
public zoomAccess: boolean = true;
1
2
3
4
5
6
7
8
9
10
11
12

修改位置三:在 WebViewInfo 的原有 zoomAccess 字段后、visible 字段前新增输入状态:

public zoomAccess: boolean = true;
// ===== 新增代码开始 =====
public inputEnabled: boolean = true;
// ===== 新增代码结束 =====
public visible: boolean = true;
public opacity: number = 1;
1
2
3
4
5
6

修改位置四:定位同一类的原有背景字段,只替换该字段类型与默认值;前后的 opacity、controller 为原代码:

public opacity: number = 1;
// ===== 删除代码开始(原实现) =====
// public backgroundColor: number = 0xffffff;
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
public backgroundColor: ResourceColor = '#FFFFFFFF';
// ===== 新增代码结束 =====
public controller: webview.WebviewController = new webview.WebviewController();
1
2
3
4
5
6
7
8

修改位置五:删除类外原有的 copyWebViewInfo() 和立即返回的 waitUtilControllerAttached() 两个辅助函数。WebView 类内各方法的替换内容见后文逐方法对照;尺寸、显隐、透明度、背景与缩放均改为更新原状态对象,不复制和替换数组项。

修改文件:Engine/Build/OpenHarmony/entry/src/main/ets/webview/UeWebview.ets

修改位置:文件顶部的导入、UeWebView 的 viewInfo 属性和 build() 中的 Web 声明。具体上下文与修改标记见本节末尾该文件代码块,不重复插入。

# 透明参数传递

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyArkTSWebBrowser.cpp

修改函数:FArkTSOpenHarmonyWebBrowser::FArkTSOpenHarmonyWebBrowser(...)。搜索 WebView.createWebView,只替换紧接着的调用参数;WebViewTag = viewTag 和函数查找语句为原代码:

WebViewTag = viewTag;

auto jsFunc = aki::JSBind::GetJSFunction("WebView.createWebView");
// ===== 删除代码开始(原实现) =====
// jsFunc->Invoke<void>(WebViewTag);
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
jsFunc->Invoke<void>(WebViewTag, bUseTransparency);
// ===== 新增代码结束 =====
1
2
3
4
5
6
7
8
9

对应 WebView.ts 的 WebView.createWebView() 参数和函数体修改见后文同名方法。背景在实例加入数组前设置,透明使用 '#00000000',不透明白色使用 '#FFFFFFFF'。

# 显隐与输入桥接

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyArkTSWebBrowser.cpp

修改函数:FArkTSOpenHarmonyWebBrowser::SetVisibility()。在原函数查找语句之后、Invoke() 调用之前插入绑定检查:

auto jsFunc = aki::JSBind::GetJSFunction("WebView.setVisible");
// ===== 新增代码开始 =====
if (jsFunc == nullptr)
{
    UE_LOG(LogTemp, Error, TEXT("鸿蒙浏览器未注册 WebView.setVisible,无法更新可见性。"));
    return;
}
// ===== 新增代码结束 =====
jsFunc->Invoke<void>(WebViewTag, InIsVisible);
1
2
3
4
5
6
7
8
9

输入控制涉及窗口、控件、ArkTS 桥接三个类的新增方法和声明,分别按后文对应文件添加。WebView.setInputEnabled() 的签名、插入位置和函数体也见后文,避免重复定义。

# WebView 与输入转发完整修改

修改文件:Engine/Build/OpenHarmony/entry/src/main/ets/webview/WebView.ts

下列每个方法单独操作。短小方法展示完整代码,较长方法保留局部对照:

  • 标为“新增方法”:按给出的插入位置新增一个方法,代码块展示完整方法时,直接按插入位置添加;若展示局部函数体,则按外部签名组装定义。
  • 标为“修改现有方法”:在原方法内部按标记修改,保留原方法签名;另有签名变更说明时再修改签名。
  • 每个方法只处理一次,不把多个代码块拼成文件,也不新增同名方法。

findView():新增方法

插入位置:WebView.ts 的 WebView 类内部、原有 createWebView() 方法之前;这四个辅助方法各添加一次。

方法签名:private static findView(viewTag: number): WebViewInfo | undefined。以下为完整方法:

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

private static findView(viewTag: number): WebViewInfo | undefined {
    // ===== 新增代码开始 =====
    const index = globalThis.webViewIndexMap.get(viewTag);
    if (index === undefined) return undefined;
    return globalThis.webViewArray[index];
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7

queueNavigation():新增方法

插入位置:WebView.ts 的 WebView 类内部、原有 createWebView() 方法之前;这四个辅助方法各添加一次。

方法签名:private static queueNavigation(view: WebViewInfo, action: () => void): void。以下为完整方法:

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

private static queueNavigation(view: WebViewInfo, action: () => void): void {
    // ===== 新增代码开始 =====
    if (view.destroyed) return;
    ++view.navigationRevision;
    view.pendingNavigation = action;
    WebView.flushNavigation(view);
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8

flushNavigation():新增方法

插入位置:WebView.ts 的 WebView 类内部、原有 createWebView() 方法之前;这四个辅助方法各添加一次。

方法签名:private static flushNavigation(view: WebViewInfo): void。以下为完整方法:

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

private static flushNavigation(view: WebViewInfo): void {
    // ===== 新增代码开始 =====
    if (!view.controllerAttached || view.destroyed || !view.pendingNavigation) return;
    const revision = view.navigationRevision;
    Promise.resolve().then(() => {
        if (view.destroyed || !view.controllerAttached || view.navigationRevision !== revision) return;
        const action = view.pendingNavigation;
        if (!action) return;
        view.pendingNavigation = undefined;
        action();
    });
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13

onControllerAttached():新增方法

插入位置:WebView.ts 的 WebView 类内部、原有 createWebView() 方法之前;这四个辅助方法各添加一次。

方法签名:static onControllerAttached(viewTag: number): void。以下为完整方法:

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static onControllerAttached(viewTag: number): void {
    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (!view || view.destroyed) return;
    view.controllerAttached = true;
    WebView.flushNavigation(view);
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8

createWebView():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 createWebView();在该方法内按标记替换,不在类末尾再添加同名方法。

方法签名修改为 static createWebView(viewTag: number, useTransparency: boolean = false) : void。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static createWebView(viewTag: number, useTransparency: boolean = false) : void {
    let view = new WebViewInfo(0, 0, 0, 0, viewTag);
    // ===== 删除代码开始(原实现) =====
    // globalThis.webViewArray.push(view);
    // globalThis.webViewIndexMap.set(viewTag, globalThis.webViewArray.length - 1);
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    view.backgroundColor = useTransparency ? '#00000000' : '#FFFFFFFF';
    globalThis.webViewArray.push(view);
    globalThis.webViewIndexMap.set(viewTag, globalThis.webViewArray.length - 1);
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13

removeWebView():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 removeWebView();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static removeWebView(viewTag: number): void {
    // ===== 删除代码开始(原实现) =====
    // if (globalThis.webViewArray.length > 0) {
    // let index = globalThis.webViewIndexMap.get(viewTag);
    // globalThis.webViewArray.splice(index, 1);
    // globalThis.webViewIndexMap.forEach((value: number, key: number, map: Map<number, number>) => {
    // if (value > index) {
    //         globalThis.webViewIndexMap.set(key, value - 1);
    //     }
    // })
    // globalThis.webViewIndexMap.delete(viewTag);
    // }
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (!view) return;
    view.destroyed = true;
    view.controllerAttached = false;
    ++view.navigationRevision;
    view.pendingNavigation = undefined;

    if (globalThis.webViewArray.length > 0) {
        const index = globalThis.webViewIndexMap.get(viewTag);
        globalThis.webViewArray.splice(index, 1);
        globalThis.webViewIndexMap.forEach((value: number, key: number, map: Map<number, number>) => {
            if (value > index) {
                globalThis.webViewIndexMap.set(key, value - 1);
            }
        });
        globalThis.webViewIndexMap.delete(viewTag);
    }
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

loadData():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 loadData();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static loadData(viewTag: number, data: string, mimeType: string,
        encoding: string, baseURL: string): void {
    // ===== 删除代码开始(原实现) =====
    // let index = globalThis.webViewIndexMap.get(viewTag);
    // let webViewInfo: WebViewInfo = globalThis.webViewArray[index];
    // waitUtilControllerAttached().then(() => {
    //     webViewInfo.controller.loadData(data, mimeType, encoding, baseURL);
    // });
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (!view) return;
    view.url = baseURL;
    WebView.queueNavigation(view, () => {
        view.controller.loadData(data, mimeType, encoding, baseURL);
    });
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

loadURL():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 loadURL();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static loadURL(viewTag: number, url: string): void {
    // ===== 删除代码开始(原实现) =====
    // let index = globalThis.webViewIndexMap.get(viewTag);
    // globalThis.webViewArray[index].url = url;
    // globalThis.webViewArray[index].isUrl = true;
    // let webViewInfo: WebViewInfo = globalThis.webViewArray[index];
    // waitUtilControllerAttached().then(() => {
    //     webViewInfo.controller.loadUrl(url);
    // });
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (!view) return;
    view.url = url;
    view.isUrl = true;

    WebView.queueNavigation(view, () => {
        view.controller.loadUrl(url);
    });
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

loadFile():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 loadFile();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static loadFile(viewTag: number, filePath: string): void {
    // ===== 删除代码开始(原实现) =====
    // let index = globalThis.webViewIndexMap.get(viewTag);
    // globalThis.webViewArray[index].url = filePath;
    // globalThis.webViewArray[index].isUrl = false;
    // let webViewInfo: WebViewInfo = globalThis.webViewArray[index];
    // waitUtilControllerAttached().then(() => {
    //     webViewInfo.controller.loadUrl($rawfile(filePath));
    // });
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (!view) return;
    view.url = filePath;
    view.isUrl = false;
    WebView.queueNavigation(view, () => {
        view.controller.loadUrl($rawfile(filePath));
    });
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

stopLoading():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 stopLoading();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static stopLoading(viewTag: number): void {
    // ===== 删除代码开始(原实现) =====
    // let index = globalThis.webViewIndexMap.get(viewTag);
    // globalThis.webViewArray[index].controller.stop();
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (!view) return;
    ++view.navigationRevision;
    view.pendingNavigation = undefined;
    if (view.controllerAttached) view.controller.stop();
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

setWebViewRect():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 setWebViewRect();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static setWebViewRect(viewTag: number, x: number, y: number, w: number, h: number): void {
    let index = globalThis.webViewIndexMap.get(viewTag);
    let tmpWebInfo: WebViewInfo = globalThis.webViewArray[index];
    tmpWebInfo.x = px2vp(x);
    tmpWebInfo.y = px2vp(y);
    tmpWebInfo.w = px2vp(w);
    tmpWebInfo.h = px2vp(h);
    // ===== 删除代码开始(原实现) =====
    // let newViewInfo: WebViewInfo = copyWebViewInfo(tmpWebInfo);
    // globalThis.webViewArray[index] = newViewInfo;
    // ===== 删除代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12

setInputEnabled():新增方法

插入位置:WebView.ts 的 WebView 类内部,原有 setWebViewRect() 方法之后、setVisible() 方法之前。

方法签名:static setInputEnabled(viewTag: number, enabled: boolean): void。以下为完整方法:

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static setInputEnabled(viewTag: number, enabled: boolean): void {
    // ===== 新增代码开始 =====
    const view = WebView.findView(viewTag);
    if (view && !view.destroyed) view.inputEnabled = enabled;
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6

setVisible():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 setVisible();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static setVisible(viewTag: number, visible: boolean): void {
    let index = globalThis.webViewIndexMap.get(viewTag);
    if (globalThis.webViewArray[index].visible == visible) {
        return;
    }
    let tmpWebInfo: WebViewInfo = globalThis.webViewArray[index];
    tmpWebInfo.visible = visible;
    // ===== 删除代码开始(原实现) =====
    // let newViewInfo: WebViewInfo = copyWebViewInfo(tmpWebInfo);
    // globalThis.webViewArray[index] = newViewInfo;
    // ===== 删除代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12

setOpacityWebView():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 setOpacityWebView();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static setOpacityWebView(viewTag: number, opacity: number): void {
    let index = globalThis.webViewIndexMap.get(viewTag);
    if (globalThis.webViewArray[index].opacity == opacity) {
        return;
    }
    let tmpWebInfo: WebViewInfo = globalThis.webViewArray[index];
    tmpWebInfo.opacity = opacity;
    // ===== 删除代码开始(原实现) =====
    // let newViewInfo: WebViewInfo = copyWebViewInfo(tmpWebInfo);
    // globalThis.webViewArray[index] = newViewInfo;
    // ===== 删除代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12

setBackgroundTransparent():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 setBackgroundTransparent();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static setBackgroundTransparent(viewTag: number): void {
    let index = globalThis.webViewIndexMap.get(viewTag);
    if (globalThis.webViewArray[index].backgroundColor == Color.Transparent) {
        return;
    }
    globalThis.webViewArray[index].backgroundColor = Color.Transparent;
    // ===== 删除代码开始(原实现) =====
    // let newViewInfo: WebViewInfo = copyWebViewInfo(globalThis.webViewArray[index]);
    // globalThis.webViewArray[index] = newViewInfo;
    // ===== 删除代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11

setScalesPageToFit():修改现有方法的函数体

定位位置:WebView.ts 的 WebView 类中原有的 setScalesPageToFit();在该方法内按标记替换,不在类末尾再添加同名方法。

下面展示该方法的完整代码,原有部分与新增/删除部分均在同一方法内定位。

static setScalesPageToFit(viewTag: number, scalesPageToFit: boolean): void {
    let index = globalThis.webViewIndexMap.get(viewTag);
    if (globalThis.webViewArray[index].zoomAccess == scalesPageToFit) {
        return;
    }
    let tmpWebInfo: WebViewInfo = globalThis.webViewArray[index];
    // ===== 删除代码开始(原实现) =====
    // tmpWebInfo.zoomAccess = scalesPageToFit
    // let newViewInfo: WebViewInfo = copyWebViewInfo(tmpWebInfo);
    // globalThis.webViewArray[index] = newViewInfo;
    // ===== 删除代码结束 =====

    // ===== 新增代码开始 =====
    tmpWebInfo.zoomAccess = scalesPageToFit;
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

修改文件:Engine/Build/OpenHarmony/entry/src/main/ets/webview/UeWebview.ets

以下四处均为原文件的局部修改,请依次在对应位置操作,不用整段替换组件。

第一处:替换文件顶部的导入。 定位原来的 import { WebViewInfo } from "./WebView";修改结束后紧接原有的 @Component 和组件声明。

// ===== 删除代码开始(原导入) =====
// import { WebViewInfo } from "./WebView"
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
import { WebView, WebViewInfo } from "./WebView"
// ===== 新增代码结束 =====

@Component
export struct UeWebView {
1
2
3
4
5
6
7
8
9

第二处:替换 UeWebView 内的 viewInfo 属性。 搜索原属性声明,只替换这一项;以下代码块在属性处结束,不表示删除后面的 build()。

// ===== 删除代码开始(原属性) =====
// viewInfo: WebViewInfo = new WebViewInfo(0, 0, 0, 0, 0);
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
@ObjectLink viewInfo: WebViewInfo;
// ===== 新增代码结束 =====
1
2
3
4
5
6

第三处:替换 build() 中的 Web 声明,并加入控制器挂载回调。 搜索原来的 Web(...);新增范围截止到 .onControllerAttached(...),其后的 .position()、.width()、.height() 为原代码定位依据。

// ===== 删除代码开始(原 Web 声明) =====
// Web({ src: this.viewInfo.isUrl ? this.viewInfo.url : $rawfile(this.viewInfo.url), controller: this.viewInfo.controller })
// ===== 删除代码结束 =====
// ===== 新增代码开始 =====
Web({ src: '', controller: this.viewInfo.controller })
  .onControllerAttached(() => {
    WebView.onControllerAttached(this.viewInfo.viewTag);
  })
  // ===== 新增代码结束 =====
  .position({ x: this.viewInfo.x, y: this.viewInfo.y })
  .width(this.viewInfo.w)
  .height(this.viewInfo.h)
1
2
3
4
5
6
7
8
9
10
11
12

第四处:在同一条 Web 属性链中插入输入开关。 搜索 .visibility(...),只在其后、.opacity(...) 之前加入 .enabled(...)。以下为原文件连续的属性配置:

.zoomAccess(this.viewInfo.zoomAccess)
      .javaScriptAccess(true)
      .visibility(this.viewInfo.visible ? Visibility.Visible : Visibility.None)
      // ===== 新增代码开始 =====
      .enabled(this.viewInfo.inputEnabled)
      // ===== 新增代码结束 =====
      .opacity(this.viewInfo.opacity)
      .backgroundColor(this.viewInfo.backgroundColor)
1
2
3
4
5
6
7
8

以下按对应 C++ 文件展示修改位置,注释中标明原代码与新增、删除的位置。

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyArkTSWebBrowser.cpp

FArkTSOpenHarmonyWebBrowser::SetNativeInputEnabled():修改位置与前后对照

这是新增方法:在下文指定位置添加函数定义,函数签名在外部列出,代码块展示完整函数。

新增位置:在 OpenHarmonyArkTSWebBrowser.cpp 中,原有 FArkTSOpenHarmonyWebBrowser::SetVisibility() 定义之前新增。

新增函数的定义签名为 void FArkTSOpenHarmonyWebBrowser::SetNativeInputEnabled(bool bEnabled),下方展示完整函数:

void FArkTSOpenHarmonyWebBrowser::SetNativeInputEnabled(bool bEnabled)
{
    // ===== 新增代码开始 =====
    auto Function = aki::JSBind::GetJSFunction("WebView.setInputEnabled");
    if (Function) Function->Invoke<void>(WebViewTag, bEnabled);
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6
7

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyArkTSWebBrowser.h

修改位置:在下列原有类成员之间插入标记内的声明;不要把不同成员位置的代码拼接到一起。

    bool SendKeyUp(int32 KeyCode);
    void SetOpenHarmony3DBrowser(bool InIsOpenHarmony3DBrowser);
    void SetVisibility(bool InIsVisible);
    // ===== 新增代码开始 =====
    void SetNativeInputEnabled(bool bEnabled);
    // ===== 新增代码结束 =====
    void Update(const int posX, const int posY, const int sizeX, const int sizeY);
private:
    FTextureRHIRef VideoTexture;
1
2
3
4
5
6
7
8
9

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyWebBrowserWidget.cpp

SOpenHarmonyWebBrowserWidget::SetNativeInputEnabled():修改位置与前后对照

这是新增方法:在下文指定位置添加函数定义,函数签名在外部列出,代码块展示完整函数。

新增位置:在 OpenHarmonyWebBrowserWidget.cpp 中,原有 SOpenHarmonyWebBrowserWidget::SetWebBrowserVisibility() 定义之前新增。

新增函数的定义签名为 void SOpenHarmonyWebBrowserWidget::SetNativeInputEnabled(bool bEnabled),下方展示完整函数:

void SOpenHarmonyWebBrowserWidget::SetNativeInputEnabled(bool bEnabled)
{
    // ===== 新增代码开始 =====
    if (ArkTSWebBrowser) ArkTSWebBrowser->SetNativeInputEnabled(bEnabled);
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyWebBrowserWidget.h

修改位置:在下列原有类成员之间插入标记内的声明;不要把不同成员位置的代码拼接到一起。


    ////set the native control's visibility
    void SetWebBrowserVisibility(bool InIsVisible);
    // ===== 新增代码开始 =====
    void SetNativeInputEnabled(bool bEnabled);
    // ===== 新增代码结束 =====
protected:
    static FCriticalSection WebControlsCS;
    static TMap<int64, TWeakPtr<SOpenHarmonyWebBrowserWidget>> AllWebControls;
1
2
3
4
5
6
7
8
9

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyWebBrowserWindow.cpp

FOpenHarmonyWebBrowserWindow::SetNativeInputEnabled():修改位置与前后对照

这是新增方法:在下文指定位置添加函数定义,函数签名在外部列出,代码块展示完整函数。

新增位置:在 OpenHarmonyWebBrowserWindow.cpp 中,原有 FOpenHarmonyWebBrowserWindow::SetIsDisabled() 定义之前新增。

新增函数的定义签名为 void FOpenHarmonyWebBrowserWindow::SetNativeInputEnabled(bool bEnabled),下方展示完整函数:

void FOpenHarmonyWebBrowserWindow::SetNativeInputEnabled(bool bEnabled)
{
    // ===== 新增代码开始 =====
    if (BrowserWidget) BrowserWidget->SetNativeInputEnabled(bEnabled);
    // ===== 新增代码结束 =====
}
1
2
3
4
5
6

FOpenHarmonyWebBrowserWindow::IsLoading():修改位置与前后对照

定位同名函数,下面展示完整函数;仅按新增/删除标记修改对应内容。

bool FOpenHarmonyWebBrowserWindow::IsLoading() const
{
	// ===== 删除代码开始(原实现) =====
	//  return DocumentState != EWebBrowserDocumentState::Loading;
	// ===== 删除代码结束 =====
	// ===== 新增代码开始 =====
	return DocumentState == EWebBrowserDocumentState::Loading;
	// ===== 新增代码结束 =====
}
1
2
3
4
5
6
7
8
9

修改文件:Engine/Source/Runtime/WebBrowser/Private/OpenHarmony/OpenHarmonyWebBrowserWindow.h

修改位置:在下列原有类成员之间插入标记内的声明;不要把不同成员位置的代码拼接到一起。

    virtual void UnbindUObject(const FString& Name, UObject* Object = nullptr, bool bIsPermanent = true) override;
    virtual int GetLoadError() override;
    virtual void SetIsDisabled(bool bValue) override;
    // ===== 新增代码开始 =====
    virtual void SetNativeInputEnabled(bool bEnabled) override;
    // ===== 新增代码结束 =====
    virtual TSharedPtr<SWindow> GetParentWindow() const override;
    virtual void SetParentWindow(TSharedPtr<SWindow> Window) override;
    virtual void ShowFloatingCloseButton(bool bShow, bool bDraggable) override;
1
2
3
4
5
6
7
8
9

# 修改完成后的编译与打包

完成公共修改和目标平台的全部引擎修改后,再统一重新生成工程并重新编译引擎与 CSDK 插件。不要只更新源码文件后直接使用原有引擎二进制。

  1. 保存所有新增和修改的引擎文件,重新生成项目工程文件。
  2. 重新编译修改后的引擎及 CSDK 插件;先确认编辑器或目标平台构建成功,再打包项目。
  3. Android:重新生成 Android 工程,确认新增 Java 文件、UPL 注册及 Activity 回调进入最终 APK/AAB。
  4. 鸿蒙:重新生成鸿蒙工程,确认模板修改进入生成结果,再编译并生成 HAP;不要仅修改会被重新生成覆盖的中间文件。
  5. iOS:在 Mac 上使用修改后的引擎重新编译并生成 IPA,检查最终 Info.plist 配置。
  6. Windows:确认最终发布包使用替换后的整套 CEF 运行库。

最后在目标设备验证客服显示隐藏、输入、附件上传及视频全屏等功能。

# 客服功能与接入准备

客服功能从 CSDK 2.23.0 开始提供,本文以 CSDK 2.23.1 的接口和控件行为说明接入方式。

从修订说明下载 CSDK 2.23.1 插件,将插件接入项目,并启用 Csdk 及其 WebBrowserWidget 依赖。请先完成上文对应平台的引擎适配,再编译、打包项目。

客服网页必须使用 CSDK 提供的 UCsdkWebBrowser,在 UMG 控件面板中显示为 Csdk Web Browser。该控件提供客服接入所需的网页加载、输入及平台适配能力。

项目 内容
业务接口类 UCsdkCustomerServiceLibrary
业务模块/头文件 CsdkRuntime/CustomerService/CsdkCustomerServiceLibrary.h
浏览器控件 UCsdkWebBrowser
浏览器模块/头文件 CsdkBrowser/Widget/WebBrowser/CsdkWebBrowser.h
业务接口分类 CSDK|CustomerService
浏览器接口分类 CSDK|WebBrowser

C++ 调用方在自身模块的 Build.cs 中添加依赖:

PrivateDependencyModuleNames.AddRange(new[] { "CsdkRuntime", "CsdkBrowser" });
1

如果自身模块的公开头文件暴露上述模块类型,按 Unreal 模块规则配置公开依赖。仅使用蓝图时,无需为此新增 C++ 调用代码。

初始化成功后可查询客服开关;获取有效客服会话和角色客服地址需要角色登录成功。

# 客服界面接入

# 添加浏览器控件

在客服 UI 中添加 Csdk Web Browser,设置所需尺寸。建议复用同一个控件实例,以 Visibility 或 WidgetSwitcher 控制显示。不要通过每次销毁并重建控件实现日常打开/关闭。

# 获取地址并加载

  1. 初始化成功后调用 IsCustomerServiceEnabled(),决定是否展示客服入口。
  2. 当前角色登录成功后调用 GetCustomerServiceURL(),返回空字符串时不打开客服。
  3. 使用同一个 UCsdkWebBrowser 实例调用 CsdkLoadURL(URL)。日常打开/关闭只切换显示状态,不重复加载地址。
  4. 通过浏览器或祖先控件的 Visibility、WidgetSwitcher 显示客服。外层 Switcher 切走整个聊天页时,原生浏览器也应隐藏。
  5. 按平台支持情况绑定加载事件,提供加载、错误和重试提示。鸿蒙加载事件的支持范围见后文接口说明。
  6. 查询客服未读并绑定变化通知;何时清除由业务显式决定。
  7. 登出/换号时先隐藏旧客服,再调用 CsdkLoadURL(TEXT("")) 清空旧页面;新角色登录后重新获取并加载 URL。

以下为已持有控件实例时的 C++ 调用片段,Browser 代表业务已有的 UCsdkWebBrowser*,不是 SDK 全局对象:

if (Browser && UCsdkCustomerServiceLibrary::IsCustomerServiceEnabled())
{
    const FString URL = UCsdkCustomerServiceLibrary::GetCustomerServiceURL();
    if (!URL.IsEmpty())
    {
        Browser->CsdkLoadURL(URL); // 首次接入、角色变化或显式重试时加载。
        Browser->SetVisibility(ESlateVisibility::Visible);
    }
}
1
2
3
4
5
6
7
8
9

上述显示自身的调用不能覆盖祖先的隐藏状态;使用 WidgetSwitcher 时还需切到包含该浏览器的活动分支。不要将含角色登录信息的 URL 长期缓存或写入日志。

# 透明背景与加载提示

CSDK 2.23.1 的 UCsdkWebBrowser 默认开启 Supports Transparency,接入方仍可按页面需要取消勾选。已有蓝图或实例保存过 false 时,请手动检查、勾选或重置为默认值;该属性在浏览器创建时传入底层,运行中改值不会自动更新已创建实例。

推荐 UMG 层级:

Overlay
├─ Border / Image:与客服页面相同颜色的底图,始终保留
└─ Csdk Web Browser:Supports Transparency = true
1
2
3

浏览器初始透明时会显示下层 UE 底图。接入方只需配置浏览器控件和 UMG 底图;客服页面的样式、内容加载及页面内部逻辑由 CSDK 负责,无需接入方修改。

# 客服未读接入

客服使用现有会话体系,同一已登录角色对应一个固定客服会话:

字段 值
ReceiverId "cs"
ServerId 当前角色的 ServerId
Type ECsdkSessionType::CustomerService

应使用 GetCustomerServiceSessionId() 获取该标识。客服未读数量查询、清除及变化通知复用会话接口,具体用法请跳转:

客服未读返回的是数量,可用于数字角标或以是否大于零判断红点。当前版本的未读数量查询返回类型为 int64;会话文档中的旧示例若仍标为 int32,以当前 SDK 声明为准。

客服未读计入总未读,不要求客服出现在本地会话列表。清除由业务显式调用现有会话清除接口;SDK 不因客服界面加载完成或显示在前台而自动清除。绑定变化通知后应主动查询一次当前数量。

# 接口说明

# 客服业务接口

# 查询客服是否开启

static bool IsCustomerServiceEnabled();
1

初始化成功后调用,返回产品是否开启客服。未初始化、初始化失败、服务端未开启或 SDK 已销毁时返回 false。该接口不要求角色登录;返回 true 不代表角色已登录或客服界面已加载完成。

# 获取客服会话标识

static FCsdkSessionId GetCustomerServiceSessionId();
1

返回当前已登录角色的固定客服会话。SDK 未初始化、角色未登录或角色标识无效时,返回无效会话。

# 获取客服地址

static FString GetCustomerServiceURL();
1

无参数,返回根据当前角色构建完成的完整客服 URL,可直接交给 UCsdkWebBrowser::CsdkLoadURL();接入方无需自行补充登录参数。

要求 SDK 初始化成功、角色已登录、客服已开启、角色及区服标识有效,且客服地址配置有效。无法获取时返回空字符串,调用方应先判断非空。该函数只返回地址,不自动创建控件或加载客服界面。

地址对应当前角色。登出或换号后应清空旧客服界面,待新角色登录后重新获取并加载地址。不要将地址长期缓存或写入日志。

# 浏览器接口

# 加载地址

void CsdkLoadURL(const FString& URL);
1

传入 GetCustomerServiceURL() 返回的非空地址。底层浏览器尚未创建时保存为 InitialURL,创建后加载;已有浏览器时发起导航。空字符串按 about:blank 处理,用于清空旧页面。

也可配置创建时的 InitialURL,为空时打开空白页;编辑器设计预览不发起加载。反复切换客服页面应复用实例,不重复调用加载接口。销毁或重建控件会重建底层浏览器,普通隐藏不会。

# 加载事件

事件 参数 含义
OnCsdkLoadStarted const FString& Url 开始导航加载
OnCsdkLoadCompleted const FString& Url 平台报告加载完成
OnCsdkLoadError int32 ErrorCode, const FString& ErrorMessage, const FString& Url 平台报告加载失败

错误码和信息粒度因平台而异,可能返回 -1 和通用错误描述,不应将错误码视为跨平台统一协议。

平台支持说明: 当前鸿蒙版本暂不提供完整的页面加载开始、完成和失败事件。鸿蒙端的加载提示应提供超时和退出方式,不要只依赖完成事件关闭提示。

加载事件用于反馈浏览器加载状态,不代表客服界面已经完成显示。

SDK 下载及版本变更记录见修订说明。

本文档对解决你的问题有所帮助?