0
# @tarojs/plugin-platform-tt
1

2
The `@tarojs/plugin-platform-tt` is a Taro platform plugin that enables compilation and deployment of Taro applications to TouTiao (ByteDance) mini program platform. This plugin provides platform-specific APIs, components, build configurations, and runtime support necessary for TouTiao mini program development.
3

4
## Package Information
5

6
- **Package Name**: @tarojs/plugin-platform-tt
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/plugin-platform-tt`
10

11
## Core Imports
12

13
```typescript
14
import ttPlatformPlugin from "@tarojs/plugin-platform-tt";
15
import { TT } from "@tarojs/plugin-platform-tt";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const ttPlatformPlugin = require("@tarojs/plugin-platform-tt");
22
const { TT } = require("@tarojs/plugin-platform-tt");
23
```
24

25
Runtime utilities and components:
26

27
```typescript
28
import { 
29
  initNativeApi, 
30
  needPromiseApis, 
31
  components, 
32
  hostConfig 
33
} from "@tarojs/plugin-platform-tt/dist/runtime-utils";
34
```
35

36
## Basic Usage
37

38
```typescript
39
import type { IPluginContext } from '@tarojs/service';
40
import ttPlatformPlugin from '@tarojs/plugin-platform-tt';
41

42
// In a Taro config file
43
export default {
44
  plugins: [
45
    // Register the TouTiao platform plugin
46
    ttPlatformPlugin
47
  ]
48
};
49

50
// The plugin will automatically register the 'tt' platform
51
// when Taro builds with --type tt
52
```
53

54
## Architecture
55

56
The plugin is built around several key components:
57

58
- **Platform Registration**: Integrates with Taro's plugin system to register the TouTiao platform
59
- **Template System**: Provides TouTiao-specific template compilation with SJS support
60
- **Component System**: Maps standard Taro components to TouTiao-specific implementations
61
- **API Adaptation**: Transforms Taro APIs to work with TouTiao's native APIs
62
- **Build Configuration**: Handles platform-specific build settings and file types
63
- **Runtime Support**: Provides runtime utilities for TouTiao mini program execution
64

65
## Capabilities
66

67
### Platform Plugin Registration
68

69
The main plugin function that registers TouTiao platform support with Taro.
70

71
```typescript { .api }
72
/**
73
 * Main plugin function that registers TouTiao platform support
74
 * @param ctx - Taro plugin context providing platform registration capabilities
75
 */
76
export default (ctx: IPluginContext) => {
77
  ctx.registerPlatform({
78
    name: 'tt',
79
    useConfigName: 'mini',
80
    async fn ({ config }) {
81
      // Handles external pages and app configuration
82
      // Creates and starts TT platform instance
83
    }
84
  });
85
};
86
```
87

88
### TT Platform Class
89

90
Platform implementation class that can be extended by other platform plugins.
91

92
```typescript { .api }
93
/**
94
 * TouTiao platform implementation class extending TaroPlatformBase
95
 */
96
export class TT extends TaroPlatformBase {
97
  platform: 'tt';
98
  globalObject: 'tt';
99
  projectConfigJson: 'project.tt.json';
100
  runtimePath: string;
101
  taroComponentsPath: string;
102
  fileType: {
103
    templ: '.ttml';
104
    style: '.ttss';
105
    config: '.json';
106
    script: '.js';
107
    xs: '.sjs';
108
  };
109
  template: Template;
110
  
111
  constructor(ctx: any, config: any);
112
  modifyTemplate(): void;
113
}
114
```
115

116
### Template Engine
117

118
Template compilation system for TouTiao mini program templates.
119

120
```typescript { .api }
121
/**
122
 * Template engine for TouTiao mini program template compilation
123
 */
