2121/// 但没有声音),这与「默认出声,否则用户会以为 TTS 坏了」的意图直接冲突。
2222/// 所以同时挂两条路径:指针 + `HardwareKeyboard` 全局处理器。
2323///
24+ /// # 压在舞台上的控件必须垫指针垫层(2026-09-11 修)
25+ ///
26+ /// 舞台是 `<iframe>` 平台视图:它在 DOM 里排在 Flutter 画布**之上**,而画布是
27+ /// `pointer-events: none` 。指针落在舞台区域时会进 **iframe 自己的文档**,父页
28+ /// (Flutter)一个都收不到——于是所有压在舞台上的 Flutter 控件都是
29+ /// **「看得见、点不着、也滑不动」**:设置面板整块(medium 下几乎全在舞台上方)、
30+ /// 断线横幅的「点此重试」、舞台右下角的缩放四键、错误覆盖层的「重试」。
31+ ///
32+ /// 修法:给它们套一层 [StagePointerInterceptor] (原理见其头注)。
33+ /// **以后新增任何压在舞台上的可交互控件,都要照做。**
34+ ///
35+ /// # 左侧不再有分区 rail(2026-09-11 用户裁决)
36+ ///
37+ /// 用户:「把左边的这些设置一级选项去掉留给舞台」。于是 `SectionRail` 整个删除,
38+ /// 那一列 168 px 全部还给舞台。导航不再有第二个入口:
39+ ///
40+ /// - 入口只有**一处**:非 compact 是 AppBar 的「设置」按钮,compact 是聊天面板头;
41+ /// - 分区切换在**面板内部**(`SettingsScaffold` 的 chip 行)——它本来就是导航的真身,
42+ /// rail 只是它的副本(同一个 `sectionNotifier` 驱动的第二处渲染)。
43+ ///
44+ /// 顺带删掉的行为:以前「再点一次 rail 上同一个分区」会收起侧板。现在收起只有
45+ /// **✕ / Esc**(`showModalBottomSheet` 另有自带的关闭手势)。
46+ ///
2447/// # 诚实记录的偏离:内联侧板不实现「点空白关闭」
2548///
26- /// 规格 §4.2 写的是「可 Esc / 点空白关闭」。内联侧板浮在**舞台列**之上 ,
27- /// 而舞台是 iframe 平台视图——**平台视图会先吃掉指针事件**,铺在下层的
28- /// 点击捕获区拿不到舞台区域的点击。能拿到的只有少量 Flutter 绘制的空隙,
29- /// 那不足以称为「点空白关闭」。因此实际提供三条关闭路径:
30- /// **Esc / 侧板右上角 ✕ / 再点一次 rail 上的同一个分区(切换语义)** 。
49+ /// 规格 §4.2 写的是「可 Esc / 点空白关闭」。垫层只罩得住**它包起来的那个盒子** ,
50+ /// 而「点空白关闭」要求整块舞台都接得住点击——那得在设置打开期间把整个舞台铺一层
51+ /// 遮挡,代价是「设置开着时还能拖模型」(渲染面 `sync.clickEnabled` 的真实交互)
52+ /// 一起没了。两害相权,先不铺。因此收起路径是**✕ / Esc**;
53+ /// `showModalBottomSheet` 自带的模态障碍层同理,在舞台区域不生效 。
3154library ;
3255
3356import 'dart:async' ;
@@ -41,6 +64,7 @@ import '../design/breakpoints.dart';
4164import '../design/tokens.dart' ;
4265import '../settings/settings_sections.dart' ;
4366import '../live2d/live2d_bridge.dart' ;
67+ import '../live2d/stage_pointer_interceptor.dart' ;
4468import '../state/ui_phase.dart' ;
4569import '../ui/chat_panel.dart' ;
4670import '../ui/connection_badge.dart' ;
@@ -281,15 +305,13 @@ class AppShellState extends State<AppShell> {
281305 widget.onSectionChanged? .call (section);
282306 }
283307
284- /// rail / 齿轮 / 抽屉 → 打开设置。
308+ /// 「设置」按钮 / compact 聊天面板头的入口 → 打开设置。
285309 ///
286310 /// 三种断点的分流就在这里(也是唯一的入口):
287311 /// - expanded:内联侧板(纯 `setState` ,不开路由);
288312 /// - medium:底部浮层;
289313 /// - compact:抽屉(第 1 层)→ 底部浮层(第 2 层)。
290314 ///
291- /// 再点一次 rail 上**同一个**分区 = 收起内联侧板(切换语义)。
292- ///
293315 /// # 打开之前必须先让宿主**加载当前分区的内容**(2026-09-11 修)
294316 ///
295317 /// 分区内容是由宿主按需加载的(`SettingsController.load()` ),而这里过去
@@ -300,14 +322,13 @@ class AppShellState extends State<AppShell> {
300322 ///
301323 /// 所以加载**不能**挂在「分区变了」上(那是结果,不是原因)——
302324 /// 「打开设置」本身就是那个原因。
303- Future <void > openSettings ({SizeClass ? sizeClass, bool toggle = false }) async {
325+ Future <void > openSettings ({SizeClass ? sizeClass}) async {
304326 final SizeClass sc =
305327 sizeClass ?? Breakpoints .sizeClassOf (MediaQuery .sizeOf (context).width);
306328
307329 if (settingsHostOf (sc) == SettingsHost .inline) {
308- setState (() => settingsOpen = toggle ? ! settingsOpen : true );
309- // 收起时不必加载(把网络请求省下来)。
310- if (settingsOpen) widget.onEnsureSectionLoaded? .call ();
330+ setState (() => settingsOpen = true );
331+ widget.onEnsureSectionLoaded? .call ();
311332 return ;
312333 }
313334
@@ -329,8 +350,13 @@ class AppShellState extends State<AppShell> {
329350 sizeClass: sc,
330351 // 用**浮层自己的** context 关掉自己:用外壳的 context 去 `maybePop`
331352 // 依赖「浮层恰好是栈顶」这个巧合,不稳健。
332- builder: (BuildContext sheetContext) => _settingsSurface (
333- onClose: () => Navigator .of (sheetContext).pop (),
353+ //
354+ // 浮层压在舞台上(medium 下几乎整块)⇒ 必须垫指针垫层,
355+ // 否则整块设置面板「看得见、点不着、也滑不动」。
356+ builder: (BuildContext sheetContext) => StagePointerInterceptor (
357+ child: _settingsSurface (
358+ onClose: () => Navigator .of (sheetContext).pop (),
359+ ),
334360 ),
335361 );
336362 }
@@ -419,9 +445,13 @@ class AppShellState extends State<AppShell> {
419445 top: 0 ,
420446 left: 0 ,
421447 right: 0 ,
422- child: OfflineBanner (
423- status: widget.wsStatus,
424- onRetry: widget.onRetryConnection,
448+ // 横幅压在舞台顶端:不垫一层指针垫层的话「点此重试」
449+ // 点不着(2026-09-11 之前一直是这样)。
450+ child: StagePointerInterceptor (
451+ child: OfflineBanner (
452+ status: widget.wsStatus,
453+ onRetry: widget.onRetryConnection,
454+ ),
425455 ),
426456 ),
427457 if (settingsOpen && inlineSettings)
@@ -432,11 +462,14 @@ class AppShellState extends State<AppShell> {
432462 ),
433463 ),
434464 // 舞台浮标:**压在舞台之上**,不占布局、不挤舞台宽度。
465+ // 压着 iframe 就必须垫指针垫层,否则四键全点不着。
435466 if (widget.stageCorner != null )
436467 Positioned (
437468 right: 0 ,
438469 bottom: 0 ,
439- child: widget.stageCorner! ,
470+ child: StagePointerInterceptor (
471+ child: widget.stageCorner! ,
472+ ),
440473 ),
441474 ],
442475 ),
@@ -485,7 +518,7 @@ class AppShellState extends State<AppShell> {
485518 const SizedBox (width: Space .s2),
486519 ],
487520 ),
488- body: compact ? body : _withRail (sizeClass, body) ,
521+ body: body,
489522 );
490523
491524 // 快捷键挂在**根**(`CallbackShortcuts` 最省样板,且不吞未匹配的键)。
@@ -503,39 +536,6 @@ class AppShellState extends State<AppShell> {
503536 );
504537 }
505538
506- /// medium / expanded 的左侧分区导航(**纯文字**)。
507- ///
508- /// # 为什么不用 `NavigationRail`
509- ///
510- /// `NavigationRail` 的两档形态(80 px 只放图标 / 232 px 图标 + 文字)都成立
511- /// 在一个前提上:**图标是主要识别通道**。用户裁决「尽量少用图片,用文字
512- /// 做按钮」之后这个前提没了,于是两档并一档——一个能放下四个汉字的宽度。
513- ///
514- /// 选中态用**实色底 + 左侧 2 px 竖条**,不靠图标变色:
515- /// 竖向标记在中文标签旁边比「图标变蓝」更好认,也是文字型导航的常规做法。
516- Widget _withRail (SizeClass sizeClass, Widget body) {
517- return Row (
518- children: < Widget > [
519- ValueListenableBuilder <SettingsSection >(
520- valueListenable: sectionNotifier,
521- builder: (BuildContext context, SettingsSection current, Widget ? _) =>
522- SectionRail (
523- sections: widget.sections,
524- selected: current,
525- onSelect: (SettingsSection picked) {
526- // 已选中同一个分区且侧板开着 → 收起(切换语义)。
527- final bool toggle = picked == current;
528- if (picked != current) _selectGuarded (picked);
529- openSettings (sizeClass: sizeClass, toggle: toggle);
530- },
531- ),
532- ),
533- VerticalDivider (width: 1 , color: appColorsOf (context).hairline),
534- Expanded (child: body),
535- ],
536- );
537- }
538-
539539 Widget _chat ({required bool compact}) => ChatPanel (
540540 messages: widget.messages,
541541 phase: widget.phase,
@@ -558,135 +558,6 @@ class AppShellState extends State<AppShell> {
558558 );
559559}
560560
561- /// 左侧分区导航:**一列文字**。
562- ///
563- /// 刻意做得很薄:这里不需要「图标 + 徽标 + 折叠」那一套,
564- /// 它只是把 8 个中文标签竖着排好,并让当前项一眼可辨。
565- class SectionRail extends StatelessWidget {
566- const SectionRail ({
567- required this .sections,
568- required this .selected,
569- required this .onSelect,
570- super .key,
571- });
572-
573- final List <SettingsSection > sections;
574- final SettingsSection selected;
575- final ValueChanged <SettingsSection > onSelect;
576-
577- @override
578- Widget build (BuildContext context) {
579- final ThemeData theme = Theme .of (context);
580- final AppColors colors = appColorsOf (context);
581- final AppPalette palette = appPaletteOf (context);
582- return SizedBox (
583- width: NavMetrics .railWidth,
584- child: ListView (
585- padding: const EdgeInsets .symmetric (vertical: Space .s2),
586- children: < Widget > [
587- for (final SettingsSection section in sections)
588- _RailItem (
589- label: section.label,
590- description: section.description,
591- selected: section == selected,
592- onTap: () => onSelect (section),
593- theme: theme,
594- colors: colors,
595- palette: palette,
596- ),
597- ],
598- ),
599- );
600- }
601- }
602-
603- class _RailItem extends StatelessWidget {
604- const _RailItem ({
605- required this .label,
606- required this .description,
607- required this .selected,
608- required this .onTap,
609- required this .theme,
610- required this .colors,
611- required this .palette,
612- });
613-
614- final String label;
615- final String description;
616- final bool selected;
617- final VoidCallback onTap;
618- final ThemeData theme;
619- final AppColors colors;
620- final AppPalette palette;
621-
622- @override
623- Widget build (BuildContext context) {
624- return Padding (
625- padding: const EdgeInsets .symmetric (
626- horizontal: Space .s2,
627- vertical: 1 ,
628- ),
629- child: Semantics (
630- button: true ,
631- selected: selected,
632- label: label,
633- // 说明只给读屏/悬停:竖排里塞两行说明会把 8 个分区撑到放不下。
634- hint: description,
635- excludeSemantics: true ,
636- child: Tooltip (
637- message: description,
638- child: InkWell (
639- onTap: onTap,
640- borderRadius: BorderRadius .circular (AppRadius .sm),
641- child: DecoratedBox (
642- decoration: BoxDecoration (
643- color: selected ? palette.surfaceAlt : Colors .transparent,
644- borderRadius: BorderRadius .circular (AppRadius .sm),
645- ),
646- child: Padding (
647- padding: const EdgeInsets .symmetric (
648- horizontal: Space .s2,
649- vertical: Space .s2,
650- ),
651- child: Row (
652- children: < Widget > [
653- // 选中竖条:**形状**通道,不只靠底色深浅。
654- Container (
655- width: 2 ,
656- height: 14 ,
657- decoration: BoxDecoration (
658- color: selected ? palette.accent : Colors .transparent,
659- // `xs`(最小合法档)而不是更小的裸值:2 px 宽的竖条上
660- // 圆角会被 Flutter 夹到半宽,两档看起来是同一条圆头,
661- // 那就没有理由为它开一个裸值。
662- borderRadius: BorderRadius .circular (AppRadius .xs),
663- ),
664- ),
665- const SizedBox (width: Space .s2),
666- Expanded (
667- child: Text (
668- label,
669- maxLines: 1 ,
670- overflow: TextOverflow .ellipsis,
671- style: theme.textTheme.labelLarge? .copyWith (
672- color: selected ? palette.ink : colors.contentMuted,
673- fontWeight: selected
674- ? FontWeight .w600
675- : FontWeight .w500,
676- ),
677- ),
678- ),
679- ],
680- ),
681- ),
682- ),
683- ),
684- ),
685- ),
686- );
687- }
688- }
689-
690561/// 一个**永不通知**的 [Listenable] 。
691562///
692563/// 只在宿主没接 `settingsChanges` 时当占位(测试里常见)。
0 commit comments