FastComments Android Library

這是 FastComments 的官方 Android 函式庫。

FastComments 用於 Android 的留言元件

儲存庫

在 GitHub 上檢視

功能

🔄 支援即時更新的即時評論
📱 原生 Android UI 元件
🧵 具回覆功能的串狀討論
👤 安全的單一登入（SSO）驗證
👍 具有可自訂樣式的投票系統
🔔 使用者通知與在線狀態
🔍 評論審核功能
📱 社群動態整合
♾️ 無限滾動分頁
🎨 完整的主題化功能

需求

Android SDK 26+ (Android 8.0 Oreo 或更新版本)
Java 8+

安裝

將 FastComments SDK 新增到您應用程式的 build.gradle.kts 檔案：

dependencies {
    implementation("com.fastcomments:sdk:0.0.1")
}

請確保您的專案的 settings.gradle.kts 中包含 Repsy 儲存庫：

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://repo.repsy.io/mvn/winrid/fastcomments")
        }
        // other repositories...
    }
}

基本用法

1. 將 FastCommentsView 加入您的佈局

<com.fastcomments.sdk.FastCommentsView
    android:id="@+id/commentsView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

2. 初始化並設定 SDK

// 設定 SDK
val config = CommentWidgetConfig(
    "your-tenant-id", 
    "page-url-id", 
    "Page Title", 
    "yourdomain.com", 
    "Site Name"
)

// 其他設定選項
config.voteStyle = VoteStyle.UpDown // or VoteStyle.Heart
config.enableInfiniteScrolling = true
config.hasDarkBackground = true // 支援深色模式

// 初始化 SDK
val sdk = FastCommentsSDK(config)

// 在佈局中找到 comments view
val commentsView = findViewById<FastCommentsView>(R.id.commentsView)

// 為該 view 設定 SDK 實例
commentsView.setSDK(sdk)

// 載入留言
commentsView.load()

安全的單一登入（SSO）驗證

為您的使用者實作安全的身份驗證：

// 建立使用者資料（理想情況下在您的伺服器上）
val userData = SecureSSOUserData(
    "user-id",
    "user@example.com",
    "User Name",
    "https://path-to-avatar.jpg"
)

// 產生 SSO token（應在伺服器端完成！）
val sso = FastCommentsSSO.createSecure("YOUR_API_KEY", userData)
val token = sso.prepareToSend()

// 新增至 config
config.sso = token

Feed 整合

顯示帶有評論的社群媒體風格動態：

// Configure the SDK
CommentWidgetConfig config = new CommentWidgetConfig();
config.tenantId = "your-tenant-id";
config.urlId = "page-url-id";

// Initialize the Feed SDK
FastCommentsFeedSDK feedSDK = new FastCommentsFeedSDK(config);

// Set up the feed view
FastCommentsFeedView feedView = findViewById(R.id.feedView);
feedView.setSDK(feedSDK);

// Set interaction listener
feedView.setFeedViewInteractionListener(new FastCommentsFeedView.OnFeedViewInteractionListener() {
    @Override
    public void onFeedLoaded(List<FeedPost> posts) {
        // Feed loaded successfully
    }

    @Override
    public void onFeedError(String errorMessage) {
        // Handle errors
    }

    @Override
    public void onPostSelected(FeedPost post) {
        // User selected a post
    }

    @Override
    public void onCommentsRequested(FeedPost post) {
        // Show comments for the post
        CommentsDialog dialog = new CommentsDialog(context, post, feedSDK);
        dialog.show();
    }
});

// Load the feed
feedView.load();

即時聊天整合

在您的應用程式中新增即時聊天介面：

// 將 LiveChatView 新增到您的佈局 XML
// <com.fastcomments.sdk.LiveChatView
//     android:id="@+id/liveChatView"
//     android:layout_width="match_parent"
//     android:layout_height="match_parent" />

// 為 SDK 建立一個設定
val config = CommentWidgetConfig().apply {
    tenantId = "your-tenant-id"
    urlId = "chat-room-identifier" 
    pageTitle = "Chat Room Name"
}
LiveChatView.setupLiveChatConfig(config)

// 可選：加入使用者驗證
val userData = SimpleSSOUserData(
    "User Name",
    "user@example.com",
    "https://path-to-avatar.jpg"
)
val sso = FastCommentsSSO(userData)
config.sso = sso.prepareToSend()

// 初始化 SDK
val sdk = FastCommentsSDK().configure(config)

// 設定 LiveChatView 視圖
val liveChatView = findViewById<LiveChatView>(R.id.liveChatView)
liveChatView.setSDK(sdk)
liveChatView.load()

// 不要忘記處理生命週期
override fun onResume() {
    super.onResume()
    sdk.refreshLiveEvents()
}

override fun onDestroy() {
    super.onDestroy()
    sdk.cleanup()
}

範例專案

查看這些示範實作：

設定選項

