diff --git a/docs/engineering/a11y-safety.md b/docs/engineering/a11y-safety.md index 08e75ef8..93d0b3ad 100644 --- a/docs/engineering/a11y-safety.md +++ b/docs/engineering/a11y-safety.md @@ -22,6 +22,9 @@ - 鍵盤焦點:強烈靜態視覺回饋 (反轉、字體加粗)。 - 按壓狀態:獨立於焦點的第三層級。深色模式使用飽和暖色 (琥珀色 `255,200,120`),亮度差 **ΔL*≥13**。 - **Tritanopia 調整亮度公式**:$L_{tritan} = (R_{lin} \times 0.2126 + G_{lin} \times 0.7152) / 0.9278$。 + - **Dwell 與 Latest 交接**:共用眼動儀回饋按鈕使用 "FeedbackButton";回饋結束先還原 Color.Empty,再清除該按鈕的原生背景動畫快取,讓背景、文字與提示框於同一幀還原。不得為此切換 VisualStylesMode、重建 HWND 或改變版面。 + - 視窗未啟用時仍須保持懸停文字與背景成對,不以略過自訂回饋後交回原生懸停取代;這不應啟用視窗或移動焦點。 + - Dwell 更新在 UI 寫入前再次檢查動畫識別碼,避免過期更新重啟已結束的視覺。測試須涵蓋三種主題、啟用/未啟用視窗、預設/一般按鈕的整段過渡取樣,不能只檢查最後一幀。 - **預設動作引導**:當焦點在輸入框時,`AcceptButton` 必須顯示與焦點框一致的情境感知邊框色;強視覺反轉情境使用 **Cyan / MediumBlue**,中性情境使用 **LightBlue / MediumBlue**。 - 輸入框與預設動作提示須共用情境選色,並在輸入框底色/焦點變更時重繪。Latest 的強調色按鈕不得使提示對比下降;可在提示邊框緊鄰處繪製對比襯底,保留按鈕本體與原生主題外觀,不得改變尺寸、Margin 或 Padding。 - 測試須量測實際渲染的邊框與相鄰背景,不得只比對顏色名稱;同時覆蓋反轉及中性情境、三種主題與進度條主填色的對比。文件中對比數值為四捨五入顯示,不取代未取整的最低門檻。 diff --git a/src/InputBox/Core/Controls/FeedbackButton.cs b/src/InputBox/Core/Controls/FeedbackButton.cs new file mode 100644 index 00000000..64333378 --- /dev/null +++ b/src/InputBox/Core/Controls/FeedbackButton.cs @@ -0,0 +1,8 @@ +namespace InputBox.Core.Controls; + +/// 保留原生 Latest 外觀,並提供自訂回饋結束時的原生色彩快取重設。 +public class FeedbackButton : Button +{ + /// 透過 WinForms 既有主題刷新路徑終止舊色動畫,不改變樣式、HWND 或版面。 + internal void ResetNativeColorTransition() => base.OnSystemColorsChanged(EventArgs.Empty); +} \ No newline at end of file diff --git a/src/InputBox/Core/Controls/GamepadCalibrationDialog.cs b/src/InputBox/Core/Controls/GamepadCalibrationDialog.cs index 6efd013c..20fb41c6 100644 --- a/src/InputBox/Core/Controls/GamepadCalibrationDialog.cs +++ b/src/InputBox/Core/Controls/GamepadCalibrationDialog.cs @@ -383,7 +383,7 @@ private Button CreateEyeTrackerButton(string text, string accessibleName, string Font boldFont = MainForm.GetSharedA11yFont(DeviceDpi, FontStyle.Bold, font.FontFamily); Size boldTextSize = TextRenderer.MeasureText(text, boldFont); - Button btn = new() + Button btn = new FeedbackButton() { Text = text, AccessibleName = accessibleName, diff --git a/src/InputBox/Core/Controls/GamepadMessageBox.cs b/src/InputBox/Core/Controls/GamepadMessageBox.cs index 45c1a007..01ab3a01 100644 --- a/src/InputBox/Core/Controls/GamepadMessageBox.cs +++ b/src/InputBox/Core/Controls/GamepadMessageBox.cs @@ -421,7 +421,7 @@ private Button CreateEyeTrackerButton(string label) string description = StripMnemonic(label) ?? label; - Button btn = new() + Button btn = new FeedbackButton() { Text = label, AccessibleName = description, diff --git a/src/InputBox/Core/Controls/HelpDialog.cs b/src/InputBox/Core/Controls/HelpDialog.cs index 1bf373f3..da85c6ff 100644 --- a/src/InputBox/Core/Controls/HelpDialog.cs +++ b/src/InputBox/Core/Controls/HelpDialog.cs @@ -169,7 +169,7 @@ public HelpDialog() // profile 用來讓關閉按鈕與說明表的顯示文字跟著目前控制器模式同步。 GamepadFaceButtonProfile profile = GamepadFaceButtonProfile.GetActiveProfile(); - _btnClose = new Button() + _btnClose = new FeedbackButton() { Text = profile.FormatCancelButtonText(Strings.Help_Btn_Close), AutoSize = true, diff --git a/src/InputBox/Core/Controls/NumericInputDialog.cs b/src/InputBox/Core/Controls/NumericInputDialog.cs index 723d35d0..166dd77f 100644 --- a/src/InputBox/Core/Controls/NumericInputDialog.cs +++ b/src/InputBox/Core/Controls/NumericInputDialog.cs @@ -906,7 +906,7 @@ private Button CreateEyeTrackerButton( int baseMinWidth = Math.Max((int)(120 * scale), boldTextSize.Width + (int)(32 * scale)), baseMinHeight = Math.Max((int)(60 * scale), boldTextSize.Height + (int)(24 * scale)); - Button btn = new() + Button btn = new FeedbackButton() { Text = text, AccessibleName = text, diff --git a/src/InputBox/Core/Controls/PhraseEditDialog.cs b/src/InputBox/Core/Controls/PhraseEditDialog.cs index 668e910e..4b6ba881 100644 --- a/src/InputBox/Core/Controls/PhraseEditDialog.cs +++ b/src/InputBox/Core/Controls/PhraseEditDialog.cs @@ -334,7 +334,7 @@ public PhraseEditDialog(string name, string content, Font? a11yFont) // profile 用於同步片語編輯對話框中的確認/取消按鈕提示與目前控制器配置。 GamepadFaceButtonProfile profile = GamepadFaceButtonProfile.GetActiveProfile(); - _btnCancel = new Button() + _btnCancel = new FeedbackButton() { Text = profile.FormatCancelButtonText(Strings.Phrase_Btn_Cancel), AutoSize = true, @@ -350,7 +350,7 @@ public PhraseEditDialog(string name, string content, Font? a11yFont) }; _btnCancel.FlatAppearance.BorderSize = 0; - _btnOk = new Button() + _btnOk = new FeedbackButton() { Text = profile.FormatConfirmButtonText(Strings.Phrase_Btn_Confirm), AutoSize = true, diff --git a/src/InputBox/Core/Controls/PhraseManagerDialog.Layout.cs b/src/InputBox/Core/Controls/PhraseManagerDialog.Layout.cs index 518ae979..fb4bde54 100644 --- a/src/InputBox/Core/Controls/PhraseManagerDialog.Layout.cs +++ b/src/InputBox/Core/Controls/PhraseManagerDialog.Layout.cs @@ -123,7 +123,7 @@ private static Button CreateActionButton( string a11yDesc, char mnemonic) { - Button btn = new() + Button btn = new FeedbackButton() { Text = ControlExtensions.GetMnemonicText(text, mnemonic), AutoSize = true, diff --git a/src/InputBox/Core/Controls/PhraseManagerDialog.cs b/src/InputBox/Core/Controls/PhraseManagerDialog.cs index 77350d88..5126f728 100644 --- a/src/InputBox/Core/Controls/PhraseManagerDialog.cs +++ b/src/InputBox/Core/Controls/PhraseManagerDialog.cs @@ -356,7 +356,7 @@ public PhraseManagerDialog(PhraseService phraseService) _tlpMain.Controls.Add(_flpButtons, 1, 0); // 底部關閉按鈕。 - _btnClose = new Button() + _btnClose = new FeedbackButton() { Text = profile.FormatCancelButtonText(Strings.Phrase_Btn_Close), AutoSize = true, diff --git a/src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs b/src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs index 1f6cfd35..8d7470b4 100644 --- a/src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs +++ b/src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs @@ -1,4 +1,5 @@ using InputBox.Core.Configuration; +using InputBox.Core.Controls; using InputBox.Resources; using System.Diagnostics; using System.Drawing.Drawing2D; @@ -44,6 +45,9 @@ private sealed class ButtonVisualState /// public long AnimId; + /// 重設原生色彩快取期間避免系統色事件重入。 + public bool IsResettingNativeColors { get; set; } + /// /// 基礎無障礙描述,供不同互動狀態下的 AccessibleDescription 組合使用 /// @@ -168,7 +172,8 @@ private static void HandleButtonKeyUp(object? sender, KeyEventArgs eventArgs) /// private static void HandleButtonSystemColorsChanged(object? sender, EventArgs eventArgs) { - if (sender is Button { IsDisposed: false } button) + if (sender is Button { IsDisposed: false } button && + _buttonStates.TryGetValue(button, out ButtonVisualState? state) && !state.IsResettingNativeColors) { StopFeedback(button); } @@ -296,11 +301,6 @@ private static void HandleButtonMouseEnter(object? sender, EventArgs eventArgs) { if (sender is Button btn) { - if (Form.ActiveForm != btn.FindForm()) - { - return; - } - if (_buttonStates.TryGetValue(btn, out ButtonVisualState? state)) { state.IsHovered = true; @@ -493,7 +493,13 @@ private static void StartAnimationFeedback(Button btn) btn.RunDwellAnimationAsync( id: currentId, animationIdGetter: () => Interlocked.Read(ref st.AnimId), - progressSetter: p => st.DwellProgress = p, + progressSetter: p => + { + if (Interlocked.Read(ref st.AnimId) == currentId) + { + st.DwellProgress = p; + } + }, durationMs: 1000, ct: st.FormCt ).SafeFireAndForget(); @@ -542,9 +548,31 @@ private static void StopFeedback(Button btn) btn.AccessibleDescription = st.BaseDescription; btn.Padding = st.OriginalPadding; + ResetNativeColors(btn, st); btn.Invalidate(); } + /// + /// 使用自家按鈕的框架主題刷新路徑清除原生動畫快取;不改主題、尺寸或焦點。 + /// Color.Empty 已先還原,因此下一幀直接以 Latest 的目前原生配色繪製。 + /// + private static void ResetNativeColors(Button button, ButtonVisualState state) + { + if (button is not FeedbackButton feedbackButton || button.IsDisposed || state.IsResettingNativeColors) + { + return; + } + + state.IsResettingNativeColors = true; + try + { + feedbackButton.ResetNativeColorTransition(); + } + finally + { + state.IsResettingNativeColors = false; + } + } /// /// 為現有文字按鈕繪製一致的互動配色,不受 Net11 預設動作強調色覆蓋。 /// diff --git a/src/InputBox/MainForm.Designer.cs b/src/InputBox/MainForm.Designer.cs index 33b09a4f..03548343 100644 --- a/src/InputBox/MainForm.Designer.cs +++ b/src/InputBox/MainForm.Designer.cs @@ -32,7 +32,7 @@ private void InitializeComponent() TLPHost = new TableLayoutPanel(); PInputHost = new Panel(); TBInput = new TextBox(); - BtnCopy = new Button(); + BtnCopy = new InputBox.Core.Controls.FeedbackButton(); TLPHost.SuspendLayout(); PInputHost.SuspendLayout(); SuspendLayout(); diff --git a/tests/InputBox.Tests/ButtonFeedbackRenderingTests.cs b/tests/InputBox.Tests/ButtonFeedbackRenderingTests.cs index 753afc1d..49a22d93 100644 --- a/tests/InputBox.Tests/ButtonFeedbackRenderingTests.cs +++ b/tests/InputBox.Tests/ButtonFeedbackRenderingTests.cs @@ -1,4 +1,5 @@ using InputBox.Core.Extensions; +using InputBox.Core.Interop; using System.Reflection; using System.Runtime.ExceptionServices; using Xunit; @@ -412,6 +413,134 @@ private static double LinearComponent(byte component) double value = component / 255.0; return value <= 0.04045 ? value / 12.92 : Math.Pow((value + 0.055) / 1.055, 2.4); } + /// 逐幀檢查 Dwell 進出與未啟用視窗的配色,不能只等原生動畫完成再驗證。 + [Theory(Skip = "Requires explicit UI test opt-in.", + SkipUnless = nameof(UiSmokeTestRequirements.IsEnabled), SkipType = typeof(UiSmokeTestRequirements))] + [InlineData(true, true)] + [InlineData(true, false)] + [InlineData(false, true)] + [InlineData(false, false)] + public void Render_DwellHandoff_PreservesEveryFrame(bool isDefault, bool active) + { + RunSta(() => + { + using var form = new Form { ClientSize = new Size(300, 200), TopMost = true }; + using var input = new TextBox { Top = 150 }; + using var button = new FeedbackButton + { + Text = "Button text", Bounds = new Rectangle(10, 30, 240, 90), + FlatStyle = FlatStyle.Flat, VisualStylesMode = VisualStylesMode.Latest + }; + using var lifetime = new CancellationTokenSource(); + form.Controls.AddRange([input, button]); + button.AttachEyeTrackerFeedback("Button", button.Font, null, lifetime.Token); + if (isDefault) + { + form.AcceptButton = button; + } + Exception? frameFailure = null; + form.Shown += (_, _) => + { + try + { + form.Activate(); + input.Focus(); + using var other = new Form { Location = new Point(850, 500), Size = new Size(100, 80) }; + if (!active) + { + other.Show(); + other.Activate(); + } + Form target = active ? form : other; + _ = User32.ShowWindow(target.Handle, User32.ShowWindowCommand.Restore); + _ = User32.SetForegroundWindow(target.Handle); + target.Activate(); + Settle(500); + if (active) + { + Assert.Same(form, Form.ActiveForm); + } + else + { + Assert.NotSame(form, Form.ActiveForm); + } + using var expected = new Bitmap(button.Width, button.Height); + button.DrawToBitmap(expected, button.ClientRectangle); + Color neutralBack = expected.GetPixel(25, 20); + Color neutralBorder = expected.GetPixel(2, 20); + Size size = button.Size; + Padding padding = button.Padding; + nint handle = button.Handle; + button.EnterHover(); + for (int i = 0; i < 25; i++) + { + Settle(16); + using var hover = new Bitmap(button.Width, button.Height); + button.DrawToBitmap(hover, button.ClientRectangle); + Assert.Equal(button.BackColor.ToArgb(), hover.GetPixel(25, 20).ToArgb()); + Assert.True(Contrast(hover.GetPixel(25, 20), button.ForeColor) >= 4.5); + int ink = 0; + for (int y = 25; y < 65; y++) + { + for (int x = 35; x < 205; x++) + { + if (hover.GetPixel(x, y).ToArgb() == button.ForeColor.ToArgb()) + { + ink++; + } + } + } + Assert.True(ink > 10, "懸停文字未以配對前景色繪製。"); + Assert.True(Contrast(hover.GetPixel(2, 20), hover.GetPixel(0, 20)) >= 3); + } + button.ExitHover(); + for (int i = 0; i < 40; i++) + { + Application.DoEvents(); + using var frame = new Bitmap(button.Width, button.Height); + button.DrawToBitmap(frame, button.ClientRectangle); + Assert.True(neutralBack.ToArgb() == frame.GetPixel(25, 20).ToArgb(), $"frame={i}; expected={neutralBack}; actual={frame.GetPixel(25, 20)}; back={button.BackColor}; fore={button.ForeColor}; active={form.ActiveControl?.GetType().Name}; default={button.NativeDefault}"); + Assert.Equal(neutralBorder.ToArgb(), frame.GetPixel(2, 20).ToArgb()); + CheckNeutralRendering(button, isDefault); + if (isDefault) + { + Assert.True(Contrast(frame.GetPixel(2, 20), frame.GetPixel(0, 20)) >= 3); + } + Assert.Equal(size, button.Size); + Assert.Equal(padding, button.Padding); + Assert.Equal(handle, button.Handle); + Assert.False(button.Focused); + Settle(16); + } + lifetime.Cancel(); + other.Close(); + } + catch (Exception ex) + { + frameFailure = ex; + } + finally + { + form.Close(); + } + }; + Application.Run(form); + if (frameFailure != null) + { + ExceptionDispatchInfo.Capture(frameFailure).Throw(); + } + }); + + static void Settle(int milliseconds) + { + long start = Environment.TickCount64; + do + { + Application.DoEvents(); + Thread.Sleep(1); + } while (Environment.TickCount64 - start < milliseconds); + } + } /// /// 以 WCAG 相對亮度檢查實際文字與背景的對比,不以色彩名稱推測可讀性。 /// @@ -458,9 +587,10 @@ private static void RunSta(Action action) /// /// 僅在測試控制項本身觸發事件,不向任何其他視窗模擬輸入。 /// - private sealed class FeedbackButton : Button + private sealed class FeedbackButton : InputBox.Core.Controls.FeedbackButton { public VisualStylesMode ResolvedMode => EffectiveVisualStylesMode; + public bool NativeDefault => IsDefault; public void Hover() { // 僅驗證繪製:不依賴 Windows 是否允許測試主機搶到前景。 @@ -482,6 +612,7 @@ public void SetProgress(float progress) public void ReleaseSpace() => OnKeyUp(new KeyEventArgs(Keys.Space)); public void RefreshSystemColors() => OnSystemColorsChanged(EventArgs.Empty); public void Press() => OnMouseDown(new MouseEventArgs(MouseButtons.Left, 1, 0, 0, 0)); + public void EnterHover() => OnMouseEnter(EventArgs.Empty); public void ExitHover() => OnMouseLeave(EventArgs.Empty); } } \ No newline at end of file diff --git a/tests/InputBox.Tests/README.md b/tests/InputBox.Tests/README.md index 537940c0..b6112f03 100644 --- a/tests/InputBox.Tests/README.md +++ b/tests/InputBox.Tests/README.md @@ -50,9 +50,9 @@ | `TextBoxSelectionExtensionsTests` | 右搖桿延伸選取共用的 `ResolveSelectionAnchor` 錨點解析(無選取、正向、反向、錨點失效)與 `GetWordJumpTarget` 單字跳轉目標(不改變目前選取、方向與邊界);原本三處複本集中後的一致性保護 | 6 | | `VibrationPatternsTests` | `VibrationPatterns` 與方向性震動設定、語意情境解析、能力感知的多段式微震動序列,以及歷程滾輪阻尼感、字數上限硬牆、震動強度預覽、右搖桿選取粒度、組合鍵進入提示與喚起握手回饋的回歸保護 | 37 | | `VibrationSafetyLimiterTests` | `VibrationSafetyLimiter` 熱保護、Duty Cycle 限制器與極端邊界保護;馬達數量熱成本倍率正規化,以及所有內建震動模式在冷啟動下不得被拒絕、單次超出預算改為降強度,以及Critical 自動連發(含不同模式交錯)降級、熱負載不失控,以及冷啟動短序列仍完整送出的回歸保護 | 20 | -| `ButtonFeedbackRenderingTests` | Latest 預設/一般按鈕實際文字與背景、焦點/預設動作同步及對比襯底、四種底色進度條與色覺紋理、粗體、按下亮度差、零抖動與配色還原、焦點懸停組合、Space 按放/失焦及空文字反例 | 23 | +| `ButtonFeedbackRenderingTests` | Latest 預設/一般按鈕實際文字與背景、焦點/預設動作同步及對比襯底、四種底色進度條與色覺紋理、粗體、按下亮度差、零抖動與配色還原、焦點懸停組合、Space 按放/失焦、空文字反例與 Dwell 交接逐幀對比 | 27 | | `BlinkFrameRenderingTests` | 實際螢幕非客戶區像素:Blink 完成/取消、有/無焦點還原;HWND、選取範圍及尺寸不變 | 4 | -| **合計** | | **494** | +| **合計** | | **498** | ## 二、執行方式 🚀 @@ -181,7 +181,7 @@ UI 測試宿主在啟動 UIA 前使用 Application.SetHighDpiMode(PerMonitorV2) ## .NET 11 Latest 按鈕配色回歸(2026-11-14) -`ButtonFeedbackRenderingTests` 是需 `INPUTBOX_RUN_UI_TESTS=1` 才執行的 23 項 UI 測試。它以實際點陣圖檢查預設/一般按鈕的焦點、懸停、按下背景、文字及焦點邊框,並檢查文字對比至少 4.5:1、尺寸/內距不變,以及回饋結束後的一般/停用外觀。停用狀態只檢查文字仍可辨識,不套用一般可操作文字的 4.5:1 門檻。 +`ButtonFeedbackRenderingTests` 是需 `INPUTBOX_RUN_UI_TESTS=1` 才執行的 27 項 UI 測試。它以實際點陣圖檢查預設/一般按鈕的焦點、懸停、按下背景、文字及焦點邊框,並檢查文字對比至少 4.5:1、尺寸/內距不變,以及回饋結束後的一般/停用外觀。停用狀態只檢查文字仍可辨識,不套用一般可操作文字的 4.5:1 門檻。 以獨立測試程序分別執行淺色與深色(測試主機設定 `INPUTBOX_BUTTON_TEST_DARK=1`);高對比必須實際啟用 Windows 高對比,並在驗證後還原。`Latest` 在高對比下由框架解析為 `Classic`,測試保留此無障礙行為。這些測試只改變測試控制項的狀態,不向其他視窗送出模擬輸入。`INPUTBOX_BUTTON_ARTIFACTS` 可指定點陣圖輸出目錄。 @@ -208,3 +208,10 @@ PR #92 審查補強:重新套色時保留焦點與懸停組合,Space 與滑 Blink 非客戶區殘框修正:.NET 11 Latest 文字框在警示中重繪非客戶區後,僅還原 BackColor/ForeColor 不會清除舊框色;還原配色與焦點提示後明確重繪框架及子控制項,保留 HWND、選取範圍、尺寸與焦點。新增 4 項完成/取消及有/無焦點的實際螢幕像素測試。v0.0.69、原版 v0.0.71 與本機修正版在 125%/120 DPI 下完成淺色、深色、高對比的 Blink 前/中/後截圖;一般主題原版 v0.0.71 殘留 2517 個警示色像素,v0.0.69 與修正版均為 0。高對比三組均正常,驗證後還原系統設定。 本輪驗證:三種主題新增測試各 4/4,完整 UI 38/38、非 UI 456/456;Release -warnaserror 建置 0 警告/0 錯誤;修改 C# 的 severity info style/analyzers 報告皆為空。非客戶區繪製參考:[.NET 11 TextBoxBase](https://github.com/dotnet/winforms/blob/v11.0.0/src/System.Windows.Forms/System/Windows/Forms/Controls/TextBox/TextBoxBase.cs)。 + + +Dwell/Latest 交接:所有共用回饋按鈕改用 FeedbackButton,在還原 Color.Empty 後透過框架的受保護主題刷新路徑清除舊背景動畫,不切換 VisualStylesMode、不重建 HWND。視窗未啟用時也套用成對懸停配色;動畫識別碼在寫入進度前再次驗證,防止過期 UI 更新重新啟用已結束的回饋。 + +新增四組逐幀測試:預設/一般 Flat 按鈕 × 啟用/未啟用視窗。每組檢查 25 個懸停樣本及還原後 40 個樣本(約每 16ms),以實際渲染文字、背景及提示邊框驗證文字至少 4.5:1、互動提示至少 3:1;還原首幀即須符合原生穩定底色與提示邊框,並保留尺寸、Padding、HWND 與按鈕焦點狀態。測試明確驗證視窗啟用狀態,因此需在可顯示視窗的測試程序執行;不能以未取得前景的執行結果宣稱啟用情境通過。 + +最終驗證:完整非 UI 456/456、UI 42/42;淺色、深色及實際 Windows 高對比各 27/27;暫時略過原生快取重設時,新增四組逐幀測試均失敗,恢復修正後通過。高對比設定已還原。Release -warnaserror 建置 0 警告/0 錯誤;所有修改 C# 的 severity info style/analyzers 報告均為空。