Extending the DSL

在 ChatGPT 中打开

Kotlin DSL 是可扩展的，允许为自定义组件或第三方库添加 DSL 函数。您可以构建内部使用 DSL 的复合组件。

添加组件到 DSL

为了使任何组件在 DSL 中可用，请在 HasComponents 上创建一个扩展函数，该函数使用 init 辅助函数。

基本 DSL 函数

这是一个简单组件的模式。此示例假设您有一个自定义的 Badge 组件：

import com.webforj.concern.HasComponents
import com.webforj.kotlin.dsl.WebforjDsl
import com.webforj.kotlin.dsl.init
import com.example.component.Badge

fun @WebforjDsl HasComponents.badge(
    block: @WebforjDsl Badge.() -> Unit = {}
): Badge {
    return init(Badge(), block)
}

init 函数完成三件事：

1. 将组件添加到父容器
2. 运行配置块
3. 返回配置好的组件

现在您可以在 DSL 代码中使用该组件：

div {
    badge {
        text = "新"
        variant = Badge.Variant.PRIMARY
    }
}

添加参数

大多数 DSL 函数在配置块之前接受常见参数：

fun @WebforjDsl HasComponents.badge(
    text: String? = null,
    variant: Badge.Variant? = null,
    block: @WebforjDsl Badge.() -> Unit = {}
): Badge {
    val badge = Badge()
    text?.let { badge.text = it }
    variant?.let { badge.variant = it }
    return init(badge, block)
}

用法变得更加简洁：

div {
    badge("新", Badge.Variant.PRIMARY)
    badge("特卖") {
        styles["font-size"] = "12px"
    }
}

创建复合组件

Composite 将多个组件包装成一个可重用的单元。DSL 非常适合定义复合结构。

基本复合

class SearchBox : Composite<Div>() {

    val searchField: TextField
    val searchButton: Button

    init {
        boundComponent.apply {
            styles["display"] = "flex"
            styles["gap"] = "8px"

            searchField = textField(placeholder = "搜索...") {
                styles["flex"] = "1"
            }

            searchButton = button("搜索") {
                theme = ButtonTheme.PRIMARY
            }
        }
    }

    fun onSearch(handler: (String) -> Unit) {
        searchButton.onClick {
            handler(searchField.text)
        }
        searchField.onEnter {
            handler(searchField.text)
        }
    }
}

复合组件公开组件引用以供外部访问，并为常见操作提供便利方法。

添加 DSL 支持

创建一个 DSL 函数，使复合组件可以像内置组件一样使用：

fun @WebforjDsl HasComponents.searchBox(
    block: @WebforjDsl SearchBox.() -> Unit = {}
): SearchBox {
    return init(SearchBox(), block)
}

现在集成自然：

div {
    h1("产品目录")

    searchBox {
        onSearch { query ->
            filterProducts(query)
        }
    }

    // 产品列表...
}

示例：状态指示器

以下是状态指示器复合组件的完整示例：

class StatusIndicator : Composite<Div>() {

    private val dot: Div
    private val label: Span

    var status: Status = Status.INACTIVE
        set(value) {
            field = value
            updateDisplay()
        }

    var text: String = ""
        set(value) {
            field = value
            label.text = value
        }

    init {
        boundComponent.apply {
            styles["display"] = "flex"
            styles["align-items"] = "center"
            styles["gap"] = "8px"

            dot = div {
                styles["width"] = "10px"
                styles["height"] = "10px"
                styles["border-radius"] = "50%"
                styles["background"] = "gray"
            }

            label = span()
        }
        updateDisplay()
    }

    private fun updateDisplay() {
        dot.styles["background"] = when (status) {
            Status.ACTIVE -> "#22c55e"
            Status.WARNING -> "#f59e0b"
            Status.ERROR -> "#ef4444"
            Status.INACTIVE -> "#9ca3af"
        }
    }

    enum class Status { ACTIVE, WARNING, ERROR, INACTIVE }
}

// DSL 函数
fun @WebforjDsl HasComponents.statusIndicator(
    text: String? = null,
    status: StatusIndicator.Status? = null,
    block: @WebforjDsl StatusIndicator.() -> Unit = {}
): StatusIndicator {
    val indicator = StatusIndicator()
    text?.let { indicator.text = it }
    status?.let { indicator.status = it }
    return init(indicator, block)
}

用法：

div {
    statusIndicator("数据库", StatusIndicator.Status.ACTIVE)
    statusIndicator("缓存", StatusIndicator.Status.WARNING)
    statusIndicator("外部 API", StatusIndicator.Status.ERROR)
}