# @vention/machine-ui 中文文档

规范地址：https://npmcn.com/package/%40vention/machine-ui/

版本：6\.7\.2
npm 元数据更新时间：2026-11-02T19:44:34.563Z
中文译文更新时间：2026-11-02T20:14:12.969Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40vention/machine-ui
原文对照：https://npmcn.com/package/%40vention/machine-ui/?lang=original
项目主页：https://github.com/VentionCo/machine-cloud#readme
源码仓库：https://github.com/VentionCo/machine-cloud

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，987 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^17\.0\.2 \|\| ^19\.3\.0，react-dom ^17\.0\.2 \|\| ^19\.3\.0，@mui/material ^5\.16\.7
- 首次发布：2025-10-22T23:42:31.645Z
- 最新版本发布：2026-11-02T19:44:34.406Z
- 已发布版本数：276（近 12 个月 262 个）

## 中文简介

Machine UI是Vention用于构建应用程序和人机界面（hmi）的组件库。这是同一个库，Vention内部使用它来构建我们自己的应用程序，现在您可以为您的Venti构建自定义应用程序

## 安装

```sh
npm install @vention/machine-ui
```

也可以使用：`pnpm add @vention/machine-ui`、`yarn add @vention/machine-ui`、`bun add @vention/machine-ui`

## README

# 机界面

Machine UI是Vention用于构建应用程序和人机界面（hmi）的组件库。这与Vention内部用来构建我们自己的应用程序的库相同，现在您可以为您的Vention机器构建自定义应用程序。

每个组件的props和它们的类型都在包的类型声明中，您的编辑器可以使用这些声明 `tsc` 阅读。在那里寻找道具；这个自述文件只涵盖了默认值、行为和类型无法显示的组合。

## 🚀安装

通过npm安装机器UI：

```bash
npm install @vention/machine-ui
```

有关最新版本和发行说明，请访问 [NPM包页面](https://www.npmjs.com/package/@vention/machine-ui).

## 设置

机器UI基于MUI v5构建。应用程序需要对等依赖 `react` 和 `react-dom` 17岁, `@mui/material` 5、加 `@emotion/react` 和 `@emotion/styled`，这是MUI所需要的。 `@tabler/icons-react`， `tss-react` 和 `react-draggable` 跟包裹一起来。

在MUI中包装应用程序 `ThemeProvider` 两个主题之一：

-   `machineUiTheme`：桌面主题。它设置了调色板，间距大小(`theme.spacing(n)` 读取 `[0, 4, 8, 12, 16, 24, 28, 32, 40, 48, 56, 64, 80, 96, 128]` Px)和版式变体。
-   `machineUiHmiTheme`：触摸HMI主题。它是 `machineUiTheme` 更粗的图标笔画（1.5px而不是1.01px）。调色板，间距和排版是相同的，所以触摸大小来自每个组件的 `size` prop，而不是来自主题（参见组件）。

这两个主题都添加了可以传递给ui的字体变体 `Typography`： `heading36Bold`， `heading24SemiBold`， `heading24Medium`， `heading18SemiBold`， `heading16SemiBold`， `paragraph18Medium`， `paragraph18Regular`， `paragraph16Medium`， `paragraph16Regular`， `paragraph14Regular`， `code16Reg`， `code14Reg`， `code12Reg`， `uiText18SemiBold`， `uiText18Medium`， `uiText18Regular`， `uiText14SemiBold`， `uiText14Medium`， `uiText14Regular`， `uiText12SemiBold`， `uiText12Medium`， `uiText12Regular`， `uiTableNumbers14Reg`， `uiTableNumbers12Reg`，以及hmi `hmiText20Regular`， `hmiText20SemiBold`， `hmiText22Regular`， `hmiText22Medium`， `hmiText22SemiBold`， `hmiText28SemiBold`， `hmiText32SemiBold`.

`COLORS` 保存原始调色板： `COLORS.slate`， `COLORS.blue`， `COLORS.cyan`， `COLORS.green`， `COLORS.amber` 和 `COLORS.red`，每个键由阴影(`50`， `100` 来 `900`， `950`)，例如 `COLORS.slate[800]`。在组件接受颜色字符串的地方使用它，比如 `VentionStatusDot`的 `color`.

从包中导入任何东西都会应用它的全局样式(`box-sizing: border-box` 在每个元素上)，所以没有 `CssBaseline` 主题使用 `Inter` 和 `Roboto Mono` 字体，应用程序自己加载，例如从谷歌fonts in `index.html`：

```html
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=Roboto+Mono&display=swap" rel="stylesheet" />
```

```tsx
import { ThemeProvider, Typography } from "@mui/material"
import { COLORS, VentionButton, VentionStatusIndicator, machineUiHmiTheme } from "@vention/machine-ui"

export function App() {
  return (
    <ThemeProvider theme={machineUiHmiTheme}>
      <div style={{ backgroundColor: COLORS.slate[50], padding: 24 }}>
        <Typography variant="hmiText28SemiBold">Cell 1</Typography>
        <VentionStatusIndicator label="Running" dotColor={COLORS.green[500]} size="xx-large" />
        <VentionButton size="xx-large" variant="filled-brand" onClick={() => console.log("start")}>
          Start cycle
        </VentionButton>
      </div>
    </ThemeProvider>
  )
}
```

## 组件

每个组件都是一个命名的导出 `@vention/machine-ui`。大多数组件都需要一个 `size` 支撑;HMI尺寸为 `x-large` 和 `xx-large`.

按钮，文本输入，选择和组合框在每个尺寸共享一个高度： `x-small` 16 px, `small` 24像素, `medium` 32像素, `large` 40像素, `x-large` 56 px, `xx-large` 80 px。触摸目标应该至少是44px，所以在触摸HMI使用 `x-large` 或者 `xx-large`。在 `xx-large`，输入和选择标签切换到 `hmiText20*`； 值文本和按钮标签保持其常规排版。

构建在MUI组件上的组件（注意“构建在MUI上”） `X`)也接受组件的props，所以标准的props，比如 `onClick`， `value`， `checked` 和 `onChange` 就像他们在MUI做的那样。

