react-native-gradient-mask

React Native 原生漸層遮罩元件

輕鬆建立精美的淡出效果、列表遮罩與流暢的漸層過渡動畫，具備原生效能與 Reanimated 動畫支援。

English •
日本語

---

展示

iOS	Android

特色

| 特色 | 說明 |
|------|------|
| 跨平台 | 支援 iOS、Android 和 Web |
| 原生效能 | iOS: CAGradientLayer • Android: Bitmap + PorterDuff • Web: CSS mask-image |
| Reanimated 支援 | 透過 AnimatedGradientMaskView 實現 60fps 流暢遮罩動畫 |
| 彈性設定 | 自訂顏色、位置、方向與遮罩強度 |
| TypeScript | 完整型別定義 |

安裝

``bash
npm install react-native-gradient-mask
`

`bash
yarn add react-native-gradient-mask
`

$3

| 相依套件 | 版本 |
|----------|------|
| Expo SDK | 50+ |
| React Native | 0.73+ |
| react-native-reanimated | >= 3.0.0 （選用） |

$3

---

快速開始

`tsx
import { processColor } from 'react-native';
import { GradientMaskView } from 'react-native-gradient-mask';

const colors = [
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,1)'),
];

export default function App() {
return (
colors={colors}
locations={[0, 1]}
direction="top"
style={{ flex: 1 }}
>


);
}
`

---

API 參考

$3

| 元件 | 說明 |
|------|------|
| GradientMaskView | 基礎漸層遮罩元件 |
| AnimatedGradientMaskView | 支援 Reanimated 動畫的漸層遮罩元件 |

$3

#### GradientMaskView

| 屬性 | 型別 | 必填 | 預設值 | 說明 |
|------|------|:----:|--------|------|
| colors | (number \| null)[] | 是 | - | 漸層顏色（需使用 processColor()） |
| locations | number[] | 是 | - | 顏色位置 (0-1) |
| direction | 'top' \| 'bottom' \| 'left' \| 'right' | 否 | 'top' | 漸層方向 |
| maskOpacity | number | 否 | 1 | 遮罩強度 (0-1) |
| style | ViewStyle | 否 | - | 容器樣式 |
| children | ReactNode | 否 | - | 要套用遮罩的內容 |

#### AnimatedGradientMaskView

與 GradientMaskView 相同，但 maskOpacity 接受 SharedValue 用於動畫控制。

$3

| 方向 | 效果 |
|------|------|
| top | 頂部透明 → 底部不透明 |
| bottom | 底部透明 → 頂部不透明 |
| left | 左側透明 → 右側不透明 |
| right | 右側透明 → 左側不透明 |

---

範例

$3

`tsx
import { processColor } from 'react-native';
import { GradientMaskView } from 'react-native-gradient-mask';

const colors = [
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,0.5)'),
processColor('rgba(0,0,0,1)'),
];

function FadeExample() {
return (
colors={colors}
locations={[0, 0.3, 1]}
direction="top"
style={{ flex: 1 }}
>

套用淡出效果的內容


);
}
`

$3

`tsx
import { processColor } from 'react-native';
import { AnimatedGradientMaskView } from 'react-native-gradient-mask';
import { useSharedValue, withTiming } from 'react-native-reanimated';

function AnimatedExample() {
const maskOpacity = useSharedValue(0);

const showMask = () => {
maskOpacity.value = withTiming(1, { duration: 600 });
};

const hideMask = () => {
maskOpacity.value = withTiming(0, { duration: 400 });
};

return (
colors={[
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,1)'),
]}
locations={[0, 1]}
maskOpacity={maskOpacity}
style={{ flex: 1 }}
>


);
}
`

$3

`tsx
import { useMemo, useCallback, useRef } from 'react';
import { processColor } from 'react-native';
import { FlashList } from '@shopify/flash-list';
import { AnimatedGradientMaskView } from 'react-native-gradient-mask';
import { useSharedValue, withTiming, cancelAnimation, Easing } from 'react-native-reanimated';

function ChatList({ messages }) {
const maskOpacity = useSharedValue(0);
const isAtBottomRef = useRef(false);

const maskColors = useMemo(() => [
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,0.2)'),
processColor('rgba(0,0,0,0.6)'),
processColor('rgba(0,0,0,0.9)'),
processColor('rgba(0,0,0,1)'),
], []);

const handleScroll = useCallback((e) => {
const { contentOffset, layoutMeasurement, contentSize } = e.nativeEvent;
const distanceFromBottom = contentSize.height - contentOffset.y - layoutMeasurement.height;
const isAtBottom = distanceFromBottom <= 30;

if (isAtBottom !== isAtBottomRef.current) {
isAtBottomRef.current = isAtBottom;
cancelAnimation(maskOpacity);
maskOpacity.value = withTiming(isAtBottom ? 1 : 0, {
duration: isAtBottom ? 600 : 400,
easing: isAtBottom ? Easing.in(Easing.quad) : Easing.out(Easing.quad),
});
}
}, []);

return (
colors={maskColors}
locations={[0, 0.42, 0.45, 0.48, 0.5, 1]}
direction="top"
maskOpacity={maskOpacity}
style={{ flex: 1 }}
>
data={messages}
renderItem={({ item }) => }
onScroll={handleScroll}
scrollEventThrottle={16}
/>

);
}
`

---

技巧與最佳實踐

$3

`tsx
// ✅ 正確
const colors = [
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,1)'),
];

// ❌ 錯誤 - 無法運作
const colors = [
'rgba(0,0,0,0)',
'rgba(0,0,0,1)',
];
`

$3

`tsx
const maskColors = useMemo(() => [
processColor('rgba(0,0,0,0)'),
processColor('rgba(0,0,0,1)'),
], []);
`

$3

`tsx
import { cancelAnimation } from 'react-native-reanimated';

// 在開始新動畫前取消前一個動畫
cancelAnimation(maskOpacity);
maskOpacity.value = withTiming(newValue, { duration: 300 });
`

---

平台支援

| 平台 | 實作方式 | 狀態 |
|------|----------|:----:|
| iOS | CAGradientLayer | ✅ |
| Android | Bitmap + LinearGradient + PorterDuff | ✅ |
| Web | CSS mask-image + linear-gradient` | ✅ |

---

為 Anini 打造

這個套件最初是為 Anini 開發的 — 一款提供流暢、原生品質使用者體驗的 AI 聊天夥伴應用程式。

---

贊助

本專案由 GAZAI 贊助 — 打造創新的 AI 驅動應用程式。

---

授權

MIT © DaYuan Lin (CS6)

---

_{為 React Native 社群用心打造 ❤️}