响应处理

在本文档中 与用户交互直接相关的 UI/UX 功能。像滚动、键盘、音频焦点、触觉震动这样 需要对用户行为立即响应的功能统一整理说明。

---

滚动回弹区域背景处理

SDK 组件： ScrollViewInertialBackground

iOS ScrollView是在 ScrollView 滚动到末端时产生的 **回弹效果区域（上/下）** 中填充背景色，从而提供更自然视觉效果的组件。

签名

function ScrollViewInertialBackground({
  topColor,
  bottomColor,
  spacer: _spacer,
}: ScrollViewInertialBackgroundProps): JSX.Element;

参数

• props对象

  是传递给组件的 props 对象。

  • props.topColor · string

    是应用于滚动上方区域的背景色。默认值会根据系统主题自动应用为 adaptive.background。
  • props.bottomColor · string

    是应用于滚动下方区域的背景色。默认值会根据系统主题自动应用为 adaptive.background。
  • props.spacer · number

    用于指定应用背景色的内容上下空间之间的间距大小。默认值为 useWindowDimensions获取的屏幕高度。

示例：为滚动视图上下添加背景色

在滚动视图上方添加红色、下方添加蓝色背景色。背景色会应用到滚动范围之外的区域。

import { ScrollView, View, Text } from 'react-native';
import { ScrollViewInertialBackground } from '@granite-js/react-native';

const dummies = Array.from({ length: 20 }, (_, i) => i);

function InertialBackgroundExample() {
  return (
    <ScrollView>
      <ScrollViewInertialBackground topColor="red" bottomColor="blue" />
      {dummies.map((i) => (
        <View
          key={`dummy-${i}`}
          style={{ width: '100%', height: 100, borderBottomColor: 'black', borderBottomWidth: 1 }}
        >
          <Text>请滚动看看。</Text>
        </View>
      ))}
    </ScrollView>
  );
}

---

颜色模式类型

SDK API： ColorPreference

当前设备的 颜色模式（浅色 / 深色） 所表示的类型。用于主题分支或样式条件处理。

签名

type ColorPreference = 'light' | 'dark';

---

将元素抬到键盘上方

SDK 组件： KeyboardAboveView

当键盘出现时 自动将子组件抬到键盘上方的布局组件。在输入时也想始终显示按钮或操作区域时很有用。

签名

function KeyboardAboveView({ style, children, ...props }: ComponentProps<typeof View>): ReactElement;

参数

• props.styleStyleProp<ViewStyle>

  可以应用额外样式。例如，可以设置背景色或尺寸等。
• props.childrenReactNode

  是键盘出现时显示在键盘上方的组件。例如，可以放入按钮、文本输入框等。

返回值

• ReactElement

  在键盘出现时，会返回调整到键盘上方的 Animated.View。

示例：将元素抬到键盘上方

import { ScrollView, TextInput, View, Text } from 'react-native';
import { KeyboardAboveView } from '@granite-js/react-native';

function KeyboardAboveViewExample() {
  return (
    <>
      <ScrollView>
        <TextInput placeholder="placeholder" />
      </ScrollView>

      <KeyboardAboveView>
        <View style={{ width: '100%', height: 50, backgroundColor: 'yellow' }}>
          <Text>在 Keyboard 上方。</Text>
        </View>
      </KeyboardAboveView>
    </>
  );
}

---

音频焦点变更回调

SDK API： OnAudioFocusChanged

是视频或音频组件的 音频焦点发生变化时调用的回调类型。可以控制因其他应用或系统事件导致声音中断时的处理。

签名

type OnAudioFocusChanged = NonNullable<VideoProperties['onAudioFocusChanged']>;

参数

• event · 必填 · Object

  是包含音频焦点信息的事件对象。

  • event.hasAudioFocus · 必填 · boolean

    表示视频组件是否拥有音频焦点。

---

触发触觉震动

SDK 函数： generateHapticFeedback

在设备上 触发触觉震动的函数。用于按钮点击、完成通知、成功/失败反馈等需要触觉响应的时刻。

需要在 Toss 应用内的设置 > 震动菜单中开启设置，震动才会执行。

签名

function generateHapticFeedback(options: HapticFeedbackOptions): Promise<void>;

返回值

• void

示例：按下按钮触发触觉反馈

js

import { generateHapticFeedback } from '@apps-in-toss/web-framework';

generateHapticFeedback({ type: 'tickWeak' });

React

import React from 'react';
import { generateHapticFeedback } from '@apps-in-toss/web-framework';

function GenerateHapticFeedbackWeb() {
  return (
    <button
      onClick={() => {
        generateHapticFeedback({ type: 'tickWeak' });
      }}
      style={{
        padding: '10px 20px',
        borderRadius: '8px',
        border: 'none',
        backgroundColor: '#3182f6',
        color: 'white',
        cursor: 'pointer',
        fontSize: '16px',
      }}
    >
      触觉
    </button>
  );
}

export default GenerateHapticFeedbackWeb;

React Native

import { Button } from 'react-native';
import { generateHapticFeedback } from '@apps-in-toss/framework';

function GenerateHapticFeedback() {
  return (
    <Button
      title="触觉"
      onPress={() => {
        generateHapticFeedback({ type: 'tickWeak' });
      }}
    />
  );
}

体验示例应用

apps-in-toss-examples 从仓库中 with-haptic-feedback 下载代码，或扫描下方 QR 码亲自体验。

QR 码链接: intoss://with-haptic-feedback

触觉震动选项及类型

类型： HapticFeedbackOptions, HapticFeedbackType

generateHapticFeedback定义要传递的震动类型选项。

签名

interface HapticFeedbackOptions {
  type: HapticFeedbackType;
}

type HapticFeedbackType =
  | 'tickWeak'
  | 'tap'
  | 'tickMedium'
  | 'softMedium'
  | 'basicWeak'
  | 'basicMedium'
  | 'success'
  | 'error'
  | 'wiggle'
  | 'confetti';

注意事项

• 与交互相关的功能 会直接影响用户体验。请避免过度使用，只在有意义的时刻使用。
• 键盘 / 音频 / 触觉功能在不同平台上的行为可能有所差异。
• 事件或回调驱动的功能务必同时实现 清理（cleanup） 逻辑。