实用示例

机器翻译

本页由英文原文机器翻译而来，尚未经过母语审校，欢迎在 GitHub 上提出修改。内容如有出入，以英文原文为准。

简短的示例，每个只做一件事。每个示例都是 examples/cookbook/ 中的一个小应用，带有自己的 quantum test 测试：页面上的代码从经过测试的文件导入，显示的结果来自实际运行。

基础

• 第一个页面，以及第二个 — components/ 中的每个文件都是一个页面，有自己的 URL；没有对应文件的 URL 返回 404。
• 变量与表达式 — q:set 保存一个值，花括号用它计算，default 补上缺失的值。
• 循环 — 用 q:loop 遍历列表（带位置）、数字范围和逗号分隔的文本。
• 条件 — q:if、q:elseif 和 q:else，条件是表达式。
• 函数 — 带类型检查参数的 q:function，可以在 q:set 和 HTML 中调用。
• 每个 URL 一个页面 — components/product/[id].q 响应 /product/1、/product/2……；这个路径段是一个变量。
• 读取查询字符串 — query.name 读取地址中的 ?name=；default 处理缺失的值；urlencode 生成链接。
• 可复用的组件 — 一个带 props 和 slot 的组件，从一个永远不会被当作页面提供的 _ 文件夹导入。

界面

• 适应屏幕的布局 — ui:hbox 在宽屏上并排、在窄屏上堆叠，配合 grow、width 和 hide-below。
• 可以就地编辑的表格 — ui:table 的 edit= 把每个单元格变成一个按数据表结构检查的小表单；不需要编写动作。
• 标签页 — ui:tabpanel，页面的每个部分一个 ui:tab。
• 卡片 — 带页眉、正文和页脚的 ui:card，放在 ui:grid 中；或者只有标题的卡片。
• 各种字段 — 用 ui:formitem 加标签的 ui:form：文本、数字、带选项的下拉框、开关、单选按钮和多行字段。
• 终端里的同一个页面 — 一个 ui:* 页面，由 quantum start 提供给浏览器，由 quantum console 在终端中绘制。

测试应用

• 用 quantum test 写第一个测试 — 在 Quantum 本身中测试一个页面及其动作——访问、提交，检查提示消息、数据表和字段错误。
• 用 test:given 准备测试数据 — 用 test:given 把测试需要的行放进它的全新数据库，用 test:as 让用户登录。
• 测试动作拒绝的内容 — 测试字段错误、业务规则和动作的成功——error=、message=、flash= 以及数据表。

文件和邮件

• 开发中的邮件 — 开发时不需要邮件服务器也能从动作发送邮件——host: log 把每封邮件写入日志。
• 当邮件服务器拒绝时 — 即使确认邮件发不出去，也要保留订单——onerror=continue，并告诉访问者。

登录和权限

• 用哈希密码登录 — 用 verifyPassword 将密码与它的 bcrypt 哈希比对，开启会话，并让一个页面只对已登录用户开放。
• 注册并保存密码哈希 — 用 hashPassword 创建账号，数据库从不保存密码本身，每个字段都有规则。
• 只对一个角色开放的页面 — require_role 让页面只对管理员开放：普通成员得到 403，未登录的访问者被带去登录。
• 会重定向的守卫 — 带 q:redirect 的顶层 q:if 保护一个页面及其所有动作：没有会话的提交不会写入任何东西。
• 退出登录 — 一个清空会话并重定向的退出页面；受保护的页面重新关闭。

表单和动作

• 在每个字段旁显示它的错误 — 把规则在动作的 q:param 上写一次；表单读取它们，并在每个字段旁显示被拒绝的原因。
• 被拒绝的表单保留已输入的内容 — 被拒绝后，表单会带着提交的值返回一次，这样没有人需要把一条长消息输入两遍。
• 重定向并说明发生了什么 — 用 q:redirect 和提示消息结束动作；警告用 q:flash；消息在下一个页面上显示一次。
• 一个页面上的多个表单 — 每个表单和按钮都会提交它的动作名；页面没有的动作名返回 400。
• 根据数据表生成表单 — q:action table= 从数据表结构获取参数；没有字段的 ui:form 为每一列画一个字段。
• 编辑一行 — 用 [id].q 为每一行提供一个页面，表单打开时带着这一行的值，保存时应用数据表的规则。
• 删除前先确认 — 一个先提问的页面，通过链接进入，删除则由它的按钮以 POST 发出；不需要 JavaScript。
• 数字和日期 — q:param 上的 type=integer、decimal 和 date：动作得到经过检查的数字和真实的日期，带 min 和 max。
• 从列表中选择 — q:param 上的 enum 为 ui:select 和 ui:radio 提供选项，并拒绝其他任何值；复选框是一个布尔值。

数据和 SQL

• 带参数的查询 — 按 URL 中的值筛选，并绑定为 q:param——这个值永远不会变成 SQL。
• 分页列表 — 一次显示长列表的一页，用 ui:pager 画出指向其他页的链接。
• 边输入边搜索 — 一个在每次输入停顿后刷新结果的字段——搜索由页面自己的查询完成。
• 筛选和排序表格 — 筛选行的链接和给行排序的表头——都在 SQL 中完成，都体现在 URL 里。
• 一起发生的写入 — 一个 q:transaction：扣款、入账和日志记录一起提交，否则一个都不提交。
• 变更历史 — history: true 记录谁修改了哪一行、如何修改；ui:history 在页面上显示它。
• 用迁移添加一列 — 用一个新的迁移文件修改数据表结构；旧的迁移保持原样。
• 读取 CSV 文件 — q:data 把 CSV 文件变成带类型的记录，并筛选和排序——不需要数据库。
• 把 CSV 文件导入数据表 — 在一个事务中插入文件的每一行——任何一行失败都不会留下任何东西。
• 读取 JSON 文件 — 把 JSON 数组作为记录列表，并给每条记录加一个计算字段。
• 一次查询得出汇总 — 在内存中对一个查询的结果执行 SQL——数据库只被询问一次。

AI

• 带来源的回答 — 用 q:knowledge 和 q:llm knowledge= 根据你自己的文档回答问题，并列出来源。
• 当文档不知道答案时 — minRelevance 挡住不相关的文本块；一个都不剩时，不询问模型，页面如实说明。
• 流式输出回答 — 流式的 q:llm 和 ui:stream：页面立即渲染，回答边生成边出现。
• 基于数据库的智能体 — 带只读查询工具的 q:agent：模型选择工具和参数，从不编写 SQL。
• 当模型失败时 — q:llm 上的 onerror：宕机或太慢的模型不会连带页面一起崩溃。
• 用 JSON 回答给消息分类 — responseFormat json：模型的回答是一个对象，你检查并保存它的字段。
• 根据数据表回答 — 一个作为查询的 q:knowledge 来源：你的常见问题数据表中的行，像文档一样被检索。