### 行动

-   `VentionButton`：标准按钮。 `size` 默认为 `"small"` （24px），太小不适合触摸，所以使用 `size="x-large"` 或者 `"xx-large"` 在触摸屏上。 `variant` 默认为 `"filled-brand"`。标签是 `children`,否则 `labelText`，当两者都缺失时，它会显示“Button”。 `type` 默认为 `"button"`，所以算了吧 `type="submit"` 提交表单。建立在MUI之上 `Button`.
-   `VentionIconButton`：一个只显示一个图标的方形按钮，传递为 `children`。它需要相同的 `variant` 和 `size` 作为 `VentionButton`，用相同的 `"small"` 违约。建立在MUI之上 `IconButton`.
-   `VentionDropdownButton`：打开其子菜单的按钮。通过一项 `VentionMenu` 包装 `VentionMenu.Item` 元素 `children`； 该按钮按原样呈现子按钮，因此裸项不会显示在菜单上。
-   `VentionLink`：内嵌文本链接。 `external` 默认为true，并显示一个外部链接图标，所以不需要 `external={false}` 用于应用内链接。没有 `labelText` 上面写着“按钮”。

### 输入

-   `VentionTextInput`：基于MUI的文本字段 `TextField`。使用 `state` （`"error"`， `"warning"`， `"success"`， `"disabled"`)而不是 `disabled` 和 `error`. `leftItemText` 和 `rightItemText` 显示字段内的固定文本，如单位，和 `maxCharacters` 显示字符数。
-   `VentionSuggestionsInput`:一个 `VentionTextInput` 当用户输入时，它会显示一个建议列表。要么通过 `value` (控制)或 `defaultValue`不是两者都有。
-   `VentionSelect`：下拉选择。 `onChange` 接收事件，因此读取 `event.target.value`。每一项 `menuItems` 是一个 `VentionSelectMenuItem` 或者一个 `VentionSelectDivider` （`{ type: "divider" }`）. 与 `isMultiple`， `value` 是一个数组。建立在MUI之上 `Select`.
-   `VentionSelectSkeleton`的加载占位符 `VentionSelect`，也可用作 `VentionSelect.Skeleton`.
-   `VentionCombobox`：一个可搜索的单选项下拉菜单。 `groups` 由每个选项的 `group`.
-   `VentionTagsInput`：收集文本标签列表的字段。
-   `VentionCheckbox`：一个带有可选标签的复选框，基于MUI构建 `FormControlLabel`,所以 `checked` 和 `onChange` 在那里工作。它的大小是 `checkboxSize`.
-   `VentionRadio`：一个单选按钮，用于MUI内部 `RadioGroup`。它的大小是 `radioSize`。建立在MUI之上 `Radio`.
-   `VentionRadioTile`：一个带有单选按钮的大可选择瓷砖，用于MUI的内部 `RadioGroup`，适合触摸选择。建立在MUI之上 `FormControlLabel`.
-   `VentionSwitch`：开/关开关。 `checked` 是字符串(`"on"`， `"off"`， `"mixed"` 或者 `"loading"`)，而不是布尔值，并且 `onChange` 接收 `"on"` 或者 `"off"`.
-   `VentionSlider`：基于MUI的范围滑块 `Slider`. `largeThumb` 把手更大，便于触摸。
-   `VentionCounter`显示数字的小药丸，如待处理项目的计数。
-   `VentionStepper`：值的两边各有减号和加号按钮。 `value` 显示如下。把 `onClick` 和 `disabled` 对于每个按钮 `minusButtonProps` 和 `plusButtonProps`.
-   `VentionInputGroupLabel`：放在一组输入内容旁边的标签。
-   `VentionUploadFile`：上载文件列表中的一行，显示其状态。集 `state` 来 `"indeterminate"` 同时上传。
-   `VentionDropZone`：放置或挑选文件的区域。 `onFilesSelect(files)` 返回一个错误消息数组，当每个文件都有效时为空。

