0
# Configuration and Utilities
1

2
Global configuration system, utility functions, event management, and plugin architecture for customizing table behavior and extending functionality.
3

4
## Capabilities
5

6
### VxeUI Core System
7

8
Core utility system providing configuration, internationalization, and extension capabilities.
9

10
```typescript { .api }
11
/**
12
 * Core VxeUI system for global configuration and utilities
13
 */
14
interface VxeUI {
15
  // Version information
16
  version: string;
17
  tableVersion: string;
18
  
19
  // Configuration methods
20
  setConfig(options: VxeGlobalConfig): void;
21
  getConfig(): VxeGlobalConfig;
22
  setTheme(theme: string): void;
23
  getTheme(): string;
24
  
25
  // Internationalization
26
  setLanguage(language: string): void;
27
  setI18n(language: string, i18nMap: object): void;
28
  getI18n(key: string, args?: any): string;
29
  hasLanguage(language: string): boolean;
30
  
31
  // Icon management
32
  setIcon(iconMap: object): void;
33
  getIcon(name: string): string;
34
  
35
  // Registry systems
36
  renderer: RendererRegistry;
37
  validators: ValidatorRegistry;
38
  menus: MenuRegistry;
39
  formats: FormatRegistry;
40
  commands: CommandRegistry;
41
  interceptor: InterceptorSystem;
42
  
43
  // Event systems
44
  globalEvents: GlobalEventSystem;
45
  globalResize: GlobalResizeSystem;
46
  clipboard: ClipboardUtilities;
47
  log: LogUtilities;
48
  
49
  // Plugin system
50
  hooks: HookSystem;
51
  use(plugin: VxeUIPlugin): void;
52
  
53
  // Component registration
54
  component(component: any): void;
55
  dynamicApp?: App;
56
  
57
  // Utility methods
58
  saveFile(options: VxeUploadDefines.SaveFileOptions): Promise<void>;
59
  readFile(options: VxeUploadDefines.ReadFileOptions): Promise<any>;
60
  print(options: VxePrintDefines.PrintOptions): Promise<void>;
61
  modal: ModalUtilities;
62
}
63
```
64

65
### Global Configuration
66

67
Comprehensive global configuration for all table and grid components.
68

69
```typescript { .api }
70
interface VxeGlobalConfig {
71
  /** Empty cell placeholder */
72
  emptyCell?: string;
73
  
74
  /** Table configuration */
75
  table?: VxeTableConfig;
76
  
77
  /** Grid configuration */
78
  grid?: VxeGridConfig;
79
  
80
  /** Toolbar configuration */
81
  toolbar?: VxeToolbarConfig;
82
  
83
  /** Gantt configuration (reserved) */
84
  gantt?: VxeGanttConfig;
85
  
86
  /** Custom configurations */
87
  [key: string]: any;
88
}
89

90
interface VxeTableConfig {
91
  // Basic settings
92
  fit?: boolean;
93
  showHeader?: boolean;
94
  animat?: boolean;
95
  delayHover?: number;
96
  autoResize?: boolean;
97
  
98
  // Performance settings
99
  resizeInterval?: number;
100
  
101
  // Display settings
102
  size?: VxeTablePropTypes.Size;
103
  zIndex?: number;
104
  stripe?: boolean;
105
  border?: boolean;
106
  round?: boolean;
107
  emptyText?: string;
108
  emptyRender?: VxeTablePropTypes.EmptyRender;
109
  
110
  // Configuration objects with defaults
111
  rowConfig?: VxeTablePropTypes.RowConfig;
112
  columnConfig?: VxeTablePropTypes.ColumnConfig;
113
  resizeConfig?: VxeTablePropTypes.ResizeConfig;
114
  resizableConfig?: VxeTablePropTypes.ResizableConfig;
115
  radioConfig?: VxeTablePropTypes.RadioConfig;
116
  checkboxConfig?: VxeTablePropTypes.CheckboxConfig;
117
  tooltipConfig?: VxeTablePropTypes.TooltipConfig;
118
  validConfig?: VxeTablePropTypes.ValidConfig;
119
  sortConfig?: VxeTablePropTypes.SortConfig;
120
  filterConfig?: VxeTablePropTypes.FilterConfig;
121
  customConfig?: VxeTablePropTypes.CustomConfig;
122
  editConfig?: VxeTablePropTypes.EditConfig;
123
  expandConfig?: VxeTablePropTypes.ExpandConfig;
124
  treeConfig?: VxeTablePropTypes.TreeConfig;
125
  menuConfig?: VxeTablePropTypes.MenuConfig;
126
  mouseConfig?: VxeTablePropTypes.MouseConfig;
127
  areaConfig?: VxeTablePropTypes.AreaConfig;
128
  keyboardConfig?: VxeTablePropTypes.KeyboardConfig;
129
  clipConfig?: VxeTablePropTypes.ClipConfig;
130
  fnrConfig?: VxeTablePropTypes.FnrConfig;
131
  importConfig?: VxeTablePropTypes.ImportConfig;
132
  exportConfig?: VxeTablePropTypes.ExportConfig;
133
  printConfig?: VxeTablePropTypes.PrintConfig;
134
  virtualXConfig?: VxeTablePropTypes.VirtualXConfig;
135
  virtualYConfig?: VxeTablePropTypes.VirtualYConfig;
136
  scrollbarConfig?: VxeTablePropTypes.ScrollbarConfig;
137
  
138
  // Drag configurations
139
  rowDragConfig?: VxeTablePropTypes.RowDragConfig;
140
  columnDragConfig?: VxeTablePropTypes.ColumnDragConfig;
141
  
142
  // Data structure configurations
143
  aggregateConfig?: VxeTablePropTypes.AggregateConfig;
144
}
145
```
146

