useHapticFeedback

提供 Telegram 触觉反馈功能的 Hook，让你的 Mini App 拥有原生般的交互体验。

导入

import { useHapticFeedback } from '@xcloud/ui-telegram';

示例

API

返回值

属性	类型	描述
impact	(style: ImpactStyle) => void	触发 Impact 反馈
notification	(type: NotificationType) => void	触发通知反馈
selection	() => void	触发选择反馈
isAvailable	() => boolean	检查触觉反馈是否可用

ImpactStyle

Impact 反馈的强度类型：

值	描述	使用场景
'light'	轻微震动	轻量级交互，如悬停、高亮
'medium'	中等震动	标准按钮点击、选择
'heavy'	强烈震动	重要操作、删除、提交
'rigid'	坚硬震动	碰撞、边界限制
'soft'	柔和震动	平滑过渡、滑动

NotificationType

通知反馈的类型：

值	描述	使用场景
'success'	成功反馈	操作成功、任务完成
'error'	错误反馈	操作失败、输入错误
'warning'	警告反馈	警告信息、需要注意

使用示例

按钮点击反馈

为按钮添加触觉反馈，提升用户体验：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function ActionButton() {
  const haptic = useHapticFeedback();

  const handleClick = () => {
    haptic.impact('medium');
    // 执行操作
    performAction();
  };

  return (
    <button onClick={handleClick}>
      点击我
    </button>
  );
}

表单验证反馈

在表单验证时提供反馈：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function LoginForm() {
  const haptic = useHapticFeedback();

  const handleSubmit = async (e) => {
    e.preventDefault();

    try {
      await login(username, password);
      haptic.notification('success');
      navigate('/dashboard');
    } catch (error) {
      haptic.notification('error');
      showError(error.message);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" placeholder="Username" />
      <input type="password" placeholder="Password" />
      <button type="submit">登录</button>
    </form>
  );
}

列表选择反馈

在列表项选择时触发反馈：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function SelectableList() {
  const haptic = useHapticFeedback();
  const [selected, setSelected] = useState<number | null>(null);

  const handleSelect = (id: number) => {
    haptic.selection();
    setSelected(id);
  };

  return (
    <div>
      {items.map((item) => (
        <div
          key={item.id}
          onClick={() => handleSelect(item.id)}
          className={selected === item.id ? 'selected' : ''}
        >
          {item.name}
        </div>
      ))}
    </div>
  );
}

滑动操作反馈

滑动到边界时提供反馈：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function SwipeableCard() {
  const haptic = useHapticFeedback();

  const handleSwipe = (direction: 'left' | 'right') => {
    if (direction === 'left') {
      haptic.impact('rigid'); // 删除时使用 rigid
      deleteItem();
    } else {
      haptic.impact('soft'); // 归档时使用 soft
      archiveItem();
    }
  };

  return (
    <div onSwipe={handleSwipe}>
      Card Content
    </div>
  );
}

游戏交互反馈

为游戏添加丰富的触觉反馈：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function Game() {
  const haptic = useHapticFeedback();

  const handleJump = () => {
    haptic.impact('light');
  };

  const handleCollect = () => {
    haptic.notification('success');
  };

  const handleDamage = () => {
    haptic.impact('heavy');
  };

  const handleGameOver = () => {
    haptic.notification('error');
  };

  return (
    <GameCanvas
      onJump={handleJump}
      onCollect={handleCollect}
      onDamage={handleDamage}
      onGameOver={handleGameOver}
    />
  );
}

删除确认反馈

重要操作的多级反馈：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function DeleteButton() {
  const haptic = useHapticFeedback();
  const [confirming, setConfirming] = useState(false);

  const handleFirstClick = () => {
    haptic.impact('medium');
    setConfirming(true);
  };

  const handleConfirm = async () => {
    haptic.impact('heavy');
    await deleteItem();
    haptic.notification('success');
    setConfirming(false);
  };

  const handleCancel = () => {
    haptic.impact('light');
    setConfirming(false);
  };

  if (confirming) {
    return (
      <div>
        <button onClick={handleConfirm}>确认删除</button>
        <button onClick={handleCancel}>取消</button>
      </div>
    );
  }

  return <button onClick={handleFirstClick}>删除</button>;
}

检查可用性

在使用前检查触觉反馈是否可用：

import { useHapticFeedback } from '@xcloud/ui-telegram';

function Settings() {
  const haptic = useHapticFeedback();

  const testHaptic = () => {
    if (haptic.isAvailable()) {
      haptic.impact('medium');
    } else {
      console.log('Haptic feedback is not available on this device');
    }
  };

  return (
    <div>
      <button onClick={testHaptic}>测试触觉反馈</button>
      <p>
        触觉反馈状态: {haptic.isAvailable() ? '可用' : '不可用'}
      </p>
    </div>
  );
}

最佳实践

1. 合理选择反馈强度

根据操作的重要性选择合适的反馈强度：

• Light: 轻量级操作（悬停、预览）
• Medium: 标准操作（点击、选择）
• Heavy: 重要操作（删除、提交）

2. 不要过度使用

避免在每个交互都添加触觉反馈，这会让用户感到疲惫。只在关键交互点添加反馈。

3. 配合视觉反馈

触觉反馈应该与视觉反馈配合使用，而不是替代视觉反馈。

4. 保持一致性

在整个应用中保持触觉反馈的一致性。相同类型的操作应该使用相同的反馈类型。

5. 尊重用户设置

Telegram 会自动遵守用户的系统设置。如果用户禁用了触觉反馈，这些方法调用不会产生任何效果。

注意事项

• 触觉反馈仅在支持的设备上可用（iOS 和部分 Android 设备）
• 在不支持的设备上，方法调用不会报错，只是不会产生任何效果
• 使用 isAvailable() 检查功能是否可用
• 触觉反馈会消耗设备电量，应适度使用
• 在 Web 版 Telegram 中，触觉反馈通常不可用

相关 Hooks

• useInitData - 获取 Telegram 初始化数据
• usePopup - 显示原生弹窗