0
# Command System
1
2
The command system provides extensible toolbar actions and text formatting capabilities through a comprehensive set of built-in commands and support for custom commands.
3
4
## Capabilities
5
6
### Command Interface
7
8
Core interface for defining toolbar commands and text formatting actions.
9
10
```typescript { .api }
11
/**
12
* Base interface for command definitions used in toolbar and text formatting
13
*/
14
interface ICommandBase<T = string> {
15
/** Parent command reference */
16
parent?: ICommand<any>;
17
/** Internal command key */
18
keyCommand?: string;
19
/** Command name identifier */
20
name?: string;
21
/** Keyboard shortcuts */
22
shortcuts?: string;
23
/** Group name for command organization */
24
groupName?: string;
25
/** Command icon React element */
26
icon?: React.ReactElement;
27
/** Command value */
28
value?: string;
29
/** Text prefix for formatting commands */
30
prefix?: string;
31
/** Text suffix for formatting commands */
32
suffix?: string;
33
/** Toolbar position */
34
position?: 'right';
35
/** List item HTML attributes */
36
liProps?: React.LiHTMLAttributes<HTMLLIElement>;
37
/** Button props (null disables button rendering) */
38
buttonProps?: React.ButtonHTMLAttributes<HTMLButtonElement> | null;
39
/** Custom render function for command UI */
40
render?: (
41
command: ICommand<T>,
42
disabled: boolean,
43
executeCommand: (command: ICommand<T>, name?: string) => void,
44
index: number
45
) => void | undefined | null | React.ReactElement;
46
/** Command execution function */
47
execute?: (
48
state: ExecuteState,
49
api: TextAreaTextApi,
50
dispatch?: React.Dispatch<ContextStore>,
51
executeCommandState?: ExecuteCommandState,
52
shortcuts?: string[]
53
) => void;
54
}
55
56
/**
57
* Command with array of child commands
58
*/
59
interface ICommandChildCommands<T = string> extends ICommandBase<T> {
60
children?: Array<ICommand<T>>;
61
}
62
63
/**
64
* Command with render function for child components
65
*/
66
interface ICommandChildHandle<T = string> extends ICommandBase<T> {
67
children?: (handle: {
68
close: () => void;
69
execute: () => void;
70
getState?: TextAreaCommandOrchestrator['getState'];
71
textApi?: TextAreaTextApi;
72
dispatch?: React.Dispatch<ContextStore>;
73
}) => React.ReactElement;
74
}
75
76
/**
77
* Union type for all command variations
78
*/
79
type ICommand<T = string> = ICommandChildCommands<T> | ICommandChildHandle<T>;
80
81
interface ExecuteState extends TextState {
82
command: ICommand;
83
}
84
85
interface ExecuteCommandState {
86
fullscreen?: boolean;
87
preview?: PreviewType;
88
highlightEnable?: boolean;
89
}
90
```
91
92
### Built-in Commands
93
94
Comprehensive set of pre-built commands for common markdown formatting and editor controls.
95
96
```typescript { .api }
97
/**
98
* Built-in commands namespace containing all available commands
99
*/
100
declare const commands: {
101
// Text formatting commands
102
bold: ICommand;
103
italic: ICommand;
104
strikethrough: ICommand;
105
106
// Heading commands
107
title: ICommand; // Alias for title1
108
heading: ICommand; // Alias for title1
109
title1: ICommand; // H1 heading
110
heading1: ICommand; // H1 heading
111
title2: ICommand; // H2 heading
112
heading2: ICommand; // H2 heading
113
title3: ICommand; // H3 heading
114
heading3: ICommand; // H3 heading
115
title4: ICommand; // H4 heading
116
heading4: ICommand; // H4 heading
117
title5: ICommand; // H5 heading
118
heading5: ICommand; // H5 heading
119
title6: ICommand; // H6 heading
120
heading6: ICommand; // H6 heading
121
122
// Content commands
123
link: ICommand; // Link insertion [text](url)
124
quote: ICommand; // Quote block >
125
code: ICommand; // Inline code `code`
126
codeBlock: ICommand; // Code block ```
127
comment: ICommand; // HTML comment <!-- -->
128
image: ICommand; // Image insertion 
129
table: ICommand; // Table insertion
130
hr: ICommand; // Horizontal rule ---
131
132
// List commands
133
unorderedListCommand: ICommand; // Unordered list -
134
orderedListCommand: ICommand; // Ordered list 1.
135
checkedListCommand: ICommand; // Checklist - [ ]
136
137
// UI commands
138
divider: ICommand; // Visual separator in toolbar
139
group: ICommand; // Command grouping utility
140
help: ICommand; // Help command
141
issue: ICommand; // Issue link command
142
143
// Preview mode commands
144
codeEdit: ICommand; // Edit mode only
145
codeLive: ICommand; // Split edit/preview mode
146
codePreview: ICommand; // Preview mode only
147
fullscreen: ICommand; // Toggle fullscreen mode
148
};
149
```
150
151
**Usage Examples:**
152
153
```typescript
154
import MDEditor, { commands } from "@uiw/react-md-editor";
155
156
// Basic command selection
157
function EditorWithBasicCommands() {
158
const [value, setValue] = useState("");
159
160
return (
161
<MDEditor
162
value={value}
163
onChange={setValue}
164
commands={[
165
commands.bold,
166
commands.italic,
167
commands.strikethrough,
168
commands.hr,
169
commands.divider,
170
commands.link,
171
commands.quote,
172
commands.code,
173
commands.image
174
]}
175
/>
176
);
177
}
178
179
// Full command set
180
function EditorWithAllCommands() {
181
return (
182
<MDEditor
183
value={value}
184
onChange={setValue}
185
commands={[
186
commands.bold, commands.italic, commands.strikethrough,
187
commands.title1, commands.title2, commands.title3,
188
commands.title4, commands.title5, commands.title6,
189
commands.link, commands.quote, commands.code, commands.codeBlock,
190
commands.comment, commands.image, commands.table, commands.hr,
191
commands.unorderedListCommand, commands.orderedListCommand,
192
commands.checkedListCommand
193
]}
194
extraCommands={[
195
commands.codeEdit, commands.codeLive, commands.codePreview,
196
commands.divider, commands.fullscreen
197
]}
198
/>
199
);
200
}
201
```
202
203
### Command Functions
204
205
Utility functions for working with commands and getting default command sets.
206
207
```typescript { .api }
208
/**
209
* Get the default commands array
210
* @returns Array of default commands for the toolbar
211
*/
212
declare function getCommands(): ICommand[];
213
214
/**
215
* Get the default extra commands array (preview modes, fullscreen)
216
* @returns Array of extra commands for the toolbar
217
*/
218
declare function getExtraCommands(): ICommand[];
219
220
/**
221
* Execute heading command with specified level
222
* @param state - Current execution state
223
* @param api - Text API for manipulation
224
* @param dispatch - State dispatcher
225
* @param executeCommandState - Execute command state
226
* @param shortcuts - Keyboard shortcuts array
227
* @param level - Heading level (1-6)
228
*/
229
declare function headingExecute(
230
state: ExecuteState,
231
api: TextAreaTextApi,
232
dispatch?: React.Dispatch<ContextStore>,
233
executeCommandState?: ExecuteCommandState,
234
shortcuts?: string[],
235
level?: number
236
): void;
237
```
238
239
### Custom Commands
240
241
Create custom commands for specialized functionality.
242
243
```typescript { .api }
244
/**
245
* Example custom command implementation
246
*/
247
const customCommand: ICommand = {
248
name: 'custom',
249
keyCommand: 'custom',
250
shortcuts: 'ctrl+k',
251
prefix: '**CUSTOM:** ',
252
suffix: '',
253
icon: <CustomIcon />,
254
execute: (state: ExecuteState) => {
255
const { textApi, dispatch } = state;
256
const selectedText = textApi.getState()?.selectedText || 'default text';
257
textApi.replaceSelection(`**CUSTOM:** ${selectedText}`);
258
dispatch?.({ type: 'custom_action' });
259
}
260
};
261
262
/**
263
* Group options for organizing commands
264
*/
265
type GroupOptions = Omit<ICommand<string>, 'children'> & {
266
children?: ICommandChildHandle['children'];
267
};
268
269
/**
270
* Create a grouped command containing multiple child commands
271
* @param arr - Array of child commands to group together
272
* @param options - Configuration options for the group
273
* @returns Group command with dropdown behavior
274
*/
275
declare function group(arr: ICommandChildCommands['children'], options?: GroupOptions): ICommand<string>;
276
```
277
278
**Usage Examples:**
279
280
```typescript
281
// Command filtering
282
function EditorWithFilteredCommands() {
283
const commandsFilter = (command: ICommand, isExtra: boolean) => {
284
// Remove certain commands
285
if (command.keyCommand === 'image') return false;
286
return command;
287
};
288
289
return (
290
<MDEditor
291
value={value}
292
onChange={setValue}
293
commandsFilter={commandsFilter}
294
/>
295
);
296
}
297
298
// Using the group function
299
import { group, commands } from "@uiw/react-md-editor";
300
301
const titleGroup = group([
302
commands.title1,
303
commands.title2,
304
commands.title3,
305
commands.title4,
306
commands.title5,
307
commands.title6
308
], {
309
name: 'title',
310
groupName: 'title',
311
buttonProps: { 'aria-label': 'Insert title', title: 'Insert title' }
312
});
313
314
// Custom commands with children
315
const customGroup: ICommand = {
316
name: 'customGroup',
317
groupName: 'Custom',
318
icon: <GroupIcon />,
319
children: [
320
commands.bold,
321
commands.italic,
322
{
323
name: 'customAction',
324
keyCommand: 'customAction',
325
icon: <ActionIcon />,
326
execute: (state) => {
327
// Custom action logic
328
}
329
}
330
]
331
};
332
```
333
334
### Command Orchestration
335
336
Classes for managing command execution and textarea manipulation.
337
338
```typescript { .api }
339
/**
340
* Command orchestrator for managing command execution on textarea elements
341
*/
342
declare class TextAreaCommandOrchestrator {
343
constructor(textArea: HTMLTextAreaElement);
344
345
/**
346
* Get current textarea state
347
* @returns Current text state or false if unavailable
348
*/
349
getState(): false | TextState;
350
351
/**
352
* Execute a command on the textarea
353
* @param command - Command to execute
354
* @param dispatch - Optional state dispatcher
355
* @param state - Optional context state
356
* @param shortcuts - Optional keyboard shortcuts
357
*/
358
executeCommand(
359
command: ICommand,
360
dispatch?: React.Dispatch<ContextStore>,
361
state?: ContextStore,
362
shortcuts?: string
363
): void;
364
}
365
366
/**
367
* Generic command orchestrator interface
368
*/
369
interface CommandOrchestrator {
370
executeCommand(command: ICommand): void;
371
}
372
```
373
374
### Chinese Commands
375
376
Localized commands for Chinese language support with Chinese labels and tooltips.
377
378
```typescript { .api }
379
/**
380
* Chinese localized commands with same API as standard commands
381
* Import from '@uiw/react-md-editor/commands-cn'
382
*/
383
declare const commands: {
384
bold: ICommand; // 粗体
385
italic: ICommand; // 斜体
386
strikethrough: ICommand; // 删除线
387
title: ICommand; // 标题
388
title1: ICommand; // 一级标题
389
title2: ICommand; // 二级标题
390
title3: ICommand; // 三级标题
391
title4: ICommand; // 四级标题
392
title5: ICommand; // 五级标题
393
title6: ICommand; // 六级标题
394
link: ICommand; // 链接
395
quote: ICommand; // 引用
396
code: ICommand; // 代码
397
codeBlock: ICommand; // 代码块
398
comment: ICommand; // 注释
399
image: ICommand; // 图片
400
table: ICommand; // 表格
401
hr: ICommand; // 分割线
402
unorderedListCommand: ICommand; // 无序列表
403
orderedListCommand: ICommand; // 有序列表
404
checkedListCommand: ICommand; // 任务列表
405
// ... all other commands with Chinese localization
406
};
407
```
408
409
**Usage Example:**
410
411
```typescript
412
import { commands } from "@uiw/react-md-editor/commands-cn";
413
414
function ChineseEditor() {
415
return (
416
<MDEditor
417
value={value}
418
onChange={setValue}
419
commands={[
420
commands.bold, // 显示为 "粗体"
421
commands.italic, // 显示为 "斜体"
422
commands.title1, // 显示为 "一级标题"
423
commands.link, // 显示为 "链接"
424
commands.image, // 显示为 "图片"
425
commands.table // 显示为 "表格"
426
]}
427
extraCommands={[
428
commands.codeEdit, // 显示为 "编辑模式"
429
commands.codeLive, // 显示为 "实时预览"
430
commands.codePreview, // 显示为 "预览模式"
431
commands.fullscreen // 显示为 "全屏"
432
]}
433
/>
434
);
435
}
436
```