Telegram 小程序 | TypeScript @telegram-apps/sdk @1.x | 方法与事件

riyad

方法与事件​

本节 SDK 涵盖与 apps communication 相关的主题。

调用方法​

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

1. import { postEvent } from '@telegram-apps/sdk';
   & i+ d& E' Y- f2 i* k
2. 
   % T2 l! W' U7 I1 }6 A
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/sdk';
   
2. 
   ' f9 f0 X/ @' \  x
3. const viewport = await request({
   
4.   method: 'web_app_request_viewport',
   : A+ g% b3 _, N1 Q0 w
5.   event: 'viewport_changed'
   
6. });
   # `+ O$ S! k/ y4 P
7. 
   
8. console.log(viewport);
   9 u9 L8 @, C. Q7 u! C
9. // Output:
   % g, K; W% @4 A( i4 G
10. // {
      e# q* C) G# X* c- O
11. //   is_state_stable: true,
    * Z/ H* Y: N+ x5 L/ i8 m
12. //   is_expanded: false,
    0 _9 a* P7 x& e1 ]. _& y. G
13. //   height: 320
    
14. // };

复制代码

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

1. import { request } from '@telegram-apps/sdk';
   
2. 
   ! t' u- h  k/ @( j; x( w
3. const buttonId = await request({
   ) m3 m* N, _3 |0 J' U) `* F# f; ?
4.   method: 'web_app_open_popup',
   
5.   event: 'popup_closed',
   
6.   params: {
   1 }. s& Y; Q8 H
7.     title: 'Caution',
   
8.     message: 'Should we delete you account?',
   
9.     buttons: [
   
10.       { id: 'yes', type: 'ok' },
    , v3 ?/ _; r$ P6 R1 Y: Y
11.       { id: 'no', type: 'cancel' },
    & Z+ ?4 j  n0 U$ J4 e
12.     ],
    
13.   },
    ( K7 V5 \# [2 @' O* {
14. });

复制代码

此外，您还可以同时跟踪多个事件：

1. import { request } from '@telegram-apps/sdk';
   
2. 
   ' u9 r$ C# m0 ~3 \1 D4 Z. l
3. const result = await request({
   
4.   method: 'web_app_open_scan_qr_popup',
   6 \8 J) F4 M; ^* E
5.   event: ['qr_text_received', 'scan_qr_popup_closed'],
   
6. });
   : U( G# k/ }9 A( f1 m- X9 k; o
7. 
   8 t' g5 D. X7 H+ [- j5 Y
8. // result will either be qr_text_received or
   * i& v- {! W: `6 B2 V" i6 G
9. // scan_qr_popup_closed events payload.

复制代码

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

$ T5 V; l" o& vpostEvent​

我们使用 postEvent 选项重写方法，该方法用于调用 Telegram 迷你应用程序 方法。

1. import { request, createPostEvent } from '@telegram-apps/sdk';
   
2. 
   2 `' b' F& s" ~8 M9 ?
3. request({
   
4.   method: 'web_app_request_viewport',
   ( K* X7 I4 Z8 l+ Q/ F% t
5.   event: 'viewport_changed',
   ) |0 `' X1 g, a$ d9 o' y
6.   postEvent: createPostEvent('6.5'),
   ! \6 A) W, u! ?6 e8 r8 A4 z6 y
7. });

复制代码

timeout​

timeout 选项负责分配请求超时。 如果超时，则会出现错误。

1. import { request, isTimeoutError } from '@telegram-apps/sdk';
   & j2 i/ m! `1 P/ U
2. 
   & I' c, I( D4 _
3. try {
   
4.   await request({
   
5.     method: 'web_app_invoke_custom_method',
   # E3 j* g& G; I# _, k* R+ q/ }
6.     event: 'custom_method_invoked',
   
7.     timeout: 5000,
   8 y0 x$ }2 o. A* i) y
8.     params: {
   ! y1 ?. r- Y* q7 o8 I% F8 G" ?
9.       req_id: '1',
   ' P  c: k/ |8 X  X, p& Q8 L
10.       method: 'deleteStorageValues',
    
11.       params: { keys: ['a'] },
    5 y0 q) l8 B# ^% Q$ [; n6 c
12.     },
    1 B# E8 z" C! H5 ?8 h" Q0 N3 H
13.   });
    
14. } catch (e) {
    * h' o8 r& L6 P  B+ ?& i9 e& t4 {; x
15.   console.error(isTimeoutError(e) ? 'Timeout error' : 'Some different error', e);
    8 O9 `+ o+ t3 s8 }
16. }

复制代码

capture​

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

1. const slug = 'jjKSJnm1k23lodd';
   6 m3 X9 a' x4 M1 X- K' O
2. 
   : y- p+ a4 d" p: c9 M& D% L
3. request({
   ! `9 y! y0 }2 P# t+ K: y
4.   method: 'web_app_open_invoice',
   
5.   event: 'invoice_closed',
   
6.   params: { slug },
   # c. W$ e5 N8 i. ^9 k: j  L
7.   capture(data) {
   2 z( X. c( f  S
8.     return slug === data.slug;
   & R* d9 O/ {' L" _# o% m
9.   },
   4 A& A) `; Q9 R& u
10. });

复制代码

默认情况下，request 函数会捕获带有所需名称的第一个事件。 在 的情况下，request 函数只有在事件具有预期的标签时才会捕获事件。
* ]1 T5 N; C. q6 Z( ~调用自定义方法​

自定义方法是 Telegram 迷你应用程序 web_app_invoke_custom_method 方法可以使用的方法。 invokeCustomMethod 函数简化了此类方法的使用，并重复使用了 request 函数。

以下是不使用该函数的代码示例：

1. import { request } from '@telegram-apps/sdk';
   
2. 
   
3. const reqId = 'ABC';
   1 P" V$ r) R$ c7 t8 n
4. 
   2 S) [0 k+ O& y3 j
5. request({
   ( Y! L4 i( W* i( j
6.   method: 'web_app_invoke_custom_method',
   7 {0 L+ `! t" S& \' F
7.   event: 'custom_method_invoked',
   
8.   params: {
   ( m3 X* r& E9 P& Y' M. ?
9.     req_id: reqId,
   
10.     method: 'deleteStorageValues',
    9 E2 {5 M& u  q- ^, z
11.     params: { keys: ['a'] },
    
12.   },
    % H8 ]9 r, ]% m" X9 J& S
13.   capture(data) {
    3 t) ^; g# f) V) i7 D9 ]
14.     return data.req_id === reqId;
    $ ]* A" H0 a, H, w" H
15.   }
    
16. });

