List icon Conteúdo

Navegação

Este guia descreve os eventos de navegação e mostra como carregar URLs e arquivos, filtrar pedidos de navegação, trabalhar com o histórico de navegação, etc.

Carregando a URL

Para navegar para um recurso identificado por um URL, utilize um dos seguintes métodos:

  • INavigation.LoadUrl(string url)
  • INavigation.LoadUrl(LoadUrlParameters parameters)

O exemplo abaixo mostra como navegar para https://www.google.com utilizando o método INavigation.LoadUrl(string) :

INavigation navigation = browser.Navigation;
navigation.LoadUrl("https://www.google.com");
Dim navigation As INavigation = browser.Navigation
navigation.LoadUrl("https://www.google.com")

Carregando URL de forma síncrona

O método LoadUrl envia um pedido de navegação para o recurso fornecido e devolve uma Task<NavigationResult> que pode ser utilizada para aguardar até que o recurso seja considerado completamente carregado.

Se for necessário bloquear a execução do thread atual até que o recurso seja completamente carregado, utilize o método Task.Wait() :

navigation.LoadUrl("https://www.google.com").Wait();
navigation.LoadUrl("https://www.google.com").Wait()

Este método bloqueia a execução do segmento atual até que a estrutura principal do recurso seja completamente carregada ou até que o tempo limite predefinido de 100 segundos seja atingido.

Se a navegação falhar, a Task<NavigationResult> devolvida é concluída e a sua propriedade Task.Result devolve os pormenores sobre a possível falha de navegação.

Se o recurso não for carregado num determinado período, ocorre a exceção TimeoutException .

Considera-se que a página Web está completamente carregada quando ocorre pelo menos um dos seguintes eventos, nomeadamente, FrameLoadFinished, NavigationFinished ou FrameLoadFailed para o frame principal.

Carregamento de URL com POST

Para carregar uma página Web pelo seu URL e enviar dados POST, utilize o método INavigation.LoadUrl(LoadUrlParameters) . O código seguinte demonstra como carregar URL e enviar dados POST em diferentes formatos utilizando cabeçalhos extra.

É possível enviar os dados de um formulário Web no formato key=value para um servidor Web:

navigation.LoadUrl(new LoadUrlParameters("https://postman-echo.com/post")
{
    UploadData = new FormData(new Dictionary<string, string>()
    {
        {"key", "value"}
    })
});
navigation.LoadUrl(New LoadUrlParameters("https://postman-echo.com/post") With {
    .UploadData = New FormData(New Dictionary(Of String, String)() From {
        {"key", "value"}
    })
})

É necessário especificar explicitamente o cabeçalho “Content-Type” para cada tipo de pedido.

Se você quiser enviar um texto simples, adicione os cabeçalhos adicionais que indicam ao servidor Web que se trata de um texto simples:

navigation.LoadUrl(new LoadUrlParameters("https://postman-echo.com/post")
{
    UploadData = new TextData("Algum texto..."),
    HttpHeaders = new[]
    {
        new HttpHeader("Content-Type", "text/plain")
    }
});
navigation.LoadUrl(New LoadUrlParameters("https://postman-echo.com/post") With {
    .UploadData = New TextData("Algum texto..."),
    .HttpHeaders = 
    { 
        New HttpHeader("Content-Type", "text/plain") 
    }
})

Você pode enviar quaisquer dados de vários tipos. Para fazer isso, especifique o seu Content-Type. Veja o exemplo de código sobre o envio de dados JSON abaixo:

navigation.LoadUrl(new LoadUrlParameters("https://postman-echo.com/post")
{
    PostData = "{\"title\":\"Olá\"}",
    HttpHeaders = new[]
    {
        new HttpHeader("Content-Type", "application/json")
    }
});
navigation.LoadUrl(New LoadUrlParameters("https://postman-echo.com/post") With {
    .PostData = "{""title"":""Olá""}",
    .HttpHeaders = 
    { 
        New HttpHeader("Content-Type", "application/json") 
    }
})

