HTML DSL
所需依赖项:io.ktor:ktor-server-html-builder
代码示例: html
原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✅
HTML DSL 将 kotlinx.html 库集成到了 Ktor 中,允许你使用 HTML 块响应客户端。借助 HTML DSL,你可以在 Kotlin 中编写纯 HTML、将变量插值到视图中,甚至使用模板构建复杂的 HTML 布局。
添加依赖项
HTML DSL 不需要安装,但需要 ktor-server-html-builder 工件。你可以按如下方式将其包含在构建脚本中:
implementation(ktorLibs.server.htmlBuilder)implementation ktorLibs.server.htmlBuilder<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-html-builder-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>发送 HTML 响应
要发送 HTML 响应,请在所需的路由内调用 respondHtml 方法。 以下示例展示了一个 HTML DSL 示例以及发送给客户端的对应 HTML:
import io.ktor.server.application.*
import io.ktor.server.html.*
import io.ktor.http.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.utils.io.*
import kotlinx.html.*
fun Application.module() {
routing {
get("/") {
val name = "Ktor"
call.respondHtml(HttpStatusCode.OK) {
head {
title {
+name
}
}
body {
h1 {
+"Hello from $name!"
}
}
}
}
}
}<html>
<head>
<title>Ktor</title>
</head>
<body>
<h1>Hello from Ktor!</h1>
</body>
</html>以下示例展示了如何响应一个用于从用户处收集凭据信息的 HTML 表单:
get("/login") {
call.respondHtml {
body {
val urlEncoded = FormEncType
.applicationXWwwFormUrlEncoded
form(
action = "/login",
encType = urlEncoded,
method = FormMethod.post
) {
p {
+"Username:"
textInput(name = "username")
}
p {
+"Password:"
passwordInput(name = "password")
}
p {
submitInput() { value = "Login" }
}
}
}
}
}<html>
<body>
<form action="/login" enctype="application/x-www-form-urlencoded" method="post">
<p>Username:<input type="text" name="username"></p>
<p>Password:<input type="password" name="password"></p>
<p><input type="submit" value="Login"></p>
</form>
</body>
</html>有关完整示例,请参阅 auth-form-html-dsl。
要了解有关在服务器端接收表单参数的更多信息,请参阅表单参数。
要了解有关使用 kotlinx.html 生成 HTML 的更多信息,请参阅 kotlinx.html wiki。
发送部分 HTML
除了生成完整的 HTML 文档外,你还可以使用 .respondHtmlPartial() 函数响应 HTML 片段。
当返回不需要完整 <html> 文档的部分标记(例如 HTMX 等库所使用的动态更新)时,HTML 片段非常有用。
import io.ktor.server.application.*
import io.ktor.server.html.*
import io.ktor.http.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.utils.io.*
import kotlinx.html.*
fun Application.module() {
routing {
get("/fragment") {
call.respondHtmlPartial(HttpStatusCode.Created) {
div("fragment") {
span { +"Created!" }
}
}
}
}
}<div class="fragment">
<span>
Created!
</span>
</div>该函数的工作方式与 .respondHtml() 类似,但它仅呈现你在构建器内部定义的内容,而不会添加根 HTML 元素。
模板
除了生成普通 HTML 外,Ktor 还提供了一个可用于构建复杂布局的模板引擎。你可以为 HTML 页面的不同部分创建模板层次结构,例如整个页面的根模板、页面页眉和页脚的子模板等。Ktor 提供了以下用于处理模板的 API:
- 要响应基于指定模板构建的 HTML,请调用 respondHtmlTemplate 方法。
- 要创建模板,你需要实现 Template 接口并重写提供 HTML 的
Template.apply方法。 - 在创建的模板类内部,你可以为不同的内容类型定义占位符:
- Placeholder 用于插入内容。PlaceholderList 可用于插入多次出现的内容(例如列表项)。
- TemplatePlaceholder 可用于插入子模板并创建嵌套布局。
示例
让我们通过示例了解如何使用模板创建层次结构布局。假设我们有以下 HTML:
<body>
<h1>Ktor</h1>
<article>
<h2>Hello from Ktor!</h2>
<p>Kotlin Framework for creating connected systems.</p>
<ul>
<li><b>One</b></li>
<li>Two</li>
</ul>
</article>
</body>我们可以将该页面的布局拆分为两部分:
- 用于页面页眉的根布局模板以及用于文章的子模板。
- 用于文章内容的子模板。
让我们逐步实现这些布局:
调用
respondHtmlTemplate方法并将模板类作为实参传递。在我们的示例中,这是应当实现Template接口的LayoutTemplate类:kotlinget("/") { call.respondHtmlTemplate(LayoutTemplate()) { // ... } }在代码块内部,我们将能够访问模板并指定其属性值。这些值将替换模板类中指定的占位符。我们将在下一步中创建
LayoutTemplate并定义其属性。根布局模板如下所示:
kotlinclass LayoutTemplate: Template<HTML> { val header = Placeholder<FlowContent>() val content = TemplatePlaceholder<ArticleTemplate>() override fun HTML.apply() { body { h1 { insert(header) } insert(ArticleTemplate(), content) } } }该类公开了两个属性:
header属性指定插入到h1标记中的内容。content属性指定文章内容的子模板。
子模板如下所示:
kotlinclass ArticleTemplate : Template<FlowContent> { val articleTitle = Placeholder<FlowContent>() val articleText = Placeholder<FlowContent>() val list = TemplatePlaceholder<ListTemplate>() override fun FlowContent.apply() { article { h2 { insert(articleTitle) } p { insert(articleText) } insert(ListTemplate(), list) } } }该模板公开了
articleTitle、articleText和list属性,它们的值将被插入到article内部。要提供值列表作为模板,请创建以下新类:
kotlinclass ListTemplate : Template<FlowContent> { val item = PlaceholderList<UL, FlowContent>() override fun FlowContent.apply() { if (!item.isEmpty()) { ul { each(item) { li { if (it.first) { b { insert(it) } } else { insert(it) } } } } } } }该模板使用
PlaceholderList类从提供的项目中生成无序列表 (UL)。 它还将第一个项目包裹在<b>元素中以示强调。现在我们准备发送使用指定属性值构建的 HTML:
kotlinget("/") { call.respondHtmlTemplate(LayoutTemplate()) { header { +"Ktor" } content { articleTitle { +"Hello from Ktor!" } articleText { +"Kotlin Framework for creating connected systems." } list { item { +"One" } item { +"Two" } } } } }
你可以在此处找到完整示例:html-templates。