复制代码

这样，我们就可以使用 invokeCustomMethod 函数重写它了：
( ^$ z3 D  X# N: E# l
5 u: E% B' Y. b* t2 S

1. import { invokeCustomMethod } from '@telegram-apps/sdk';
   - Z" {0 Q2 I& N0 _8 g
2. 
   % ~( I3 H( W) t6 A
3. invokeCustomMethod('deleteStorageValues', { keys: ['a'] }, 'ABC');

复制代码

invokeCustomMethod('deleteStorageValues', { keys: ['a'] }, 'ABC');
# O; Y0 Q! E; B: I5 r/ O

与request函数相反，invokeCustomMethod函数解析结果，并 检查是否包含error属性。 如果出现这种情况，函数将抛出相应的 错误。 否则，将返回 result 属性。

事件监听​on 和 off​

要开始处理事件，开发人员可以使用 on 和 off 函数。 下面是 on 函数的基本用法

1. import { on } from '@telegram-apps/sdk';
   2 J. b) _% [7 R+ q- M1 ?, Z, ~5 D+ E
2. 
   ( D2 k% D& l% }) H
3. // Start listening to "viewport_changed" event. Returned value
   
4. // is a function, which removes this event listener.
   
5. const removeListener = on('viewport_changed', payload => {
   
6.   console.log('Viewport changed:', payload);
   
7. });
   
8. 
   # l7 T  Q2 [: @# u2 ^
9. // Remove this event listener.
   : E. ^+ Q( d, U( S& l8 [, Q" R6 g
10. removeListener();

复制代码

要停止监听事件，开发人员也可以使用 off 函数：

1. import { on, off, type MiniAppsEventListener } from '@telegram-apps/sdk';
   
2. 
   
3. const listener: MiniAppsEventListener<'viewport_changed'> = payload => {
   # @/ X2 n9 E# |4 J( L: r
4.   console.log('Viewport changed:', payload);
   # R8 }6 R. P( }$ u) W
5. };
   ' p) v5 Z+ S" m3 A
6. 
   
7. // Start listening to event.
   
8. on('viewport_changed', listener);
   
9. 
   
10. // Remove event listener.
    7 Y" w% j5 ?+ l) E: s" P
11. off('viewport_changed', listener);

复制代码

要只调用监听器一次，请使用第三个布尔参数。

1. import { on } from '@telegram-apps/sdk';
   
2. 
   
3. // Will be automatically removed after the first listener execution.
   
4. on('viewport_changed', (payload) => {
   
5.   console.log('Viewport changed:', payload);
   
6. }, true);

复制代码

subscribe 和 unsubscribe​

要监听从本地 Telegram 应用程序发送的所有事件，开发人员应使用 subscribe 和 unsubscribe：

1. import {
   % H9 K: `5 T, {! ]
2.   subscribe,
   & t0 s8 g. B0 u3 _7 B
3.   unsubscribe,
   
4.   type MiniAppsGlobalEventListener,
   * U5 T" Q8 R0 q; W
5. } from '@telegram-apps/sdk';
   
6. 
   : [; }: j; Q( N9 M* t- A
7. const listener: MiniAppsSubscribeListener = (event) => {
   / c. Z7 n6 l2 d) P0 r9 w- \- [: O, m
8.   console.log('Received event', event);
   
9. };
   5 Q5 p- s; c, Z3 T* U
10. 
    5 n$ k" {# N0 T3 J4 i& ^- I5 T
11. // Listen to all events.
    
12. subscribe(listener);
    
13. 
    
14. // Remove this listener.
    2 `1 r) [* \( V$ Z2 b
15. unsubscribe(listener);

复制代码

监听器接受一个包含 name 和 payload 属性的对象，这些属性是迷你应用程序 事件名称和有效载荷。
检查方法支持​

postEvent 函数本身未检查当前本地 Telegram 应用程序是否支持指定方法。 为此，开发人员可以使用 supports 函数，该函数接受 Mini Apps 方法名称和当前平台版本：

1. import { supports } from '@telegram-apps/sdk';
   
2. 
   2 j2 R  `/ c* w
3. supports('web_app_trigger_haptic_feedback', '6.0'); // false
   
4. supports('web_app_trigger_haptic_feedback', '6.1'); // true

复制代码

supports 函数还允许检查方法参数中的指定参数是否受 支持：

1. import { supports } from '@telegram-apps/sdk';
   2 U( w! q+ \, Q
2. 
   * H- P' r! {8 D0 L
3. supports('web_app_open_link', 'try_instant_view', '6.0'); // false
   
4. supports('web_app_open_link', 'try_instant_view', '6.7'); // true

复制代码

TIP

建议在调用 Mini Apps 方法之前使用该函数，以防止应用程序出现 停顿和其他意外行为。

创建更安全的 postEvent​

该软件包包含一个名为 createPostEvent 的函数，它将当前 Mini Apps 版本作为输入。 它返回 postEvent 函数，内部检查是否支持指定的 方法和参数。 如果不是，函数将出错。

1. import { createPostEvent } from '@telegram-apps/sdk';
   
2. 
   
3. const postEvent = createPostEvent('6.5');
   " {: p, ]/ W, t. W4 F
4. 
   
5. // Will work fine.
   
6. postEvent('web_app_read_text_from_clipboard');
   , {4 X  J+ ]& u) b) i0 A% x) R. `
7. 
   
8. // Will throw an error.
   ' Y7 `( b  x/ p( J) t* H
9. postEvent('web_app_request_phone');

复制代码

强烈建议使用此 postEvent 生成器，以确保方法调用按照 的预期运行。
调试​

软件包支持启用调试模式，从而记录与事件 处理相关的信息。 要更改调试模式，请使用setDebug函数：

1. import { setDebug } from '@telegram-apps/sdk';
   
2. 
   
3. setDebug(true);

复制代码

目标源​

如果软件包在浏览器环境（iframe）中使用，则软件包会使用 函数 window.parent.postMessage 。 此功能需要指定目标来源，以确保 事件只发送到受信任的父 iframe。 默认情况下，软件包 使用 https://web.telegram.org 作为原点。 开发人员应使用 setTargetOrigin 函数将事件传输到其他来源：

1. import { setTargetOrigin } from '@telegram-apps/sdk';
   : }. X1 V# [3 c+ V) f# b
2. 
   
3. setTargetOrigin('https://myendpoint.org');

复制代码

WARNING

强烈建议不要长期覆盖此值，否则可能导致安全问题。 只有当您知道自己在做什么时，才能指定该值。

! s, ]# |4 P+ ?  i9 i* M' l
% u' G4 e) n, D' B) l$ v; h

6 B. v. m" b3 m2 f- m