https://github.com/lukailun/react-native-animated-header-flat-list
A React Native FlatList component with an animated collapsible header, featuring parallax effects, smooth title transitions, sticky component support, and customizable styles. Built with TypeScript and separate background/content layers in header.
https://github.com/lukailun/react-native-animated-header-flat-list
android animated flat-list ios package react-native web
Last synced: 3 months ago
JSON representation
A React Native FlatList component with an animated collapsible header, featuring parallax effects, smooth title transitions, sticky component support, and customizable styles. Built with TypeScript and separate background/content layers in header.
- Host: GitHub
- URL: https://github.com/lukailun/react-native-animated-header-flat-list
- Owner: lukailun
- License: mit
- Created: 2024-11-21T06:51:16.000Z (over 1 year ago)
- Default Branch: develop
- Last Pushed: 2026-02-11T10:04:34.000Z (4 months ago)
- Last Synced: 2026-02-11T18:04:37.703Z (4 months ago)
- Topics: android, animated, flat-list, ios, package, react-native, web
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-native-animated-header-flat-list
- Size: 125 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README-zh.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# react-native-animated-header-flat-list
[](https://www.npmjs.com/package/react-native-animated-header-flat-list)
[](https://www.npmjs.com/package/react-native-animated-header-flat-list)
[](https://www.npmjs.com/package/react-native-animated-header-flat-list)
一个带有动画折叠头部的 React Native FlatList 组件，具有视差效果、平滑标题过渡、粘性组件支持和可自定义样式。使用 TypeScript 构建，并在 Header 中实现了背景层和内容层的分离。
[English](./README.md) | 简体中文
## 预览
iOS
Android
Web
## 特性
- 带有视差效果的动画折叠头部
- 标题从 Header 到 NavigationBar 的平滑过渡
- 可选的粘性组件支持
- 完全可自定义的头部和标题样式
- Header 中背景层和内容层的分离
- TypeScript 支持
## 安装
```sh
npm install react-native-animated-header-flat-list
```
## 必需的依赖
本库需要安装以下依赖项：
```sh
npm install @react-navigation/native @react-navigation/native-stack @react-navigation/elements react-native-reanimated react-native-safe-area-context
```
请确保按照每个依赖的安装说明进行操作：
- [React Navigation](https://reactnavigation.org/docs/getting-started)
- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
- [React Native Safe Area Context](https://github.com/th3rdwave/react-native-safe-area-context#getting-started)
## 使用示例
```tsx
import { useCallback } from 'react';
import { Image, ImageBackground, StyleSheet, Text, View } from 'react-native';
import { AnimatedHeaderFlatList } from 'react-native-animated-header-flat-list';
export default function HomeScreen() {
const data = Array.from({ length: 50 }, (_, index) => ({
id: `item-${index}`,
title: `Item ${index + 1}`,
description: 'Lorem ipsum dolor sit amet',
}));
const title = 'Animated Title';
const renderItem = useCallback(
({
item,
}: {
item: { id: string; title: string; description: string };
}) => (
{item.title}
{item.description}
),
[]
);
return (
);
}
const HeaderBackground = () => {
const backgroundImageUrl =
'https://images.unsplash.com/photo-1579546929518-9e396f3cc809';
return (
);
};
const HeaderContent = () => {
const avatarUrl = 'https://api.dicebear.com/7.x/avataaars/png?seed=John';
return (
);
};
const StickyComponent = () => (
Sticky Item
);
const styles = StyleSheet.create({
headerBackground: {
backgroundColor: 'white',
height: 300,
width: '100%',
},
headerContent: {
height: 300,
width: '100%',
},
avatar: {
position: 'absolute',
top: 80,
left: 10,
backgroundColor: 'white',
width: 120,
height: 120,
borderRadius: 60,
borderWidth: 2,
borderColor: 'white',
},
headerTitle: {
position: 'absolute',
top: 200,
left: 10,
fontSize: 30,
fontWeight: 'bold',
color: 'white',
},
navigationTitle: {
fontSize: 18,
fontWeight: '600',
color: 'white',
},
stickyComponent: {
backgroundColor: 'white',
padding: 15,
borderWidth: 1,
borderColor: '#EEEEEE',
},
listItem: {
padding: 15,
borderBottomWidth: 1,
borderBottomColor: '#EEEEEE',
backgroundColor: 'white',
},
itemTitle: {
fontSize: 16,
fontWeight: '600',
},
itemDescription: {
fontSize: 14,
color: '#666666',
marginTop: 4,
},
});
```
### 属性
| 属性 | 类型 | 是否必需 | 描述 |
| --------------------------- | -------------------- | -------- | ---------------------------------------------------------------------------- |
| `title` | string | 是 | 在 Header 和 NavigationBar 之间动画过渡的标题文本 |
| `headerTitleStyle` | StyleProp | 否 | Header 标题的样式对象。支持所有 Text 样式属性。位置相对于 HeaderContent |
| `navigationTitleStyle` | StyleProp | 否 | NavigationBar 标题的样式对象。支持除位置相关属性外的所有 Text 样式属性 |
| `HeaderBackground` | React.ComponentType | 是 | 渲染为 Header 背景的组件 |
| `HeaderContent` | React.ComponentType | 否 | 渲染在 Header 背景之上的组件。其透明度会根据滚动位置自动动画 |
| `StickyComponent` | React.ComponentType | 否 | 可选的粘性组件，会固定在 NavigationBar 下方 |
| `parallax` | boolean | 否 | 启用/禁用头部背景的视差效果。默认为 true |
| `navigationBarColor` | ColorValue | 否 | NavigationBar 的颜色。其透明度会根据滚动位置自动动画 |
| `navigationTitleTranslateX` | number | 否 | 导航栏标题的水平偏移量。默认为 0 |
| `navigationTitleTranslateY` | number | 否 | 导航栏标题的垂直偏移量。默认为 0 |
| `...FlatListProps` | FlatListProps | - | 支持所有标准的 FlatList 属性 |
## 贡献
查看[贡献指南](CONTRIBUTING.md)了解如何为该仓库做出贡献以及开发工作流程。
## 许可证
MIT
---
使用 [create-react-native-library](https://github.com/callstack/react-native-builder-bob) 创建