Django recaptcha表单字段/小部件应用。
项目描述
Django reCAPTCHA
Django reCAPTCHA表单字段/小部件集成应用。
[注意] django-recaptcha 支持 Google reCAPTCHA V2 - 复选框（默认）、Google reCAPTCHA V2 - 隐藏和 Google reCAPTCHA V3。请参阅小部件部分以获取更多信息。
Django reCAPTCHA 使用一个修改过的版本，即包含在包中的
client.py，它是 Python reCAPTCHA 客户端。
需求
测试与
- Python: 3.8, 3.9, 3.10, 3.11
- Django: 3.2, 4.1, 4.2
- 您可以在这里查看 Python-Django 支持矩阵。
此包仅支持现代的“常青”桌面和移动浏览器。对于 IE11 支持，请确保添加一个 Element.closest 的 polyfill。
安装
-
使用
pip install django-recaptcha安装。 -
将
'django_recaptcha'添加到您的INSTALLED_APPS设置中。
INSTALLED_APPS = [
...,
'django_recaptcha',
...
]
- 将步骤 1 中生成的 Google reCAPTCHA 密钥添加到您的 Django 生产设置中，使用
RECAPTCHA_PUBLIC_KEY和RECAPTCHA_PRIVATE_KEY。请注意，省略这些设置将默认使用一组测试密钥，有关更多信息，请参阅本地开发和功能测试。
例如
RECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123'
RECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456'
这些也可以通过将 public_key 或 private_key 参数传递给 ReCaptchaField 来按字段指定 - 详见以下字段使用说明。
- （可选）如果您需要代理，请添加一个
RECAPTCHA_PROXY设置（代理字典），例如
RECAPTCHA_PROXY = {'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}
- （可选）如果无法访问
www.google.com，则可以根据reCAPTCHA 常见问题解答将RECAPTCHA_DOMAIN设置更改为www.recaptcha.net。
RECAPTCHA_DOMAIN = 'www.recaptcha.net'
这将更改 Google JavaScript API 域以及客户端字段验证域。
用法
字段
将 reCAPTCHA 添加到表单的最快方法是使用包含的 ReCaptchaField 字段类。默认情况下将渲染 ReCaptchaV2Checkbox。例如
from django import forms
from django_recaptcha.fields import ReCaptchaField
class FormWithCaptcha(forms.Form):
captcha = ReCaptchaField()
请确保在您的表单中包含验证码字段。Django 中有许多将字段添加到表单的方法。我们建议您参考表单渲染选项和手动渲染字段部分，这些部分位于官方 Django 文档表单部分。
要允许在运行时指定密钥，您可以可选地将 private_key 或 public_key 参数传递给构造函数。例如
captcha = ReCaptchaField(
public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh',
private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs',
)
如果指定了这些参数，则将使用这些参数而不是您的 reCAPTCHA 项目设置。
小部件
与 ReCaptchaField 类一起可以使用三个小部件
ReCaptchaV2Checkbox用于 Google reCAPTCHA V2 - 复选框ReCaptchaV2Invisible用于 Google reCAPTCHA V2 - 隐藏ReCaptchaV3用于 Google reCAPTCHA V3
要使用除默认 Google reCAPTCHA V2 - 复选框小部件之外的其他小部件，只需替换 ReCaptchaField 小部件即可。例如
from django import forms
from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Invisible
class FormWithCaptcha(forms.Form):
captcha = ReCaptchaField(widget=ReCaptchaV2Invisible)
reCAPTCHA 小部件支持几个 数据属性，这些属性可以自定义小部件的行为，例如 data-theme、data-size 等。您可以通过传递包含选项的字典的 attrs 参数将选项传递给小部件。例如
captcha = fields.ReCaptchaField(
widget=widgets.ReCaptchaV2Checkbox(
attrs={
'data-theme': 'dark',
'data-size': 'compact',
}
)
)
# The ReCaptchaV2Invisible widget
# ignores the "data-size" attribute in favor of 'data-size="invisible"'
reCAPTCHA API支持多个参数。要自定义发送的参数，请向小部件传递一个包含选项字典的api_params参数。例如
captcha = fields.ReCaptchaField(
widget=widgets.ReCaptchaV2Checkbox(
api_params={'hl': 'cl', 'onload': 'onLoadFunc'}
)
)
# The dictionary is urlencoded and appended to the reCAPTCHA api url.
默认情况下，提供的小部件只支持每页一个表单，每个表单一个小部件。
可以通过“h1”参数设置语言，查看语言代码以获取语言代码选项。注意，为了正确显示错误，需要将翻译添加到此包中。目前该包支持以下语言代码的错误翻译：es、fr、nl、pl、pt_BR、ru、zh_CN、zh_TW
但是，小部件使用的JavaScript可以在模板中轻松覆盖。
模板位于
django_recaptcha/includes/js_v2_checkbox.html用于覆盖reCAPTCHA V2 - Checkbox模板django_recaptcha/includes/js_v2_invisible.html用于覆盖reCAPTCHA V2 - Invisible模板django_recaptcha/includes/js_v3.html用于覆盖reCAPTCHA V3模板
有关覆盖模板的更多信息，请参阅Django的模板覆盖
reCAPTCHA V3 分数
从版本3开始，reCAPTCHA还返回一个分数值。这可以用来确定页面交互是否为机器操作。有关详细信息，请参阅Google的文档。
要设置项目级别的分数限制，请使用RECAPTCHA_REQUIRED_SCORE设置。
例如
RECAPTCHA_REQUIRED_SCORE = 0.85
对于每个字段、运行时、规范属性，也可以将其传递给小部件
captcha = fields.ReCaptchaField(
widget=ReCaptchaV3(
attrs={
'required_score':0.85,
...
}
)
)
如果分数不满足要求，字段验证将像预期那样失败，并记录错误消息。
reCAPTCHA V3 行动
Google的reCAPTCHA V3 API支持传递一个操作值。操作允许您将reCAPTCHA验证与您网站上的特定表单相关联，以便进行统计分析，使您能够根据表单执行风险评估。这将允许您根据特定表单的滥用行为调整分数阈值，因为滥用行为可能因表单的性质而异。
要设置操作值，在实例化ReCaptcha小部件时传递一个action参数。请注意，仅使用reCAPTCHA文档中所述的字母数字字符、斜杠和下划线。
captcha = fields.ReCaptchaField(
widget=widgets.ReCaptchaV3(
action='signup'
)
)
设置操作完全是可选的。如果您不指定操作，则不会将任何操作传递给reCAPTCHA V3 API。
本地开发和功能测试
如果未设置RECAPTCHA_PUBLIC_KEY和RECAPTCHA_PRIVATE_KEY，django-recaptcha将使用Google的测试密钥。这些密钥不能在生产中使用，因为它们始终验证为真，并且reCAPTCHA将显示警告。Google的测试密钥仅适用于reCAPTCHA版本2。
要绕过防止测试密钥被无意中使用的安全检查，请将SILENCED_SYSTEM_CHECKS = [..., 'django_recaptcha.recaptcha_test_key_error', ...]添加到您的设置中，以下是一个示例
SILENCED_SYSTEM_CHECKS = ['django_recaptcha.recaptcha_test_key_error']
如果您想完全模拟调用Google服务器，请查看test_fields.py
from unittest.mock import patch
from django.test import TestCase
from django_recaptcha.client import RecaptchaResponse
class TestFields(TestCase):
@patch("django_recaptcha.fields.client.submit")
def test_client_success_response(self, mocked_submit):
mocked_submit.return_value = RecaptchaResponse(is_valid=True)
...
致谢
最初由Praekelt Consulting开发
灵感来源于Marco Fucci的博客文章Integrating reCAPTCHA with Django
client.py取自recaptcha-client，由Mike Crawford授权MIT/X11。
reCAPTCHA版权2012 Google。
作者
当前维护者
Praekelt Consulting
- Shaun Sephton
- Peter Pistorius
- Hedley Roos
- Altus Barry
- Cilliers Blignaut
bTaylor Design
其他
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。