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

riyad

方法与事件​

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

调用方法​

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

1. import { postEvent } from '@telegram-apps/sdk';
   7 G* U8 M/ B  W7 ]; @
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/sdk';
   # E$ j) t9 w4 F5 \* F  H
2. 
   ) l1 k& c6 e, \# }3 V0 z
3. const viewport = await request({
   
4.   method: 'web_app_request_viewport',
   
5.   event: 'viewport_changed'
   
6. });
   ; C1 [. _7 {2 t" V7 h) Y
7. 
   ) ~1 \) m! ~5 P9 w" y
8. console.log(viewport);
   
9. // Output:
   $ u, I! ?# l2 [' {
10. // {
    * l1 |  p' x. u4 o
11. //   is_state_stable: true,
    - h3 b. T; Z2 Q& ^; g6 P" q8 Z
12. //   is_expanded: false,
    
13. //   height: 320
    
14. // };

复制代码

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

1. import { request } from '@telegram-apps/sdk';
   : H9 e; k0 q) H. ?9 U
2. 
   . g( Q& l" ^9 V' s- {! Q4 q
3. const buttonId = await request({
   8 X! }9 u* @) h
4.   method: 'web_app_open_popup',
   ) I. I! E( j: a
5.   event: 'popup_closed',
   - O0 v3 e( A/ Z0 |( v
6.   params: {
   
7.     title: 'Caution',
   
8.     message: 'Should we delete you account?',
   : R- x5 h5 t+ r" X& s  [
9.     buttons: [
     h$ h0 P# D. N3 {9 e- D. F5 T
10.       { id: 'yes', type: 'ok' },
    / m' _: F  T$ d3 k- P8 l5 b
11.       { id: 'no', type: 'cancel' },
    - j# J* A5 F+ W3 y: o4 v5 I) P" |
12.     ],
    8 Q+ y7 ^% `# u5 y/ Y' }
13.   },
    
14. });

复制代码

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

1. import { request } from '@telegram-apps/sdk';
   
2. 
   + `( V' J9 r8 F2 i6 o+ r# X
3. const result = await request({
     H- c! R/ K% n: f# N8 H
4.   method: 'web_app_open_scan_qr_popup',
   
5.   event: ['qr_text_received', 'scan_qr_popup_closed'],
   
6. });
   
7. 
   ' T5 h: R7 Z! i% K# x
8. // result will either be qr_text_received or
   2 p/ @* m  V! Y( X
9. // scan_qr_popup_closed events payload.

复制代码

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

9 w! m3 s: U" B- t5 ?7 z3 H- |postEvent​

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

1. import { request, createPostEvent } from '@telegram-apps/sdk';
   
2. 
   ; u( t+ n0 y0 {  w2 r
3. request({
   ; l7 k3 j: ~# [  O5 R
4.   method: 'web_app_request_viewport',
   6 Q5 o. [7 |8 e
5.   event: 'viewport_changed',
   ! @* v. M# V2 z# I. j
6.   postEvent: createPostEvent('6.5'),
   % C" x4 S) F' _7 z4 P
7. });

复制代码

timeout​

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

1. import { request, isTimeoutError } from '@telegram-apps/sdk';
   
2. 
   ' l: R. \( S5 V3 }
3. try {
   
4.   await request({
   : e- H/ F6 v+ v! r% N
5.     method: 'web_app_invoke_custom_method',
   
6.     event: 'custom_method_invoked',
   / u( i1 h' |7 C5 j  K1 ~6 l
7.     timeout: 5000,
   
8.     params: {
   
9.       req_id: '1',
   % z& z# G9 Y& W+ q$ W$ J
10.       method: 'deleteStorageValues',
    % j/ l9 x& A" J3 {
11.       params: { keys: ['a'] },
    
12.     },
    
13.   });
    
14. } catch (e) {
    
15.   console.error(isTimeoutError(e) ? 'Timeout error' : 'Some different error', e);
    
16. }

复制代码

capture​

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

1. const slug = 'jjKSJnm1k23lodd';
   3 B( G; P& a2 U- z) ?
2. 
   
3. request({
   / C& B9 q' k) E
4.   method: 'web_app_open_invoice',
   
5.   event: 'invoice_closed',
   
6.   params: { slug },
   ( u5 v. ~% J3 U. f8 G3 p# K( [
7.   capture(data) {
   3 H4 t& B& J. f* {* M: `! l2 w5 \' q
8.     return slug === data.slug;
   " r- c: p8 D: u- M( O
9.   },
   ' \' R4 ?: g( h  I1 J5 e9 h
10. });

复制代码

默认情况下，request 函数会捕获带有所需名称的第一个事件。 在 的情况下，request 函数只有在事件具有预期的标签时才会捕获事件。
调用自定义方法​

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

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

1. import { request } from '@telegram-apps/sdk';
   ( e4 b$ b: c1 n! i$ S  y; B( L/ |
2. 
   
3. const reqId = 'ABC';
   5 ]( r! o& w3 e. G
4. 
   
5. request({
   
6.   method: 'web_app_invoke_custom_method',
   
7.   event: 'custom_method_invoked',
   
8.   params: {
   
9.     req_id: reqId,
   
10.     method: 'deleteStorageValues',
    
11.     params: { keys: ['a'] },
    - Y0 A8 f$ z4 A+ ?5 V
12.   },
    
13.   capture(data) {
    
14.     return data.req_id === reqId;
    
15.   }
    
16. });

复制代码

这样，我们就可以使用 invokeCustomMethod 函数重写它了：

9 [) O0 \, b: k) l

1. import { invokeCustomMethod } from '@telegram-apps/sdk';
   
2. 
   
3. invokeCustomMethod('deleteStorageValues', { keys: ['a'] }, 'ABC');

复制代码

invokeCustomMethod('deleteStorageValues', { keys: ['a'] }, 'ABC');

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

事件监听​on 和 off​

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

1. import { on } from '@telegram-apps/sdk';
   : G2 G! K1 Y& M
2. 
   
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 => {
   & H" v, u/ u- [' U$ i9 B0 n
6.   console.log('Viewport changed:', payload);
   % ]  R( ~* D; }6 P( j5 D/ X" w
7. });
   $ X; S/ V# v, }4 `3 b
8. 
   
9. // Remove this event listener.
   3 d# k) ^, G5 i/ @. j% m( j
10. removeListener();

复制代码

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

% f0 ~. l, m  w+ K2 Z

1. import { on, off, type MiniAppsEventListener } from '@telegram-apps/sdk';
   7 }% g" b3 X, ?) n# k* P$ ~  K' T
2. 
   
3. const listener: MiniAppsEventListener<'viewport_changed'> = payload => {
   
4.   console.log('Viewport changed:', payload);
   
5. };
   
6. 
   
7. // Start listening to event.
   ) k  W9 t0 a: o
8. on('viewport_changed', listener);
   
9. 
   . E) e" g. z" a3 @8 f% x
10. // Remove event listener.
    
11. off('viewport_changed', listener);

复制代码

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

3 h0 ?* J- X; j  ], W2 |

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);
   & g# H" ^) ~  m
6. }, true);

复制代码

subscribe 和 unsubscribe​

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

1. import {
   
2.   subscribe,
   
3.   unsubscribe,
   9 X: R8 t" h# |7 }5 I* r
4.   type MiniAppsGlobalEventListener,
   - d2 M9 I# Q7 s  f2 S: `1 Y
5. } from '@telegram-apps/sdk';
   6 o; z* R; j5 P- |" @
6. 
   ) f) c5 Z  V- [& ~
7. const listener: MiniAppsSubscribeListener = (event) => {
   
8.   console.log('Received event', event);
   
9. };
   
10. 
    $ q& D7 c% c, `# J
11. // Listen to all events.
    
12. subscribe(listener);
    
13. 
    ; K2 r! a+ ~( J: o5 b2 [) G
14. // Remove this listener.
    3 g! |+ M4 ^% ~1 j0 j% L) s
15. unsubscribe(listener);

复制代码

监听器接受一个包含 name 和 payload 属性的对象，这些属性是迷你应用程序 事件名称和有效载荷。
+ N5 d, O) \1 w& {( A2 w检查方法支持​

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

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

复制代码

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

; [2 l& m, J# E: L% d

1. import { supports } from '@telegram-apps/sdk';
   8 l2 d3 I% S4 P  v
2. 
   
3. supports('web_app_open_link', 'try_instant_view', '6.0'); // false
   ) Q( g5 J. n* ^- o
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';
   9 ]* ^4 M" {9 A' D1 Z7 H
2. 
   " e' x6 U7 z9 Y* ~( z: X  j3 I
3. const postEvent = createPostEvent('6.5');
   
4. 
   1 Q! k3 Q! z; @! D
5. // Will work fine.
   
6. postEvent('web_app_read_text_from_clipboard');
   8 V! s- ~1 j2 p/ |  V
7. 
   
8. // Will throw an error.
   
9. postEvent('web_app_request_phone');

复制代码

强烈建议使用此 postEvent 生成器，以确保方法调用按照 的预期运行。
4 L( s- [  ]$ ~8 w$ B" i调试​

软件包支持启用调试模式，从而记录与事件 处理相关的信息。 要更改调试模式，请使用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';
   
2. 
   ( Q, U1 o1 F( \9 z9 @
3. setTargetOrigin('https://myendpoint.org');

复制代码

3 H' s1 o1 {1 q! }; H

WARNING

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

2 t9 F0 b- h6 Q. S% @# @8 G
4 w5 J1 b, d& L' E1 j6 W% J8 }) C
" ]$ S" d) V$ g' \: ?) e