373 lines
7.8 KiB
Markdown
373 lines
7.8 KiB
Markdown
Typecho 用户卡片插件使用说明
|
||
插件概述
|
||
用户卡片插件是一个用于Typecho博客系统的评论增强插件。当用户悬停在评论者的用户名上时，会显示一个包含用户信息和近期文章的用户卡片，提升用户体验和社区互动性。
|
||
|
||
功能特性
|
||
核心功能
|
||
用户信息展示：显示用户的注册时间、评论数量、最后登录时间等
|
||
|
||
RSS文章集成：自动获取并显示用户的RSS源中的近期文章
|
||
|
||
响应式交互：鼠标悬停显示，智能延迟与隐藏机制
|
||
|
||
缓存机制：RSS数据缓存，减少服务器请求压力
|
||
|
||
技术特性
|
||
支持动态加载的评论内容
|
||
|
||
自动处理游客和注册用户
|
||
|
||
完善的错误处理机制
|
||
|
||
可配置的显示参数
|
||
|
||
安装指南
|
||
环境要求
|
||
Typecho 1.0 或更高版本
|
||
|
||
PHP 5.6 或更高版本
|
||
|
||
支持JavaScript的现代浏览器
|
||
|
||
安装步骤
|
||
下载插件
|
||
|
||
bash
|
||
git clone https://github.com/your-repo/UserCard.git
|
||
# 或者下载ZIP包解压
|
||
上传插件
|
||
|
||
将插件文件夹重命名为 UserCard
|
||
|
||
上传到Typecho的 usr/plugins/ 目录下
|
||
|
||
确保目录结构为：usr/plugins/UserCard/
|
||
|
||
激活插件
|
||
|
||
登录Typecho后台
|
||
|
||
进入"控制台" → "插件"
|
||
|
||
找到"用户卡片"插件，点击"启用"
|
||
|
||
配置权限
|
||
|
||
确保缓存目录可写：
|
||
|
||
bash
|
||
chmod 755 usr/plugins/UserCard/cache
|
||
插件配置
|
||
后台配置选项
|
||
登录Typecho后台，进入"设置" → "用户卡片"，配置以下参数：
|
||
|
||
配置项 默认值 说明
|
||
RSS缓存时间（秒） 3600 RSS数据缓存时间，建议1小时
|
||
最多显示文章数 5 前端卡片中显示的RSS文章数量
|
||
RSS请求超时时间（秒） 10 获取RSS数据时的超时时间
|
||
卡片显示延迟（毫秒） 200 鼠标悬停后显示卡片的延迟
|
||
用户RSS管理
|
||
管理员可以管理用户的RSS源地址：
|
||
|
||
进入"管理" → "RSS管理"
|
||
|
||
查看所有注册用户列表
|
||
|
||
编辑用户的RSS源地址
|
||
|
||
主题集成
|
||
方法一：自动替换（推荐）
|
||
修改主题的 comments.php 文件，找到显示评论作者的地方，替换为：
|
||
|
||
php
|
||
<?php
|
||
// 原始代码可能是：
|
||
// <cite><?php $comments->author(); ?></cite>
|
||
|
||
// 替换为：
|
||
<cite><?php echo UserCard_Plugin::render($comments); ?></cite>
|
||
方法二：手动调用
|
||
如果主题有特殊的评论结构，可以手动调用：
|
||
|
||
php
|
||
<?php if (class_exists('UserCard_Plugin')): ?>
|
||
<?php echo UserCard_Plugin::render($comments); ?>
|
||
<?php else: ?>
|
||
<?php $comments->author(); ?>
|
||
<?php endif; ?>
|
||
常见主题修改位置
|
||
默认主题：
|
||
|
||
php
|
||
// 文件：usr/themes/default/comments.php
|
||
// 第25行左右：
|
||
<h3 class="comment-author">
|
||
<?php echo UserCard_Plugin::render($comments); ?>
|
||
</h3>
|
||
其他主题：
|
||
通常在评论循环中的作者显示位置，查找类似代码：
|
||
|
||
php
|
||
<?php $comment->author(); ?>
|
||
// 或
|
||
<?php $comments->author(); ?>
|
||
使用方法
|
||
用户侧
|
||
游客用户：显示简单的作者名和链接（如果有）
|
||
|
||
注册用户：
|
||
|
||
默认显示基本信息
|
||
|
||
如果管理员设置了RSS源，会显示近期文章
|
||
|
||
鼠标悬停时显示完整卡片
|
||
|
||
管理员侧
|
||
1. 为用户设置RSS源
|
||
登录后台
|
||
|
||
进入"管理" → "RSS管理"
|
||
|
||
找到需要设置的用户
|
||
|
||
输入正确的RSS源地址
|
||
|
||
点击保存
|
||
|
||
2. 支持的RSS格式
|
||
标准RSS 2.0格式
|
||
|
||
包含 <item> 标签的RSS
|
||
|
||
支持 title、link、pubDate 字段
|
||
|
||
3. 推荐的RSS源
|
||
博客RSS地址（如：https://example.com/feed/）
|
||
|
||
第三方平台RSS（如Medium、知乎专栏等）
|
||
|
||
确保RSS地址可公开访问
|
||
|
||
缓存系统
|
||
缓存目录
|
||
text
|
||
usr/plugins/UserCard/cache/
|
||
├── usercard_rss_[hash1].json
|
||
├── usercard_rss_[hash2].json
|
||
└── ...
|
||
缓存策略
|
||
缓存时间：默认3600秒（1小时）
|
||
|
||
缓存内容：每个RSS源最多保存10篇文章
|
||
|
||
缓存更新：过期后自动重新获取
|
||
|
||
缓存清理：手动删除缓存文件或等待自动过期
|
||
|
||
手动清理缓存
|
||
bash
|
||
# 清空所有缓存
|
||
rm -rf usr/plugins/UserCard/cache/*.json
|
||
|
||
# 或通过PHP
|
||
<?php
|
||
// 在主题或插件中调用
|
||
array_map('unlink', glob("usr/plugins/UserCard/cache/*.json"));
|
||
故障排除
|
||
常见问题
|
||
1. 卡片不显示
|
||
检查插件是否激活
|
||
|
||
检查主题是否正确集成
|
||
|
||
查看浏览器控制台是否有JavaScript错误
|
||
|
||
确认用户有usercard-wrapper类名
|
||
|
||
2. RSS文章不显示
|
||
检查RSS地址是否正确
|
||
|
||
确认RSS源可公开访问
|
||
|
||
检查服务器是否支持file_get_contents
|
||
|
||
查看PHP错误日志
|
||
|
||
3. 样式错乱
|
||
检查CSS是否正常加载
|
||
|
||
确认没有CSS冲突
|
||
|
||
调整卡片宽度设置
|
||
|
||
4. 缓存问题
|
||
确保缓存目录可写
|
||
|
||
检查文件权限
|
||
|
||
清除旧缓存文件
|
||
|
||
调试模式
|
||
在主题的header.php中添加调试信息：
|
||
|
||
php
|
||
<?php if (Typecho_Widget::widget('Widget_Options')->plugin('UserCard')): ?>
|
||
<!-- UserCard Plugin Loaded -->
|
||
<?php endif; ?>
|
||
性能优化
|
||
建议配置
|
||
缓存时间：根据RSS更新频率设置
|
||
|
||
频繁更新：1800秒（30分钟）
|
||
|
||
一般更新：3600秒（1小时）
|
||
|
||
较少更新：7200秒（2小时）
|
||
|
||
显示数量：根据卡片大小调整
|
||
|
||
小卡片：3-5条
|
||
|
||
大卡片：5-10条
|
||
|
||
超时时间：根据网络状况调整
|
||
|
||
国内网络：5-10秒
|
||
|
||
国际网络：10-15秒
|
||
|
||
服务器优化
|
||
开启PHP的allow_url_fopen
|
||
|
||
配置合适的max_execution_time
|
||
|
||
确保有足够的磁盘空间用于缓存
|
||
|
||
高级定制
|
||
自定义样式
|
||
在主题的CSS文件中覆盖默认样式：
|
||
|
||
css
|
||
/* 修改卡片背景 */
|
||
.usercard-popup {
|
||
background: #f8f9fa !important;
|
||
border-color: #dee2e6 !important;
|
||
}
|
||
|
||
/* 修改标题样式 */
|
||
.usercard-header {
|
||
background: linear-gradient(135deg, #6a11cb 0%, #2575fc 100%) !important;
|
||
}
|
||
|
||
/* 调整动画效果 */
|
||
.usercard-popup {
|
||
transition: opacity 0.3s ease !important;
|
||
}
|
||
扩展功能
|
||
创建自定义插件继承功能：
|
||
|
||
php
|
||
class MyUserCard_Plugin extends UserCard_Plugin
|
||
{
|
||
public static function render($comments)
|
||
{
|
||
$html = parent::render($comments);
|
||
// 添加自定义内容
|
||
return $html . '<div class="my-custom-content">自定义内容</div>';
|
||
}
|
||
}
|
||
更新日志
|
||
v3.1.0 (当前版本)
|
||
优化缓存机制，固定获取10条RSS数据
|
||
|
||
前端显示数量可配置
|
||
|
||
改进鼠标交互逻辑
|
||
|
||
修复动态评论加载问题
|
||
|
||
v3.0.0
|
||
重构插件架构
|
||
|
||
添加管理员界面
|
||
|
||
支持用户RSS管理
|
||
|
||
改进卡片样式
|
||
|
||
v2.0.0
|
||
添加RSS支持
|
||
|
||
实现缓存系统
|
||
|
||
优化响应式设计
|
||
|
||
v1.0.0
|
||
基础用户卡片功能
|
||
|
||
基本用户信息显示
|
||
|
||
简单的悬停交互
|
||
|
||
技术支持
|
||
官方资源
|
||
插件主页：https://www.shitoucuo.com
|
||
|
||
GitHub仓库：https://github.com/shitoucuo/UserCard
|
||
|
||
文档Wiki：https://github.com/shitoucuo/UserCard/wiki
|
||
|
||
问题反馈
|
||
GitHub Issues
|
||
|
||
Typecho官方论坛
|
||
|
||
作者博客留言
|
||
|
||
贡献指南
|
||
Fork仓库
|
||
|
||
创建功能分支
|
||
|
||
提交Pull Request
|
||
|
||
遵循代码规范
|
||
|
||
许可证
|
||
本插件基于MIT许可证发布。
|
||
|
||
text
|
||
MIT License
|
||
|
||
Copyright (c) 2023 石头厝
|
||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
of this software and associated documentation files (the "Software"), to deal
|
||
in the Software without restriction, including without limitation the rights
|
||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||
copies of the Software, and to permit persons to whom the Software is
|
||
furnished to do so, subject to the following conditions:
|
||
|
||
The above copyright notice and this permission notice shall be included in all
|
||
copies or substantial portions of the Software.
|
||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||
SOFTWARE.
|
||
致谢
|
||
Typecho开发团队
|
||
|
||
所有贡献者和测试者
|
||
|
||
使用本插件的用户
|
||
|
||
注意：使用本插件前请备份网站数据，建议在测试环境中先进行试用。
|
||
|
||
最后更新：2024年1月
|
||
|
||
版本：3.1.0 |