企业官网建设流程全解析

react-native-elements-universe CircularSlider 圆形滑块组件完全指南：Props 详解与实战用法

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

导读

本文基于 react-native-elements 仓库 v4.0.0-beta.0 版本文档中CircularSlider的 Props 参考（website/versioned_docs/version-4.0.0-beta.0/universe/props/circularslider.md）编写，系统讲解这个react-native-elements-universe圆形/弧形滑块组件的全部属性、默认值与取值范围，并结合官方 Usage 示例与后续版本文档，给出可复制的实战用法。读完本文，你将掌握：如何用圆形滑块让用户从连续区间取值、如何通过noThumb将其降级为环形进度指示器、如何通过minAngle/maxAngle生成 90° 弧形滑块，以及每个外观与文本属性的作用。

组件定位：一个控件，两种形态

按照 version-4.0.0-beta.0 的 circularSlider 组件文档 的描述：

这是一个react-native-elements-universe组件。滑块（Slider）允许用户从一段数值范围内做出选择。

该组件最典型的两种使用形态是：

1. 带滑块（作为 Slider 使用）：用户沿圆形轨道拖动 thumb 选取数值，交互形式与线性 Slider 一致，但呈现为环形轨道。
2. 不带滑块（作为 Progress Indicator 使用）：设置noThumb后隐藏 thumb，仅以轨道填充比例展示进度，例如环形进度环。

从仓库内的 GSoC 2021 博客（website/blog/2021-08-23-google-summer-of-code-arpitBhalla.md）可以看到，CircularSlider 正是该届 GSoC 期间由贡献者 Arpit Bhalla 在react-native-elements-universe仓库中新建并合入的组件（对应其 universe 仓库 PR #1），属于 React Native Elements 生态中独立于packages/base与packages/themed的扩展组件。因此在 v4.0.0-beta.0 时期，它通过独立的react-native-elements-universe包分发。

安装与导入

v4.0.0-beta.0 的组件文档给出的导入方式为：

import { CircularSlider } from 'react-native-elements-universe';

在后续版本（如 version-4.0.0-rc.1 的 CircularSlider.mdx）中，该组件被拆分为独立的@rneui/circular-slider包，此时安装与导入方式变为：

# NPM npm install @rneui/circular-slider # Yarn yarn add @rneui/circular-slider

import { CircularSlider } from '@rneui/circular-slider';

提示：以上两种导入方式分别对应不同文档版本，实际使用时请以你所安装的包版本对应文档为准。v4.0.0-beta.0 版本文档面向react-native-elements-universe包。

基础用法：三个最小示例

组件文档给出了三个可以直接运行的最小示例，覆盖了本文档涉及的三种核心场景：

import { CircularSlider } from 'react-native-elements-universe'; // 1. 标准滑块：value 为当前值，onChange 为值变化回调 <CircularSlider value={value} onChange={setValue} />; // 2. 进度指示器：隐藏 thumb，仅展示填充比例 <CircularSlider value={value} noThumb />; // 3. 90 度弧形滑块：通过 maxAngle 限定弧长 <CircularSlider maxAngle={90} />;

• 第一个示例是最基本的滑块用法：value传入当前值，用户在轨道上拖动后通过onChange拿到新值（注意：beta.0 的组件文档正文只展示了value/onChange/noThumb/maxAngle，onChange的类型签名(value: number) => void在 rc 版本 Props 表中被补充为(x) => x默认恒等函数）。
• 第二个示例即"进度指示器"形态，对应组件文档中的第二张预览图（不带 thumb 的环形进度）。
• 第三个示例展示了弧形模式：maxAngle={90}会把完整圆环收缩为 90° 的扇形弧，配合minAngle可以进一步控制弧的起始位置。

值域模型：百分比与自定义范围二选一

组件文档在 Usage 之后特别用引用块强调了一条取值规则：

要么在value中使用百分比（0 到 100），要么指定maximumValue与minimumValue。

这决定了CircularSlider的值域工作方式：

• 默认百分比模式：minimumValue默认0、maximumValue默认100，此时value直接以 0~100 的百分比语义参与轨道映射，0 对应起始角度，100 对应结束角度。
• 自定义范围模式：当业务数值不是 0~100（例如温度 -20~60、音量 0~200 等）时，显式设置maximumValue与minimumValue，组件会按比例把该区间线性映射到弧形轨道上，value与onChange中传递的都是业务数值本身。

从 Props 参考可知，value的默认值是100，也就是说如果你只写<CircularSlider />而不传值，轨道会默认处于满值状态——这也是noThumb进度指示形态下常见的默认呈现。实践建议：滑块场景中务必显式传入受控的value并配套onChange，避免使用默认满值。

Props 全解析

这是本篇文章的核心章节。v4.0.0-beta.0 的 Props 文档（website/versioned_docs/version-4.0.0-beta.0/universe/props/circularslider.md）共定义了 17 个 Props，可归纳为四类：值与范围、角度与几何、颜色外观、文本显示与模式开关。

速查总表

值与取值范围

• value（number，默认100）：滑块当前值。作为受控组件使用时，配合onChange实现双向更新。
• maximumValue（number，默认100）：滑块可达到的最大值。与minimumValue一起构成自定义值域（见上文"值域模型"）。
• minimumValue（number，默认0）：滑块可达到的最小值。

角度与几何

这组 Props 决定了圆环的几何形状，是CircularSlider区别于线性 Slider 的关键。