124
export class Template extends RecursiveTemplate {
125
  supportXS: true;
126
  Adapter: {
127
    if: 'tt:if';
128
    else: 'tt:else';
129
    elseif: 'tt:elif';
130
    for: 'tt:for';
131
    forItem: 'tt:for-item';
132
    forIndex: 'tt:for-index';
133
    key: 'tt:key';
134
    xs: 'sjs';
135
    type: 'tt';
136
  };
137
  
138
  replacePropName(name: string, value: string): string;
139
  buildXsTemplate(filePath?: string): string;
140
}
141
```
142

143
### API Transformation
144

145
Functions for adapting Taro APIs to work with TouTiao platform.
146

147
```typescript { .api }
148
/**
149
 * Transforms API calls for TouTiao platform compatibility
150
 * @param api - API name to transform
151
 * @param options - API options to modify
152
 * @returns Transformed API configuration
153
 */
154
export function transformMeta(
155
  api: string, 
156
  options: Record<string, any>
157
): { key: string; options: Record<string, any> };
158

159
/**
160
 * Initializes native TouTiao APIs in Taro runtime
161
 * @param taro - Taro instance to enhance with TouTiao APIs
162
 */
163
export function initNativeApi(taro: any): void;
164
```
165

166
### Component Configuration
167

168
Pre-configured component settings for TouTiao platform compatibility.
169

170
```typescript { .api }
171
/**
172
 * Component configuration object for TouTiao-specific components
173
 */
