0
# User Interface APIs
1

2
Comprehensive UI control APIs for displaying toasts, modals, action sheets, and managing screen properties in Taro React Native applications.
3

4
## Capabilities
5

6
### Toast Messages
7

8
Display temporary toast messages with different styles and durations.
9

10
```typescript { .api }
11
/**
12
 * Show a toast message
13
 * @param options Toast configuration options
14
 */
15
function showToast(options: {
16
  title: string;
17
  icon?: 'success' | 'error' | 'loading' | 'none';
18
  image?: string;
19
  duration?: number;
20
  mask?: boolean;
21
  success?: (res: TaroGeneral.CallbackResult) => void;
22
  fail?: (res: TaroGeneral.CallbackResult) => void;
23
  complete?: (res: TaroGeneral.CallbackResult) => void;
24
}): Promise<TaroGeneral.CallbackResult>;
25

26
/**
27
 * Hide the currently shown toast
28
 * @param options Hide toast options
29
 */
30
function hideToast(options?: {
31
  success?: (res: TaroGeneral.CallbackResult) => void;
32
  fail?: (res: TaroGeneral.CallbackResult) => void;
33
  complete?: (res: TaroGeneral.CallbackResult) => void;
34
}): void;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { showToast, hideToast } from "@tarojs/taro-rn";
41

42
// Show success toast
43
await showToast({
44
  title: 'Success!',
45
  icon: 'success',
46
  duration: 2000
47
});
48

49
// Show custom image toast
50
await showToast({
51
  title: 'Custom Toast',
52
  image: '/images/custom-icon.png',
53
  duration: 3000
54
});
55

56
// Hide toast manually
57
hideToast();
58
```
59

60
### Loading Indicators
61

62
Display loading indicators for asynchronous operations.
63

64
```typescript { .api }
65
/**
66
 * Show a loading indicator
67
 * @param options Loading configuration options
68
 */
69
function showLoading(options?: {
70
  title?: string;
71
  mask?: boolean;
72
  success?: (res: TaroGeneral.CallbackResult) => void;
73
  fail?: (res: TaroGeneral.CallbackResult) => void;
74
  complete?: (res: TaroGeneral.CallbackResult) => void;
75
}): Promise<TaroGeneral.CallbackResult>;
76

77
/**
78
 * Hide the loading indicator
79
 * @param options Hide loading options
80
 */
81
function hideLoading(options?: {
82
  success?: (res: TaroGeneral.CallbackResult) => void;
83
  fail?: (res: TaroGeneral.CallbackResult) => void;
84
  complete?: (res: TaroGeneral.CallbackResult) => void;
85
}): void;
86
```
87

88
### Modal Dialogs
89

90
Display modal dialogs with customizable content and actions.
91

92
```typescript { .api }
93
/**
94
 * Show a modal dialog
95
 * @param options Modal configuration options
96
 */
97
function showModal(options: {
98
  title?: string;
99
  content?: string;
100
  showCancel?: boolean;
101
  cancelText?: string;
102
  cancelColor?: string;
103
  confirmText?: string;
104
  confirmColor?: string;
105
  success?: (res: { confirm: boolean; cancel: boolean }) => void;
106
  fail?: (res: TaroGeneral.CallbackResult) => void;
107
  complete?: (res: any) => void;
108
}): Promise<{ confirm: boolean; cancel: boolean }>;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { showModal, showLoading, hideLoading } from "@tarojs/taro-rn";
115

116
// Show loading
117
await showLoading({ title: 'Loading...' });
118

119
// Simulate async operation
120
setTimeout(() => {
121
  hideLoading();
122
}, 2000);
123

124
// Show confirmation modal
125
const result = await showModal({
126
  title: 'Confirm Action',
127
  content: 'Are you sure you want to delete this item?',
128
  showCancel: true,
129
  cancelText: 'Cancel',
130
  confirmText: 'Delete'
131
});
132

133
if (result.confirm) {
134
  console.log('User confirmed');
135
}
136
```
137

138
### Action Sheets
139

140
Display action sheets for presenting multiple options to users.
141

142
```typescript { .api }
143
/**
144
 * Show an action sheet
145
 * @param options Action sheet configuration options
146
 */
147
function showActionSheet(options: {
148
  itemList: string[];
149
  itemColor?: string;
150
  success?: (res: { tapIndex: number }) => void;
151
  fail?: (res: TaroGeneral.CallbackResult) => void;
152
  complete?: (res: any) => void;
153
}): Promise<{ tapIndex: number }>;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { showActionSheet } from "@tarojs/taro-rn";
160

161
// Show action sheet with options
162
const result = await showActionSheet({
163
  itemList: ['Option 1', 'Option 2', 'Option 3'],
164
  itemColor: '#007AFF'
165
});
166

167
console.log('Selected option index:', result.tapIndex);
168
```
169

170
### Screen Properties
171

172
Control screen brightness and keep-awake functionality.
173

