后台组件 UI

TextPress 后台内置了一系列通用 UI 组件，方便开发者快速构建一致的用户界面。

TPDialog

通用对话框组件

showToast

轻量级消息提示

Loading

加载状态指示

统一风格

与后台 UI 保持一致

TPDialog 对话框

替代原生对话框

TPDialog 是对浏览器原生 confirm() 和 alert() 的美化替代，支持 Promise，可配合 async/await 使用。

对话框类型

类型	图标	用途
`confirm`	灰色问号	确认操作，需要用户选择
`info`	蓝色信息	普通信息提示
`success`	绿色勾选	操作成功提示
`warning`	黄色警告	警告提示
`error`	红色错误	错误提示

基础用法

确认框 (替代 confirm)

JavaScript

// 基础确认框
const confirmed = await TPDialog.confirm('确定要删除吗？');
if (confirmed) {
    // 用户点击了确定
    await deleteItem();
}

// 带描述的确认框
const confirmed = await TPDialog.confirm('删除文章', '删除后无法恢复，确定要继续吗？');
if (confirmed) {
    // 执行删除
}

提示框 (替代 alert)

JavaScript

// 普通提示
await TPDialog.alert('提示', '请先登录后再操作');

// 成功提示
await TPDialog.success('保存成功');
await TPDialog.success('操作完成', '数据已成功保存到服务器');

// 错误提示
await TPDialog.error('操作失败', '请检查网络连接后重试');

// 警告提示
await TPDialog.warning('警告', '此操作不可逆，请谨慎操作');

高级配置

使用 TPDialog.show() 方法可以完全自定义对话框：

JavaScript

const result = await TPDialog.show({
    type: 'confirm',           // confirm, info, success, warning, error
    title: '安装主题',          // 标题
    content: '确定要安装此主题吗？安装后可在主题管理中启用。',  // 内容（支持 HTML）
    confirmText: '立即安装',    // 确定按钮文字，默认"确定"
    cancelText: '取消',        // 取消按钮文字，默认"取消"
    showCancel: true,          // 是否显示取消按钮，默认 true
    confirmClass: 'success'    // 确定按钮样式：primary(默认), success, danger
});

if (result) {
    // 用户点击了确定
    console.log('开始安装...');
}

配置参数

参数	类型	默认值	说明
`type`	string	'confirm'	对话框类型
`title`	string	'确认操作'	标题文字
`content`	string	''	内容文字，支持 HTML
`confirmText`	string	'确定'	确定按钮文字
`cancelText`	string	'取消'	取消按钮文字
`showCancel`	boolean	true	是否显示取消按钮
`confirmClass`	string	'primary'	确定按钮样式类

快捷方法

方法	参数	返回值	说明
`TPDialog.confirm(title, content?)`	标题, 内容	Promise<boolean>	确认框，返回用户选择
`TPDialog.alert(title, content?)`	标题, 内容	Promise<true>	普通提示框
`TPDialog.success(title, content?)`	标题, 内容	Promise<true>	成功提示框
`TPDialog.error(title, content?)`	标题, 内容	Promise<true>	错误提示框
`TPDialog.warning(title, content?)`	标题, 内容	Promise<true>	警告提示框
`TPDialog.show(options)`	配置对象	Promise<boolean>	自定义对话框

实际应用示例

删除确认

JavaScript

async function deletePost(id) {
    const confirmed = await TPDialog.confirm(
        '删除文章', 
        '删除后无法恢复，确定要删除这篇文章吗？'
    );
    
    if (!confirmed) return;
    
    try {
        const res = await fetch(`/admin/post/delete/${id}`, { method: 'POST' });
        const data = await res.json();
        
        if (data.success) {
            await TPDialog.success('删除成功', '文章已被删除');
            location.reload();
        } else {
            await TPDialog.error('删除失败', data.message || '请稍后重试');
        }
    } catch (e) {
        await TPDialog.error('网络错误', '请检查网络连接');
    }
}

安装确认与结果提示

JavaScript

async function installTheme(downloadUrl, slug) {
    // 安装确认
    const confirmed = await TPDialog.confirm(
        '安装主题', 
        '确定要安装此主题吗？安装后可在主题管理中启用。'
    );
    if (!confirmed) return;
    
    try {
        const res = await fetch('/api/market/install', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ type: 'theme', download_url: downloadUrl, slug })
        });
        const data = await res.json();
        
        if (data.success) {
            // 安装成功，询问是否启用
            const enableNow = await TPDialog.show({
                type: 'success',
                title: '安装成功',
                content: `主题 "${data.name}" 已安装成功，是否立即启用？`,
                confirmText: '立即启用',
                cancelText: '稍后启用',
                showCancel: true,
                confirmClass: 'success'
            });
            
            if (enableNow) {
                await switchTheme(data.slug);
            }
        } else {
            await TPDialog.error('安装失败', data.message);
        }
    } catch (e) {
        await TPDialog.error('安装失败', '网络错误，请稍后重试');
    }
}

