♻️ refactor(vscode): 代码阅读不再在页面里拦 ⌘↓ / ⌘↑，快捷键只在「键盘快捷方式」里绑；跳到下一处时把浏览器自己的滚动拉回来，页面不再先滚到底

vscode/webview-ui/src/codeReader/occurrences.test.ts

@@ -1,12 +1,12 @@
 import type { Click, Highlight } from './occurrences'
-import type { BlockView, Inline, KeyCombo, Occurrence, PreviewText, PropertyItem, Segment, WebviewToExtension } from './types'
+import type { BlockView, Inline, Occurrence, PreviewText, PropertyItem, Segment, WebviewToExtension } from './types'
 import { describe, expect, it } from 'vitest'
 import { toBlockViews } from '../../../src/codeReader/blockView'
 import { createPythonAdapter } from '../../../src/codeReader/languages/python'
 import { WASM_DIR, withBlocks } from '../../../src/codeReader/testSupport'
 import { pythonZhTranslator } from '../../../src/codeReader/translators/pythonZh'
 import { DefinitionLinks } from './definitionLinks'
-import { clickAction, isCurrent, matchesKey, occurrenceCount, OccurrenceHighlight, OccurrenceNavigation, occurrenceStyle, segmentOccurrence, stepIndex } from './occurrences'
+import { clickAction, isCurrent, KEY_SCROLL_MS, KEY_TO_COMMAND_MS, KeyScroll, occurrenceCount, OccurrenceHighlight, OccurrenceNavigation, occurrenceStyle, segmentOccurrence, stepIndex } from './occurrences'
 
 function name(text: string, offset: number): Segment {
   return { text, role: 'variable', offset }
@@ -310,20 +310,43 @@ describe('occurrences：用键盘在各处出现之间跳', () => {
     expect(reports()).toEqual([false, true, false, true, false])
   })
 
-  it('命令绑的键：能跳时拦下浏览器的默认动作（⌘↓ 滚到底），不能跳、别的键、修饰键对不上都不拦', () => {
-    const keys: KeyCombo[] = [{ key: 'ArrowDown', ctrl: false, shift: false, alt: false, meta: true }, { key: 'j', ctrl: true, shift: false, alt: false, meta: false }]
-    const press = (key: string, modifiers: Partial<Record<'ctrlKey' | 'shiftKey' | 'altKey' | 'metaKey', boolean>> = {}): Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'shiftKey' | 'altKey' | 'metaKey'> =>
-      ({ key, ctrlKey: false, shiftKey: false, altKey: false, metaKey: false, ...modifiers })
-    const navigation = new OccurrenceNavigation(() => {}, { focused: true, typing: false })
-    expect(navigation.blocks(press('ArrowDown', { metaKey: true }), keys)).toBe(false)
-    navigation.update({ highlighted: true })
-    expect(navigation.blocks(press('ArrowDown', { metaKey: true }), keys)).toBe(true)
-    expect(navigation.blocks(press('J', { ctrlKey: true }), keys)).toBe(true)
-    expect(navigation.blocks(press('ArrowDown', { metaKey: true, shiftKey: true }), keys)).toBe(false)
-    expect(navigation.blocks(press('ArrowDown'), keys)).toBe(false)
-    expect(navigation.blocks(press('ArrowUp', { metaKey: true }), keys)).toBe(false)
-    navigation.update({ typing: true })
-    expect(navigation.blocks(press('ArrowDown', { metaKey: true }), keys)).toBe(false)
-    expect(matchesKey(press('ArrowDown', { metaKey: true }), keys[0])).toBe(true)
+  it('不拦任何键：跳转发来时回到刚按键那一刻的位置（只回一次），隔太久、点过鼠标、没按过键（命令面板）不回', () => {
+    const scroll = new KeyScroll()
+    expect(scroll.take(100)).toBeUndefined()
+    scroll.press({ x: 0, y: 40 }, 1000)
+    expect(scroll.take(1012)).toEqual({ x: 0, y: 40 })
+    expect(scroll.take(1013)).toBeUndefined()
+    scroll.press({ x: 0, y: 40 }, 2000)
+    expect(scroll.take(2000 + KEY_TO_COMMAND_MS + 1)).toBeUndefined()
+    scroll.press({ x: 0, y: 40 }, 3000)
+    scroll.forget()
+    expect(scroll.take(3010)).toBeUndefined()
+  })
+
+  it('跳完守住跳到的位置：浏览器对那个键自己的滚动晚于命令才开始，按键后 KEY_SCROLL_MS 内滚走了就拉回来', () => {
+    const scroll = new KeyScroll()
+    scroll.press({ x: 0, y: 40 }, 1000)
+    scroll.take(1012)
+    // 刚回到按键那一刻、还没跳完：守住按键那一刻的位置
+    expect(scroll.scrolled({ x: 0, y: 300 }, 1020)).toEqual({ x: 0, y: 40 })
+    scroll.hold({ x: 0, y: 900 })
+    expect(scroll.scrolled({ x: 0, y: 900 }, 1030)).toBeUndefined()
+    expect(scroll.scrolled({ x: 0, y: 1200 }, 1040)).toEqual({ x: 0, y: 900 })
+    expect(scroll.scrolled({ x: 0, y: 1200 }, 1000 + KEY_SCROLL_MS + 1)).toBeUndefined()
+    expect(scroll.scrolled({ x: 0, y: 1300 }, 1000 + KEY_SCROLL_MS + 2)).toBeUndefined()
+  })
+
+  it('不是按键触发的跳转、又按了键、点了鼠标：不守', () => {
+    const scroll = new KeyScroll()
+    scroll.take(10)
+    scroll.hold({ x: 0, y: 900 })
+    expect(scroll.scrolled({ x: 0, y: 0 }, 20)).toBeUndefined()
+    scroll.press({ x: 0, y: 40 }, 1000)
+    scroll.take(1010)
+    scroll.press({ x: 0, y: 40 }, 1100)
+    expect(scroll.scrolled({ x: 0, y: 300 }, 1110)).toBeUndefined()
+    scroll.take(1120)
+    scroll.forget()
+    expect(scroll.scrolled({ x: 0, y: 300 }, 1130)).toBeUndefined()
   })
 })

vscode/webview-ui/src/codeReader/occurrences.ts

@@ -1,4 +1,4 @@
-import type { Inline, KeyCombo, Occurrence, Segment, WebviewToExtension } from './types'
+import type { Inline, Occurrence, Segment, WebviewToExtension } from './types'
 
 /** 高亮画成哪种底色，和 VS Code 编辑器一样：写入（定义、赋值）用强高亮色，读取和按文字认出的用普通高亮色。 */
 export type OccurrenceStyle = 'strong' | 'normal'
@@ -111,10 +111,58 @@ export function stepIndex(
   return undefined
 }
 
-/** 按下的键是不是这个组合：键名（字母不分大小写）和四个修饰键都对上。 */
-export function matchesKey(event: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'shiftKey' | 'altKey' | 'metaKey'>, combo: KeyCombo): boolean {
-  return event.key.toLowerCase() === combo.key.toLowerCase()
-    && event.ctrlKey === combo.ctrl && event.shiftKey === combo.shift && event.altKey === combo.alt && event.metaKey === combo.meta
+/** 按键之后多久内发来的跳转算这个键触发的：命令从 VS Code 绕一圈回到页面通常只要几十毫秒 */
+export const KEY_TO_COMMAND_MS = 1000
+/** 浏览器对一个键自己的滚动（⌘↓ 滚到底）按下后多久内会开始：它可能在命令发来之后才开始，这段时间里跳到的位置要守住 */
+export const KEY_SCROLL_MS = 500
+
+export interface ScrollPosition { x: number, y: number }
+
+/**
+ * 跳到下一处 / 上一处的命令由 VS Code 的快捷键系统触发，页面不知道绑的是哪个键，浏览器对这个键自己的动作（⌘↓ 滚到底）拦不住；
+ * 它还可能早于命令开始，也可能晚于命令（实测命令十几毫秒就到，滚动动画再过一帧才开始）。所以不管哪个键：
+ * 按键那一刻记下页面滚在哪（press）；命令发来时先回到那里（take）再滚到目标；跳完守住跳到的位置（hold），
+ * 按键后 KEY_SCROLL_MS 内浏览器自己滚走了就拉回来（scrolled）。
+ * 按键后点了鼠标、滚了滚轮、又按了键，或跳转隔了 KEY_TO_COMMAND_MS 以上才来（从命令面板运行），都不算这个键触发的。
+ */
+export class KeyScroll {
+  private pressed: { position: ScrollPosition, at: number } | undefined
+  private held: { position: ScrollPosition, until: number } | undefined
+
+  /** 按下任何键（照常交给浏览器和 VS Code 处理）时记下页面滚在哪。 */
+  press(position: ScrollPosition, at: number): void {
+    this.pressed = { position, at }
+    this.held = undefined
+  }
+
+  forget(): void {
+    this.pressed = undefined
+    this.held = undefined
+  }
+
+  /** 跳转发来时：刚按过键就交出按键那一刻的位置（只交一次），从这时起守住它，直到跳完换成跳到的位置。 */
+  take(now: number): ScrollPosition | undefined {
+    const pressed = this.pressed
+    this.pressed = undefined
+    this.held = pressed && now - pressed.at <= KEY_TO_COMMAND_MS ? { position: pressed.position, until: pressed.at + KEY_SCROLL_MS } : undefined
+    return this.held?.position
+  }
+
+  /** 跳完了（滚到了目标，或没处可跳留在原地）：按键触发的跳转改守这个位置。 */
+  hold(position: ScrollPosition): void {
+    if (this.held)
+      this.held = { ...this.held, position }
+  }
+
+  /** 页面滚动了：还在守着、又被浏览器滚走了，给出要拉回的位置。 */
+  scrolled(position: ScrollPosition, now: number): ScrollPosition | undefined {
+    const held = this.held
+    if (!held || now > held.until) {
+      this.held = undefined
+      return undefined
+    }
+    return held.position.x === position.x && held.position.y === position.y ? undefined : held.position
+  }
 }
 
 /**
@@ -210,7 +258,7 @@ export interface NavigationFacts {
   highlighted: boolean
   /** 页面有焦点：按的键才会到这个页面 */
   focused: boolean
-  /** 焦点在输入框里：⌘↑ / ⌘↓ 这些键归输入框移光标 */
+  /** 焦点在输入框里：按的键归输入框（打字、移光标），不拿来跳 */
   typing: boolean
 }
 
@@ -237,14 +285,6 @@ export class OccurrenceNavigation {
     this.report()
   }
 
-  /**
-   * 这个键要不要拦下浏览器的默认动作：能跳、又是那两条命令绑的键。VS Code 把页面上按的每个键都转给自己的快捷键系统，
-   * 但不回头告诉页面有没有命令接了它，浏览器的默认动作又只能在按下的当下拦，所以只能照命令绑的键（keys）当场判断。
-   */
-  blocks(event: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'shiftKey' | 'altKey' | 'metaKey'>, keys: readonly KeyCombo[]): boolean {
-    return this.available && keys.some(combo => matchesKey(event, combo))
-  }
-
   private report(): void {
     const { available } = this
     if (available === this.reported)

vscode/webview-ui/src/codeReader/types.ts

@@ -142,19 +142,6 @@ export interface Occurrence {
   kind: 'text' | 'read' | 'write'
 }
 
-/**
- * 一个按键组合，按 KeyboardEvent 的写法：key 是 KeyboardEvent.key（'ArrowDown'），四个修饰键都要对上。
- * 页面上按的每个键 VS Code 都会转给自己的快捷键系统，但不告诉页面有没有命令接了它；浏览器对这个键的默认动作
- * （⌘↓ 滚到底）又只能在按下的当下拦，所以页面要事先知道命令绑的是哪些键
- */
-export interface KeyCombo {
-  key: string
-  ctrl: boolean
-  shift: boolean
-  alt: boolean
-  meta: boolean
-}
-
 export interface DocumentMessage {
   type: 'document'
   version: number
@@ -247,7 +234,6 @@ export interface AnswerEnd {
  * askProfiles：「问 AI」的 profile 下拉；ready 后来一次，任何一个预览改了都会来
  * answer：askId 那个问题的回答长了（text 是到现在为止的全文）、或换了在做的事
  * answerEnd：askId 那个问题答完了，见 AnswerEnd
- * occurrenceKeys：「跳到下一处 / 上一处高亮」这两条命令默认绑的键；ready 后来一次，见 KeyCombo
  * moveOccurrence：跳到高亮着的名字的下一处（step 1）/ 上一处（step -1）出现
  */
 export type ExtensionToWebview
@@ -255,7 +241,6 @@ export type ExtensionToWebview
     | ({ type: 'reveal' } & Reveal)
     | { type: 'definitionProbed', id: number, found: boolean }
     | { type: 'occurrencesFound', id: number, occurrences: Occurrence[] }
-    | { type: 'occurrenceKeys', keys: KeyCombo[] }
     | { type: 'moveOccurrence', step: 1 | -1 }
     | { type: 'filter', excluded: Excluded }
     | QaMessage

vscode/webview-ui/src/codeReader/useOccurrences.ts

@@ -1,7 +1,7 @@
-import type { Click, Highlight } from './occurrences'
-import type { BlockView, KeyCombo, Occurrence } from './types'
+import type { Click, Highlight, ScrollPosition } from './occurrences'
+import type { BlockView, Occurrence } from './types'
 import { createContext, useEffect, useLayoutEffect, useRef, useState } from 'react'
-import { clickAction, OccurrenceHighlight, OccurrenceNavigation } from './occurrences'
+import { clickAction, KeyScroll, OccurrenceHighlight, OccurrenceNavigation } from './occurrences'
 import { occurrencePlan } from './reveal'
 import { showInViewport } from './useReveal'
 import { onMessage, postMessage } from './vscode'
@@ -47,15 +47,30 @@ function isTyping(target: EventTarget | null): boolean {
     || (target instanceof HTMLInputElement && !NON_TEXT_INPUTS.has(target.type))
 }
 
+function scrollPosition(): ScrollPosition {
+  return { x: window.scrollX, y: window.scrollY }
+}
+
+/**
+ * 立刻滚到这里，顺带打断浏览器正在播（或刚排上、还没开始播）的滚动动画。滚到原地浏览器当没滚、不打断动画，
+ * 所以先挪一个像素再回来：同一段脚本里连着滚两下，中间不画，画面上看不出。
+ */
+function scrollBack({ x, y }: ScrollPosition): void {
+  window.scrollTo({ left: x, top: y > 0 ? y - 1 : y + 1, behavior: 'instant' })
+  window.scrollTo({ left: x, top: y, behavior: 'instant' })
+}
+
 /**
  * 单击名字高亮它在文档里的各处出现，点空白处、Esc、换文档版本或翻译清掉；返回眼下高亮着的名字。
  * 高亮着时扩展端的「跳到下一处 / 上一处高亮」命令发来 moveOccurrence：当前那一处换成下一处页面上找得到的出现，
  * 展开把它折叠住的块、属性行和子行，再把它滚进视口。
+ * 触发命令的那个键浏览器自己的滚动不拦（页面不知道是哪个键），跳的时候盖掉它，见 KeyScroll。
  */
 export function useOccurrences(version: number | undefined, translatorId: string | undefined, page: OccurrencePage | undefined): Highlight | undefined {
   const [highlight, setHighlight] = useState<Highlight | undefined>()
   const [occurrences] = useState(() => new OccurrenceHighlight(postMessage, setHighlight))
   const [navigation] = useState(() => new OccurrenceNavigation(postMessage, { focused: document.hasFocus(), typing: isTyping(document.activeElement) }))
+  const [keyScroll] = useState(() => new KeyScroll())
   /** 用键盘跳过几次：每跳一次，画完后把当前那一处滚进视口 */
   const [moves, setMoves] = useState(0)
   const latestPage = useRef(page)
@@ -71,22 +86,28 @@ export function useOccurrences(version: number | undefined, translatorId: string
 
   // 要展开的已经展开、当前那一处已经画出来（data-current），页面上按先后第一个就是它
   useLayoutEffect(() => {
-    const el = moves > 0 ? document.querySelector<HTMLElement>('[data-current]') : null
+    if (moves === 0)
+      return
+    const el = document.querySelector<HTMLElement>('[data-current]')
     if (el)
       showInViewport(el)
-  }, [moves])
+    keyScroll.hold(scrollPosition())
+  }, [moves, keyScroll])
 
   useEffect(() => {
-    let keys: KeyCombo[] = []
     const move = (step: 1 | -1): void => {
+      // 触发命令的那个键浏览器可能已经照自己的意思滚了（⌘↓ 滚到底），先回到按键那一刻
+      const before = keyScroll.take(performance.now())
+      if (before)
+        scrollBack(before)
       const current = latestPage.current
-      if (!current)
-        return
-      const planOf = (occurrence: Occurrence): ReturnType<typeof occurrencePlan> => occurrencePlan(current.blocks, occurrence, current.skip)
-      const target = occurrences.move(step, occurrence => planOf(occurrence) !== undefined)
+      const planOf = (occurrence: Occurrence): ReturnType<typeof occurrencePlan> => current && occurrencePlan(current.blocks, occurrence, current.skip)
+      const target = current && occurrences.move(step, occurrence => planOf(occurrence) !== undefined)
       const plan = target && planOf(target)
-      if (!plan)
+      if (!current || !plan) {
+        keyScroll.hold(scrollPosition())
         return
+      }
       const folded = plan.expand.filter(id => current.collapsed.has(id))
       if (folded.length > 0)
         current.expand(folded)
@@ -94,12 +115,18 @@ export function useOccurrences(version: number | undefined, translatorId: string
     }
     // 捕获阶段：赶在块里的按钮处理点击、折叠箭头换图标之前读出点在哪
     const onClick = (event: MouseEvent): void => occurrences.click(clickAction(clickOf(event)))
+    // 任何键都照常交给浏览器和 VS Code，这里只记下按键那一刻页面滚在哪
+    const onKeyDown = (event: KeyboardEvent): void => keyScroll.press(scrollPosition(), event.timeStamp)
+    const onPointer = (): void => keyScroll.forget()
+    const onScroll = (event: Event): void => {
+      const back = keyScroll.scrolled(scrollPosition(), event.timeStamp)
+      if (back)
+        scrollBack(back)
+    }
     const onKey = (event: KeyboardEvent): void => {
       // 输入框、下拉列表自己用掉的 Esc 不算
       if (event.key === 'Escape' && !event.defaultPrevented)
         occurrences.clear()
-      else if (navigation.blocks(event, keys))
-        event.preventDefault()
     }
     const onFocus = (): void => navigation.update({ focused: true })
     const onBlur = (): void => navigation.update({ focused: false })
@@ -108,13 +135,15 @@ export function useOccurrences(version: number | undefined, translatorId: string
     const off = onMessage((msg) => {
       if (msg.type === 'occurrencesFound')
         occurrences.answer(msg.id, msg.occurrences)
-      else if (msg.type === 'occurrenceKeys')
-        keys = msg.keys
       else if (msg.type === 'moveOccurrence')
         move(msg.step)
     })
     navigation.update({})
     document.addEventListener('click', onClick, true)
+    window.addEventListener('keydown', onKeyDown, true)
+    window.addEventListener('pointerdown', onPointer, true)
+    window.addEventListener('wheel', onPointer, { capture: true, passive: true })
+    window.addEventListener('scroll', onScroll, { passive: true })
     window.addEventListener('keydown', onKey)
     window.addEventListener('focus', onFocus)
     window.addEventListener('blur', onBlur)
@@ -123,13 +152,17 @@ export function useOccurrences(version: number | undefined, translatorId: string
     return () => {
       off()
       document.removeEventListener('click', onClick, true)
+      window.removeEventListener('keydown', onKeyDown, true)
+      window.removeEventListener('pointerdown', onPointer, true)
+      window.removeEventListener('wheel', onPointer, { capture: true })
+      window.removeEventListener('scroll', onScroll)
       window.removeEventListener('keydown', onKey)
       window.removeEventListener('focus', onFocus)
       window.removeEventListener('blur', onBlur)
       document.removeEventListener('focusin', onFocusIn)
       document.removeEventListener('focusout', onFocusOut)
     }
-  }, [occurrences, navigation])
+  }, [occurrences, navigation, keyScroll])
 
   return highlight
 }