PPress 主题开发核心指南

1. 主题目录结构规范

必需文件（一个预览图，一个主题配置信息）:

preview.png

theme.json

 

推荐结构：

theme_name/

├── base.html          # 基础模板

├── blog/              # 博客相关页面

│   ├── index.html    # 首页

│   ├── article.html  # 文章页

│   ├── category.html # 分类页

│   ├── tag.html      # 标签页

│   ├── search.html   # 搜索页

│   ├── password.html # 密码保护页

│   └── edit.html     # 文章编辑页

├── components/        # 可复用组件

│   ├── comments.html # 评论组件

│   ├── pagination.html # 分页组件

│   └── flash.html    # 消息提示组件

├── custom/           # 自定义页面模板

2. theme.json 配置说明

{

    "name": "主题名称",

    "description": "主题描述",

    "version": "版本号",

    "author": "作者",

    "website": "主题主页",

    "settings": {

        // 主题可配置项,以 default 主题为例:

        "qq": "xxxxxx",        // QQ联系方式

        "wx": "weixin",          // 微信号

        "email": "xxx@qq.com",   // 邮箱

        "github_url": "",        // GitHub链接

        "gitee_url": ""         // Gitee链接

    },

    "article_fields": {

        // 文章自定义字段,以 default 主题为例:

        "thumbnail": {

            "name": "缩略图",

            "type": "image",

            "description": "文章缩略图"

        },

        "subtitle": {

            "name": "副标题",

            "type": "text",

            "description": "文章副标题"

        }

    }

}

3. 模板继承规范

base.html 必需 block:

{% block title %}     # 页面标题

{% block head %}      # 头部资源

{% block meta %}      # SEO meta信息

{% block content %}   # 主要内容

{% block scripts %}   # 底部脚本

4. 常用模板变量

全局变量:

site_config:

 site_config.get_config('site_name')      # 网站名称

 site_config.get_config('site_url')       # 网站URL

 site_config.get_config('site_logo')      # 网站Logo

 site_config.get_config('icp_number')     # ICP备案号

 site_config.get_config('footer_text')    # 底部文本

用户相关:

current_user:

 current_user.is_authenticated  # 是否登录

 current_user.id               # 用户ID

 current_user.username        # 用户名

 current_user.nickname        # 昵称

 current_user.avatar         # 头像URL

 current_user.role          # 用户角色

文章相关:

article:

 article.title              # 标题

 article.content           # 内容(HTML)

 article.summary          # 摘要

 article.created_at       # 创建时间

 article.view_count      # 浏览量

 article.allow_comment   # 是否允许评论

 article.status         # 文章状态

 article.category      # 所属分类

 article.tags         # 标签列表

 article.author      # 作者

 article.fields     # 自定义字段

评论相关:

comment:

 comment.content    # 评论内容

 comment.user      # 评论用户

 comment.created_at # 评论时间

 comment.parent    # 父评论

 comment.replies   # 子评论列表

 主题相关:

 theme:

  theme.settings           # 主题设置

  theme.article_fields    # 文章字段定义

 

 文章字段调用示例:

 ```html

 <! 使用 get_field 方法获取字段值 >

 {{ article.get_field('thumbnail', '/static/images/default.jpg') }}

 {{ article.get_field('subtitle', '') }}

 

 <! 遍历所有字段 >

 {% for key, value in article.fields.items() %}

     <div class="field{{ key }}">{{ value }}</div>

 {% endfor %}

 ```

5. 常用函数和过滤器

URL生成:

{{ url_for('blog.index') }}                    # 首页

{{ url_for('blog.article', id=article.id) }}   # 文章页

{{ url_for('static', filename='css/style.css') }} # 静态资源

时间格式化:

{{ time|datetime }}     # 完整日期时间

{{ time|date }}        # 仅日期

{{ time|time }}        # 仅时间

{{ time|timeago }}     # 相对时间

文本处理:

{{ text|striptags }}   # 去除HTML标签

{{ text|truncate(200) }} # 截取指定长度

{{ text|safe }}        # 不转义HTML

6. 组件开发规范

评论组件:

 支持嵌套回复

 支持游客评论

 支持评论分页

 支持实时预览

 评论组件实现示例(default主题):

 ```html

 <! 评论表单 >

 <form action="{{ url_for('blog.add_comment', article_id=article.id) }}" method="post">

     <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">

     <input type="hidden" name="parent_id" id="parentCommentId">

     <input type="hidden" name="reply_to_id" id="replyToCommentId">

     <! 评论内容输入框 >

     <textarea name="content" required></textarea>

     <! 游客信息(可选) >

     {% if not current_user.is_authenticated and comment_config.allow_guest %}

         <input type="text" name="guest_name" required placeholder="昵称">

         <input type="email" name="guest_email" required placeholder="邮箱">

     {% endif %}

 </form>

 ```

分页组件:

 支持上一页/下一页

 显示当前页/总页数

 支持自定义链接生成

消息提示:

 支持多种类型(success/error/warning)

 自动消失

 可自定义样式

7. 主题设置页面开发

 使用 theme.json 定义配置项

 settings.html 实现配置界面

 支持实时预览

 配置项分类管理

 设置页面实现示例(default主题):

 ```html

 <div class="spacey8">

     <! 联系方式设置 >

     <div class="bgwhite roundedlg shadowsm p6">

         <h3 class="textlg fontmedium">联系方式</h3>

         <div class="spacey4">

             <input type="text" name="qq" value="{{ settings.qq }}">

             <input type="text" name="wx" value="{{ settings.wx }}">

             <input type="email" name="email" value="{{ settings.email }}">

         </div>

     </div>

     <! 社交链接设置 >

     <div class="bgwhite roundedlg shadowsm p6">

         <h3 class="textlg fontmedium">社交链接</h3>

         <div class="spacey4">

             <input type="url" name="github_url" value="{{ settings.github_url }}">

             <input type="url" name="gitee_url" value="{{ settings.gitee_url }}">

         </div>

     </div>

 </div>

 ```