showToast 消息提示

轻量级的消息提示，适合简短的操作反馈。

JavaScript

// 成功提示（绿色）
showToast('保存成功');

// 错误提示（红色）
showToast('操作失败', true);

// 自定义持续时间（毫秒）
showToast('正在处理...', false, 5000);

参数说明

参数	类型	默认值	说明
`message`	string	-	提示文字
`isError`	boolean	false	是否为错误提示（红色样式）
`duration`	number	3000	显示时长（毫秒）

最佳实践

使用建议

TPDialog 适合需要用户确认或关注的重要操作，showToast 适合简单的操作反馈。

删除、禁用等危险操作

使用 TPDialog.confirm() 让用户二次确认

操作成功/失败反馈

简单反馈用 showToast()，重要结果用 TPDialog.success/error()

安装后询问启用

使用 TPDialog.show() 自定义按钮文字和样式

配合 async/await

TPDialog 返回 Promise，可以用 await 等待用户操作

媒体上传函数

TextPress 提供了一系列媒体上传辅助函数，方便开发者在主题和插件中处理文件上传。

upload_media() - 通用上传

PHP

// 基础用法
$result = upload_media($_FILES['file']);
if ($result['success']) {
    echo '上传成功: ' . $result['url'];
    // $result['url'] = '/uploads/2025/01/xxx.jpg'
    // $result['path'] = '/var/www/uploads/2025/01/xxx.jpg'
    // $result['filename'] = 'xxx.jpg'
} else {
    echo '上传失败: ' . $result['message'];
}

// 自定义配置
$result = upload_media($_FILES['file'], [
    'allowed_types' => ['image/jpeg', 'image/png'],  // 允许的 MIME 类型
    'allowed_exts' => ['jpg', 'jpeg', 'png'],        // 允许的扩展名
    'max_size' => 5 * 1024 * 1024,                   // 最大 5MB
    'upload_dir' => '/uploads/avatars',              // 自定义目录
    'filename' => 'user_123',                        // 自定义文件名
]);

快捷上传函数

PHP

// 上传图片（默认最大 5MB）
$result = upload_image($_FILES['avatar'], 2);  // 最大 2MB

// 上传文档（PDF、Word、Excel 等，默认最大 20MB）
$result = upload_document($_FILES['doc'], 10);  // 最大 10MB

// 上传压缩包（ZIP、RAR 等，默认最大 50MB）
$result = upload_archive($_FILES['package']);

// 上传任意文件（不限制类型）
$result = upload_file($_FILES['file'], 100, '/uploads/files');

辅助函数

PHP

// 删除媒体文件
delete_media('/uploads/2025/01/xxx.jpg');

// 格式化文件大小
echo format_file_size(1048576);  // 输出: 1 MB

// 检查是否为图片
if (is_image($path)) {
    // 获取图片尺寸
    $size = get_image_size($path);
    echo "宽度: {$size['width']}px, 高度: {$size['height']}px";
}

// 获取上传错误信息
echo get_upload_error_message(UPLOAD_ERR_INI_SIZE);
// 输出: 文件大小超过服务器限制 (upload_max_filesize)

返回值说明

字段	类型	说明
`success`	boolean	是否上传成功
`url`	string	文件 URL（相对路径）
`path`	string	文件绝对路径
`filename`	string	文件名
`size`	int	文件大小（字节）
`mime_type`	string	MIME 类型
`message`	string	提示信息

完整示例

PHP

<?php
// 在插件或主题中处理文件上传
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['image'])) {
    $result = upload_image($_FILES['image'], 5);
    
    if ($result['success']) {
        // 保存到数据库
        $db = \Core\Database::getInstance();
        $stmt = $db->prepare("UPDATE users SET avatar = ? WHERE id = ?");
        $stmt->execute([$result['url'], $_SESSION['user_id']]);
        
        \Core\View::json([
            'success' => true,
            'url' => $result['url'],
            'message' => '头像上传成功'
        ]);
    } else {
        \Core\View::json([
            'success' => false,
            'message' => $result['message']
        ]);
    }
    exit;
}
?>

TextPress 开发者文档

后台组件 UI

TPDialog

showToast

Loading

统一风格

TPDialog 对话框

对话框类型

基础用法

确认框 (替代 confirm)

提示框 (替代 alert)

高级配置

配置参数

快捷方法

实际应用示例

删除确认

安装确认与结果提示

showToast 消息提示

参数说明

最佳实践

删除、禁用等危险操作

操作成功/失败反馈

安装后询问启用

配合 async/await

媒体上传函数

upload_media() - 通用上传

快捷上传函数

辅助函数

返回值说明

完整示例