插件配置文件

This content is not available in your language yet.

⚙️ 配置文件

plugin.json 配置详解

配置文件概述

plugin.json 是插件的配置文件，用于定义插件的元信息和配置项。虽然这个文件是可选的，但建议每个插件都包含它，以便更好地管理和展示插件信息。

基本结构

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

字段详解

name（必填）

说明：插件的显示名称

类型：string

示例：

{
    "name": "JSON 格式化工具"
}

规范：

使用中文或英文
简洁明了，不超过 20 个字符
能准确描述插件功能

version（必填）

说明：插件的版本号

类型：string

示例：

{
    "version": "1.0.0"
}

版本号规范（语义化版本）：

格式	说明	示例
主版本号	重大更新，可能不兼容	1.0.0 → 2.0.0
次版本号	功能更新，向下兼容	1.0.0 → 1.1.0
修订号	Bug 修复	1.0.0 → 1.0.1

description（可选）

说明：插件的详细描述

类型：string

示例：

{
    "description": "提供 JSON 数据的格式化、压缩、验证功能，支持语法高亮显示"
}

建议：

描述插件的主要功能
说明适用场景
不超过 100 个字符

author（可选）

说明：插件作者名称

类型：string

示例：

{
    "author": "张三"
}

url（可选）

说明：作者主页或项目地址

类型：string

示例：

{
    "url": "https://github.com/username/toolbox-plugin"
}

icon（可选）

说明：插件图标名称

类型：string

示例：

{
    "icon": "fa-code"
}

常用图标：

图标类名	说明
`fa-code`	代码相关
`fa-lock`	加密安全
`fa-image`	图片处理
`fa-file`	文件处理
`fa-globe`	网络相关
`fa-calculator`	计算工具
`fa-qrcode`	二维码
`fa-gamepad`	游戏娱乐

config（可选）

说明：是否有配置页面

类型：boolean

示例：

{
    "config": true
}

当设置为 true 时，需要在插件目录下创建 config.html 文件。

hooks（可选）

说明：插件钩子配置

类型：object

示例：

{
    "hooks": {
        "init": "initHook",
        "beforeRender": "beforeRenderHook",
        "afterRender": "afterRenderHook"
    }
}

可用钩子：

钩子名称	触发时机	说明
`init`	插件初始化时	用于初始化配置
`beforeRender`	渲染页面前	用于准备数据
`afterRender`	渲染页面后	用于清理资源

完整配置示例

简单插件

{
    "name": "Base64 编解码",
    "version": "1.0.0",
    "description": "提供 Base64 编码和解码功能",
    "author": "Toolbox Team",
    "icon": "fa-code"
}

带配置的插件

{
    "name": "二维码生成器",
    "version": "2.1.0",
    "description": "支持文本、URL、名片等多种类型的二维码生成，可自定义尺寸和颜色",
    "author": "张三",
    "url": "https://github.com/zhangsan/qrcode-plugin",
    "icon": "fa-qrcode",
    "config": true,
    "hooks": {
        "init": "initConfig"
    }
}

复杂插件

{
    "name": "图片处理工具箱",
    "version": "3.0.2",
    "description": "提供图片压缩、格式转换、加水印、裁剪等多种图片处理功能",
    "author": "李四",
    "url": "https://example.com/image-toolbox",
    "icon": "fa-image",
    "config": true,
    "hooks": {
        "init": "initHook",
        "beforeRender": "prepareData",
        "afterRender": "cleanup"
    }
}

配置页面开发

当 config 设置为 true 时，需要创建 config.html 文件：

基本结构

<div class="layui-form" lay-filter="plugin-config">
    <!-- 文本输入 -->
    <div class="layui-form-item">
        <label class="layui-form-label">API Key</label>
        <div class="layui-input-block">
            <input type="text" name="api_key"
                   placeholder="请输入 API Key"
                   class="layui-input"
                   value="{$config.api_key|default=''}">
        </div>
    </div>

    <!-- 开关 -->
    <div class="layui-form-item">
        <label class="layui-form-label">启用功能</label>
        <div class="layui-input-block">
            <input type="checkbox" name="enable"
                   lay-skin="switch" lay-text="ON|OFF"
                   {if $config.enable}checked{/if}>
        </div>
    </div>

    <!-- 下拉选择 -->
    <div class="layui-form-item">
        <label class="layui-form-label">默认格式</label>
        <div class="layui-input-block">
            <select name="format">
                <option value="json" {if $config.format=='json'}selected{/if}>JSON</option>
                <option value="xml" {if $config.format=='xml'}selected{/if}>XML</option>
                <option value="yaml" {if $config.format=='yaml'}selected{/if}>YAML</option>
            </select>
        </div>
    </div>

    <!-- 多行文本 -->
    <div class="layui-form-item">
        <label class="layui-form-label">自定义样式</label>
        <div class="layui-input-block">
            <textarea name="custom_css"
                      placeholder="输入自定义 CSS"
                      class="layui-textarea">{$config.custom_css|default=''}</textarea>
        </div>
    </div>
