@nativescript-community/ui-collectionview

允许您轻松地将集合视图（网格列表视图）添加到项目中。支持垂直和水平模式、模板等。


iOS 示例	Android 示例

安装

从项目的根目录运行以下命令

ns 插件添加 @nativescript-community/ui-collectionview

API

事件

属性	描述
itemLoading	在生成 CollectionView 中的项时触发。
itemTap	当用户在 CollectionView 中点击项时触发。
loadMoreItems	当生成的项达到 items 属性的末尾时触发。
scroll	在 collectionview 滚动时触发。
scrollEnd	在 collectionview 滚动结束时触发。
itemReorderStarting	当开始重新排序时触发。改变事件数据的 `returnValue` 允许您取消操作
itemReorderStarted	当开始重新排序时触发。
itemReordered	当重新排序完成时触发。
dataPopulated	当调用刷新时触发。

属性

属性	类型	描述
ios	UICollectionView	获取表示此组件用户界面的原生 iOS 视图。仅在 iOS 上有效。
android	android.support.v7.widget.RecyclerView	获取表示此组件用户界面的原生 android 小部件。仅在 Android OS 上有效。
items	`array` 或 `ItemsSource`	获取或设置 CollectionView 的项集合。items 属性可以设置为数组或定义长度和 getItem(index) 方法的对象。
itemTemplate	`string`	获取或设置 CollectionView 的项模板。
rowHeight	`PercentLength`	获取或设置 CollectionView 中每一行的长度。
colWidth	`PercentLength`	获取或设置 CollectionView 中每一列的宽度。
spanSize	`function`	当项加载时触发。返回元素应占用的列数，考虑设备垂直时的 `colWidth` 和水平时的 `rowHeight`。参数：(item, index: number)。
scrollOffset	`number`	获取当前滚动。
orientation	`vertical` 或 `horizontal`	设置 CollectionView 的方向。默认为 `vertical`。

方法

名称	返回	描述
refresh()	`void`	强制 CollectionView 重新加载所有项。
refreshVisibleItem()	`void`	强制 CollectionView 重新加载可见项。
scrollToIndex(index: number, animated: boolean = true)	`void`	将 CollectionView 滚动到给定索引的项。这可能是有动画的或无动画的。默认为有动画。
isItemAtIndexVisible(index: number)	`boolean`	返回一个布尔值，指示项是否可见。

用法

您需要在页面标签中添加 xmlns:gv="@nativescript-community/ui-collectionview"，然后只需在页面上使用 <gv:CollectionView/> 即可添加小部件。使用 <gv:Gridview.itemTemplate/> 指定每个单元格的模板。

简单示例

在您的 JS/TS 文件中创建一个简单的对象数组。

const items = [
    { index: 0, name: 'TURQUOISE', color: '#1abc9c' },
    { index: 1, name: 'EMERALD', color: '#2ecc71' },
    { index: 2, name: 'PETER RIVER', color: '#3498db' },
    { index: 3, name: 'AMETHYST', color: '#9b59b6' },
    { index: 4, name: 'WET ASPHALT', color: '#34495e' },
    { index: 5, name: 'GREEN SEA', color: '#16a085' },
    { index: 6, name: 'NEPHRITIS', color: '#27ae60' },
    { index: 7, name: 'BELIZE HOLE', color: '#2980b9' },
    { index: 8, name: 'WISTERIA', color: '#8e44ad' },
    { index: 9, name: 'MIDNIGHT BLUE', color: '#2c3e50' }
];

<!-- test-page.xml -->
<Page xmlns="http://schemas.nativescript.org/tns.xsd" xmlns:gv="@nativescript-community/ui-collectionview" loaded="pageLoaded">
    <GridLayout>
        <gv:CollectionView items="items" colWidth="50%" rowHeight="100">
            <gv:CollectionView.itemTemplate>
                <Label text="value" verticalAlignment="center"/>
            </gv:CollectionView.itemTemplate>
        </gv:CollectionView>
    </GridLayout>
</Page>

模板示例

您也可以以与在内置 ListView 控件中添加它们相同的方式拥有多个模板。

<gv:CollectionView id="gv" row="0" class="cssClass" items="items" 
                colWidth="colWidth" rowHeight="rowHeight" itemTemplateSelector="templateSelector"
                itemTap="gridViewItemTap" itemLoading="gridViewItemLoading" loadMoreItems="gridViewLoadMoreItems">
    <gv:CollectionView.itemTemplates>
        <template key="odd">
            <GridLayout backgroundColor="#33ffff" style="margin: 10 10 0 0">
                <Label text="value" verticalAlignment="center"/>
            </GridLayout>
        </template>

        <template key="even">
            <GridLayout backgroundColor="#33ffff" rows="auto, auto" style="margin: 10 10 0 0">
                <Label row="0" text="value" verticalAlignment="center"/>
                <Label row="1" text="value" verticalAlignment="center"/>
            </GridLayout>
        </template>
    </gv:CollectionView.itemTemplates>
</gv:CollectionView>

export function templateSelector(item: any, index: number, items: any) {
    return index % 2 === 0 ? "even" : "odd";
}

