graphif 创建新的设置项功能
本技能指导如何在 Project Graph 项目中创建新的设置项。
创建设置项的步骤
创建新设置项需要完成以下 5 个步骤：
1. 在 Settings.tsx 中添加 Schema 定义
在 app/src/core/service/Settings.tsx 文件的 settingsSchema 对象中添加新的设置项定义。
支持的 Zod 类型：
z.boolean().default(false)- 布尔值开关z.number().min(x).max(y).default(z)- 数字（可添加.int()限制为整数）z.string().default("")- 字符串z.union([z.literal("option1"), z.literal("option2")]).default("option1")- 枚举选择z.tuple([z.number(), z.number(), z.number(), z.number()]).default([0,0,0,0])- 元组（如颜色 RGBA）
示例：
// 布尔值设置
enableNewFeature: z.boolean().default(false),
// 数字范围设置（带滑块）
newSliderValue: z.number().min(0).max(100).int().default(50),
// 枚举选择设置
newMode: z.union([z.literal("mode1"), z.literal("mode2")]).default("mode1"),
2. 在 SettingsIcons.tsx 中添加图标
在 app/src/core/service/SettingsIcons.tsx 文件的 settingsIcons 对象中添加对应的图标。
步骤：
- 从
lucide-react导入合适的图标组件 - 在
settingsIcons对象中添加映射：settingKey: IconComponent
示例：
import { NewIcon } from "lucide-react";
export const settingsIcons = {
// ... 其他设置项
enableNewFeature: NewIcon,
};
3. 添加翻译文本
在所有语言文件中添加翻译：
app/src/locales/zh_CN.yml- 简体中文app/src/locales/zh_TW.yml- 繁体中文app/src/locales/en.yml- 英文app/src/locales/zh_TWC.yml- 接地气繁体中文app/src/locales/id.yml- 印度尼西亚语
翻译结构：
settings:
settingKey:
title: "设置项标题"
description: |
设置项的详细描述
可以多行
options: # 仅枚举类型需要
option1: "选项1显示文本"
option2: "选项2显示文本"
示例：
settings:
enableNewFeature:
title: "启用新功能"
description: |
开启后将启用新功能特性。
此功能可能会影响性能。
newMode:
title: "新模式"
description: "选择新的模式选项"
options:
mode1: "模式一"
mode2: "模式二"
4. 将设置项添加到分组中
在 app/src/sub/SettingsWindow/settings.tsx 文件的 categories 对象中，将新设置项的键名添加到相应的分组数组中。
分组结构：
const categories = {
visual: { // 一级分类：视觉
basic: [...], // 二级分组：基础
background: [...], // 二级分组：背景
node: [...], // 二级分组：节点样式
// ...
},
automation: { // 一级分类：自动化
autoNamer: [...],
autoSave: [...],
// ...
},
control: { // 一级分类：控制
mouse: [...],
cameraMove: [...],
// ...
},
performance: { // 一级分类：性能
memory: [...],
cpu: [...],
// ...
},
ai: { // 一级分类：AI
api: [...],
},
};
添加设置项到分组：
const categories = {
visual: {
basic: [
"language",
"isClassroomMode",
"enableNewFeature", // 添加新设置项
// ...
],
},
// ...
};
分组选择指南：
- visual（视觉）：界面显示、主题、背景、节点样式、连线样式等
basic: 基础视觉设置background: 背景相关设置node: 节点样式设置edge: 连线样式设置section: 分组框的样式设置entityDetails: 实体详情面板设置debug: 调试相关设置miniWindow: 迷你窗口设置experimental: 实验性视觉功能
- automation（自动化）：自动保存、自动备份、自动命名等
autoNamer: 自动命名相关autoSave: 自动保存相关autoBackup: 自动备份相关autoImport: 自动导入相关
- control（控制）：鼠标、键盘、触摸板、相机控制等
mouse: 鼠标相关设置touchpad: 触摸板设置cameraMove: 相机移动设置cameraZoom: 相机缩放设置objectSelect: 对象选择设置textNode: 文本节点编辑设置edge: 连线操作设置generateNode: 节点生成设置gamepad: 游戏手柄设置
- performance（性能）：内存、CPU、渲染性能相关
memory: 内存相关设置cpu: CPU 相关设置render: 渲染相关设置experimental: 实验性性能功能
- ai（AI）：AI 相关设置
api: AI API 配置
注意： 如果设置项不属于任何现有分组，可以：
- 添加到最接近的现有分组
- 在相应分类下创建新的分组（需要同时更新翻译文件中的分类结构）
5. 在设置页面中使用 SettingField 组件
设置项添加到分组后，会在设置页面的相应分组中自动显示。如果需要手动渲染或添加额外内容，可以使用 SettingField 组件：
基本用法：
import { SettingField } from "@/components/ui/field";
<SettingField settingKey="enableNewFeature" />;
带额外内容的用法：
<SettingField settingKey="enableNewFeature" extra={<Button>额外按钮</Button>} />
注意： 大多数情况下，只需要将设置项添加到 categories 中即可，设置页面会自动渲染。只有在需要特殊布局或额外功能时才需要手动使用 SettingField 组件。
SettingField 组件的自动类型推断
SettingField 组件会根据 schema 定义自动渲染对应的 UI 控件：
- 字符串类型 →
Input输入框 - 数字类型（有 min/max） →
Slider滑块 +Input数字输入框 - 数字类型（无范围） →
Input数字输入框 - 布尔类型 →
Switch开关 - 枚举类型（Union） →
Select下拉选择框
访问设置值
在代码中访问设置值：
import { Settings } from "@/core/service/Settings";
// 读取设置值
const value = Settings.enableNewFeature;
// 修改设置值
Settings.enableNewFeature = true;
// 监听设置变化（返回取消监听的函数）
const unsubscribe = Settings.watch("enableNewFeature", (newValue) => {
console.log("设置已更改:", newValue);
});
// React Hook 方式（在组件中使用）
const [value, setValue] = Settings.use("enableNewFeature");
注意事项
- 设置项键名命名规范： 使用驼峰命名法（camelCase），如
enableNewFeature - 默认值： 所有设置项都必须提供默认值（
.default()） - 类型安全： TypeScript 会自动推断类型，确保类型一致性
- 持久化： 设置值会自动保存到
settings.json文件中 - 翻译键名： 翻译文件中的键名必须与设置项的键名完全一致
- 图标可选： 如果不需要图标，可以不在
settingsIcons中添加，组件会使用 Fragment - 分组必须： 所有设置项都必须添加到
categories对象中的相应分组，否则不会在设置页面中显示 - 分组选择： 根据设置项的功能特性选择合适的分类和分组，保持设置页面的逻辑清晰
完整示例
假设要添加一个"启用暗色模式"的设置项：
1. Settings.tsx:
export const settingsSchema = z.object({
// ... 其他设置项
enableDarkMode: z.boolean().default(false),
});
2. SettingsIcons.tsx:
import { Moon } from "lucide-react";
export const settingsIcons = {
// ... 其他设置项
enableDarkMode: Moon,
};
3. zh_CN.yml:
settings:
enableDarkMode:
title: "启用暗色模式"
description: "开启后将使用暗色主题界面"
4. settings.tsx - 添加到分组：
const categories = {
visual: {
basic: [
"language",
"isClassroomMode",
"enableDarkMode", // 添加到基础视觉设置分组
// ...
],
// ...
},
// ...
};
5. 设置项会自动显示：
设置项添加到 categories 后，会在设置页面的"视觉 > 基础"分组中自动显示，无需手动使用 SettingField 组件。
快捷设置栏支持
如果希望设置项出现在快捷设置栏（Quick Settings Toolbar）中，需要：
- 确保设置项已正确创建（完成上述 4 步）
- 快捷设置栏会自动显示所有布尔类型的设置项
- 可以通过
QuickSettingsManager.addQuickSetting()手动添加非布尔类型的设置项