174
export const components: {
175
  // Standard components with TouTiao-specific attributes
176
  Icon: { size: '24' };
177
  Input: {
178
    'adjust-position': '!0';
179
    'hold-keyboard': '!1';
180
    'clue-type': '0';
181
    bindKeyboardHeightChange: '';
182
  };
183
  Button: {
184
    bindGetPhoneNumber: '';
185
    'data-channel': '';
186
    'data-aweme-id': '';
187
    'group-id': '';
188
    'data-is-half-page': '';
189
    bindOpenAwemeUserProfile: '';
190
    bindJoinGroup: '';
191
  };
192
  Form: {
193
    'report-submit-timeout': '0';
194
  };
195
  Slider: {
196
    color: "'#e9e9e9'";
197
    'selected-color': "'#1aad19'";
198
  };
199
  WebView: {
200
    'progressbar-color': "'#51a0d8'";
201
  };
202
  Video: {
203
    'play-btn-position': "'center'";
204
    'pre-roll-unit-id': '';
205
    'post-roll-unit-id': '';
206
    'vslide-gesture': '!1';
207
    'vslide-gesture-in-fullscreen': '!0';
208
    'enable-play-gesture': '!1';
209
    'show-playback-rate-btn': '!1';
210
    'enable-play-in-background': '!1';
211
    signature: '';
212
    bindProgress: '';
213
    bindSeekComplete: '';
214
    bindAdLoad: '';
215
    bindAdStart: '';
216
    bindAdEnded: '';
217
    bindAdError: '';
218
    bindAdClose: '';
219
    bindLoadedMetadata: '';
220
    bindPlaybackRateChange: '';
221
    bindMuteChange: '';
222
    bindControlTap: '';
223
    bindEnterBackground: '';
224
    bindCloseBackground: '';
225
    bindLeaveBackground: '';
226
  };
227
  Ad: {
228
    fixed: '';
229
    type: "'banner'";
230
    scale: '100';
231
  };
232
  Textarea: {
233
    'disable-default-padding': '!1';
234
    'confirm-type': "'return'";
235
    'confirm-hold': '!1';
236
    'show-confirm-bar': '!0';
237
    'adjust-position': '!0';
238
    'hold-keyboard': '!1';
239
  };
240
  ScrollView: {
241
    enhanced: '!1';
242
    bounces: '!0';
243
    'refresher-enabled': '!1';
244
    'refresher-threshold': '55';
245
    'refresher-default-style': "'black'";
246
    'refresher-background': "'#FFF'";
247
    'refresher-triggered': '!1';
248
    bindRefresherPulling: '';
249
    bindRefresherRefresh: '';
250
    bindRefresherRestore: '';
251
    bindRefresherAbort: '';
252
  };
253
  Canvas: {
254
    type: '';
255
  };
256
  Map: {
257
    polygons: '[]';
258
    rotate: '0';
259
    skew: '0';
260
    'max-scale': '19';
261
    'min-scale': '3';
262
    'enable-3D': '!1';
263
    'show-compass': '!1';
264
    'show-scale': '!1';
265
    'enable-overlooking': '!1';
266
    'enable-zoom': '!0';
267
    'enable-scroll': '!0';
268
    'enable-rotate': '!1';
269
    'enable-satellite': '!1';
270
    'enable-traffic': '!1';
271
    'enable-poi': '!0';
272
    'enable-building': '!0';
273
    bindLabelTap: '';
274
    bindRegionChange: '';
275
    bindAnchorPointTap: '';
276
  };
277
  // TouTiao-specific components
278
  RtcRoom: {
279
    'user-id': '';
280
    mode: 'camera';
281
    'device-position': 'front';
282
    bindError: '';
283
  };
284
  PayButton: {
285
    mode: '1';
286
    'goods-id': '';
287
    'goods-type': '';
288
    'order-status': '0';
289
    'order-id': '';
290
    'refund-id': '';
291
    'refund-total-amount': '';
292
    'biz-line': '1';
293
    'marketing-ready': '!1';
294
    bindGetGoodsInfo: '';
295
    bindPlaceOrder: '';
296
    bindError: '';
297
    bindApplyRefund: '';
298
    bindRefund: '';
299
    bindPay: '';
300
  };
301
  ConsumeCard: {
302
    'order-id': '';
303
    bindConsume: '';
304
    bindRefund: '';
305
    bindApplyRefund: '';
306
    bindError: '';
307
  };
308
  AwemeData: {
309
    'aweme-id': '';
310
    type: "'avatar'";
311
    'disable-default': '';
312
    'default-avatar': '';
313
    'default-text': '';
314
    bindError: '';
315
  };
316
  RateButton: {
317
    'order-id': '';
318
    bindInit: '';
319
    bindSuccess: '';
320
    bindError: '';
321
  };
322
  OpenData: {
323
    type: '';
324
    'default-text': '';
325
    'default-avatar': '';
326
    'use-empty-value': '!1';
327
    bindError: '';
328
  };
329
  AwemeUserCard: {
330
    'aweme-id': '';
331
    width: '504';
332
    height: '144';
333
    fixed: '!1';
334
    'left-right-padding': '';
335
    bindError: '';
336
  };
337
};
338
```
339

340
### Promise-based APIs
341

342
Set of TouTiao APIs that require Promise wrapping for asynchronous operations.
343

344
```typescript { .api }
345
/**
346
 * Set of API names that need Promise wrapping for TouTiao platform
347
 */
348
export const needPromiseApis: Set<string>;
349
```
350

351
The set includes these TouTiao-specific APIs:
352
- `applyRefund` - Apply for refund operations
353
- `canRateAwemeOrders` - Check if orders can be rated
354
- `checkFollowAwemeState` - Check follow state for Aweme users
355
- `checkFollowState` - Check general follow state  
356
- `continueToPay` - Continue payment process
357
- `createOrder` - Create new orders
358
- `exitMiniProgram` - Exit mini program
359
- `followAwemeUser` - Follow Aweme users
360
- `followOfficialAccount` - Follow official accounts
361
- `getMenuButtonLayout` - Get menu button layout information
362
- `getUserProfile` - Get user profile data
363
- `hideInteractionBar` - Hide interaction bar
364
- `navigateToVideoView` - Navigate to video view
365
- `openAwemeUserProfile` - Open Aweme user profiles
366
- `openEcGood` - Open e-commerce goods
367
- `openWebcastRoom` - Open webcast rooms
368
- `pay` - Process payments
369
- `rateAwemeOrder` - Rate Aweme orders
370
- `showDouyinOpenAuth` - Show Douyin authorization
371
- `showInteractionBar` - Show interaction bar
372

373
### React Components
374

375
TouTiao-specific React components for use in Taro applications.
376

377
```typescript { .api }
378
/**
379
 * Re-exports all standard Taro mini program components
380
 */