### 反馈

-   `VentionAlert`：带有可选动作的警告框。按钮或链接在设置文本时显示，因此将每个文本与其单击处理程序配对，例如 `primaryButtonText` 与 `onPrimaryButtonClick`。使用 `size="xx-large"` 触摸式人机界面。
-   `VentionBanner`表示机器或页面状态的全宽彩色条。
-   `VentionCallout`：带有可选动作的内联高亮注释。
-   `VentionProgressBar`：水平进度条。 `value` 取值范围是0 ~ 100。
-   `VentionSpinner`：循环进度指示器。与 `type="progress"` 它显示了 `value`，从0到100。
-   `VentionSkeleton`加载占位符。 `variant` （`"text"`， `"rounded"` 或者 `"circular"`)决定它需要哪些其他的道具。
-   `VentionStatusDot`一个小的彩色点。 `dotColor` 颜色和 `VentionBadge`： `"red"`， `"blue"`， `"green"`， `"yellow"` 或者 `"slate"`． 年长的 `color`，它接受任何CSS颜色，是不赞成的。
-   `VentionStatusIndicator`：带有文本标签的状态点，如机器状态。使用 `size="xx-large"` 触摸式人机界面。
-   `VentionBadge`小标签。将颜色与文本标签配对，因为在车间里，单独使用颜色很难辨认。
-   `VentionTooltip`悬停或聚焦时的工具提示，基于MUI `Tooltip`. `placement` 默认为 `"top-end"`。鼠标悬停在触摸屏上是不存在的，所以不要把操作员需要的信息只放在工具提示中。

### 覆盖

-   `VentionModal`：带有标题、正文和最多两个按钮的对话框。 `type` 设置图标。 `backDropClickClosable` 默认为true。 `width` 覆盖宽度 `modalSize` 集。集 `isTouchDevice` 触摸hmi更大的填充，图标，文本和按钮。
-   `VentionModalBase`：用于自定义内容的空模态框架。集 `isTouchDevice` 触摸式人机界面。
-   `VentionModalBanner`放置在样式顶部的彩色横幅。
-   `VentionDrawer`：一个可以从屏幕边缘滑动的面板，基于MUI `Drawer`。当 `onDrawerHandleClick` 设置时，抽屉保持安装状态，并显示一个调用它进行切换的手柄。
-   `VentionPopover`有箭头的浮动牌，指向一个元素或位置。将它与 `anchorElement` (一个 `HTMLElement`)或 `pos2D` （`{ top, left }` 在px)。 `buttons` 最多三个人 `VentionButton` 道具的对象。
-   `VentionMenu`：一个菜单列表，当用户在其外部单击时关闭。 `showMenu` 和 `closeMenuOnClick` 默认为true。填满 `VentionMenu.Item` （`subMenuItems` 创建一个嵌套菜单)， `VentionMenu.Header` 和 `VentionMenu.Divider`.
-   `VentionPositionedComponent`：放置它。 `children` 在停留在视窗内的固定位置。要么通过 `anchorRect` (一个 `DOMRect`，例如从 `getBoundingClientRect()`)或 `position` （`{ top, left }`)，而不是两者兼而有之。

### 导航和布局

-   `VentionTabs`一行选项卡。 `value` 是所选选项卡的索引，和 `onChange(event, index)` 接收新索引。
-   `VentionSteps`指导程序的垂直的步骤表。使用 `size="xx-large"` 触控式人机界面； `"small"` 总是显示点。
-   `VentionSidebarItem`：侧边栏中的配置文件条目。
-   `VentionTreeItem`：树的一行，嵌套 `VentionTreeItem` 的孩子。
-   `VentionDraggable`：用户可以在屏幕上拖动的浮动面板。 `tabLocation` 在那一边显示一个拖拽手柄；没有它，整个面板就会拖动。

