# ldesign-ui

**Repository Path**: ldesign-v1/ldesign-ui

## Basic Information

- **Project Name**: ldesign-ui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/tool-ui

`@ldesign/tool-ui` 是 LDesign 内部工具的 Vue 3 基础 UI 包，提供统一壳层、类型安全的前后端桥接能力，以及面向命令面板、表单、日志、数据展示和覆盖层的组件集合。

## 文档入口

- [QUICKSTART.md](./QUICKSTART.md)：最快上手路径
- [COMPONENTS.md](./COMPONENTS.md)：组件与桥接 API 参考
- [`.workspace-ui-runtime`](./.workspace-ui-runtime)：本地展示站运行时

## 包含能力

- 壳层与启动：`createUI`、`ToolShell`、分组导航、路由搜索、主题控制
- 布局组件：`ToolPage`、`ToolSection`、`ToolPanel`、`ToolGrid`、`ToolCard`
- 展示组件：`ToolHero`、`ToolStat`、`ToolNotice`、`ToolBadge`、`ToolDescriptions`、`ToolTimeline`、`ToolSparkline`
- 表单组件：`ToolInput`、`ToolTextarea`、`ToolSelect`、`ToolCheckbox`、`ToolRadio`、`ToolSwitch`、`ToolSlider`
- 数据与执行视图：`ToolTable`、`ToolChart`、`ToolConsole`、`ToolLogViewer`、`ToolPagination`、`ToolTree`、`ToolTerminal`
- 交互与覆盖层：`ToolDialog`、`ToolDrawer`、`ToolTabs`、`ToolCollapse`、`ToolAccordion`、`ToolToast`
- 桥接能力：`defineUIBridge`、`createUIBridgeClient`、`toolCommandBridge`、服务端挂载辅助函数

## 本地预览

```bash
pnpm run preview:dev
```

相关命令：

- `pnpm run preview:build`
- `pnpm run preview:check`

当前展示页包括：

- `Home`：壳层结构与视觉方向
- `Component Library`：完整组件库交互示例
- `Playground`：布局、密度、模糊和强调参数调节

## 快速开始

```ts
import { defineComponent, h, ref } from 'vue'
import { Home } from 'lucide-vue-next'
import {
  ToolButton,
  ToolDescriptions,
  ToolGrid,
  ToolPage,
  ToolPanel,
  ToolTerminal,
  ToolTimeline,
  createUI,
  toolCommandBridge,
} from '@ldesign/tool-ui'

const OverviewPage = defineComponent({
  name: 'OverviewPage',
  setup() {
    const command = ref('pnpm -s test -- --run')

    return () =>
      h(ToolPage, {
        eyebrow: 'Workspace',
        title: '发布控制台',
        description: '把状态卡片、元信息、日志和操作按钮放进同一套壳层里。',
      }, {
        actions: () => [
          h(ToolButton, { variant: 'secondary' }, () => '刷新'),
          h(ToolButton, () => '发布'),
        ],
        default: () => [
          h(ToolGrid, { columns: 2, min: 320 }, () => [
            h(ToolPanel, { title: '发布元信息' }, {
              default: () =>
                h(ToolDescriptions, {
                  columns: 2,
                  items: [
                    { label: 'Region', value: 'ap-southeast-1', copyable: true },
                    { label: 'Commit', value: 'c1a4d02', copyable: true },
                    { label: 'Artifact', value: 'release-surface.tgz', span: 2 },
                  ],
                }),
            }),
            h(ToolPanel, { title: '流水线时间线' }, {
              default: () =>
                h(ToolTimeline, {
                  items: [
                    { title: '构建排队', time: '09:41', tone: 'accent' },
                    { title: '产物上传', time: '09:44', tone: 'success' },
                    { title: '缓存预热中', time: '09:46', tone: 'warning' },
                  ],
                }),
            }),
            h(ToolPanel, { title: '命令终端', padding: 'none' }, {
              default: () =>
                h(ToolTerminal, {
                  modelValue: command.value,
                  bridgeId: 'tool-command',
                  cwd: '/workspace/app',
                  'onUpdate:modelValue': (value: string) => {
                    command.value = value
                  },
                }),
            }),
          ]),
        ],
      })
  },
})

createUI({
  shell: {
    title: 'Workspace Studio',
    subtitle: '内部工具统一操作界面',
    accentColor: '#c56f34',
    railBadge: 'Console',
    navigationLabel: '工作台',
    navigationPlaceholder: '搜索页面或模块',
    statusItems: [
      { label: 'ENV', value: 'DEV', tone: 'accent' },
      { label: 'Region', value: 'CN' },
    ],
  },
  routes: [
    {
      path: '/',
      component: OverviewPage,
      meta: {
        title: '概览',
        description: '壳层概览与发布控制',
        group: '核心',
        iconComponent: Home,
      },
    },
  ],
  backend: {
    defaultBridgeId: 'tool-command',
    bridges: [toolCommandBridge],
  },
})
```

`meta.icon` 适合短文本标记，`meta.iconComponent` 适合传入 Lucide 之类的 Vue 图标组件。

## 命令终端桥接

`ToolTerminal` 支持两种接入方式：

- 直接传入 `runner`
- 使用内置的 `toolCommandBridge`

前端侧：

```ts
import { ToolTerminal, toolCommandBridge } from '@ldesign/tool-ui'

// 在 createUI({ backend: { bridges: [toolCommandBridge] } }) 中注册 toolCommandBridge
// 再在 ToolTerminal 上通过 bridgeId="tool-command" 使用它。
```

服务端侧：

```ts
import { HttpServer } from '@ldesign/kit/network'
import { mountToolCommandBridgeToKitServer } from '@ldesign/tool-ui/server'

const server = new HttpServer({
  port: 3001,
  cors: true,
})

mountToolCommandBridgeToKitServer(server, {
  basePath: '/api/ui',
})

server.start()
```

该桥接暴露三个方法：

- `start`：启动命令会话
- `poll`：轮询新的 stdout / stderr 输出
- `stop`：停止当前命令

## 不通过 `createUI` 时注入样式

如果只复用组件而不使用 `createUI` 启动壳层，需要手动注入基础样式：

```ts
import { ensureToolUIStyles } from '@ldesign/tool-ui'

ensureToolUIStyles()
```

## 主要导出

- 应用与壳层：`createUI`、`createToolHost`、`composeUIToolModules`、`ToolShell`
- 桥接：`defineUIBridge`、`defineUIBridgeMethod`、`createUIBridgeClient`、`toolCommandBridge`
- 服务端：`mountUIBridgeToKitServer`、`mountToolCommandBridgeToKitServer`
- 组件：`src/components/index.ts` 中的全部导出

更详细的组件分类、关键 props 和示例见 [COMPONENTS.md](./COMPONENTS.md)。