文档首页 / HareAdmin 开发手册

插件

插件放在 addons/{name}/,可前后台一体交付。安装时系统会做文件冲突检测;日常安装/升级也可走后台「插件管理」或商店。

优先复用系统能力(强制倾向)

插件开发优先使用平台已有组件与约定,避免再打包一份同类库或自写重复壳。这样安装包更小、行为与后台一致,也减少冲突。

  • 列表 / 表单 / 上传 / 弹层 / 提示:复用 Table.api、Form.api、Fast.api.ajax / confirm / contentDialog、Toastr、Layer;不要另引一套表格或 toast。
  • 富文本 / 短信 / 支付 / 存储:走驱动通道(见下节)。业务页只写约定 class(如 editor),不硬编码具体厂商包名。
  • 后台页面脚本:优先写在当前视图内联;不要为单个列表页再新增零散 public/assets/js/backend/** 包装文件。
  • 文案:界面用 lang() + 短 key 复用;业务内容用 ContentLang;访客配置用 Settings / localize。
  • 样式:沿用 AdminLTE4 / Bootstrap5 与系统 content CSS;仅补充业务必需的少量样式,勿整份拷贝 UI 框架。
  • 仅当平台确实没有对应能力时,再在插件 assets/ 中引入第三方库,并在 bootstrap.js 注册 RequireJS 路径。

目录结构

blog/
├── Blog.php           # 插件主类(安装/卸载/菜单/行为),必需
├── info.ini           # 基本信息与开关状态,必需
├── config.php         # 后台「配置」表单 schema,必需
├── bootstrap.js       # 前端 RequireJS 路径/shim(可选)
├── install.sql        # 安装时导入(可选)
├── LICENSE
├── controller/        # 前台插件控制器
├── model/
├── view/
├── lang/              # zh.php / en.php … → 合并进 yt_lang
├── app/               # 覆盖到项目 app/(后台控制器/视图等)
├── public/            # 覆盖到项目 public/
└── assets/            # 复制到 public/assets/addons/blog/

目录说明

  • app/、public/:安装时映射到根目录;冲突会提示覆盖或跳过。
  • assets/:始终复制到 /public/assets/addons/{name}/,视图里用 __ADDON__ 指该路径。尽量少放,优先系统资源。
  • controller / model / view:插件前台 MVC,不拷贝到 app/。
  • lang/*.php:安装/升级时 LangPack::mergeAddon 写入 yt_lang(source=插件名)。
  • 主类文件名与目录名对应,首字母大写(如 blog → Blog.php)。

行为与菜单

在插件主类中实现安装菜单、卸载清理,以及平台钩子(如 configInit 注册驱动)。菜单节点标题用短 key(Edit / Add / Delete),走 lang(),不要为每个插件再建同义长 key。

驱动通道

业务代码不要写死具体编辑器 / 短信 / 支付 SDK。通过 AddonDriver::register / active 注册;消费方只用约定 class(如 textarea.editor)。详见项目「Addon drivers」规范。

配置与 localize

访客可见文案(站名、SEO)在 config.php 设 localize => true;开关、路由、密钥保持全局一份。读写用 Settings / settings_get,API 见「多语言 → 模块设置与 localize」。

命令与商店

php think addon -a blog -c create|enable|disable|uninstall|package

打包后可上传商店。默认商店/API:api.hareadmin.com。

注意

  • 界面文案一律 lang();业务标题/正文用 ContentLang。
  • 卸载前确认菜单、表、覆盖文件已按主类逻辑清理。

会员组能力(UserCapability)

会员组在核心里保持薄底座:表 user_group、用户字段 group_id、后台 CRUD。日常权限在「会员组」表单里勾选能力(Capability)。底层 user/rule 规则树留给高级场景,侧栏默认隐藏(yetuadmin.member_rule_menu = false;设为 true 可再显示)。

不要单独做「整包会员组插件」只为托管 group_id。业务插件注册自己需要的能力,运营只勾选即可。

插件注册

在插件 configInit 或钩子 user_capability_init 中:

\app\common\library\UserCapability::register('addon/shop/buy', [
    'title' => 'Shop buy',
    'category' => 'shop',
    'category_title' => 'Shop',
    'priority' => 50,
]);

name 须与鉴权时的完整规则路径一致(与历史 user_rule.name 相同风格)。

鉴权

Auth::instance()->hasCapability('addon/shop/buy');

请求级仍可用 Auth::check()(会拼当前模块前缀)。对已注册的完整能力名,优先用 hasCapability()。

存储与兼容

  • 勾选结果写入 user_group.rules(user_rule id,含祖先),兼容原有 Auth::check()。
  • 保存能力表单时保留未进入能力注册表的自定义规则节点。
  • 核心内置:前台 / API 的登录、注册、会员中心、个人资料。

建议 / 避免

  • 建议:由真正执行校验的插件注册能力。
  • 建议:标题复用短 i18n(如 Login、Profile)。
  • 避免:让运营为日常 ACL 维护规则树。
  • 避免:在能力 + 会员组模型之外硬编码业务 ACL。

开发版约定,行为可能继续演进;示例保持可复制粘贴。