174
```typescript { .api }
175
/**
176
 * Set screen brightness
177
 * @param options Brightness options
178
 */
179
function setScreenBrightness(options: {
180
  value: number; // 0-1
181
  success?: (res: TaroGeneral.CallbackResult) => void;
182
  fail?: (res: TaroGeneral.CallbackResult) => void;
183
  complete?: (res: TaroGeneral.CallbackResult) => void;
184
}): Promise<TaroGeneral.CallbackResult>;
185

186
/**
187
 * Get current screen brightness
188
 * @param options Get brightness options
189
 */
190
function getScreenBrightness(options?: {
191
  success?: (res: { value: number }) => void;
192
  fail?: (res: TaroGeneral.CallbackResult) => void;
193
  complete?: (res: any) => void;
194
}): Promise<{ value: number }>;
195

196
/**
197
 * Keep screen on or allow it to turn off
198
 * @param options Keep screen on options
199
 */
200
function setKeepScreenOn(options: {
201
  keepScreenOn: boolean;
202
  success?: (res: TaroGeneral.CallbackResult) => void;
203
  fail?: (res: TaroGeneral.CallbackResult) => void;
204
  complete?: (res: TaroGeneral.CallbackResult) => void;
205
}): Promise<TaroGeneral.CallbackResult>;
206
```
207

208
### Image Preview
209

210
Display full-screen image preview with zoom and swipe functionality.
211

212
```typescript { .api }
213
/**
214
 * Preview images in full screen
215
 * @param options Image preview options
216
 */
217
function previewImage(options: {
218
  urls: string[];
219
  current?: string;
220
  success?: (res: TaroGeneral.CallbackResult) => void;
221
  fail?: (res: TaroGeneral.CallbackResult) => void;
222
  complete?: (res: TaroGeneral.CallbackResult) => void;
223
}): Promise<TaroGeneral.CallbackResult>;
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { 
230
  setScreenBrightness, 
231
  setKeepScreenOn, 
232
  previewImage 
233
} from "@tarojs/taro-rn";
234

235
// Set screen brightness to 50%
236
await setScreenBrightness({ value: 0.5 });
237

238
// Keep screen on
239
await setKeepScreenOn({ keepScreenOn: true });
240

241
// Preview images
242
await previewImage({
243
  urls: [
244
    'https://example.com/image1.jpg',
245
    'https://example.com/image2.jpg'
246
  ],
247
  current: 'https://example.com/image1.jpg'
248
});
249
```
250

251
### Keyboard Management
252

253
Control keyboard visibility and handle keyboard height changes.
254

255
```typescript { .api }
256
/**
257
 * Hide the keyboard
258
 * @param options Hide keyboard options
259
 */
260
function hideKeyboard(options?: {
261
  success?: (res: TaroGeneral.CallbackResult) => void;
262
  fail?: (res: TaroGeneral.CallbackResult) => void;
263
  complete?: (res: TaroGeneral.CallbackResult) => void;
264
}): Promise<TaroGeneral.CallbackResult>;
265

266
/**
267
 * Listen to keyboard height changes
268
 * @param callback Callback function when keyboard height changes
269
 */
270
function onKeyboardHeightChange(callback: (res: { height: number }) => void): void;
271

272
/**
273
 * Stop listening to keyboard height changes
274
 * @param callback Optional callback to remove specific listener
275
 */
276
function offKeyboardHeightChange(callback?: (res: { height: number }) => void): void;
277
```
278

279
### DOM Query
280

281
Create selector queries for DOM element information.
282

283
```typescript { .api }
284
/**
285
 * Create a selector query instance
286
 * @returns SelectorQuery instance
287
 */
288
function createSelectorQuery(): SelectorQuery;
289

290
interface SelectorQuery {
291
  select(selector: string): NodesRef;
292
  selectAll(selector: string): NodesRef;
293
  selectViewport(): NodesRef;
294
  exec(callback?: (res: any[]) => void): Promise<any[]>;
295
}
296

297
interface NodesRef {
298
  boundingClientRect(callback?: (res: any) => void): SelectorQuery;
299
  scrollOffset(callback?: (res: any) => void): SelectorQuery;
300
  fields(fields: {
301
    id?: boolean;
302
    dataset?: boolean;
303
    rect?: boolean;
304
    size?: boolean;
305
    scrollOffset?: boolean;
306
    properties?: string[];
307
  }, callback?: (res: any) => void): SelectorQuery;
308
}
309
```
310

311
**Usage Examples:**
312

313
```typescript
314
import { createSelectorQuery, hideKeyboard } from "@tarojs/taro-rn";
315

316
// Hide keyboard
317
await hideKeyboard();
318

319
// Query DOM elements
320
const query = createSelectorQuery();
321
const result = await query
322
  .select('#my-element')
323
  .boundingClientRect()
324
  .exec();
325

326
console.log('Element bounds:', result[0]);
327
```