如何在Kotlin Compose for Web中使用Clarity Design System(CDS)Web组件

1. 配置npm依赖 #

在项目的build.gradle.kts（Kotlin DSL）文件中，给jsMain源集添加CDS的npm依赖：

kotlin {
    sourceSets {
        val jsMain by getting {
            dependencies {
                implementation(npm("@cds/core", "你需要的CDS稳定版本号"))
                implementation(npm("@cds/city", "你需要的CDS稳定版本号"))
            }
        }
    }
}

2. 导入全局样式 #

两种可选方式：

• 如果你使用自定义HTML入口文件，在<head>标签中添加样式引入：

<link rel="stylesheet" href="./node_modules/@cds/core/global.min.css">
<link rel="stylesheet" href="./node_modules/@cds/city/css/bundles/default.min.css">

• 如果你使用Sass预处理全局样式，在全局scss文件顶部添加导入：

@import "@cds/core/global.min";
@import "@cds/city/css/bundles/default.min";

3. 注册CDS组件 #

在Compose渲染逻辑执行之前，导入需要使用的组件对应的注册文件，注册逻辑建议放在项目入口的最顶部：

import kotlin.js.import

fun main() {
    // 按需注册你需要用到的CDS组件
    import("@cds/core/button/register.js")
    import("@cds/core/input/register.js")
    // 其他组件注册以此类推

    // 后续的Compose渲染逻辑
    renderComposable(rootElementId = "root") {
        // 页面内容
    }
}

4. 封装并使用CDS组件 #

Compose for Web支持直接调用自定义Web组件，你可以封装对应的Composable函数方便调用：

import org.jetbrains.compose.web.attributes.AttrsScope
import org.jetbrains.compose.web.dom.TagElement
import org.jetbrains.compose.web.dom.Text
import org.w3c.dom.HTMLElement

// 封装cds-button组件
@Composable
fun CdsButton(
    attrs: AttrsScope<HTMLElement>.() -> Unit = {},
    content: @Composable () -> Unit
) {
    TagElement("cds-button", applyAttrs = attrs, content = content)
}

封装完成后即可直接在Compose代码中使用：

// 基础使用
CdsButton {
    Text("Click me!")
}

// 带属性和事件的使用
CdsButton(
    attrs = {
        attr("status", "success")
        attr("size", "lg")
        onClick { 
            println("按钮被点击")
        }
    }
) {
    Text("大号成功按钮")
}

常见注意事项 #

• 组件必须完成注册后再渲染，否则会出现组件不显示的问题
• CDS组件的所有原生属性都可以通过attr()方法设置，事件绑定可以直接使用Compose的on*系列方法
• 如果需要支持TypeScript类型推导，可以额外添加@types/clarity__core的npm依赖

内容的提问来源于stack exchange，提问作者Endzeit