@quicktvui/web-renderer 1.0.0

package/src/core/TVFocusManager.js

@@ -0,0 +1,2014 @@
+// TV Focus Navigation System
+// Handles keyboard arrow keys for TV-style focus navigation
+
+import { syncDomAutoWidthIn } from './templateBinding'
+
+const DEBUG = false
+
+export class TVFocusManager {
+  constructor() {
+    this.focusableElements = []
+    this.focusedElement = null
+    this.focusedElementOriginalStyles = new Map()
+
+    // Focus history for back navigation
+    // Stack of { routeName, focusSelector, focusIndex } objects
+    this.focusHistory = []
+    this.currentRouteName = null
+
+    // Focus navigation options
+    this.options = {
+      // 是否使用距离计算来选择最近的焦点元素
+      // 强烈建议在瀑布流/复杂列表中开启 true
+      useDistanceBasedNavigation: true,
+      // 距离计算时的横向距离权重（0-1）
+      crossDistanceWeight: 0.5,
+    }
+
+    // Default focus styles
+    this.defaultFocusStyle = {
+      border: {
+        enabled: true,
+        color: '#FFFFFF',
+        width: 3,
+        innerColor: '#000000',
+        innerWidth: 2,
+        cornerRadius: 0,
+      },
+      scale: 1.0,
+      transition: 'transform 0.15s ease-out, outline 0.15s ease-out',
+    }
+
+    // Bind methods
+    this.handleKeyDown = this.handleKeyDown.bind(this)
+    this.updateFocusableElements = this.updateFocusableElements.bind(this)
+
+    // Start listening
+    this.init()
+  }
+
+  /**
+   * 设置焦点导航选项
+   */
+  setOptions(options) {
+    this.options = { ...this.options, ...options }
+  }
+
+  /**
+   * Update focus configuration from FocusModule
+   * @param {object} config - Focus configuration from FocusModule
+   */
+  updateFocusConfig(config) {
+    if (!config) return
+
+    // Update border color
+    if (config.borderColorEnabled) {
+      this.defaultFocusStyle.border.color = config.borderColor
+    }
+
+    // Update border width
+    if (config.borderWidthEnabled) {
+      this.defaultFocusStyle.border.width = config.borderWidth
+    }
+
+    // Update corner radius
+    if (config.cornerEnabled) {
+      this.defaultFocusStyle.border.cornerRadius = config.cornerRadius
+    }
+
+    // Update border inset (we'll apply this as margin in focus styles)
+    // Note: inset in native means the border moves inward, in web we handle this differently
+    if (config.borderInsetEnabled) {
+      this.defaultFocusStyle.border.inset = config.borderInset
+    }
+
+    // Update inner border
+    this.defaultFocusStyle.border.innerEnabled = config.innerBorderEnabled
+
+    // Update focus scale
+    if (config.focusScale) {
+      this.defaultFocusStyle.scale = config.focusScale
+    }
+
+    // Re-apply focus styles if there's a focused element
+    if (this.focusedElement) {
+      this._applyFocusStyle(this.focusedElement)
+    }
+
+    this._log('[TVFocusManager] Focus config updated:', this.defaultFocusStyle)
+  }
+
+  _log(...args) {
+    if (DEBUG) console.log(...args)
+  }
+
+  init() {
+    document.addEventListener('keydown', this.handleKeyDown)
+
+    // Add mouse/pointer click support
+    document.addEventListener('click', this.handleClick.bind(this), true)
+
+    const observer = new MutationObserver((mutations) => {
+      this.updateFocusableElements()
+
+      // 检查新添加的元素是否有 autofocus 属性，实现 Android 端兼容效果
+      for (const mutation of mutations) {
+        if (mutation.type === 'childList' && mutation.addedNodes.length > 0) {
+          // 延迟处理，等待元素完全渲染
+          setTimeout(() => {
+            for (const node of mutation.addedNodes) {
+              this._checkAndFocusAutofocusElement(node)
+            }
+          }, 50)
+        }
+      }
+    })
+    observer.observe(document.body, { childList: true, subtree: true })
+
+    // Initial scan (no auto-focus, keep consistent with Android)
+    setTimeout(() => {
+      this.updateFocusableElements()
+    }, 1000)
+    this._log('Focus manager initialized')
+  }
+
+  // Check if navigation is going back
+  _isGoingBack(from, to) {
+    // Check if the 'to' route exists in our history
+    const toIndex = this.focusHistory.findIndex((h) => h.routeName === to.name)
+    return toIndex >= 0
+  }
+
+  // Save current focus state before navigation
+  _saveFocusState(routeName) {
+    if (!this.focusedElement) return
+
+    // Generate a unique selector for the focused element
+    const selector = this._generateElementSelector(this.focusedElement)
+
+    const focusState = {
+      routeName,
+      focusSelector: selector,
+    }
+
+    // Check if we already have a state for this route
+    const existingIndex = this.focusHistory.findIndex((h) => h.routeName === routeName)
+    if (existingIndex >= 0) {
+      // Update existing state
+      this.focusHistory[existingIndex] = focusState
+    } else {
+      // Push new state
+      this.focusHistory.push(focusState)
+    }
+
+    // console.log('[TVFocus] Saved focus state for route:', routeName, 'selector:', selector)
+  }
+
+  // Restore focus state when returning to a page
+  _restoreFocusState(routeName) {
+    const focusState = this.focusHistory.find((h) => h.routeName === routeName)
+
+    // console.log('[TVFocus] Attempting to restore focus for route:', routeName)
+
+    // Clear current focus
+    this.clearFocus()
+
+    // Update focusable elements first
+    this.updateFocusableElements()
+
+    if (focusState && focusState.focusSelector) {
+      // Try to find element by selector
+      setTimeout(() => {
+        const element = document.querySelector(focusState.focusSelector)
+        if (element && this.focusableElements.includes(element)) {
+          this._doFocusElement(element)
+        }
+      }, 200)
+    } else {
+      // console.log('[TVFocus] No saved focus state found for route:', routeName)
+    }
+  }
+
+  // Generate a unique CSS selector for an element
+  _generateElementSelector(element) {
+    if (!element) return null
+
+    // Helper to escape CSS identifier (handles numeric IDs)
+    const escapeCSSId = (id) => {
+      if (!id) return null
+      // CSS.escape is available in modern browsers
+      if (typeof CSS !== 'undefined' && CSS.escape) {
+        return CSS.escape(id)
+      }
+      // Fallback: manually escape
+      return id.replace(/([^\w-])/g, '\\$1')
+    }
+
+    // Try data-component-name first
+    const componentName = element.getAttribute('data-component-name')
+    const id = element.id
+
+    if (componentName && id) {
+      // Use attribute selector for ID to avoid issues with numeric IDs
+      return `[data-component-name="${componentName}"][id="${id}"]`
+    }
+
+    if (componentName) {
+      return `[data-component-name="${componentName}"]`
+    }
+
+    // Try id with proper escaping
+    if (id) {
+      return `[id="${id}"]`
+    }
+
+    // Generate path-based selector
+    const path = []
+    let current = element
+
+    while (current && current !== document.body) {
+      let selector = current.tagName.toLowerCase()
+
+      if (current.id) {
+        // Use attribute selector instead of # for numeric IDs
+        selector = `[id="${current.id}"]`
+        path.unshift(selector)
+        break
+      }
+
+      if (current.className && typeof current.className === 'string') {
+        const classes = current.className.split(' ').filter((c) => c && !c.includes(':'))
+        if (classes.length > 0) {
+          selector += `.${classes[0]}`
+        }
+      }
+
+      // Add nth-child if needed
+      const parent = current.parentElement
+      if (parent) {
+        const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName)
+        if (siblings.length > 1) {
+          const index = siblings.indexOf(current) + 1
+          selector += `:nth-child(${index})`
+        }
+      }
+
+      path.unshift(selector)
+      current = current.parentElement
+    }
+
+    return path.join(' > ')
+  }
+
+  resetForNewPage() {
+    // console.log('[TVFocus] Resetting focus for new page')
+    this.clearFocus()
+
+    // Update focusable elements list
+    // Unlike native Android, we don't auto-focus the first element
+    // Only focus elements with 'autofocus' attribute
+    const updateElements = (attempt = 0, maxAttempts = 5) => {
+      this.updateFocusableElements()
+
+      // [TVFocus] Attempt ${attempt + 1}: Found ${this.focusableElements.length} focusable elements
+
+      if (this.focusableElements.length > 0) {
+        // Look for element with autofocus attribute
+        const autofocusElement = this.focusableElements.find((el) => {
+          const autofocus = el.getAttribute('autofocus')
+          return autofocus === 'true' || autofocus === '' || autofocus === '1'
+        })
+
+        if (autofocusElement) {
+          this._doFocusElement(autofocusElement)
+          // console.log('[TVFocus] Auto-focused element with autofocus attribute')
+        }
+        // If no autofocus element, don't auto-focus anything
+        // Focus will be set when user presses arrow keys or when requestFocus() is called
+      } else if (attempt < maxAttempts) {
+        const delay = 100 + attempt * 100
+        // console.log(`[TVFocus] No elements found, retrying in ${delay}ms...`)
+        setTimeout(() => updateElements(attempt + 1, maxAttempts), delay)
+      }
+    }
+
+    setTimeout(() => updateElements(0), 150)
+  }
+
+  /**
+   * 检查新添加的节点是否有 autofocus 属性，实现 Android 端兼容效果
+   * 当组件 mount 时自动获取焦点
+   */
+  _checkAndFocusAutofocusElement(node) {
+    if (!node || node.nodeType !== 1) return
+
+    // 检查节点本身是否有 autofocus 属性
+    const autofocus = node.getAttribute && node.getAttribute('autofocus')
+    const hasAutofocus = autofocus === 'true' || autofocus === '' || autofocus === '1'
+
+    // 检查节点是否可聚焦
+    const isFocusable = node.hasAttribute && node.hasAttribute('focusable')
+
+    if (hasAutofocus && isFocusable) {
+      // 更新 focusable 元素列表
+      this.updateFocusableElements()
+
+      // 检查该元素是否在 focusable 列表中
+      if (this.focusableElements.includes(node)) {
+        this._doFocusElement(node)
+        return
+      }
+    }
+
+    // 检查子元素是否有 autofocus 属性
+    if (node.querySelector) {
+      const autofocusChild = node.querySelector(
+        '[autofocus="true"], [autofocus=""], [autofocus="1"]'
+      )
+      if (
+        autofocusChild &&
+        autofocusChild.hasAttribute &&
+        autofocusChild.hasAttribute('focusable')
+      ) {
+        // 更新 focusable 元素列表
+        this.updateFocusableElements()
+
+        // 检查该元素是否在 focusable 列表中
+        if (this.focusableElements.includes(autofocusChild)) {
+          this._doFocusElement(autofocusChild)
+        }
+      }
+    }
+  }
+
+  _focusFirstDivFallback() {
+    const currentPage = this._getCurrentPage()
+    // console.log('[TVFocus] Fallback: searching for first div in', currentPage.tagName)
+
+    const divs = currentPage.querySelectorAll('div')
+    for (const div of divs) {
+      const style = window.getComputedStyle(div)
+      const isVisible =
+        style.display !== 'none' && style.visibility !== 'hidden' && parseFloat(style.opacity) > 0
+      const rect = div.getBoundingClientRect()
+      const hasDimensions = rect.width > 0 && rect.height > 0
+
+      if (isVisible && hasDimensions) {
+        div.setAttribute('focusable', 'true')
+        div.setAttribute('tabindex', '0')
+
+        this.focusableElements = [div]
+        this._doFocusElement(div)
+        // console.log('[TVFocus] Fallback: focused first div element')
+        return
+      }
+    }
+
+    console.warn('[TVFocus] Fallback: no visible div element found either')
+  }
+
+  _getCurrentPage() {
+    const routerViewSelectors = [
+      '[data-component-name="ESPageRouterView"]',
+      '[data-component-name="ESRouterView"]',
+      'es-page-router-view',
+      'es-router-view',
+      '[data-router-view]',
+      '.es-router-view',
+    ]
+
+    for (const selector of routerViewSelectors) {
+      const routerView = document.querySelector(selector)
+      if (routerView && routerView.children.length > 0) {
+        // [TVFocus] Router view found with selector: selector children: routerView.children.length
+
+        for (let i = routerView.children.length - 1; i >= 0; i--) {
+          const child = routerView.children[i]
+          const style = window.getComputedStyle(child)
+          const isVisible =
+            style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            parseFloat(style.opacity) > 0
+          if (isVisible) {
+            const componentName = child.getAttribute('data-component-name') || child.tagName
+            // [TVFocus] Current page componentName className index
+            return child
+          }
+        }
+
+        return routerView.children[routerView.children.length - 1]
+      }
+    }
+
+    // console.log('[TVFocus] Router view not found, searching for visible page containers')
+
+    const pageContainers = document.querySelectorAll(
+      '[data-component-name="ESPageRootView"], es-page-root-view, [data-page]'
+    )
+    for (let i = pageContainers.length - 1; i >= 0; i--) {
+      const container = pageContainers[i]
+      const style = window.getComputedStyle(container)
+      if (style.display !== 'none' && style.visibility !== 'hidden') {
+        return container
+      }
+    }
+
+    // console.log('[TVFocus] No page container found, using body as fallback')
+    return document.body
+  }
+
+  updateFocusableElements() {
+    const selectors = [
+      '[focusable="true"]',
+      '[focusable="1"]',
+      '[focusable]',
+      '[data-focusable="true"]',
+      '[data-focusable]',
+      '[canfocus="true"]',
+      '[canFocus="true"]',
+      '.focusable',
+      '[tabindex="0"]',
+      '[tabindex]',
+    ]
+
+    const allElements = new Set()
+    selectors.forEach((selector) => {
+      try {
+        document.querySelectorAll(selector).forEach((el) => allElements.add(el))
+      } catch (e) {
+        // Ignore invalid selectors
+      }
+    })
+
+    const elements = Array.from(allElements)
+    // console.log('[TVFocus] Total elements with focusable attributes:', elements.length)
+
+    if (elements.length > 0) {
+      const attrDebug = elements.slice(0, 5).map((el) => {
+        const attrs = []
+        if (el.hasAttribute('focusable')) attrs.push(`focusable="${el.getAttribute('focusable')}"`)
+        if (el.hasAttribute('data-focusable'))
+          attrs.push(`data-focusable="${el.getAttribute('data-focusable')}"`)
+        if (el.hasAttribute('tabindex')) attrs.push(`tabindex="${el.getAttribute('tabindex')}"`)
+        return { tag: el.tagName, attrs: attrs.join(', ') }
+      })
+      // console.log('[TVFocus] Sample focusable elements:', attrDebug)
+    }
+
+    const currentPage = this._getCurrentPage()
+    // [TVFocus] Current page for filtering
+
+    const candidates = Array.from(elements).filter((el) => {
+      // Skip elements with focusable="false" or focusable="0"
+      const focusableAttr = el.getAttribute('focusable')
+      if (focusableAttr === 'false' || focusableAttr === '0') {
+        return false
+      }
+
+      // Skip elements with duplicateParentState - they inherit parent's focus state
+      const duplicateParentState = el.getAttribute('duplicateParentState')
+      if (
+        duplicateParentState === 'true' ||
+        duplicateParentState === '' ||
+        el.hasAttribute('duplicateparentstate')
+      ) {
+        return false
+      }
+
+      if (currentPage !== document.body && !currentPage.contains(el)) {
+        return false
+      }
+
+      const style = window.getComputedStyle(el)
+      const isVisible =
+        style.display !== 'none' &&
+        style.visibility !== 'hidden' &&
+        parseFloat(style.opacity) > 0 &&
+        !el.hasAttribute('data-template')
+
+      if (!isVisible) return false
+
+      const rect = el.getBoundingClientRect()
+      const hasDimensions = rect.width > 0 && rect.height > 0
+
+      // 放宽视口检测：允许元素在更大的范围内被检测到
+      // 这样可以支持 waterfall 等可滚动布局中的焦点导航
+      // 使用一个更大的"虚拟视口"范围（3倍屏幕高度）
+      const extendedViewportHeight = window.innerHeight * 3
+      const extendedViewportWidth = window.innerWidth * 2
+      const inViewport =
+        rect.top < extendedViewportHeight &&
+        rect.bottom > -extendedViewportHeight &&
+        rect.left < extendedViewportWidth &&
+        rect.right > -extendedViewportWidth
+
+      return hasDimensions && inViewport
+    })
+
+    this.focusableElements = candidates
+
+    // Initialize showOnState visibility for all elements (default to 'normal' state)
+    this._initShowOnStateVisibility()
+
+    // [TVFocus] Found focusableElements.length visible focusable elements
+
+    if (this.focusableElements.length > 0) {
+      const sample = this.focusableElements.slice(0, 3).map((el, i) => {
+        const rect = el.getBoundingClientRect()
+        const componentName = el.getAttribute('data-component-name') || el.tagName
+        return {
+          index: i,
+          component: componentName,
+          tag: el.tagName,
+          class: el.className?.substring?.(0, 30),
+          rect: {
+            x: Math.round(rect.x),
+            y: Math.round(rect.y),
+            w: Math.round(rect.width),
+            h: Math.round(rect.height),
+          },
+        }
+      })
+      // console.log('[TVFocus] Sample elements:', sample)
+    }
+  }
+
+  handleKeyDown(e) {
+    this._dispatchPageKeyDown(e)
+
+    if (!['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Enter', 'Escape'].includes(e.key)) {
+      return
+    }
+
+    e.preventDefault()
+
+    switch (e.key) {
+      case 'ArrowUp':
+        this.moveFocus('up')
+        break
+      case 'ArrowDown':
+        this.moveFocus('down')
+        break
+      case 'ArrowLeft':
+        this.moveFocus('left')
+        break
+      case 'ArrowRight':
+        this.moveFocus('right')
+        break
+      case 'Enter':
+        this.clickFocused()
+        break
+      case 'Escape':
+        this.dispatchBackPressed(e)
+        break
+    }
+  }
+
+  _dispatchPageKeyDown(e) {
+    const keyEvent = this._toESKeyEvent(e)
+    // action: 0 = keydown, 1 = keyup
+    keyEvent.action = 0
+
+    // 模拟 Android 平台发送 DispatchKeyEvent
+    try {
+      const { EventBus } = require('@extscreen/es3-vue')
+      if (EventBus && EventBus.$emit) {
+        EventBus.$emit('DispatchKeyEvent', keyEvent)
+      }
+    } catch (err) {
+      // fallback to direct method call
+      this._callCurrentPageMethod('onKeyDown', keyEvent)
+    }
+  }
+
+  _dispatchPageKeyUp(e) {
+    const keyEvent = this._toESKeyEvent(e)
+    // action: 0 = keydown, 1 = keyup
+    keyEvent.action = 1
+
+    // 模拟 Android 平台发送 DispatchKeyEvent
+    try {
+      const { EventBus } = require('@extscreen/es3-vue')
+      if (EventBus && EventBus.$emit) {
+        EventBus.$emit('DispatchKeyEvent', keyEvent)
+      }
+    } catch (err) {
+      // fallback to direct method call
+      this._callCurrentPageMethod('onKeyUp', keyEvent)
+    }
+  }
+
+  _toESKeyEvent(e) {
+    const domKey = e?.key
+    let keyCode = e?.keyCode ?? e?.which
+
+    switch (domKey) {
+      case 'ArrowUp':
+        keyCode = 19
+        break
+      case 'ArrowDown':
+        keyCode = 20
+        break
+      case 'ArrowLeft':
+        keyCode = 21
+        break
+      case 'ArrowRight':
+        keyCode = 22
+        break
+      case 'Enter':
+        keyCode = 23
+        break
+      case 'Escape':
+        keyCode = 4
+        break
+    }
+
+    return {
+      keyCode,
+      key: domKey,
+      code: e?.code,
+      repeat: e?.repeat,
+      altKey: e?.altKey,
+      ctrlKey: e?.ctrlKey,
+      shiftKey: e?.shiftKey,
+      metaKey: e?.metaKey,
+      nativeEvent: e,
+    }
+  }
+
+  _getCurrentPageVueInstance() {
+    // 从页面栈获取栈顶实例
+    const stack = global.__ES_PAGE_STACK__
+    if (stack && stack.length > 0) {
+      const top = stack[stack.length - 1]
+      if (top && (top.exposed || top.proxy || top.setupState)) {
+        return top
+      }
+    }
+
+    const currentPage = this._getCurrentPage()
+    if (!currentPage) return null
+    return this._findVueInstanceInSubtree(currentPage)
+  }
+
+  _findVueInstanceInSubtree(rootEl) {
+    const queue = [rootEl]
+    const visited = new Set()
+    let scanned = 0
+
+    while (queue.length > 0 && scanned < 200) {
+      const el = queue.shift()
+      if (!el || visited.has(el)) continue
+      visited.add(el)
+      scanned += 1
+
+      const inst = el.__vueParentComponent || el.__vue__
+      if (inst && (inst.exposed || inst.proxy)) {
+        return inst
+      }
+
+      const children = el.children
+      if (children && children.length > 0) {
+        for (let i = 0; i < children.length; i++) {
+          queue.push(children[i])
+        }
+      }
+    }
+
+    return null
+  }
+
+  _callCurrentPageMethod(methodName, arg) {
+    const inst = this._getCurrentPageVueInstance()
+    if (!inst) return false
+
+    // 优先从 setupState 获取，然后是 exposed，最后是 proxy
+    const fn =
+      inst?.setupState?.[methodName] || inst?.exposed?.[methodName] || inst?.proxy?.[methodName]
+    if (typeof fn !== 'function') return false
+
+    try {
+      const result = fn(arg)
+      if (result && typeof result.then === 'function') {
+        result.catch((err) => console.error(`[TVFocus] ${methodName} rejected:`, err))
+      }
+    } catch (err) {
+      console.error(`[TVFocus] ${methodName} threw:`, err)
+    }
+
+    return true
+  }
+
+  moveFocus(direction) {
+    if (this.focusableElements.length === 0) {
+      this.updateFocusableElements()
+      if (this.focusableElements.length === 0) return
+    }
+
+    // 如果没有焦点元素，聚焦第一个
+    if (!this.focusedElement) {
+      this._doFocusElement(this.focusableElements[0])
+      return
+    }
+
+    const current = this.focusedElement
+
+    // Check if the current element blocks focus movement in this direction
+    if (this._isDirectionBlocked(current, direction)) {
+      this._log('[TVFocus] Direction', direction, 'is blocked for current element')
+      return
+    }
+
+    // Check if element is still valid and in the DOM
+    if (!document.body.contains(current)) {
+      console.warn(
+        '[TVFocus] Current focused element no longer in DOM, refreshing focusable elements'
+      )
+      this.updateFocusableElements()
+      if (this.focusableElements.length > 0) {
+        this._doFocusElement(this.focusableElements[0])
+      }
+      return
+    }
+
+    // 检查是否在 FastListView 中，如果是则委托处理
+    // 但是，由于有 List 嵌套 List (如 Waterfall 嵌套 Section) 的情况，
+    // 局部的 FastListView 可能无法找到合适的焦点，此时应该继续让全局基于距离寻找。
+    let fastListViewCandidate = null
+    if (!this.options.useDistanceBasedNavigation) {
+      fastListViewCandidate = this._tryFastListViewNavigation(current, direction)
+      if (fastListViewCandidate) {
+        this._doFocusElement(fastListViewCandidate)
+        return
+      }
+    }
+
+    // 根据配置选择导航方式
+    let bestCandidate = null
+    if (this.options.useDistanceBasedNavigation) {
+      bestCandidate = this._findBestCandidateByDistance(current, direction)
+    } else {
+      bestCandidate = this._findBestCandidateSequential(current, direction)
+    }
+
+    if (bestCandidate) {
+      if (this.options.useDistanceBasedNavigation) {
+        this._triggerBoundaryScrollOnExitIfNeeded(current, bestCandidate, direction)
+      }
+      this._doFocusElement(bestCandidate)
+    } else {
+      // 全局寻焦没找到候选者（到达了真正的边界）
+      // 此时，如果当前元素在某个 List 中，且方向是向边界方向，
+      // 我们需要触发该 List 的边界滚动（如回滚到顶部/底部）。
+      if (this.options.useDistanceBasedNavigation) {
+        this._triggerBoundaryScrollIfNeeded(current, direction)
+      }
+    }
+  }
+
+  _triggerBoundaryScrollOnExitIfNeeded(current, next, direction) {
+    if (!current || !next) return
+    let parent = current.parentElement
+    while (parent && parent !== document.body) {
+      if (parent.__fastListViewInstance) {
+        if (!parent.contains(next)) {
+          const fastList = parent.__fastListViewInstance
+          if (fastList && typeof fastList._scrollToBoundary === 'function') {
+            fastList._scrollToBoundary(direction, current)
+          }
+        }
+      }
+      parent = parent.parentElement
+    }
+  }
+
+  /**
+   * 当焦点无法继续移动时，检查是否需要触发列表的边界滚动
+   */
+  _triggerBoundaryScrollIfNeeded(current, direction) {
+    // 向上查找所有可能包含滚动逻辑的容器
+    let parent = current.parentElement
+    while (parent && parent !== document.body) {
+      if (parent.__fastListViewInstance) {
+        const fastList = parent.__fastListViewInstance
+
+        // 我们需要判断当前焦点是否处于这个列表的“逻辑第一行”或“逻辑最后一行”
+        // 最简单的方法是直接调用它的滚动边界方法，
+        // 或者让 fastList 内部判断并执行
+        if (typeof fastList._scrollToBoundary === 'function') {
+          // FastListView 会根据方向判断是否需要滚动，传入 current 让它自己判断是否在边缘
+          fastList._scrollToBoundary(direction, current)
+          // 我们继续向上遍历，因为可能有多层嵌套列表都需要响应（比如内层是水平列表，外层是垂直列表）
+          // 但对于同一个方向，通常只处理最近的一层即可。
+          // 不过为了安全起见，这里不 break，让所有的父列表都有机会检查边界
+        }
+      }
+      parent = parent.parentElement
+    }
+  }
+
+  /**
+   * 尝试 FastListView 焦点导航
+   * 如果当前焦点在 FastListView 内，委托给 FastListView 处理
+   */
+  _tryFastListViewNavigation(current, direction) {
+    // 向上查找 FastListView 容器
+    let parent = current.parentElement
+    let fastListViewInstance = null
+
+    while (parent) {
+      if (parent.__fastListViewInstance) {
+        fastListViewInstance = parent.__fastListViewInstance
+        break
+      }
+      parent = parent.parentElement
+    }
+
+    if (!fastListViewInstance) return null
+
+    // 如果启用了基于距离的全局导航，我们不再依赖局部的 FastListView 导航
+    // 直接让外层基于全屏坐标计算焦点，这样可以无缝处理 List 嵌套 List (如 Waterfall) 的问题
+    // 在复杂的嵌套布局中，局部的 _handleFocusNavigation 往往会因为视野受限而找不到最优解。
+    // 但是，全局导航无法处理列表滚动边界的特殊需求（比如焦点在列表顶端，按上应该让列表滚动到最顶部）。
+    // 所以我们依然让局部处理一下，但告诉它不要返回“未找到”或者处理失败，而是让它专注于“边界滚动”或特殊的内部逻辑。
+
+    // 我们可以在全局寻找之后，如果找不到合适的焦点，再考虑是不是触发了边界滚动。
+    // 或者更优雅的做法是：全局寻焦只负责“找焦点”。
+    // 当找到下一个焦点时，我们判断这个焦点是否导致了某个容器（List）的滚动。
+    // 但是如果找不到焦点（比如已经在最上面了），我们依然需要通知相关的容器“你触顶了”。
+
+    // 为了兼容滚动到顶部的逻辑，我们依然调用一下局部的处理，
+    // 但是我们给它传一个特殊的标记，让它只处理边界逻辑，不处理焦点导航。
+    // 由于我们不能修改 API 签名太多，这里我们直接返回 null，把边界滚动逻辑放在焦点没有改变时处理。
+    if (this.options.useDistanceBasedNavigation) {
+      return null
+    }
+
+    // 委托给 FastListView 处理
+    const nextElement = fastListViewInstance.handleFocusNavigation(current, direction)
+    if (nextElement) {
+      this._log('[TVFocus] FastListView handled navigation:', direction)
+      return nextElement
+    }
+
+    return null
+  }
+
+  /**
+   * 根据距离计算找到最佳候选元素
+   */
+  _findBestCandidateByDistance(current, direction) {
+    const currentRect = current.getBoundingClientRect()
+    const currentCenter = {
+      x: currentRect.left + currentRect.width / 2,
+      y: currentRect.top + currentRect.height / 2,
+    }
+
+    let bestCandidate = null
+    let bestDistance = Infinity
+    const crossWeight = this.options.crossDistanceWeight
+
+    this.focusableElements.forEach((el) => {
+      // 跳过当前焦点元素
+      if (el === current) return
+
+      // Skip elements no longer in the DOM or hidden
+      if (!el || !document.body.contains(el)) return
+      const computedStyle = window.getComputedStyle(el)
+      if (computedStyle.display === 'none' || computedStyle.visibility === 'hidden') return
+
+      const rect = el.getBoundingClientRect()
+      // Skip 0-sized elements
+      if (rect.width === 0 && rect.height === 0) return
+
+      const center = {
+        x: rect.left + rect.width / 2,
+        y: rect.top + rect.height / 2,
+      }
+
+      // 计算向量：从当前元素指向目标元素
+      const dx = center.x - currentCenter.x
+      const dy = center.y - currentCenter.y
+
+      // 判断是否在指定方向上：方向分量 > 0
+      let isInDirection = false
+      let primaryDistance = 0
+      let crossDistance = 0
+
+      // 1. 基础方向判断：不仅看中心点，也看边界是否有足够覆盖，同时加一些像素容差避免被忽略。
+      switch (direction) {
+        case 'up':
+          isInDirection = dy < 0 || rect.bottom < currentRect.top + 10
+          primaryDistance = Math.max(0, currentRect.top - rect.bottom)
+          crossDistance = Math.abs(dx)
+          break
+        case 'down':
+          isInDirection = dy > 0 || rect.top > currentRect.bottom - 10
+          primaryDistance = Math.max(0, rect.top - currentRect.bottom)
+          crossDistance = Math.abs(dx)
+          break
+        case 'left':
+          isInDirection = dx < 0 || rect.right < currentRect.left + 10
+          primaryDistance = Math.max(0, currentRect.left - rect.right)
+          crossDistance = Math.abs(dy)
+          break
+        case 'right':
+          isInDirection = dx > 0 || rect.left > currentRect.right - 10
+          primaryDistance = Math.max(0, rect.left - currentRect.right)
+          crossDistance = Math.abs(dy)
+          break
+      }
+
+      // 2. 角度限制判断（Cone/Angle Limit）
+      // 如果按右，即使元素在右下角，如果角度太陡（> 45度），也不应该被认为是“右侧”的元素，而应该是“下侧”的元素。
+      // 我们通过计算中心点连线的夹角来判断。tan(theta) = crossDistance / primaryCenterDistance
+      // 当 crossDistance > primaryCenterDistance 时，角度 > 45度。
+      if (isInDirection) {
+        // 使用中心点距离来计算角度是最准确的
+        const absDx = Math.abs(dx)
+        const absDy = Math.abs(dy)
+        let angleExceeded = false
+
+        // 为了防止相邻元素（距离很近）因为细微的高低差导致角度变得极大而被误杀，
+        // 我们只对“非重叠”或者“主方向距离有一定跨度”的元素进行严格的角度限制。
+        if (direction === 'left' || direction === 'right') {
+          // 左右移动时，如果垂直偏移量(dy)大于水平偏移量(dx)，则角度大于45度
+          // 添加 20px 的宽容度，避免相邻元素轻微错位被过滤
+          if (absDy > absDx + 20) {
+            angleExceeded = true
+          }
+        } else {
+          // 上下移动时，如果水平偏移量(dx)大于垂直偏移量(dy)，则角度大于45度
+          if (absDx > absDy + 20) {
+            angleExceeded = true
+          }
+        }
+
+        if (angleExceeded) {
+          console.log(
+            `[TVFocus] Candidate rejected by >45 degree angle limit - tag: ${el.tagName}, dx: ${dx.toFixed(1)}, dy: ${dy.toFixed(1)}`
+          )
+          isInDirection = false
+        }
+      }
+
+      if (isInDirection) {
+        // --- 处理 blockFocusDirections 的边界拦截 ---
+        // 外层容器（比如 List）可能会设置 blockFocusDirections="left,right"。
+        // 它的目的是防止焦点“溢出”这个容器，而不是阻止容器内部子元素之间的移动。
+        // 所以我们检查候选元素 `el` 是否和当前元素 `current` 在同一个受限的容器内。
+        // 如果不在，说明这一步移动跨越了受限容器的边界，应当被阻断。
+        let isBlockedByContainer = false
+        let parent = current.parentElement
+        while (parent && parent !== document.body) {
+          const blockAttr =
+            parent.getAttribute('blockFocusDirections') ||
+            parent.getAttribute('blockfocusdirections')
+          if (blockAttr) {
+            // 解析方向
+            let blockedDirections = []
+            try {
+              blockedDirections = JSON.parse(blockAttr.replace(/'/g, '"'))
+              if (!Array.isArray(blockedDirections)) blockedDirections = []
+            } catch (e) {
+              blockedDirections = blockAttr
+                .split(',')
+                .map((d) => d.trim().toLowerCase())
+                .filter((d) => d)
+            }
+
+            // 如果这个容器限制了当前移动的方向
+            if (blockedDirections.some((d) => d.toLowerCase() === direction.toLowerCase())) {
+              // 检查候选元素是否依然在这个容器内
+              // 如果候选元素不在这个容器内，说明当前移动试图“逃出”该容器，必须被阻断
+              if (!parent.contains(el)) {
+                isBlockedByContainer = true
+                break
+              }
+            }
+          }
+          parent = parent.parentElement
+        }
+
+        // 如果被容器边界阻断，跳过该候选者
+        if (isBlockedByContainer) {
+          console.log(
+            `[TVFocus] Candidate rejected by container blockFocusDirections - tag: ${el.tagName}, id: ${el.id}`
+          )
+          return // return from forEach callback
+        }
+
+        // 改进距离算法：
+        // 1. 如果在对应方向的同一直线上（例如横向移动时，y坐标重叠部分较大），侧向距离应该被忽略或极小化
+        // 2. 如果不在同一直线上，侧向距离应该被放大（惩罚），从而优先选择同一行的元素
+        let isOverlapping = false
+        let overlapRatio = 0
+
+        if (direction === 'left' || direction === 'right') {
+          // 判断垂直方向是否有重叠
+          const overlapY = Math.max(
+            0,
+            Math.min(rect.bottom, currentRect.bottom) - Math.max(rect.top, currentRect.top)
+          )
+          isOverlapping = overlapY > 0
+          overlapRatio = overlapY / Math.min(rect.height, currentRect.height)
+
+          if (!isOverlapping) {
+            // 如果完全没有重叠，说明在不同行，施加极大惩罚，避免焦点跳行
+            crossDistance *= 50
+          } else {
+            // 如果有重叠，根据重叠比例来减少侧向距离的影响
+            // 重叠越多，侧向距离影响越小
+            crossDistance *= 1 - overlapRatio * 0.9
+          }
+        } else if (direction === 'up' || direction === 'down') {
+          // 判断水平方向是否有重叠
+          const overlapX = Math.max(
+            0,
+            Math.min(rect.right, currentRect.right) - Math.max(rect.left, currentRect.left)
+          )
+          isOverlapping = overlapX > 0
+          overlapRatio = overlapX / Math.min(rect.width, currentRect.width)
+
+          if (!isOverlapping) {
+            // 如果完全没有重叠，说明在不同列，施加极大惩罚
+            crossDistance *= 50
+          } else {
+            // 如果有重叠，说明在同一列，降低侧向距离的影响
+            crossDistance *= 1 - overlapRatio * 0.9
+          }
+        }
+
+        // 为了防止“跨行/跨列斜向移动”的优先级高于“本行/本列稍远距离的移动”
+        // 我们需要把主方向距离和加权后的侧向距离相加，
+        // 并且如果是不重叠的（跨行/列），给予一个基础的巨大惩罚值
+        const distance = primaryDistance + crossDistance + (isOverlapping ? 0 : 10000)
+
+        console.log(
+          `[TVFocus] Candidate - tag: ${el.tagName}, id: ${el.id}, dx: ${dx.toFixed(1)}, dy: ${dy.toFixed(1)}, primary: ${primaryDistance.toFixed(1)}, cross: ${crossDistance.toFixed(1)}, overlap: ${isOverlapping}, distance: ${distance.toFixed(1)}`
+        )
+
+        if (distance < bestDistance) {
+          bestDistance = distance
+          bestCandidate = el
+        }
+      }
+    })
+
+    if (bestCandidate) {
+      console.log(
+        `[TVFocus] Best candidate found for direction ${direction}, distance: ${bestDistance.toFixed(1)}`,
+        bestCandidate
+      )
+    } else {
+      console.log(`[TVFocus] No candidate found for direction ${direction}`)
+    }
+
+    return bestCandidate
+  }
+
+  /**
+   * 简单顺序导航：按 DOM 顺序找到下一个可聚焦元素
+   */
+  _findBestCandidateSequential(current, direction) {
+    const currentIndex = this.focusableElements.indexOf(current)
+    if (currentIndex === -1) return null
+
+    // 根据方向决定查找顺序
+    if (direction === 'down' || direction === 'right') {
+      // 向下/向右：查找后面的元素
+      for (let i = currentIndex + 1; i < this.focusableElements.length; i++) {
+        const el = this.focusableElements[i]
+        if (el && document.body.contains(el)) {
+          return el
+        }
+      }
+    } else if (direction === 'up' || direction === 'left') {
+      // 向上/向左：查找前面的元素
+      for (let i = currentIndex - 1; i >= 0; i--) {
+        const el = this.focusableElements[i]
+        if (el && document.body.contains(el)) {
+          return el
+        }
+      }
+    }
+
+    return null
+  }
+
+  // Check if the element blocks focus movement in a specific direction
+  // blockFocusDirections can be:
+  // - Array: ['left', 'right'] or ['up', 'down', 'left', 'right']
+  // - String (JSON array): "['left', 'right']" or '["left", "right"]'
+  // direction can be:
+  // - String: 'left', 'up', 'right', 'down'
+  // - Number: QTFocusDirection enum value (17, 33, 66, 130)
+  _isDirectionBlocked(element, direction) {
+    // Check element and all its parents up to the body
+    let currentEl = element
+    while (currentEl && currentEl !== document.body) {
+      const blockAttr =
+        currentEl.getAttribute('blockFocusDirections') ||
+        currentEl.getAttribute('blockfocusdirections')
+
+      if (blockAttr) {
+        // Convert direction number to name if needed
+        let directionName = direction
+        if (typeof direction === 'number') {
+          directionName = this._directionNumberToName(direction)
+          // If it's forward/backward, they don't block
+          if (!directionName || directionName === 'forward' || directionName === 'backward') {
+            return false
+          }
+        }
+
+        let blockedDirections = []
+
+        try {
+          // Try to parse as JSON array
+          // Handle both single quotes and double quotes
+          const normalized = blockAttr.replace(/'/g, '"')
+          blockedDirections = JSON.parse(normalized)
+
+          if (!Array.isArray(blockedDirections)) {
+            blockedDirections = []
+          }
+        } catch (e) {
+          // If not valid JSON, try comma-separated string
+          blockedDirections = blockAttr
+            .split(',')
+            .map((d) => d.trim().toLowerCase())
+            .filter((d) => d)
+        }
+
+        // Normalize direction for comparison
+        const normalizedDirection = String(directionName).toLowerCase()
+
+        if (blockedDirections.some((blocked) => blocked.toLowerCase() === normalizedDirection)) {
+          // 找到了 blockFocusDirections 配置
+
+          // 【核心修复】：判断是不是真正的“溢出边缘”
+          // 如果当前元素配置了 blockFocusDirections，但我们要寻找的下一个焦点依然在这个容器内部，
+          // 那么不应该被阻断！block 仅仅是防止焦点逃出这个容器。
+          // 但是 _isDirectionBlocked 是在找下一个元素前调用的，我们怎么知道下一个元素在不在容器里？
+          // 所以这里我们不再进行彻底阻断，而是返回 `false` 放行，
+          // 把容器的边界判断交给 `_findBestCandidateByDistance` 中的后续逻辑去处理，
+          // 或者在这里，仅仅当“当前获取焦点的元素，已经处于该容器的最边缘”时，才阻断。
+
+          // 既然如此，我们只允许元素自身的 block 彻底阻断。
+          // 对于父容器的 block，我们在这里一律不阻断。
+          if (currentEl === element) {
+            return true
+          }
+        }
+      }
+      currentEl = currentEl.parentElement
+    }
+
+    return false
+  }
+
+  /**
+   * 解析 showOnState 属性值
+   * @param {string} attrValue - showOnState 属性值
+   * @returns {string[]} - 状态数组
+   */
+  _parseShowOnState(attrValue) {
+    if (!attrValue) return null
+
+    // 尝试解析为 JSON 数组
+    try {
+      const parsed = JSON.parse(attrValue)
+      if (Array.isArray(parsed)) {
+        return parsed.map((s) => String(s).toLowerCase())
+      }
+    } catch (e) {
+      // 不是 JSON，作为单个状态字符串处理
+    }
+
+    // 作为单个状态字符串处理
+    return [String(attrValue).toLowerCase()]
+  }
+
+  /**
+   * 检查元素是否应该在指定状态显示
+   * @param {HTMLElement} element - 要检查的元素
+   * @param {string} state - 当前状态 ('normal', 'focused', 'selected')
+   * @returns {boolean|null} - 是否应该显示，null 表示没有 showOnState 属性
+   */
+  _shouldShowOnState(element, state) {
+    const showOnStateAttr = element.getAttribute('showOnState')
+    if (!showOnStateAttr) return null
+
+    const states = this._parseShowOnState(showOnStateAttr)
+    if (!states || states.length === 0) return null
+
+    return states.includes(state.toLowerCase())
+  }
+
+  /**
+   * 更新元素及其子元素的 showOnState 可见性
+   * @param {HTMLElement} element - 父元素
+   * @param {string} state - 当前状态 ('normal', 'focused', 'selected')
+   */
+  _updateShowOnStateVisibility(element, state) {
+    // 更新元素自身的可见性
+    const shouldShow = this._shouldShowOnState(element, state)
+    if (shouldShow !== null) {
+      if (shouldShow) {
+        element.style.display = ''
+        element.style.visibility = ''
+      } else {
+        element.style.display = 'none'
+      }
+    }
+
+    // 更新所有带 showOnState 属性的子元素
+    const showOnStateChildren = element.querySelectorAll('[showOnState]')
+    showOnStateChildren.forEach((child) => {
+      const childShouldShow = this._shouldShowOnState(child, state)
+      if (childShouldShow !== null) {
+        if (childShouldShow) {
+          child.style.display = ''
+          child.style.visibility = ''
+        } else {
+          child.style.display = 'none'
+        }
+      }
+    })
+  }
+
+  /**
+   * 初始化所有带 showOnState 属性元素的可见性
+   * 默认设置为 'normal' 状态
+   */
+  _initShowOnStateVisibility() {
+    const showOnStateElements = document.querySelectorAll('[showOnState]')
+    showOnStateElements.forEach((element) => {
+      // 检查元素是否有 duplicateParentState 属性
+      const hasDuplicateParentState =
+        element.hasAttribute('duplicateParentState') || element.hasAttribute('duplicateparentstate')
+
+      // 检查元素是否在已获得焦点的元素内
+      const focusedParent = element.closest('.focused')
+
+      if (focusedParent) {
+        // 如果在已获得焦点的元素内，使用 focused 状态
+        this._updateShowOnStateVisibilityForElement(element, 'focused')
+      } else {
+        // 否则使用 normal 状态
+        this._updateShowOnStateVisibilityForElement(element, 'normal')
+      }
+    })
+  }
+
+  /**
+   * 更新单个元素的 showOnState 可见性
+   * @param {HTMLElement} element - 元素
+   * @param {string} state - 当前状态
+   */
+  _updateShowOnStateVisibilityForElement(element, state) {
+    const shouldShow = this._shouldShowOnState(element, state)
+    if (shouldShow !== null) {
+      if (shouldShow) {
+        element.style.display = ''
+        element.style.visibility = ''
+      } else {
+        element.style.display = 'none'
+      }
+    }
+  }
+
+  /**
+   * 初始化元素及其子元素的 showOnState 可见性（公开方法）
+   * 用于动态创建的元素（如列表项）的初始化
+   * @param {HTMLElement} container - 容器元素
+   */
+  initShowOnStateForElement(container) {
+    if (!container) return
+
+    // 查找容器内所有带 showOnState 属性的元素
+    const showOnStateElements = container.querySelectorAll('[showOnState]')
+    console.log(
+      '[TVFocusManager] initShowOnStateForElement found',
+      showOnStateElements.length,
+      'elements with showOnState'
+    )
+
+    showOnStateElements.forEach((element) => {
+      // 检查元素是否在已获得焦点的元素内
+      const focusedParent = element.closest('.focused')
+      const selectedParent = element.closest('[selected="true"], [selected=""]')
+
+      if (focusedParent) {
+        this._updateShowOnStateVisibilityForElement(element, 'focused')
+      } else if (selectedParent) {
+        this._updateShowOnStateVisibilityForElement(element, 'selected')
+      } else {
+        this._updateShowOnStateVisibilityForElement(element, 'normal')
+      }
+    })
+  }
+
+  _getFocusProps(element) {
+    // Get computed style for CSS variable reading and original borderRadius
+    const computedStyle = window.getComputedStyle(element)
+
+    // 获取元素原本的 borderRadius 作为默认值
+    const originalBorderRadius = computedStyle.borderRadius
+    let defaultBorderRadius = this.defaultFocusStyle.border.cornerRadius || 8
+    if (originalBorderRadius && originalBorderRadius !== 'none' && originalBorderRadius !== '0px') {
+      // 解析 borderRadius，可能包含多个值（如 "8px 8px 8px 8px"）
+      const radiusMatch = originalBorderRadius.match(/^(\d+(?:\.\d+)?)(px)?/)
+      if (radiusMatch) {
+        defaultBorderRadius = parseFloat(radiusMatch[1])
+      }
+    }
+
+    // Use global focus config as defaults
+    const props = {
+      enableBorder: false, // 默认不显示边框
+      borderColor: this.defaultFocusStyle.border.color,
+      borderWidth: this.defaultFocusStyle.border.width,
+      borderRadius: defaultBorderRadius,
+      innerBorderColor: this.defaultFocusStyle.border.innerColor,
+      innerBorderWidth: this.defaultFocusStyle.border.innerWidth,
+      innerBorderEnabled: this.defaultFocusStyle.border.innerEnabled !== false,
+      scale: this.defaultFocusStyle.scale,
+      focusBackgroundColor: null,
+      focusColor: null,
+    }
+
+    const enableFocusBorder =
+      element.getAttribute('enableFocusBorder') || element.getAttribute('enable-focus-border')
+    // 只有显式设置 enableFocusBorder="true" 或 "1" 才启用边框
+    if (enableFocusBorder === 'true' || enableFocusBorder === '1' || enableFocusBorder === '') {
+      props.enableBorder = true
+    }
+
+    const focusScale =
+      element.getAttribute('focusScale') ||
+      element.getAttribute('focus-scale') ||
+      element.getAttribute('data-focus-scale') ||
+      computedStyle.getPropertyValue('--focus-scale')?.trim()
+    if (focusScale) {
+      const scale = parseFloat(focusScale)
+      if (!isNaN(scale) && scale > 0) {
+        props.scale = scale
+      }
+    }
+
+    const focusBorderRadius =
+      element.getAttribute('focusBorderRadius') ||
+      element.getAttribute('focus-border-radius') ||
+      element.getAttribute('data-focus-border-radius') ||
+      computedStyle.getPropertyValue('--focus-border-radius')?.trim()
+    if (focusBorderRadius) {
+      const radius = parseFloat(focusBorderRadius)
+      if (!isNaN(radius) && radius >= 0) {
+        props.borderRadius = radius
+      }
+    }
+
+    const focusBorderWidth =
+      element.getAttribute('focusBorderWidth') ||
+      element.getAttribute('focus-border-width') ||
+      element.getAttribute('data-focus-border-width') ||
+      computedStyle.getPropertyValue('--focus-border-width')?.trim()
+    if (focusBorderWidth) {
+      const width = parseFloat(focusBorderWidth)
+      if (!isNaN(width) && width >= 0) {
+        props.borderWidth = width
+      }
+    }
+
+    const focusBorderColor =
+      element.getAttribute('focusBorderColor') ||
+      element.getAttribute('focus-border-color') ||
+      element.getAttribute('data-focus-border-color') ||
+      computedStyle.getPropertyValue('--focus-border-color')?.trim()
+    if (focusBorderColor) {
+      props.borderColor = focusBorderColor
+    }
+
+    const focusBorderAttr = element.getAttribute('data-focus-border')
+    if (focusBorderAttr) {
+      props.enableBorder = focusBorderAttr === 'true'
+    }
+
+    // Focus background color - check attributes first, then CSS variables
+    const focusBackgroundColor =
+      element.getAttribute('focusBackgroundColor') ||
+      element.getAttribute('focus-background-color') ||
+      element.getAttribute('data-focus-background-color') ||
+      computedStyle.getPropertyValue('--focus-background-color')?.trim() ||
+      computedStyle.getPropertyValue('--focus-background')?.trim()
+    if (focusBackgroundColor) {
+      props.focusBackgroundColor = focusBackgroundColor
+    }
+
+    // Focus text color - check attributes first, then CSS variables
+    const focusColor =
+      element.getAttribute('focusColor') ||
+      element.getAttribute('focus-color') ||
+      element.getAttribute('data-focus-color') ||
+      computedStyle.getPropertyValue('--focus-color')?.trim()
+    if (focusColor) {
+      props.focusColor = focusColor
+    }
+
+    return props
+  }
+
+  // 内部方法：直接设置焦点元素
+  _doFocusElement(element) {
+    if (!element) return
+
+    const prevFocused = this.focusedElement
+    if (prevFocused) {
+      this._maybeNotifyFastListItemFocusChanged(prevFocused, false)
+      this._removeFocusStyle(prevFocused)
+    }
+
+    this.focusedElement = element
+
+    this._applyFocusStyle(this.focusedElement)
+    this.focusedElement.classList.add('focused')
+    this.focusedElement.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+    this._maybeScrollFastListToStart(this.focusedElement)
+    this._maybeUpdateFastListBlockFocusDirections(this.focusedElement)
+    this._maybeNotifyFastListItemFocusChanged(this.focusedElement, true)
+
+    // console.log('[TVFocus] Focused element', element)
+  }
+
+  _maybeNotifyFastListItemFocusChanged(element, hasFocus) {
+    if (!element) return
+    let parent = element.parentElement
+    let fastListViewInstance = null
+    while (parent) {
+      if (parent.__fastListViewInstance) {
+        fastListViewInstance = parent.__fastListViewInstance
+        break
+      }
+      parent = parent.parentElement
+    }
+    if (fastListViewInstance && typeof fastListViewInstance.notifyItemFocusChanged === 'function') {
+      fastListViewInstance.notifyItemFocusChanged(element, hasFocus)
+    }
+  }
+
+  _maybeUpdateFastListBlockFocusDirections(element) {
+    if (!element) return
+    let parent = element.parentElement
+    let fastListViewInstance = null
+    while (parent) {
+      if (parent.__fastListViewInstance) {
+        fastListViewInstance = parent.__fastListViewInstance
+        break
+      }
+      parent = parent.parentElement
+    }
+    if (
+      fastListViewInstance &&
+      typeof fastListViewInstance.updateBlockFocusDirections === 'function'
+    ) {
+      fastListViewInstance.updateBlockFocusDirections(element)
+    }
+  }
+
+  _maybeScrollFastListToStart(element) {
+    if (!element || !element.closest) return
+
+    const item = element.closest('[data-position]') || element.closest('[data-index]')
+    if (!item) return
+
+    const rawPos = item.getAttribute('data-position') ?? item.getAttribute('data-index')
+    if (rawPos === null || rawPos === undefined) return
+    const pos = Number(rawPos)
+    if (!Number.isFinite(pos) || pos !== 0) return
+
+    const container = element.closest('.fast-list-item-container')
+    if (!container) return
+
+    const style = window.getComputedStyle(container)
+    const isHorizontal =
+      style.flexDirection === 'row' || style.overflowX === 'auto' || style.overflowX === 'scroll'
+    if (!isHorizontal) return
+
+    if (container.scrollLeft > 0) {
+      try {
+        container.scrollTo({ left: 0, behavior: 'smooth' })
+      } catch (e) {
+        container.scrollLeft = 0
+      }
+    }
+
+    const parent = container.parentElement
+    if (parent && parent.scrollLeft > 0) {
+      try {
+        parent.scrollTo({ left: 0, behavior: 'smooth' })
+      } catch (e) {
+        parent.scrollLeft = 0
+      }
+    }
+  }
+
+  // 兼容方法：通过索引设置焦点
+  setFocus(index) {
+    if (index < 0 || index >= this.focusableElements.length) return
+    this._doFocusElement(this.focusableElements[index])
+  }
+
+  _applyFocusStyle(element) {
+    const props = this._getFocusProps(element)
+
+    const originalStyles = {
+      transform: element.style.transform,
+      outline: element.style.outline,
+      outlineOffset: element.style.outlineOffset,
+      boxShadow: element.style.boxShadow,
+      transition: element.style.transition,
+      zIndex: element.style.zIndex,
+      borderRadius: element.style.borderRadius,
+      backgroundColor: element.style.backgroundColor,
+      color: element.style.color,
+      display: element.style.display,
+      visibility: element.style.visibility,
+    }
+    this.focusedElementOriginalStyles.set(element, originalStyles)
+
+    element.style.transition = this.defaultFocusStyle.transition
+
+    if (props.scale !== 1.0) {
+      element.style.transform = `scale(${props.scale})`
+      element.style.zIndex = '10'
+    }
+
+    if (props.enableBorder) {
+      element.style.borderRadius = props.borderRadius + 'px'
+      const spread = props.borderWidth
+      const innerSpread = props.innerBorderWidth
+      // Only add inner border if enabled
+      const innerShadow = props.innerBorderEnabled
+        ? `inset 0 0 0 ${innerSpread}px ${props.innerBorderColor}`
+        : ''
+      element.style.boxShadow = `0 0 0 ${spread}px ${props.borderColor}, ${innerShadow}, 0 4px 12px rgba(0,0,0,0.3)`
+      element.style.outline = 'none'
+    }
+
+    // Apply focusBackgroundColor if specified
+    if (props.focusBackgroundColor) {
+      element.style.backgroundColor = props.focusBackgroundColor
+    }
+
+    // Apply focusColor if specified (for elements that have text)
+    if (props.focusColor) {
+      element.style.color = props.focusColor
+    }
+
+    // Handle duplicateParentState children - apply focus styles to children with duplicateParentState="true"
+    this._applyDuplicateParentStateStyles(element)
+
+    // Handle showOnState - update visibility based on focused state
+    this._updateShowOnStateVisibility(element, 'focused')
+
+    requestAnimationFrame(() => syncDomAutoWidthIn(element))
+  }
+
+  // Apply focus styles to children with duplicateParentState attribute
+  // Supports: duplicateParentState, duplicateParentState="true", duplicateParentState=""
+  _applyDuplicateParentStateStyles(parentElement) {
+    // Match elements with duplicateParentState attribute present (regardless of value)
+    // This handles both <div duplicateParentState> and <div duplicateParentState="true">
+    const duplicateChildren = parentElement.querySelectorAll('[duplicateparentstate]')
+
+    duplicateChildren.forEach((child) => {
+      // Skip if explicitly set to false
+      const attrValue = child.getAttribute('duplicateparentstate')
+      if (attrValue === 'false' || attrValue === '0') {
+        return
+      }
+
+      // Get focus styles from multiple sources:
+      // 1. Child's own focus attributes
+      // 2. Data attributes (from style extraction)
+      // 3. CSS custom properties (--focus-color, --focus-background-color)
+
+      const computedStyle = window.getComputedStyle(child)
+
+      // Helper to get focus attribute from multiple sources
+      const getFocusAttr = (attrName, kebabName) => {
+        return (
+          child.getAttribute(attrName) ||
+          child.getAttribute(kebabName) ||
+          child.getAttribute('data-' + kebabName) ||
+          computedStyle.getPropertyValue('--' + kebabName)?.trim()
+        )
+      }
+
+      // Get all focus style attributes
+      const focusColor =
+        getFocusAttr('focusColor', 'focus-color') ||
+        getFocusAttr('focusTextColor', 'focus-text-color')
+      const focusBackgroundColor = getFocusAttr('focusBackgroundColor', 'focus-background-color')
+      const focusBorderRadius = getFocusAttr('focusBorderRadius', 'focus-border-radius')
+      const focusScale = getFocusAttr('focusScale', 'focus-scale')
+      const focusBorderWidth = getFocusAttr('focusBorderWidth', 'focus-border-width')
+      const focusBorderColor = getFocusAttr('focusBorderColor', 'focus-border-color')
+
+      // Check if enableFocusBorder is set
+      const enableFocusBorder =
+        child.getAttribute('enableFocusBorder') || child.getAttribute('enable-focus-border')
+      const shouldShowBorder =
+        enableFocusBorder === 'true' || enableFocusBorder === '1' || enableFocusBorder === ''
+
+      // Store original styles
+      const originalStyles = {
+        backgroundColor: child.style.backgroundColor,
+        color: child.style.color,
+        borderRadius: child.style.borderRadius,
+        transform: child.style.transform,
+        zIndex: child.style.zIndex,
+        transition: child.style.transition,
+        outline: child.style.outline,
+        outlineOffset: child.style.outlineOffset,
+      }
+      this.focusedElementOriginalStyles.set(child, originalStyles)
+
+      // Apply transition
+      child.style.transition = this.defaultFocusStyle.transition
+
+      // Apply focus styles
+      if (focusBackgroundColor) {
+        child.style.backgroundColor = focusBackgroundColor
+      }
+
+      if (focusColor) {
+        child.style.color = focusColor
+      }
+
+      if (focusBorderRadius) {
+        const radius = parseFloat(focusBorderRadius)
+        if (!isNaN(radius) && radius >= 0) {
+          child.style.borderRadius = radius + 'px'
+        }
+      }
+
+      if (focusScale) {
+        const scale = parseFloat(focusScale)
+        if (!isNaN(scale) && scale > 0 && scale !== 1) {
+          child.style.transform = `scale(${scale})`
+          child.style.zIndex = '10'
+        }
+      }
+
+      // Apply border if enableFocusBorder is set
+      if (shouldShowBorder) {
+        const borderWidth = focusBorderWidth ? parseFloat(focusBorderWidth) : 3
+        const borderColor = focusBorderColor || '#FFFFFF'
+        const borderRadius = focusBorderRadius ? parseFloat(focusBorderRadius) : 8
+
+        child.style.outline = `${borderWidth}px solid ${borderColor}`
+        child.style.outlineOffset = '0px'
+        child.style.borderRadius = borderRadius + 'px'
+      }
+
+      // Add focused class to child as well (for CSS-based styling)
+      child.classList.add('focused-child')
+
+      // Handle showOnState for duplicateParentState children
+      // When parent is focused, update child visibility based on showOnState
+      const childShowOnState = this._shouldShowOnState(child, 'focused')
+      if (childShowOnState !== null) {
+        // Store original display value
+        const originalDisplay = child.style.display
+        if (!this.focusedElementOriginalStyles.has(child)) {
+          this.focusedElementOriginalStyles.set(child, { display: originalDisplay })
+        } else {
+          const existing = this.focusedElementOriginalStyles.get(child)
+          existing.display = originalDisplay
+        }
+
+        if (childShowOnState) {
+          child.style.display = ''
+        } else {
+          child.style.display = 'none'
+        }
+      }
+    })
+  }
+
+  _removeFocusStyle(element) {
+    const originalStyles = this.focusedElementOriginalStyles.get(element)
+    if (originalStyles) {
+      element.style.transform = originalStyles.transform
+      element.style.outline = originalStyles.outline
+      element.style.outlineOffset = originalStyles.outlineOffset
+      element.style.boxShadow = originalStyles.boxShadow
+      element.style.transition = originalStyles.transition
+      element.style.zIndex = originalStyles.zIndex
+      element.style.borderRadius = originalStyles.borderRadius
+      if (originalStyles.backgroundColor !== undefined) {
+        element.style.backgroundColor = originalStyles.backgroundColor
+      }
+      if (originalStyles.color !== undefined) {
+        element.style.color = originalStyles.color
+      }
+    } else {
+      element.style.transform = ''
+      element.style.outline = ''
+      element.style.outlineOffset = ''
+      element.style.boxShadow = ''
+      element.style.zIndex = ''
+    }
+    element.classList.remove('focused')
+
+    // Remove focus styles from duplicateParentState children
+    this._removeDuplicateParentStateStyles(element)
+
+    // Handle showOnState - update visibility based on normal state
+    this._updateShowOnStateVisibility(element, 'normal')
+
+    requestAnimationFrame(() => syncDomAutoWidthIn(element))
+  }
+
+  // Remove focus styles from children with duplicateParentState attribute
+  _removeDuplicateParentStateStyles(parentElement) {
+    const duplicateChildren = parentElement.querySelectorAll('[duplicateparentstate]')
+
+    duplicateChildren.forEach((child) => {
+      // Skip if explicitly set to false
+      const attrValue = child.getAttribute('duplicateparentstate')
+      if (attrValue === 'false' || attrValue === '0') {
+        return
+      }
+      const originalStyles = this.focusedElementOriginalStyles.get(child)
+      if (originalStyles) {
+        child.style.backgroundColor = originalStyles.backgroundColor
+        child.style.color = originalStyles.color
+        child.style.borderRadius = originalStyles.borderRadius
+        child.style.transform = originalStyles.transform
+        child.style.zIndex = originalStyles.zIndex
+        child.style.transition = originalStyles.transition
+        child.style.outline = originalStyles.outline
+        child.style.outlineOffset = originalStyles.outlineOffset
+      } else {
+        child.style.backgroundColor = ''
+        child.style.color = ''
+        child.style.borderRadius = ''
+        child.style.transform = ''
+        child.style.zIndex = ''
+        child.style.outline = ''
+        child.style.outlineOffset = ''
+      }
+      child.classList.remove('focused-child')
+
+      // Handle showOnState for duplicateParentState children
+      // When parent loses focus, update child visibility based on showOnState for 'normal' state
+      const childShowOnState = this._shouldShowOnState(child, 'normal')
+      if (childShowOnState !== null) {
+        if (childShowOnState) {
+          child.style.display = ''
+        } else {
+          child.style.display = 'none'
+        }
+      }
+
+      this.focusedElementOriginalStyles.delete(child)
+    })
+  }
+
+  clearFocus() {
+    if (this.focusedElement) {
+      this._removeFocusStyle(this.focusedElement)
+    }
+    this.focusedElement = null
+  }
+
+  clickFocused() {
+    if (this.focusedElement) {
+      const element = this.focusedElement
+
+      let handledByComponent = false
+      const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+      if (componentRegistry && componentRegistry.has(element)) {
+        const component = componentRegistry.get(element)
+        if (component.events && component.events.onClick) {
+          component.dispatchEvent('onClick', { nativeEvent: { target: element } })
+          handledByComponent = true
+        }
+      }
+
+      if (!handledByComponent) {
+        const componentId = element.id
+        if (componentId && global.Hippy) {
+          const uiManager = global.Hippy?.context?.getModuleByName?.('UIManagerModule')
+          if (uiManager && uiManager.findViewById) {
+            const component = uiManager.findViewById(componentId)
+            if (component && component.events && component.events.onClick) {
+              component.dispatchEvent('onClick', { nativeEvent: { target: element } })
+              handledByComponent = true
+            }
+          }
+        }
+      }
+
+      // 只有当组件没有处理 onClick 事件时，才调用原生 DOM click
+      // 这样避免 onClick 事件被触发多次（component.dispatchEvent + element.click + handleClick）
+      if (!handledByComponent) {
+        element.click()
+      }
+    }
+  }
+
+  handleClick(e) {
+    // Find the closest focusable element that was clicked
+    let target = e.target
+    const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+
+    while (target && target !== document.body) {
+      // Check if this element is focusable
+      if (target.hasAttribute && target.hasAttribute('focusable')) {
+        // console.log('[TVFocus] Mouse click on focusable element:', target)
+
+        // Update focus to this element
+        if (this.focusableElements.includes(target)) {
+          this._doFocusElement(target)
+        }
+
+        // Dispatch onClick event via Hippy component system
+        if (componentRegistry && componentRegistry.has(target)) {
+          const component = componentRegistry.get(target)
+          // console.log('[TVFocus] Found component for click:', component.tagName)
+
+          if (component.events && component.events.onClick) {
+            // console.log('[TVFocus] Dispatching onClick from mouse click')
+            component.dispatchEvent('onClick', { nativeEvent: e })
+            // Don't prevent default - let the DOM click also propagate
+          }
+        }
+        break
+      }
+
+      // Also check if this is a registered Hippy component
+      if (componentRegistry && componentRegistry.has(target)) {
+        const component = componentRegistry.get(target)
+        // console.log('[TVFocus] Mouse click on Hippy component:', component.tagName)
+
+        // Update focus if the element is focusable
+        if (this.focusableElements.includes(target)) {
+          this._doFocusElement(target)
+        }
+
+        if (component.events && component.events.onClick) {
+          // console.log('[TVFocus] Dispatching onClick from mouse click')
+          component.dispatchEvent('onClick', { nativeEvent: e })
+        }
+        break
+      }
+
+      target = target.parentElement
+    }
+  }
+
+  dispatchBackPressed(e) {
+    console.log('[TVFocusManager] dispatchBackPressed called - emitting hardwareBackPress event')
+
+    // 模拟 Android 平台的硬件返回按键事件
+    // 通过 EventBus 发射 hardwareBackPress 事件
+    // ESCore 监听此事件并调用 router.back()
+    try {
+      // 从 es3-vue 动态获取 EventBus（避免模块级别导入问题）
+      const { EventBus } = require('@extscreen/es3-vue')
+      if (EventBus && EventBus.$emit) {
+        console.log('[TVFocusManager] Emitting hardwareBackPress event')
+        EventBus.$emit('hardwareBackPress')
+      }
+    } catch (err) {
+      console.error('[TVFocusManager] Error emitting hardwareBackPress:', err)
+    }
+  }
+
+  // Focus direction constants (matching QTFocusDirection enum)
+  static FOCUS_DIRECTION = {
+    BACKWARD: 1,
+    FORWARD: 2,
+    LEFT: 17,
+    UP: 33,
+    RIGHT: 66,
+    DOWN: 130,
+  }
+
+  // Convert direction number to direction name
+  _directionNumberToName(directionNum) {
+    const { FOCUS_DIRECTION } = TVFocusManager
+    switch (directionNum) {
+      case FOCUS_DIRECTION.LEFT:
+        return 'left'
+      case FOCUS_DIRECTION.UP:
+        return 'up'
+      case FOCUS_DIRECTION.RIGHT:
+        return 'right'
+      case FOCUS_DIRECTION.DOWN:
+        return 'down'
+      case FOCUS_DIRECTION.FORWARD:
+        return 'forward'
+      case FOCUS_DIRECTION.BACKWARD:
+        return 'backward'
+      default:
+        return null
+    }
+  }
+
+  // Focus a specific DOM element
+  // Used by requestFocus API
+  focusElement(element) {
+    if (!element) return false
+
+    // Ensure focusable elements are up to date
+    if (!this.focusableElements.includes(element)) {
+      this.updateFocusableElements()
+    }
+
+    if (this.focusableElements.includes(element)) {
+      this._doFocusElement(element)
+      return true
+    }
+
+    return false
+  }
+
+  // Move focus from a specific element in a given direction
+  // direction can be a number (QTFocusDirection enum) or string ('left', 'up', 'right', 'down')
+  moveFocusFromElement(element, direction) {
+    if (!element) return false
+
+    // Convert direction number to name if needed
+    let directionName = direction
+    if (typeof direction === 'number') {
+      directionName = this._directionNumberToName(direction)
+    }
+
+    if (!directionName) {
+      // No direction specified, just focus the element
+      return this.focusElement(element)
+    }
+
+    // Handle 'forward' and 'backward' as sequential navigation
+    if (directionName === 'forward' || directionName === 'backward') {
+      // Ensure focusable elements are up to date
+      if (!this.focusableElements.includes(element)) {
+        this.updateFocusableElements()
+      }
+
+      const currentIndex = this.focusableElements.indexOf(element)
+      if (currentIndex < 0) {
+        return this.focusElement(element)
+      }
+
+      let nextIndex
+      if (directionName === 'forward') {
+        nextIndex = (currentIndex + 1) % this.focusableElements.length
+      } else {
+        nextIndex =
+          (currentIndex - 1 + this.focusableElements.length) % this.focusableElements.length
+      }
+
+      this._doFocusElement(this.focusableElements[nextIndex])
+      return true
+    }
+
+    // Ensure the element is in focusable list
+    if (!this.focusableElements.includes(element)) {
+      this.updateFocusableElements()
+    }
+
+    if (!this.focusableElements.includes(element)) {
+      return false
+    }
+
+    // Check if direction is blocked for this element
+    if (this._isDirectionBlocked(element, directionName)) {
+      this._log('[TVFocus] Direction', directionName, 'is blocked for element')
+      return false
+    }
+
+    // 先正确聚焦到指定元素
+    this._doFocusElement(element)
+
+    // 在指定方向上移动焦点
+    this.moveFocus(directionName)
+
+    return true
+  }
+
+  // Clear focus from a specific element
+  clearFocusFromElement(element) {
+    if (this.focusedElement === element) {
+      this.clearFocus()
+      return true
+    }
+    return false
+  }
+}