#UE-Connect 文档

import { UEProvider, useUEContext } from 'ue-connect'

// 在应用根组件中提供上下文
function App() {
  return (
    <UEProvider>
      <YourComponent />
    </UEProvider>
  )
}

// 在子组件中使用上下文
function YourComponent() {
  const { isConnected, isMobile, useMouse, setUseMouse, lastKeyAction } = useUEContext()

  return (
    <div>
      <p>连接状态: {isConnected ? '已连接' : '未连接'}</p>
      <p>设备类型: {isMobile ? '移动设备' : '桌面设备'}</p>
      <p>最近按键: {lastKeyAction || '无'}</p>
      <button onClick={() => setUseMouse(!useMouse)}>{useMouse ? '禁用鼠标' : '启用鼠标'}</button>
    </div>
  )
}

import { useQuickUIEvent, useQuickUIEventListener } from 'ue-connect'

function EventSystemComponent() {
  // 发送事件 - 需要指定事件名称（对应后端QuickUIListenEvent）
  const sendEvent = useQuickUIEventSender('playerUpdate')

  // 监听事件 - 监听来自 UE 的事件（对应后端QuickUIEventCallBack）
  useQuickUIEventListener('gameStateChange', (event) => {
    console.log('游戏状态改变:', event)
    console.log('事件主题:', event.topic)
    console.log('事件载荷:', event.payload)
    console.log('时间戳:', event.timestamp)
    console.log('事件源:', event.source) // "web" 或 "ue"
  })

  const updatePlayer = () => {
    // 发送事件到 UE（fire-and-forget）
    sendEvent({
      health: 100,
      ammo: 30,
      position: { x: 10, y: 20, z: 30 }
    })
  }

  return <button onClick={updatePlayer}>更新玩家数据</button>
}

import { useUEMouse } from 'ue-connect'

function MouseComponent() {
  const { useMouse, setUseMouse } = useUEMouse(true)

  return (
    <div>
      <button onClick={() => setUseMouse(!useMouse)}>{useMouse ? '禁用鼠标事件' : '启用鼠标事件'}</button>

      {/* 这个区域不会触发鼠标事件 */}
      <div data-nohit style={{ padding: '20px', background: '#f0f0f0' }}>
        鼠标事件禁用区域
      </div>
    </div>
  )
}

import { useUEGameControl } from 'ue-connect'

function GameControlComponent() {
  const gameControl = useUEGameControl()

  return (
    <div>
      <button onClick={() => gameControl.quitGame()}>退出游戏</button>
      <button onClick={() => gameControl.executeCommand('stat fps')}>显示FPS</button>
      <button onClick={() => gameControl.clientTravel('127.0.0.1')}>连接到服务器</button>
    </div>
  )
}

import { useDevicePixelRatio } from 'ue-connect'

function ResponsiveComponent() {
  const dpr = useDevicePixelRatio()

  return (
    <div
      style={{
        width: `${100 * dpr}px`,
        height: `${50 * dpr}px`
      }}
    >
      自适应元素
    </div>
  )
}

import { useInputBlocker } from 'ue-connect'

function InputComponent() {
  const { blockInput, unblockInput, isBlocked } = useInputBlocker()

  return (
    <div>
      <button onClick={blockInput}>阻止输入</button>
      <button onClick={unblockInput}>允许输入</button>
      <p>当前状态: {isBlocked ? '输入已阻止' : '输入正常'}</p>
    </div>
  )
}

#### `useInputKeyEventListener`

监听 UE5 引擎发送的按键导航事件（上/下/左/右/确认/上一页/下一页），适用于 TV 端或手柄遥控器等非鼠标输入场景。

