Telegram 小程序 | TypeScript @telegram-apps/bridge | 方法

riyad

本文涵盖与 apps communication 方法相关的主题。

1 G! w! D7 X2 o  X! G* u
调用方法​

要调用 Telegram 迷你应用程序的方法，开发人员应使用 postEvent 函数：

1. import { postEvent } from '@telegram-apps/bridge';
   
2. 
   
3. postEvent('web_app_setup_back_button', { is_visible: true });

复制代码

该功能会根据当前 环境自动确定发送事件的正确方式。 它能识别 Telegram 应用程序类型并选择合适的流程。

request​

当开发人员需要调用 Telegram 小应用程序方法和 接收特定事件时，应使用 request 函数。

例如，调用web_app_request_viewport 方法并捕捉 viewport_changed 事件以获取实际视口数据：

1. import { request } from '@telegram-apps/bridge';
   
2. 
   5 d: u1 T8 f; S6 s
3. const viewport = await request(
   8 s' W. [! w: M# k4 E) p$ h' e
4.   'web_app_request_viewport',
   
5.   'viewport_changed',
   
6. );
   1 f. X3 c5 R/ h- `5 D
7. 
   4 t" I/ W* J6 W  p' z
8. console.log(viewport);
   
9. // Output:
   0 ?$ P& t6 {" H  v
10. // {
    # T4 V0 b2 J  w
11. //   is_state_stable: true,
    
12. //   is_expanded: false,
    6 p) G# M7 g4 g- x
13. //   height: 320
    2 e) ^+ c* J! c. C2 [
14. // };

复制代码

" a. e! o3 l: Z& N  O

如果 Telegram 小应用程序方法接受参数，则应在第三个参数的 params 属性 中传递这些参数：

1. const buttonId = await request('web_app_open_popup', 'popup_closed', {
   
2.   params: {
   
3.     title: 'Caution',
   . X5 s7 [6 Q( ~6 b3 ~4 e. o
4.     message: 'Should we delete your account?',
   
5.     buttons: [
   / s# q0 P( U9 x
6.       { id: 'yes', type: 'ok' },
   % c9 U/ P9 q. W5 Z+ s/ {
7.       { id: 'no', type: 'cancel' },
   
8.     ],
   + K2 U7 s( d% Q1 ^( _2 Y
9.   },
   7 H5 H1 w9 E! V6 c
10. });

复制代码

它还可以同时跟踪多个事件：

1. const result = await request(
   
2.   'web_app_open_scan_qr_popup',
   
3.   ['qr_text_received', 'scan_qr_popup_closed'],
   . h  v0 S/ F* }, ]2 ?
4. );
   
5. 
   
6. // The result will either be the qr_text_received
   * F; L4 H) u1 _
7. // or scan_qr_popup_closed event payload.

复制代码

该函数允许传递其他选项，如 postEvent、abortSignal、timeout、 和 capture。

2 c: z8 m* m0 i9 n' G$ mpostEvent​

postEvent 选项允许开发人员覆盖用于调用 Telegram 迷你应用程序 方法的方法。

1. request('web_app_request_viewport', 'viewport_changed', {
   ( P0 [; h# p3 K# Y! \3 w3 L
2.   postEvent() {
   
3.     console.log('Hey, I am not going to do anything');
   
4.   },
   
5. });

复制代码

abortSignal​

要从外部终止返回的承诺，需要使用 abortSignal 选项。

1. const controller = new AbortController();
   
2. 
   ( @/ n: D/ W3 i7 `. T
3. request('web_app_request_viewport', 'viewport_changed', {
   
4.   abortSignal: controller.signal,
   7 p( P! k" i/ x3 t
5. });
   3 l  Z- |. q/ \  M0 ~6 w
6. 
   / S4 l2 r+ p: V" B' w& E6 Q
7. setTimeout(() => {
   
8.   controller.abort(new Error('Not going to wait anymore'));
   
9. }, 500);

复制代码

timeout​

timeout 选项为请求指定一个超时时间。

1. import { request } from '@telegram-apps/bridge';
   $ d' m2 j$ v. Q% t5 [
2. 
   7 ?: v7 v, R+ j
3. try {
   + Q  N: n3 a. F) J2 A. }% Z
4.   await request(
   ; w: k, ]+ Y5 D. Q
5.     'web_app_invoke_custom_method',
   
6.     'custom_method_invoked',
   & N% W* ]+ ^/ e$ y% g% A: V
7.     {
   
8.       timeout: 5000,
   # ?; O7 V5 K1 u* O
9.       params: {
   
10.         req_id: '1',
    
11.         method: 'deleteStorageValues',
    
12.         params: { keys: ['a'] },
    / \3 I/ f9 X6 j% J5 Y+ |
13.       },
    
14.     },
    
15.   );
    ! b1 P' T' ]' ]8 @& z7 ~
16. } catch (e) {
    
17.   console.error(e); // TypedError with e.type === 'ERR_TIMED_OUT'
    , K9 e  Q8 ]+ Q6 a6 \; x# M
18. }

复制代码

capture​

capture 属性是一个允许开发人员确定是否应捕获 Mini Apps 事件并从 request 函数返回的函数：

1. const slug = 'jjKSJnm1k23lodd';
   
2. 
   : I$ y1 Y9 Y- `# T# R) ~! A
3. request('web_app_open_invoice', 'invoice_closed', {
   
4.   params: { slug },
   
5.   capture(data) {
   8 L  S! d2 s; c0 S5 R7 S: e
6.     return slug === data.slug;
   + `! m; {: h, R2 [( u6 \
7.   },
   ( ^5 }5 A9 G3 V3 t+ `8 I
8. });

复制代码

默认情况下，request 函数会捕获具有所需名称的第一个事件。 在这种情况下，只有当事件具有预期的标签时，该函数才会捕获事件，特定于 [color=var(--vp-c-brand-1)]invoice_closed 事件。

当传递一个事件数组时，capture 函数将收到一个对象，其中包含 event: EventName 和 payload?: EventPayload 属性的对象。