Box

一个带边框、背景色和布局能力的容器组件。用于创建面板、框架和有组织的区域。

基本用法

Renderable API

import { BoxRenderable, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

const panel = new BoxRenderable(renderer, {
  id: "panel",
  width: 30,
  height: 10,
  backgroundColor: "#333366",
  borderStyle: "double",
  borderColor: "#FFFFFF",
})

renderer.root.add(panel)

Construct API

import { Box, Text, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

renderer.root.add(
  Box(
    {
      width: 30,
      height: 10,
      backgroundColor: "#333366",
      borderStyle: "rounded",
    },
    Text({ content: "Inside the box!" }),
  ),
)

边框样式

// No border
{
  border: false
}

// Simple border (default style)
{
  border: true
}

// Specific border styles
{
  borderStyle: "single"
} // Single line: ┌─┐│└─┘
{
  borderStyle: "double"
} // Double line: ╔═╗║╚═╝
{
  borderStyle: "rounded"
} // Rounded corners: ╭─╮│╰─╯
{
  borderStyle: "heavy"
} // Heavy lines: ┏━┓┃┗━┛

标题

为框边框添加标题和底部标题：

const panel = new BoxRenderable(renderer, {
  id: "settings",
  width: 40,
  height: 15,
  borderStyle: "rounded",
  title: "Settings",
  titleColor: "yellow",
  titleAlignment: "center",
  bottomTitle: "Footer",
  bottomTitleAlignment: "center",
})

标题对齐（顶部和底部标题）

{
  titleAlignment: "left"
} // ┌─ Title ────────┐
{
  titleAlignment: "center"
} // ┌──── Title ─────┐
{
  titleAlignment: "right"
} // ┌────────── Title ┐

{
  bottomTitleAlignment: "left"
} // └─ Title ────────┘
{
  bottomTitleAlignment: "center"
} // └──── Title ─────┘
{
  bottomTitleAlignment: "right"
} // └────────── Title ┘

布局容器

Box 作为子元素的 flex 容器：

const container = Box(
  {
    flexDirection: "column",
    justifyContent: "space-between",
    alignItems: "stretch",
    width: 50,
    height: 20,
    padding: 1,
    gap: 1,
  },
  Text({ content: "Header" }),
  Box({ flexGrow: 1, backgroundColor: "#222" }, Text({ content: "Content area" })),
  Text({ content: "Footer" }),
)

鼠标事件

处理框上的鼠标交互：

const button = new BoxRenderable(renderer, {
  id: "button",
  width: 12,
  height: 3,
  border: true,
  backgroundColor: "#444",
  onMouseDown: () => {
    console.log("Button clicked!")
  },
  onMouseOver: () => {
    button.backgroundColor = "#666"
  },
  onMouseOut: () => {
    button.backgroundColor = "#444"
  },
})

属性

属性	类型	默认值	说明
`width`	`number \| string`	-	宽度（字符数或百分比）
`height`	`number \| string`	-	高度（行数或百分比）
`backgroundColor`	`string \| RGBA`	-	背景填充颜色
`border`	`boolean`	`false`	显示边框
`borderStyle`	`string`	`"single"`	边框样式
`borderColor`	`string \| RGBA`	-	边框颜色
`title`	`string`	-	边框中的标题文本
`titleColor`	`string \| RGBA`	-	标题文本颜色
`titleAlignment`	`string`	`"left"`	标题位置
`bottomTitle`	`string`	-	边框中的底部标题文本
`bottomTitleAlignment`	`string`	`"left"`	底部标题位置
`padding`	`number`	`0`	内部内边距
`gap`	`number \| string`	-	子元素之间的间距
`flexDirection`	`string`	`"column"`	子元素布局方向
`justifyContent`	`string`	`"flex-start"`	主轴对齐
`alignItems`	`string`	`"stretch"`	交叉轴对齐

示例：卡片组件

import { Box, Text, t, bold, fg } from "@opentui/core"

function Card(props: { title: string; description: string }) {
  return Box(
    {
      width: 40,
      borderStyle: "rounded",
      borderColor: "#666",
      padding: 1,
      margin: 1,
    },
    Text({
      content: t`${bold(fg("#00FFFF")(props.title))}`,
    }),
    Text({
      content: props.description,
      fg: "#AAAAAA",
    }),
  )
}

renderer.root.add(
  Box(
    { flexDirection: "row", flexWrap: "wrap" },
    Card({ title: "Feature 1", description: "Description of feature 1" }),
    Card({ title: "Feature 2", description: "Description of feature 2" }),
    Card({ title: "Feature 3", description: "Description of feature 3" }),
  ),
)