### 身份

-   `VentionAvatar`圆形的用户头像或首字母。
-   `VentionPersonCard`：一个有名字和描述线的头像。
-   `VentionPersonCardSkeleton`的加载占位符 `VentionPersonCard`，也可用作 `VentionPersonCard.Skeleton`.
-   `VentionIcon`：来自“Vention”图标集的图标。 `type` 图标名称是否为 `"player-play"` 或者 `"status-warning-hmi"`. `size` 大小为px，默认值为24。图标的笔触跟随主题，所以它们在下面更粗 `machineUiHmiTheme`。对于其他图标， `@tabler/icons-react` 与包一起安装。

一个小的触摸面板，使用以下几种：

```tsx
import { useState } from "react"
import { VentionModal, VentionSelect, VentionSwitch } from "@vention/machine-ui"

export function RecipePanel() {
  const [recipe, setRecipe] = useState<string>("small-box")
  const [vacuum, setVacuum] = useState<"on" | "off">("off")
  const [pendingRecipe, setPendingRecipe] = useState<string | null>(null)

  return (
    <>
      <VentionSelect
        size="xx-large"
        variant="outlined"
        labelText="Recipe"
        value={recipe}
        onChange={event => setPendingRecipe(String(event.target.value))}
        menuItems={[
          { value: "small-box", displayText: "Small box" },
          { value: "large-box", displayText: "Large box" },
          { type: "divider" },
          { value: "custom", displayText: "Custom", isDisabled: true },
        ]}
      />
      <VentionSwitch size="xx-large" labelText="Vacuum" checked={vacuum} onChange={setVacuum} />
      <VentionModal
        isOpen={pendingRecipe !== null}
        onClose={() => setPendingRecipe(null)}
        isTouchDevice
        type="warning"
        titleText="Change recipe?"
        body="The current cycle will stop."
        primaryButton={{
          text: "Change",
          onClick: () => {
            if (pendingRecipe !== null) setRecipe(pendingRecipe)
            setPendingRecipe(null)
          },
        }}
        secondaryButton={{ text: "Cancel", onClick: () => setPendingRecipe(null) }}
      />
    </>
  )
}
```

## 故事书

故事书是视觉上的参考：它呈现了每一个组件的每一个变体和大小，与交互控制，加上设计指南的颜色，排版和人机界面。

**[https://assets.vention.com/machine-ui-storybook/](https://assets.vention.com/machine-ui-storybook/index.html?path=/docs/guides-introduction--documentation)**

## 📋版本控制策略

从1.0.0版本开始，机器UI遵循严格的语义版本控制：

-   **主要版本** (例如,1. x。X→2；x)：破坏对组件契约、api或行为的更改
-   **小版本** (例如,1.1。X→1.2。x)：向后兼容的新特性
-   **补丁版本** （例如，1.1.1→1.1.2）：Bug修复和内部改进

任何破坏性的更改，无论多么小，都需要一个主要的版本碰撞。这确保您可以自信地升级补丁和次要版本，而不会出现意外的破坏性更改。

## 🏭构建hmi

机器UI组件在工业HMI应用中工作得非常好。有关构建针对工业环境优化的触摸屏界面的指南，请参阅我们的文档：

-   触摸目标大小和间距
-   远距离可读性
-   色彩对比要求
-   简化了手套操作的交互

## 推荐功能️

-   **反应**UI框架
-   **打印稿**：型式安全
-   **材质- ui （MUI v5）**：基本组件库
-   **TSS**：造型解决方案

## 📄许可证

此库可用于Vention机器和应用程序。

## 常见问题

### @vention/machine-ui 是什么？

Machine UI是Vention用于构建应用程序和人机界面（hmi）的组件库。这是同一个库，Vention内部使用它来构建我们自己的应用程序，现在您可以为您的Venti构建自定义应用程序

### 如何安装 @vention/machine-ui？

在项目目录运行 npm install @vention/machine-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.2 \|\| ^19\.3\.0）、react-dom（^17\.0\.2 \|\| ^19\.3\.0）、@mui/material（^5\.16\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @vention/machine-ui 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @vention/machine-ui 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @vention/machine-ui 可以商用吗？

@vention/machine-ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @vention/machine-ui 还在维护吗？

最新版本 6\.7\.2 发布于 2026/11/03（今天）；至今共发布 276 个版本，其中过去 12 个月发布了 262 个；首次发布于 2025/10/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。