381
export * from '@tarojs/components/mini';
382

383
/**
384
 * TouTiao-specific React components
385
 */
386
export const RtcRoom: 'rtc-room';
387
export const PayButton: 'pay-button';
388
export const ConsumeCard: 'consume-card';
389
export const AwemeData: 'aweme-data';
390
export const RateButton: 'rate-button';
391
export const OpenData: 'open-data';
392
export const AwemeUserCard: 'aweme-user-card';
393
```
394

395
### Runtime Configuration
396

397
Runtime host configuration for TouTiao platform integration.
398

399
```typescript { .api }
400
/**
401
 * Runtime host configuration for TouTiao platform
402
 */
403
export const hostConfig: {
404
  initNativeApi: (taro: any) => void;
405
  modifyMpEventImpl: (event: any) => void;
406
  modifyTaroEventReturn: (node: any, event: any, returnVal: any) => any;
407
};
408
```
409

410
The `hostConfig` object provides:
411

412
- **`initNativeApi`**: Initializes TouTiao native APIs in the Taro runtime
413
- **`modifyMpEventImpl`**: Modifies events, specifically transforming `regionchange` events to use `event.detail.type`
414
- **`modifyTaroEventReturn`**: Handles special return value processing for `pay-button` component events (`applyrefund` and `getgoodsinfo`)
415

416
### Type Extensions
417

418
TypeScript type extensions for Taro APIs with TouTiao-specific properties.
419

420
```typescript { .api }
421
declare module '@tarojs/taro' {
422
  namespace getSystemInfoSync {
423
    interface Result {
424
      /** Host APP name for TouTiao platform */
425
      appName?: string;
426
    }
427
  }
428

429
  namespace getSystemInfo {
430
    interface Result {
431
      /** Host APP name for TouTiao platform */
432
      appName?: string;
433
    }
434
  }
435
}
436
```
437

438
## External Page Handling
439

440
The plugin automatically handles external pages (pages with `ext://` prefix) by:
441

442
1. Filtering external pages from the main app configuration during `modifyAppConfig`
443
2. Collecting external page references in an array
444
3. Adding external pages back to the final build assets via `modifyBuildAssets`
445
4. Ensuring external pages are properly included in the compiled app.json
446

447
This allows TouTiao mini programs to reference external pages hosted by the platform while maintaining proper build configuration.
448

449
## Error Handling
450

451
The plugin handles several error scenarios:
452

453
- **Template compilation errors**: Provides fallbacks for unsupported template directives
454
- **API transformation errors**: Safely transforms API calls with error boundaries
455
- **Component configuration errors**: Uses default values when custom configurations fail
456
- **Build asset errors**: Handles missing or malformed app.json files gracefully
457

458
## Platform-Specific Features
459

460
### File Extensions
461
- **Templates**: `.ttml` files for TouTiao template markup
462
- **Styles**: `.ttss` files for TouTiao-specific styling
463
- **Scripts**: `.sjs` files for TouTiao Script (similar to WXS)
464
- **Configuration**: `.json` files for component and page configuration
465

466
### Build Configuration
467
- **Project config**: Uses `project.tt.json` for TouTiao-specific project settings
468
- **Global object**: Accesses TouTiao APIs through the global `tt` object
469
- **Runtime path**: Loads runtime files from the plugin's dist directory
470

471
### Event System
472
- **Event transformation**: Converts `regionchange` events to use `event.detail.type`
473
- **Custom event handling**: Special handling for `pay-button` component events
474
- **Event binding**: Automatic binding transformation (e.g., `bindlongtap` → `bindlongpress`)