This project provides an InfiniteGrid component for Cocos Creator >= 3.8.0, designed to efficiently handle large data sets with smooth scrolling and cell reuse. It is highly configurable and supports both vertical and horizontal scrolling.
[Vertiacl]
┌─────────────────────────────┬──────── ┌───┐
│ │ padding Top cell A │ A │
row 0 ◄─────┤ ┌───┐ ┌───┐ ┌────────┐ ├──────── └───┘
│ │ A │ │ A │ │ B │ │
│ └───┘ └───┘ │ │ │
│ └────────┘ ├──────── ┌────────┐
│ │ spacing Y cell B │ B │
row 1 ◄─────┤ ┌───┐ ┌───────────────┐ ├──────── │ │
│ │ A │ │C │ │ └────────┘
│ └───┘ │ │ │
│ └───────────────┘ │
│ │ ┌────────────────┐
row 2 ◄─────┤ ┌───┐ ┌───┐ ┌────────┐ │ cell C │ C │
│ │ A │ │ A │ │ B │ │ │ │
│ └───┘ └───┘ │ │ │ └────────────────┘
│ └────────┘ │
│ │
row 3 ◄─────┤ ┌───┐ ┌───────────────┐ │
│ │ A │ │C │ │
│ └───┘ │ │ │
│ └───────────────┘ ├────────
│ │ padding Bottom
├───┬───┬──┬───────────────┬──┼────────
│ │ │ │ │ │
│ │ │ │ │ │
padding Left spacing X padding Right
[Horizontal]
col 0 col 1 col 2 col 3
▲ ▲ ▲ ▲
│ │ │ │
│ │ │ │
────────┬──┴───────────┴───────────────────┴───────────────────┴────────────────────┐
padding Top │ │
────────┤ ┌───┐ ┌────────────────┐ ┌────────┐ ┌───┐ │
│ │ A │ │ C │ │ B │ │ A │ │
────────┤ └───┘ │ │ │ │ └───┘ │
spacing Y │ └────────────────┘ └────────┘ │
────────┤ ┌───┐ ┌────────┐ │
│ │ A │ ┌───┐ ┌────────────────┐ │ B │ │
│ └───┘ │ A │ │ C │ │ │ │
│ └───┘ │ │ └────────┘ │
│ ┌────────┐ └────────────────┘ │
│ │ B │ ┌───┐ ┌────────────────┐ │
│ │ │ │ A │ ┌───┐ │ C │ │
│ └────────┘ └───┘ │ A │ │ │ │
│ └───┘ └────────────────┘ ├──────
│ │ padding Bottom
├──┬────────┬──┬─────────────────────────────────────────────────────────┬──┼──────
│ │ │ │ │ │
│ │ │ │ │ │
padding Left spacing X padding Right
Align: [Vertical Row] [Horizontal Col]
┌─────────────────────┐
│ │
│ ┌───┐ │
┌───────────────────────────────────────┐ │ │ A │ │
│ │ │ └───┘ │
│ ┌───┐ ┌────────┐ ┌────────────────┐ │ │ │
│ │ A │ │ B │ │ C │ │ │ ┌────────┐ │
FLEX_START │ └───┘ │ │ │ │ │ │ │ B │ │
│ │ │ └────────────────┘ │ │ │ │ │
│ │ │ │ │ │ │ │
│ └────────┘ │ │ │ │ │
│ │ │ └────────┘ │
└───────────────────────────────────────┘ │ │
│ ┌────────────────┐ │
│ │ C │ │
│ │ │ │
│ └────────────────┘ │
│ │
└─────────────────────┘
┌─────────────────────┐
│ │
│ ┌───┐ │
┌───────────────────────────────────────┐ │ │ A │ │
│ │ │ └───┘ │
│ ┌────────┐ │ │ │
│ ┌───┐ │ B │ ┌────────────────┐ │ │ ┌────────┐ │
│ │ A │ │ │ │ C │ │ │ │ B │ │
CENTER │ └───┘ │ │ │ │ │ │ │ │ │
│ │ │ └────────────────┘ │ │ │ │ │
│ └────────┘ │ │ │ │ │
│ │ │ └────────┘ │
└───────────────────────────────────────┘ │ │
│ ┌────────────────┐ │
│ │ C │ │
│ │ │ │
│ └────────────────┘ │
│ │
└─────────────────────┘
┌─────────────────────┐
│ │
│ ┌───┐ │
┌───────────────────────────────────────┐ │ │ A │ │
│ │ │ └───┘ │
│ ┌────────┐ │ │ │
FLEX_END │ │ B │ │ │ ┌────────┐ │
│ │ │ ┌────────────────┐ │ │ │ B │ │
│ ┌───┐ │ │ │ C │ │ │ │ │ │
│ │ A │ │ │ │ │ │ │ │ │ │
│ └───┘ └────────┘ └────────────────┘ │ │ │ │ │
│ │ │ └────────┘ │
└───────────────────────────────────────┘ │ │
│ ┌────────────────┐ │
│ │ C │ │
│ │ │ │
│ └────────────────┘ │
│ │
└─────────────────────┘
-
Dynamic Loading: Dynamically loads and unloads cells based on user scrolling position.
-
Multiple Cell Types: Supports various cell types, each with different sizes and views.
-
Flexible Data Source: Provides a flexible data source through implementing the IFDataSource interface.
-
Flexible Layout: Automatically arranges cells based on their sizes.
-
(Vertical): One cell, when added, exceeds the width of the scroll area, it will be added to the current row if it's the first cell in the current row. Otherwise, it will be added to the next row.
-
(Horizontal): One cell, when added, exceeds the height of the scroll area, it will be added to the current column if it's the first cell in the current column. Otherwise, it will be added to the next column.
-
-
Dynamic Cell Sizes: Handles cells of varying sizes.
-
Clone the repository.
-
Copy the InfiniteGrid.ts and InfiniteCell.ts files to your Cocos Creator project's assets folder.
-
Ensure you have Cocos Creator >= 3.8.0 installed. Not sure work well with versions earlier than 3.8.0.
-
Prepare Cell Templates. Ensure the anchor point of the cell node is set to the center v2(0.5, 0.5).
-
Create a new Node in your Cocos Creator scene.
-
Add the InfiniteGrid component to the Node.
-
Configure the properties of the InfiniteGrid in the Inspector panel:
-
Direction: Set the scrolling direction (vertical or horizontal).
-
Align: Depending on your requirements, set the alignment for the cells. This could be FLEX_START, CENTER or FLEX_END, etc. Refer to CSS Flexbox (align-items)
-
Padding: Set the padding values for the grid.
-
Spacing: Set the spacing between cells.
-
Elastic: Enable or disable elastic scrolling.
-
Implement the IFDataSource interface to provide the data source. The IFDataSource interface defines the following methods:
interface IFDataSource {
GetCellNumber(): number {
// Return the total number of cells
}
GetCellIdentifer(dataIndex: number): string {
// Return the identifier for the cell type based on the data index
}
GetCellSize(dataIndex: number): Size {
// Return the size of the cell based on the data index
}
GetCellView(dataIndex: number, identifier?: string): InfiniteCell {
// Return an instance of the cell view based on the data index and identifier
}
GetCellData(dataIndex: number): any {
// Return the data for the cell based on the data index
}
}
Initialize the InfiniteGrid with your data source:
import { InfiniteGrid } from "./InfiniteGrid";
const infiniteGridNode = ...; // Get your InfiniteGrid node
const infiniteGrid = infiniteGridNode.getComponent(InfiniteGrid);
infiniteGrid.Init(...); // dataSource implements IFDataSource
You can control the InfiniteGrid using various methods:
- Reload the entire grid, optionally keeping the scroll position.
infiniteGrid.Reload(true);
- Refreshes the currently visible cells without reloading the entire list. Note that if the length of your list data changes, you should use Reload instead.
infiniteGrid.Refresh();
- Scroll to a specific cell: Scroll to a specific cell index.
infiniteGrid.ScrollToCell(10);
- Gets the maximum scroll offset.
infiniteGrid.GetMaxScrollOffset();
- Gets the current scroll offset.
infiniteGrid.GetScrollOffset();
- Stops the current scrolling action.
infiniteGrid.StopScrolling();
Set event handlers for scroll events:
infiniteGrid.OnScrollBegan(() => {
console.log("Scroll began");
});
infiniteGrid.OnScrollEnded(() => {
console.log("Scroll ended");
});
infiniteGrid.OnScrolling(() => {
console.log("Scrolling");
});
Contributions to InfiniteGrid
are welcome. If you have any suggestions or improvements, please submit a Pull Request or an Issue.
For a demonstration of how to use InfiniteGrid, visit the example repository: infinitegrid-ccc-proj
This project is licensed under the MIT License - see the LICENSE file for details.