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允许用户从一段数值范围内做出选择。该组件最典型的两种使用形态是带滑块作为 Slider 使用用户沿圆形轨道拖动 thumb 选取数值交互形式与线性 Slider 一致但呈现为环形轨道。不带滑块作为 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-sliderimport { 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/maxAngleonChange的类型签名(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可归纳为四类值与范围、角度与几何、颜色外观、文本显示与模式开关。速查总表属性类型默认值说明valuenumber100滑块当前值maximumValuenumber100滑块最大值minimumValuenumber0滑块最小值minAnglenumber0圆弧起始角度度maxAnglenumber359.9圆弧结束角度度trackRadiusnumber100圆形滑块轨道半径thumbRadiusnumber12滑块 thumb 半径trackWidthnumber5轨道宽度trackColorcolor string主题主色轨道已填充段颜色thumbColorcolor stringtrackColor的值thumb 颜色trackTintColorcolor stringtheme.primary.gray5轨道背景未填充段颜色thumbTextColorcolor stringwhitethumb 上标记文本颜色thumbTextSizenumber10thumb 上标记文本字号noThumbbooleanfalse是否隐藏 thumb用于进度展示showTextbooleanfalse是否在圆环中心显示当前值showThumbTextbooleanfalse是否在 thumb 处显示当前值textColorcolor stringtrackColor的值中心数值文本颜色textSizenumber100中心数值文本字号值与取值范围valuenumber默认100滑块当前值。作为受控组件使用时配合onChange实现双向更新。maximumValuenumber默认100滑块可达到的最大值。与minimumValue一起构成自定义值域见上文值域模型。minimumValuenumber默认0滑块可达到的最小值。角度与几何这组 Props 决定了圆环的几何形状是CircularSlider区别于线性 Slider 的关键。minAnglenumber默认0圆弧的起始角度单位是度degrees。默认从 0° 开始画弧。maxAnglenumber默认359.9圆弧的结束角度单位是度。默认359.9接近但不到 360°这样轨道保持近乎完整的圆环把maxAngle设为90即得到 90° 弧形滑块。注意 Props 文档原表中maxAngle的描述写作 Maximum angle of arc (in degress)degress 为文档笔误实际含义即度且原始列表里minAngle/maxAngle的锚点顺序存在互换本文按语义修正呈现不影响属性本身含义。trackRadiusnumber默认100圆形轨道自身的半径。轨道中心即组件中心trackRadius决定圆环在画布上的大小。thumbRadiusnumber默认12thumb可拖动的小圆点的半径。trackWidthnumber默认5轨道的宽度圆环线宽数值越大轨道越粗。颜色外观trackColorcolor string默认主题主色轨道已填充段的颜色。默认跟随当前主题的 primary 色。thumbColorcolor string默认取trackColor的值thumb 的颜色未显式指定时与trackColor保持一致保证滑块整体视觉统一。trackTintColorcolor string默认theme.primary.gray5轨道背景未填充段的色调色即轨道底色。文档所记默认值为theme.primary.gray5即主题灰色系中的浅灰用于与已填充的trackColor形成明暗对比。注意此处的theme.primary.gray5为 v4.0.0-beta.0 文档的原始写法实际主题对象路径在不同版本中可能表述为theme.colors.grey5使用时以你项目中createTheme的实际结构为准。文本显示与模式开关thumbTextColorcolor string默认whitethumb 上标记文本当前值小标签的颜色。thumbTextSizenumber默认10thumb 上标记文本的字号默认较小10适合作为贴合 thumb 的小标签。textColorcolor string默认取trackColor的值圆环中心数值文本的颜色默认与轨道已填充段颜色一致。textSizenumber默认100圆环中心数值文本的字号。需要说明的是v4.0.0-beta.0 的 Props 文档所记默认值为100超大号数字适合进度指示形态的醒目展示而在后续 rc 版本文档中该默认值被调整为80两个版本对同一属性的默认字号记录不同具体以你安装的版本为准。noThumbboolean默认false是否显示 thumb。文档描述为 Show no thumb (for progress)即设为true后不渲染 thumb组件从滑块退化为进度指示器配合showText可在圆环中心显示进度百分比。showTextboolean默认false是否在圆环中心显示当前值文本。适合进度指示形态把当前百分比大字展示在圆环中央。showThumbTextboolean默认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)形态noThumbshowText是环形进度的标准组合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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考