在您的 Django 應用程式中添加評論

• Python 3.10+
• Django 4.2, 5.0, 5.1, or 5.2
• 一個 FastComments 租戶 ID（使用 demo 以在沒有帳戶的情況下試用）
• 僅在 Secure SSO 時需要 API secret

從發行標籤安裝（此專案透過 git 標籤分發，而非 PyPI）：

pip install "git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

若要進行伺服器端 REST 存取（admin() / public_api() 輔助函式），加入 api 額外套件，這會拉入 SDK 生成的客戶端：

pip install "fastcomments-django[api] @ git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

將此應用程式加入 INSTALLED_APPS：

INSTALLED_APPS = [
    # ...
    "fastcomments_django",
]

在 settings.py 中配置您的租戶：

import os

FASTCOMMENTS = {
    "TENANT_ID": os.environ.get("FASTCOMMENTS_TENANT_ID", "demo"),
}

把小部件放入任意模板中：

{% load fastcomments %}

{% fastcomments url_id="my-page" %}

若要自動將已登入的使用者傳遞給小工具，標籤會從請求中讀取當前使用者。請確保您的專案具備以下兩者（在標準的 Django 專案中預設已啟用）：

• django.template.context_processors.request in TEMPLATES["OPTIONS"]["context_processors"]
• django.contrib.auth.middleware.AuthenticationMiddleware in MIDDLEWARE

如果模板上下文中沒有請求，則小工具會以匿名訪客的身份呈現。您也可以隨時明確傳遞使用者：{% fastcomments user=some_user %}。

每個小工具都有自己的標籤。所有標籤皆接受 **extra 關鍵字參數，這些參數會以原樣（使用 camelCase 鍵）合併至小工具設定中，針對以下未列出的情況。

具名參數對應小工具的 camelCase 設定鍵：

範例：

{% load fastcomments %}

{% fastcomments url_id="my-page" locale="en_us" default_sort_direction="MR" %}

{% fastcomments_live_chat url_id="room-1" %}

評論： {% fastcomments_comment_count url_id="my-page" number_only=True %}

{# 協作聊天附加於頁面上已存在的元素 #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# 批量計數：放置標記，之後一次批量載入器會填入所有數值 #}
{% for post in posts %}
    <a href="\{{ post.url }}">\{{ post.title }}</a>
    {% fastcomments_count_marker url_id=post.url_id %}
{% endfor %}
{% fastcomments_comment_count_bulk %}

Enable SSO and choose a mode in settings.py. Secure SSO signs the user server-side with HMAC-SHA256 using your API secret and is recommended.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # 您的 API 密鑰；簽署 Secure SSO
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # 將 FastComments 欄位對映到您的使用者模型。值可以是屬性
        # 名稱、點記法路徑 ("profile.avatar_url")、callable(user) 或 None.
        "USER_MAP": {
            "id": "id",
            "email": "email",
            "username": "username",
            "avatar": None,
            "display_name": None,
            "website_url": None,
        },
        "IS_ADMIN": lambda user: user.is_staff,      # callable(user) -> bool，或點記法路徑
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list，或點記法路徑
    },
}

請謹慎選擇 SSO id。 FastComments 的 id 是使用者評論歷史的永久標識。預設的 USER_MAP 會將它映射到您的 Django 主鍵，以提供零設定的便利，但順序整數主鍵是可枚舉的，且日後很難更改（更改使用者的 id 會將其歷史分割到新帳號）。對於任何非示範用途，請將 id 映射為事先選定的穩定且不透明的值（如 UUID 或專用的公開 id），且絕不要在其中放入私人資料。範例應用程式因此使用基於使用者名稱的 id。

SSO is injected automatically into {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %}, and {% fastcomments_user_activity %} for the current user.

Login/logout URLs shown to signed-out visitors default to reverse("login") / reverse("logout"); override them with SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

自訂映射

Two higher-precedence options beat USER_MAP:

• 您使用者模型上的方法 (the Pythonic analog of an interface):

  class User(AbstractUser):
      def to_fastcomments_user_data(self):
          return {"id": self.pk, "email": self.email, "username": self.get_username()}

• 全域映射器, a dotted path to callable(user) -> dict:

  FASTCOMMENTS = {"SSO": {"USER_MAPPER": "myapp.sso.map_user"}}

Precedence is USER_MAPPER > to_fastcomments_user_data() > USER_MAP.

使用已安裝的 [api] 擴充功能，可透過 SDK 呼叫 FastComments REST API，已預先配置您的 API 金鑰與區域：

from fastcomments_django import admin, public_api, get_manager

admin().get_comments("YOUR_TENANT_ID", ...)     # 已驗證 (DefaultApi)
public_api().get_comments_public(...)            # 公開 (PublicApi)

# 為 API 呼叫或客戶端交接產生 SSO 令牌：
token = get_manager().sso().token_for(request.user)

設定 REGION 以將小工具和 API 路由至歐盟：

FASTCOMMENTS = {"TENANT_ID": "...", "REGION": "eu"}

覆蓋 fastcomments/widget.html，方法是將您自己的副本放置在模板搜尋路徑的較前面位置
模板搜尋路徑（例如專案的 templates/fastcomments/widget.html）。這是
Django 中對應 Laravel 的 vendor:publish --tag=fastcomments-views。

一個可執行的示範位於 example/：一個左側導覽列 + 主舞台的 應用程式，為每個 widget 提供一個頁面，並有 列出預先種子化示範使用者的登入頁面。
使用其中任何一個帳號登入，評論與即時聊天 widget 會透過 Secure SSO 驗證該身分。從該目錄：

python manage.py migrate
# Use your own tenant to see Secure SSO in action (an API secret enables it):
FASTCOMMENTS_TENANT_ID=... FASTCOMMENTS_API_KEY=... python manage.py runserver

如果未提供 API 金鑰，則會回退到公共的 demo 租戶（匿名）。
example/browser_smoke.py 是一個 Playwright e2e 測試，會在真實瀏覽器中載入頁面，並以 Secure-SSO 使用者身分發表評論。