mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-01 15:32:48 +08:00
119 lines
5.1 KiB
Markdown
119 lines
5.1 KiB
Markdown
---
|
||
name: "ulthon-scheme-definition"
|
||
description: "指导编写 Ulthon Admin 的 Scheme 架构定义文件。当需要新增表结构、修改字段定义或配置组件显示时调用。"
|
||
---
|
||
|
||
# Ulthon Scheme 定义指南
|
||
|
||
本技能指导如何在 `app/admin/scheme/` 目录下编写 Scheme 文件，这些文件定义了数据库表结构以及后台管理界面的组件呈现方式。
|
||
|
||
参考文档：[表结构-ulthon_admin](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html)
|
||
|
||
## 基本结构
|
||
|
||
Scheme 文件是一个 PHP 类，继承自 `BaseScheme`，并使用 PHP 8 注解（Attribute）来描述元数据。
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace app\admin\scheme;
|
||
|
||
use app\common\scheme\BaseScheme;
|
||
use app\common\scheme\attribute\Table;
|
||
use app\common\scheme\attribute\Field;
|
||
use app\common\scheme\attribute\Component;
|
||
use app\common\scheme\attribute\Index;
|
||
|
||
#[Table(name: 'ul_your_table_name', comment: '表注释')]
|
||
#[Index(columns: ['field1'], name: 'idx_field1', type: 'NORMAL')]
|
||
class YourClassName extends BaseScheme
|
||
{
|
||
#[Field(type: 'int', length: 11, nullable: false, unsigned: true, autoIncrement: true, primary: true)]
|
||
public $id;
|
||
|
||
#[Field(type: 'char', length: 100, default: '', comment: '标题')]
|
||
public $title;
|
||
|
||
#[Field(type: 'int', length: 11, default: '1', comment: '状态', unsigned: true)]
|
||
#[Component(type: 'radio', options: ['禁用', '启用'])]
|
||
public $status;
|
||
|
||
#[Field(type: 'int', length: 11, default: '0', comment: '创建时间', unsigned: true)]
|
||
public $create_time;
|
||
|
||
#[Field(type: 'int', length: 11, default: '0', unsigned: true)]
|
||
public $update_time;
|
||
|
||
#[Field(type: 'int', length: 11, default: '0', unsigned: true)]
|
||
public $delete_time;
|
||
}
|
||
```
|
||
|
||
## 注解详解
|
||
|
||
### 1. #[Table] (类注解)
|
||
- `name`: 数据库表名（建议以 `ul_` 开头）。
|
||
- `comment`: 表注释。
|
||
- `engine`: 存储引擎，默认 `InnoDB`。
|
||
- `charset`: 字符集，默认 `utf8mb4`。
|
||
|
||
### 2. #[Index] (类注解，可重复)
|
||
- `columns`: 索引列，字符串或数组（如 `['cate_id', 'status']`）。
|
||
- `name`: 索引名称。
|
||
- `type`: 索引类型：`NORMAL`, `UNIQUE`, `FULLTEXT`。
|
||
|
||
### 3. #[Field] (属性注解)
|
||
- `type`: 字段类型 (e.g., `int`, `bigint`, `char`, `varchar`, `text`, `decimal`, `tinyint`)。
|
||
- `length`: 长度 (对于 char/varchar/int)。
|
||
- `precision`: 精度 (对于 decimal)。
|
||
- `scale`: 小数位数 (对于 decimal)。
|
||
- `nullable`: 是否允许为空 (bool)。
|
||
- `default`: 默认值 (mixed)。
|
||
- `comment`: 字段注释。
|
||
- `unsigned`: 是否无符号 (bool)。
|
||
- `autoIncrement`: 是否自增 (bool)。
|
||
- `primary`: 是否为主键 (bool)。
|
||
|
||
### 4. #[Component] (属性注解，可选)
|
||
定义在后台管理页面中该字段使用的 UI 组件。
|
||
- `type`: 组件类型。常用值：
|
||
- `text`: 普通文本框（默认）。
|
||
- `image`: 单图片上传。
|
||
- `images`: 多图片上传（默认分隔符为 `|`）。
|
||
- `file`: 单文件上传。
|
||
- `files`: 多文件上传（默认分隔符为 `|`）。
|
||
- `date`: 时间/日期组件。需配合 `options` 指定格式，如 `datetime` 或 `date`。
|
||
- `editor`: 富文本编辑器。
|
||
- `textarea`: 文本域。
|
||
- `select`: 下拉选择框（需配合 `options`）。
|
||
- `switch`: 开关组件（需配合 `options`，如 `['0' => '关闭', '1' => '开启']`）。
|
||
- `checkbox`: 复选框（需配合 `options`）。
|
||
- `radio`: 单选框（需配合 `options`）。
|
||
- `relation`: 关联表下拉选择。`options` 需包含：
|
||
- `table`: 关联表名。
|
||
- `relationBindSelect`: 显示的字段名。
|
||
- `primaryKey`: 关联表主键（可选）。
|
||
- `onlyFields`: 列表页显示的字段（可选，用 `|` 分隔）。
|
||
- `table`: 表格选择器。`options` 需包含：
|
||
- `table`: 关联表名。
|
||
- `type`: 选择模式 (`checkbox`/`radio`)。
|
||
- `valueField`: 值字段名。
|
||
- `fieldName`: 显示字段名。
|
||
- `city`: 城市选择器。`options` 需包含：
|
||
- `level`: 层级 (`province`/`city`/`area`)。
|
||
- `options`: 选项数据。支持索引数组 `['禁用', '启用']` 或关联数组 `['1' => '男', '2' => '女']`，对于 `relation`/`table`/`city` 类型，则是配置参数数组。
|
||
|
||
## 编写规范
|
||
|
||
1. **命名规范**: 文件名采用大驼峰（PascalCase），且必须与类名一致。
|
||
2. **时间字段**: 统一使用 `int` 存储 Unix 时间戳，默认 `0`，非空。不要使用 `datetime`/`timestamp`。
|
||
3. **软删除**: `delete_time` 字段（`int`，默认 `0`）存在时，模型自动启用软删除机制。查询时不要手写 `delete_time` 条件。
|
||
4. **状态表达**: 避免使用 MySQL ENUM 类型。优先使用 `int` 或 `tinyint` 配合 `#[Component(type: 'radio')]` 或 `#[Component(type: 'switch')]`。
|
||
5. **注释约定**: `Field` 的 `comment` 会直接同步到数据库字段注释，同时也作为后台表单的 Label。
|
||
6. **字段后缀约定**: 框架会根据字段名后缀自动推断部分组件类型（若未显式指定 `#[Component]`）：
|
||
- `image`, `logo`, `photo`, `icon`: 默认为单图片。
|
||
- `images`, `photos`, `icons`: 默认为多图片。
|
||
- `file`: 默认为单文件。
|
||
- `files`: 默认为多文件。
|
||
|