mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-07-01 15:32:48 +08:00

Files

2026-03-26 20:22:34 +08:00

5.1 KiB

Raw Blame History

name, description

name	description
ulthon-scheme-definition	指导编写 Ulthon Admin 的 Scheme 架构定义文件。当需要新增表结构、修改字段定义或配置组件显示时调用。

Ulthon Scheme 定义指南

本技能指导如何在 app/admin/scheme/ 目录下编写 Scheme 文件，这些文件定义了数据库表结构以及后台管理界面的组件呈现方式。

参考文档：表结构-ulthon_admin

基本结构

Scheme 文件是一个 PHP 类，继承自 BaseScheme，并使用 PHP 8 注解（Attribute）来描述元数据。

<?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 类型，则是配置参数数组。

编写建议

命名规范: 文件名采用大驼峰（PascalCase），且必须与类名一致。
基础字段: 建议所有业务表都包含 id, create_time, update_time 字段。如果需要软删除，增加 delete_time。
- create_time, update_time, delete_time 建议设置为 int 类型，默认 0，非空。
状态表达: 避免使用 MySQL ENUM 类型。优先使用 int 或 tinyint 配合 #[Component(type: 'radio')] 或 #[Component(type: 'switch')]。
注释约定: Field 的 comment 会直接同步到数据库字段注释，同时也作为后台表单的 Label。
字段后缀约定: 框架会根据字段名后缀自动推断部分组件类型（若未显式指定 #[Component]）：
- image, logo, photo, icon: 默认为单图片。
- images, photos, icons: 默认为多图片。
- file: 默认为单文件。
- files: 默认为多文件。

5.1 KiB Raw Blame History Unescape Escape