• minAngle（number，默认0）：圆弧的起始角度，单位是度（degrees）。默认从 0° 开始画弧。
• maxAngle（number，默认359.9）：圆弧的结束角度，单位是度。默认359.9（接近但不到 360°），这样轨道保持近乎完整的圆环；把maxAngle设为90即得到 90° 弧形滑块。注意 Props 文档原表中maxAngle的描述写作 "Maximum angle of arc (in degress)"（"degress" 为文档笔误，实际含义即"度"），且原始列表里minAngle/maxAngle的锚点顺序存在互换，本文按语义修正呈现，不影响属性本身含义。
• trackRadius（number，默认100）：圆形轨道自身的半径。轨道中心即组件中心，trackRadius决定圆环在画布上的大小。
• thumbRadius（number，默认12）：thumb（可拖动的小圆点）的半径。
• trackWidth（number，默认5）：轨道的宽度（圆环线宽），数值越大轨道越粗。

颜色外观

• trackColor（color string，默认主题主色）：轨道已填充段的颜色。默认跟随当前主题的 primary 色。
• thumbColor（color string，默认取trackColor的值）：thumb 的颜色，未显式指定时与trackColor保持一致，保证滑块整体视觉统一。
• trackTintColor（color string，默认theme.primary.gray5）：轨道背景（未填充段）的色调色，即轨道"底色"。文档所记默认值为theme.primary.gray5（即主题灰色系中的浅灰），用于与已填充的trackColor形成明暗对比。注意此处的theme.primary.gray5为 v4.0.0-beta.0 文档的原始写法，实际主题对象路径在不同版本中可能表述为theme.colors.grey5，使用时以你项目中createTheme的实际结构为准。

文本显示与模式开关

• thumbTextColor（color string，默认white）：thumb 上标记文本（当前值小标签）的颜色。
• thumbTextSize（number，默认10）：thumb 上标记文本的字号，默认较小（10），适合作为贴合 thumb 的小标签。
• textColor（color string，默认取trackColor的值）：圆环中心数值文本的颜色，默认与轨道已填充段颜色一致。
• textSize（number，默认100）：圆环中心数值文本的字号。需要说明的是，v4.0.0-beta.0 的 Props 文档所记默认值为100（超大号数字，适合进度指示形态的醒目展示）；而在后续 rc 版本文档中该默认值被调整为80，两个版本对同一属性的默认字号记录不同，具体以你安装的版本为准。
• noThumb（boolean，默认false）：是否显示 thumb。文档描述为 "Show no thumb (for progress)"，即设为true后不渲染 thumb，组件从"滑块"退化为"进度指示器"，配合showText可在圆环中心显示进度百分比。
• showText（boolean，默认false）：是否在圆环中心显示当前值文本。适合进度指示形态，把当前百分比大字展示在圆环中央。
• showThumbText（boolean，默认false）：是否在 thumb 处显示当前值文本。适合滑块形态，让用户拖动时随时看到精确数值。

典型组合实战

将上述 Props 组合起来，可以得到若干常见场景的完整写法：

// 场景 A：带 thumb 的标准滑块，thumb 上显示当前值 <CircularSlider value={value} onChange={setValue} showThumbText trackRadius={100} thumbRadius={14} trackWidth={8} />; // 场景 B：环形进度指示器（隐藏 thumb，中心大字显示百分比） <CircularSlider value={progress} // 0 ~ 100 noThumb showText textSize={48} trackColor="#2089dc" trackTintColor="#e1e8ee" />; // 场景 C：自定义值域的 90° 弧形滑块（如音量 0~200） <CircularSlider value={volume} onChange={setVolume} minimumValue={0} maximumValue={200} minAngle={0} maxAngle={90} />;

• 场景 A 对应文档预览中"With Thumb (as a slider)"的形态，showThumbText让 thumb 自带数值标签；
• 场景 B 对应"Without Thumb (as a Progress Indicator)"形态，noThumb+showText是环形进度的标准组合，trackTintColor提供底色对比；
• 场景 C 对应arcSlider.png预览图展示的弧形滑块：通过minAngle/maxAngle把完整圆环收缩为指定角度的弧，并配合minimumValue/maximumValue使用业务数值而非百分比。

版本演进与迁移注意

从仓库内的文档历史可以梳理出该组件的演进脉络，便于你在不同版本间迁移：

• v4.0.0-beta.0（本文 Props 参考的版本）：组件属于react-native-elements-universe包，通过import { CircularSlider } from 'react-native-elements-universe'引入，对应 universe/circularSlider.md。
• v4.0.0-rc.1 / rc.2：组件独立为@rneui/circular-slider包，Props 基本保持一致，但 Props 表中补全了onChange（类型(value: number) => void，默认(x) => x），且textSize默认值记录为80（见 rc.1 的 CircularSlider.mdx）。
• 更早的v3.4.2文档（version-3.4.2/circularSlider.md）已具备与 beta.0 相同的用法示例与 Props 引用机制。

迁移时需注意两点：一是导入来源随版本变化（react-native-elements-universe→@rneui/circular-slider）；二是textSize默认值在不同版本文档中存在差异，若依赖默认字号呈现，升级后请核对实际渲染效果。本文所有 Props 默认值均以 v4.0.0-beta.0 的 Props 文档为基准，已在相应位置标注与其他版本的差异。

总结

CircularSlider 是 React Native Elements 生态中负责"环形取值"的扩展组件，它的核心设计可以概括为三点：值域可自定义（百分比模式或minimumValue/maximumValue模式）、几何可配置（minAngle/maxAngle/trackRadius/thumbRadius/trackWidth共同决定圆环形态）、双形态复用（noThumb一行属性即可在滑块与进度指示器之间切换）。17 个 Props 中，值与范围、角度与几何、颜色外观、文本显示四大类职责清晰，配合showText、showThumbText、textColor、textSize、thumbTextColor、thumbTextSize可精细控制数值文本的呈现位置与样式。如果你需要进一步确认某个属性的行为，可回到 Props 参考文档 与 组件主文档 对照查阅。

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