本頁說明如何在網頁上顯示和自訂 reCAPTCHA v2 小工具。
如要顯示小工具,您可以採取下列任一做法:
如要瞭解如何自訂小工具,請參閱「設定」一節。舉例來說,您可以指定小工具的語言或主題。
請參閱「驗證使用者的回應」,看看使用者是否已成功通過人機驗證 (CAPTCHA)。
自動轉譯 reCAPTCHA 小工具
如要在網頁轉譯 reCAPTCHA 小工具,最簡單的方法就是加入必要的 JavaScript 資源和 g-recaptcha
標記。g-recaptcha
標記是 DIV 元素,在 data-sitekey
屬性中具有類別名稱 g-recaptcha
和網站金鑰:
<html>
<head>
<title>reCAPTCHA demo: Simple page</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form action="?" method="POST">
<div class="g-recaptcha" data-sitekey="your_site_key"></div>
<br/>
<input type="submit" value="Submit">
</form>
</body>
</html>
指令碼必須使用 HTTPS 通訊協定載入,且可由網頁的任何位置加入,不受任何限制。
明確轉譯 reCAPTCHA 小工具
您可以指定 onload 回呼函式,並新增參數至 JavaScript 資源,藉此延後轉譯作業。
指定
onload
回呼函式。所有依附元件載入完畢後,系統就會呼叫此函式。<script type="text/javascript"> var onloadCallback = function() { alert("grecaptcha is ready!"); }; </script>
插入 JavaScript 資源,將
onload
參數設為 onload 回呼函式的名稱,並將render
參數設為explicit
。<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit" async defer> </script>
執行回呼後,您可以從 JavaScript API 呼叫
grecaptcha.render
方法。
設定
JavaScript 資源 (api.js) 參數
參數 | 價值 | 說明 |
---|---|---|
onload | 選用設定。所有依附元件載入後要執行的回呼函式名稱。 | |
算繪 | 明確 載入 |
選用設定。是否明確算繪小工具。預設為 onload,在第一個找到的 g-recaptcha 標記中算繪小工具。 |
hl | 查看語言代碼 | 選用設定。強制小工具以特定語言顯示。如未指定,則會自動偵測使用者的語言。 |
g-recaptcha 標記屬性和 grecaptcha.render 參數
g-recaptcha 標記屬性 | grecaptcha.render 參數 | 價值 | 預設 | 說明 |
---|---|---|---|---|
資料 - 網站鍵 | 網站鍵 | 您的網站金鑰。 | ||
資料主題 | 主題 | 深淺 | 燈具 | 選用設定。小工具的顏色主題。 |
data-size | 大小 | 精簡正常 | 一般 | 選用設定。小工具的大小。 |
資料分頁索引 | Tabindex | 0 | 選用設定。小工具和挑戰的分頁索引。如果網頁中的其他元素使用 Tabindex,則應該設定用於方便使用者瀏覽。 | |
資料回呼 | 回呼 | 選用設定。回呼函式的名稱,會在使用者提交成功回應時執行。g-recaptcha-response 權杖會傳遞至回呼。 |
||
資料過期的回呼 | 過期的回呼 | 選用設定。回呼函式的名稱,會在 reCAPTCHA 回應到期時執行,讓使用者必須重新驗證。 | ||
資料錯誤-回呼 | 錯誤回呼 | 選用設定。回呼函式的名稱;reCAPTCHA 遇到錯誤時就會執行此函式 (通常是網路連線),直到連線恢復為止。如果您在這裡指定函式,則需負責通知使用者應重試。 |
JavaScript API
方法 | 說明 |
---|---|
grecaptcha.render( 容器
參數
|
將容器顯示為 reCAPTCHA 小工具,並傳回新建立小工具的 ID。 container 用來轉譯 reCAPTCHA 小工具的 HTML 元素。請指定容器 (字串) 的 ID 或 DOM 元素本身的 ID。 參數 包含鍵/值組合參數的物件,例如 {"sitekey": "your_site_key", "theme": "light"}。請參閱 grecaptcha.render 參數。 |
grecaptcha.reset( opt_widget_id
)。
|
重設 reCAPTCHA 小工具。 opt_widget_id 選用的小工具 ID;如未指定,系統會預設為建立的第一個小工具。 |
grecaptcha.getResponse( opt_widget_id
)。
|
取得 reCAPTCHA 小工具的回應。 opt_widget_id 選用的小工具 ID;如未指定,系統會預設為建立的第一個小工具。 |
示例
在 onload 回呼後明確算繪
<html>
<head>
<title>reCAPTCHA demo: Explicit render after an onload callback</title>
<script type="text/javascript">
var onloadCallback = function() {
grecaptcha.render('html_element', {
'sitekey' : 'your_site_key'
});
};
</script>
</head>
<body>
<form action="?" method="POST">
<div id="html_element"></div>
<br>
<input type="submit" value="Submit">
</form>
<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
async defer>
</script>
</body>
</html>
多個小工具的明確顯示
<html>
<head>
<title>reCAPTCHA demo: Explicit render for multiple widgets</title>
<script type="text/javascript">
var verifyCallback = function(response) {
alert(response);
};
var widgetId1;
var widgetId2;
var onloadCallback = function() {
// Renders the HTML element with id 'example1' as a reCAPTCHA widget.
// The id of the reCAPTCHA widget is assigned to 'widgetId1'.
widgetId1 = grecaptcha.render('example1', {
'sitekey' : 'your_site_key',
'theme' : 'light'
});
widgetId2 = grecaptcha.render(document.getElementById('example2'), {
'sitekey' : 'your_site_key'
});
grecaptcha.render('example3', {
'sitekey' : 'your_site_key',
'callback' : verifyCallback,
'theme' : 'dark'
});
};
</script>
</head>
<body>
<!-- The g-recaptcha-response string displays in an alert message upon submit. -->
<form action="javascript:alert(grecaptcha.getResponse(widgetId1));">
<div id="example1"></div>
<br>
<input type="submit" value="getResponse">
</form>
<br>
<!-- Resets reCAPTCHA widgetId2 upon submit. -->
<form action="javascript:grecaptcha.reset(widgetId2);">
<div id="example2"></div>
<br>
<input type="submit" value="reset">
</form>
<br>
<!-- POSTs back to the page's URL upon submit with a g-recaptcha-response POST parameter. -->
<form action="?" method="POST">
<div id="example3"></div>
<br>
<input type="submit" value="Submit">
</form>
<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
async defer>
</script>
</body>
</html>