k-data
在 HTML 模板中用标签声明数据流程(推荐,替代已弃用的
k-query)
概述
k-data 用纯 HTML 标签(<k-data>、<let>、<query> 等)描述「读参数 → 查数据 → 整形 → 暴露变量」,在服务端执行。需要交给模板层使用的结果,在生成变量的 <query> 或 <let> 上添加 export 属性。
语法以 Kooboo kooboo-coding 技能包中 references/Frontend/k-data/ 为准,本文档与其保持一致。
与历史 k-query 单行属性相比,k-data:
- 结构固定,便于 AI 生成与代码审查
- 支持分支、异常、重定向、字段映射
where/test使用 JSON5 条件,而非 SQL 字符串
与模板绑定的分工
| 层级 | 语法 | 用途 |
|---|---|---|
<k-data> 内 | <let>、<query>、<when>… | 准备数据 |
| 模板 DOM | k-content、k-for、k-if、k-attribute | 渲染 UI |
详见 模板绑定语法。
最小可运行示例
下面只完成一件事:查询 article 内容并显示标题。
html
<k-data>
<query
as="articles"
source="content"
resource="article"
action="list"
export
></query>
</k-data>
<ul>
<li k-for="article in articles">
<span k-content="article.title"></span>
</li>
</ul>这段代码形成了最小闭环:
<query>查询数据,并把结果保存为articles。<query>上的export属性将articles暴露给模板。k-for遍历结果,k-content显示标题。
运行前提
站点中需要存在名为 article 的 Content Folder,并包含 title 字段。实际项目请替换为自己的资源名和字段名。
相关主题
| 主题 | 说明 | 文档 |
|---|---|---|
| 字段与过滤 | 使用 select、where 控制查询结果 | query 数据源 |
| 请求参数 | 从 URL、Cookie、Header 等位置读取值 | 标签语法 · let |
| 分页与排序 | 使用 paged、page-number、order-desc | query 数据源 · paged |
| 映射与格式化 | 调整字段结构和展示格式 | 标签语法 · map、内置函数 |
| 条件与异常 | 条件分支、异常处理和重定向 | 条件表达式、标签语法 |
编写约定
- 外部输入用
source+from(如queryString、cookie)。 - 查询用
source+resource+action;分页统一page-number、page-size。 action="paged"的列表在map里用from="结果.list"。- 模板层只使用通过
export属性暴露的变量。 <when>/<else-if>/<else>只能写在<k-data>内;DOM 条件用k-if/k-else-if/k-else。k-attribute的{...}只做变量插值,不做运算;先<let use="add|subtract|...">再绑定。<query>不是 HTML void element,必须写结束标签</query>,不要使用<query ... />。
标签一览
| 标签 | 作用 |
|---|---|
k-data | 数据流程根容器 |
let | 变量、请求读取、函数调用 |
query | 查询 content / commerce / 数据库等 |
map | 数组或对象逐项映射 |
when / else-if / else | k-data 内条件分支 |
try / catch | 异常处理 |
redirect | 重定向 |
export 是 <query> 和 <let> 的布尔属性,用于将其 as 变量暴露给模板层。
属性与用法见 标签语法。
文档导航
| 主题 | 说明 |
|---|---|
| 标签语法 | let、query、map、分支、变量暴露 |
| query 数据源 | content、commerce、sqlite、mysql、culture 等 |
| 内置函数 | dateFormat、jwtDecode、数学与文本 |
| 条件表达式 | JSON5 where / test |
与 KScript API 的关系
| 场景 | 文档 |
|---|---|
| 模板内声明式取数 | 本目录 k-data |
| 脚本里 CRUD、业务逻辑 | k.content、k.DB、k.commerce 等 |