```tsx
import { useInputKeyEventListener } from 'ue-connect'

function NavigationComponent() {
  const { lastKeyAction } = useInputKeyEventListener({
    onKeyAction: (action) => {
      console.log('按键事件:', action)
      // action 值为 "Up" | "Down" | "Left" | "Right" | "Next" | "Previous" | "Select"
    }
  })

  return (
    <div>
      <p>最近按键: {lastKeyAction || '无'}</p>
    </div>
  )
}

import { useUEEventJSON } from 'ue-connect'

function EventComponent() {
  const triggerEvent = useUEEventJSON({ functionName: 'MyBlueprintEvent' })

  const handleClick = () => {
    triggerEvent({
      playerName: '玩家1',
      score: 100,
      level: 5,
      items: ['item1', 'item2']
    })
  }

  return <button onClick={handleClick}>发送游戏事件</button>
}

import { useUECallback } from 'ue-connect'

function CallbackComponent() {
  useUECallback('OnPlayerDataUpdated', (onData) => {
    console.log('玩家数据更新:', onData)
    // 处理玩家数据
  })

  return <div>回调组件</div>
}

function filterUECallBackJSonData<T extends Record<string, any>>(
  data: T | undefined,
  filters: Record<string, any>
): Partial<T> | undefined

import { useUECallback, filterUECallBackJSonData } from 'ue-connect'
import { useState } from 'react'

function AuthComponent() {
  const [serverURL, setServerURL] = useState('')
  const [title, setTitle] = useState('')

  useUECallback(
    'OnPlayerDataUpdated', // 前端回调函数名称
    (data) => {
      // 注意传回的数据先判断是否为json字符串，普通字符按非json处理
      if (typeof data === 'string') {
        try {
          data = JSON.parse(data)
        } catch {
          console.error('无效的 JSON 字符串按非json处理:', data)
          return
        }
      }
    
      // 过滤数据
      const filter = filterUECallBackJSonData(data, { health: (vs: any) => vs, isAlive: (vs: any) => vs })
      
      // 回调逻辑处理
      console.log('筛选后的数据:', filter)
      /*
      打印结果：
      筛选后的数据: { health: 100, isAlive: true }
      */
    }
  )

  return (
    <div>
      <p>健康值: {filter?.health || '未指定'}</p>
      <p>是否存活: {filter?.isAlive ? '是' : '否'}</p>
    </div>
  )
}

import React from 'react'
import {
  UEProvider,
  useUEContext,
  useUEEventJSON,
  useUEMouse,
  useQuickUIEvent,
  useQuickUIEventListener,
  useUECallback,
  useInputKeyEventListener,
  filterUECallBackJSonData,
} from 'ue-connect'

function GameUI() {
  const { isConnected, useMouse, lastKeyAction } = useUEContext()
  const { useMouse: mouseEnabled, setUseMouse } = useUEMouse(true)
  const triggerEvent = useUEEventJSON({ functionName: 'UpdateUI' })

  // 使用更新后的 useQuickUIEvent
  const sendPlayerEvent = useQuickUIEvent('playerAction')
  const sendGameEvent = useQuickUIEvent('gameState')

  // 监听来自 UE5 的事件
  useQuickUIEventListener('enemySpawn', (event) => {
    console.log('敌人生成:', event.payload)
    // 可以在这里更新 UI 状态
  })

  // 监听 UE5 按键导航事件（适用于 TV 端或手柄遥控器）
  useInputKeyEventListener({
    onKeyAction: (action) => {
      console.log('按键导航:', action)
    }
  })

  // 使用优化的回调管理
  useUECallback('OnPlayerDataUpdated', (data) => {
    console.log('玩家数据更新:', data)
    // 处理玩家数据更新
  })

  // 使用filterUECallBackJSonData进行数据筛选
  useUECallback(
    'OnPlayerDataUpdated', // 前端回调函数名称
    (data) => {
      // 注意传回的数据先判断是否为json字符串，普通字符按非json处理
      if (typeof data === 'string') {
        try {
          data = JSON.parse(data)
        } catch {
          console.error('无效的 JSON 字符串按非json处理:', data)
          return
        }
      }
    
      // 过滤数据
      const filter = filterUECallBackJSonData(data, { health: (vs: any) => vs, isAlive: (vs: any) => vs })
      
      // 回调逻辑处理
      console.log('筛选后的数据:', filter)
      /*
      打印结果：
      筛选后的数据: { health: 100, isAlive: true }
      */
    }
  )

  const handlePlayerAction = (action: string) => {
    // 发送 JSON 事件到 UE5
    triggerEvent({
      action,
      timestamp: Date.now(),
      playerId: 'player123'
    })

    // 发送 QuickUI 事件
    sendPlayerEvent({
      actionType: action,
      player: 'player123'
    })
  }

  const handleGameStateChange = (state: string) => {
    sendGameEvent({
      newState: state,
      previousState: 'playing'
    })
  }

  return (
    <div className="game-ui">
      <div className="status-bar">
        <span>状态: {isConnected ? '已连接' : '连接中...'}</span>
        <span>最近按键: {lastKeyAction || '无'}</span>
        <button onClick={() => setUseMouse(!mouseEnabled)}>{mouseEnabled ? '禁用' : '启用'}鼠标</button>
      </div>

      <div className="game-controls">
        <button onClick={() => handlePlayerAction('jump')}>跳跃</button>
        <button onClick={() => handlePlayerAction('attack')}>攻击</button>
        <button onClick={() => handleGameStateChange('paused')}>暂停游戏</button>
      </div>

      {/* 鼠标事件禁用区域 */}
      <div data-nohit className="no-mouse-zone">
        此区域不响应鼠标事件
      </div>
    </div>
  )
}

export default function App() {
  return (
    <UEProvider>
      <GameUI />
    </UEProvider>
  )
}

// 按键操作类型
type KeyAction = "Up" | "Down" | "Left" | "Right" | "Next" | "Previous" | "Select"

// 自定义事件接口
interface QuickEvent<Payload = QuickEventPayload> {
  type: 'event' // 事件类型（固定为 "event"）
  topic: string // 事件主题/名称
  payload?: Payload // 事件载荷数据
  timestamp: number // 事件时间戳
  source: 'web' | 'ue' // 事件源
}

type QuickEventPayload = Record<string, any> | null

import { useQuickUIEvent, useQuickUIEventListener, type QuickEvent } from 'ue-connect'

// 定义自定义载荷类型
interface PlayerEvent {
  playerId: string
  health: number
  position: { x: number; y: number; z: number }
}

function TypedComponent() {
  // 使用类型化的事件
  const sendPlayerUpdate = useQuickUIEvent('playerUpdate')

  // 监听类型化的事件
  useQuickUIEventListener('playerUpdate', (event: QuickEvent<PlayerEvent>) => {
    if (event.payload) {
      console.log('玩家ID:', event.payload.playerId)
      console.log('玩家血量:', event.payload.health)
      console.log('玩家位置:', event.payload.position)
    }
  })

  const updatePlayer = () => {
    sendPlayerUpdate({
      playerId: 'player123',
      health: 100,
      position: { x: 10, y: 20, z: 30 }
    })
  }

  return <button onClick={updatePlayer}>更新玩家</button>
}