React Native 圖表接入指南
概述
本文檔詳細介紹了在React Native項目中接入ECharts圖表的完整步驟,包括依賴安裝、組件配置、數據獲取、圖表渲染等各個環節。
目錄
- 1. 環境準備
- 2. 依賴安裝
- 3. 圖表組件創建
- 4. 數據獲取Hook
- 5. 圖表配置
- 6. 組件集成
- 7. 國際化支持
- 8. 最佳實踐
- 9. 常見問題
1. 環境準備
1.1 項目要求
- React Native 0.76.9+
- Expo SDK 52+
- TypeScript 5.3.3+
- Node.js 18.18.0+
1.2 開發環境
確保已安裝以下工具:
- Node.js 和 npm/yarn
- React Native CLI 或 Expo CLI
- iOS Simulator (macOS) 或 Android Emulator
2. 依賴安裝
2.1 核心依賴
# 安裝圖表核心庫
npm install echarts@^5.6.0# 安裝React Native圖表渲染器
npm install @wuba/react-native-echarts@^2.0.3# 安裝SVG支持(圖表渲染需要)
npm install react-native-svg@^15.8.0# 安裝日期處理庫(用于圖表時間軸格式化)
npm install date-fns@^4.1.0
這個過程是這樣的:
- ECharts 核心庫 ( echarts ) :負責所有的數據處理、圖表邏輯計算和配置項解析。它會生成一個虛擬的、與平臺無關的渲染指令。
- SVG 渲染器 ( SVGRenderer ) :這個渲染器來自于 @wuba/react-native-echarts 包,它的作用是接收 ECharts 核心庫生成的渲染指令,并將其轉換成 SVG 元素。
- React Native SVG ( react-native-svg ) :這個庫提供了在 React Native 中渲染 SVG 的能力。它會將 SVGRenderer 生成的 SVG 元素真正在原生視圖上繪制出來。
所以,整個流程可以看作是 ECharts (邏輯) -> SVGRenderer (轉換為 SVG) -> react-native-svg (在屏幕上繪制) 。這種方式使得強大的 ECharts 庫能夠跨平臺運行在沒有原生 Canvas 和 DOM 環境的 React Native 中
2.2 可選依賴
# 如果需要健康數據(如心率圖表示例)
npm install react-native-health@^1.19.0# 如果需要更多圖表類型
npm install @types/echarts
2.3 依賴說明
依賴包 | 版本 | 作用 |
---|---|---|
echarts | ^5.6.0 | 圖表核心庫,提供豐富的圖表類型 |
@wuba/react-native-echarts | ^2.0.3 | React Native適配的ECharts渲染器 |
react-native-svg | ^15.8.0 | SVG渲染支持,圖表顯示必需 |
date-fns | ^4.1.0 | 日期處理工具,用于時間軸格式化 |
3. 圖表組件創建
3.1 基礎組件結構
創建文件:app/components/HeartRateChart.tsx
import { useRef, useEffect, useMemo } from "react"
import { StyleProp, View, ViewStyle } from "react-native"
import { echarts } from "../utils/echarts" // 導入集中的 echarts 實例
import SvgChart from "@wuba/react-native-echarts/svgChart"
import { useHealthData } from "../hooks/useHealthData"
import { HealthValue } from "react-native-health"
import { format } from "date-fns"
import { ECharts } from "echarts/core"// 不再需要在此處注冊組件,已在 app/utils/echarts.ts 中集中處理interface HeartRateChartProps {style?: StyleProp<ViewStyle>
}const CHART_HEIGHT = 300
const CHART_WIDTH = 350export function HeartRateChart(props: HeartRateChartProps) {const { style } = propsconst chartRef = useRef<any>(null)const { heartRateSamples, fetchHeartRateSamples, permissionsGranted } = useHealthData({requestPermissions: true,autoFetch: false,})// 數據獲取useEffect(() => {if (permissionsGranted) {const endDate = new Date()const startDate = new Date()startDate.setDate(endDate.getDate() - 1)fetchHeartRateSamples(startDate, endDate)}}, [permissionsGranted, fetchHeartRateSamples])// 圖表配置const chartOption = useMemo(() => {if (!heartRateSamples || heartRateSamples.length === 0) {return {}}const data = heartRateSamples.map((sample: HealthValue) => [new Date(sample.startDate),sample.value,])return {tooltip: {trigger: "axis",formatter: (params: any) => {const param = params[0]const date = new Date(param.axisValue)const value = param.data[1]return `${format(date, "MM-dd HH:mm")}<br/>心率: ${value}`},},xAxis: {type: "time",axisLabel: {formatter: (value: number) => {return format(new Date(value), "HH:mm")},},},yAxis: {type: "value",name: "心率 (bpm)",min: (value: { min: number }) => Math.floor(value.min / 10) * 10,},series: [{data,type: "line",smooth: true,showSymbol: false,lineStyle: {width: 2,},},],grid: {left: "12%",right: "5%",bottom: "10%",top: "10%",},}}, [heartRateSamples])// 圖表初始化和更新useEffect(() => {let chartInstance: ECharts | undefinedif (chartRef.current && Object.keys(chartOption).length > 0) {chartInstance = echarts.init(chartRef.current, "light", {renderer: "svg",width: CHART_WIDTH,height: CHART_HEIGHT,})chartInstance.setOption(chartOption)}return () => {chartInstance?.dispose()}}, [chartOption])return (<View style={style}><SvgChart ref={chartRef} /></View>)
}
3.2 組件導出
在 app/components/index.ts
中添加導出:
export * from "./HeartRateChart"
4. 數據獲取Hook
4.1 創建數據Hook
創建文件:app/hooks/useHealthData.ts
import { useState, useCallback, useEffect } from "react"
import AppleHealthKit, { HealthKitPermissions, HealthValue } from "react-native-health"interface HealthDataState {stepCount: number | nullheartRateSamples: HealthValue[]isLoading: booleanerror: string | nullpermissionsGranted: boolean
}interface UseHealthDataOptions {requestPermissions?: booleanautoFetch?: boolean
}export const useHealthData = (options: UseHealthDataOptions = {}) => {const { requestPermissions = true, autoFetch = true } = optionsconst [healthData, setHealthData] = useState<HealthDataState>({stepCount: null,heartRateSamples: [],isLoading: false,error: null,permissionsGranted: false,})// 初始化 HealthKit 并請求權限const initializeHealthKit = useCallback(async () => {if (!requestPermissions) returnsetHealthData((prev) => ({ ...prev, isLoading: true, error: null }))const permissions = {permissions: {read: [AppleHealthKit.Constants.Permissions.Steps,AppleHealthKit.Constants.Permissions.HeartRate,AppleHealthKit.Constants.Permissions.StepCount,],write: [],},} as HealthKitPermissionsreturn new Promise<void>((resolve, reject) => {AppleHealthKit.initHealthKit(permissions, (error: string) => {if (error) {const errorMessage = `無法授予 HealthKit 權限: ${error}`console.error("HealthKit 權限請求失敗:", errorMessage)setHealthData((prev) => ({...prev,isLoading: false,error: errorMessage,permissionsGranted: false,}))reject(new Error(errorMessage))return}setHealthData((prev) => ({...prev,isLoading: false,permissionsGranted: true,}))resolve()})})}, [requestPermissions])// 獲取心率樣本const fetchHeartRateSamples = useCallback(async (startDate?: Date, endDate?: Date) => {if (!healthData.permissionsGranted) {const errorMsg = "HealthKit 權限未授予,無法獲取心率數據"console.error(errorMsg)throw new Error(errorMsg)}setHealthData((prev) => ({ ...prev, isLoading: true, error: null }))const heartRateOptions = {startDate: (startDate || new Date(new Date().getTime() - 24 * 60 * 60 * 1000)).toISOString(),endDate: (endDate || new Date()).toISOString(),}return new Promise<HealthValue[]>((resolve, reject) => {AppleHealthKit.getHeartRateSamples(heartRateOptions,(err: string, results: HealthValue[]) => {if (err) {const errorMessage = `獲取心率樣本時出錯: ${err}`console.error(errorMessage)setHealthData((prev) => ({...prev,isLoading: false,error: errorMessage,}))reject(new Error(errorMessage))return}setHealthData((prev) => ({...prev,heartRateSamples: results,isLoading: false,}))resolve(results)},)})},[healthData.permissionsGranted],)// 獲取所有健康數據const fetchAllHealthData = useCallback(async () => {if (!healthData.permissionsGranted) {return}try {await fetchHeartRateSamples()} catch (error) {console.error("獲取健康數據時出錯:", error)}}, [fetchHeartRateSamples, healthData.permissionsGranted])// 清除錯誤const clearError = useCallback(() => {setHealthData((prev) => ({ ...prev, error: null }))}, [])// 初始化useEffect(() => {if (requestPermissions) {initializeHealthKit().then(() => {setTimeout(() => {if (autoFetch) {fetchAllHealthData()}}, 100)}).catch((error) => {console.error("初始化 HealthKit 失敗:", error)})}}, [requestPermissions, autoFetch, initializeHealthKit, fetchAllHealthData])return {// 狀態...healthData,// 方法initializeHealthKit,fetchHeartRateSamples,fetchAllHealthData,clearError,}
}
4.2 Hook導出
在 app/hooks/index.ts
中添加導出:
export * from "./useHealthData"
5. 圖表配置
5.1 基礎配置
const baseChartOption = {// 提示框配置tooltip: {trigger: "axis",backgroundColor: "rgba(0, 0, 0, 0.8)",borderColor: "rgba(255, 255, 255, 0.2)",textStyle: {color: "#fff",},},// 網格配置grid: {left: "12%",right: "5%",bottom: "10%",top: "10%",containLabel: true,},// 動畫配置animation: true,animationDuration: 1000,animationEasing: "cubicOut",
}
5.2 時間軸配置
const timeAxisConfig = {xAxis: {type: "time",axisLabel: {formatter: (value: number) => format(new Date(value), "HH:mm"),color: "#666",fontSize: 12,},axisLine: {lineStyle: {color: "#ddd",},},splitLine: {show: true,lineStyle: {color: "#f0f0f0",type: "dashed",},},},
}
5.3 數值軸配置
const valueAxisConfig = {yAxis: {type: "value",name: "心率 (bpm)",nameTextStyle: {color: "#666",fontSize: 12,},axisLabel: {color: "#666",fontSize: 12,},axisLine: {lineStyle: {color: "#ddd",},},splitLine: {show: true,lineStyle: {color: "#f0f0f0",type: "dashed",},},min: (value: { min: number }) => Math.floor(value.min / 10) * 10,},
}
5.4 數據系列配置
const seriesConfig = {series: [{data: chartData,type: "line",smooth: true,showSymbol: false,lineStyle: {width: 2,color: "#ff6b6b",},areaStyle: {color: {type: "linear",x: 0,y: 0,x2: 0,y2: 1,colorStops: [{ offset: 0, color: "rgba(255, 107, 107, 0.3)" },{ offset: 1, color: "rgba(255, 107, 107, 0.1)" },],},},},],
}
6. 組件集成
6.1 創建演示組件
創建文件:app/screens/DemoShowroomScreen/demos/DemoHeartRateChart.tsx
import { HeartRateChart } from "../../../components"
import { View, StyleSheet } from "react-native"
import { Text } from "../../../components"export const DemoHeartRateChart = () => {return (<View style={styles.container}><Text preset="heading" style={styles.title}>24小時心率圖表</Text><HeartRateChart /></View>)
}const styles = StyleSheet.create({container: {alignItems: "center",padding: 20,},title: {marginBottom: 20,textAlign: "center",},
})
6.2 添加到演示頁面
在 app/screens/DemoShowroomScreen/DemoShowroomScreen.tsx
中:
import { FC } from "react"
import { Screen } from "../../components"
import { DemoHeartRateChart } from "./demos"export const DemoShowroomScreen: FC = function DemoShowroomScreen() {return (<Screen preset="fixed" safeAreaEdges={["top"]}><DemoHeartRateChart /></Screen>)
}
6.3 導出演示組件
在 app/screens/DemoShowroomScreen/demos/index.ts
中:
export * from "./DemoHeartRateChart"
7. 國際化支持
7.1 中文翻譯
在 app/i18n/zh.ts
中添加:
const zh = {// ... 其他翻譯demoShowroomScreen: {// ... 其他翻譯demoHeartRateChart: "心率圖表",demoHeartRateChartDesc: "一個顯示心率隨時間變化的圖表。",},
}
7.2 英文翻譯
在 app/i18n/en.ts
中添加:
const en = {// ... 其他翻譯demoShowroomScreen: {// ... 其他翻譯demoHeartRateChart: "Heart Rate Chart",demoHeartRateChartDesc: "A chart showing heart rate over time.",},
}
8. 最佳實踐
8.1 性能優化
- 使用useMemo緩存圖表配置
const chartOption = useMemo(() => {// 圖表配置邏輯
}, [data, theme])
- 合理管理圖表實例
useEffect(() => {let chartInstance: ECharts | undefinedif (chartRef.current && data.length > 0) {chartInstance = echarts.init(chartRef.current, "light", {renderer: "svg",width: CHART_WIDTH,height: CHART_HEIGHT,})chartInstance.setOption(chartOption)}return () => {chartInstance?.dispose()}
}, [chartOption])
- 避免不必要的重新渲染
const MemoizedChart = React.memo(HeartRateChart)
8.2 錯誤處理
- 數據驗證
const chartOption = useMemo(() => {if (!data || data.length === 0) {return {}}// 圖表配置
}, [data])
- 權限檢查
useEffect(() => {if (permissionsGranted) {fetchData()}
}, [permissionsGranted])
- 加載狀態
{isLoading && <LoadingSpinner />}
{error && <ErrorMessage error={error} onRetry={fetchData} />}
8.3 響應式設計
- 動態尺寸
const [chartSize, setChartSize] = useState({ width: 350, height: 300 })useEffect(() => {const updateSize = () => {const { width } = Dimensions.get('window')setChartSize({width: width - 40, // 減去paddingheight: 300,})}updateSize()Dimensions.addEventListener('change', updateSize)return () => {Dimensions.removeEventListener('change', updateSize)}
}, [])
- 主題適配
const chartOption = useMemo(() => ({// ... 其他配置backgroundColor: theme.colors.background,textStyle: {color: theme.colors.text,},
}), [theme, data])
8.4 統一ECharts實例管理
為了避免在多個組件中重復初始化ECharts模塊導致 [ReferenceError: Property 'document' doesn't exist]
等問題,建議創建一個中心化的echarts.ts
文件來統一管理ECharts實例和模塊注冊。
創建 app/utils/echarts.ts
:
import * as echarts from "echarts/core"
import { SVGRenderer } from "@wuba/react-native-echarts/svgChart"
import {LineChart,BarChart,GaugeChart,CustomChart,
} from "echarts/charts"
import {GridComponent,TooltipComponent,LegendComponent,
} from "echarts/components"// 注冊所有需要的組件
echarts.use([SVGRenderer,LineChart,BarChart,GaugeChart,CustomChart,GridComponent,TooltipComponent,LegendComponent,
])export { echarts }
在組件中使用:
import { echarts } from "../utils/echarts" // 導入集中的 echarts 實例
// ...
// 不再需要 echarts.use(...)
9. 常見問題
9.1 圖表不顯示
問題:圖表組件渲染但圖表內容不顯示
解決方案:
- 檢查模塊注冊:確保所有需要的圖表類型(如
LineChart
)和組件(如TooltipComponent
)都已在app/utils/echarts.ts
中導入并使用echarts.use()
注冊。這是最常見的原因,尤其是在添加新圖表類型后。 - 確認容器尺寸:確保
<SvgChart>
組件或其父容器具有明確的width
和height
樣式。沒有尺寸,圖表將無法渲染。 - 驗證數據格式:檢查傳遞給
setOption
的配置對象中的series.data
格式是否符合 ECharts 的要求。 - 查看初始化錯誤:在
useEffect
中echarts.init
的部分添加try...catch
來捕獲任何初始化時拋出的錯誤。
示例:
// 1. 檢查 app/utils/echarts.ts
echarts.use([SVGRenderer,LineChart, // 確保已添加GridComponent,TooltipComponent,
])// 2. 在組件中設置明確的容器尺寸
<SvgChart ref={chartRef} style={{ width: 350, height: 300 }} />
9.2 數據更新不生效
問題:數據更新后圖表沒有重新渲染
解決方案:
- 檢查useMemo的依賴數組
- 確保數據引用發生變化
- 驗證圖表實例是否正確更新
const chartOption = useMemo(() => {// 圖表配置
}, [data, theme]) // 確保包含所有依賴useEffect(() => {if (chartInstance && chartOption) {chartInstance.setOption(chartOption, true) // 第二個參數為true表示完全替換}
}, [chartOption])
9.3 性能問題
問題:圖表渲染導致性能問題
解決方案:
- 使用數據采樣減少數據點
- 實現虛擬滾動
- 使用Web Worker處理大量數據
// 數據采樣
const sampledData = data.length > 1000 ? data.filter((_, index) => index % 10 === 0): data
9.4 內存泄漏
問題:組件卸載后圖表實例未正確清理
解決方案:
- 在useEffect的清理函數中銷毀圖表實例
- 使用useRef確保引用一致性
useEffect(() => {let chartInstance: ECharts | undefinedif (chartRef.current) {chartInstance = echarts.init(chartRef.current)chartInstance.setOption(chartOption)}return () => {if (chartInstance) {chartInstance.dispose()}}
}, [chartOption])
總結
通過以上步驟,您可以在React Native項目中成功接入ECharts圖表。關鍵要點包括:
- 正確的依賴安裝和配置
- 合理的數據獲取和管理
- 優化的圖表配置和渲染
- 完善的錯誤處理和用戶體驗
- 性能優化和內存管理
這個解決方案提供了一個完整的圖表集成框架,可以根據具體需求進行擴展和定制。