SDK 提供許多透過 CommentWidgetConfig 類別的設定選項：

選項	說明
`tenantId`	您的 FastComments 帳戶 ID
`urlId`	表示當前頁面的 ID
`sso`	用於驗證的 SSO 令牌
`allowAnon`	允許匿名評論
`voteStyle`	UpDown 或 Heart 投票樣式
`hideAvatars`	隱藏使用者頭像
`hasDarkBackground`	表示深色模式
`customCSS`	自訂 CSS 樣式
`enableInfiniteScrolling`	啟用無限捲動分頁
`readonly`	停用發表評論但顯示評論
`disableVoting`	停用投票功能
`disableLiveCommenting`	停用即時更新
---

完整的主題自訂

FastComments SDK 中的所有按鈕與 UI 元素都可套用主題。使用 FastCommentsTheme.Builder 可完整控管您應用程式的品牌樣式。

程式化主題設定（建議）

val theme = FastCommentsTheme.Builder()
    // 操作按鈕：發送、投票、選單、按讚/分享按鈕
    .setActionButtonColor(Color.parseColor("#FF1976D2"))

    // 回覆按鈕：留言回覆按鈕  
    .setReplyButtonColor(Color.parseColor("#FF4CAF50"))

    // 切換按鈕：顯示/隱藏回覆按鈕
    .setToggleRepliesButtonColor(Color.parseColor("#FFFF5722"))

    // 載入更多按鈕：分頁按鈕
    .setLoadMoreButtonTextColor(Color.parseColor("#FF9C27B0"))

    .setPrimaryColor(Color.parseColor("#FF6200EE"))
    .setLinkColor(Color.parseColor("#FF1976D2"))
    .setDialogHeaderBackgroundColor(Color.parseColor("#FF333333"))
    .build()

// 套用主題
sdk.setTheme(theme)

快速顏色覆寫

在你的 colors.xml 中覆寫顏色資源即可達成簡易品牌設定：

<!-- 在你的應用程式的 res/values/colors.xml 中 -->
<resources>
    <!-- 變更所有主要 UI 元素 -->
    <color name="primary">#FF1976D2</color>

    <!-- 或自訂特定按鈕類型 -->
    <color name="fastcomments_action_button_color">#FF1976D2</color>
    <color name="fastcomments_reply_button_color">#FF4CAF50</color>
    <color name="fastcomments_toggle_replies_button_color">#FFFF5722</color>
    <color name="fastcomments_load_more_button_text_color">#FF9C27B0</color>
</resources>

主題化按鈕涵蓋範圍

SDK 中的每一個按鈕都支援主題化：

發送按鈕、投票按鈕、選單按鈕、回覆按鈕
顯示/隱藏回覆按鈕、載入更多按鈕
動態牆的操作按鈕（按讚、留言、分享）
對話框按鈕（提交、取消、儲存）
動態貼文中的動態任務按鈕

如需更詳細的主題文件，請參見 THEMING.md.

記憶體管理

防止記憶體洩漏

為了在 Activity 或 Fragment 中使用 FastComments 視圖時防止記憶體洩漏，當不再需要該視圖時，請務必呼叫 cleanup()：

In Activities:

@Override
protected void onDestroy() {
    super.onDestroy();
    // 清理 FastComments 視圖以防止記憶體洩漏
    if (feedView != null) {
        feedView.cleanup();
    }
    if (commentsView != null) {
        commentsView.cleanup();
    }
}

In Fragments:

@Override
public void onDestroyView() {
    super.onDestroyView();
    // 當 Fragment 視圖被銷毀時，清理 FastComments 視圖
    if (feedView != null) {
        feedView.cleanup();
        feedView = null;
    }
}

@Override
public void onDestroy() {
    super.onDestroy();
    // Fragment 被銷毀時的額外清理
    if (feedSDK != null) {
        feedSDK.cleanup();
        feedSDK = null;
    }
}

When Switching Fragments:

// 在替換或移除包含 FastComments 視圖的 Fragment 之前
Fragment currentFragment = getSupportFragmentManager().findFragmentById(R.id.container);
if (currentFragment instanceof YourFragmentWithFeedView) {
    ((YourFragmentWithFeedView) currentFragment).cleanupFeedView();
}

// 然後繼續執行 Fragment 交易
getSupportFragmentManager().beginTransaction()
    .replace(R.id.container, newFragment)
    .commit();

重要：請務必在以下情況呼叫 cleanup() 方法以防止記憶體洩漏，特別是在：

Activities 被銷毀時
Fragment 視圖被銷毀時
切換 Fragment 時
從包含 FastComments 元件的畫面導覽離開時

需要幫助？

如果您在使用 Android 函式庫時遇到任何問題或有任何疑問，請：

貢獻

歡迎投稿！請造訪 GitHub 儲存庫以取得貢獻指南。

語言 🇹🇼 繁體中文

文件

快速開始

用法

驗證

設定