147
### Renderer Registry
148

149
Custom renderer system for cells, editors, and other components.
150

151
```typescript { .api }
152
interface RendererRegistry {
153
  /** Register a new renderer */
154
  add(name: string, options: RendererOptions): void;
155
  
156
  /** Remove a renderer */
157
  delete(name: string): void;
158
  
159
  /** Get renderer by name */
160
  get(name: string): RendererOptions | null;
161
  
162
  /** Check if renderer exists */
163
  has(name: string): boolean;
164
  
165
  /** Get all registered renderers */
166
  map(): Map<string, RendererOptions>;
167
}
168

169
interface RendererOptions {
170
  /** Render function for display */
171
  renderDefault?: (renderOpts: any, params: any) => VNode | string;
172
  /** Render function for editing */
173
  renderEdit?: (renderOpts: any, params: any) => VNode | string;
174
  /** Render function for filter */
175
  renderFilter?: (renderOpts: any, params: any) => VNode | string;
176
  /** Render function for cell */
177
  renderCell?: (renderOpts: any, params: any) => VNode | string;
178
  /** Auto focus method */
179
  autofocus?: string;
180
  /** Get cell value method */
181
  cellValueMethod?: (renderOpts: any, params: any) => any;
182
  /** Set cell value method */
183
  cellChangeMethod?: (renderOpts: any, params: any) => void;
184
  /** Component properties */
185
  props?: object;
186
  /** Component events */
187
  events?: object;
188
}
189
```
190

191
### Validator Registry
192

193
Custom validator system for data validation.
194

195
```typescript { .api }
196
interface ValidatorRegistry {
197
  /** Register a new validator */
198
  add(name: string, validatorFn: ValidatorFunction): void;
199
  
200
  /** Remove a validator */
201
  delete(name: string): void;
202
  
203
  /** Get validator by name */
204
  get(name: string): ValidatorFunction | null;
205
  
206
  /** Check if validator exists */
207
  has(name: string): boolean;
208
  
209
  /** Get all registered validators */
210
  map(): Map<string, ValidatorFunction>;
211
}
212

213
type ValidatorFunction = (params: VxeTableDefines.ValidatorMethodParams) => boolean | string | Error;
214
```
215

216
### Menu Registry
217

218
Context menu system for custom menu items.
219