Carregando um arquivo

É possível utilizar os mesmos métodos para carregar arquivos HTML a partir do sistema de arquivos local, fornecendo um caminho absoluto para o arquivo HTML em vez de uma URL. Veja o exemplo de código abaixo:

navigation.LoadUrl(Path.GetFullPath("index.html"));
navigation.LoadUrl(Path.GetFullPath("index.html"))

Carregamento de HTML

Para carregar HTML no browser, pode criar um URI codificado data: e depois carregá-lo utilizando a chamada regular LoadUrl . Eis um exemplo:

var html = "<html><head></head><body><h1>Html codificado no URL!</h1></body></html>";
var base64EncodedHtml = Convert.ToBase64String(Encoding.UTF8.GetBytes(html));
browser.Navigation.LoadUrl("data:text/html;base64," + base64EncodedHtml).Wait();
Dim html = "<html><head></head><body><h1>Html codificado no URL!</h1></body></html>"
Dim base64EncodedHtml = Convert.ToBase64String(Encoding.UTF8.GetBytes(html))
browser.Navigation.LoadUrl("data:text/html;base64," & base64EncodedHtml).Wait()

O Chromium limita os URIs codificados com dados a um comprimento máximo de 2MB.

No entanto, o URL de base não pode ser definido quando se utiliza esta abordagem.

Outra abordagem possível é registrar um Scheme com um handler e interceptar o pedido correspondente para fornecer o HTML. Veja o artigo correspondente.

Recarregando

Existem várias opções para recarregar a página Web atualmente carregada:

  • Recarregar utilizando a cache HTTP:
navigation.Reload();
navigation.Reload()
  • Recarregar ignorando a cache HTTP:
navigation.ReloadIgnoringCache();
navigation.ReloadIgnoringCache()
  • Recarregar utilizando a cache HTTP e verificar se há repostagem:
navigation.ReloadAndCheckForRepost();
navigation.ReloadAndCheckForRepost()
  • Recarregar ignorando a cache HTTP e verificar se há repostagem:
navigation.ReloadIgnoringCacheAndCheckForRepost();
navigation.ReloadIgnoringCacheAndCheckForRepost()

Parada

Utilize o método INavigation.Stop() para cancelar qualquer operação de navegação ou download pendente e parar quaisquer elementos dinâmicos da página, como sons de fundo e animações. Veja o exemplo de código abaixo:

navigation.Stop();
navigation.Stop()

Voltar e Avançar

O DotNetBrowser permite trabalhar com a lista de histórico de navegação para trás e para a frente.

Quando você cria uma instância do IBrowser, ela navega para a página web about:blank por padrão. Existe sempre uma entrada na lista de navegação para trás e para a frente.

Para carregar a localização anterior na lista de retrocesso, utilize a seguinte abordagem:

if (navigation.CanGoBack()) {
    navigation.GoBack();
}
If navigation.CanGoBack() Then
    navigation.GoBack()
End If

Para carregar a localização seguinte na lista de retrocesso, utilize a seguinte abordagem:

if (navigation.CanGoForward()) {
    navigation.GoForward();
}
If navigation.CanGoForward() Then
    navigation.GoForward()
End If

Para navegar para a entrada num índice específico na lista anterior, utilize a seguinte abordagem:

if (index >=0 && index < navigation.EntryCount) {
    navigation.GoTo(index);
}
If index >=0 AndAlso index < navigation.EntryCount Then
    navigation.GoTo(index)
End If

Para percorrer a lista anterior e obter os detalhes de cada entrada de navegação, utilize a seguinte abordagem:

for (int index = 0; index < navigation.EntryCount; index++) {
    INavigationEntry navigationEntry = navigation.EntryAt(index);
    Console.WriteLine("URL: " + navigationEntry.Url);
    Console.WriteLine("Title: " + navigationEntry.Title);
}
For index As Integer = 0 To navigation.EntryCount - 1
    Dim navigationEntry As INavigationEntry = navigation.EntryAt(index)
    Console.WriteLine("URL: " & navigationEntry.Url)
    Console.WriteLine("Title: " & navigationEntry.Title)
