系统配置

XinAdmin 提供了灵活的系统配置管理功能，支持分组管理、自定义表单组件和自动保存。

数据结构

配置分组（sys_setting_group）

字段	类型	说明
id	int	分组ID
title	string	分组标题
key	string	分组标识（唯一）
remark	string	备注说明

配置项（sys_setting_items）

字段	类型	说明
id	int	配置项ID
group_id	int	所属分组ID
key	string	配置键名
title	string	配置标题
describe	string	配置描述/占位符提示
values	string	配置值
type	string	组件类型：Input/TextArea/InputNumber/Switch/Radio/Checkbox/Select/DatePicker
options	text	选项配置（格式：`value=label` 每行一个）
props	text	组件额外属性（格式：`key=value` 每行一个）
sort	int	排序

支持的组件类型

类型	说明	适用场景
Input	单行文本输入框	简短文本配置
TextArea	多行文本输入框	长文本配置
InputNumber	数字输入框	数值配置
Switch	开关组件	布尔值配置
Radio	单选按钮组	单选配置
Checkbox	复选框组	多选配置
Select	下拉选择框	下拉选项配置
DatePicker	日期选择器	日期配置

options 配置格式

对于 Radio、Checkbox、Select 类型，需要配置 options 选项：

value1=选项1
value2=选项2
value3=选项3

会被解析为：

[
  { "label": "选项1", "value": "value1" },
  { "label": "选项2", "value": "value2" },
  { "label": "选项3", "value": "value3" }
]

props 配置格式

可以为组件添加额外的 Ant Design 属性：

placeholder=请输入内容
maxlength=100
disabled=false

会被解析为：

{
  "placeholder": "请输入内容",
  "maxlength": 100,
  "disabled": false
}

前端使用

读取配置

use Illuminate\Support\Facades\Cache;

// 获取单个配置
$siteName = setting('site.name');

// 获取带默认值的配置
$siteName = setting('site.name', '默认站点');

// 获取整个分组
$siteSettings = setting('site');

// 获取所有配置
$allSettings = setting();

在代码中使用

// 站点名称
$name = setting('site.name', 'XinAdmin');

// 是否启用某功能
$enabled = setting('feature.enabled', false);

// 获取下拉选项配置
$options = setting('dropdown.options');

API 接口

配置分组

接口	方法	路径	说明
列表	GET	/api/admin/system/setting/group	获取分组列表
创建	POST	/api/admin/system/setting/group	创建分组
更新	PUT	/api/admin/system/setting/group/{id}	更新分组
删除	DELETE	/api/admin/system/setting/group/{id}	删除分组

配置项

接口	方法	路径	说明
列表	GET	/api/admin/system/setting/item	获取配置项列表
详情	GET	/api/admin/system/setting/item/{id}	获取配置项详情
创建	POST	/api/admin/system/setting/item	创建配置项
更新	PUT	/api/admin/system/setting/item/{id}	更新配置项
删除	DELETE	/api/admin/system/setting/item/{id}	删除配置项
保存值	POST	/api/admin/system/setting/item/{id}/value	保存配置值

获取分组下的配置项

GET /api/admin/system/setting/item?group_id=1

保存配置值

POST /api/admin/system/setting/item/{id}/value

请求参数：

参数	类型	说明
values	string	配置值

自动保存机制：

前端在用户修改配置后会触发自动保存，设置 500ms 防抖延迟，避免频繁请求。

使用示例

创建一个网站配置分组

1. 创建分组

{
  "title": "网站设置",
  "key": "site",
  "remark": "网站基本信息配置"
}

2. 添加配置项

添加站点名称配置：

{
  "key": "name",
  "title": "站点名称",
  "describe": "显示在浏览器标签页的站点名称",
  "type": "Input",
  "group_id": 1,
  "sort": 1
}

添加是否启用维护模式配置：

{
  "key": "maintenance",
  "title": "启用维护模式",
  "describe": "开启后普通用户将无法访问",
  "type": "Switch",
  "group_id": 1,
  "sort": 2
}

添加日期格式配置：

{
  "key": "date_format",
  "title": "日期格式",
  "describe": "选择日期显示格式",
  "type": "Select",
  "options": "Y-m-d=年-月-日\nY/m/d=年/月/日\nm-d-y=月-日-年",
  "group_id": 1,
  "sort": 3
}

3. 代码中使用

// 获取站点名称
$siteName = setting('site.name', '默认站点');

// 判断是否启用维护模式
if (setting('site.maintenance', false)) {
    abort(503, '网站维护中...');
}

// 获取日期格式
$dateFormat = setting('site.date_format', 'Y-m-d');

最佳实践

1. 分组规划

按功能模块划分配置分组
保持分组键名唯一且有意义
为分组添加清晰的备注说明

2. 配置项命名

使用点号分隔的层级结构：group.key
键名使用小写字母和下划线
确保键名在整个系统中唯一

3. 安全性

敏感配置（如 API 密钥）建议使用加密存储
避免在客户端代码中硬编码配置值
定期清理不再使用的配置项

4. 性能

配置数据会被缓存，减少数据库查询
修改配置后自动清除缓存
大量配置考虑使用数据库索引优化

#系统配置

#数据结构

#配置分组（sys_setting_group）

#配置项（sys_setting_items）

#支持的组件类型

#options 配置格式

#props 配置格式

#前端使用

#读取配置

#在代码中使用

#API 接口

#配置分组

#配置项

#获取分组下的配置项

#保存配置值

#使用示例

#创建一个网站配置分组

#最佳实践

#1. 分组规划

#2. 配置项命名

#3. 安全性

#4. 性能