Skip to content

@telegram-apps/sdk-solid

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

安装

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

bash
pnpm i @telegram-apps/sdk-solid
bash
npm i @telegram-apps/sdk-solid
bash
yarn add @telegram-apps/sdk-solid

SDKProvider

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

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

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

jsx
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

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

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

下面就是一个例子:

ts
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

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

让我们来看看这个例子:

ts
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

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

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

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

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

Hooks 和 HOCs 列表

HookHOCSignal value
useBackButtonwithBackButtonBackButton
useBiometryManagerwithBiometryManagerBiometryManagerundefined
useClosingBehaviorwithClosingBehaviorClosingBehavior
useCloudStoragewithCloudStorageCloudStorage
useHapticFeedbackwithHapticFeedbackHapticFeedback
useInitDatawithInitDataInitData
useInvoicewithInvoiceInvoice
useMainButtonwithMainButtonMainButton
useMiniAppwithMiniAppMiniApp
usePopupwithPopupPopup
useQRScannerwithQRScannerQRScanner
useSettingsButtonwithSettingsButtonSettingsButton
useSwipeBehaviorwithSwipeBehaviorSwipeBehavior
useThemeParamswithThemeParamsThemeParams
useUtilswithUtilsUtils
useViewportwithViewportViewportundefined

模板

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

Released under the MIT License.