cadau
登录开始使用
产品场景方案文档博客论坛关于
登录开始使用
← 全部文档

视图与布局：能做什么、不能做什么、以后怎么加

读者：要理解「界面长什么样」以及「按设计稿/截图做界面」该怎么走的人。

来源 sdk/appsdk/视图与布局.md

读者：要理解「界面长什么样」以及「按设计稿/截图做界面」该怎么走的人。 关联：界面描述规范 · 手工搭建指南 · 平台插件 SDK

1. 当前视图只有三种

标准渲染器只认：

类型用户看到什么点下去干什么
list表格列表加载/刷新/可选删除；有 upload_id 时可打开/下载附件
form实体登记表单往本地业务库 新建一行（crud.create）
action_form动作参数表单调用自定义动作（通常 handlers.py）

没有第四种。 未知的 type：校验可能失败；即便进了前端，也会被跳过（不显示）。

字段级写法见 界面描述规范。

2. 「布局」有没有？

没有独立的布局模型。 没有：

  • 分栏 / 栅格 / 侧栏 / 页签
  • 主从详情、抽屉、弹层（确认删除由平台统一确认框处理，不是可配置布局）
  • 自定义 CSS、自由 HTML 组件树、路由子页

仅有的「排版」手段：

  1. views[] 数组顺序 → 页面上从上到下叠卡片
  2. 每块内部的字段/列顺序 → fields / columns / actions[].params
  3. 平台统一皮肤 → .wa-* 样式，作者不可改

因此：能搭「上表单 + 下历史」这类工具页；搭不出设计稿上的复杂运营后台视觉。

3. 以后想加新视图 / 布局，怎么处理？

按「改平台契约」走，而不是只改某一个应用的 app.json。

3.1 建议流程

  1. 产品定稿：新视图给用户带来什么（例如「看板」「详情页」「可编辑表格」）。
  2. 扩展契约（同一版本或 bump）：

- backend/internal/workspaceapp/spec.go：ViewDef + ValidateSpec - client/web/src/api.ts：WorkspaceAppViewDef - client/web/src/WorkspaceAppRenderer.tsx：增加渲染分支 - 本文档与 界面描述规范 同步

  1. 可选：应用开发助手的系统提示 / 校验提示同步，避免助手编造未支持类型。
  2. 迁移：旧应用无该字段则行为不变；新字段要有默认值与校验。

3.2 不建议的做法

做法原因
在 app.json 里发明 type: "dashboard" 却不改渲染器前端直接忽略，用户以为坏了
用 action_form 硬塞复杂 UI 语义描述与真实控件脱节，难维护
在 handlers.py 里返回 HTML 当「整页界面」当前标准 UI 只认有限结果字段（如 upload_id），不是自定义页面壳

3.3 复杂界面的正规出口

需要接近设计稿的完整 Web（多页、图表、拖拽、自有组件库）→ 用 平台插件（应用桌面 iframe + 自有前端），不要硬扩工作区轻量应用。

4. 「上传一张图片，按这个图做界面」如何实现？

先分清目标：

你想要的推荐路径
A. 报告/结果页长得像某张图（例如员工画像 HTML 版式）轻量应用：assets/*.html + 组装脚本 + 字段映射；界面入口仍是标准表单
B. 应用操作界面长得像某张设计稿（多区块、复杂交互）平台插件自绘 UI；或等平台新增视图类型后再用声明式
C. 用 AI 根据截图改一改现有表单/列表应用开发助手：把图当作附件说明意图 → 仍只能改成三种视图能表达的结构

4.1 路径 A：按图做「结果版式」（员工画像类）

适合：截图是 报表/档案页，用户填几个参数后生成可预览的 HTML。

  1. 把目标版式做成 assets/xxx.html（可先手工从设计还原，或由设计导出静态 HTML）。
  2. 用 references/field-mapping.json（或组装脚本内逻辑）把取数结果填进模板。
  3. app.json 只提供标准入口：action_form（输入）+ list（历史，可选 upload_id 打开结果）。
  4. 动作实现：handlers.py → 取数 → 组装 → platform.save_upload → 返回 upload_id。

图片在这里的作用：给人/助手当「版式参考」，最终落地的是 HTML 模板，不是把 PNG 当成可运行界面。

详见：取数与流水线、动作与handlers。

4.2 路径 B：按图做「操作台本身」

适合：截图是 完整业务 UI（导航、多面板、复杂控件）。

  1. 用平台插件工程做前端（任意框架）。
  2. 在 Cadau 注册为应用桌面插件。
  3. 需要对话调同一后端时，再配技能 + 联网能力包（见 pluginsdk）。

轻量应用 不能 把上传的 PNG/JPG 直接渲染成可点的业务界面。

4.3 路径 C：给应用开发助手附图

  1. 在应用开发助手对话里粘贴/上传截图，并用自然语言说明：「做成上表单下列表」「去掉删除」等。
  2. 助手只能输出符合当前契约的 app.json（及可选脚本）。
  3. 若截图远超三种视图能力，应明确改走插件，或拆成「标准操作页 + HTML 结果页」（路径 A）。

4.4 决策简图

上传的是「结果页/报表」样张？
  ├─ 是 → 路径 A：HTML 模板 + 取数组装 + 标准表单入口
  └─ 否（操作台/复杂布局）
        ├─ 必须像素级还原 → 路径 B：平台插件
        └─ 可接受标准列表/表单 → 路径 C：助手改 app.json，或手工写三种视图

5. 与界面描述规范的关系

  • 字段怎么写：以 界面描述规范 为准。
  • 整包怎么搭、脚本怎么写：见同目录其余文档。
  • 本文：回答「为什么只有三种」「布局边界」「按图做界面选哪条路」。