220
```typescript { .api }
221
interface MenuRegistry {
222
  /** Register a new menu */
223
  add(name: string, options: MenuOptions): void;
224
  
225
  /** Remove a menu */
226
  delete(name: string): void;
227
  
228
  /** Get menu by name */
229
  get(name: string): MenuOptions | null;
230
  
231
  /** Check if menu exists */
232
  has(name: string): boolean;
233
  
234
  /** Get all registered menus */
235
  map(): Map<string, MenuOptions>;
236
}
237

238
interface MenuOptions {
239
  /** Menu code */
240
  code?: string;
241
  /** Menu name */
242
  name?: string;
243
  /** Menu render function */
244
  renderItem?: (params: any) => VNode | string;
245
  /** Menu click handler */
246
  clickMethod?: (params: any) => void;
247
  /** Menu visibility check */
248
  visibleMethod?: (params: any) => boolean;
249
}
250
```
251

252
### Format Registry
253

254
Data formatter system for custom data formatting.
255

256
```typescript { .api }
257
interface FormatRegistry {
258
  /** Register a new formatter */
259
  add(name: string, formatFn: FormatFunction): void;
260
  
261
  /** Remove a formatter */
262
  delete(name: string): void;
263
  
264
  /** Get formatter by name */
265
  get(name: string): FormatFunction | null;
266
  
267
  /** Check if formatter exists */
268
  has(name: string): boolean;
269
  
270
  /** Get all registered formatters */
271
  map(): Map<string, FormatFunction>;
272
}
273

274
type FormatFunction = (value: any, ...args: any[]) => string;
275
```
276

277
### Command Registry
278

279
Command system for custom table operations.
280

281
```typescript { .api }
282
interface CommandRegistry {
283
  /** Register a new command */
284
  add(name: string, options: CommandOptions): void;
285
  
286
  /** Remove a command */
287
  delete(name: string): void;
288
  
289
  /** Get command by name */
290
  get(name: string): CommandOptions | null;
291
  
292
  /** Check if command exists */
293
  has(name: string): boolean;
294
  
295
  /** Get all registered commands */
296
  map(): Map<string, CommandOptions>;
297
}
298

299
interface CommandOptions {
300
  /** Command execute function */
301
  commandMethod?: (params: any) => any;
302
  /** Undo function */
303
  undoMethod?: (params: any) => any;
304
  /** Redo function */
305
  redoMethod?: (params: any) => any;
306
}
307
```
308

309
### Interceptor System
310

311
Request/response interceptor system for data operations.
312

313
```typescript { .api }
314
interface InterceptorSystem {
315
  /** Add interceptor */
316
  add(type: string, callback: InterceptorCallback): void;
317
  
318
  /** Remove interceptor */
319
  delete(type: string, callback?: InterceptorCallback): void;
320
  
321
  /** Get interceptors by type */
322
  get(type: string): InterceptorCallback[];
323
  
324
  /** Execute interceptors */
325
  handle(type: string, params: any, ...args: any[]): any;
326
}
327

328
type InterceptorCallback = (params: any, ...args: any[]) => any;
329

330
// Built-in interceptor types
331
type InterceptorTypes = 
332
  | 'event.clearFilter'
333
  | 'event.clearSort'
334
  | 'event.showMenu'
335
  | 'event.keydown'
336
  | string;
337
```
338

339
### Global Event System
340

341
Global event management for cross-component communication.
342

343
```typescript { .api }
344
interface GlobalEventSystem {
345
  /** Add event listener */
346
  on(type: string, callback: EventCallback): void;
347
  
348
  /** Remove event listener */
349
  off(type: string, callback?: EventCallback): void;
350
  
351
  /** Emit event */
352
  emit(type: string, ...args: any[]): void;
353
  
354
  /** Add one-time event listener */
355
  once(type: string, callback: EventCallback): void;
356
}
357

358
type EventCallback = (...args: any[]) => void;
359
```
360

361
### Utility Functions
362

363
Various utility functions for common operations.
364