在 Angular 中使用

将模块导入到您的项目中。

import { CollectionViewModule } from '@nativescript-community/ui-collectionview/angular';

@NgModule({
    imports: [
        CollectionViewModule,
    ],
})

简单示例

在您的 Typescript 文件中创建一个简单的对象数组。

items = [
    { index: 0, name: 'TURQUOISE', color: '#1abc9c' },
    { index: 1, name: 'EMERALD', color: '#2ecc71' },
    { index: 2, name: 'PETER RIVER', color: '#3498db' },
    { index: 3, name: 'AMETHYST', color: '#9b59b6' },
    { index: 4, name: 'WET ASPHALT', color: '#34495e' },
    { index: 5, name: 'GREEN SEA', color: '#16a085' },
    { index: 6, name: 'NEPHRITIS', color: '#27ae60' },
    { index: 7, name: 'BELIZE HOLE', color: '#2980b9' },
    { index: 8, name: 'WISTERIA', color: '#8e44ad' },
    { index: 9, name: 'MIDNIGHT BLUE', color: '#2c3e50' }
];

将以下内容添加到您的组件 HTML 中。

<CollectionView [items]="items" colWidth="50%" rowHeight="100">
    <ng-template let-item="item">
        <Label [text]="item.name"></Label>
    </ng-template>
</CollectionView>

模板示例

如果您想使用多个项目模板，可以非常相似地按照内置 ListView 控件的方式操作。唯一的区别是，由于当前的限制，您需要使用来自 CollectionView 的 cvTemplateKey 指令，而不是 nsTemplateKey 指令。（在未来版本中，一旦框架允许，您将能够使用相同的指令为 CollectionView 使用）

<CollectionView row="1" [items]="items" colWidth="33%" rowHeight="100" [itemTemplateSelector]="templateSelector">
    <ng-template cvTemplateKey="Defender" let-item="item" let-odd="odd">
        <StackLayout [nsRouterLink]="['/item', item.id]" borderColor="blue" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
        <Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
        </StackLayout>
    </ng-template>

    <ng-template cvTemplateKey="Goalkeeper" let-item="item" let-odd="odd">
        <StackLayout [nsRouterLink]="['/item', item.id]" borderColor="black" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
        <Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
        </StackLayout>
    </ng-template>

    <ng-template cvTemplateKey="Midfielder" let-item="item" let-odd="odd">
        <StackLayout [nsRouterLink]="['/item', item.id]" borderColor="yellow" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
        <Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
        </StackLayout>
    </ng-template>

    <ng-template cvTemplateKey="Forward" let-item="item" let-odd="odd">
        <StackLayout [nsRouterLink]="['/item', item.id]" borderColor="red" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
        <Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
        </StackLayout>
    </ng-template>
</CollectionView>

对于更完整的示例，请查看 demo-ng 目录。

在 Vue 3 中使用

在您的 app.ts 中注册插件。

import CollectionView from '@nativescript-community/ui-collectionview/vue3';

const app = createApp(YourComponent);
app.use(CollectionView);
app.start();

简单示例

在您的组件中，添加以下内容以创建一个简单的对象数组。

<script setup lang="ts">
import { ObservableArray } from '@nativescript/core';
import { ref } from "nativescript-vue";

const itemList = ref(new ObservableArray([
    { name: 'TURQUOISE', color: '#1abc9c' },
    { name: 'EMERALD', color: '#2ecc71' },
    { name: 'PETER RIVER', color: '#3498db' },
    { name: 'AMETHYST', color: '#9b59b6' },
    { name: 'WET ASPHALT', color: '#34495e' }
]));
</script>

然后添加以下 XML 到您的组件中。

<CollectionView :items="itemList" colWidth="50%" rowHeight="100">
     <template #default="{ item }">
        <StackLayout :backgroundColor="item.color" >
            <Label :text="item.name"/>
        </StackLayout>
    </template>
</CollectionView>

对于更完整的示例，请查看 demo-vue3 和 demo-snippets/vue3 目录。

在 Vue 2 中使用

在您的 app.ts 中注册插件。

import CollectionView from '@nativescript-community/ui-collectionview/vue';
Vue.use(CollectionView);

简单示例

在您的组件中，添加以下内容以创建一个简单的对象数组。

export default {
    // ...
    data() {
        const items = [
            { index: 0, name: 'TURQUOISE', color: '#1abc9c' },
            { index: 1, name: 'EMERALD', color: '#2ecc71' },
            { index: 2, name: 'PETER RIVER', color: '#3498db' },
            { index: 3, name: 'AMETHYST', color: '#9b59b6' },
            { index: 4, name: 'WET ASPHALT', color: '#34495e' },
            { index: 5, name: 'GREEN SEA', color: '#16a085' },
            { index: 6, name: 'NEPHRITIS', color: '#27ae60' },
            { index: 7, name: 'BELIZE HOLE', color: '#2980b9' },
            { index: 8, name: 'WISTERIA', color: '#8e44ad' },
            { index: 9, name: 'MIDNIGHT BLUE', color: '#2c3e50' }
        ];
        return {
            itemList: items
        };
    },
    // ...
};

