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

riyad

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

" G% w  n+ `6 I
, a" f) O" @" b! L5 t调用方法​

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

1. import { postEvent } from '@telegram-apps/bridge';
   , T! H  o4 c' K9 y0 U
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. 
   - _( @1 F0 }+ W: s9 n, w
3. const viewport = await request(
   1 Z6 K& e+ H$ d( J6 m& ^8 ]; F
4.   'web_app_request_viewport',
   ' a8 f9 L8 Q- j! B, \* C
5.   'viewport_changed',
   
6. );
   
7. 
   ) Q) x4 n  h" L% H4 x. X
8. console.log(viewport);
   
9. // Output:
   
10. // {
    / d* i6 {4 z+ A2 m6 p4 F
11. //   is_state_stable: true,
    
12. //   is_expanded: false,
    # D6 R1 j2 N% q: A* h6 s3 [( r
13. //   height: 320
    7 A% O0 X5 h! z9 r
14. // };

复制代码

* y- n/ \/ X% `( Q& A( ]7 s

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

1. const buttonId = await request('web_app_open_popup', 'popup_closed', {
   ) e5 f: V1 `3 B0 U! r! R
2.   params: {
   ! L0 g8 \9 Y2 B  d
3.     title: 'Caution',
   
4.     message: 'Should we delete your account?',
   8 Y, ~8 ^9 ~7 Z: F
5.     buttons: [
   
6.       { id: 'yes', type: 'ok' },
   ' r7 V; g! m! V" q, n
7.       { id: 'no', type: 'cancel' },
   
8.     ],
   4 L) y0 N! N5 o; {. s; _
9.   },
   1 ^0 ~$ |" p" d# L) B4 ~7 S, t3 p
10. });

复制代码

) O  g/ v( ]; Y4 `) m' ^

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

1. const result = await request(
   & F5 ^% a# G( x/ m0 b6 j! I
2.   'web_app_open_scan_qr_popup',
   
3.   ['qr_text_received', 'scan_qr_popup_closed'],
   
4. );
   ' c1 W/ P) s# V. |/ v
5. 
   ! g; C. @- h/ I, q4 H
6. // The result will either be the qr_text_received
   . h  @  _2 ^( z$ K" X. {, L
7. // or scan_qr_popup_closed event payload.

复制代码

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

# J9 C  G, t/ `" x) K. b+ ipostEvent​

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

1. request('web_app_request_viewport', 'viewport_changed', {
   # ^2 K! ], P4 s$ r) l
2.   postEvent() {
   
3.     console.log('Hey, I am not going to do anything');
   
4.   },
   
5. });

复制代码

abortSignal​

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

1. const controller = new AbortController();
   ; ]9 s' A8 {) C& x" q2 \
2. 
   2 w( T0 A' T- x
3. request('web_app_request_viewport', 'viewport_changed', {
   
4.   abortSignal: controller.signal,
   . s! k! u+ b  W+ Z
5. });
   ! b7 a5 k* {3 ?( p! q0 L& s
6. 
   ; ~1 X  x8 ~* v' y
7. setTimeout(() => {
   9 w2 ?$ i+ l* t3 N8 i8 k1 U
8.   controller.abort(new Error('Not going to wait anymore'));
   . m2 A! J$ \- b1 [2 Y1 r& A
9. }, 500);

复制代码

timeout​

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

1. import { request } from '@telegram-apps/bridge';
   ) I" `& u* ~$ M$ ?
2. 
   9 a: ]5 K& _4 m0 i# E
3. try {
   ( {' o  u. y  t+ F. M
4.   await request(
   + t- p$ q+ x& n' L8 k: B) z) g1 l( ?, y
5.     'web_app_invoke_custom_method',
   , ]& d$ E6 P5 i! |3 N
6.     'custom_method_invoked',
   ! O' A# W& L" L4 V' B5 R
7.     {
   
8.       timeout: 5000,
   
9.       params: {
   
10.         req_id: '1',
    
11.         method: 'deleteStorageValues',
    
12.         params: { keys: ['a'] },
    ! M* c' F8 n+ Z. k: d5 |- l4 J
13.       },
    % r9 K0 C  B8 W) \' Z9 \; I( ^
14.     },
    " X& S; A5 v3 k6 {2 G
15.   );
    , J. {# F( j* f+ t( }, |; M5 n! q; `- J
16. } catch (e) {
    
17.   console.error(e); // TypedError with e.type === 'ERR_TIMED_OUT'
    6 S# c% Q5 J& U2 Z7 T; R7 Y- j7 ?
18. }

复制代码

capture​

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

1. const slug = 'jjKSJnm1k23lodd';
   ! p8 b/ Q" W3 L( a" N- L
2. 
   
3. request('web_app_open_invoice', 'invoice_closed', {
   ( y! n; u. Z; @) P
4.   params: { slug },
   % Q$ h+ J! ^, D0 N. X% z/ I( \* _
5.   capture(data) {
   
6.     return slug === data.slug;
   * |& M0 q2 f  ]8 w) C
7.   },
   
8. });

复制代码

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

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