企业官网建设流程全解析

React Native Elements LinearProgress 组件实战：indeterminate 与 determinate 两种进度条的正确用法

【免费下载链接】react-native-elementsCross-Platform React Native UI Toolkit项目地址: https://gitcode.com/gh_mirrors/re/react-native-elements

导读

LinearProgress 是 React Native Elements（RNE）提供的线性进度指示器组件，用于向用户反馈正在进行的任务的当前状态——例如应用加载、表单提交、数据保存等场景。它支持「不确定进度（indeterminate）」与「确定进度（determinate）」两种形态，并原生支持主题定制与无障碍属性。读完本文，你将掌握 LinearProgress 的完整 Props 体系、两种变体的适用场景与实现原理，并能基于 website/versioned_docs/version-4.0.0-beta.0/main/usage/LinearProgress/snack/index.md 中的可运行示例，快速搭建一个带进度模拟与重置控制的真实进度条应用。

一、组件定位与适用场景

根据 LinearProgress 组件文档 的定义：进度指示器向用户传达正在进行中的过程状态，如加载应用、提交表单或保存更新，同时说明应用当前状态并暗示可用操作（例如用户能否离开当前页面）。

从源码注释（packages/base/src/LinearProgress/LinearProgress.tsx）可以看到，LinearProgress 继承自 React Native 的View，因此所有 View 的 Props（onLayout、accessible、testID 等）均可直接透传。其最小可用形态极其简单：

import { LinearProgress } from 'react-native-elements'; // 不确定进度（默认形态） <LinearProgress />

二、安装与导入

2.1 包结构说明

仓库采用packages/base与packages/themed双层架构：

• base 包（@rneui/base）：无主题依赖的底层组件实现，位于 packages/base/src/LinearProgress；
• themed 包（@rneui/themed）：通过withTheme包装后的主题化版本，位于 packages/themed/src/LinearProgress/index.tsx。

2.2 导入方式

// 方式一：聚合入口（示例文档采用） import { LinearProgress } from 'react-native-elements'; // 方式二：主题化包 import { LinearProgress } from '@rneui/themed'; // 方式三：base 包 import { LinearProgress } from '@rneui/base';

themed 包在导出时还通过Object.assign注入了两个便捷常量（见 packages/themed/src/LinearProgress/index.tsx），使代码语义更清晰：

LinearProgress.INDETERMINATE; // 'indeterminate' LinearProgress.DETERMINATE; // 'determinate' // 使用方式 <LinearProgress variant={LinearProgress.DETERMINATE} value={0.5} />

三、两种变体（variant）的实战用法

3.1 Indeterminate（不确定进度）

当无法预知任务完成时间或进度百分比时使用，表现为进度条来回往复滑动的动画效果。它是默认形态——只要不传value，组件自动进入 indeterminate 模式：

// 默认 indeterminate <LinearProgress style={{ marginVertical: 10 }} /> // 指定颜色 <LinearProgress style={{ marginVertical: 10 }} color="red" />

3.2 Determinate（确定进度）

当进度值可计算时使用，value取值范围为0～1的浮点数（0 表示未开始，1 表示完成）：

<LinearProgress style={{ marginVertical: 10 }} value={0.6} variant="determinate" />

关键默认行为：variant的默认值并非写死的字符串，而是由value是否传入动态决定——value === undefined ? 'indeterminate' : 'determinate'（见 packages/base/src/LinearProgress/LinearProgress.tsx）。也就是说：

• 传了value没传variant→ 自动按 determinate 渲染；
• 没传value→ 自动按 indeterminate 渲染。

组件测试用例 packages/base/src/LinearProgress/tests/LinearProgress.test.tsx 专门验证了「提供 value 时默认降级为 determinate」这一行为。

四、Props 完整参考

下表整理自 LinearProgress 组件文档 的 Props 表格，并结合源码补充了取值细节：

五、完整可运行示例：带启动/重置控制的进度条

以下示例直接取自 snack/index.md（当前仓库 v4.0.0-beta.0 版本文档），同时展示了两种变体，并用Button驱动 determinate 进度的模拟推进：

import React from 'react'; import { View, Text } from 'react-native'; import { Button, LinearProgress } from 'react-native-elements'; const LinearProgressAPI: React.FunctionComponent = () => { const [progress, setProgress] = React.useState(0); React.useEffect(() => { let subs = true; if (progress < 1 && progress !== 0) { setTimeout(() => { if (subs) { setProgress(progress + 0.1); } }, 100); } return () => { subs = false; }; }, [progress]); return ( <View> <View style={{ margin: 10, }} > <Text>Indeterminate Variant </Text> <LinearProgress style={{ marginVertical: 10 }} /> <Text>Indeterminate Variant with color</Text> <LinearProgress style={{ marginVertical: 10 }} color="red" /> <Text>Determinate Variant</Text> <LinearProgress style={{ marginVertical: 10 }} value={progress} variant="determinate" /> <Button disabled={progress > 0} onPress={() => { setProgress(0.00001); }} title={'Start Progress'} containerStyle={{ margin: 10 }} /> <Button disabled={progress === 0} onPress={() => { setProgress(0); }} title={'Restart'} containerStyle={{ margin: 10 }} /> </View> </View> ); }; export default LinearProgressAPI;

