Delphi WebView2 in FMX: Entscheidungspfad für Lifecycle, Bridge, Downloads und stabile Dispose-Logik

unit NbWebView2Host;

interface

uses
  System.SysUtils, System.Classes, System.IOUtils, System.JSON,
  Winapi.Windows, Winapi.ActiveX,
  FMX.Types,
  WebView2, WebView2_TLB;

type
  TWebView2State = (wvsCreated, wvsInitializing, wvsReady, wvsDisposed);

  TWebView2JsonMessage = record
    Name: string;
    Cid: string;
    Payload: TJSONObject;
    class function TryParse(const S: string; out M: TWebView2JsonMessage): Boolean; static;
  end;

  TOnWebMessage = reference to procedure(const M: TWebView2JsonMessage);
  TOnDownloadMeta = reference to procedure(const Uri, MimeType, SuggestedFileName: string; TotalBytes: Int64);

  TNbWebView2Host = class
  private
    FParentHwnd: HWND;
    FState: TWebView2State;

    FUserDataFolder: string;
    FEnvironment: ICoreWebView2Environment;
    FController: ICoreWebView2Controller;
    FWebView: ICoreWebView2;

    FTokenWebMsg: EventRegistrationToken;
    FTokenDownload: EventRegistrationToken;

    FOnWebMessage: TOnWebMessage;
    FOnDownloadMeta: TOnDownloadMeta;

    procedure RequireState(const Allowed: array of TWebView2State);
    function EffectiveUserDataFolder: string;

    procedure HookEvents;
    procedure UnhookEvents;

    procedure HandleWebMessage(const args: ICoreWebView2WebMessageReceivedEventArgs);
    procedure HandleDownloadStarting(const args: ICoreWebView2DownloadStartingEventArgs);

  public
    constructor Create(AParentHwnd: HWND; const AUserDataFolder: string = '');
    destructor Destroy; override;

    procedure InitializeAsync;
    procedure Dispose;

    procedure Navigate(const Url: string);
    procedure ResizePx(const BoundsPx: TRect);

    procedure PostJson(const Obj: TJSONObject);

    property State: TWebView2State read FState;
    property WebView: ICoreWebView2 read FWebView;

    property OnWebMessage: TOnWebMessage read FOnWebMessage write FOnWebMessage;
    property OnDownloadMeta: TOnDownloadMeta read FOnDownloadMeta write FOnDownloadMeta;
  end;

implementation

class function TWebView2JsonMessage.TryParse(const S: string; out M: TWebView2JsonMessage): Boolean;
var
  V: TJSONValue;
  O: TJSONObject;
  P: TJSONValue;
begin
  Result := False;
  M.Name := '';
  M.Cid := '';
  M.Payload := nil;

  V := TJSONObject.ParseJSONValue(S);
  try
    if not (V is TJSONObject) then Exit;
    O := TJSONObject(V);

    M.Name := O.GetValue('name', '');
    M.Cid  := O.GetValue('cid', '');

    if O.TryGetValue('payload', P) and (P is TJSONObject) then
      M.Payload := TJSONObject(P.Clone)
    else
      M.Payload := TJSONObject.Create;

    Result := M.Name <> '';
  finally
    V.Free;
  end;
end;

constructor TNbWebView2Host.Create(AParentHwnd: HWND; const AUserDataFolder: string);
begin
  inherited Create;
  FParentHwnd := AParentHwnd;
  FUserDataFolder := AUserDataFolder;
  FState := wvsCreated;
  FTokenWebMsg.value := 0;
  FTokenDownload.value := 0;
end;

destructor TNbWebView2Host.Destroy;
begin
  Dispose;
  inherited;
end;

procedure TNbWebView2Host.RequireState(const Allowed: array of TWebView2State);
var
  S: TWebView2State;
  Ok: Boolean;
  I: Integer;
begin
  Ok := False;
  for I := Low(Allowed) to High(Allowed) do
    if FState = Allowed[I] then
      Ok := True;

  if not Ok then
  begin
    for S := Low(TWebView2State) to High(TWebView2State) do begin end; // nur, um Enum im Debug sichtbar zu halten
    raise EInvalidOperation.CreateFmt('WebView2Host: ungültiger Zustand (%d).', [Ord(FState)]);
  end;
end;

function TNbWebView2Host.EffectiveUserDataFolder: string;
begin
  if FUserDataFolder <> '' then
    Exit(FUserDataFolder);

  // Stabiler, pro Windows-User; bewusst nicht im Installationsordner.
  Result := TPath.Combine(TPath.GetHomePath, 'MyCompany\MyApp\WebView2UserData');
  ForceDirectories(Result);
end;

procedure TNbWebView2Host.InitializeAsync;
var
  Opt: ICoreWebView2EnvironmentOptions;
  UserData: string;