Next

Para modificar a lista de reenvio removendo as entradas, utilize a seguinte abordagem:

// Retorna o número de entradas na lista de voltar/avançar.
int entryCount = navigation.EntryCount;
// Remove entradas de navegação no índice.
for (int i = entryCount - 2; i >= 0; i--) {
    bool success = navigation.RemoveEntryAt(i);
    Console.WriteLine("A entrada de navegação no índice " + i +
            " foi removida com êxito? " + success);
}
' Retorna o número de entradas na lista de voltar/avançar.
Dim entryCount As Integer = navigation.EntryCount
' Remove as entradas de navegação no índice.
For i As Integer = entryCount - 2 To 0 Step -1
    Dim success As Boolean = navigation.RemoveEntryAt(i)
    Console.WriteLine("A entrade de navegação no índice " & i & 
                      " foi removida com sucesso? " & success)
Next

No modo de renderização acelerada por hardware, o DotNetBrowser permite navegar para trás/para a frente com um deslize para a esquerda/direita em dispositivos com tela tátil. Por padrão, a navegação de deslocamento por overscroll está desativada. Para a ativar, utilize a propriedade IBrowserSettings.OverscrollHistoryNavigationEnabled:

browser.Settings.OverscrollHistoryNavigationEnabled = true;
browser.Settings.OverscrollHistoryNavigationEnabled = True

Filtrando URLs

Você pode decidir se o pedido de navegação para um URL específico é ignorado.

Veja o exemplo de código abaixo mostrando como ignorar os pedidos de navegação para todos os URLs que começam com https://www.google:

navigation.StartNavigationHandler = 
    new Handler<StartNavigationParameters, StartNavigationResponse>((p) =>
    {
        // Ignorar pedidos de navegação para os URLs que começam 
        // com "https://www.google"
        if (p.Url.StartsWith("https://www.google"))
        {
            return StartNavigationResponse.Ignore();
        }
        return StartNavigationResponse.Start();
    });
navigation.StartNavigationHandler = 
    New Handler(Of StartNavigationParameters, StartNavigationResponse)(Function(p)
        ' Ignorar pedidos de navegação para os URLs que começam
        ' com "https://www.google".
        If p.Url.StartsWith("https://www.google") Then
            Return StartNavigationResponse.Ignore()
        End If
        Return StartNavigationResponse.Start()
    End Function)

Filtrando recursos

O handler SendUrlRequestHandler permite-lhe determinar se os recursos como HTML, imagem, arquivo JavaScript ou CSS, favicon e outros estão carregados. Por padrão, todos os recursos são carregados. Para modificar o comportamento padrão, registre a sua própria implementação do handler onde você decide quais os recursos que são cancelados ou carregados.

Veja o exemplo de código abaixo que mostra como suprimir todas as imagens:

engine.Network.SendUrlRequestHandler =
    new Handler<SendUrlRequestParameters, SendUrlRequestResponse>(p =>
    {
        if (p.UrlRequest.ResourceType == ResourceType.Image)
        {
            return SendUrlRequestResponse.Cancel();
        }
        return SendUrlRequestResponse.Continue();
    });
engine.Network.SendUrlRequestHandler = 
    New Handler(Of SendUrlRequestParameters, SendUrlRequestResponse)(Function(p)
        If p.UrlRequest.ResourceType = ResourceType.Image Then
            Return SendUrlRequestResponse.Cancel()
        End If
        Return SendUrlRequestResponse.Continue()
    End Function)

Eventos de navegação

O carregamento de uma página Web é um processo complexo em que são acionados eventos de navegação. O diagrama seguinte mostra a ordem dos eventos de navegação que podem ser acionados durante o carregamento de uma página Web: Fluxo de eventos de navegação

