插件目录结构

📁 目录结构

了解插件的文件组织结构

目录结构概览

一个完整的 Toolbox 插件通常包含以下文件和目录：

plugin/                          # 插件根目录
└── {分类}/{插件名}/              # 插件目录
    ├── App.php                 # 插件主类（必需）
    ├── index.html              # 插件首页（必需）
    ├── plugin.json             # 插件配置（可选）
    ├── config.html             # 配置页面（可选）
    └── static/                 # 静态资源（可选）
        ├── css/                # 样式文件
        ├── js/                 # JavaScript 文件
        └── images/             # 图片资源

目录命名规范

分类目录

分类目录使用小写英文，可选值：

分类	说明	示例
dev	开发工具	JSON 格式化、代码转换
fun	娱乐工具	小游戏、趣味生成器
utility	实用工具	二维码、IP 查询
web	站长工具	ICP 查询、WHOIS
wqq	QQ 工具	QQ 等级、好友检测

插件目录

插件目录命名规则：

• ✅ 推荐：小写英文 + 下划线

  • json_format
  • qr_code
  • ip_lookup

• ❌ 避免：

  • 大写字母
  • 中文字符
  • 特殊符号（除下划线外）
  • 空格

核心文件详解

App.php（必需）

插件的主类文件，定义插件的后端逻辑。

文件位置：plugin/{分类}/{插件名}/App.php

基本结构：

<?php
/**
 * 插件标题
 *
 * 插件功能描述
 */

namespace plugin\{分类}\{插件名};

use app\Plugin;

class App extends Plugin
{
    /**
     * 插件首页
     */
    public function index()
    {
        return $this->view();
    }

    /**
     * 处理 AJAX 请求
     */
    public function api()
    {
        $input = input('post.data');
        $result = $this->process($input);
        return json(['code' => 0, 'data' => $result]);
    }
}

index.html（必需）

插件的前端页面，使用 HTML + Layui 编写。

文件位置：plugin/{分类}/{插件名}/index.html

基本结构：

<!-- 插件标题 -->
<div class="nk-content">
    <div class="container-fluid">
        <div class="nk-content-inner">
            <div class="nk-content-body">
                <!-- 页面标题 -->
                <div class="nk-block-head nk-block-head-sm">
                    <div class="nk-block-between">
                        <div class="nk-block-head-content">
                            <h3 class="nk-block-title page-title">工具标题</h3>
                            <div class="nk-block-des text-soft">
                                <p>工具功能描述</p>
                            </div>
                        </div>
                    </div>
                </div>

                <!-- 工具内容区 -->
                <div class="nk-block">
                    <div class="card card-bordered">
                        <div class="card-inner">
                            <!-- 工具界面 -->
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
</div>

<script>
// 页面逻辑
</script>

plugin.json（可选）

插件的配置文件，定义插件的元信息。

文件位置：plugin/{分类}/{插件名}/plugin.json

基本结构：

{
    "name": "插件名称",
    "version": "1.0.0",
    "description": "插件描述",
    "author": "作者名",
    "url": "https://example.com",
    "icon": "icon-name",
    "config": true
}

字段说明：

字段	类型	必填	说明
name	string	是	插件显示名称
version	string	是	版本号（如 1.0.0）
description	string	否	插件描述
author	string	否	作者名称
url	string	否	作者主页或项目地址
icon	string	否	图标名称
config	boolean	否	是否有配置页面

config.html（可选）

插件的配置页面，当 plugin.json 中 config 为 true 时显示。

文件位置：plugin/{分类}/{插件名}/config.html

基本结构：

<div class="layui-form">
    <div class="layui-form-item">
        <label class="layui-form-label">配置项1</label>
        <div class="layui-input-block">
            <input type="text" name="config1" class="layui-input">
        </div>
    </div>

    <div class="layui-form-item">
        <label class="layui-form-label">配置项2</label>
        <div class="layui-input-block">
            <input type="checkbox" name="config2" lay-skin="switch">
        </div>
    </div>
</div>

静态资源目录

css/ 目录

存放插件的样式文件：

static/
└── css/
    ├── style.css          # 主样式文件
    └── theme.css          # 主题样式（可选）

引用方式：

<link rel="stylesheet" href="/plugin/{分类}/{插件名}/static/css/style.css">

js/ 目录

存放插件的 JavaScript 文件：

static/
└── js/
    ├── main.js            # 主逻辑文件
    └── utils.js           # 工具函数（可选）

引用方式：

<script src="/plugin/{分类}/{插件名}/static/js/main.js"></script>

images/ 目录

存放插件的图片资源：

static/
└── images/
    ├── logo.png           # 插件图标
    ├── banner.jpg         # 横幅图片
    └── icons/             # 图标集合
        ├── icon1.png
        └── icon2.png

引用方式：

<img src="/plugin/{分类}/{插件名}/static/images/logo.png">

完整示例

以下是一个完整的插件目录结构示例：

plugin/
└── dev/
    └── json_format/           # JSON 格式化工具
        ├── App.php            # 主类文件
        ├── index.html         # 插件页面
        ├── plugin.json        # 插件配置
        ├── config.html        # 配置页面
        └── static/            # 静态资源
            ├── css/
            │   └── style.css
            ├── js/
            │   └── main.js
            └── images/
                └── icon.png

文件权限

确保插件文件有正确的权限：

# 设置目录权限
chmod -R 755 plugin/dev/json_format/

# 设置文件权限
chmod 644 plugin/dev/json_format/App.php
chmod 644 plugin/dev/json_format/index.html

# 静态资源目录需要写入权限（如果需要动态生成文件）
chmod -R 777 plugin/dev/json_format/static/

命名空间

插件类的命名空间遵循 PSR-4 规范：

namespace plugin\{分类}\{插件名};

// 示例
namespace plugin\dev\json_format;
namespace plugin\utility\qr_code;

最佳实践

✅ 推荐做法

1. 文件组织清晰

   • 按功能分类存放文件
   • 使用有意义的文件名

2. 代码规范

   • 遵循 PSR 编码规范
   • 添加必要的注释

3. 资源管理

   • 压缩 CSS/JS 文件
   • 优化图片大小
   • 使用 CDN（可选）

❌ 避免做法

1. 文件混乱

   • 所有文件放在根目录
   • 使用无意义的文件名

2. 硬编码路径

   • 使用绝对路径
   • 假设固定的目录结构

3. 资源浪费

   • 加载不必要的库
   • 使用过大的图片

---

📁 目录结构清晰，开发更高效！

接下来学习如何配置插件～