@telegram-apps/sdk-react

客户端 SDK 的 React JS 绑定。 包括钩子、组件和 实用程序，以便在 Telegram 迷你应用程序平台上轻松使用 React JS。

安装

在此之前，假定您已经安装了 react 软件包，因为 是该软件包的同级依赖关系。

pnpm

pnpm i @telegram-apps/sdk-react

npm

npm i @telegram-apps/sdk-react

yarn

yarn add @telegram-apps/sdk-react

SDKProvider

SDKProvider 是负责提供 SDK 功能的组件。 它接受 ，如 acceptCustomStyles: boolean 和 debug: boolean 等属性。 两者都是可选的。

acceptCustomStyles 属性负责接受来自 Telegram 网页版的自定义样式。

debug 属性负责启用调试模式。

import { SDKProvider } from '@telegram-apps/sdk-react';

/**
 * Root component for the whole project.
 */
export function Root() {
  return (
    <SDKProvider acceptCustomStyles debug>
      <div>My application!</div>
    </SDKProvider>
  );
}

Hooks

为了更好地理解，每个组件钩子都使用各自与组件相关的 init 函数。 如果 init 函数返回的是非承诺值，钩子将立即检索该值。 如果 init 函数 是异步的，那么当组件仍在 初始化时，钩子将返回一个 undefined 值。 然后，它将更新为初始化值。

本软件包中的所有组件钩子分为两部分：

1. 读取实际的初始函数值。 这些钩子是非后缀的，如 useBackButton。
2. 检索与初始函数值相关的元项目。 这些钩子包括一个后缀，如 ，如 Raw，如 useBackButtonRaw。

第一类钩子返回实际的初始函数值。 如果 在组件初始化过程中出现问题，它们就会出错。

第二类钩子会返回一个包含初始化进程信息的对象。 下面是物体的形状：

export interface SDKContextItem<T> {
  /**
   * This item execution result. The property may be missing
   * in case the execution is async.
   */
  result?: T;
  /**
   * Function to clean up item side effects.
   */
  cleanup?(): void;
  /**
   * An error occurred during execution.
   */
  error?: unknown;
}

使用第二类钩子，可以提取错误而不抛出错误。

下面是完整的使用示例：

import {
  useBackButton,
  useBackButtonRaw,
  useViewport,
  useViewportRaw,
  useBiometryManagerRaw,
} from '@telegram-apps/sdk-react';
import { useEffect } from 'react';

// BackButton initializes synchronously. So, bb will be 
// the BackButton instance.
const bb = useBackButton();

// Viewport is being initialized asynchronously, so signal may return undefined.
// After some time it will receive a valid value.
const vp = useViewport();

useEffect(() => {
  console.log(vp); // will be undefined and then Viewport instance.
}, [vp]);

const bm = useBiometryManagerRaw();

useEffect(() => {
  if (bm.error) {
    console.error('Something went wrong for BiometryManager', bm.error);
  }
}, [bm]);

SSR

该软件包还支持在 Next.js 等流行框架中广泛使用的 SSR 模式。 在服务器端使用 软件包钩子时，必须将 true 作为第一个参数传递。 这将通知钩子 服务器端模式已启用。 如果不指定此值，在服务器端 上调用钩子将导致错误。

服务器端模式会为服务器端的每个组件钩子返回 undefined，也会在挂载当前组件之前返回 undefined。这对于服务器端和客户端渲染的树之间的持久性是必需的。

import { useBackButton } from '@telegram-apps/sdk-react';
import { useEffect } from 'react';

function Component() {
  const bb = useBackButton(true); // will be undefined or BackButton.

  useEffect(() => {
    if (bb) {
      // Here we can safely work with the BackButton.
    }
  }, [bb]);
}

HOCs

所有软件包的高阶组件都使用前面描述的钩子。 使用方法相当 简单：

import { withBackButton } from '@telegram-apps/sdk-react';
import { useEffect } from 'react';

const A = withBackButton('bb', false, ({ bb }) => {
  useEffect(() => {
    bb.show();
  }, [bb]);
  return null;
});

const B = withBackButton('bb', true, ({ bb }) => {
  useEffect(() => {
    bb && bb.show();
  }, [bb]);
  return null;
});

作为第一个参数，您必须传递一个值，该值负责接收 钩子结果的组件属性名称。 第二个参数是 SSR 标志模式，将传递给钩子，内部使用 。

Hooks 和 HOC 列表

Hook and HOC (Raw)	Hook and HOC (Result)	Returned value
useBackButtonRaw, withBackButtonRaw	useBackButton, withBackButton	BackButton
useBiometryManagerRaw, withBiometryManagerRaw	useBiometryManager, withBiometryManager	BiometryManager 或 undefined
useClosingBehaviorRaw, withClosingBehaviorRaw	useClosingBehavior, withClosingBehavior	ClosingBehavior
useCloudStorageRaw, withCloudStorageRaw	useCloudStorage, withCloudStorage	CloudStorage
useHapticFeedbackRaw, withHapticFeedbackRaw	useHapticFeedback, withHapticFeedback	HapticFeedback
useInitDataRaw, withInitDataRaw	useInitData, withInitData	InitData
useInvoiceRaw, withInvoiceRaw	useInvoice, withInvoice	Invoice
	useLaunchParams	Launch params
useMainButtonRaw, withMainButtonRaw	useMainButton, withMainButton	MainButton
useMiniAppRaw, withMiniAppRaw	useMiniApp, withMiniApp	MiniApp
usePopupRaw, withPopupRaw	usePopup, withPopup	Popup
useQRScannerRaw, withQRScannerRaw	useQRScanner, withQRScanner	QRScanner
useSettingsButtonRaw, withSettingsButtonRaw	useSettingsButton, withSettingsButton	SettingsButton
useSwipeBehaviorRaw, withSwipeBehaviorRaw	useSwipeBehavior, withSwipeBehavior	SwipeBehavior
useThemeParamsRaw, withThemeParamsRaw	useThemeParams, withThemeParams	ThemeParams
useUtilsRaw, withUtilsRaw	useUtils, withUtils	Utils
useViewportRaw, withViewportRaw	useViewport, withViewport	Viewport 或 undefined

模板

我们已经创建了一个用于 React JS 的 模板，它使用了当前软件包，因此您可以使用它。