07-视图与前端开发
<![CDATA[# 第7章 视图与前端开发
## 7.1 模板语法
Xiuno BBS使用PHP原生模板语法，模板文件为`.htm`格式，通过`_include()`加载。
你没听错，就是PHP原生的模板语法，目的是尽可能让抽象层变得最薄，毕竟多一层封装就会损失性能。
### 7.1.1 基本语法
```php
<?= $variable; ?> // 输出变量
<?php if ($condition): ?> ... <?php endif; ?> // 条件判断
<?php foreach ($list as $item): ?> ... <?php endforeach; ?> // 循环
<?= url('xxx'); ?> // 生成URL
<?= $conf['view_url']; ?> // 视图资源URL
```
### 7.1.2 Hook标记
在模板中预留Hook点:
```html
<!--{hook thread_plugin_body.htm}-->
```
编译时，系统将`<!--{hook xxx}-->`统一转换为`// hook xxx`，然后替换为对应插件的hook文件内容。
### 7.1.3 Template/Slot 机制
```html
<!-- 定义Slot -->
<slot name="thread_actions" />
<!-- 填充Slot（在插件中） -->
<template include="view/htm/thread.htm">
<slot name="thread_actions">
<button>自定义操作</button>
</slot>
</template>
```
## 7.2 HTM Hook文件开发
### 7.2.1 注入UI片段
在模板的特定位置注入HTML代码:
```html
<!-- 文件：hook/index_site_brief_after.htm -->
<div class="card mt-3">
<div class="card-header">
<?= $conf['sitename']; ?> 签到
</div>
<div class="card-body">
<p>今日已有 <strong><?= $sign_count; ?></strong> 人签到</p>
<button class="btn btn-primary" id="sign-btn">签到</button>
</div>
</div>
```
**关键**: HTM hook文件中可以使用PHP代码，因为编译后它就是PHP文件的一部分。
### 7.2.2 注入JavaScript
通过`_js`类hook注入页面交互:
```html
<!-- 文件：hook/thread_js.htm -->
<script>
$('#favorite-btn').on('click', function() {
var tid = <?= $tid; ?>;
$.xpost('<?= url('my-favorite'); ?>', {tid: tid}, function(code, message) {
if (code == 0) {
$('#favorite-btn').text('已收藏');
} else {
$.alert(message);
}
});
});
</script>
```
### 7.2.3 注入CSS
通过header hook注入自定义样式:
```html
<!-- 文件：hook/header_bootstrap_bbs_after.htm -->
<link rel="stylesheet" href="<?= $conf['view_url']; ?>plugin/my_plugin/view/css/custom.css">
```
或直接内联:
```html
<!-- 文件：hook/header_bootstrap_bbs_after.htm -->
<style>
.my-plugin-card { border-left: 3px solid #007bff; }
</style>
```
## 7.3 完整视图页面开发
### 7.3.1 标准页面模板
```php
<?php include _include(APP_PATH.'view/htm/header.inc.htm'); ?>
<div class="row">
<div class="col-lg-8">
<div class="card">
<div class="card-header">
<?= $plugin_name; ?>
</div>
<div class="card-body">
<?php foreach ($datalist as $item): ?>
<div class="media">
<div class="media-body">
<h5><?= $item['title']; ?></h5>
<p><?= $item['content']; ?></p>
</div>
</div>
<?php endforeach; ?>
</div>
</div>
<?= $pagination; ?>
</div>
<div class="col-lg-4">
<?php include _include(APP_PATH.'view/htm/my_sidebar.inc.htm'); ?>
</div>
</div>
<?php include _include(APP_PATH.'view/htm/footer.inc.htm'); ?>
```
### 7.3.2 设置页面模板
```php
<?php include _include(APP_PATH.'view/htm/header.inc.htm'); ?>
<div class="row">
<div class="col-lg-6 offset-lg-3">
<div class="card">
<div class="card-header">
插件设置
</div>
<div class="card-body">
<form action="<?= url('setting-my_plugin'); ?>" method="post" id="setting_form">
<input type="hidden" name="form_hash" value="<?= $form_hash; ?>" />
<div class="form-group">
<label>选项1</label>
<input type="text" class="form-control" name="option1"
value="<?= $config['option1']; ?>" />
</div>
<div class="form-group">
<label>开关选项</label>
<select class="form-control" name="option2">
<option value="1" <?= $config['option2'] ? 'selected' : ''; ?>>开启</option>
<option value="0" <?= !$config['option2'] ? 'selected' : ''; ?>>关闭</option>
</select>
</div>
<button type="submit" class="btn btn-primary">保存设置</button>
</form>
</div>
</div>
</div>
</div>
<?php include _include(APP_PATH.'view/htm/footer.inc.htm'); ?>
```
## 7.4 前端技术栈
### 7.4.1 Bootstrap
Xiuno BBS使用Bootstrap 4作为UI框架，插件应遵循Bootstrap样式:
```html
<!-- 卡片 -->
<div class="card">
<div class="card-header">标题</div>
<div class="card-body">内容</div>
</div>
<!-- 按钮 -->
<button class="btn btn-primary">主要按钮</button>
<button class="btn btn-sm btn-outline-secondary">小按钮</button>
<!-- 表单 -->
<input type="text" class="form-control" />
<select class="form-select"></select>
<!-- 徽章 -->
<span class="badge bg-primary">标签</span>
```
**注意**：Stately主题使用的是Bootstrap 5，这是新范式，插件应遵循Bootstrap 5的class名。
### 7.4.2 HTMX
用于无刷新交互（仅在Aether主题中使用）:
```html
<!-- 点击按钮，POST请求，替换目标内容 -->
<button hx-post="<?= url('my-action'); ?>"
hx-vals='{"tid":"<?= $tid; ?>"}'
hx-target="#result"
hx-swap="innerHTML"
class="btn btn-primary">
操作
</button>
<!-- 表单提交 -->
<form hx-post="<?= url('my-action'); ?>"
hx-target="#result"
hx-swap="innerHTML">
<input type="text" name="content" class="form-control" />
<button type="submit" class="btn btn-primary">提交</button>
</form>
```
### 7.4.3 jQuery
Xiuno BBS内置jQuery，可直接使用:
```javascript
// AJAX POST
$.xpost(url, data, callback);
// AJAX GET
$.xget(url, callback);
// 弹窗提示
$.alert('提示信息');
// 确认对话框
$.confirm('确认操作？', function() {
// 确认后的操作
});
```
而jquery属于历史遗留问题，建议在新插件中少使用。
## 7.5 静态资源管理
### 7.5.1 资源目录
```
my_plugin/
└── static/
├── img/ # 图片
├── css/ # 样式
├── js/ # 脚本
└── index.htm # 防目录浏览（必须）
```
### 7.5.2 资源引用
```html
<!-- CSS -->
<link rel="stylesheet" href="./plugin/my_plugin/static/css/style.css">
<!-- JS -->
<script src="./plugin/my_plugin/static/js/script.js"></script>
<!-- 图片 -->
<img src="./plugin/my_plugin/static/img/icon.png" />
```
> **关键**: 使用`./`相对路径而非`/`绝对路径，以兼容子目录部署。
### 7.5.3 防目录浏览
在静态资源目录下放置`index.htm`:
```html
<html><body>403</body></html>
```
## 7.6 常用Hook点与UI注入位置
包括但不限于：
| Hook点 | 位置 | 典型用途 |
|--------|------|---------|
| `header_nav_user_start.htm` | 导航栏用户区域前 | 添加搜索图标 |
| `index_site_brief_after.htm` | 首页站点简介后 | 添加签到/公告面板 |
| `index_thread_list_before.htm` | 首页帖子列表前 | 添加筛选/排序 |
| `thread_plugin_body.htm` | 帖子详情底部 | 添加收藏/分享按钮 |
| `thread_subject_end.htm` | 帖子标题后 | 添加标签/图章 |
| `thread_username_before.htm` | 帖子用户名前 | 保存原始用户名 |
| `thread_username_after.htm` | 帖子用户名后 | 添加VIP标记 |
| `post_message_after.htm` | 发帖内容后 | 添加付费设置 |
| `thread_js.htm` | 帖子页JS区域 | 注入交互JS |
| `post_js.htm` | 发帖页JS区域 | 注入编辑器JS |
| `footer_js_after.htm` | 页面底部JS后 | 全局JS注入 |
| `my_end.php` | 个人中心路由末尾 | 注册个人中心子页面 |
]]>