该示例的精妙之处在于进度模拟逻辑：

• 初始progress = 0，点击Start Progress后将其设为0.00001（非 0 才能进入useEffect的自增分支）；
• useEffect监听progress，只要progress < 1且非 0，就通过setTimeout每100ms递增0.1，模拟加载过程；
• subs标志位在组件卸载时将subs置为false，避免卸载后仍触发setState（防止内存泄漏与 React 警告）；
• Start Progress在progress > 0时禁用，Restart在progress === 0时禁用，构成完整的交互闭环。

六、源码级原理剖析

6.1 动画实现：Animated 驱动

packages/base/src/LinearProgress/LinearProgress.tsx 内部维护一个Animated.Value过渡值transition，通过useNativeDriver: true将动画交由原生驱动以提升性能：

• indeterminate：使用Animated.loop()无限循环Animated.timing，让进度条不断往返；
• determinate：单次Animated.timing将transition动画到value || 0；
• 动画时长取自animation.duration，默认2000ms（见 LinearProgress.tsx）；
• determinate 模式下useNativeDriver在 Web 端被关闭（Platform.OS !== 'web'），以保证跨端兼容。

进度条视觉宽度通过transition.interpolate()的translateX与scaleX组合变换实现，两个变体的插值区间不同：

• indeterminate：translateX从-width滑向0.5 * width，scaleX走[0.0001, 1, 0.001]三段区间，产生「滑块伸缩往复」的经典效果；
• determinate：translateX从-0.5 * width归零，scaleX从0.0001放大到1，呈现「从中心向右侧展开」的填充动画。

6.2 颜色与轨道色

const tintColor = color === 'secondary' || color === 'primary' ? theme?.colors?.[color] : Color(color).rgb().string() || theme?.colors?.secondary; const trackTintColor = trackColor || Color(tintColor).alpha(0.4).rgb().string();

• 传入'primary'/'secondary'时读取主题色板；
• 传入任意颜色字符串时，通过color库归一化为 RGB 格式；
• 未指定trackColor时，轨道色自动取前景色的 40% 透明度——这是默认样式的实现来源。

6.3 数值安全：clamp 边界钳制

determinate 的value会被clamp()钳制到 [0, 1] 区间（实现见 packages/base/src/utils/math.ts）：

export const clamp = (value: number = 0): number => Math.max(0, Math.min(value, 1)) || 0;

对应测试（LinearProgress.test.tsx）验证了：clamp(3) === 1、clamp(-1) === 0、clamp(undefined) === 0、clamp(0.6) === 0.6。因此即使传入越界值也不会破坏 UI。

6.4 无障碍支持

组件根节点自带accessible、accessibilityRole="progressbar"与accessibilityValue（{ now, min: 0, max: 1 }），屏幕阅读器可正确播报进度状态。注意now取整为Math.floor(clamp(value))——测试注释说明这是为避免浮点运算精度警告而刻意为之（见 LinearProgress.test.tsx）。

6.5 关闭动画的静态渲染

当animation={false}时，组件跳过 Animated 分支，直接渲染普通View，宽度为width * clamp(value)。测试用例验证了value={0.4}、容器宽 300 时进度条宽为300 * 0.4（见 LinearProgress.test.tsx）。静态渲染非常适合需要精确控制、或动画开销敏感的场景（如列表项内嵌）。

七、主题定制

themed 包通过withTheme(LinearProgress, 'LinearProgress')注册了LinearProgress主题键（packages/themed/src/LinearProgress/index.tsx）。因此可以在ThemeProvider的components中统一配置默认行为：

import { ThemeProvider } from '@rneui/themed'; const theme = { components: { LinearProgress: { color: 'rgb(255, 0, 0)', trackColor: '#eee', animation: { duration: 1500 }, }, }, }; export default () => ( <ThemeProvider theme={theme}> <App /> </ThemeProvider> );

主题化测试 packages/themed/src/LinearProgress/tests/LinearProgress.test.tsx 验证了：从主题注入的color: 'rgb(255, 0, 0)'会正确应用到前景色。这意味着你可以全局统一样式，而无需在每个使用处重复传参。

八、测试保障概览

base 包的测试覆盖了组件主要行为（LinearProgress.test.tsx）：

• 颜色与轨道色正确应用（color="red" trackColor="blue"时背景为blue）；
• determinate / indeterminate 快照渲染；
• 提供value时自动采用 determinate；
• animation={false}时按width * value静态渲染；
• 无障碍属性完整（role 与 accessibilityValue）。

九、使用建议小结

1. 任务时长未知（网络请求、图片加载）→ 用默认 indeterminate 形态；
2. 任务进度可计算（文件上传、表单分步）→ 传value，让组件自动切换 determinate；
3. 需要精确反馈→ 用animation={false}关闭动画，直接按数值渲染；
4. 统一品牌色→ 通过 ThemeProvider 的components.LinearProgress全局配置，而非逐个传参；
5. 注意 value 取值范围：虽然内部有clamp兜底，但业务侧仍应尽量传入 0～1 的合法值，配合Math.floor或百分比换算使用更清晰。

相关源码与文档可继续查阅：组件实现、组件文档、主题化实现。

【免费下载链接】react-native-elementsCross-Platform React Native UI Toolkit项目地址: https://gitcode.com/gh_mirrors/re/react-native-elements