u-desk/docs/03-模块文档/设置功能/settings-quick-reference.md

设置功能快速参考

API 端点

获取应用配置

// Go 方法
func (a *App) GetAppConfig() (map[string]interface{}, error)

// 前端调用
const result = await window.go.main.App.GetAppConfig()

响应格式：

{
  "success": true,
  "data": {
    "tabs": [
      {
        "key": "db-cli",
        "title": "数据库",
        "visible": true,
        "enabled": true
      }
    ],
    "visibleTabs": ["db-cli", "file-system", "device"],
    "defaultTab": "db-cli"
  }
}

保存应用配置

// Go 方法
func (a *App) SaveAppConfig(req SaveAppConfigRequest) (map[string]interface{}, error)

// 前端调用
const result = await window.go.main.App.SaveAppConfig({
  tabs: [
    { key: "db-cli", title: "数据库", visible: true, enabled: true }
  ],
  visibleTabs: ["db-cli", "file-system"],
  defaultTab: "db-cli"
})

响应格式：

{
  "success": true,
  "message": "配置保存成功"
}

数据库表结构

app_config 表

CREATE TABLE `app_config` (
  `id` INTEGER PRIMARY KEY AUTOINCREMENT,
  `key` VARCHAR(50) UNIQUE NOT NULL,
  `value` TEXT NOT NULL,
  `description` VARCHAR(200),
  `created_at` DATETIME,
  `updated_at` DATETIME
);

示例数据

// key = "tab_config"
{
  "available_tabs": [
    { "key": "db-cli", "title": "数据库", "enabled": true },
    { "key": "file-system", "title": "文件管理", "enabled": true },
    { "key": "device", "title": "设备调用测试", "enabled": true }
  ],
  "visible_tabs": ["db-cli", "file-system", "device"],
  "default_tab": "db-cli"
}

组件使用

SettingsPanel 组件

<template>
  <SettingsPanel
    v-model="showSettings"
    :config="appConfig"
    @save="handleSaveConfig"
  />
</template>

<script setup>
import SettingsPanel from './components/SettingsPanel.vue'

const showSettings = ref(false)
const appConfig = ref({
  tabs: [],
  visibleTabs: [],
  defaultTab: 'db-cli'
})

const handleSaveConfig = async (config) => {
  // config 包含:
  // - tabs: Tab 定义数组
  // - visibleTabs: 可见 Tab key 数组
  // - defaultTab: 默认 Tab key
  console.log('保存配置:', config)
}
</script>

拖拽实现

HTML5 Drag & Drop API

<template>
  <div
    draggable="true"
    @dragstart="handleDragStart"
    @dragover.prevent="handleDragOver"
    @drop="handleDrop"
    @dragend="handleDragEnd"
  >
    拖拽元素
  </div>
</template>

<script setup>
const handleDragStart = (index, event) => {
  event.dataTransfer.effectAllowed = 'move'
  event.target.classList.add('dragging')
}

const handleDragOver = (event) => {
  event.preventDefault()
  event.dataTransfer.dropEffect = 'move'
}

const handleDrop = (index, event) => {
  event.preventDefault()
  // 处理排序逻辑
}

const handleDragEnd = (event) => {
  event.target.classList.remove('dragging')
}
</script>

配置验证规则

前端验证

1. 至少保留一个可见 Tab: visibleTabs.length >= 1
2. 默认 Tab 必须可见: visibleTabs.includes(defaultTab)
3. 禁用 Tab 不可取消选中: !tab.enabled 时禁用复选框

后端验证

1. JSON 格式验证: 使用 json.Unmarshal 验证
2. 业务规则验证: 与前端相同
3. 数据库错误处理: 捕获并返回友好错误信息

样式参考

拖拽元素样式

.tab-sort-item {
  display: flex;
  align-items: center;
  padding: 12px;
  background: var(--color-fill-1);
  border: 1px solid var(--color-border);
  border-radius: 4px;
  cursor: move;
  transition: all 0.2s;
}

.tab-sort-item.dragging {
  opacity: 0.5;
  background: var(--color-fill-2);
  transform: scale(0.98);
}

.tab-sort-item:hover {
  background: var(--color-fill-2);
  border-color: var(--color-border-2);
}

常见问题

Q: 如何添加新的 Tab？

A: 在 defaultTabConfig 中添加新的 TabDefinition，并确保在前端 getComponent 方法中添加对应的组件映射。

Q: 如何禁用某个 Tab？

A: 将 TabDefinition.Enabled 设置为 false，前端会自动显示"不可用"标签并禁用复选框。

Q: 配置存储在哪里？

A: 配置存储在 SQLite 数据库中，位置：~/.u-desk/app.db（Windows: C:\Users\你的用户名\.u-desk\app.db），表名：app_config。

Q: 如何重置配置？

A: 删除数据库中的 tab_config 记录，系统会自动使用默认配置。

Q: 拖拽功能不工作？

A: 确保元素设置了 draggable="true" 属性，并且正确实现了所有拖拽事件处理函数。

调试技巧

查看当前配置

console.log('应用配置:', appConfig.value)
console.log('可见 Tabs:', visibleTabs.value)
console.log('当前激活 Tab:', activeTab.value)

查看数据库

# Windows
sqlite3 ~/.u-desk/app.db

# 查询配置
SELECT * FROM app_config WHERE key = 'tab_config';

重置配置

DELETE FROM app_config WHERE key = 'tab_config';

性能优化建议

1. 减少重新渲染: 使用 computed 属性缓存计算结果
2. 防抖保存: 对保存操作添加防抖，避免频繁保存
3. 懒加载组件: 使用 <KeepAlive> 缓存组件状态
4. 批量更新: 使用 watch 的 deep 选项时注意性能影响

扩展建议

1. 导出/导入配置

// 导出
const exportConfig = () => {
  const data = JSON.stringify(appConfig.value)
  const blob = new Blob([data], { type: 'application/json' })
  const url = URL.createObjectURL(blob)
  // 下载文件
}

// 导入
const importConfig = (file) => {
  const reader = new FileReader()
  reader.onload = (e) => {
    const config = JSON.parse(e.target.result)
    // 保存配置
  }
  reader.readAsText(file)
}

2. 键盘辅助

<a-button @click="moveUp(index)">
  <template #icon><icon-up /></template>
</a-button>
<a-button @click="moveDown(index)">
  <template #icon><icon-down /></template>
</a-button>

3. 配置预览

<a-modal v-model:visible="showPreview" title="配置预览">
  <div v-for="tab in visibleTabs" :key="tab.key">
    {{ tab.title }}
  </div>
</a-modal>