插件开发 · 后台菜单与配置

一、注册后台菜单

在入口类的 menu() 方法中返回菜单数组，安装时写入 ws_rule：

public function menu()
{
    return [
        [
            'name'  => '我的插件',                  // 菜单名
            'icon'  => 'fa-solid fa-plug',          // FontAwesome 6 类名
            'url'   => 'myplugin/index/index',      // 控制器路径
            'sort'  => 50,                          // 排序
            'child' => [
                ['name' => '数据列表', 'url' => 'myplugin/log/index'],
                ['name' => '插件设置', 'url' => 'myplugin/index/config'],
            ],
        ],
    ];
}

图标一律使用 FontAwesome 6：fa-solid fa-xxx。**不要用 am-icon-*** —— Amaze UI 的字体路径是坏的，会导致全站图标空白。

二、权限节点

菜单项会自动注册为权限节点。若需要更细粒度的操作权限，显式声明：

public function menu()
{
    return [
        [
            'name'   => '我的插件',
            'icon'   => 'fa-solid fa-plug',
            'url'    => 'myplugin/index/index',
            'nodes'  => [
                'myplugin/log/delete'   => '删除日志',
                'myplugin/log/export'   => '导出日志',
            ],
            'child'  => [
                ['name' => '数据列表', 'url' => 'myplugin/log/index'],
            ],
        ],
    ];
}

后台「角色管理」中即可勾选这些节点。

三、后台控制器

放在 addons/myplugin/admin/controller/，继承 CMS 的后台基类以复用列表、表单与分页：

<?php
namespace addons\myplugin\admin\controller;

use app\admin\controller\Base;

class Log extends Base
{
    protected $modelName = 'my_log';     // 物理表名（不含前缀）
    protected $order     = 'id desc';

    public function index()
    {
        return parent::index();
    }
}

继承 Base 后自动获得：

四、插件配置页

4.1 声明配置字段

addons/myplugin/config.php：

<?php
return [
    [
        'name'  => 'api_key',
        'title' => '接口密钥',
        'type'  => 'text',
        'value' => '',
        'tip'   => '在服务商后台获取',
        'rule'  => 'require',
    ],
    [
        'name'  => 'notify_url',
        'title' => '回调地址',
        'type'  => 'text',
        'value' => '',
    ],
    [
        'name'  => 'debug',
        'title' => '调试模式',
        'type'  => 'switch',
        'value' => '0',
    ],
];

4.2 自动渲染

后台访问 myplugin/index/config 时，程序会按上述定义渲染表单并处理保存，值写入 ws_addon_config。

4.3 读取配置

use think\facade\Config;
$key = Config::get('addons.myplugin.api_key');

4.4 自定义设置页

需要更复杂的界面时，写自己的控制器与视图：

addons/myplugin/admin/view/index/config.html

{include file="common/page" /}
<form class="cms-form" method="post" action="{:url('myplugin/index/saveConfig')}">
  {:token_field()}
  <div class="cms-form-item">
    <label>接口密钥</label>
    <input type="text" name="api_key" class="layui-input" value="{$config.api_key}">
  </div>
  <button type="submit" class="layui-btn layui-btn-normal">保存</button>
</form>

五、前台页面

插件需要前台页面时：

addons/myplugin/controller/Callback.php
addons/myplugin/view/callback/index.html

并在 addons/myplugin/route/route.php 注册路由。

六、注意事项

• 后台控制器名不要与基类的动作冲突：新增自定义动作前先

grep -rn "public function <动作名>\b" app/admin/controller/ | grep -v Base.php

• 所有写操作必须校验 CSRF（表单里加 {:token_field()}）

• 列表页不要用 ->column('id,sort') 取映射，改用 field()->select()->toArray() 自行遍历

• 弹层页统一继承 common/page，程序会自动隐藏侧栏与头部