365
```typescript { .api }
366
interface UtilityFunctions {
367
  /** Cell view composable */
368
  useCellView(props: any): CellViewComposable;
369
  
370
  /** Install function for Vue app */
371
  install(app: App, options?: VxeGlobalConfig): void;
372
  
373
  /** File operations */
374
  saveFile(options: VxeUploadDefines.SaveFileOptions): Promise<void>;
375
  readFile(options: VxeUploadDefines.ReadFileOptions): Promise<any>;
376
  
377
  /** Print functionality */
378
  print(options: VxePrintDefines.PrintOptions): Promise<void>;
379
  
380
  /** Modal utilities */
381
  modal: {
382
    get(id: string): any;
383
    close(id: string): Promise<void>;
384
    open(options: any): Promise<any>;
385
    alert(content: any, title?: any, options?: any): Promise<any>;
386
    confirm(content: any, title?: any, options?: any): Promise<any>;
387
    message(content: any, options?: any): Promise<any>;
388
    notification(content: any, title?: any, options?: any): Promise<any>;
389
  };
390
  
391
  /** Component registration and dynamic app handling */
392
  component(component: any): void;
393
  dynamicApp?: App;
394
  
395
  /** Version information */
396
  version: string;
397
  tableVersion: string;
398
}
399

400
interface CellViewComposable {
401
  // Cell view utilities
402
  [key: string]: any;
403
}
404
```
405

406
**Usage Examples:**
407

408
```typescript
409
// Global configuration
410
import VxeTable from "vxe-table";
411

412
VxeTable.setConfig({
413
  table: {
414
    stripe: true,
415
    border: true,
416
    fit: true,
417
    showHeader: true,
418
    autoResize: true,
419
    emptyText: 'No data available',
420
    virtualYConfig: {
421
      enabled: true,
422
      gt: 100
423
    },
424
    editConfig: {
425
      trigger: 'click',
426
      mode: 'cell',
427
      showIcon: true
428
    }
429
  },
430
  grid: {
431
    pagerConfig: {
432
      enabled: true,
433
      pageSize: 20
434
    },
435
    toolbarConfig: {
436
      enabled: true
437
    }
438
  }
439
});
440

441
// Theme configuration
442
VxeTable.setTheme('dark');
443

444
// Internationalization
445
VxeTable.setI18n('en-US', {
446
  'vxe.table.emptyText': 'No data',
447
  'vxe.table.confirmDelete': 'Are you sure you want to delete?'
448
});
449
VxeTable.setLanguage('en-US');
450

451
// Custom renderer registration
452
VxeTable.renderer.add('MyCustomInput', {
453
  renderEdit(renderOpts, params) {
454
    const { row, column } = params;
455
    return h('input', {
456
      value: row[column.field],
457
      onInput: (event) => {
458
        row[column.field] = event.target.value;
459
      }
460
    });
461
  }
462
});
463

464
// Custom validator registration
465
VxeTable.validators.add('phone', (params) => {
466
  const { cellValue } = params;
467
  const phoneRegex = /^\d{3}-\d{3}-\d{4}$/;
468
  if (cellValue && !phoneRegex.test(cellValue)) {
469
    return 'Please enter a valid phone number (xxx-xxx-xxxx)';
470
  }
471
  return true;
472
});
473

474
// Custom formatter registration
475
VxeTable.formats.add('currency', (value, decimals = 2) => {
476
  if (value == null) return '';
477
  return `$${Number(value).toFixed(decimals)}`;
478
});
479

480
// Global event handling
481
VxeTable.globalEvents.on('table-created', (tableInstance) => {
482
  console.log('New table created:', tableInstance);
483
});
484

485
// Interceptor registration
486
VxeTable.interceptor.add('event.keydown', (params, event) => {
487
  // Custom keydown handling
488
  if (event.ctrlKey && event.key === 's') {
489
    event.preventDefault();
490
    // Custom save logic
491
    return false; // Prevent default
492
  }
493
});
494

495
// Plugin usage
496
const myPlugin = {
497
  install(VxeUI) {
498
    // Add custom functionality
499
    VxeUI.renderer.add('my-renderer', {
500
      // renderer implementation
501
    });
502
  }
503
};
504

505
VxeTable.use(myPlugin);
506

507
// Component registration with Vue app
508
const app = createApp(App);
509
app.use(VxeTable, {
510
  table: {
511
    border: true,
512
    stripe: true
513
  }
514
});
515
```
516

