Baklib 文档中心
登录 官网

批量创建页面功能配置指南

概述

批量创建页面功能允许模板定义一个专门的界面，让用户能够批量导入/创建页面。这个功能通过在模板的 schema 中配置 batch_create_url 来实现。 使站点在管理端中可以按需提供批量创建页面的功能。

工作流程

系统交互流程

1. 用户在页面管理界面中点击"批量创建"按钮
   ↓
2. 系统获取该页面的模板及其子模板信息
   ↓
3. 如果子模板的 schema 中配置了 batch_create_url，则显示批量创建选项
   ↓
4. 用户点击某个模板的批量创建选项
   ↓
5. 系统生成包含认证信息的 batch_create_url 并在 iframe 中打开
   ↓
6. 用户在 iframe 中进行批量导入操作
   ↓
7. iframe 中的页面通过 API 调用创建页面

配置步骤

1. 在模板 Schema 中添加 batch_create_url

在你的 .liquid 模板文件中，在 {% schema %} 部分添加 batch_create_url 配置：
{% schema %}
  {
    "name": "页面模板名称",
    "description": "页面模板描述",
    "batch_create_url": "https://your-import-service.com/batch_import", // 或者 "/s/batch_import"（模版中静态地址）
    "settings": [
      // ... 其他模板设置
    ]
  }
{% endschema %}

2. batch_create_url 的两种形式

2.1 绝对 URL（推荐用于外部服务）

{
  "batch_create_url": "https://external-service.com/batch_import"
}
绝对 URL 使用完整的 http/https 地址。系统会自动追加以下查询参数： - token: 用户的临时 API token（JWT 格式） - site_id: 当前站点 ID - full_path: 父页面的完整路径 - template_name: 模板名称 - template_style: 模板风格
示例生成的 URL：
https://external-service.com/batch_import?
  token=JWT+eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3NzAyOTY1NTh9...
  &site_id=34
  &full_path=%2F80ec12
  &template_name=page
  &template_style=style

2.2 相对路径 URL（建议页面构建在模版中静态页面中）

{
  "batch_create_url": "/s/batch_import"
}
相对路径会被转换为完整的站点门户 URL。系统会使用站点的门户地址作为基础 URL，并追加相同的查询参数。
示例生成的 URL：
http://site-demo.baklib.localhost:3000/s/batch_import?
  token=JWT+eyJhbGciOiJIUzI1NiJ9...
  &site_id=34
  &full_path=%2Fparent
  &template_name=page
  &template_style=style

3. 完整的模板配置示例

{%
  # 模板的 HTML/Liquid 内容
%}

{% schema %}
  {
    "name": "数据批量导入页面",
    "description": "支持批量创建页面的模板",
    "thumb_url": "images/theme/batch_import_page.png",
    "batch_create_url": "https://api.example.com/pages/batch_import",
    "settings": [
      {
        "id": "title",
        "type": "text",
        "label": "页面标题"
      },
      {
        "id": "description",
        "type": "richtext",
        "label": "页面描述"
      },
      {
        "id": "enable_batch_import",
        "type": "checkbox",
        "label": "启用批量导入",
        "default": true
      }
    ]
  }
{% endschema %}

在批量创建 iframe 中的操作

接收的查询参数

当 iframe 中的页面加载时，会收到以下查询参数：
参数 说明 示例
token JWT 格式的 API 认证 token JWT eyJhbGciOiJIUzI1NiJ9...
site_id 站点的数字 ID 34
full_path 父页面的完整路径（URL 编码） %2F80ec12
template_name 模板名称 page
template_style 模板风格 style

调用 API 创建页面

iframe 中的页面可以通过以下 Baklib API 创建新页面： > baklib api接口文档： https://dev.baklib.cn/api#/paths/sites-site_id–pages/post

最佳实践

1. 选择合适的 URL 类型

  • 外部服务：使用绝对 URL（完整的 http/https 地址）
  • 站点内部：使用相对路径（以 / 开头）

2. 安全考虑

  • 传递给 iframe 的 token 是临时 API token，有过期时间限制
  • 确保你的批量创建服务在安全的 HTTPS 连接上运行
  • 验证 site_id 和 full_path 参数的有效性

3. 用户体验

  • 在模板中明确说明支持批量创建功能
  • 在 batch_create_url 指向的页面中提供清晰的导入说明
  • 实现进度提示和错误处理

4. 模板命名规范

  • template_name: 模板的基础名称（如 page, article）
  • template_style: 模板的风格变体（如 default, dark, compact）

故障排查

问题：批量创建选项不显示

可能原因： - 模板的 schema 中没有配置 batch_create_url - batch_create_url 值为空或 null - 子模板没有正确关联到父模板
解决方案： 1. 检查模板文件中的 schema 部分 2. 确保 batch_create_url 有有效的值 3. 验证模板的 sub_page_templates 配置

问题：iframe 加载失败

可能原因： - URL 解析错误 - 网络不可达 - CORS 跨域问题
解决方案： 1. 检查浏览器控制台的错误信息 2. 验证 URL 是否正确生成 3. 确保批量创建服务正在运行 4. 检查是否配置了适当的 CORS 头

问题：无法创建页面

可能原因： - API token 已过期 - 用户权限不足 - API 参数格式错误
解决方案： 1. 刷新页面重新获取 token 2. 检查用户是否有页面创建权限 3. 验证 API 请求体格式是否正确