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

riyad

本文涵盖与 apps communication 方法相关的主题。
, g/ p9 ~$ [0 [- E2 i
$ V6 R# ]6 m9 ], W" X4 ^8 V
调用方法​

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

1. import { postEvent } from '@telegram-apps/bridge';
   + [$ L& T$ b. @0 c! {) ?
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';
   9 q6 c. w- [+ Y0 F
2. 
   
3. const viewport = await request(
   1 d: f" `& }# T% D0 ]; f
4.   'web_app_request_viewport',
   
5.   'viewport_changed',
   4 s3 m/ y( I# N
6. );
   
7. 
   - H  V( _8 I0 ^
8. console.log(viewport);
   $ u$ D- V- _8 n" X( f8 j, C( m
9. // Output:
   ) J  R6 F" d2 v( y& m+ x% j
10. // {
    3 F1 j4 P; H  Q0 m9 I
11. //   is_state_stable: true,
    ( D5 A; T' F& I( O& r
12. //   is_expanded: false,
    & v# E; m$ V: Q! B
13. //   height: 320
    
14. // };

复制代码

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

1. const buttonId = await request('web_app_open_popup', 'popup_closed', {
   
2.   params: {
   : b8 s8 s3 ]- g% y: p+ l- z" ~
3.     title: 'Caution',
   
4.     message: 'Should we delete your account?',
   
5.     buttons: [
   
6.       { id: 'yes', type: 'ok' },
   * K, i( E( I, K: _
7.       { id: 'no', type: 'cancel' },
   $ e6 v/ e( G0 @; {' P$ @0 [
8.     ],
   
9.   },
   ; W  m5 H* i7 Z* U) y; b
10. });

复制代码

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

1. const result = await request(
   
2.   'web_app_open_scan_qr_popup',
   3 M4 |) Z- g/ I% I& z  j+ G4 p7 s1 F
3.   ['qr_text_received', 'scan_qr_popup_closed'],
   
4. );
   ) f8 V  Q; j1 l# |
5. 
   
6. // The result will either be the qr_text_received
   
7. // or scan_qr_popup_closed event payload.

复制代码

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

: t/ V  D) Q) ]7 g* x' PpostEvent​

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

1. request('web_app_request_viewport', 'viewport_changed', {
   
2.   postEvent() {
   
3.     console.log('Hey, I am not going to do anything');
     N: R- L1 Q) F' G0 b& O* n) |
4.   },
   
5. });

复制代码

abortSignal​

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

1. const controller = new AbortController();
   3 s! V7 w1 R, r7 J4 u
2. 
   
3. request('web_app_request_viewport', 'viewport_changed', {
   4 X& R7 w  P- ?
4.   abortSignal: controller.signal,
   
5. });
   
6. 
   
7. setTimeout(() => {
   
8.   controller.abort(new Error('Not going to wait anymore'));
   
9. }, 500);

复制代码

timeout​

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

1. import { request } from '@telegram-apps/bridge';
   * Q! H& w# L7 p' U! g
2. 
   
3. try {
   - ~9 ]  a- p+ w, k
4.   await request(
   
5.     'web_app_invoke_custom_method',
   * {" c. V) h# d
6.     'custom_method_invoked',
   . z$ P2 G% k; [) b  N4 C
7.     {
   1 ]2 W5 D/ {2 `" |( F5 Z$ @- @
8.       timeout: 5000,
   : J* U* m( J+ K  {% `
9.       params: {
   4 J" l. G) B7 E0 s) I- u; m$ L2 l
10.         req_id: '1',
    1 f) S  q! H  v5 J) K+ W: r* ^
11.         method: 'deleteStorageValues',
    
12.         params: { keys: ['a'] },
    
13.       },
    
14.     },
    
15.   );
    
16. } catch (e) {
    
17.   console.error(e); // TypedError with e.type === 'ERR_TIMED_OUT'
    . d% g, o! v; f2 W- z
18. }

复制代码

capture​

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

1. const slug = 'jjKSJnm1k23lodd';
   
2. 
   
3. request('web_app_open_invoice', 'invoice_closed', {
   
4.   params: { slug },
   , p; D  x  S- v# o. o: U
5.   capture(data) {
   
6.     return slug === data.slug;
   
7.   },
   ) Q8 o. \0 q$ t2 Q% V! j
8. });

复制代码

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

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