Bevy Feathers NumberInput 數(shù)字輸入控件實(shí)戰(zhàn)scrubbing 拖拽、限制區(qū)間與受控?cái)?shù)值綁定的完整指南【免費(fèi)下載鏈接】bevyA refreshingly simple>項(xiàng)目地址: https://gitcode.com/GitHub_Trending/be/bevy導(dǎo)讀FeathersNumberInput是 Bevy Feathers UI 組件庫中的數(shù)字輸入控件本文基于其新增的 scrubbing按住鼠標(biāo)拖拽改值能力展開講清該控件的支持類型、HardLimit/SoftLimit/NumberInputPrecision/Step等可選配置組件各自的語義以及“受控組件”模式下與ValueChange事件的雙向同步寫法。讀完本文你可以直接用場景 DSL 組裝一個(gè)具備 Blender 式交互、可限制區(qū)間、可帶單位換算的數(shù)字輸入框并理解其底層狀態(tài)機(jī)與拖拽速度啟發(fā)式算法。一、這次更新改了什么向 Blender 的數(shù)字輸入交互對齊在本次重構(gòu)之前FeathersNumberInput更像一個(gè)能輸入數(shù)字的文本框。更新后該控件從 Blender 的數(shù)字輸入字段numeric input中借鑒了最佳交互元素核心變化是引入了多種編輯模式并存Scrubbing拖拽改值按住鼠標(biāo)左右拖動即可連續(xù)修改數(shù)值直接鍵盤輸入direct keyboard entry點(diǎn)擊后進(jìn)入編輯態(tài)直接鍵入數(shù)字與此同時(shí)保留了對f32、f64、i32、i64四種數(shù)值類型的完整支持由NumberInputValue的枚舉變體決定見 crates/bevy_feathers/src/controls/number_input.rs。這意味著 Feathers 的數(shù)字輸入控件在交互能力上大大貼近 Blender 的數(shù)字字段適用于屬性面板、變換工具位置/旋轉(zhuǎn)/縮放、參數(shù)化編輯器等需要快速、連續(xù)、精確同時(shí)具備的場景。二、受控組件模型數(shù)值真相保存在應(yīng)用側(cè)FeathersNumberInput是標(biāo)準(zhǔn) Feathers 風(fēng)格的受控控件controlled widget。所謂受控指控件內(nèi)部不會自動維護(hù)當(dāng)前數(shù)值數(shù)值的真實(shí)來源始終是應(yīng)用持有的某個(gè)數(shù)據(jù)結(jié)構(gòu)控件與數(shù)據(jù)之間通過兩條通道保持雙向同步此設(shè)計(jì)在 number_input.rs 的文檔注釋中描述得很清楚用戶在控件上拖拽或輸入 → 控件發(fā)出ValueChangeT事件 → 應(yīng)用事件處理器把新值寫回應(yīng)用數(shù)據(jù)應(yīng)用數(shù)據(jù)變化無論來自該事件還是別處→ 應(yīng)用向控件實(shí)體插入NumberInputValue組件→ 控件監(jiān)聽組件插入、刷新文本框內(nèi)容與滑塊位置。ValueChangeT事件定義在 crates/bevy_ui_widgets/src/lib.rs除value外還攜帶一個(gè)is_final布爾標(biāo)志拖拽過程中is_final為false表示值在預(yù)覽/連續(xù)變化狀態(tài)拖拽結(jié)束、回車提交或失焦時(shí)is_final為true表示這是一個(gè)最終提交值。源碼注釋特別提醒即使is_final false應(yīng)用也應(yīng)該回寫控件值插入新的NumberInputValue否則用戶拖拽時(shí)看不到數(shù)字實(shí)時(shí)變化見 number_input.rs。事件處理器的最小寫法feathers_number_input示例展示了這種數(shù)值回寫自身的最小處理器見 examples/ui/widgets/feathers_number_input.rson( |value_change: OnValueChangef32, mut commands: Commands| { commands .entity(value_change.event_target()) .insert(NumberInputValue::F32(value_change.value)); }, )從源碼看控件通過OnInsertNumberInputValue觀察者number_input_on_insert_value監(jiān)聽組件插入若新值與當(dāng)前文本不同就用queue_edit(TextEdit::SelectAll)queue_edit(TextEdit::Insert(...))替換文本框內(nèi)容同時(shí)調(diào)用update_slider_pos把背景滑塊條移動到對應(yīng)位置見 number_input.rs。為減少無謂刷新官方建議只在值真正變化時(shí)插入NumberInputValue見 number_input.rs。三、行為配置組件四件套 環(huán)繞模式控件行為通過若干可選組件直接隨場景 DSL 掛到FeathersNumberInput實(shí)體上來配置。它們的語義是本次發(fā)布說明的核心內(nèi)容下面逐一展開。HardLimit —— 絕對硬邊界HardLimit指定數(shù)值的絕對最小/最大范圍對應(yīng)NumberInputRange的一個(gè)區(qū)間。任何超出該范圍的取值都會被clamp截?cái)嗷剡吔鐑?nèi)無論來自拖拽、步進(jìn)還是鍵入。若該組件缺省則使用該數(shù)據(jù)類型自身的自然范圍如f32即整個(gè) 32 位浮點(diǎn)范圍。按類型提供便捷構(gòu)造HardLimit::f32(range)、HardLimit::f64(range)、HardLimit::i32(range)、HardLimit::i64(range)見 number_input.rs。clamp 行為本身定義在NumberInputRange::clamp見 number_input.rs。注意若區(qū)間類型與值類型不匹配會warn_once并原樣返回值。SoftLimit —— 僅約束拖拽的“軟邊界”SoftLimit指定僅通過拖拽可到達(dá)的范圍通過鍵入輸入的值可以超出這個(gè)范圍。這正是它叫“軟”的原因——它不是上限而是拖拽舒適區(qū)。例如SoftLimit(NumberInputRange::F32(0.0..10.0))意味著拖拽最多改到 0~10但鍵盤可以輸入 25.5。應(yīng)用場景既希望鼠標(biāo)操作限定在合理區(qū)間防止誤拖又保留高級用戶直接輸入越界值的靈活性。NumberInputPrecision —— 拖拽精度量化NumberInputPrecision(pub i32)表示拖拽時(shí)保留的小數(shù)位數(shù)值為2→ 四舍五入到最近的 1/100值為0→ 取整值為負(fù)數(shù)如-3→ 四舍五入到最近的千位見 number_input.rs。它的作用僅限于拖拽過程中量化數(shù)值避免小數(shù)點(diǎn)后面一串?dāng)?shù)字亂跳不影響鍵盤鍵入也不阻止應(yīng)用通過其他途徑如直接插入NumberInputValue設(shè)置非量化值見 number_input.rs 注釋。實(shí)現(xiàn)上NumberInputPrecision::round對F32/F64計(jì)算10^n因子做乘后取整再除對整數(shù)類型保持恒等映射見 number_input.rs。NumberInputStep —— 步進(jìn)增量NumberInputStep(pub f64)表示遞增/遞減時(shí)單次改變的增量默認(rèn)1.0。當(dāng)光標(biāo)懸停在無軟邊界的輸入框上時(shí)會出現(xiàn)左右兩個(gè) chevron 箭頭NumberInputDecrement/NumberInputIncrement點(diǎn)擊即按該步長加減拖拽速度計(jì)算也會參考該值見下文。構(gòu)造與默認(rèn)值見 number_input.rs。發(fā)布說明中描述的是Step實(shí)際實(shí)現(xiàn)中的組件名為NumberInputStep二者指向同一配置語義。NumberInputWrap —— 硬邊界環(huán)繞除四件套外實(shí)現(xiàn)中還提供了NumberInputWrapNoWrap/Wrap組件當(dāng)存在HardLimit且開啟Wrap時(shí)越界值會wrap環(huán)繞回區(qū)間內(nèi)而非被 clamp典型用例是角度/朝向這類周期性數(shù)值。環(huán)繞實(shí)現(xiàn)在NumberInputRange::wrap基于rem_euclid見 number_input.rs若配置了Wrap卻沒有HardLimit會告警并忽略環(huán)繞見 number_input.rs。各約束的合成順序當(dāng)一個(gè)拖拽/提交同時(shí)攜帶多個(gè)約束時(shí)應(yīng)用順序是有講究的。emit_drag_value_change中可以看到完整流水線見 number_input.rs以拖拽起始值base_value為基準(zhǔn)累加偏移得到候選值每次拖拽是相對拖拽開始值的增量而不是相對上一幀值若有SoftLimit→ clamp 進(jìn)軟范圍若有NumberInputPrecision→ 按小數(shù)位量化最后處理硬邊界HardLimitWrap則環(huán)繞否則 clamp。硬邊界最后應(yīng)用確保任何路徑產(chǎn)出的值都不可能越出硬邊界。四、兩種交互外觀Slider 模式與 Scrubber 模式控件的外觀與拖拽手感取決于是否配置SoftLimit這是本次發(fā)布說明區(qū)分出的兩種模式。有 SoftLimit看起來像一個(gè)滑塊當(dāng)SoftLimit存在時(shí)控件觀感與手感都更接近 FeathersSlider輸入框背景會繪制一條滑軌slide bar數(shù)值所在位置有一條與滑塊 thumb 等寬的“已填充”條拖拽速度按公式(范圍長度 / 滑軌像素寬度)計(jì)算見 number_input.rs也就是鼠標(biāo)移動多少像素值就按比例覆蓋多少范圍鼠標(biāo)位移與滑軌尺寸嚴(yán)格同步——這正是發(fā)布說明中“changes in the bars size will be synchronized with movement of the mouse”的含義滑軌位置由update_slider_pos依據(jù)NumberInputRange::thumb_position計(jì)算出的 0~1 比例實(shí)時(shí)更新到BackgroundGradient的漸變色標(biāo)上見 number_input.rs這種用漸變畫滑塊的做法可以讓滑軌也保持圓角。無 SoftLimit更像一個(gè)“擦子”Scrubber當(dāng)SoftLimit不存在時(shí)控件不畫滑軌表現(xiàn)為典型的“scrubber”拖拽速度不再由滑軌決定而是依據(jù)一套啟發(fā)式算法綜合當(dāng)前可用信息推斷見 number_input.rs優(yōu)先級從高到低為有NumberInputStep→ 速度 step × BASE_DRAG_SPEEDBASE_DRAG_SPEED 0.01見 number_input.rs是整數(shù)類型I32/I64→ 視為 step1使用基礎(chǔ)速度有NumberInputPrecision→ 由精度反推速度 10^(-precision)以上都沒有 → 使用自適應(yīng)算法取當(dāng)前值絕對值的數(shù)量級距 1 最近的 10 的冪作為量級縮放BASE_DRAG_SPEED × 10^decade保證大數(shù)拖得快、小數(shù)拖得慢。增強(qiáng)細(xì)節(jié)Shift 慢速微調(diào)scrubber_on_drag中還有一個(gè)實(shí)用設(shè)計(jì)拖拽時(shí)按住Shift位移增量乘以0.1實(shí)現(xiàn)慢速精細(xì)調(diào)節(jié)見 number_input.rs。五、點(diǎn)擊 vs 拖拽內(nèi)部狀態(tài)機(jī)如何區(qū)分兩種手勢兩種模式共同的前提是需要區(qū)分用戶是想拖拽改值還是想點(diǎn)一下進(jìn)入輸入模式?？丶靡粋€(gè)DragState組件 EditMode枚舉Idle/Scrubbing/Editing見 number_input.rs管理狀態(tài)遷移并定義一個(gè)DRAG_THRESHOLD_DISTANCE 0.5像素閾值見 number_input.rs。從事件處理器可以梳理出完整的判定流程輸入框內(nèi)部有一個(gè)絕對定位、覆蓋整個(gè)輸入?yún)^(qū)、用于攔截指針事件的透明子實(shí)體scrubber承載 press/release/drag_start/drag/drag_end/drag_cancel 一系列觀察者見 number_input.rsscrubber_on_press非編輯態(tài)下按下 → 進(jìn)入Scrubbing模式并把TextReadWriteMode切為Static隱藏光標(biāo)同時(shí)propagate(false)阻止事件繼續(xù)傳給底層文本編輯見 number_input.rsscrubber_on_drag實(shí)時(shí)記錄累計(jì)最大位移max_distance只有當(dāng)位移超過 0.5px 閾值才開始改值防止點(diǎn)擊時(shí)的抖動誤觸發(fā)——這是“click vs drag”判定的核心見 number_input.rsscrubber_on_release若整次按下釋放過程中max_distance從未超過閾值 → 視為一次點(diǎn)擊切換進(jìn)Editing模式恢復(fù)TextReadWriteMode::Editable、光標(biāo)變成 I-Beam并根據(jù)點(diǎn)擊位置把文本光標(biāo)MoveToPoint定位過去見 number_input.rs輸入過程中若發(fā)生PointerCancel如窗口失焦打斷scrubber_on_drag_cancel會把狀態(tài)還原為Idle見 number_input.rs。拖拽/懸停時(shí)控件的滑軌與配色由set_slidebar_styles統(tǒng)一刷新它根據(jù) disabled / pressed / hovered / focused 狀態(tài)在SLIDER_BAR_*、SLIDER_BG_*、TEXT_INPUT_TEXT_*等主題 token 之間切換顏色并同步設(shè)置系統(tǒng)光標(biāo)形狀禁用時(shí)NotAllowed否則ColResize見 number_input.rs。點(diǎn)擊進(jìn)入編輯模式后的行為非拖拽點(diǎn)擊會激活typing 模式用戶可以輸入數(shù)字直接改值回車Enter提交number_input_on_enter_key把當(dāng)前文本按控件聲明的格式解析應(yīng)用硬邊界與環(huán)繞約束后觸發(fā)一次is_final true的ValueChange并把模式切回Idle見 number_input.rs失焦提交number_input_on_focus_lost走同樣的解析提交路徑并恢復(fù)光標(biāo)與只讀模式見 number_input.rs解析失敗時(shí)只warn!(number input parsing failed, invalid format)并放棄該次提交見 number_input.rs若文本被清空為空串則不觸發(fā)事件見 number_input.rs。六、類型支持與格式解析NumberInputValue 是如何分派的NumberInputValue是承載數(shù)值的組件也是一個(gè)帶類型的枚舉pub enum NumberInputValue { F32(f32), F64(f64), I32(i32), I64(i64), }默認(rèn)值為F32(0.0)見 number_input.rs。由于FeathersNumberInput通過#[require(NumberInputValue)]要求該組件創(chuàng)建控件時(shí)只需直接插入一個(gè)帶值的NumberInputValue變體即可設(shè)定初始值并決定控件的數(shù)據(jù)格式見 number_input.rs。NumberFormat枚舉默認(rèn)F32記錄當(dāng)前編輯格式它決定發(fā)出的ValueChangeT泛型類型trigger_value_change會按枚舉變體把commands.trigger(ValueChange { source, value, is_final })分派為ValueChangef32/ValueChangef64/ValueChangei32/ValueChangei64四者之一見 number_input.rs。事件中攜帶的source實(shí)體即FeathersNumberInput根實(shí)體應(yīng)用可以據(jù)此區(qū)分是哪個(gè)輸入框發(fā)出的變化。整數(shù)變體的加減采用saturating_add防止溢出見 number_input.rs。七、帶單位的數(shù)字輸入U(xiǎn)nits 注冊表與展示換算除了裸數(shù)值實(shí)現(xiàn)還提供了成熟的單位系統(tǒng)讓同一個(gè)控件既顯示45°又能以45d編輯NumberInputUnits掛在控件上的引用組件內(nèi)容是一個(gè)字符串 id如length_meters、angle_degrees指向注冊表中某個(gè)UnitsFormat見 number_input.rsUnitsFormattrait定義id()、format(value, editing)按展示/編輯兩種模式格式化字符串、parse(...)把帶后綴字符串解析回規(guī)范單位數(shù)值見 number_input.rsStandardUnitKind以后綴表 換算比例表的形式便捷實(shí)現(xiàn)UnitsFormat并支持canonical_index內(nèi)部存儲單位如弧度/display_index展示單位如度/editing_index編輯單位如 d三套索引分離見 number_input.rs。內(nèi)置了三組標(biāo)準(zhǔn)單位見 number_input.rs類型id典型后綴內(nèi)部規(guī)范單位Dimensionlessnone無—LengthMeterslength_metersm / km / cm / mm / ft / in / mi米TimeSecondstime_secondss / ks / cs / ms秒AngleDegreesangle_degreesrad / ° / d / deg弧度顯示為度有意思的細(xì)節(jié)角度單位內(nèi)部規(guī)范量是弧度但展示時(shí)輸出45°由于°不方便鍵入編輯模式會自動把內(nèi)容替換為45ddisplay_index與editing_index分離正是為此見 number_input.rs。scrubber_on_release在進(jìn)入編輯態(tài)前也會先把顯示文本替換為可編輯格式并在結(jié)束時(shí)換回展示格式見 number_input.rs。這些單位對象由UnitsRegistry資源集中管理NumberInputPlugin在Plugin::build時(shí)默認(rèn)注冊了上述四者并掛接兩個(gè)系統(tǒng)在PickingSystems::Last、InputFocusSystems::Dispatch之后同步滑軌配色見 number_input.rs。注冊表支持通過insert注入自定義單位見 number_input.rs。解析/格式化的正確性有單元測試兜底例如test_length_meters_convert_km_to_m1km → 1000m、test_angle_degrees_formatπ/4 rad → 45° / 編輯時(shí) 45d、test_parse_negative_numbers-50.5cm → -0.505m等見 number_input.rs。八、從零搭一個(gè)輸入框完整示例控件本身是一個(gè)可繼承的 Scene 組件#[derive(SceneComponent)]見 number_input.rs在 bsn 場景 DSL 中用FeathersNumberInput生成。倉庫中的feathers_number_input示例examples/ui/widgets/feathers_number_input.rs把各種配置組合平鋪展示節(jié)選如下fn demo_root() - impl Scene { bsn! { ... Children[ demo_field_f32(soft limit, 2.0, bsn!( SoftLimit(NumberInputRange::F32(0.0..10.0)) )), demo_field_f32(hard limit, 3.0, bsn!( HardLimit(NumberInputRange::F32(-100.0..100.0)) )), demo_field_f32(soft hard, 4.0, bsn!( SoftLimit(NumberInputRange::F32(0.0..10.0)) HardLimit(NumberInputRange::F32(-100.0..100.0)) )), demo_field_f32(precision(2), 6.0, bsn!( NumberInputPrecision(2) )), demo_field_f32(hard limit wrap, 0.0, bsn!( HardLimit(NumberInputRange::F32(-180.0..180.0)) NumberInputWrap::Wrap )), demo_field_f32(in meters, 2.0, bsn!( NumberInputUnits::new(LengthMeters) )), demo_field_f32(in degrees, PI, bsn!( NumberInputUnits::new(AngleDegrees) )), ] } } fn demo_field_f32(label_text: str, value: f32, options: impl Scene) - impl Scene { bsn! { ... Children [ ( FeathersNumberInput NumberInputValue::F32(value) {options} Node { flex_grow: 1.0, max_width: px(120) } on( |value_change: OnValueChangef32, mut commands: Commands| { commands.entity(value_change.event_target()) .insert(NumberInputValue::F32(value_change.value)); }) ), ] } }要點(diǎn)拆解FeathersNumberInput生成控件骨架其內(nèi)部結(jié)構(gòu)標(biāo)簽段、可編輯文本、透明 scrubber 層、左右 chevron由FeathersNumberInput::scene預(yù)置見 number_input.rsNumberInputValue::F32(value)直接設(shè)置初始值與數(shù)值格式可選行為組件SoftLimit、HardLimit、NumberInputPrecision、NumberInputStep、NumberInputWrap、NumberInputUnits、InteractionDisabled用{options}展開注入每個(gè)輸入框必須配套OnValueChangef32或?qū)?yīng)泛型處理器做受控回寫InteractionDisabled組件可讓控件進(jìn)入禁用態(tài)文本只讀、光標(biāo)變?yōu)镹otAllowed、滑軌與文字改用 disabled token相關(guān)邏輯見 number_input.rs。需要 f32 / i32 標(biāo)準(zhǔn)字段時(shí)也可以直接復(fù)用倉庫封裝好的 helper注意它們需要bevy_feathersfeature 開啟examples/helpers/number_input_f32.rs 提供number_input_f32(name, identifier, value, precision, limits)內(nèi)部組合了HardLimit::f32(limits)與可選標(biāo)識組件examples/helpers/number_input_i32.rs 提供number_input_i32(...)。標(biāo)識組件用來在多輸入框場景中區(qū)分事件來源——查詢哪個(gè)帶number_input_identifier的FeathersNumberInput是ValueChange的source實(shí)體即可。視覺定制sigil 與 label創(chuàng)建控件時(shí)還可通過FeathersNumberInputProps定制兩處外觀見 number_input.rssigil_color輸入框左側(cè)的一條彩色豎條默認(rèn)透明常用于區(qū)分不同坐標(biāo)軸如 X/Y/Z 分別用不同 token 著色示例中用的是tokens::TEXT_INPUT_X_AXISlabel_textsigil 右側(cè)的靜態(tài)說明文字慣例填 X / Y / Z帶 label 時(shí) sigil 會加寬為 4px 的左邊框。在 bsn 中使用 props 的寫法是屬性語法FeathersNumberInput { sigil_color: ..., label_text: X }見 examples/ui/widgets/feathers_number_input.rs。運(yùn)行示例在啟用bevy_feathersfeature 的前提下可用 cargo 直接運(yùn)行該示例cargo run --example feathers_number_input --features bevy/bevy_feathers具體 feature 名稱以倉庫 Cargo.toml 中的配置為準(zhǔn)。九、升級遷移用插入組件取代觸發(fā)事件如果你是從舊 API 遷移到本次重構(gòu)版本需要特別注意程序化更新數(shù)值的通道變了舊版本通過觸發(fā)UpdateNumberInput事件來更新值新版本改為插入NumberInputValue組件詳見 遷移指南。后者在創(chuàng)建時(shí)指定初始值也更容易// BEFORE舊 API已廢棄 commands.trigger(UpdateNumberInput { entity: input_ent, value: NumberInputValue::F32(new_value), }); // AFTER新 API commands .entity(input_ent) .insert(NumberInputValue::F32(new_value));其余不變事件處理器仍然監(jiān)聽ValueChangeTValueChange中is_final false拖拽中與 true提交的語義配合受控回寫可以實(shí)現(xiàn)拖拽實(shí)時(shí)預(yù)覽、松開才落庫的編輯器級體驗(yàn)。結(jié)語把本次發(fā)布說明與 number_input.rs 的實(shí)現(xiàn)對照來看FeathersNumberInput的交互模型可以概括為三句話可選組件決定能力限制/精度/步進(jìn)/單位/環(huán)繞有無SoftLimit決定觀感滑塊還是擦子受控回寫決定數(shù)據(jù)流事件外發(fā) 組件插入回流。借助0.5px的手勢閾值與EditMode狀態(tài)機(jī)點(diǎn)擊與拖拽被可靠區(qū)分借助啟發(fā)式拖拽速度與 Shift 微調(diào)從千分位小值到十萬級大值都能用一只手順滑調(diào)整。這套能力對需要高密度數(shù)值編輯的工具型 UI 非常實(shí)用值得在屬性面板、變換 gizmo 或參數(shù)化設(shè)置界面中優(yōu)先采用?！久赓M(fèi)下載鏈接】bevyA refreshingly simple>項(xiàng)目地址: https://gitcode.com/GitHub_Trending/be/bevy創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考