Foliq

Foliq 不是一个只能独立运行的页面 Demo,也没有把技术路线限定为 Web Component。内部工程代号继续沿用 PTD;v2 将产品拆成三个可以独立演进的层次:

• 可嵌入的设计器内核:Schema、单位换算、序列化、数据绑定和组件注册表不依赖 UI 框架。
• 专业 React 编辑器:提供完整的画布工作区、组件目录、属性面板和编辑命令。
• 可演进的完整应用:Vite Web Host 已接通 NestJS 模板服务,提供认证、文件工作台、版本历史、 真实逐页打印预览与服务端 PDF;后续继续扩展长文档分页和外部数据连接器。

当前更准确的描述是:已经形成文档设计、数据校样、版本化保存和确定性 PDF 输出闭环的专业 Web 应用,复杂打印出版能力仍在持续扩展。

• Canvas-first 工作区:工具坞、资源面板、上下文工具栏、属性面板、状态栏。
• 选择、多选、框选、拖动、缩放、旋转、锁定、组合与图层操作。
• 复制、剪切、定位粘贴、Undo/Redo、右键菜单和键盘命令。
• 真实标尺、悬停预览线、可固定和着色的参考线。
• 文本框、直线、矩形、椭圆、星形的画布拖拽绘制,以及 Hand Tool。
• 多页面新增、复制、删除和排序。
• JSON object / object array 导入、嵌套字段树、字段搜索、格式化、组件绑定、记录切换与实时数据校样。
• Host 可通过显式 RenderContext 注入临时运行时数据、locale、timeZone 与确定性的 now,不会默认写回模板。
• 宽屏、标准与紧凑三种响应式工作区布局。
• 文本、表格、图像、编码、图形五类组件目录,并区分可用组件与规划组件。

• 框架无关的 TemplateSchema、canonical Datasource v2、页面配置、序列化、安全数据绑定和组件注册表。
• 原生 DOM 渲染组件:文本、表格、图像、二维码、条码和基础图形。
• NestJS + Prisma + PostgreSQL 多用户模板 API,支持开放 GitHub OAuth、owner 隔离、可选演示数据恢复、不可变版本快照、恢复和乐观并发控制。
• GitHub Actions 构建 Web/Server 镜像并发布到 GHCR;Compose 管理 PostgreSQL、migration、Server 和同源 Web 入口。
• @ptd/export 将模板编译为显式派生页,支持 Page Master、页码、明细表智能分页与续页重复表头。
• Web 提供与设计器同主题的多页打印预览;认证 Server 使用固定 Playwright Chromium 输出保留文字对象的 PDF。

apps/web (React + Vite) ───────────────┐
 ▼
 @ptd/react-designer
 │
 ┌────────────┴────────────┐
 ▼ ▼
 @ptd/components @ptd/core
 │ ▲さんかく
 └─────────────────────────┘
apps/server (NestJS + Prisma + PostgreSQL) ──── @ptd/core
apps/web ───────────┐
 ├── @ptd/export ── @ptd/components ── @ptd/core
apps/server render ─┘

packages/
 core/ 框架无关的数据模型与引擎
 components/ 原生 DOM 渲染组件
 react-designer/ React 专业编辑器
 export/ 确定性派生页编译、分页与输出 DOM renderer
apps/
 web/ 独立设计器 Host
 server/ 模板持久化与版本 API
docker/ Web/Server 镜像与 Nginx 同源代理配置
legacy/ 只读的 Vue 2 版本

更完整的代码边界见 Monorepo 架构规范。

• Node.js 22.12 或更高版本(CI 与 Docker 使用 Node 22)。
• 通过 Corepack 使用仓库声明的 pnpm 11.18.0。

虽然部分 package 的 engines 仍允许 Node 20,完整开发、CI 与容器环境统一使用 Node 22,以减少工具链和 Prisma 运行时差异。

corepack enable
corepack pnpm install
corepack pnpm dev

根 dev 命令会按依赖顺序构建 core、components、export、react-designer,再同时启动 package watch 和 Vite。默认访问地址通常为 http://localhost:5173。

