Extension & Customization

TechUI allows developers to perform deep customization of the control panel, including excluding unwanted default options or injecting business-specific configuration switches.

All customization operations are implemented by modifying the global state $tState.controlPanel.

Excluding Default Items

If you do not want users to see certain system settings (e.g., you don't want users to turn off sound), you can add the corresponding label to the exclusion array.

import { inject, onMounted } from 'vue';

const { $tState } = inject('$global');

onMounted(() => {
  // Hide "Sound" and "Menu Trigger" settings
  $tState.controlPanel.exclusion = ['sound', 'menuTrigger'];
});

List of Excludable Labels:theme, t3D, maskBlur, transition, sound, adaptive, floaterTo, resizeBy, background, menuTrigger.

Injecting Custom Items

You can add custom switches or options to the panel to control business logic.

Data Structure

Push objects that meet the specifications into the extension array. The object must contain the following fields:

Field	Type	Description
label	String	Unique identifier, corresponds to the Key in $globalConfig.
type	String	Control type: 'switch' (Switch) or 'radio' (Radio Group).
value	Any	Default value.
title	String	Title text displayed on the panel.
tipContent	String	(Optional) Tooltip content displayed when hovering over the info icon.
children	Array	(Radio type only) List of options, structure is { label, value }.

Full Development Example

The following example demonstrates how to add a Switch and a Radio Group simultaneously.

import { inject, onMounted, watch } from 'vue';

const { $tState, $globalConfig } = inject('$global');

// Define extension configuration array
const myExtensions = [
  // Case 1: Append a global switch
  {
    label: "extendItem",
    type: "switch",
    title: "Appended Toggle",
    value: true,
    tipContent: "Append a global Toggle to the control panel via Extension"
  },
  
  // Case 2: Append a global radio group
  {
    label: "extendArray",
    type: "radio",
    title: "Appended Radio",
    value: "item3",
    tipContent: "Append a global Radio to the control panel via Extension",
    children: [
      { label: "Option 1", value: "item1" },
      { label: "Option 2", value: "item2" },
      { label: "Option 3", value: "item3" },
    ]
  },
];

onMounted(() => {
  // 1. Inject extension items
  $tState.controlPanel.extension = myExtensions;
  
  // 2. (Optional) Configure other panel properties simultaneously
  // $tState.controlPanel.exclusion = ["t3D"]; // Exclude 3D panel options
  // $tState.controlPanel.width = 300;        // Modify panel width
});

// 3. Watch for configuration changes (Business Logic)
watch(() => $globalConfig.value.extendItem, (val) => {
  console.log("Appended Toggle state changed to:", val);
});

watch(() => $globalConfig.value.extendArray, (val) => {
  console.log("Appended Radio value is:", val);
});

Working Principle

After you inject the above configuration into extension:

1. Auto Rendering: The control panel automatically renders the corresponding UI component based on type.
2. State Binding: The system automatically registers the extendItem and extendArray fields in $globalConfig.
3. Instant Response: When users operate the panel, the corresponding values in $globalConfig update in real-time. You only need to watch these values in your business code to implement functionality.

Appearance Configuration

You can also directly control the properties of the panel container.

// Set panel width to 400px
$tState.controlPanel.width = 400;

// Disable modal background (clicking mask does not close, and background does not darken)
$tState.controlPanel.modal = false;

Toggle Component

The trigger component used to call out the control panel.

Property Name	Type	Default	Description
modelValue	Boolean	false	(v-model) Controls the active state of the trigger, usually no manual binding needed.
appearance	String	'iconPlain'	Appearance style. Options: 'iconPlain' (Plain Icon), 'iconButton' (Button), 'toggleRound' (Round Switch), 'toggleRect' (Square Switch).
size	String	'default'	Size. Options: 'small', 'default', 'large'.
icon	String/Array	'tui-icon ti-cog'	Icon class name.
direction	String	'h'	Alignment direction. Options: 'h' (Horizontal), 'v' (Vertical).
showLabel	Boolean	false	Whether to show text label.
label	String	null	Content of the text label.

Control Panel Component

Customize by modifying the parameters of $tState.controlPanel.

The core state object of the control panel.

Property Name	Type	Description
visible	Boolean	Controls the display and hiding of the control panel.
width	Number	The width of the panel drawer (px).
modal	Boolean	Whether to enable the modal background mask for the drawer.
exclusion	Array	String array used to store the Labels of default configuration items to be hidden.
extension	Array	Object array used to store custom extension configuration items.