517
## Types
518

519
```typescript { .api }
520
// Plugin interface
521
interface VxeUIPlugin {
522
  install(VxeUI: VxeUI): void;
523
}
524

525
// Configuration type
526
interface VxeGlobalConfig {
527
  table?: VxeTableConfig;
528
  grid?: VxeGridConfig;
529
  toolbar?: VxeToolbarConfig;
530
  [key: string]: any;
531
}
532

533
// Core export interface
534
interface VxeUIExport extends VxeUI {
535
  install(app: App, options?: VxeGlobalConfig): void;
536
}
537

538
// File operation types
539
interface VxeUploadDefines.SaveFileOptions {
540
  filename?: string;
541
  type?: string;
542
  content?: string | ArrayBuffer;
543
}
544

545
interface VxeUploadDefines.ReadFileOptions {
546
  multiple?: boolean;
547
  types?: string[];
548
}
549

550
// Print options
551
interface VxePrintDefines.PrintOptions {
552
  sheetName?: string;
553
  mode?: string;
554
  content?: string;
555
  [key: string]: any;
556
}
557

558
// Deprecated functions (for backward compatibility)
559
interface DeprecatedFunctions {
560
  /** @deprecated Use setConfig instead */
561
  setup(options?: VxeGlobalConfig): void;
562
  
563
  /** @deprecated Use setConfig instead */
564
  config(options?: VxeGlobalConfig): void;
565
  
566
  /** @deprecated Use getI18n instead */
567
  t(key: string, args?: any): string;
568
  
569
  /** @deprecated Internal function */
570
  _t(content: string | number | boolean | null | undefined, args?: any): string;
571
  
572
  /** @deprecated Use VxeUI instead */
573
  VXETable: VxeUIExport;
574
}
575
```
576

577
## Migration Guide for Deprecated APIs
578

579
This section provides clear migration paths for deprecated APIs to help users upgrade to the latest version.
580

581
### Global API Migration
582

583
```typescript
584
// ❌ Deprecated - Old way
585
import VxeTable from "vxe-table";
586
VxeTable.setup({ table: { border: true } });
587
VxeTable.config({ table: { stripe: true } });
588
const text = VxeTable.t('vxe.table.emptyText');
589

590
// ✅ Current - New way
591
import VxeTable from "vxe-table";
592
VxeTable.setConfig({ table: { border: true, stripe: true } });
593
const text = VxeTable.getI18n('vxe.table.emptyText');
594
```
595

596
### Component Props Migration
597

598
```typescript
599
// ❌ Deprecated props
600
<VxeTable
601
  :data="tableData"
602
  row-key="id"
603
  column-key="field"
604
  :highlight-current-column="true"
605
  :highlight-hover-column="true"
606
  resizable
607
  :scroll-x="{ enabled: true }"
608
  :scroll-y="{ enabled: true }"
609
>
610
</VxeTable>
611

612
// ✅ Current props
613
<VxeTable
614
  :data="tableData"
615
  :row-config="{ useKey: true, keyField: 'id' }"
616
  :column-config="{ useKey: true }"
617
  :virtual-x-config="{ enabled: true }"
618
  :virtual-y-config="{ enabled: true }"
619
  :column-config="{ resizable: true }"
620
>
621
</VxeTable>
622
```
623

624
### Event Migration
625

626
```typescript
627
// ❌ Deprecated events
628
<VxeTable
629
  @current-change="handleCurrentChange"
630
  @resizable-change="handleResizableChange"
631
  @edit-actived="handleEditActived"
632
  @change-fnr="handleChangeFnr"
633
>
634
</VxeTable>
635

636
// ✅ Current events
637
<VxeTable
638
  @current-row-change="handleCurrentRowChange"
639
  @column-resizable-change="handleColumnResizableChange"
640
  @edit-activated="handleEditActivated"
641
  @fnr-change="handleFnrChange"
642
>
643
</VxeTable>
644
```
645

