扩展与定制

TechUI 允许开发者对控制面板进行深度定制，包括排除不需要的默认选项，或注入业务特定的配置开关。

所有的定制操作均通过修改全局状态 $tState.controlPanel 来实现。

排除默认项

如果您不希望用户看到某些系统设置（例如不希望用户关闭声音），可以将对应的 label 添加到 exclusion 数组中。

import { inject, onMounted } from 'vue';

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

onMounted(() => {
  // 隐藏 "声音" 和 "导航触发" 设置
  $tState.controlPanel.exclusion = ['sound', 'menuTrigger'];
});

可排除的 Label 列表： theme, t3D, maskBlur, transition, sound, adaptive, floaterTo, resizeBy, background, menuTrigger。

注入自定义项

您可以向面板中添加自定义的开关或选项，用于控制业务逻辑。

数据结构

向 extension 数组中推送符合规范的对象。对象必须包含以下字段：

字段	类型	说明
label	String	唯一标识符，对应 $globalConfig 中的 Key。
type	String	控件类型：'switch' (开关) 或 'radio' (单选)。
value	Any	默认值。
title	String	显示在面板上的标题文本。
tipContent	String	(可选) 鼠标悬停在 info 图标上显示的提示内容。
children	Array	(仅 Radio 类型) 选项列表，结构为 { label, value }。

完整开发案例

以下案例展示了如何同时添加一个开关 (Switch) 和一个单选组 (Radio)。

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

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

// 定义扩展配置数组
const myExtensions = [
  // 案例 1: 追加一个全局开关
  {
    label: "extendItem",
    type: "switch",
    title: "追加的 Toggle",
    value: true,
    tipContent: "通过 Extension 给控制面板追加全局的 Toggle"
  },
  
  // 案例 2: 追加一个全局单选组
  {
    label: "extendArray",
    type: "radio",
    title: "追加的 Radio",
    value: "item3",
    tipContent: "通过 Extension 给控制面板追加全局 Radio",
    children: [
      { label: "选项一", value: "item1" },
      { label: "选项二", value: "item2" },
      { label: "选项三", value: "item3" },
    ]
  },
];

onMounted(() => {
  // 1. 注入扩展项
  $tState.controlPanel.extension = myExtensions;
  
  // 2. (可选) 同时配置其他面板属性
  // $tState.controlPanel.exclusion = ["t3D"]; // 排除 3D 面板选项
  // $tState.controlPanel.width = 300;        // 修改面板宽度
});

// 3. 监听配置变化 (业务逻辑)
watch(() => $globalConfig.value.extendItem, (val) => {
  console.log("追加的 Toggle 状态变更为:", val);
});

watch(() => $globalConfig.value.extendArray, (val) => {
  console.log("追加的 Radio 选值为:", val);
});

工作原理

当您将上述配置注入 extension 后：

1. 自动渲染：控制面板会自动根据 type 渲染对应的 UI 组件。
2. 状态绑定：系统会自动在 $globalConfig 中注册 extendItem 和 extendArray 这两个字段。
3. 即时响应：用户在面板操作时，$globalConfig 对应的值会实时更新，您只需在业务代码中 watch 这些值即可实现功能逻辑。

面板外观配置

您还可以直接控制面板容器的属性。

// 设置面板宽度为 400px
$tState.controlPanel.width = 400;

// 关闭模态背景 (点击遮罩不关闭，且背景不变暗)
$tState.controlPanel.modal = false;

控制面板切换组件

用于呼出控制面板的触发器组件。

属性名	类型	默认值	说明
modelValue	Boolean	false	(v-model) 控制触发器的激活状态，通常无需手动绑定。
appearance	String	'iconPlain'	外观风格。可选值：'iconPlain' (纯图标), 'iconButton' (按钮), 'toggleRound' (圆形开关), 'toggleRect' (方形开关)。
size	String	'default'	尺寸。可选值：'small', 'default', 'large'。
icon	String/Array	'tui-icon ti-cog'	图标类名。
direction	String	'h'	排列方向。可选值：'h' (水平), 'v' (垂直)。
showLabel	Boolean	false	是否显示文本标签。
label	String	null	文本标签的内容。

控制面板组件

通过修改$tState.controlPanel的参数进行自定义。

控制面板的核心状态对象。

属性名	类型	说明
visible	Boolean	控制面板的显示与隐藏。
width	Number	面板抽屉的宽度 (px)。
modal	Boolean	是否启用抽屉的模态背景遮罩。
exclusion	Array	字符串数组，用于存储需要隐藏的默认配置项 Label。
extension	Array	对象数组，用于存储自定义扩展配置项。