</div>

<script>
layui.use(['form'], function(){
    var form = layui.form;

    // 监听配置保存
    form.on('submit(saveConfig)', function(data){
        // 保存配置逻辑
        return false;
    });
});
</script>

配置项类型

文本输入

<div class="layui-form-item">
    <label class="layui-form-label">文本标签</label>
    <div class="layui-input-block">
        <input type="text" name="field_name"
               class="layui-input"
               value="{$config.field_name|default=''}">
    </div>
</div>

密码输入

<div class="layui-form-item">
    <label class="layui-form-label">密码</label>
    <div class="layui-input-block">
        <input type="password" name="password"
               class="layui-input"
               value="{$config.password|default=''}">
    </div>
</div>

数字输入

<div class="layui-form-item">
    <label class="layui-form-label">数量</label>
    <div class="layui-input-block">
        <input type="number" name="count"
               class="layui-input"
               value="{$config.count|default=0}">
    </div>
</div>

开关

<div class="layui-form-item">
    <label class="layui-form-label">开关</label>
    <div class="layui-input-block">
        <input type="checkbox" name="switch"
               lay-skin="switch"
               {if $config.switch}checked{/if}>
    </div>
</div>

单选框

<div class="layui-form-item">
    <label class="layui-form-label">选项</label>
    <div class="layui-input-block">
        <input type="radio" name="option" value="1" title="选项1" {if $config.option==1}checked{/if}>
        <input type="radio" name="option" value="2" title="选项2" {if $config.option==2}checked{/if}>
    </div>
</div>

多选框

<div class="layui-form-item">
    <label class="layui-form-label">多选</label>
    <div class="layui-input-block">
        <input type="checkbox" name="features[]" value="feature1" title="功能1"
               {in_array('feature1', $config.features)}checked{/in_array}>
        <input type="checkbox" name="features[]" value="feature2" title="功能2"
               {in_array('feature2', $config.features)}checked{/in_array}>
    </div>
</div>

下拉选择

<div class="layui-form-item">
    <label class="layui-form-label">选择</label>
    <div class="layui-input-block">
        <select name="select">
            <option value="">请选择</option>
            <option value="1" {if $config.select==1}selected{/if}>选项1</option>
            <option value="2" {if $config.select==2}selected{/if}>选项2</option>
        </select>
    </div>
</div>

多行文本

<div class="layui-form-item">
    <label class="layui-form-label">内容</label>
    <div class="layui-input-block">
        <textarea name="content"
                  class="layui-textarea">{$config.content|default=''}</textarea>
    </div>
</div>

配置数据读取

在 App.php 中读取配置：

<?php
namespace plugin\dev\my_plugin;

use app\Plugin;

class App extends Plugin
{
    public function index()
    {
        // 获取插件配置
        $config = $this->getConfig();

        // 获取特定配置项
        $apiKey = $this->getConfig('api_key');

        // 传递给视图
        return $this->view()->assign([
            'config' => $config,
            'apiKey' => $apiKey
        ]);
    }
}

最佳实践

✅ 推荐做法

版本管理
- 使用语义化版本号
- 记录版本更新日志
配置设计
- 提供合理的默认值
- 配置项命名清晰
- 添加配置说明
文档完善
- 描述插件功能
- 说明配置项用途
- 提供使用示例

❌ 避免做法

版本混乱
- 随意更改版本号
- 不记录更新内容
配置复杂
- 过多的配置项
- 不直观的命名
信息缺失
- 没有插件描述
- 缺少作者信息

⚙️ 配置完成！

接下来学习开发规范，写出优雅的代码～