646
### Renderer Migration
647

648
```typescript
649
// ❌ Deprecated renderers
650
<VxeColumn
651
  field="status"
652
  title="Status"
653
  :cell-render="{ name: '$select', options: statusOptions }"
654
>
655
</VxeColumn>
656

657
<VxeColumn
658
  field="name"
659
  title="Name"
660
  :edit-render="{ name: '$input' }"
661
>
662
</VxeColumn>
663

664
// ✅ Current renderers
665
<VxeColumn
666
  field="status"
667
  title="Status"
668
  :cell-render="{ name: 'VxeSelect', options: statusOptions }"
669
>
670
</VxeColumn>
671

672
<VxeColumn
673
  field="name"
674
  title="Name"
675
  :edit-render="{ name: 'VxeInput' }"
676
>
677
</VxeColumn>
678
```
679

680
### Configuration Object Migration
681

682
```typescript
683
// ❌ Deprecated configuration
684
<VxeTable
685
  :data="tableData"
686
  :drag-config="{ enabled: true }"
687
  :row-group-config="{ enabled: true }"
688
  padding
689
  animat
690
  delay-hover="300"
691
>
692
</VxeTable>
693

694
// ✅ Current configuration
695
<VxeTable
696
  :data="tableData"
697
  :row-drag-config="{ enabled: true }"
698
  :aggregate-config="{ enabled: true }"
699
  :cell-config="{ padding: true }"
700
>
701
</VxeTable>
702
```
703

704
### File Operations Migration
705

706
```typescript
707
// ❌ Deprecated file operations
708
import { saveFile, readFile, print } from "vxe-table";
709
await saveFile({ filename: 'data.csv', content: csvData });
710
const files = await readFile({ types: ['csv'] });
711
await print({ content: htmlContent });
712

713
// ✅ Current file operations
714
import VxeTable from "vxe-table";
715
await VxeTable.saveFile({ filename: 'data.csv', content: csvData });
716
const files = await VxeTable.readFile({ types: ['csv'] });
717
await VxeTable.print({ content: htmlContent });
718
```
719

720
### Modal API Migration
721

722
```typescript
723
// ❌ Deprecated modal API
724
import { modal } from "vxe-table";
725
await modal.alert('Message');
726
await modal.confirm('Are you sure?');
727
await modal.message('Success!');
728

729
// ✅ Current modal API
730
import VxeTable from "vxe-table";
731
await VxeTable.modal.alert('Message');
732
await VxeTable.modal.confirm('Are you sure?');
733
await VxeTable.modal.message('Success!');
734
```
735

736
### Global Object Migration
737

738
```typescript
739
// ❌ Deprecated global access
740
window.VXETable.setConfig({ /* config */ });
741
const VXETable = window.VXETable;
742

743
// ✅ Current global access
744
window.VxeUITable.setConfig({ /* config */ });
745
const VxeTable = window.VxeUITable;
746
```
747

748
## Breaking Changes Summary
749

750
### Version 4.x Changes
751

752
1. **Global API**: `setup()` and `config()` replaced with `setConfig()`
753
2. **Props**: Many shorthand props moved to configuration objects
754
3. **Events**: Event names standardized with consistent naming
755
4. **Renderers**: Deprecated `$` prefix renderers replaced with `Vxe` prefix
756
5. **Virtual Scrolling**: `scrollX`/`scrollY` replaced with `virtualXConfig`/`virtualYConfig`
757
6. **Configuration**: Related settings grouped into config objects
758
7. **File Operations**: Moved from named exports to `VxeUI` methods
759
8. **Modal API**: Moved from named exports to `VxeUI.modal` methods
760

761
### Compatibility Notes
762

763
- Most deprecated APIs still work but will show console warnings
764
- Deprecated APIs will be removed in future major versions
765
- New features are only available through current APIs
766
- Performance optimizations require using current configuration patterns