0
# Configuration
1
2
Comprehensive configuration options for customizing editor behavior, appearance, and functionality.
3
4
## Overview
5
6
All configuration is done through the `customConfig` property before calling `create()`. The configuration object provides extensive customization options for menus, styling, event handling, and functionality.
7
8
```javascript
9
const editor = new wangEditor('#toolbar');
10
11
// Configure before creating
12
editor.customConfig.option = value;
13
editor.customConfig.onchange = function(html) { /* ... */ };
14
15
// Then create the editor
16
editor.create();
17
```
18
19
## Capabilities
20
21
### Menu Configuration
22
23
Control which menu items appear in the toolbar.
24
25
```javascript { .api }
26
interface MenuConfig {
27
/** Array of menu item names to display in toolbar */
28
menus?: string[];
29
}
30
31
// Default menu items
32
const defaultMenus = [
33
'head', // Heading styles
34
'bold', // Bold text
35
'fontSize', // Font size
36
'fontName', // Font family
37
'italic', // Italic text
38
'underline', // Underline text
39
'strikeThrough', // Strikethrough text
40
'foreColor', // Text color
41
'backColor', // Background color
42
'link', // Insert/edit links
43
'list', // Ordered/unordered lists
44
'justify', // Text alignment
45
'quote', // Blockquote
46
'emoticon', // Emoticons/emojis
47
'image', // Image insertion
48
'table', // Table insertion
49
'video', // Video embedding
50
'code', // Code blocks
51
'undo', // Undo action
52
'redo' // Redo action
53
];
54
```
55
56
**Usage Examples:**
57
58
```javascript
59
// Minimal toolbar
60
editor.customConfig.menus = ['bold', 'italic', 'underline'];
61
62
// Common formatting options
63
editor.customConfig.menus = [
64
'head', 'bold', 'italic', 'underline', 'foreColor', 'backColor'
65
];
66
67
// Full featured editor
68
editor.customConfig.menus = [
69
'head', 'bold', 'fontSize', 'fontName', 'italic', 'underline',
70
'strikeThrough', 'foreColor', 'backColor', 'link', 'list',
71
'justify', 'quote', 'emoticon', 'image', 'table', 'video',
72
'code', 'undo', 'redo'
73
];
74
```
75
76
### Font Configuration
77
78
Configure available fonts and font sizes.
79
80
```javascript { .api }
81
interface FontConfig {
82
/** Array of font family names available in font dropdown */
83
fontNames?: string[];
84
}
85
```
86
87
**Usage Examples:**
88
89
```javascript
90
// Default fonts
91
editor.customConfig.fontNames = [
92
'宋体',
93
'微软雅黑',
94
'Arial',
95
'Tahoma',
96
'Verdana'
97
];
98
99
// Custom font list
100
editor.customConfig.fontNames = [
101
'Arial',
102
'Helvetica',
103
'Times New Roman',
104
'Georgia',
105
'Courier New'
106
];
107
108
// Web fonts
109
editor.customConfig.fontNames = [
110
'system-ui',
111
'Roboto',
112
'Open Sans',
113
'Lato',
114
'Montserrat'
115
];
116
```
117
118
### Color Configuration
119
120
Define color palettes for text and background colors.
121
122
```javascript { .api }
123
interface ColorConfig {
124
/** Array of color values available in color pickers */
125
colors?: string[];
126
}
127
```
128
129
**Usage Examples:**
130
131
```javascript
132
// Custom color palette
133
editor.customConfig.colors = [
134
'#000000', '#333333', '#666666', '#999999', '#cccccc', '#ffffff',
135
'#ff0000', '#ff9900', '#ffff00', '#00ff00', '#00ffff', '#0000ff',
136
'#9900ff', '#ff0099'
137
];
138
139
// Brand colors
140
editor.customConfig.colors = [
141
'#1f2937', // Dark gray
142
'#3b82f6', // Blue
143
'#10b981', // Green
144
'#f59e0b', // Yellow
145
'#ef4444', // Red
146
'#8b5cf6', // Purple
147
'#f97316', // Orange
148
'#06b6d4' // Cyan
149
];
150
```
151
152
### Event Handlers
153
154
Configure callbacks for editor events.
155
156
```javascript { .api }
157
interface EventConfig {
158
/** Callback fired when content changes */
159
onchange?: (html: string) => void;
160
161
/** Callback fired when editor loses focus */
162
onblur?: (html: string) => void;
163
164
/** Callback fired when editor gains focus */
165
onfocus?: () => void;
166
167
/** Debounce timeout for onchange event in milliseconds */
168
onchangeTimeout?: number;
169
}
170
```
171
172
**Usage Examples:**
173
174
```javascript
175
// Content change handling
176
editor.customConfig.onchange = function(html) {
177
console.log('Content changed:', html);
178
// Auto-save, validation, etc.
179
};
180
181
// Focus/blur handling
182
editor.customConfig.onfocus = function() {
183
console.log('Editor focused');
184
document.getElementById('editor-status').textContent = 'Editing...';
185
};
186
187
editor.customConfig.onblur = function(html) {
188
console.log('Editor blurred');
189
document.getElementById('editor-status').textContent = 'Saved';
190
saveContent(html);
191
};
192
193
// Debounced change events
194
editor.customConfig.onchangeTimeout = 500; // 500ms delay
195
editor.customConfig.onchange = function(html) {
196
// This will only fire 500ms after user stops typing
197
performExpensiveOperation(html);
198
};
199
```
200
201
### UI Configuration
202
203
Control editor appearance and behavior.
204
205
```javascript { .api }
206
interface UIConfig {
207
/** Z-index for editor UI elements */
208
zIndex?: number;
209
210
/** Enable debug mode with error throwing */
211
debug?: boolean;
212
213
/** Language configuration for UI text */
214
lang?: {[key: string]: string};
215
216
/** Custom alert function for messages */
217
customAlert?: (info: string) => void;
218
}
219
```
220
221
**Usage Examples:**
222
223
```javascript
224
// Z-index configuration
225
editor.customConfig.zIndex = 15000; // Ensure editor appears above other elements
226
227
// Debug mode
228
editor.customConfig.debug = true; // Throw errors instead of silent failure
229
230
// Custom alert
231
editor.customConfig.customAlert = function(info) {
232
// Use custom modal instead of browser alert
233
showCustomModal(info);
234
};
235
236
// Language customization
237
editor.customConfig.lang = {
238
'设置标题': 'Set Title',
239
'正文': 'Normal',
240
'链接文字': 'Link Text',
241
'链接': 'URL'
242
};
243
```
244
245
### Paste Configuration
246
247
Control paste behavior and content filtering.
248
249
```javascript { .api }
250
interface PasteConfig {
251
/** Filter styles when pasting content */
252
pasteFilterStyle?: boolean;
253
254
/** Ignore images when pasting */
255
pasteIgnoreImg?: boolean;
256
257
/** Custom handler for processing pasted content */
258
pasteTextHandle?: (content: string) => string;
259
}
260
```
261
262
**Usage Examples:**
263
264
```javascript
265
// Basic paste filtering
266
editor.customConfig.pasteFilterStyle = true; // Remove inline styles
267
editor.customConfig.pasteIgnoreImg = false; // Allow pasted images
268
269
// Custom paste processing
270
editor.customConfig.pasteTextHandle = function(content) {
271
// Custom content processing
272
content = content.replace(/\n/g, '<br>'); // Convert line breaks
273
content = content.replace(/\t/g, ' '); // Convert tabs
274
return content;
275
};
276
277
// Advanced paste filtering
278
editor.customConfig.pasteTextHandle = function(content) {
279
// Remove unwanted HTML tags
280
const allowedTags = ['p', 'br', 'strong', 'em', 'u', 'h1', 'h2', 'h3'];
281
const doc = new DOMParser().parseFromString(content, 'text/html');
282
283
// Filter content based on allowed tags
284
const walker = document.createTreeWalker(
285
doc.body,
286
NodeFilter.SHOW_ELEMENT,
287
{
288
acceptNode: function(node) {
289
return allowedTags.includes(node.tagName.toLowerCase())
290
? NodeFilter.FILTER_ACCEPT
291
: NodeFilter.FILTER_REJECT;
292
}
293
}
294
);
295
296
// Process and return filtered content
297
return doc.body.innerHTML;
298
};
299
```
300
301
### Link Validation
302
303
Configure link insertion and validation.
304
305
```javascript { .api }
306
interface LinkConfig {
307
/** Validation function for inserted links */
308
linkCheck?: (text: string, link: string) => boolean | string;
309
310
/** Validation function for network images */
311
linkImgCheck?: (src: string) => boolean | string;
312
313
/** Show network image insertion tab */
314
showLinkImg?: boolean;
315
316
/** Callback when network image is inserted */
317
linkImgCallback?: (url: string) => void;
318
}
319
```
320
321
**Usage Examples:**
322
323
```javascript
324
// Link validation
325
editor.customConfig.linkCheck = function(text, link) {
326
// Return true for valid links, string for error message
327
if (!link.startsWith('http://') && !link.startsWith('https://')) {
328
return 'Links must start with http:// or https://';
329
}
330
if (link.includes('malicious-site.com')) {
331
return 'This domain is not allowed';
332
}
333
return true; // Valid link
334
};
335
336
// Image link validation
337
editor.customConfig.linkImgCheck = function(src) {
338
const allowedDomains = ['example.com', 'images.example.com'];
339
const url = new URL(src);
340
341
if (!allowedDomains.includes(url.hostname)) {
342
return 'Images must be from allowed domains';
343
}
344
return true;
345
};
346
347
// Network image configuration
348
editor.customConfig.showLinkImg = true;
349
editor.customConfig.linkImgCallback = function(url) {
350
console.log('Network image inserted:', url);
351
// Track image usage, validate, etc.
352
};
353
```
354
355
### Emoticon Configuration
356
357
Configure available emoticons and emojis.
358
359
```javascript { .api }
360
interface EmoticonConfig {
361
/** Emoticon configuration with tabs and content */
362
emotions?: Array<{
363
title: string;
364
type: 'image' | 'emoji';
365
content: Array<{
366
alt: string;
367
src?: string;
368
data?: string;
369
}>;
370
}>;
371
}
372
```
373
374
**Usage Examples:**
375
376
```javascript
377
// Custom emoticons
378
editor.customConfig.emotions = [
379
{
380
title: 'Smileys',
381
type: 'emoji',
382
content: [
383
{alt: '[smile]', data: '😊'},
384
{alt: '[laugh]', data: '😂'},
385
{alt: '[sad]', data: '😢'},
386
{alt: '[angry]', data: '😠'}
387
]
388
},
389
{
390
title: 'Custom',
391
type: 'image',
392
content: [
393
{alt: '[custom1]', src: '/images/emoji1.png'},
394
{alt: '[custom2]', src: '/images/emoji2.png'}
395
]
396
}
397
];
398
399
// Simple emoji set
400
editor.customConfig.emotions = [
401
{
402
title: 'Basic',
403
type: 'emoji',
404
content: [
405
{alt: '😊', data: '😊'},
406
{alt: '😂', data: '😂'},
407
{alt: '🤔', data: '🤔'},
408
{alt: '👍', data: '👍'},
409
{alt: '❤️', data: '❤️'}
410
]
411
}
412
];
413
```
414
415
## Complete Configuration Interface
416
417
```javascript { .api }
418
interface CustomConfig {
419
// Menu configuration
420
menus?: string[];
421
fontNames?: string[];
422
colors?: string[];
423
emotions?: Array<any>;
424
425
// UI configuration
426
zIndex?: number;
427
debug?: boolean;
428
lang?: {[key: string]: string};
429
customAlert?: (info: string) => void;
430
431
// Event handlers
432
onchange?: (html: string) => void;
433
onblur?: (html: string) => void;
434
onfocus?: () => void;
435
onchangeTimeout?: number;
436
437
// Paste configuration
438
pasteFilterStyle?: boolean;
439
pasteIgnoreImg?: boolean;
440
pasteTextHandle?: (content: string) => string;
441
442
// Link configuration
443
linkCheck?: (text: string, link: string) => boolean | string;
444
linkImgCheck?: (src: string) => boolean | string;
445
showLinkImg?: boolean;
446
linkImgCallback?: (url: string) => void;
447
448
// Upload configuration (see Image Upload documentation)
449
uploadImgServer?: string;
450
uploadImgMaxSize?: number;
451
uploadImgMaxLength?: number;
452
uploadImgShowBase64?: boolean;
453
uploadFileName?: string;
454
uploadImgParams?: {[key: string]: any};
455
uploadImgParamsWithUrl?: boolean;
456
uploadImgHeaders?: {[key: string]: string};
457
withCredentials?: boolean;
458
uploadImgTimeout?: number;
459
uploadImgHooks?: {[key: string]: Function};
460
qiniu?: boolean;
461
customUploadImg?: (files: FileList, insert: Function) => void;
462
}
463
```
464
465
## Configuration Patterns
466
467
### Environment-based Configuration
468
469
```javascript
470
// Different configs for different environments
471
function createEditorConfig(environment) {
472
const baseConfig = {
473
zIndex: 10000,
474
pasteFilterStyle: true,
475
onchangeTimeout: 200
476
};
477
478
const configs = {
479
development: {
480
...baseConfig,
481
debug: true,
482
customAlert: console.log
483
},
484
production: {
485
...baseConfig,
486
debug: false,
487
customAlert: function(info) {
488
// Log to monitoring service
489
logToService('editor-alert', info);
490
}
491
}
492
};
493
494
return configs[environment] || configs.production;
495
}
496
497
// Usage
498
const config = createEditorConfig(process.env.NODE_ENV);
499
Object.assign(editor.customConfig, config);
500
```
501
502
### Feature-based Configuration
503
504
```javascript
505
// Configuration presets for different use cases
506
const EditorPresets = {
507
minimal: {
508
menus: ['bold', 'italic'],
509
colors: ['#000000', '#ff0000', '#0000ff']
510
},
511
512
blog: {
513
menus: ['head', 'bold', 'italic', 'underline', 'foreColor', 'link', 'image'],
514
pasteFilterStyle: true,
515
linkCheck: function(text, link) {
516
return link.startsWith('http://') || link.startsWith('https://');
517
}
518
},
519
520
comment: {
521
menus: ['bold', 'italic', 'emoticon'],
522
emotions: [/* emoji set */],
523
uploadImgServer: '/api/upload'
524
},
525
526
full: {
527
menus: [
528
'head', 'bold', 'fontSize', 'fontName', 'italic', 'underline',
529
'strikeThrough', 'foreColor', 'backColor', 'link', 'list',
530
'justify', 'quote', 'emoticon', 'image', 'table', 'video',
531
'code', 'undo', 'redo'
532
]
533
}
534
};
535
536
// Apply preset
537
Object.assign(editor.customConfig, EditorPresets.blog);
538
```