begin
  RequireState([wvsCreated]);
  FState := wvsInitializing;

  UserData := EffectiveUserDataFolder;
  Opt := TCoreWebView2EnvironmentOptions.Create;

  OleCheck(CreateCoreWebView2EnvironmentWithOptions(
    nil,
    PWideChar(UserData),
    Opt,
    TCoreWebView2CreateCoreWebView2EnvironmentCompletedHandler.Create(
      procedure(errorCode: HRESULT; const createdEnvironment: ICoreWebView2Environment)
      begin
        if FState = wvsDisposed then Exit;
        OleCheck(errorCode);
        FEnvironment := createdEnvironment;

        OleCheck(FEnvironment.CreateCoreWebView2Controller(
          FParentHwnd,
          TCoreWebView2CreateCoreWebView2ControllerCompletedHandler.Create(
            procedure(errorCode2: HRESULT; const createdController: ICoreWebView2Controller)
            begin
              if FState = wvsDisposed then Exit;
              OleCheck(errorCode2);

              FController := createdController;
              OleCheck(FController.get_CoreWebView2(FWebView));

              HookEvents;
              OleCheck(FController.put_IsVisible(1));
              FState := wvsReady;
            end)));
      end)));
end;

procedure TNbWebView2Host.HookEvents;
begin
  if FWebView = nil then Exit;

  OleCheck(FWebView.add_WebMessageReceived(
    TCoreWebView2WebMessageReceivedEventHandler.Create(
      procedure(const sender: ICoreWebView2; const args: ICoreWebView2WebMessageReceivedEventArgs)
      begin
        if FState = wvsDisposed then Exit;
        HandleWebMessage(args);
      end),
    FTokenWebMsg));

  OleCheck(FWebView.add_DownloadStarting(
    TCoreWebView2DownloadStartingEventHandler.Create(
      procedure(const sender: ICoreWebView2; const args: ICoreWebView2DownloadStartingEventArgs)
      begin
        if FState = wvsDisposed then Exit;
        HandleDownloadStarting(args);
      end),
    FTokenDownload));
end;

procedure TNbWebView2Host.UnhookEvents;
begin
  // Wichtig: remove_* reduziert Nachläufer nach Dispose.
  if FWebView <> nil then
  begin
    if FTokenWebMsg.value <> 0 then
      FWebView.remove_WebMessageReceived(FTokenWebMsg);
    if FTokenDownload.value <> 0 then
      FWebView.remove_DownloadStarting(FTokenDownload);
  end;
  FTokenWebMsg.value := 0;
  FTokenDownload.value := 0;
end;

procedure TNbWebView2Host.Dispose;
begin
  if FState = wvsDisposed then Exit;
  FState := wvsDisposed;

  UnhookEvents;

  // Reihenfolge: erst WebView/Controller lösen, dann Environment.
  FWebView := nil;
  FController := nil;
  FEnvironment := nil;
end;

procedure TNbWebView2Host.Navigate(const Url: string);
begin
  RequireState([wvsReady]);
  OleCheck(FWebView.Navigate(PWideChar(Url)));
end;

procedure TNbWebView2Host.ResizePx(const BoundsPx: TRect);
var
  R: tagRECT;
begin
  if (FState <> wvsReady) or (FController = nil) then Exit;

  R.Left := BoundsPx.Left;
  R.Top := BoundsPx.Top;
  R.Right := BoundsPx.Right;
  R.Bottom := BoundsPx.Bottom;
  OleCheck(FController.put_Bounds(R));
end;

procedure TNbWebView2Host.PostJson(const Obj: TJSONObject);
var
  S: string;
begin
  if (FState <> wvsReady) or (FWebView = nil) then Exit;
  S := Obj.ToJSON;
  OleCheck(FWebView.PostWebMessageAsString(PWideChar(S)));
end;

procedure TNbWebView2Host.HandleWebMessage(const args: ICoreWebView2WebMessageReceivedEventArgs);
var
  P: PWideChar;
  S: string;
  M: TWebView2JsonMessage;
begin
  P := nil;
  OleCheck(args.TryGetWebMessageAsString(P));
  try
    S := P;
  finally
    CoTaskMemFree(P);
  end;

  if not Assigned(FOnWebMessage) then Exit;
  if not TWebView2JsonMessage.TryParse(S, M) then Exit;

  try
    // UI-Update hier nicht direkt erzwingen: in der App-Schicht ggf. TThread.Queue nutzen.
    FOnWebMessage(M);
  finally
    M.Payload.Free;
  end;
end;

procedure TNbWebView2Host.HandleDownloadStarting(const args: ICoreWebView2DownloadStartingEventArgs);
var
  Dl: ICoreWebView2DownloadOperation;
  Uri, Mime, ResultPath: PWideChar;
  Total: Int64;
  Suggested: string;
begin
  Uri := nil;
  Mime := nil;
  ResultPath := nil;

  OleCheck(args.get_DownloadOperation(Dl));
  OleCheck(Dl.get_TotalBytesToReceive(Total));
  OleCheck(Dl.get_Uri(Uri));
  OleCheck(Dl.get_MimeType(Mime));
  OleCheck(Dl.get_ResultFilePath(ResultPath));

  try
    Suggested := ExtractFileName(string(ResultPath));
    if Suggested = '' then Suggested := 'download.bin';

    if Assigned(FOnDownloadMeta) then
      FOnDownloadMeta(string(Uri), string(Mime), Suggested, Total);

    // Variante: eigenes Handling aktivieren
    // args.put_Handled(1);
  finally
    CoTaskMemFree(Uri);
    CoTaskMemFree(Mime);
    CoTaskMemFree(ResultPath);
  end;
end;

end.