Referência da API JavaScript para o reCAPTCHA

Esta página descreve os métodos da API JavaScript do reCAPTCHA e os respetivos parâmetros de configuração que pode usar para renderizar as páginas Web com uma chave do reCAPTCHA (chave de site).

Métodos da API JavaScript reCAPTCHA

Esta secção descreve a sintaxe e os parâmetros dos métodos da API JavaScript do reCAPTCHA.

grecaptcha.enterprise.render

Renderiza o contentor como um widget reCAPTCHA e devolve o ID do widget criado recentemente.

Sintaxe

grecaptcha.enterprise.render(container: string | HTMLelement, parameters: Object): number

Parâmetros do método

Parâmetro Descrição
container O elemento HTML para renderizar o widget reCAPTCHA. Especifique o ID do contentor (string) ou o próprio elemento DOM.
parameters

Um objeto que contém parâmetros como pares de chave=valor, por exemplo, {"sitekey": "your_site_key", "action": "login", "theme": "dark"}.

Consulte o artigo Atributos e parâmetros para ver detalhes sobre cada parâmetro configurável.

Valor devolvido

Devolve o ID do widget recém-criado.

grecaptcha.enterprise.reset

Repõe o widget reCAPTCHA.

Sintaxe

grecaptcha.enterprise.reset(widget_id: number): void

Parâmetros

Parâmetro Descrição
widget_id Opcional. ID do widget devolvido por grecaptcha.enterprise.render(). Se não for especificado, o valor predefinido é o ID do primeiro widget criado.

Valor devolvido

Não devolve um valor.

grecaptcha.enterprise.execute

Invoca programaticamente a validação reCAPTCHA.

Sintaxe

grecaptcha.enterprise.execute(widget_id: number): Promise<string>
 
grecaptcha.enterprise.execute(sitekey: string, action: Object): Promise<string>

Parâmetros

Parâmetro Descrição
widget_id Opcional. ID do widget devolvido por grecaptcha.enterprise.render().

Se não for especificado, o valor predefinido é o ID do primeiro widget que foi criado.
sitekey

Especifique a chave de site do reCAPTCHA a proteger.
action Um objeto com um único par chave=valor, em que o valor da chave action especifica o nome da ação associada ao elemento protegido.

Por exemplo: {"action": "action_name"}

Valor devolvido

Se for bem-sucedido, devolve um objeto Promise que contém o token se for bem-sucedido.

grecaptcha.enterprise.ready

Executa a sua função quando a biblioteca de JavaScript do reCAPTCHA é carregada.

Sintaxe

grecaptcha.enterprise.ready(callback: function): void

Parâmetros

Parâmetro Descrição
callback A função a chamar quando a biblioteca reCAPTCHA terminar o carregamento.

Valor devolvido

Não devolve um valor.

grecaptcha.enterprise.getResponse

Obtém a resposta para o widget reCAPTCHA.

Sintaxe

grecaptcha.enterprise.getResponse(widget_id: number): string

Parâmetros

Parâmetro Descrição
widget_id Opcional. ID do widget devolvido por grecaptcha.enterprise.render(). Se não for especificado, o valor predefinido é o ID do primeiro widget criado.

Valor devolvido

Obtém a resposta do widget reCAPTCHA. Pode ser uma string com o token criado por grecaptcha.enterprise.execute() ou uma string vazia se o token ainda não tiver sido criado.

Configuração

Esta secção descreve os parâmetros de recursos JavaScript e os parâmetros usados por grecaptcha.enterprise.render() e os atributos do widget g-recaptcha.

Parâmetros de recursos JavaScript (enterprise.js)

A tabela seguinte apresenta os parâmetros do recurso JavaScript (enterprise.js) que tem de incluir quando usa o reCAPTCHA.

Para mais informações sobre a utilização destes parâmetros, consulte os exemplos em Renderizar o widget reCAPTCHA no frontend.

Parâmetro Valor Descrição
onload callback Opcional. O nome da função de chamada de retorno a ser executada depois de todas as dependências terem sido carregadas.
render onload

Opcional, valor predefinido. Renderiza o widget na primeira etiqueta g-recaptcha que encontrar.
explicit

Opcional. Não renderiza o widget automaticamente. Tem de chamar grecaptcha.enterprise.render() para a renderizar programaticamente.
siteKey

Quando usado com chaves do site baseadas em pontuação, este parâmetro não é opcional. O valor siteKey especifica a chave do site baseada em pontuação associada.
hl Veja os códigos de idioma. Opcional. Força a renderização do widget num idioma específico. Deteta automaticamente o idioma do utilizador se não for especificado.

Atributos da etiqueta g-recaptcha e parâmetros grecaptcha.enterprise.render()

A tabela seguinte lista os atributos da etiqueta g-recaptcha e os parâmetros grecaptcha.enterprise.render() correspondentes.

Atributo da etiqueta g-recaptcha Parâmetro grecaptcha.enterprise.render() Valores permitidos Predefinição Descrição
data-sitekey sitekey Chave reCAPTCHA.
data-badge badge bottomright, bottomleft, inline bottomright Opcional. Reposicione o emblema do reCAPTCHA. inline permite-lhe posicioná-lo com CSS.
data-action action Opcional. String que descreve a ação atual.
data-theme theme dark, light light Opcional. O tema de cores do widget.
data-size size compact, normal normal Opcional. O tamanho do widget.
data-tabindex tabindex Número inteiro 0 Opcional. O tabindex do widget e do desafio. Se outros elementos na sua página usarem tabindex, este deve ser definido para facilitar a navegação do utilizador.
data-callback callback String N/A Opcional. O nome da sua função de callback, executada quando o utilizador envia uma resposta bem-sucedida. O token g-recaptcha-response é transmitido ao seu callback.
data-expired-callback expired-callback String N/A Opcional. O nome da sua função de chamada de retorno, executada quando a resposta do reCAPTCHA expira e o utilizador tem de voltar a validar.
data-error-callback error-callback String N/A Opcional. O nome da sua função de retorno de chamada, executada quando o reCAPTCHA encontra um erro (normalmente, conetividade de rede) e não pode continuar até que a conetividade seja restaurada. A função de retorno de chamada não recebe argumentos com detalhes do erro. Se especificar uma função aqui, é responsável por informar o utilizador de que deve tentar novamente.