跳至主要内容

InfiniteCell

重要 注意 提醒

Coding Style wiki​

InfiniteCell 為 Cell 的基底類 (MonoBehaviour)，掛載於 Cell Prefab 的根節點；Cell 由物件池循環利用，透過覆寫生命週期方法實作顯示邏輯，渲染所需的數據由 InfiniteCellData 承載。

命名空間OxGKit.InfiniteScrollView
類型public class InfiniteCell : MonoBehaviour
原始碼InfiniteCell.cs
using OxGKit.InfiniteScrollView;

提醒 透過 Right-Click Create/OxGKit/Infinite ScrollView/Template Infinite Cell.cs (Script) 與 Template Infinite Cell (RectTransform Prefab) 可快速建立 Cell 的腳本與 Prefab 模板。

快速上手​

using Cysharp.Threading.Tasks;
using OxGKit.InfiniteScrollView;
using UnityEngine.UI;

public class ItemCell : InfiniteCell
{
    public Text titleTxt;
    public Button button;

    public override async UniTask OnCreate(object args)
    {
        // 建立時初始一次 (args 由 InitializePool(args) 轉傳)
        this.button.onClick.AddListener(this.OnClick);
    }

    public override void OnRefresh()
    {
        // Cell 為物件池循環利用，顯示必須完全由 cellData 驅動
        string text = (string)this.cellData.data;
        this.titleTxt.text = $"[{this.cellData.index}] {text}";
    }

    public override void OnRecycle()
    {
        // 回收回物件池時的清理
    }

    public override void OnSnap()
    {
        // 成為 Snap 目標時的表現 (如高亮)
    }

    public override void OnClick()
    {
        // 觸發列表的 onCellSelected 事件
        base.OnClick();
    }
}

通用規則​

生命週期​

方法觸發時機
OnCreateInitializePool 實例化 Cell 時 (一次性，await)。
OnRefreshcellData 被指派時 (Cell 進入可視範圍配置顯示、數據刷新)。
OnRecycleCell 被回收回物件池時 (GameObject 已停用)。
OnSnapSnap 完成且該 Cell 為目標時。
OnClick點擊時 (需自行將 Button 事件綁定至此方法)。

重要 Cell 為物件池循環利用 — 同一個 Cell 實例會輪流顯示不同筆數據，OnRefresh 必須完全由 cellData 驅動重繪，勿將單筆項目的狀態存於 Cell 身上 (應存於數據物件)。

注意 Insert / Remove 會位移數據索引，Cell 內請即時讀取 this.cellData.index，勿快取索引值。

成員​

成員說明
public RectTransform rectTransformCell 的 RectTransform (自動快取)。
public InfiniteCellData cellData當前綁定的數據；被指派 (set) 時會自動觸發 OnRefresh。

方法​

方法總覽​

方法說明
OnCreate建立時初始 (一次性)。
OnRefresh依數據重繪顯示。
OnRecycle回收時清理。
OnSnap成為 Snap 目標時。
OnClick點擊事件 (觸發選中)。
InvokeSelected(protected) 主動觸發選中事件。

OnCreate​

public virtual async UniTask OnCreate(object args)

於 InitializePool 實例化 Cell 時被 await 呼叫一次；args 為 InitializePool(args) 轉傳的自定義參數，適合進行組件初始等一次性設置。

OnRefresh​

public virtual void OnRefresh()

cellData 被指派時自動呼叫 — 於 Cell 被配置顯示 (進入可視範圍) 時觸發，請在此依 cellData 重繪顯示內容。

OnRecycle​

public virtual void OnRecycle()

Cell 被回收回物件池時呼叫 (此時 GameObject 已被停用)，可在此進行清理 (如停止動畫、釋放暫存)。

OnSnap​

public virtual void OnSnap()

Snap 完成且該 Cell 為目標索引時呼叫 (適用頁籤切換、選中表現等)。

OnClick​

public virtual void OnClick()

點擊事件入口 — 預設實作會呼叫 InvokeSelected 觸發列表的 onCellSelected 事件；請自行將 Cell 上的 Button 事件綁定至此方法 (覆寫時記得呼叫 base.OnClick())。

InvokeSelected​

protected void InvokeSelected()

主動觸發選中事件 (通知列表的 onCellSelected)；自定義點擊流程 (不經由 OnClick) 時可直接呼叫。

InfiniteCellData​

Cell 的數據載體，決定 Cell 的尺寸與渲染數據；與 Cell (顯示) 分離，由列表持有並於配置顯示時綁定給 Cell。

類型public class InfiniteCellData : IDisposable
原始碼InfiniteCellData.cs
成員說明
public int index { get; internal set; }數據索引 (由列表自動維護，Insert / Remove 後自動更新)。
public Vector2 cellSizeCell 尺寸 (x = 寬、y = 高)：垂直列表取 y、水平列表取 x、Grid 兩者皆用。
public object data渲染 Cell 所需的自定義數據。

建構子

public InfiniteCellData()
public InfiniteCellData(Vector2 cellSize)
public InfiniteCellData(Vector2 cellSize, object data)

方法

public void Dispose()

釋放數據引用 (data = null)；由列表的 Remove / Clear 自動呼叫。

動態尺寸範例 (聊天室)

// 先以量測用 Text 計算文字高度，再依內容建立動態高度的數據
this.heightInstrument.text = message;
float height = this.heightInstrument.preferredHeight;
this.chatScrollView.Add(new InfiniteCellData(new Vector2(0f, height), new ChatData(user, message)));
this.chatScrollView.Refresh();
this.chatScrollView.SnapLast(0.1f);

注意 cellSize 需於加入列表前決定；之後變更尺寸需更新該筆數據的 cellSize 並執行完整 Refresh。