Carregamento iniciado

Para obter notificações quando o carregamento de conteúdos tiver começado, utilize o evento LoadStarted . Veja o exemplo de código abaixo:

navigation.LoadStarted += (s, e) => {};
AddHandler navigation.LoadStarted, Sub(s, e)
End Sub

Este evento corresponde ao momento em que o spinner da aba começa a rodar.

Carregamento concluído

Para obter notificações quando o carregamento de conteúdos tiver terminado, utilize o evento LoadFinished . Por exemplo:

navigation.LoadFinished += (s, e) => {};
AddHandler navigation.LoadFinished, Sub(s, e)
End Sub

Este evento corresponde ao momento em que o spinner do aba para de rodar.

Progresso de carregamento

O evento LoadProgressChanged permite obter notificações sobre o progresso do carregamento:

navigation.LoadProgressChanged += (s, e) =>
{
    // O valor que indica o progresso do carregamento da página web.
    double progress = e.Progress;
};
AddHandler navigation.LoadProgressChanged, Sub(s, e)
    ' O valor que indica o progresso do carregamento da página web.
    Dim progress As Double = e.Progress
End Sub

Início da navegação

Para receber notificações quando a navegação tiver começado, utilize o evento NavigationStarted . Veja o exemplo de código abaixo:

navigation.NavigationStarted += (s, e) => 
{
    string url = e.Url;
    // Indica se a navegação será realizada
    // no escopo do mesmo documento.
    bool isSameDocument = e.IsSameDocument;
};
AddHandler navigation.NavigationStarted, Sub(s, e)
    Dim url As String = e.Url
    ' Indica se a navegação será realizada
    ' no escopo do mesmo documento.
    Dim isSameDocument As Boolean = e.IsSameDocument
End Sub

Para receber notificações quando a navegação tiver parado, utilize o evento NavigationStopped . Veja o exemplo de código abaixo:

navigation.NavigationStopped += (s, e) => {};
AddHandler navigation.NavigationStopped, Sub(s, e)
End Sub

Este evento é ativado quando a navegação é interrompida utilizando o método Navigation.stop() .

Para receber notificações quando a navegação tiver sido redirecionada para um novo URL, utilize o evento NavigationRedirected. Veja o exemplo de código abaixo:

navigation.NavigationRedirected += (s, e) => {
    // A navegação redireciona a URL.
    string url = e.Url;
};
AddHandler navigation.NavigationRedirected, Sub(s, e)
    ' O URL de redirecionamento da navegação.
    Dim url As String = e.Url
End Sub

Para receber notificações quando a navegação tiver terminado, utilize o evento NavigationFinished . Veja o exemplo de código abaixo:

navigation.NavigationFinished += (s, e) => {
    string url = e.Url;
    IFrame frame = e.Frame;
    bool hasCommitted = e.HasCommitted;
    bool isSameDocument = e.IsSameDocument;
    bool isErrorPage = e.IsErrorPage;
    if (isErrorPage) {
        NetError error = e.ErrorCode;
    }
};
AddHandler navigation.NavigationFinished, Sub(s, e)
    Dim url As String = e.Url
    Dim frame As IFrame = e.Frame
    Dim hasCommitted As Boolean = e.HasCommitted
    Dim isSameDocument As Boolean = e.IsSameDocument
    Dim isErrorPage As Boolean = e.IsErrorPage
    If isErrorPage Then
        Dim [error] As NetError = e.ErrorCode
    End If
End Sub

Este evento é disparado quando a navegação é confirmada, abortada ou substituída por uma nova. Para saber se a navegação foi confirmada, utilize NavigationFinishedEventArgs.HasCommitted. Para saber se a navegação resultou numa página de erro, utilize NavigationFinishedEventArgs.IsErrorPage.

Se o evento for chamado porque a navegação foi comprometida, o carregamento do documento ainda estará em curso.