8. 移动端适配

 使用响应式设计

 断点设置:

  sm: 640px

  md: 768px

  lg: 1024px

  xl: 1280px

 导航菜单适配

 图片自适应

9. 性能优化

 静态资源合并压缩

 图片懒加载

 评论异步加载

 合理使用缓存

 减少HTTP请求

10. 安全注意事项

 所有用户输入必须转义

 富文本内容使用 |safe 过滤

 CSRF 防护

 XSS 防护

 文件上传限制

11. SEO优化

 合理的标题结构

 Meta描述和关键词

 语义化HTML标签

 图片ALT属性

 面包屑导航

12. 主题开发最佳实践

1. 代码组织

 模块化开发

 组件复用

 统一命名规范

 注释完善

2. 用户体验

 页面过渡动画

 加载状态提示

 错误信息友好

 操作反馈及时

3. 主题配置

 提供足够自定义选项

 配置项说明清晰

 默认值合理

 实时预览效果

4. 文档支持

 安装说明

 配置文档

 使用示例

 常见问题

5. URL生成和链接处理

------------------

1. 文章链接生成

```html

<!-- 基础文章链接 -->

{{ url_for('blog.article', id=article.id) }}

<!-- 带分类的文章链接 -->

{{ url_for('blog.article', id=article.id, category=article.category.slug) }}

<!-- 自定义URL结构的文章链接 -->

{{ ArticleUrlGenerator.generate(article.id, article.category_id, article.created_at) }}

<!-- 密码保护的文章链接 -->

{{ url_for('blog.article', id=article.id) }}?password={{ password }}

```

2. 分类链接生成

```html

<!-- 基础分类链接 -->

{{ url_for('blog.category', id=category.id) }}

<!-- 使用别名的分类链接 -->

{{ url_for('blog.category', id=category.slug if category.use_slug else category.id) }}

<!-- 带父分类的链接 -->

{{ url_for('blog.category', id=parent.slug + '/' + category.slug) }}

```

3. 标签链接生成

```html

<!-- 基础标签链接 -->

{{ url_for('blog.tag', tag_id=tag.id) }}

<!-- 使用别名的标签链接 -->

{{ url_for('blog.tag', tag_id_or_slug=tag.slug if tag.use_slug else tag.id) }}

```

4. 分页链接生成

```html

<!-- 基础分页链接 -->

{{ url_for(endpoint, page=page) }}

<!-- 带参数的分页链接 -->

{{ url_for(endpoint, page=page, **kwargs) }}

<!-- 分类下的分页 -->

{{ url_for('blog.category', id=category.id, page=page) }}

<!-- 标签下的分页 -->

{{ url_for('blog.tag', tag_id=tag.id, page=page) }}

<!-- 搜索结果分页 -->

{{ url_for('blog.search', q=query, page=page, **filters) }}

```

5. 分页组件实现

```html

{% if pages.pages > 1 %}

    <div class="pagination">

        <!-- 上一页 -->

        {% if pages.has_prev %}

            <a href="{{ url_for(endpoint, page=pages.prev_num, **kwargs) }}"

               class="prev">上一页</a>

        {% endif %}

       

        <!-- 页码 -->

        {% for page in pages.iter_pages() %}

            {% if page %}

                <a href="{{ url_for(endpoint, page=page, **kwargs) }}"

                   class="{% if page == pages.page %}active{% endif %}">

                   {{ page }}

                </a>

            {% else %}

                <span class="ellipsis">...</span>

            {% endif %}

        {% endfor %}

       

        <!-- 下一页 -->

        {% if pages.has_next %}

            <a href="{{ url_for(endpoint, page=pages.next_num, **kwargs) }}"

               class="next">下一页</a>

        {% endif %}

       

        <!-- 页码信息 -->

        <span class="info">

            第 {{ pages.page }}/{{ pages.pages }} 页

            共 {{ pages.total }} 条

        </span>

    </div>

{% endif %}

```

6. 自定义页面链接

```html

<!-- 基础页面链接 -->

{{ url_for(page.route) }}

<!-- 带参数的页面链接 -->

{{ url_for(page.route, **page.params) }}

<!-- 评论分页链接 -->

{{ url_for(page.route) }}?page={{ page }}#comments

```

7. 用户相关链接

```html

<!-- 用户主页 -->

{{ url_for('user.profile') }}

<!-- 用户文章列表 -->

{{ url_for('user.my_articles') }}

<!-- 作者页面 -->

{{ url_for('user.author', id=user.id) }}

<!-- 编辑资料 -->

{{ url_for('user.edit_profile') }}

```

8. 静态资源链接

```html

<!-- CSS文件 -->

{{ url_for('static', filename='theme_name/css/style.css') }}

<!-- JavaScript文件 -->

{{ url_for('static', filename='theme_name/js/script.js') }}

<!-- 图片文件 -->

{{ url_for('static', filename='theme_name/images/logo.png') }}

<!-- 主题资源 -->

{{ url_for('static', filename=theme_name + '/assets/file.ext') }}

```

注意事项:

1. 所有的 URL 生成都应该使用 url_for() 函数

2. 分类和标签的链接要考虑是否启用了别名(slug)

3. 分页链接要传递当前的所有查询参数

4. 静态资源链接要包含主题名称前缀

5. 密码保护的文章链接要通过查询参数传递密码