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 發生錯誤 (通常是網路連線問題) 時，系統會執行這個函式，且必須等到連線恢復後才能繼續。回呼不會收到任何包含錯誤詳細資料的引數。如果您在此指定函式，則有責任告知使用者應重試。