O evento é disparado por navegações do mesmo documento (no âmbito do mesmo documento), tais como navegações de fragmentos ou window.history.pushState()/window.history.replaceState(), que não resultam numa alteração do documento. Utilize a propriedade NavigationFinishedEventArgs.IsSameDocument para verificar se se trata de uma navegação no mesmo documento.

Carregamento do frame terminado

Para receber notificações quando o carregamento de conteúdo no IFrame tiver terminado, utilize o evento FrameLoadFinished . Veja o exemplo de código abaixo:

navigation.FrameLoadFinished += (s, e) =>
{
    string url = e.ValidatedUrl;
    IFrame frame = e.Frame;
};
AddHandler navigation.FrameLoadFinished, Sub(s, e)
    Dim url As String = e.ValidatedUrl
    Dim frame As IFrame = e.Frame
End Sub

Este evento corresponde ao momento em que o conteúdo do Frame foi completamente carregado.

Falha no carregamento do frame

Para receber notificações quando o carregamento de conteúdo no Frame tiver falhado por algum motivo, utilize o evento FrameLoadFailed . Veja o exemplo de código abaixo:

navigation.FrameLoadFailed += (s, e) =>
{
    string url = e.ValidatedUrl;
    NetError error = e.ErrorCode;
};
AddHandler navigation.FrameLoadFailed, Sub(s, e)
    Dim url As String = e.ValidatedUrl
    Dim [error] As NetError = e.ErrorCode
End Sub

Carregamento do documento no frame terminado

Para receber notificações quando o carregamento do documento no Frame tiver terminado, utilize o evento FrameDocumentLoadFinished . Veja o exemplo de código abaixo:

navigation.FrameDocumentLoadFinished += (s, e) => 
{
    IFrame frame = e.Frame;
};
AddHandler navigation.FrameDocumentLoadFinished, Sub(s, e)
    Dim frame As IFrame = e.Frame
End Sub

Neste ponto, os scripts diferidos foram executados e os scripts de conteúdo marcados como document_end são injetados no frame.

Página de erro personalizada

Para substituir as páginas de erro padrão do Chromium, utilize os handlers ShowHttpErrorPageHandler e ShowNetErrorPageHandler para erros HTTP (por exemplo, 404 Not Found) ou de rede (por exemplo, ERR_CONNECTION_REFUSED), respectivamente. Veja exemplos abaixo:

Página de erro HTTP

browser.Navigation.ShowHttpErrorPageHandler =
    new Handler<ShowHttpErrorPageParameters, ShowHttpErrorPageResponse>(arg =>
    {
        string url = arg.Url;
        HttpStatusCode httpStatusCode = arg.HttpStatus;
        return ShowHttpErrorPageResponse.Show("HTTP Error web page:" + httpStatusCode);
    });
browser.Navigation.ShowHttpErrorPageHandler = 
    New Handler(Of ShowHttpErrorPageParameters, ShowHttpErrorPageResponse)(Function(arg)
        Dim url As String = arg.Url
        Dim httpStatusCode As HttpStatusCode = arg.HttpStatus
        Return ShowHttpErrorPageResponse.Show("HTTP Error web page:" & httpStatusCode)
    End Function)

Página de erro de rede

browser.Navigation.ShowNetErrorPageHandler = 
    new Handler<ShowNetErrorPageParameters, ShowNetErrorPageResponse>(arg =>
    {
        return ShowNetErrorPageResponse.Show("Network error web page");
    });
browser.Navigation.ShowNetErrorPageHandler = 
    New Handler(Of ShowNetErrorPageParameters, ShowNetErrorPageResponse)(Function(arg)
        Return ShowNetErrorPageResponse.Show("Network error web page")
    End Function)

As páginas de erro personalizadas fornecidas pelos servidores não são interceptadas por estes handlers e não podem ser substituídas utilizando esta funcionalidade. Os handlers acima são invocados apenas para substituir as páginas de erro padrão do Chromium.

Go Top