完成 Server 环境和 PostgreSQL migration 配置后,也可以从根目录一次启动完整联调环境:

corepack pnpm dev:all

dev:all 沿用相同的前端依赖预构建顺序,然后并行启动四个 package watcher、Web 和 Server。

Web 的登录与账户检查依赖 Server。复制 apps/server/.env.example 并配置 PostgreSQL/GitHub OAuth 后,可单独启动 API:

corepack pnpm --filter server prisma:migrate:deploy
corepack pnpm --filter server dev

默认服务地址为 http://localhost:3000,健康检查为 GET /healthz。DATABASE_URL 必须指向 PostgreSQL;没有本地文件数据库回退。

更完整的环境、命令和原生依赖排障见 DEVELOPMENT.md。

v2 packages 当前只在本仓库 workspace 中使用,尚未发布到 npm。下面展示真实的受控组件 API,而不是 npm 安装说明:

import { useState } from 'react'
import { Designer, type DesignerHost, type TemplateSchema } from '@ptd/react-designer'
import '@ptd/react-designer/styles.css'
export function TemplateEditor({ initialValue }: { initialValue: TemplateSchema }) {
 const [template, setTemplate] = useState(initialValue)
 const host: DesignerHost = {
 commands: { save: {}, open: {} },
 onCommand: (command, context) => runDocumentCommand(command, context.template),
 }
 return <Designer value={template} onChange={setTemplate} host={host} />
}

DesignerProps 当前只有四项:

样式需要由 Host 显式导入。API 与集成约束见 @ptd/react-designer README。

模板服务提供以下 HTTP 端点:

更新和恢复请求必须携带 expectedVersion。版本过期时返回 409 Conflict,以避免静默覆盖其他写入。请求体和响应语义见 Server README。

TemplateSchema.pages 表示用户手动管理、需要持久化的设计页面。打印预览/PDF 通过 @ptd/export 生成独立 OutputDocument 派生页面;明细表可以续页并重复表头,但不会写回手工页、Dirty 或 Undo/Redo。 v1 已证明结构化表格 vertical slice,完整富文本逐行分页、分组小计和跨页合并单元格仍属后续能力。

当前生产链路交付完整自托管栈:

GitHub Actions → 前后端质量/容器构建 → GHCR Web + Server 镜像
 ↓
 PostgreSQL → migration → Server → Nginx Web/API

服务器不需要 Node.js 或 pnpm:

git clone https://github.com/ROYIANS/foliq-print-template-designer.git
cd foliq-print-template-designer
cp .env.example .env
# 编辑 .env 中所有 CHANGE_ME、公开 origin 和 GitHub OAuth 配置
./deploy.sh

默认访问 http://<server-ip>:8080。PowerShell 7、HTTPS 反向代理、GitHub callback、数据库卷、备份、私有 GHCR、版本固定和回滚说明见 DEPLOYMENT.md。

接下来的主线按依赖顺序推进:

1. 在现有确定性输出主干上实现长文本逐行分页和更完整的 Page Master 编辑体验。
2. 扩展结构化表格的分组、小计、carry-forward 与受控跨页规则。
3. 在已稳定的数据合同上增加 Excel/CSV 本地文件连接器。
4. 设计具备 Secret 隔离和 SSRF 防护的 REST Server 连接器。
5. 增加批量输出/任务队列,并独立评估 Word 版式降级边界。

Excel/XLS/XLSX、CSV、REST、Word、完整长文本分页、复杂表格分页、图表、签名、条件显示、字体管理、 批量打印和多语言属于后续扩展,不应被理解为当前 v1 输出能力。

Vue 2 时代的源码、资源和实现记录保存在 legacy/ 中,不再维护,也不会被 v2 运行时代码引用。

• npm 历史版本:print-template-designer
• v1 的 ptd-designer / ptd-viewer API 与 v2 不兼容。
• v1 曾包含的预览和导出实现不代表 v2 已具备同等功能。

• 作者:ROYIANS
• Email:royians@vidorra.life
• Website:https://vidorra.life

联系二维码

主要参考项目:

• report-designer
• printer-editor
• visual-drag-demo
• vue-email-editor

MIT © ROYIANS

Star History Chart