社区论坛
论坛首页/ LiteLog /帖子详情

LiteLog 小工具(Widget)开发规范 v1.0

龙魂 管理员
1 天前 279 浏览 0 回复
1 楼

目标:彻底解耦“数据结构”与“视觉样式”。让插件专注业务逻辑,让主题专注皮肤美化,一次开发,通吃所有主题。


第一条:核心原则(戒掉“UI 依赖”)

  1. 禁止输出卡片外壳:插件代码里绝对不准出现带背景色、边框的 <div class="widget"> 或 <div class="card">。

  2. 禁止输出标题栏:不要自己写 <h3 class="widget-title"> 或包一层 <div class="head">。

  3. 禁止写内联样式:绝对不准使用 style="background:#fff; color:#333;" 这种暴力写法。

  4. 纯净输出内容:render() 方法里只准输出纯净的数据结构,比如 ul>li 列表、div 包裹的图文、form 表单。


第二条:如何让标题和“更多”生效?

内核在渲染时会自动提取以下特定标记,并放入标准的头部中:

  1. 标题:如果你必须动态输出标题,请用 <h3>(或者带 .title 类的标签),内核会自动剥离它并送入标准头部。如果不需要,可以不输出,内核会默认使用后台配置的标题(如“最新文章”)。

  2. 更多链接:请使用 <a class="more" href="...">更多</a>,内核会自动把它提取到标题栏的最右侧。


第三条:标准代码对比(照着这个改)

❌ 错误示范(旧版,严重污染主题)

php
// 这种写法会生成一大片白底卡片,主题根本改不动!
public function render($s, $instanceId) {
    echo '<div class="my-custom-box" style="background:#fff; padding:15px; border-radius:8px;">';
    echo '<h3 style="color:red;">' . $s['title'] . '</h3>';
    echo '<ul>';
    echo '<li style="padding:10px; border-bottom:1px solid #eee;"><a href="...">文章1</a></li>';
    echo '</ul>';
    echo '</div>';
}

✅ 正确示范(新版,无壳纯内容)

php
// 只需要输出纯粹的列表,外套和标题全交给内核与主题!
public function render($s, $instanceId) {
    // 1. (可选) 让内核捕获并生成“更多”按钮
    $moreUrl = BLOG_URL . '?action=archive';
    
    // 2. 输出纯内容(可以使用自定义 class,但别带样式)
    echo '<ul class="my-plugin-list">';
    foreach ($data as $row) {
        echo '<li>';
        echo '<a href="' . h($row['url']) . '">' . h($row['title']) . '</a>';
        echo '<span class="count">' . (int)$row['views'] . '</span>'; // 徽章用 class="count",主题会自动美化
        echo '</li>';
    }
    echo '</ul>';
    
    // 3. 渲染“更多”链接(插件写在这里,内核会自动提拔到标题栏右侧)
    if ($moreUrl) {
        echo '<a class="more" href="' . $moreUrl . '">更多</a>';
    }
}

第四条:HTML 标签约定(供主题匹配)

为了让所有主题都能精准识别并美化,请尽量遵循以下基础标签结构:

元素推荐写法主题将如何处理
列表<ul> <li>主题会自动重置缩进,并加上羊皮纸虚线分隔
列表内的数字/徽章<span class="count">12</span> 或 <span class="badge">Lv.5</span>主题会自动加背景色、小圆角
按钮<button class="btn">提交</button>主题会自动渲染为朱红渐变按钮
图片<img src="..." alt="...">主题会自动加复古边框和阴影
空状态<div class="empty">暂无内容</div>主题会自动加上斜体、居中和提示色

第五条:后台配置(form 方法)

这部分保持不变,继续使用内核提供的 fieldText、fieldNumber 等方法输出配置项。


🛠️ 改造操作指南(给现在的你)

去找到你那几个插件的源码文件(比如 widget_builtin.php、widget_extra.php 或者第三方插件的 xxx.php),执行以下“粉碎”操作:

  1. 搜 echo '<div class="widget:直接干掉这一行,把对应的闭合 </div> 也干掉。

  2. 搜 style="background:把所有内联的背景色、文字颜色、边框删掉。

  3. 搜 <h3 class="widget-title"> 或 <div class="head">:删掉这些外框和标题,不用自己输出。

  4. 搜 class="more":确保“更多”链接包在 a 标签里,并且有 class="more",放在末尾即可。

改完之后,只要里面的内容还是 a 标签和 ul 列表,这个插件就被彻底“招安”了,套在任何符合规范的 LiteLog 主题上,都会自动变成完美契合的样式!

标签: #LiteLog
请先 登录 或 后台登录 后参与讨论