reCAPTCHA 的 JavaScript API 參考資料

本頁面說明 reCAPTCHA JavaScript API 的方法，以及可用於使用 reCAPTCHA 金鑰 (網站金鑰) 算繪網頁的設定參數。

reCAPTCHA JavaScript API 方法

本節說明 reCAPTCHA JavaScript API 方法的語法和參數。

grecaptcha.enterprise.render

將容器算繪為 reCAPTCHA 小工具，並傳回新建立的小工具 ID。

語法

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

方法參數

參數 說明
container 用於轉譯 reCAPTCHA 小工具的 HTML 元素。指定容器的 ID (字串) 或 DOM 元素本身。
parameters

含有參數的物件，格式為鍵/值組合，例如 {"sitekey": "your_site_key", "action": "login", "theme": "dark"}。

如要進一步瞭解各項可設定的參數，請參閱「屬性和參數」。

傳回值

傳回新建立的小工具 ID。

grecaptcha.enterprise.reset

重設 reCAPTCHA 小工具。

語法

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

參數

參數 說明
widget_id (選用步驟) 從 grecaptcha.enterprise.render() 傳回的小工具 ID。如未指定，預設值為建立的第一個小工具 ID。

傳回值

不會傳回值。

grecaptcha.enterprise.execute

以程式輔助方式叫用 reCAPTCHA 驗證。

語法

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

參數

參數 說明
widget_id (選用步驟) 從 grecaptcha.enterprise.render() 傳回的小工具 ID。

如未指定，預設值為建立的第一個小工具的 ID。
sitekey

指定要保護的 reCAPTCHA 網站金鑰。
action 具有單一鍵/值組合的物件，其中 action 鍵的值會指定與受保護元素相關聯的動作名稱。

例如：{"action": "action_name"}

傳回值

如果成功，則會傳回包含權杖的 Promise 物件。

grecaptcha.enterprise.ready

在載入 reCAPTCHA JavaScript 程式庫時執行函式。

語法

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

參數

參數 說明
callback reCAPTCHA 程式庫載入完成時要呼叫的函式。

傳回值

不會傳回值。

grecaptcha.enterprise.getResponse

取得 reCAPTCHA 小工具的回應。

語法

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

參數

參數 說明
widget_id (選用步驟) 從 grecaptcha.enterprise.render() 傳回的小工具 ID。如未指定，預設值為建立的第一個小工具的 ID。

傳回值

取得 reCAPTCHA 小工具的回應。如果尚未建立權杖，則可以是 grecaptcha.enterprise.execute() 建立的權杖字串，也可以是空字串。

設定

本節說明 JavaScript 資源參數，以及 grecaptcha.enterprise.render() 和 g-recaptcha 小工具屬性使用的參數。

JavaScript 資源 (enterprise.js) 參數

下表列出使用 reCAPTCHA 時必須加入的 JavaScript 資源 (enterprise.js) 參數。

如要進一步瞭解如何使用這些參數，請參閱「 在前端轉譯 reCAPTCHA 小工具」一文中的範例。

參數 值 說明
onload callback (選用步驟) 所有依附元件載入完畢後要執行的回呼函式名稱。
render onload

選用，預設值。在找到的第一個 g-recaptcha 標記中算繪小工具。
explicit

(選用步驟) 不會自動算繪小工具。您需要呼叫 grecaptcha.enterprise.render()，透過程式輔助方式算繪。
siteKey

搭配使用評分型網站金鑰時，這個參數為必填。 值 siteKey 會指定相關聯的評分式網站金鑰。
hl 請參閱語言代碼。 (選用步驟) 強制小工具以特定語言顯示。 如果未指定，系統會自動偵測使用者的語言。

g-recaptcha 標記屬性和 grecaptcha.enterprise.render() 參數

下表列出 g-recaptcha 標記屬性和對應的 grecaptcha.enterprise.render() 參數。

g-recaptcha 標記屬性 grecaptcha.enterprise.render() 參數 允許值 預設 說明
data-sitekey sitekey reCAPTCHA 金鑰。
data-badge badge bottomright、bottomleft、inline bottomright (選用步驟) 重新放置 reCAPTCHA 徽章。inline 可讓您使用 CSS 放置圖片。
data-action action (選用步驟) 描述目前動作的字串。
data-theme theme dark、light light (選用步驟) 小工具的顏色主題。
data-size size compact、normal normal (選用步驟) 小工具的大小。
data-tabindex tabindex 整數 0 (選用步驟) 小工具和驗證的 tabindex。如果網頁中的其他元素使用 tabindex，請設定該屬性，讓使用者更容易瀏覽。
data-callback callback 字串 不適用 (選用步驟) 回呼函式的名稱，會在使用者提交成功的回應時執行。g-recaptcha-response 權杖會傳遞至回呼。
data-expired-callback expired-callback 字串 不適用 (選用步驟) 回呼函式的名稱。當 reCAPTCHA 回應過期，且使用者需要重新驗證時，系統會執行這個函式。
data-error-callback error-callback 字串 不適用 (選用步驟) 回呼函式的名稱。當 reCAPTCHA 發生錯誤 (通常是網路連線問題) 時，系統會執行這個函式，且必須等到連線恢復後才能繼續。回呼不會收到任何包含錯誤詳細資料的引數。如果您在此指定函式，則有責任告知使用者應重試。