@telegram-apps/sdk-solid

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

安装

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

pnpm

pnpm i @telegram-apps/sdk-solid

npm

npm i @telegram-apps/sdk-solid

yarn

yarn add @telegram-apps/sdk-solid

SDKProvider

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

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

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

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

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

钩子（Hooks）

该软件包中的每个组件钩子都会返回一个自定义 signal 。 返回的信号包含一个属性 error?: unknown，如果组件初始化过程中出现问题，该属性将被设置。 调用包含该属性的 signal 将导致产生相应的 错误。 如果没有错误发生， signal 将返回一个组件实例。

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

下面就是一个例子：

import { useBackButton, useViewport } from '@telegram-apps/sdk-solid';

// BackButton initializes synchronously. So, bb will be a signal
// returning an instance of BackButton.
const bb = useBackButton();
const bbV = bb(); // will be BackButton

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

// ...after some time
const vpV2 = vp(); // will be Viewport

需要注意的是，组件的所有属性都是响应式的。 因此，如果钩子 signal 返回的值发生变化 ， signal 本身不会收到通知。 这是因为 组件本身没有变化，但其属性发生了变化。

让我们来看看这个例子：

import { useViewport } from '@telegram-apps/sdk-solid';
import { createEffect } from 'solid-js';

// Let's assume that viewport is already initialized.
const vp = useViewport();

createEffect(() => {
  // This line of code will not be called if the viewport height 
  // or expansion state changes.
  console.log('Viewport changed', vp());
});

createEffect(() => {
  // But this line of code will be called every time the viewport
  // height changes.
  console.log('Viewport height changed', vp().height);
});

我们拥有这种细粒度的反应能力，以提供最佳性能，就像 Solid 本身一样。

HOCs（高阶组件）

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

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

const MyComponent = withBackButton('bb', (props) => {
  createEffect(() => {
    props.bb().show();
  });
  return null;
});

作为第一个参数，您必须传递一个负责接收 钩子结果的组件属性名称的值。 请注意，接收到的值将是一个 signal ，而不是后面的值。

Hooks 和 HOCs 列表

Hook	HOC（高阶组件）	Signal value
useBackButton	withBackButton	BackButton
useBiometryManager	withBiometryManager	BiometryManager 或 undefined
useClosingBehavior	withClosingBehavior	ClosingBehavior
useCloudStorage	withCloudStorage	CloudStorage
useHapticFeedback	withHapticFeedback	HapticFeedback
useInitData	withInitData	InitData
useInvoice	withInvoice	Invoice
useMainButton	withMainButton	MainButton
useMiniApp	withMiniApp	MiniApp
usePopup	withPopup	Popup
useQRScanner	withQRScanner	QRScanner
useSettingsButton	withSettingsButton	SettingsButton
useSwipeBehavior	withSwipeBehavior	SwipeBehavior
useThemeParams	withThemeParams	ThemeParams
useUtils	withUtils	Utils
useViewport	withViewport	Viewport 或 undefined

模板

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