然后添加以下 XML 到您的组件中。

<CollectionView
    :items="itemList"
    colWidth="50%"
    rowHeight="100"
>
    <v-template>
        <Label :text="item.name"></Label>
    </v-template>
</CollectionView>

对于更完整的示例，请查看 demo-vue 目录。

在 Svelte 中使用

在您的 app.ts 中注册插件。

import CollectionViewElement from '@nativescript-community/ui-collectionview/svelte';
CollectionViewElement.register();

简单示例

在您组件中，添加以下内容以导入 Svelte Templates 并创建一个简单的对象数组。

import { Template } from 'svelte-native/components';

const items = [
    { index: 0, name: 'TURQUOISE', color: '#1abc9c' },
    { index: 1, name: 'EMERALD', color: '#2ecc71' },
    { index: 2, name: 'PETER RIVER', color: '#3498db' },
    { index: 3, name: 'AMETHYST', color: '#9b59b6' },
    { index: 4, name: 'WET ASPHALT', color: '#34495e' },
    { index: 5, name: 'GREEN SEA', color: '#16a085' },
    { index: 6, name: 'NEPHRITIS', color: '#27ae60' },
    { index: 7, name: 'BELIZE HOLE', color: '#2980b9' },
    { index: 8, name: 'WISTERIA', color: '#8e44ad' },
    { index: 9, name: 'MIDNIGHT BLUE', color: '#2c3e50' }
];

然后添加以下 XML 到您的组件。

<collectionView 
    {items} 
    colWidth="50%"
    rowHeight="100"
>
    <Template let:item>
        <label text="{item.name}" />
    </Template>
</collectionView>

对于更完整的示例，请查看 demo-svelte 目录。

在 React 中使用

在您的 app.ts 中注册插件。

import { registerCollectionView } from '@nativescript-community/ui-collectionview/react';
registerCollectionView();

简单示例

在您的组件中，添加以下代码以创建一个简单的列表。

import { CollectionView } from '@nativescript-community/ui-collectionview/react';

const items = [
    { index: 0, name: 'TURQUOISE', color: '#1abc9c' },
    { index: 1, name: 'EMERALD', color: '#2ecc71' },
    { index: 2, name: 'PETER RIVER', color: '#3498db' },
    { index: 3, name: 'AMETHYST', color: '#9b59b6' },
    { index: 4, name: 'WET ASPHALT', color: '#34495e' },
    { index: 5, name: 'GREEN SEA', color: '#16a085' },
    { index: 6, name: 'NEPHRITIS', color: '#27ae60' },
    { index: 7, name: 'BELIZE HOLE', color: '#2980b9' },
    { index: 8, name: 'WISTERIA', color: '#8e44ad' },
    { index: 9, name: 'MIDNIGHT BLUE', color: '#2c3e50' }
];

interface Item {
    index: number;
    name: string;
    color: string;
}

const cellFactory = (item: Item) => (
    <label text={item.name} />
);

export function First() {
    return (
        <CollectionView items={items} colWidth="50%" rowHeight="100" cellFactory={cellFactory} width="100%" height="100%" />
    );
}

对于更完整的示例，请查看 demo-react 目录。

演示

此存储库包括 Angular、Vue.js 和 Svelte 示例。要运行这些示例，请在您的 shell 中执行以下操作

$ git clone https://github.com/@nativescript-community/ui-collectionview
$ cd ui-collectionview
$ npm i
$ npm run setup
$ npm run build # && npm run build.angular
$ cd demo-ng # or demo-vue or demo-svelte
$ ns run ios|android

演示和开发

仓库设置

该存储库使用子模块。如果您没有使用 --recursive 进行克隆，则需要调用

git submodule update --init

用于安装和链接依赖项的包管理器必须是 pnpm 或 yarn。 npm 不可用。

为了开发和测试：如果您使用 yarn，则运行 yarn；如果您使用 pnpm，则运行 pnpm i

交互式菜单

要启动交互式菜单，请运行 npm start（或 yarn start 或 pnpm start）。这将列出所有常用的脚本。

构建

npm run build.all

警告：似乎 yarn build.all 不会始终工作（在 node_modules/.bin 中找不到二进制文件），这就是为什么文档明确使用 npm run

演示

npm run demo.[ng|react|svelte|vue].[ios|android]

npm run demo.svelte.ios # Example

贡献

更新仓库

您可以非常容易地更新存储库文件。

首先更新子模块

npm run update

然后提交更改，然后更新公共文件

npm run sync

然后您可以运行 yarn|pnpm，如果有任何更改，请提交更改的文件

更新 README

npm run readme

更新文档

npm run doc

发布

发布完全由 lerna 处理（您可以使用 -- --bump major 强制发布主要版本）。只需运行

npm run publish

修改子模块

该存储库使用 https:// 子模块，这意味着您无法直接推送到子模块。一个简单的解决方案是修改 ~/.gitconfig 并添加

[url "ssh://[email protected]/"]
	pushInsteadOf = https://github.com/

问题

如果您有任何问题/问题/评论，请随时创建问题或开始在 NativeScript Community Discord 中的对话。