---
url: https://ooui-react.pages.dev/guide/usage.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 使用方式

## 安装


```sh [npm]
npm install ooui-react
```

```sh [yarn]
yarn add ooui-react
```

```sh [pnpm]
pnpm add ooui-react
```

```sh [bun]
bun add ooui-react
```

```sh [deno]
deno add npm:ooui-react
```

需 React 版本 ≥ 18。

## 运行环境

- **面向浏览器运行，不支持服务端渲染（SSR）**：浮层组件（`Popup`、`Dropdown` 一类菜单、工具栏弹出面板）在 render 期解析 portal 容器并 `createPortal`，服务端没有 `document` 时直接抛错。用 Next.js 一类同构框架时，把这些组件挡在服务端渲染树之外，或仅在客户端挂载后再渲染。
- **同时提供 ESM 与 CJS 两份产物，二者是独立模块实例**：Node 进程内混用 `import` 与 `require` 加载时，语言消息注册表与 `OOUIProvider` context 互不共享；浏览器打包场景不受影响。

在非 MediaWiki 站点使用时，样式需自行引入 OOUI 的主题 CSS 与 Codex 设计令牌表（oojs-ui 0.54 起令牌表须一并引入）。主题 CSS 二选一：wikimediaui 为当前默认，apex 为遗留主题（两主题下部分状态的观感不同，本组件库输出对两者均有效）：

```js
import "@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.css";
// 主题二选一：
import "oojs-ui/dist/oojs-ui-wikimediaui.css";
import "oojs-ui/dist/oojs-ui-apex.css";
```

OOUI 主题的尺寸以 MediaWiki 的正文基准字号 14px 为准，宿主页面应保持一致。

:::tip
本站导航栏提供「示例主题」切换器，可在 wikimediaui 与 apex 下预览全部实时示例；组件库本身不自带样式，切到哪个主题即还原哪个主题下的观感。
:::

## 在 MediaWiki 站点使用

本组件库开发的初衷就是用于 MediaWiki 站点的用户小工具。如果对产物体积较为敏感，建议[使用 Preact 兼容层](#preact-兼容)代替完整的 React。

使用示例可见[我的萌娘百科工具仓库](https://github.com/BearBin1215/MoegirlPedia)：

- [`src/gadgets/AdvancedSearch`](https://github.com/BearBin1215/MoegirlPedia/tree/master/src/gadgets/AdvancedSearch)
- [`src/gadgets/DynamicRecentChanges`](https://github.com/BearBin1215/MoegirlPedia/tree/master/src/gadgets/DynamicRecentChanges)
- [`src/gadgets/FileInspector`](https://github.com/BearBin1215/MoegirlPedia/tree/master/src/gadgets/FileInspector)


### 声明依赖
MediaWiki 站点的 OOUI 样式由其内置的 `oojs-ui` 资源模块提供，运行时通过 `mw.loader.using` 或小工具的 ResourceLoader 定义里引入：
```ts
mw.loader.using([
  "oojs-ui", // 加载 OOUI 基础样式
  "oojs-ui.styles.icons-media", // 加载 OOUI 对应图标组的 CSS
]);
```
其中图标组的组名见[图标索引](https://ooui-react.pages.dev/components/icon/index.md#%E5%85%A8%E9%83%A8%E5%9B%BE%E6%A0%87)里的分组。
### 挂载
建议渲染到 `div` 或 `DocumentFragment` 元素，然后插到锚点前后：

**index.tsx**

```tsx
import React from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

$(async () => {
  await mw.loader.using(["oojs-ui"]);
  const fragment = document.createDocumentFragment();
  createRoot(fragment).render(<App />);
  // 例：添加到最近更改列表前
  document.querySelector(".mw-changeslist")!.before(fragment);
});
```


**App.tsx**

```tsx
import { Button } from "ooui-react";

function App() {
  return <Button onClick={() => alert("Hello ooui-react!")}>点我</Button>;
}

export default App;
```


## Preact 兼容

本库可在 Preact 兼容层（`preact/compat`）下运行，映射方法参考[官方指南](https://preactjs.com/guide/getting-started/#aliasing-react-to-preact)。

- 版本门槛 Preact ≥ 10.18，10.x 与 11.x 均兼容。
- `react-dom/client` 须映射到 `preact/compat/client`，缺失时命令式 API（confirm / alert / prompt）会缺失 `createRoot` 而报错。

## 与 AI 协作

本文档站已开启 `llms` 支持，除每页标题下方的复制 Markdown 等入口外，同步发布两份面向 LLM 的纯文本文件：

- [llms.txt](https://ooui-react.pages.dev/llms.txt)：索引文件，包含文档站各页面的说明和链接
  ```
  https://ooui-react.pages.dev/llms.txt
  ```
- [llms-full.txt](https://ooui-react.pages.dev/llms-full.txt)：合并了本文档站的全部中文内容
  ```
  https://ooui-react.pages.dev/llms-full.txt
  ```

英文站内容对应 `/en/llms.txt` 与 `/en/llms-full.txt`。引用单页时，在页面地址后追加 `.md` 也可获得该页的纯 Markdown 版本。

可按需将上述链接复制给你的 agent。



---
url: https://ooui-react.pages.dev/guide/ooui.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# OOUI 对照

ooui-react 按 OOUI 的交互语义与 DOM 结构重新实现，样式直接复用原版主题 CSS，但 API 是地道的 React 形态。

无论你熟悉 OOUI、想照着原有的使用经验写新脚本，还是要重写旧的复杂脚本，本页都给出两套 API 的对应关系：先看概念映射，再按原版类名找到对应组件，最后核对能力舍弃与行为差异。

## 概念映射

原版的命令式 API 在本工程统一改写为声明式 props，规则详见[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)：

| 原版                                              | 本工程                                                                                                                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue` / `setDisabled` / `setPage` 等 setter | `value` / `defaultValue` / `onChange` 等受控 props                                                                                                                     |
| `WindowManager.openWindow` / `closeWindow`      | Dialog 家族只有必填 `open` prop，关闭意图经 `onEscape` 等回调报出，见[弹窗必须受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%BC%B9%E7%AA%97%E5%BF%85%E9%A1%BB%E5%8F%97%E6%8E%A7) |
| `updateState` / `choose` / `toggle` 等事件         | `onChange` / `onChoose` / `onOpenChange` 等回调 props                                                                                                                  |
| `OO.ui.msg` 全局与 `OO.ui.deferMsg`                | `OOUIProvider` 的 `messages` 配置与 `useMessage`，见[全局配置](https://ooui-react.pages.dev/guide/configuration.md)                                                           |
| `OO.ui.isMobile()`（始终返回 `false` 的桩函数）           | `OOUIProvider` 的 `isMobile` 配置                                                                                                                                      |
| `OO.ui.HtmlSnippet`（不转义包装类）                     | 直接写 `ReactNode`；字符串默认转义，要原样输出 HTML 只能自行使用 `dangerouslySetInnerHTML`，并自行承担风险                                                                                         |
| `OO.ui.Theme` 运行时对象（`getElementClasses` 等钩子）    | 无。类名由组件按 wikimediaui 语义直接输出，主题样式由站点 CSS 提供；apex 等第三方主题下会多出少量状态类（如选项选中态的 progressive 着色），属已知偏差                                                                       |
| `ToolFactory` / `ToolGroupToolFactory` 等工厂注册    | 声明式数据：工具栏传 `tools` 数组、内嵌工具组直接给 React 元素，见[工具栏](https://ooui-react.pages.dev/components/toolbar/index.md)                                                            |



## 组件寻址与类映射

组件名 = 原版类名去掉 `Widget` 后缀（`ButtonWidget` → `Button`、`TextInputWidget` → `TextInput`）。有几个组件名去掉后缀后不成立，保留原样：`SearchWidget`、`HiddenInputWidget`、`SelectFileInputWidget`、`ButtonMenuSelectWidget`。

原版里一些类不对应独立组件，处理方式如下：

| 原版类                                                                                                                     | 处理方式                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `OO.ui.WindowManager`                                                                                                   | 各 Dialog 组件自持开合（受控 `open`），弹窗内容隔离与层叠随组件内置；命令式 `confirm` / `alert` / `prompt` 不需要管理器                             |
| `OO.ui.ActionWidget` / `ActionSet` / `OO.ui.Error`                                                                      | 内联进 `ProcessDialog`：动作数组、modes 过滤与错误面板，见[过程弹窗](https://ooui-react.pages.dev/components/process-dialog/index.md) |
| `OO.ui.Process`                                                                                                         | `onAction` 异步回调编排，多步 `.next()` 链改写为一个 async 函数                                                                  |
| `OO.ui.OutlineControlsWidget`                                                                                           | 内联进 `BookletLayout` 的大纲面板，见[手册布局](https://ooui-react.pages.dev/components/booklet-layout/index.md)              |
| `OO.ui.SelectWidget`                                                                                                    | [`Select`](https://ooui-react.pages.dev/components/select/index.md)                                             |
| `OO.ui.PopupTagMultiselectWidget`（原版已废弃）                                                                                | 不提供，用 [MenuTagMultiselect](https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md)               |
| `OO.ui` 宿主环境全局工具（`bind` / `infuse` / `getUserLanguages` / `generateElementId` / `debounce` / `Keys` / `MouseButtons` 等） | 不映射：React 自带的能力、`useId` 与 es-toolkit 已覆盖对应场景                                                                    |



## 能力舍弃清单

以下原版能力本工程有意不做，按原版 API 名检索：

| 原版能力                                                     | 替代做法                                                                                                                                   |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `TabOption` 的 `href` 链接                                  | 不支持（原版仅 PHP 端在用），需要链接页签自行组合实现，见[页签选择](https://ooui-react.pages.dev/components/tab-select/index.md)                                     |
| `MultilineTextInputWidget` 的 `allowLinebreaks` / `enter` | 始终允许换行；禁止换行由调用方清洗输入值，见[多行输入框](https://ooui-react.pages.dev/components/multiline-text-input/index.md)                                   |
| `TagMultiselectWidget` 的 `config.input` / `inputWidget`  | 输入框内置，不可替换                                                                                                                             |
| `LabelWidget` 的 `config.input`                           | 有 id 的字段用 `htmlFor`，其余统一由 FieldLayout 关联，见[标签](https://ooui-react.pages.dev/components/label/index.md)                                 |
| `ActionSet.static.specialFlags` 子类扩展                     | 特殊动作固定为 `safe` / `primary`，经 `flags` 声明即可                                                                                              |
| `FieldLayout` 的 `align='inline'` 自动降级                    | 不做降级校验，传入 `inline` 前保证字段根元素为内联形态                                                                                                       |
| 纯标签选项（Tab / Radio / CheckboxMultioption）的 `flags`        | `flags` 只在带图标槽位的选项形态开放，见[选择与选项](https://ooui-react.pages.dev/guide/options.md)                                                         |
| `OO.ui.isSafeUrl` 自动净化                                   | 组件不改写 `href` / `action`；来源不可信的 URL 用导出的 `sanitizeUrl` 自行净化（安全责任在调用方与后端），见[按钮](https://ooui-react.pages.dev/components/button/index.md) |

## 行为差异速查

以下是使用行为会与原版**不同**、且不调整就会出错或与预期相反的差异，按组件速查。各组件页有对应细节：

| 组件                                    | 差异                                                                                 | 详见                                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Message`                             | 关闭按钮只回调 `onClose`、不自行隐藏——漏接回调，消息就关不掉                                               | [消息](https://ooui-react.pages.dev/components/message/index.md)                                                    |
| `Dialog`（裸用）                          | 无内置标题槽位，须自行渲染标题并传 `aria-labelledby`，漏传即无名弹窗                                        | [对话框](https://ooui-react.pages.dev/components/dialog/index.md)                                                    |
| `Dialog` 家族                           | 始终受控：只有必填 `open`，没有 `defaultOpen`                                                  | [受控与非受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%BC%B9%E7%AA%97%E5%BF%85%E9%A1%BB%E5%8F%97%E6%8E%A7) |
| `confirm` / `alert` / `prompt`        | 原版已有窗口打开时第二层调用静默失效；本工程层叠显示、逐个可交互                                                   | [命令式弹窗](https://ooui-react.pages.dev/components/imperative-dialogs/index.md)                                      |
| `prompt`                              | `textInput.value` 只作初始值，弹窗存活期间不可从外部修改                                              | [命令式弹窗](https://ooui-react.pages.dev/components/imperative-dialogs/index.md)                                      |
| `Toolbar` 工具                          | 可见文本与 tooltip 从单个 `title` 拆为 `label` + `title`（`narrowConfig.title` 的值应改传 `label`） | [工具栏](https://ooui-react.pages.dev/components/toolbar/index.md)                                                   |
| `Toolbar`                             | 弹出工具不要放进 List / Menu 组内：浮层锚点随面板收起失效，在本工程里会错位到视口左上角                                 | [工具栏](https://ooui-react.pages.dev/components/toolbar/index.md)                                                   |
| `TagMultiselect`                      | 标签标识改为标量 `value`，对象数据改走 `data` 字段按值反查                                              | [标签输入](https://ooui-react.pages.dev/components/tag-multiselect/index.md)                                          |
| `Dropdown` / `ButtonMenuSelectWidget` | 展开态按空格直接选定高亮项（原版空格不被菜单消费、只经按键模拟关闭菜单）                                               | [下拉选择](https://ooui-react.pages.dev/components/dropdown/index.md)                                                 |
| `Popup`                               | 滚动引起裁剪变化时会重新判定翻转方向（原版冻结到下次打开），滚动过程中浮层可能跳动                                          | [浮层](https://ooui-react.pages.dev/components/popup/index.md)                                                      |

## 命令式弹窗

`confirm` / `alert` / `prompt` 是独立函数，从任意事件回调里 `await` 即可，弹窗自动继承所在 `OOUIProvider` 的配置（文案、`isMobile`、`dir` 及应用自有 Provider）。与原版共用单例管理器不同，本工程重复调用会层叠显示；返回值与运行时语义见[命令式弹窗](https://ooui-react.pages.dev/components/imperative-dialogs/index.md)，配置继承见[全局配置](https://ooui-react.pages.dev/guide/configuration.md#%E5%91%BD%E4%BB%A4%E5%BC%8F%E5%BC%B9%E7%AA%97)。

## 多语言

`en` 为内建默认基线，另提供 222 种语言包（`ooui-react/locales/<代码>`）按需引入；MediaWiki 站点可直接把 `mw.msg` 接进 `messages` 跟随站点语言。语言清单与接入方式见[文案与国际化](https://ooui-react.pages.dev/guide/configuration.md#%E6%96%87%E6%A1%88%E4%B8%8E%E5%9B%BD%E9%99%85%E5%8C%96)。

## 完整差异清单

本页只列影响使用的差异。与原版的全部差异（含实现层取舍与论证）见仓库的 [`dev-docs/DEVIATIONS.md`](https://github.com/BearBin1215/ooui-react/blob/main/dev-docs/DEVIATIONS.md)。



---
url: https://ooui-react.pages.dev/guide/basics.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 通用属性

本页是各组件页的公共前提，说明所有组件共有的属性规则与写入位置。组件特有的属性见对应组件页。

## 属性透传

组件把本库未声明的属性原样透传到渲染出的根元素，`className`、`id`、`style`、`data-*`、`aria-*`、`onClick` 等可以直接写：

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button onClick={() => console.log("clicked")} data-role="demo">点我</Button>
      <Button className="my-button" style={{ fontSize: 20 }}>
        自定义类与样式
      </Button>
    </div>
  );
}

export default App;
```

- 如果组件本身会往根元素固定写入同名属性，透传会失效，例如绝大多数组件的 `aria-disabled` 由 `disabled` 参数计算，手动指定无效。
- 原生 `defaultValue` / `defaultChecked` 不随透传写入 DOM。

## ref 与内部元素

`ref` 指向根元素。要拿到内部元素或往内部元素传入属性，走组件提供的通道：

| 通道                             | 指向 / 作用                                   | 提供通道的组件                                                                                                                                 |
| ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`                     | 内部 `<input>` / `<textarea>`               | 输入框系（`TextInput`、`NumberInput`、`MultilineTextInput`、`ComboBoxInput`、`SearchInput`、`CheckboxInput`）与 `SelectFileInputWidget` 的文件 `input` |
| `inputProps`                   | 内部输入元素的属性                                 | `TextInput`、`NumberInput`、`ComboBoxInput`                                                                                               |
| `buttonProps`                  | 内部按钮的属性                                   | `SelectFileInputWidget`（选择按钮）、`CopyTextLayout`（复制按钮）                                                                                    |
| `textInputProps`               | 文本框的属性                                    | `CopyTextLayout`                                                                                                                        |
| `menuProps`                    | 菜单的属性                                     | `ButtonMenuSelectWidget`                                                                                                                |
| `iconProps` / `indicatorProps` | 图标 / 指示器元素的属性                             | `Button`、`TextInput`                                                                                                                    |
| `anchorRef` / `anchorProps`    | 内部可聚焦的 `<a>`（Button 系的根是 `<span>`，聚焦需经过它） | `Button`                                                                                                                                |

## 通用属性

| 属性          | 说明                                         | 类型                   | 默认值     |
| ----------- | ------------------------------------------ | -------------------- | ------- |
| `disabled`  | 是否禁用                                       | `boolean`            | `false` |
| `flags`     | 附加标志，可选值见组件页                               | `string \| string[]` | —       |
| `className` | 追加到根元素，与组件自身的类链合并                          | `string`             | —       |
| `id`        | 根元素 id                                     | `string`             | —       |
| `title`     | 提示文本；标签视觉隐藏时以标签文本兜底                        | `string`             | —       |
| `accessKey` | 快捷键，写入元素并在 `title` 末尾附 `[键]`               | `string`             | —       |
| `tabIndex`  | Tab 序；传 `null` 表示完全不可聚焦（不输出 `tabindex` 属性） | `number \| null`     | `0`     |
| 其余          | `aria-*`、`data-*`、`style`、各类事件             | 原生属性                 | —       |

含标签的组件（`Button`、`TextInput` 等）另有 `label`（标签文本）与 `invisibleLabel`（视觉隐藏但保留可访问名称），语义见下方说明。

几点说明：

- **`disabled` 输出 `aria-disabled` 而非原生 `disabled`**：禁用后元素仍可被聚焦与朗读，原生 `disabled` 只写在真实的表单控件上。
- **部分布局容器的 `disabled` 另有语义**：
  - `FieldLayout` 只作用于字段本身；`FieldsetLayout` 走原生 `<fieldset disabled>`，会连带禁用整组内的控件；
  - 纯布局容器（`PanelLayout`、`StackLayout` 等）没有 `disabled`。
- **`title` 与 `accessKey` 的写入位置因组件而异**：多数写在根元素上，`Button` 系写在内部锚点，输入框系写在内部 `<input>` 上。要给 `title` 配 `aria-*` 时先看组件页的写入位置说明。
- **`title` 的标签兜底随标签变化重算**：标签视觉隐藏且未显式给 `title` 时以标签文本兜底；本工程每次渲染按当前 `label` / `invisibleLabel` 重算该兜底，后续改标签会联动更新。{/* deviations: dev-resolve-title-rerender */}
- **`label` 接受任意可渲染的 ReactNode**：`0` 等可渲染节点按有标签处理，布尔值按无标签处理。{/* deviations: dev-label-reactnode */}
- **`tabIndex={null}` 会移除 `tabindex` 属性**：元素完全不可聚焦，编程聚焦也不生效——区别于 `-1` 的不进 Tab 序但仍可编程聚焦。{/* deviations: dev-tabindex-null */}
- **`flags` 不是每个组件都有**：各组件按其形态接受不同的标志（如 `Button` 的 `primary` / `progressive`、`Icon` 的色彩变体），具体见组件页。

## 键盘与无障碍

键盘操作、焦点管理与 `aria` 属性与原版 OOUI 一致，具体按键见各组件页。



---
url: https://ooui-react.pages.dev/guide/controlled.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 受控与非受控

多数组件的“当前值”可以由你持有（受控），也可以交给组件自己维护（非受控）。

## 受控通道

| 通道  | 属性                                        | 用于                                                                     |
| --- | ----------------------------------------- | ---------------------------------------------------------------------- |
| 值   | `value` / `defaultValue` / `onChange`     | 输入框、选择框、标签输入、文件选择、布局的激活项                                               |
| 打开态 | `open` / `defaultOpen` / `onOpenChange`   | `Popup`、`PopupButton`、`ButtonMenuSelectWidget`、工具栏的弹出面板与工具的 `popup` 配置 |
| 勾选  | `checked` / `defaultChecked` / `onChange` | `CheckboxInput`、`RadioInput`、`ToggleButton`、`ToggleSwitch`             |

选择系组件共用的选项数据书写约定（`value`
、分组、`labelText`
、禁用下发等）见[选择与选项](https://ooui-react.pages.dev/guide/options.md)
。
## 判定规则

**传入 `value`（或 `checked`）即为受控**，组件只按传入的值渲染；不传则由组件维护内部状态，`defaultValue` 仅作为初始值。

```tsx preview
import { useState } from "react";
import { Button, ToggleSwitch } from "ooui-react";

function App() {
  const [on, setOn] = useState(false);

  return (
    <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 12 }}>
      {/* 受控：值由外部持有 */}
      <ToggleSwitch checked={on} onChange={(checked) => setOn(checked)} />
      {/* 非受控：组件自己记住状态 */}
      <ToggleSwitch defaultChecked />
      <Button disabled={!on} onClick={() => setOn(false)}>
        重置
      </Button>
    </div>
  );
}

export default App;
```

不要把 `value` 在值与 `undefined` 之间来回切换——这属于模式变更，不受支持。

## 回调签名

值类回调统一为**值优先**：

```ts
type ChangeHandler<T, P extends EventTarget = HTMLElement> = (
  value: T,
  event?: ChangeEvent<P>,
) => void;
```

多数场景只用到第一个参数（`onChange={setValue}` 即可）。第二参数是触发变更的原生事件，**仅输入框类组件提供**。

不遵循该签名的回调：

| 组件                            | 回调                           | 签名                           |
| ----------------------------- | ---------------------------- | ---------------------------- |
| `ToggleSwitch`、`ToggleButton` | `onChange`                   | `(checked: boolean) => void` |
| `SelectFileInputWidget`       | `onChange`                   | `(files: File[]) => void`    |
| `SearchWidget`                | `onQueryChange` / `onChoose` | 查询值 / 选定的结果                  |
| `Message`                     | `onClose`                    | `() => void`，点击关闭按钮时触发       |

容易混淆的“选定”回调：

- `Select` 系列同时提供 `onChange`（选中值变化，重复选同一项不触发）与 `onChoose`（每次选定都触发，含重复）。`clearOnChoose` 为真时只触发 `onChoose`、不改变选中值，适合做命令菜单。
- `SearchWidget` 不提供 `onChange`，查询变化走 `onQueryChange`。

## 弹窗必须受控

`Dialog`
、`MessageDialog`
、`ProcessDialog`
 只有 `open`
（必填），没有 `defaultOpen`
：开与关由你的状态决定，关闭动作经回调通知你。
| 回调                | 触发时机                    |
| ----------------- | ----------------------- |
| `onEscape`        | 按下 ESC（`escapable` 为真时） |
| `onPrimaryAction` | 按下 Ctrl / Cmd + Enter   |
| `onReady`         | 打开动画结束，可执行聚焦等操作         |

`MessageDialog` 另有 `onOk` / `onCancel`，`ProcessDialog` 另有 `onAction`，见各自组件页。

## 受控值不在备选项内时

你传给组件的 `value`，有时在 `options` 里找不到对应项，比如某个选项被移除了、初始值写错，或选项是异步加载、首帧还没到位。这时组件的表现如下：

| 组件                                                                             | 找不到对应项时                  | 会回写 `onChange` 吗                       |
| ------------------------------------------------------------------------------ | ------------------------ | -------------------------------------- |
| `IndexLayout`、`BookletLayout`、`StackLayout`、`DropdownInput`、`RadioSelectInput` | 自动显示一个兜底项（通常是首个可选项），不留空档 | 会：把兜底值经 `onChange` 交回给你，让你的 state 跟上界面 |
| `Select`、`Dropdown`、`TagMultiselect`、`MenuTagMultiselect`                      | 不选中任何项，按你传入的值原样渲染        | 不会                                     |

第一类中，假设 `options` 是 `a`、`b`，而你传了 `value="c"`：

```tsx
const options = [
  { value: "a", label: "A", children: "面板 A" },
  { value: "b", label: "B", children: "面板 B" },
];

// 传入的 `c` 不在 options 里
<IndexLayout value="c" onChange={setTab} options={options} />
```

组件会显示 `a`
（兜底项），并调用 `onChange("a")`
 告诉你“实际生效的是 a”。父级据此把 state 更新为 `a`
，`value`
 与界面就重新对齐了。同一个非法值只回写一次，父级若不采纳也不会反复触发。
第二类完全以你的 `value` 为准：找不到匹配就是不选，界面如实呈现“当前值无匹配”，要不要纠正由你在外部处理。



---
url: https://ooui-react.pages.dev/guide/options.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 选择与选项

[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)介绍了值如何在组件与你的状态之间流动，本页介绍值的两端怎么写——Select 系组件共用的选项数据约定。适用于：

- 选择列表：`Select`、`OutlineSelect`、`TabSelect`、`ButtonSelect`、`ButtonMenuSelectWidget`
- 标签输入：`TagMultiselect`、`MenuTagMultiselect`
- 表单字段：`DropdownInput`、`RadioSelectInput`、`CheckboxMultiselectInput`
- 带候选的输入：`ComboBoxInput`、`SearchWidget`（结果集）

各组件只在此约定上增补自己的属性（如 `OutlineSelect` 的层级、标签的 `fixed`），具体见组件页。

## 选项数据

`options` 是一个选项对象数组：

- **带 `value` 的项是可选项**。`value` 始终是 `string | number`，同时是选中态的匹配依据与列表 key。
- **不带 `value` 的项渲染为分组标题**（不可选中、不参与键盘导航），只有分组形态的组件支持（`Select`、`OutlineSelect`、`Dropdown`、`ButtonMenuSelectWidget` 等）。
- 选项文本写在 `children` 上；标签多选写在 `label` 上，见下文。
- **选中态不需要在选项里声明**——组件按 `value` 与当前值计算得出，选项数据保持为纯数据。

```tsx preview
import { Select } from "ooui-react";

function App() {
  return (
    <Select
      defaultValue="orange"
      aria-label="水果"
      options={[
        { value: "apple", children: "苹果" },
        { value: "orange", children: "橙子" },
        { value: "banana", children: "香蕉", disabled: true },
        { children: "浆果" },
        { value: "grape", children: "葡萄" },
        { value: "melon", children: "西瓜" },
      ]}
    />
  );
}

export default App;
```

上面的 `浆果` 一项没有 `value`，渲染为分组标题。

## 标签多选的选项

`TagMultiselect` / `MenuTagMultiselect` 的选项同时充当**标签本体**与**菜单候选**，约定与前文一致，另有三处专属字段：

```tsx
import { Icon, MenuTagMultiselect } from "ooui-react";

<MenuTagMultiselect
  options={[
    { value: "bold", label: "加粗", icon: "bold" },
    // label 为富内容时，前缀过滤与回填需要纯文本形态 labelText
    {
      value: "code",
      label: (
        <>
          <Icon icon="code" /> 代码
        </>
      ),
      labelText: "代码",
    },
    // data 携带任意数据，与标识 value 相互独立
    { value: "link", label: "链接", data: { openInNewTab: true } },
    { value: "lock", label: "锁定", fixed: true },
  ]}
/>
```

- **`label` 收 `ReactNode`**（对齐原版接受富内容），缺省显示 `value`。标签多选的选项文本用 `label` 而非 `children`。
- **`labelText` 是 `label` 的纯文本形态**，用于按输入前缀过滤菜单候选、选中/编辑标签时回填输入框。`label` 为字符串时缺省取自身；为富内容时必须显式给出——未给出时该选项**不参与前缀过滤**（回填以 `String(value)` 兜底），开发期会告警一次。{/* deviations: dev-tag-label-labeltext */}
- **`data` 携带任意数据**。标签的标识始终是标量 `value`（受控数组可序列化、可比对），`onChange` 回传的也是标量数组；需要随标签携带对象时放在 `data` 里，按 `value` 在自己的 `options` 数组里反查取回。{/* deviations: dev-tag-value-data */}
- `fixed: true` 的标签固定（不渲染关闭按钮、不可移除），拖拽排序也不会把它移到固定项之前。{/* deviations: dev-tag-fixed */}

## 禁用

- 选项对象自己的 `disabled` 禁用该项。
- 组件级 `disabled` 的作用范围分两种：**列表/组形态**（`Select`、`TabSelect`、`ButtonSelect`、`RadioSelect`、`CheckboxMultiselect`）会一并禁用组内全部选项，且组禁用优先——被禁用组内的选项无法单独启用；**浮层触发形态**（`Dropdown`、`ComboBoxInput`、`ButtonMenuSelectWidget`）禁用的是触发端（不可展开、键盘不可用），菜单里各项是否禁用由选项自身的 `disabled` 决定。

## 图标与标志

带图标槽位的选项形态（菜单/大纲/按钮选项及分组标题）支持 `icon`
 与 `flags`
：`icon`
 取图标名（见 [Icon](https://ooui-react.pages.dev/components/icon/index.md)
），`flags`
 给图标着色（`progressive`
、`destructive`
 等变体）。纯文本选项（`TabSelect`
、`RadioSelect`
、`CheckboxMultiselect`
 的项）没有图标槽位，不支持这两个字段。
## 键盘与焦点

- **方向键**在选项间移动：直选类（`TabSelect`、`ButtonSelect`、`RadioSelect`）按键即改选；菜单类（`Dropdown` 等的菜单）移动高亮，Enter / 空格选定。
- **Home / End / PageUp / PageDown** 跳至首尾项或翻页：菜单类默认支持，独立 `Select` 可经 `handleNavigationKeys` 打开；`listWrapsAround` 控制到端点后是否环绕。
- **前缀跳转**：直接键入字符，按选项文本的前缀跳转（1.5 秒缓冲）；标签多选按前缀过滤候选。
- **焦点不进列表**：焦点保持在控件（或触发元素）上，高亮项经 `aria-activedescendant` 关联，列表根缺省不进 Tab 序——这是与原版一致的 listbox 模式。**例外**：直选类（`TabSelect`、`ButtonSelect`）的组根在 Tab 序内（焦点停在整组），且点击选项后焦点自动收进组根（原版点击后焦点留在原处、方向键不响应，此处对齐 ARIA APG 略作改良）。{/* deviations: dev-directselect-focus */}
- 直选类（`TabSelect`、`ButtonSelect`）带初始选中值时，`aria-activedescendant` 首帧即指向选中项（原版要等首次改选才写入该属性）。{/* deviations: dev-directselect-activedescendant */}
- 输入法**合成期间**的确认 Enter 与选词方向键不会误触发选择、开合或提交。{/* deviations: dev-ime-guard */}

## 另见

- 受控值不在备选项内时各组件的行为：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%8F%97%E6%8E%A7%E5%80%BC%E4%B8%8D%E5%9C%A8%E5%A4%87%E9%80%89%E9%A1%B9%E5%86%85%E6%97%B6)
- `onChange` 与 `onChoose`（每次选定都触发）的分工：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%9B%9E%E8%B0%83%E7%AD%BE%E5%90%8D)



---
url: https://ooui-react.pages.dev/guide/configuration.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 全局配置

`OOUIProvider` 承载跨组件的全局设定：文案、浮层挂载位置、移动端形态、快捷键显示等。包一层即可，未包裹时组件按缺省值工作。组件文案的语言包与站点消息接入见[文案与国际化](#文案与国际化)。

## 用法

```jsx
import { OOUIProvider } from "ooui-react";
import zhHans from "ooui-react/locales/zh-hans";

root.render(
  <OOUIProvider messages={zhHans}>{app}</OOUIProvider>,
);
```

不包裹也能正常使用：英文文案、浮层挂载到 `document.body`、非移动端形态、文本方向按锚点元素自动解析、视口留白为 0。

## 配置项

| 配置                   | 说明                       | 类型                                           | 缺省              |
| -------------------- | ------------------------ | -------------------------------------------- | --------------- |
| `messages`           | 消息覆盖表，见[文案与国际化](#文案与国际化) | `Partial<Record<MessageKey, MessageValue>>`  | 英文              |
| `getPortalContainer` | 浮层的挂载容器，入参为浮层锚点元素        | `(trigger: HTMLElement) => HTMLElement`      | `document.body` |
| `isMobile`           | 移动端形态开关                  | `boolean`                                    | `false`         |
| `dir`                | 浮层的文本方向                  | `'ltr' \| 'rtl'`                             | 按锚点自动解析         |
| `viewportSpacing`    | 浮层贴边与限制高度时计入的视口留白        | `number` 或逐边对象                               | 各边 0            |
| `getAccessKeyLabel`  | 快捷键的显示文案                 | `(accessKey: string) => string \| undefined` | 原键值             |

## 浮层挂载位置

`getPortalContainer` 决定浮层（下拉菜单、弹出面板、`Popup`）挂载到哪个容器。默认挂载到 `document.body`；**弹窗内的浮层**挂载到该弹窗的容器，随弹窗一起层叠与隔离。

配置该项后始终以它为准——包括弹窗内的浮层，此时浮层不再随弹窗被隔离，层叠交给容器自行承担。容器不应建立新的定位上下文（浮层按页面坐标绝对定位）。
## 移动端形态

`isMobile`
 开启后部分组件切换为移动端形态：`TabSelect`
 的选中项居中滚动，`IndexLayout`
 / `BookletLayout`
 不再自动聚焦，弹窗与下拉按移动端排布。缺省 `false`
，宿主可接 `matchMedia`
 自行判定后传入。
## 文本方向

缺省按锚点元素的文本方向解析，因此**把 `dir="rtl"` 设在页面或容器即可**，多数场景无需配置本项。

只有浮层挂载到内容区之外、锚点方向不能代表浮层方向时（例如浮层要挂载到站点内容区之外的容器里）才需要显式指定 `dir`。

## 视口留白

`viewportSpacing` 是浮层贴边、限制高度与翻转判定时计入的四周留白。站点有固定头栏一类悬浮元素时可用它避开，例如 `viewportSpacing={{ top: 48 }}`。缺省各边 0。

## 快捷键文案

`getAccessKeyLabel`
 给出快捷键在 `title`
 里的显示文案。未配置时显示为 `保存 [s]`
，配置后可显示为站点本地的组合键：
```tsx preview
import { Button, OOUIProvider } from "ooui-react";

function App() {
  return (
    <OOUIProvider getAccessKeyLabel={(key) => `Alt+Shift+${key}`}>
      <Button accessKey="s" title="保存">
        保存
      </Button>
    </OOUIProvider>
  );
}

export default App;
```

## 文案与国际化

消息提示弹窗、文件选择组件等部分位置有文案，默认为英文。`messages`
 传入语言包即可切换，`messages`
 变化即时生效。
```tsx preview
import { useState } from "react";
import type { MessageKey, MessageValue } from "ooui-react";
import { Button, OOUIProvider, SelectFileInputWidget } from "ooui-react";
import ja from "ooui-react/locales/ja";
import ru from "ooui-react/locales/ru";
import zhHans from "ooui-react/locales/zh-hans";

type Locale = "zh-hans" | "en" | "ja" | "ru";

const LOCALES: Array<{
  value: Locale;
  label: string;
  messages?: Partial<Record<MessageKey, MessageValue>>;
}> = [
  { value: "zh-hans", label: "简体中文", messages: zhHans },
  { value: "en", label: "English" },
  { value: "ja", label: "日本語", messages: ja },
  { value: "ru", label: "Русский", messages: ru },
];

function App() {
  const [locale, setLocale] = useState<Locale>("zh-hans");
  const pack = LOCALES.find((item) => item.value === locale);

  return (
    <OOUIProvider messages={pack?.messages}>
      <div style={{ display: "grid", gap: 16, justifyItems: "start" }}>
        <div style={{ display: "flex", gap: 8 }}>
          {LOCALES.map((item) => (
            <Button
              key={item.value}
              active={item.value === locale}
              onClick={() => setLocale(item.value)}
            >
              {item.label}
            </Button>
          ))}
        </div>
        <SelectFileInputWidget />
      </div>
    </OOUIProvider>
  );
}

export default App;
```

### 支持的语言

语言包与原版 OOUI `dist/i18n` 的语种对应，共 222 个，按 MediaWiki 语言代码引入（`ooui-react/locales/<代码>`），语言包按需引入、互不牵连产物体积。`en` 是内建默认基线、始终随主产物，不需要引入；语言包缺的键逐键回落英文默认。

上游对本库用到的消息无译文的语种（`crh-cyrl` / `crh-latn` / `vo`）与翻译说明语种 `qqq` 未引入，全部语言代码见安装目录下的 `ooui-react/dist/locales/`。

阿拉伯语、希伯来语、波斯语等从右到左的语言，页面或容器的文本方向另见[文本方向](#文本方向)。

### 修改个别文案

`messages` 是逐键合并的，只传要改的键，其余保持原有文案：

```jsx
<OOUIProvider messages={{ "ooui-dialog-message-accept": "好嘞" }}>
```

键名沿用 OOUI 的消息名，完整键名可查看内建语言包（npm 包内 `ooui-react/locales/en`）。嵌套 `OOUIProvider` 时内层优先，可以外层传语言包、内层只改个别文案。

### 在 MediaWiki 站点使用

MediaWiki 自带 OOUI 的消息，键名与本库一致，因此不必引入语言包——把站点的 `mw.msg` 接进来即可跟随站点语言。值写成函数，取值时才解析：

```jsx
<OOUIProvider
  messages={{
    "ooui-dialog-message-accept": () => mw.msg("ooui-dialog-message-accept"),
    "ooui-dialog-message-reject": () => mw.msg("ooui-dialog-message-reject"),
  }}
>
```

只有给出的键走站点消息，其余回落英文，所以按界面上实际用到的文案接即可。命令式弹窗（`confirm` / `alert` / `prompt`）由 `OOUIProvider` 的宿主渲染，同样继承这份映射，无需另行注册。

## 命令式弹窗

`confirm` / `alert` / `prompt` 是独立函数，import 后从任意事件回调里 `await` 即可，无需 hook 或额外挂载：

```tsx
const ok = await confirm("确定要删除吗？", { title: "删除" });
```

只要调用处在 `OOUIProvider`
 之下，弹窗就**自动继承它的配置**
（文案、`isMobile`
、`dir`
 及你自己的 Provider），无需手动注入；嵌套多个 Provider 时用最外层那份。
未包 `OOUIProvider` 时按英文缺省渲染，此时改文案用模块级 `registerMessages`：

```js
import { registerMessages } from "ooui-react";

registerMessages({ "ooui-dialog-message-accept": "确定" });
```

返回值、options 与运行时语义见[命令式弹窗](https://ooui-react.pages.dev/components/imperative-dialogs/index.md)。

## 读取配置

组件之外也能读到生效的配置：

| Hook                                            | 返回                                                    |
| ----------------------------------------------- | ----------------------------------------------------- |
| `useOOUIConfig`                                 | 合并后的完整配置对象                                            |
| `useMessage(key, ...params)`                    | 一条消息的当前文案（`OOUIProvider` > `registerMessages` > 英文默认） |
| `useIsMobile` / `useDir` / `useViewportSpacing` | 对应配置项的生效值                                             |
| `useAccessKeyLabel(accessKey)`                  | 快捷键的显示文案                                              |

## 嵌套

内层覆盖外层，`messages` 逐键合并：可以外层传语言包、内层只改个别文案。

## 常见问题

**命令式弹窗的文案没变？** 确认 `confirm` / `alert` / `prompt` 的调用处于某个 `OOUIProvider` 之下——弹窗由该 Provider 的宿主渲染并继承其 `messages`。完全不包 `OOUIProvider` 时才需用 `registerMessages` 注册，见[命令式弹窗](#命令式弹窗)。

**切换语言后整棵树重渲染？** `messages` 应传稳定引用（如从 `ooui-react/locales/*` 引入的模块级常量），内联的对象字面量会让每次渲染都产生新对象。



---
url: https://ooui-react.pages.dev/components/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 组件总览

本组件库以 React 重新实现 OOUI，组件按原版类层级分为**控件、布局、弹窗、工具栏**几族，合计 60 个。

组件**不自带样式**，只输出与原版一致的 DOM 与 `oo-ui-*` 类名，使用前请先按[使用方式](https://ooui-react.pages.dev/guide/usage.md)引入 OOUI 样式表；所有组件共有的属性规则见[通用属性与 ref](https://ooui-react.pages.dev/guide/basics.md)。

## 控件


- [Button](https://ooui-react.pages.dev/components/button/index.md) 支持图标、指示器、标签与链接形态
- [ToggleButton](https://ooui-react.pages.dev/components/toggle-button/index.md) 可切换的按钮（按下/弹起）
- [ToggleSwitch](https://ooui-react.pages.dev/components/toggle-switch/index.md) 开关
- [ButtonGroup](https://ooui-react.pages.dev/components/button-group/index.md) 把若干按钮排成一组，可统一禁用
- [PopupButton](https://ooui-react.pages.dev/components/popup-button/index.md) 点击弹出浮层的按钮
- [Popup](https://ooui-react.pages.dev/components/popup/index.md) 弹出浮层本身
- [Label](https://ooui-react.pages.dev/components/label/index.md) 独立文本标签
- [Icon](https://ooui-react.pages.dev/components/icon/index.md) 图标
- [Indicator](https://ooui-react.pages.dev/components/indicator/index.md) 指示器（“展开”“必填”一类标记）
- [ProgressBar](https://ooui-react.pages.dev/components/progress-bar/index.md) 进度条
- [Message](https://ooui-react.pages.dev/components/message/index.md) 行内消息提示（含关闭按钮）

### 输入


- [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 单行文本输入框
- [MultilineTextInput](https://ooui-react.pages.dev/components/multiline-text-input/index.md) 多行文本输入框
- [NumberInput](https://ooui-react.pages.dev/components/number-input/index.md) 数字输入框（带步进按钮）
- [SearchInput](https://ooui-react.pages.dev/components/search-input/index.md) 搜索输入框（带清空指示器）
- [SearchWidget](https://ooui-react.pages.dev/components/search-widget/index.md) 查询输入框加常驻结果列表
- [ComboBoxInput](https://ooui-react.pages.dev/components/combo-box-input/index.md) 可输入过滤也可下拉选择的组合框
- [CheckboxInput](https://ooui-react.pages.dev/components/checkbox-input/index.md) 单个复选框
- [RadioInput](https://ooui-react.pages.dev/components/radio-input/index.md) 单个单选框
- [SelectFileInputWidget](https://ooui-react.pages.dev/components/select-file-input-widget/index.md) 文件选择（含拖放区形态）

### 选择

选项数据的书写约定（`value`、分组标题、标签多选的 `label`/`labelText`/`data`）见[选择与选项](https://ooui-react.pages.dev/guide/options.md)。


- [Select](https://ooui-react.pages.dev/components/select/index.md) 选择列表（下拉/菜单的内层）
- [Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md) 下拉选择
- [OutlineSelect](https://ooui-react.pages.dev/components/outline-select/index.md) 带层级缩进的选择列表
- [TabSelect](https://ooui-react.pages.dev/components/tab-select/index.md) 页签式选择
- [ButtonSelect](https://ooui-react.pages.dev/components/button-select/index.md) 按钮式选择
- [ButtonMenuSelectWidget](https://ooui-react.pages.dev/components/button-menu-select/index.md) 按钮触发的命令菜单
- [CheckboxMultiselect](https://ooui-react.pages.dev/components/checkbox-multiselect/index.md) 复选组
- [RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md) 单选组
- [TagMultiselect](https://ooui-react.pages.dev/components/tag-multiselect/index.md) 标签输入（自由输入）
- [MenuTagMultiselect](https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md) 标签输入（带候选菜单）

### 表单提交

随 `<form>` 原生提交的一组字段控件，配合 `FormLayout` 使用。


- [ButtonInput](https://ooui-react.pages.dev/components/button-input/index.md) 提交按钮
- [DropdownInput](https://ooui-react.pages.dev/components/dropdown-input/index.md) 下拉选择字段
- [CheckboxMultiselectInput](https://ooui-react.pages.dev/components/checkbox-multiselect-input/index.md) 复选组字段
- [RadioSelectInput](https://ooui-react.pages.dev/components/radio-select-input/index.md) 单选组字段
- [HiddenInputWidget](https://ooui-react.pages.dev/components/hidden-input-widget/index.md) 随表单提交但不显示的字段

## 布局


- [Layout](https://ooui-react.pages.dev/components/layout/index.md) 布局基类
- [PanelLayout](https://ooui-react.pages.dev/components/panel-layout/index.md) 带内边距的面板
- [PageLayout](https://ooui-react.pages.dev/components/page-layout/index.md) 页面整体布局
- [StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md) 堆叠面板，一次显示一个
- [BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md) 带页签的多面板（手册式）
- [IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md) 带索引区与搜索的多面板
- [TabPanelLayout](https://ooui-react.pages.dev/components/tab-panel-layout/index.md) 单个页签面板
- [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 带标签与提示的字段包装
- [FieldsetLayout](https://ooui-react.pages.dev/components/fieldset-layout/index.md) 字段分组（可统一禁用）
- [ActionFieldLayout](https://ooui-react.pages.dev/components/action-field-layout/index.md) 字段加随行按钮
- [FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md) 表单容器
- [HorizontalLayout](https://ooui-react.pages.dev/components/horizontal-layout/index.md) 横向排列若干元素
- [MenuLayout](https://ooui-react.pages.dev/components/menu-layout/index.md) 菜单整体布局
- [CopyTextLayout](https://ooui-react.pages.dev/components/copy-text-layout/index.md) 只读文本框加复制按钮

## 弹窗


- [Dialog](https://ooui-react.pages.dev/components/dialog/index.md) 弹窗基类（受控 open）
- [MessageDialog](https://ooui-react.pages.dev/components/dialog/index.md) 消息弹窗（确定/取消）
- [ProcessDialog](https://ooui-react.pages.dev/components/process-dialog/index.md) 带多步流程与错误面板的弹窗
- [`confirm` / `alert` / `prompt`](https://ooui-react.pages.dev/components/imperative-dialogs/index.md) 命令式弹窗（不依赖 React 树）

## 工具栏


- [Toolbar](https://ooui-react.pages.dev/components/toolbar/index.md) 工具栏容器
- [BarToolGroup](https://ooui-react.pages.dev/components/toolbar/index.md) 按钮式工具组
- [ListToolGroup](https://ooui-react.pages.dev/components/toolbar/index.md) 列表式工具组
- [MenuToolGroup](https://ooui-react.pages.dev/components/toolbar/index.md) 菜单式工具组
- [LabelToolGroup](https://ooui-react.pages.dev/components/toolbar/index.md) 工具栏内的静态标签组



---
url: https://ooui-react.pages.dev/components/button/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Button 按钮

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Button) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonWidget.html "OO.ui.ButtonWidget")

基础按钮组件，同时也是 [ToggleButton](https://ooui-react.pages.dev/components/toggle-button/index.md)、[PopupButton](https://ooui-react.pages.dev/components/popup-button/index.md)、[ButtonMenuSelectWidget](https://ooui-react.pages.dev/components/button-menu-select/index.md) 等组件的按钮基座。

## 基本用法

```tsx preview
import { useState } from "react";
import { Button } from "ooui-react";

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button onClick={() => setCount((n) => n + 1)}>点我</Button>
      <span>已点击 {count} 次</span>
    </div>
  );
}

export default App;
```

## 图标与指示器

`icon` 取图标名（见 [Icon](https://ooui-react.pages.dev/components/icon/index.md)），`indicator` 取指示器名（见 [Indicator](https://ooui-react.pages.dev/components/indicator/index.md)）。二者分别渲染在标签两端。

标签只用图标时把 `invisibleLabel` 打开：标签视觉隐藏但仍保留可访问名称，`title` 未显式给出时以标签文本兜底。

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button icon="check">完成</Button>
      <Button icon="trash" flags="destructive">
        删除
      </Button>
      <Button indicator="down">展开</Button>
      <Button icon="search" invisibleLabel>
        搜索
      </Button>
    </div>
  );
}

export default App;
```

## 标志与形态

`flags` 影响配色与图标着色，`framed={false}` 切换为无边框形态，`active` 表示已选中/已激活。

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
      <Button>默认</Button>
      <Button flags="progressive">继续</Button>
      <Button flags={["primary", "progressive"]}>保存</Button>
      <Button flags="destructive">删除</Button>
      <Button framed={false} flags="destructive">
        无边框删除
      </Button>
      <Button active>已选中</Button>
    </div>
  );
}

export default App;
```

带边框的按钮在 `primary`、激活或禁用时整体反色，此时图标与指示器也随之反色；其余情形按 `flags` 里的色彩标志着色。可用的色彩标志为 `progressive`、`destructive`、`invert`、`error`、`warning`、`success`。

## 链接用法

给出 `href` 后内部 `<a>` 即成为可跳转链接，`target` 指定打开位置。`rel` 默认为 `nofollow`；带 `target="_blank"` 时应自行补上 `noopener`。

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button href="https://www.mediawiki.org">MediaWiki</Button>
      <Button href="https://www.mediawiki.org" target="_blank" rel={["nofollow", "noopener"]}>
        新窗口打开
      </Button>
    </div>
  );
}

export default App;
```

:::warning 安全提示
本组件不对 `href`
 做 URL 净化（越过原版的 `OO.ui.isSafeUrl`
），React 在运行期也不拦截 `javascript:`
 一类危险协议。来源不可信的链接（如由用户输入拼接）必须先自行校验协议，否则构成 XSS；需要组件层净化时可用导出的方法 `sanitizeUrl`
。
:::
## 禁用

`disabled` 输出 `oo-ui-widget-disabled` 与 `aria-disabled`（不用原生 `disabled`），此时按钮不响应点击、`tabindex` 转为 `-1`、`href` 也不再生效。放进 `ButtonGroup` 时，组级禁用会一并下发给组内按钮。

```tsx preview
import { Button } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <Button disabled>禁用</Button>
      <Button icon="check" disabled>
        禁用（带图标）
      </Button>
    </div>
  );
}

export default App;
```

## 焦点与键盘

- 可聚焦的是内部 `<a>`，根元素是不可聚焦的 `<span>`：要手动聚焦按钮请用 `anchorRef`（组件 `ref` 指向外层 `<span>`）。
- Enter / 空格触发 `onClick`，`onKeyPress` 将在存在点击回调时阻止空格滚动页面。
- 按压态（`oo-ui-buttonElement-pressed`）由组件用 JS 维护（含键盘按压与松开）。`pressed` 属性可与之外取或，用于“关联菜单打开期间按钮保持按压”的场景。
- `title`、`accessKey` 写在内部 `<a>` 上；未显式给 `title` 且标签隐藏时以标签文本兜底，`accessKey` 存在时 `title` 末尾附键位提示（组合键文案可经 [OOUIProvider](https://ooui-react.pages.dev/guide/configuration.md#%E5%BF%AB%E6%8D%B7%E9%94%AE%E6%96%87%E6%A1%88) 本地化）。

## API

| 属性                             | 描述                                                                                                                   | 类型                                        | 默认值            |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- |
| `children`                     | 按钮标签                                                                                                                 | `ReactNode`                               | —              |
| `icon`                         | 前置图标名                                                                                                                | `string`                                  | —              |
| `indicator`                    | 后置指示器                                                                                                                | `'up' \| 'down' \| 'clear' \| 'required'` | —              |
| `flags`                        | 附加标志（色彩与按钮专属形态）                                                                                                      | `ButtonFlag \| ButtonFlag[]`              | `[]`           |
| `framed`                       | 是否带边框                                                                                                                | `boolean`                                 | `true`         |
| `active`                       | 是否为激活状态                                                                                                              | `boolean`                                 | `false`        |
| `invisibleLabel`               | 标签视觉隐藏（保留可访问名称）                                                                                                      | `boolean`                                 | `false`        |
| `disabled`                     | 是否禁用（含所属 `ButtonGroup` 的组禁用）                                                                                         | `boolean`                                 | `false`        |
| `href`                         | 链接地址（写在内部 `<a>` 上）                                                                                                   | `string`                                  | —              |
| `target`                       | 链接打开位置                                                                                                               | `string`                                  | —              |
| `rel`                          | 内部 `<a>` 的 `rel`（数组以空格拼接）                                                                                            | `string \| string[]`                      | `['nofollow']` |
| `title`                        | 内部 `<a>` 的提示文本                                                                                                       | `string`                                  | —              |
| `accessKey`                    | 快捷键                                                                                                                  | `string`                                  | —              |
| `tabIndex`                     | Tab 序；传 `null` 表示不输出该属性                                                                                              | `number \| null`                          | `0`            |
| `pressed`                      | 受控按压态（与内部按压流取或）                                                                                                      | `boolean`                                 | —              |
| `onClick`                      | 点击回调（Enter / 空格同样触发）                                                                                                 | `(ev: ButtonClickEvent) => void`          | —              |
| `anchorRef`                    | 内部 `<a>` 元素的引用                                                                                                       | `Ref<HTMLAnchorElement>`                  | —              |
| `anchorProps`                  | 内部 `<a>` 的附加属性；`role`、`tabIndex`、`aria-disabled` 等由组件接管、优先                                                           | `HTMLAttributes<HTMLAnchorElement>`       | —              |
| `iconProps` / `indicatorProps` | 图标 / 指示器元素的附加属性                                                                                                      | `object`                                  | —              |
| `...rest`                      | 原生 `span` 属性（`className`、`id`、`data-*` 等）直传根元素；`aria-label` / `aria-labelledby` / `aria-pressed` 例外，写在内部可聚焦的 `<a>` 上 | `HTMLAttributes<HTMLSpanElement>`         | —              |

`ButtonFlag` 为 `'progressive' | 'destructive' | 'invert' | 'error' | 'warning' | 'success' | 'primary' | 'safe' | 'back' | 'close'`，其中前六个决定着色，后四个是按钮专属的形态标志。



---
url: https://ooui-react.pages.dev/components/toggle-button/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ToggleButton 切换按钮

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ToggleButton) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToggleButtonWidget.html "OO.ui.ToggleButtonWidget")

切换按钮：能“按下 / 弹起”的 [Button](https://ooui-react.pages.dev/components/button/index.md)。

## 基本用法

开/关状态由 `checked` / `defaultChecked` / `onChange` 控制，`onChange` 的第一个参数是新的开关布尔值。按下时按钮呈激活（高亮）外观。

```tsx preview
import { useState } from "react";
import { ToggleButton } from "ooui-react";

function App() {
  const [highlight, setHighlight] = useState(false);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <ToggleButton icon="highlight" checked={highlight} onChange={setHighlight}>
        高亮
      </ToggleButton>
      <ToggleButton icon="star" defaultChecked>
        收藏（非受控，初始按下）
      </ToggleButton>
      <span>高亮：{String(highlight)}</span>
    </div>
  );
}

export default App;
```

## 无边框形态

与 Button 一样支持 `framed={false}` 与各类 `flags`，常用于工具条里的成组切换。

```tsx preview
import { ToggleButton } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <ToggleButton icon="bold" defaultChecked>
        加粗
      </ToggleButton>
      <ToggleButton icon="italic">
        斜体
      </ToggleButton>
      <ToggleButton framed={false} icon="link" defaultChecked>
        无边框
      </ToggleButton>
    </div>
  );
}

export default App;
```

## 与 Button 的区别

ToggleButton 继承 Button 的外观，但**没有链接能力**：`href` / `target` / `rel` / `anchorRef` 不接受；`active`、`onClick`、`aria-pressed` 由开关状态驱动，不外露。要“点击执行一次动作”请用 [Button](https://ooui-react.pages.dev/components/button/index.md)，要“表达一个持续的开/关状态”才用本组件。

## API

| 属性               | 描述                           | 类型                                        | 默认值     |
| ---------------- | ---------------------------- | ----------------------------------------- | ------- |
| `children`       | 按钮标签                         | `ReactNode`                               | —       |
| `checked`        | 是否按下（受控，传入后即进入受控模式）          | `boolean`                                 | —       |
| `defaultChecked` | 非受控初始开关态                     | `boolean`                                 | `false` |
| `onChange`       | 开关状态变更回调（仅回传新状态）             | `(checked: boolean) => void`              | —       |
| `icon`           | 前置图标名                        | `string`                                  | —       |
| `indicator`      | 后置指示器                        | `'up' \| 'down' \| 'clear' \| 'required'` | —       |
| `flags`          | 附加标志（色彩与按钮专属形态）              | `ButtonFlag \| ButtonFlag[]`              | `[]`    |
| `framed`         | 是否带边框                        | `boolean`                                 | `true`  |
| `invisibleLabel` | 标签视觉隐藏（保留可访问名称）              | `boolean`                                 | `false` |
| `disabled`       | 是否禁用（含所属 `ButtonGroup` 的组禁用） | `boolean`                                 | `false` |
| `tabIndex`       | Tab 序                        | `number \| null`                          | `0`     |
| `...rest`        | Button 的其余非链接属性，直传按钮元素       | `object`                                  | —       |

`onChange` 是切换回调，不遵循值优先的 `ChangeHandler` 签名（见[受控与非受控 · 回调签名](https://ooui-react.pages.dev/guide/controlled.md#%E5%9B%9E%E8%B0%83%E7%AD%BE%E5%90%8D)）。

## 另见

- 按钮的基础能力与图标 / 指示器：[Button](https://ooui-react.pages.dev/components/button/index.md)
- 拨动开关形态：[ToggleSwitch](https://ooui-react.pages.dev/components/toggle-switch/index.md)
- 把多个按钮排成一组：[ButtonGroup](https://ooui-react.pages.dev/components/button-group/index.md)



---
url: https://ooui-react.pages.dev/components/toggle-switch/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ToggleSwitch 开关

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ToggleSwitch) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToggleSwitchWidget.html "OO.ui.ToggleSwitchWidget")

拨动开关。不自带文字标签，需要标签时交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 包裹。

## 基本用法

开/关状态由 `checked` / `defaultChecked` / `onChange` 控制，`onChange` 的第一个参数是新的开关布尔值。

```tsx preview
import { useState } from "react";
import { ToggleSwitch } from "ooui-react";

function App() {
  const [on, setOn] = useState(true);

  return (
    <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 12 }}>
      <ToggleSwitch checked={on} onChange={setOn} />
      <div>当前状态：{on ? "开" : "关"}</div>
      <ToggleSwitch defaultChecked />
    </div>
  );
}

export default App;
```

## 与 FieldLayout 配合

字段文字标签交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)。点击标签会**直接翻转开关**并聚焦（与多数“点标签聚焦控件”的字段不同，这是原版 `ToggleSwitchWidget` 的覆写行为）。

```tsx preview
import { ToggleSwitch, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 280 }}>
      <FieldLayout label="接收邮件通知" align="inline">
        <ToggleSwitch defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 交互

- 点击（仅左键）切换；`Tab` 聚焦后可用 **Space / Enter** 切换。
- 输入法**合成期间**的确认 Enter 不触发切换。
- `disabled` 输出 `aria-disabled`（不用原生 `disabled`），此时不可点击、不可聚焦，点标签也不翻转。

## API

| 属性               | 描述                                            | 类型                               | 默认值     |
| ---------------- | --------------------------------------------- | -------------------------------- | ------- |
| `checked`        | 是否开启（受控，传入后即进入受控模式）                           | `boolean`                        | —       |
| `defaultChecked` | 非受控初始开关态                                      | `boolean`                        | `false` |
| `onChange`       | 开关状态变更回调（仅回传新状态）                              | `(checked: boolean) => void`     | —       |
| `disabled`       | 是否禁用                                          | `boolean`                        | `false` |
| `tabIndex`       | Tab 序                                         | `number \| null`                 | `0`     |
| `...rest`        | 原生 `div` 属性（`className`、`id`、`aria-*` 等）直传根元素 | `HTMLAttributes<HTMLDivElement>` | —       |

本组件没有 `children`、`label`、`icon` 写入位置——开关是纯图形控件，文字说明交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)。`onClick` / `onKeyDown` 由组件承载切换逻辑，不接受外部覆盖。

## 另见

- 按钮形态的切换控件：[ToggleButton](https://ooui-react.pages.dev/components/toggle-button/index.md)
- 带标签字段的排版：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 受控值约定：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)



---
url: https://ooui-react.pages.dev/components/button-group/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ButtonGroup 按钮组

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonGroup) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonGroupWidget.html "OO.ui.ButtonGroupWidget")

按钮组：把若干 [Button](https://ooui-react.pages.dev/components/button/index.md) 排在一起，相邻按钮首尾相连成一块。

## 基本用法

```tsx preview
import { Button, ButtonGroup } from "ooui-react";

function App() {
  return (
    <ButtonGroup>
      <Button icon="bold">加粗</Button>
      <Button icon="italic">斜体</Button>
      <Button icon="link">链接</Button>
    </ButtonGroup>
  );
}

export default App;
```

## 组内混用切换按钮

组里可以同时放普通按钮与 [ToggleButton](https://ooui-react.pages.dev/components/toggle-button/index.md)，常用于编辑器工具条。

```tsx preview
import { Button, ButtonGroup, ToggleButton } from "ooui-react";

function App() {
  return (
    <ButtonGroup>
      <ToggleButton icon="bold">加粗</ToggleButton>
      <ToggleButton icon="italic">斜体</ToggleButton>
      <Button icon="highlight" flags="destructive">
        清除格式
      </Button>
    </ButtonGroup>
  );
}

export default App;
```

## 组级禁用

给组设 `disabled`，会**一并下发**给组内的每个按钮，无需逐个设置。

```tsx preview
import { Button, ButtonGroup } from "ooui-react";

function App() {
  return (
    <ButtonGroup disabled>
      <Button>复制</Button>
      <Button>剪切</Button>
      <Button>粘贴</Button>
    </ButtonGroup>
  );
}

export default App;
```

:::note 与原版的差异
原版没有组级禁用下发，需自行逐个禁用组内按钮；本工程组级 `disabled`
 经 React 上下文一并下发——组内按钮的 `disabled`
 取“自身或所属组禁用”之或。
:::
## API

| 属性         | 描述                                                                                                                                                         | 类型                               | 默认值     |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- |
| `children` | 组内按钮（[Button](https://ooui-react.pages.dev/components/button/index.md) / [ToggleButton](https://ooui-react.pages.dev/components/toggle-button/index.md) 等） | `ReactNode`                      | —       |
| `disabled` | 组级禁用，一并下发到组内按钮                                                                                                                                             | `boolean`                        | `false` |
| `...rest`  | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素                                                                                                              | `HTMLAttributes<HTMLDivElement>` | —       |

## 另见

- 组内按钮：[Button](https://ooui-react.pages.dev/components/button/index.md)、[ToggleButton](https://ooui-react.pages.dev/components/toggle-button/index.md)
- 通用透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/components/popup/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Popup 浮层

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Popup) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PopupWidget.html "OO.ui.PopupWidget")

浮动面板：锚定到某个元素、自动定位与翻转的浮层，适合注解、Tooltip 一类的按需展示内容；按钮触发的场景可直接用 [PopupButton](https://ooui-react.pages.dev/components/popup-button/index.md)。

## 基本用法

Popup 自身不会打开，显隐由 `open` 驱动：用一个按钮作为 `container` 锚点，点击切换 `open`。`autoClose` 让点击浮层与触发按钮之外（或按 Escape）自动关闭，`autoCloseIgnore` 把触发按钮排除在“点外部”判定之外。

```tsx preview
import { useRef, useState } from "react";
import { Button, Popup } from "ooui-react";

function App() {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <div style={{ padding: 60 }}>
      <Button ref={anchorRef} indicator="down" onClick={() => setOpen((o) => !o)}>
        打开浮层
      </Button>
      <Popup
        open={open}
        onOpenChange={setOpen}
        container={anchorRef}
        autoClose
        autoCloseIgnore={anchorRef}
        padded
        width={220}
        position="below"
      >
        这里是浮层内容。点空白处、按 Escape，或 Tab 走出浮层都会关闭它。
      </Popup>
    </div>
  );
}

export default App;
```

## 定位与翻转

- `position` 取 `below`（缺省）、`above`、`before`（左侧）、`after`（右侧）。
- `align` 控制在锚点上的对齐：`center`（缺省）、`forwards` / `backwards`（随书写方向/RTL 换物理侧），或 `force-left` / `force-right`（始终是物理左右，不随方向翻转）。
- `autoFlip`（默认开）在当前方向放不下时翻到对侧；`anchor`（默认开）画指向锚点的箭头。
- 空间不足时浮层会被裁剪/钳制在可视区（或就近滚动容器）内，`containerPadding` 控制钳制内边距（默认 10px）；`hideWhenOutOfView`（默认开）让锚点滚出可视区时暂时隐藏浮层（不改 `open`）。

:::note 与原版的差异
滚动引起裁剪变化时会重新判定翻转方向（原版会保持方向不变，直到下次打开），滚动过程中浮层可能因此跳动。
:::
最常用的调整：`position` 换弹出方位，`anchor={false}` 去掉指向锚点的箭头。

```tsx preview
import { useRef, useState, type ReactNode } from "react";
import { Button, Popup } from "ooui-react";

function TriggerPopup({
  children,
  buttonLabel,
  position = "below",
  anchor = true,
}: {
  children: ReactNode;
  buttonLabel: string;
  position?: "above" | "below" | "before" | "after";
  anchor?: boolean;
}) {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button ref={anchorRef} onClick={() => setOpen((o) => !o)}>
        {buttonLabel}
      </Button>
      <Popup
        open={open}
        onOpenChange={setOpen}
        container={anchorRef}
        autoClose
        autoCloseIgnore={anchorRef}
        padded
        width={200}
        position={position}
        anchor={anchor}
      >
        {children}
      </Popup>
    </>
  );
}

function App() {
  return (
    <div style={{ display: "flex", gap: 32, flexWrap: "wrap", padding: "72px 8px 8px" }}>
      <TriggerPopup buttonLabel="向上弹" position="above">
        position="above"
      </TriggerPopup>
      <TriggerPopup buttonLabel="向右弹" position="after">
        position="after"
      </TriggerPopup>
      <TriggerPopup buttonLabel="无箭头" anchor={false}>
        anchor=&#123;false&#125;
      </TriggerPopup>
    </div>
  );
}

export default App;
```

## 头部与底部

`head` 开启头部区，渲染 `icon` + `label` + 右上角关闭按钮（`hideCloseButton` 可隐藏）；`footer` 是底部区域。点关闭按钮、点外部、Escape 都通过 `onOpenChange(false)` 报告关闭。

```tsx preview
import { useRef, useState } from "react";
import { Button, Popup } from "ooui-react";

function App() {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <div style={{ padding: 60 }}>
      <Button ref={anchorRef} indicator="down" onClick={() => setOpen((o) => !o)}>
        带头部
      </Button>
      <Popup
        open={open}
        onOpenChange={setOpen}
        container={anchorRef}
        autoClose
        autoCloseIgnore={anchorRef}
        head
        icon="info"
        label="提示"
        padded
        width={240}
        footer={<div style={{ padding: 8 }}>底部说明文字</div>}
      >
        头部带图标、标题与关闭按钮，底部可放自定义内容。
      </Popup>
    </div>
  );
}

export default App;
```

## 悬浮触发

悬浮提示（术语解释、悬浮卡）是 Popup 的高频场景：开合完全由锚点的 `mouseenter` / `mouseleave` 驱动，并传 `autoClose={false}` 关掉外点与 Escape 通道。实现要点：浮层通过 portal 渲染到锚点子树之外，鼠标移向浮层时会先触发锚点的 `mouseleave`——收起前留一小段延时，鼠标移入浮层时取消；浮层内容再包一层自带 mouse 事件的元素，悬停浮层期间就不会收起。

```tsx preview
import { useRef, useState } from "react";
import { Popup } from "ooui-react";

function App() {
  const anchorRef = useRef<HTMLSpanElement>(null);
  const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const [open, setOpen] = useState(false);

  const show = () => {
    if (hideTimer.current) clearTimeout(hideTimer.current);
    setOpen(true);
  };
  const hideLater = () => {
    hideTimer.current = setTimeout(() => setOpen(false), 150);
  };

  return (
    <p style={{ padding: "56px 8px 8px" }}>
      ooui-react 是{" "}
      <span
        ref={anchorRef}
        onMouseEnter={show}
        onMouseLeave={hideLater}
        style={{ textDecoration: "underline dotted", cursor: "help" }}
      >
        OOUI
        <Popup
          open={open}
          onOpenChange={setOpen}
          container={anchorRef}
          position="above"
          autoClose={false}
          padded
          width={250}
        >
          <div onMouseEnter={show} onMouseLeave={hideLater}>
            OOUI（oojs-ui）的 React 重实现；悬停在词条或浮层上都保持展开。
          </div>
        </Popup>
      </span>
      {" "}
      的 React 重实现，样式直接复用原版主题。
    </p>
  );
}

export default App;
```

## API

| 属性                                  | 描述                                            | 类型                                                                       | 默认值        |
| ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ | ---------- |
| `open`                              | 是否打开（受控，传入后即进入受控模式；Popup 不自行打开）               | `boolean`                                                                | —          |
| `defaultOpen`                       | 非受控初始打开态                                      | `boolean`                                                                | `false`    |
| `onOpenChange`                      | 开合变化回调（点关闭按钮 / 点外部 / Escape / Tab 越界触发）       | `(open: boolean) => void`                                                | —          |
| `container`                         | 锚定容器（`ref` 或元素）；缺省定位到 body 左上角                | `RefObject<HTMLElement \| null> \| HTMLElement \| null`                  | —          |
| `position`                          | 弹出方位                                          | `'above' \| 'below' \| 'before' \| 'after'`                              | `'below'`  |
| `align`                             | 对齐方向（逻辑值随 RTL 换侧，`force-*` 始终是物理侧）            | `'center' \| 'forwards' \| 'backwards' \| 'force-left' \| 'force-right'` | `'center'` |
| `anchor`                            | 是否画指向锚点的箭头                                    | `boolean`                                                                | `true`     |
| `autoClose`                         | 点击外部 / Escape 自动关闭                            | `boolean`                                                                | —          |
| `autoCloseIgnore`                   | 自动关闭的忽略元素（如触发按钮）                              | `RefObject<HTMLElement \| null> \| HTMLElement \| null`                  | —          |
| `autoFlip`                          | 放不下时翻转到对侧                                     | `boolean`                                                                | `true`     |
| `hideWhenOutOfView`                 | 锚点滚出可视区时暂时隐藏                                  | `boolean`                                                                | `true`     |
| `containerPadding`                  | 钳制内边距（px）                                     | `number`                                                                 | `10`       |
| `head`                              | 渲染头部（icon + label + 关闭按钮）                     | `boolean`                                                                | `false`    |
| `hideCloseButton`                   | 配合 `head` 隐藏关闭按钮                              | `boolean`                                                                | —          |
| `padded`                            | 内容是否有内边距                                      | `boolean`                                                                | `false`    |
| `icon` / `label` / `invisibleLabel` | 头部图标 / 标题 / 标题视觉隐藏                            | —                                                                        | —          |
| `width` / `height`                  | 弹层尺寸（px）                                      | `number \| string`                                                       | `320` / —  |
| `footer`                            | 底部区域内容                                        | `ReactNode`                                                              | —          |
| `disabled`                          | 是否禁用                                          | `boolean`                                                                | `false`    |
| `...rest`                           | 原生 `div` 属性（`className`、`id`、`data-*` 等）写到浮层根 | `HTMLAttributes<HTMLDivElement>`                                         | —          |

## 另见

- 更省事的触发式浮层：[PopupButton](https://ooui-react.pages.dev/components/popup-button/index.md)
- 下拉选择（内含浮层菜单）：[Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md)
- 全局配置（浮层 portal 容器、视口留白、方向）：[OOUIProvider](https://ooui-react.pages.dev/guide/configuration.md)



---
url: https://ooui-react.pages.dev/components/popup-button/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# PopupButton 浮层按钮

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/PopupButton) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PopupButtonWidget.html "OO.ui.PopupButtonWidget")

弹出按钮：点击 [Button](https://ooui-react.pages.dev/components/button/index.md) 开合一个锚定到它的 [Popup](https://ooui-react.pages.dev/components/popup/index.md)，并内建“点按钮与浮层之外自动关闭”。多数“点按钮弹一块浮层”的场景用它即可，无需手写 Popup 的锚定与开合。

## 基本用法

```tsx preview
import { PopupButton } from "ooui-react";

function App() {
  return (
    <div style={{ padding: 40 }}>
      <PopupButton
        icon="language"
        defaultOpen
        popupContent={
          <div style={{ padding: 12 }}>浮层里可以放任意内容，比如一段说明或一组控件。</div>
        }
      >
        选项
      </PopupButton>
    </div>
  );
}

export default App;
```

## 受控开合

需要在外侧控制显隐时用 `open` / `onOpenChange`；点按钮、点外部、关闭按钮、Escape 都会回调 `onOpenChange`。

```tsx preview
import { useState } from "react";
import { PopupButton } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12, padding: 40 }}>
      <PopupButton
        open={open}
        onOpenChange={setOpen}
        head
        label="颜色"
        padded
        popupContent={<div style={{ padding: 12 }}>头部带标题与关闭按钮的浮层。</div>}
      >
        选颜色
      </PopupButton>
      <span>当前 open：{String(open)}</span>
    </div>
  );
}

export default App;
```

## 浮层定位

`position` / `align` / `anchor` / `autoFlip` / `width` / `height` / `padded` / `head` / `footer` / `container` 等浮层属性都会透传给内部 Popup（含义同 [Popup](https://ooui-react.pages.dev/components/popup/index.md)）。缺省以按钮为锚点、朝下弹出。

## API

| 属性                                                                                                                                                                            | 描述                                                                          | 类型                               | 默认值     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------- | ------- |
| `children`                                                                                                                                                                    | 按钮标签                                                                        | `ReactNode`                      | —       |
| `popupContent`                                                                                                                                                                | 浮层内容                                                                        | `ReactNode`                      | —       |
| `open`                                                                                                                                                                        | 浮层是否打开（受控）                                                                  | `boolean`                        | —       |
| `defaultOpen`                                                                                                                                                                 | 非受控初始打开态                                                                    | `boolean`                        | `false` |
| `onOpenChange`                                                                                                                                                                | 开合变化回调（点按钮 / 点外部 / 关闭按钮 / Escape）                                           | `(open: boolean) => void`        | —       |
| `onClick`                                                                                                                                                                     | 按钮点击回调（在切换开合前触发）                                                            | `(ev: ButtonClickEvent) => void` | —       |
| `label`                                                                                                                                                                       | 浮层头部标签，经 `head` 渲染（按钮标签是 `children`，二者分离）                                   | `ReactNode`                      | —       |
| `icon` / `flags` / `framed` / `title` / `accessKey` / `invisibleLabel` / `disabled`                                                                                           | 按钮侧属性，含义同 [Button](https://ooui-react.pages.dev/components/button/index.md) | —                                | —       |
| `position` / `align` / `anchor` / `autoFlip` / `head` / `hideCloseButton` / `padded` / `width` / `height` / `footer` / `container` / `hideWhenOutOfView` / `containerPadding` | 浮层侧属性，透传给内部 [Popup](https://ooui-react.pages.dev/components/popup/index.md) | —                                | —       |

`framed` 除决定按钮边框外，还会切换浮层的带框 / 无框外观。`label` 传给浮层头部，`invisibleLabel` 仅作用于按钮侧——原版 `PopupButtonWidget` 中两者属于按钮、popup 经独立配置传入。`active`、`autoClose`、`autoCloseIgnore` 由组件内部管理，不接受外部覆盖。

## 另见

- 底层浮层组件：[Popup](https://ooui-react.pages.dev/components/popup/index.md)
- 触发命令菜单的按钮：`ButtonMenuSelectWidget`
- 通用透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/components/icon/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Icon 图标

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Icon) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.IconWidget.html "OO.ui.IconWidget")

基础图标组件。

## 基本用法

```tsx preview
import { Icon } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Icon icon="image" title="image" />
      <Icon icon="alert" title="alert" />
      <Icon icon="add" title="add" />
      <Icon icon="arrowDown" title="arrowDown" />
    </div>
  );
}

export default App;
```

图标名取自 OOUI 主题的图标集，完整列表与分组见文末[「全部图标」](#全部图标)，上游对照见 [OOUI demos 的 icons 页](https://doc.wikimedia.org/oojs-ui/master/demos/?page=icons)。

## 变体

`flags` 命中主题的 image 变体类（`oo-ui-image-{flag}`）给图标着色。`invert` 面向深色背景，须自备深色底。

```tsx preview
import { Icon } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Icon icon="alert" flags="progressive" title="progressive" />
      <Icon icon="alert" flags="destructive" title="destructive" />
      <span style={{ display: "inline-block", background: "#222", padding: "4px 8px" }}>
        <Icon icon="alert" flags="invert" title="invert" />
      </span>
      <Icon icon="alert" flags="error" title="error" />
      <Icon icon="alert" flags="warning" title="warning" />
      <Icon icon="alert" flags="success" title="success" />
    </div>
  );
}

export default App;
```

## 禁用态

`disabled` 输出 `oo-ui-widget-disabled` 与 `aria-disabled`，同时按原版 `Widget` 的做法输出 `oo-ui-widget` 类链。

```tsx preview
import { Icon } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Icon icon="image" title="常规" />
      <Icon icon="image" disabled title="禁用" />
    </div>
  );
}

export default App;
```

## API

| 属性         | 描述                                                             | 类型                                | 默认值     |
| ---------- | -------------------------------------------------------------- | --------------------------------- | ------- |
| `icon`     | 图标名，取自主题图标集                                                    | `string`                          | —       |
| `flags`    | 附加标志，经 `oo-ui-flaggedElement-{flag}` 与 `oo-ui-image-{flag}` 输出 | `IconFlag \| IconFlag[]`          | `[]`    |
| `disabled` | 是否禁用                                                           | `boolean`                         | `false` |
| `...rest`  | 原生 `span` 属性（`className`、`title`、`aria-*`、事件等）直传根元素            | `HTMLAttributes<HTMLSpanElement>` | —       |

`IconFlag` 为 `'progressive' | 'destructive' | 'invert' | 'error' | 'warning' | 'success'`。

## 全部图标

点击图标可以复制名称。


共 293 个

### Icons – movement

arrowDownarrowNextarrowPreviousarrowUpcollapsedownTriangledraggabledraggableHorizontaldraggableVerticaldraggableXYdoubleChevronEnddoubleChevronStartexpandmovefirstlastnextprevioussortVerticalupTriangle

### Icons – content

articlearticlesarticleAddarticleCheckarticleDisambiguationarticleNotFoundarticleSearcharticlesSearcharticleRedirectasteriskdatabasediedownloadfolderPlaceholderhistoryinfoinfoFilledmergeqrCoderobotshareshareAndroidshareIOSspecialPagestabstagupdateuploadwindow

### Icons – alerts

alertbellbellOutlineerrorlevelNonelevelOnelevelTwolevelThreelivemessagenoticespeechBubblespeechBubbleAlertspeechBubbleAddspeechBubblessuccesstray

### Icons – interactions

addbrowsercancelcheckcheckAllclearclockcloseconfigureellipsisverticalEllipsisfeedbackfilterfunnelfunnelMatchhandheartheartOutlinehelphelpNoticehelpNoticeFilledhomekeykeyboardlightbulblightbulbOutlinelightbulbDashedlogInlogOutmagicWandnetworknetworkOffnewWindowpageSettingspowerprinterreloadrestartrotatesearchsettingssubtract

### Icons – moderation

bookmarkOutlinebookmarkblockblockOutlineunBlockflagunFlaglockunLockrestorestarhalfStarunStartrashpushPinongoingConversationsuggestedInvestigations

### Icons – editing-core

editeditLockeditUndolinkunLinklinkExternallinkSecureredoundo

### Icons – editing-styling

biggersmallersubscriptsuperscriptboldhighlightitalicstrikethroughunderlinetextLanguagetextDirLTRtextDirRTLtextStyle

### Icons – editing-functions

functionfunctionArgumentinstanceliteral

### Icons – editing-list

indentlistBulletlistNumberedoutdent

### Icons – editing-advanced

alignCenteralignLeftalignRightattachmentcalendarcodecopycutdiffshieroglyphimageLayoutBasicimageLayoutFrameimageLayoutFramelessimageLayoutThumbnaillabFlasklanguagelayoutmarkupmathematicsmathematicsDisplayBlockmathematicsDisplayDefaultmathematicsDisplayInlinenewlinenoWikiTextocroutlinepalettepastepuzzlequotessandboxsearchCaseSensitivesearchDiacriticssearchRegularExpressionsignaturespecialCharactertabletableAddColumnAftertableAddColumnBeforetableAddRowAftertableAddRowBeforetableCaptiontableMergeCellstableMoveColumnAftertableMoveColumnBeforetableMoveRowAftertableMoveRowBeforetemplateAddtranslationwikiText

### Icons – editing-citation

bookjournalnewspaperreferencereferenceExistingreferences

### Icons – media

camerachartchartBarchartLinechartPiechartScatterexitFullscreenfullScreenimageimageAddimageBrokenimageLockimageGallerymicrophonemusicalScorepausepictureInPictureplaystopsubtitlethreeDimensionalvolumeDownvolumeOffvolumeUpzoomInzoomOut

### Icons – location

globemapmapPinmapPinAddmapTrail

### Icons – user

bookmarkListuserAdduserAnonymoususerAvataruserAvatarOutlineuserBlockeduserChatuserContributionsuserGroupuserMentoruserPagesuserRightsuserTalkuserTemporaryuserTemporaryLocationwatchlist

### Icons – layout

menurecentChangestextFlowtextSummaryviewCompactviewDetails

### Icons – accessibility

appearancebrighthalfBrightnotBrighteyeeyeClosedmoonlargerTextsmallerTextuniversalDesignvisionSimulator

### Icons – wikimedia

logoCClogoCodexlogoMediaWikilogoMetaWikilogoWikibookslogoWikidatalogoWikifunctionslogoWikimedialogoWikimediaCommonslogoWikimediaDiscoverylogoWikinewslogoWikipedialogoWikiquotelogoWikisourcelogoWikispecieslogoWikiversitylogoWikivoyagelogoWiktionary


---
url: https://ooui-react.pages.dev/components/indicator/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Indicator 指示器

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Indicator) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.IndicatorWidget.html "OO.ui.IndicatorWidget")

指示器组件，通常在其他组件内渲染表示特定含义。

## 基本用法

取值有 `up`、`down`、`clear`（关闭叉）、`required`（必填星号）。

```tsx preview
import { Indicator } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Indicator indicator="up" title="up" />
      <Indicator indicator="down" title="down" />
      <Indicator indicator="clear" title="clear" />
      <Indicator indicator="required" title="required" />
    </div>
  );
}

export default App;
```

## 禁用态

`disabled` 输出 `oo-ui-widget-disabled` 与 `aria-disabled`，主题把指示器调淡。

```tsx preview
import { Indicator } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Indicator indicator="down" title="常规" />
      <Indicator indicator="down" disabled title="禁用" />
    </div>
  );
}

export default App;
```

## 结构

组件渲染单个 `<span>`，`ref` 指向它，未声明的属性透传到该元素。指示器本身是无文本的装饰性图形，需要让读屏器读出含义时，请在宿主元素上给出 `aria-label`。

## API

| 属性          | 描述                                                  | 类型                                        | 默认值     |
| ----------- | --------------------------------------------------- | ----------------------------------------- | ------- |
| `indicator` | 指示器种类                                               | `'up' \| 'down' \| 'clear' \| 'required'` | —       |
| `disabled`  | 是否禁用                                                | `boolean`                                 | `false` |
| `...rest`   | 原生 `span` 属性（`className`、`title`、`aria-*`、事件等）直传根元素 | `HTMLAttributes<HTMLSpanElement>`         | —       |



---
url: https://ooui-react.pages.dev/components/label/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Label 标签

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Label) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.LabelWidget.html "OO.ui.LabelWidget")

独立的表单标签，需要单独摆放一个标签时使用。

## 关联表单控件

点击标签聚焦/激活控件依赖原生 `<label>`
 的 `htmlFor`
 关联。关联方式因组件而异，`id`
 的写入位置不对会静默失效：
- **TextInput 系**（含 MultilineTextInput、NumberInput、ComboBoxInput 等）：`id` 写在根 div 上；要写在原生输入元素上，须经 `inputProps={{ id }}` 写入。
- **CheckboxInput / RadioInput**：没有 `inputProps` 通道，用专用的 `inputId` prop——它直接写在原生 `<input>` 上。

表单里这类关联由 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 自动处理，无需手写。

:::note 表单里更推荐用 FieldLayout
表单中「标签 + 控件」的布局、对齐与关联激活通常交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 统一处理，标签与控件各自单独书写 `htmlFor`/`id` 适合自由拼装的场景。
:::

```tsx preview
import { CheckboxInput, Label, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <Label htmlFor="label-demo-username">用户名</Label>
      <TextInput inputProps={{ id: "label-demo-username" }} placeholder="点上方标签聚焦这里" />
      <Label htmlFor="label-demo-agree">同意条款</Label>
      <CheckboxInput inputId="label-demo-agree" />
    </div>
  );
}

export default App;
```

## 视觉隐藏与标题

`invisibleLabel` 把标签内容视觉隐藏（裁剪而非移除，读屏器仍可读）。`title` 未显式给出时以标签文本兜底。

```tsx preview
import { Label } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Label>常规标签</Label>
      <Label invisibleLabel>仅读屏可见的标签</Label>
    </div>
  );
}

export default App;
```

## 禁用态

`disabled` 输出 `oo-ui-widget-disabled` 与 `aria-disabled`，主题把标签调淡。

```tsx preview
import { Label } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <Label>常规标签</Label>
      <Label disabled>禁用标签</Label>
    </div>
  );
}

export default App;
```

## 结构

组件渲染单个 `<label>`，`ref` 指向它，未声明的属性（`htmlFor`、`title`、事件等）直传该元素。

## API

| 属性               | 描述                                                    | 类型                                 | 默认值     |
| ---------------- | ----------------------------------------------------- | ---------------------------------- | ------- |
| `children`       | 标签内容                                                  | `ReactNode`                        | —       |
| `invisibleLabel` | 视觉隐藏标签（保留可访问名称）                                       | `boolean`                          | `false` |
| `disabled`       | 是否禁用                                                  | `boolean`                          | `false` |
| `...rest`        | 原生 `label` 属性（`htmlFor`、`title`、`className`、事件等）直传根元素 | `HTMLAttributes<HTMLLabelElement>` | —       |

## 另见

- 表单字段的标签布局与关联：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 输入组件自带的内嵌标签：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 的「标签」一节



---
url: https://ooui-react.pages.dev/components/progress-bar/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ProgressBar 进度条

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ProgressBar) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ProgressBarWidget.html "OO.ui.ProgressBarWidget")

进度条。

## 确定进度

`progress`
 取 0–100 的数值，超出范围会被钳制到 `[0, 100]`
（原版不钳制，`NaN`
 会直接输出非法的宽度与属性值）。
```tsx preview
import { useState } from "react";
import { Button, ProgressBar } from "ooui-react";

function App() {
  const [progress, setProgress] = useState(40);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <ProgressBar progress={progress} />
      <div style={{ display: "flex", gap: 8 }}>
        <Button onClick={() => setProgress((p) => Math.max(0, p - 10))}>-10</Button>
        <Button onClick={() => setProgress((p) => Math.min(100, p + 10))}>+10</Button>
      </div>
    </div>
  );
}

export default App;
```

## 不定进度

`progress={false}`（也是缺省值）表示总时长未知的“进行中”，填充条以滑动动画示意，不给出具体数值。

```tsx preview
import { ProgressBar } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <ProgressBar />
    </div>
  );
}

export default App;
```

## 进度随异步任务推进

典型用法是在任务开始时置为不定进度，拿到可量化的进展后切换为确定进度。

```tsx preview
import { useEffect, useState } from "react";
import { Button, ProgressBar } from "ooui-react";

function App() {
  const [state, setState] = useState<"idle" | "starting" | "running" | "done">("idle");
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    if (state !== "running") {
      return;
    }
    const timer = setInterval(() => {
      setProgress((p) => {
        if (p >= 100) {
          setState("done");
          return 100;
        }
        return p + 10;
      });
    }, 300);
    return () => clearInterval(timer);
  }, [state]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <ProgressBar
        progress={state === "starting" || state === "idle" ? false : progress}
      />
      <Button
        disabled={state === "starting" || state === "running"}
        onClick={() => {
          setProgress(0);
          setState("starting");
          setTimeout(() => setState("running"), 800);
        }}
      >
        开始任务
      </Button>
    </div>
  );
}

export default App;
```

## API

| 属性         | 描述                                                          | 类型                               | 默认值     |
| ---------- | ----------------------------------------------------------- | -------------------------------- | ------- |
| `progress` | 进度百分比（0–100，越界钳制）；`false` 为不定进度（滑动动画），非有限值（如 `NaN`）也按不定进度处理 | `number \| false`                | `false` |
| `disabled` | 是否禁用                                                        | `boolean`                        | `false` |
| `...rest`  | 原生 `div` 属性（`className`、`id`、`aria-label` 等）直传根元素           | `HTMLAttributes<HTMLDivElement>` | —       |

进度条只读、不可聚焦，用 `aria-valuenow` / `aria-valuemin` / `aria-valuemax` 播报数值；确定进度下 `aria-valuenow` 为钳制后的值，不定进度下不输出该属性。要给进度条补充可读名称，用 `aria-label`。

## 另见

- 通用透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/components/message/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Message 消息

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Message) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MessageWidget.html "OO.ui.MessageWidget")

行内消息提示，类型有 `notice` / `error` / `warning` / `success`。

## 基本用法

类型决定默认图标与配色，也可用 `icon` 覆盖。

```tsx preview
import { Message } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <Message>Notice：这是一条说明信息</Message>
      <Message type="success">Success：保存成功</Message>
      <Message type="warning">Warning：即将超出配额</Message>
      <Message type="error">Error：保存失败，请重试</Message>
      <Message icon="help">自定义图标（覆盖类型默认图标）</Message>
    </div>
  );
}

export default App;
```

## 内联形态

`inline` 渲染为不带边框的内联消息，适合嵌在正文段落中；块级（缺省）带边框与内边距。内联消息不渲染关闭按钮。

```tsx preview
import { Message } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <Message inline>Inline：这是一条内联说明</Message>
      <Message inline type="error">
        Inline error：这是一条内联错误
      </Message>
    </div>
  );
}

export default App;
```

## 关闭按钮

:::warning 与原版的差异
原版点击关闭按钮即自行隐藏；本工程 `onClose`
 只报告「点击了关闭按钮」，组件不保存显隐状态——**必须在回调里把消息卸载或隐藏**
，没有处理回调时消息无法关闭。
:::
```tsx preview
import { useState } from "react";
import { Button, Message } from "ooui-react";

function App() {
  const [visible, setVisible] = useState(true);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      {visible ? (
        <Message type="warning" showClose onClose={() => setVisible(false)}>
          点右侧 × 关闭（由 onClose 卸载）
        </Message>
      ) : (
        <Button onClick={() => setVisible(true)}>重新显示</Button>
      )}
    </div>
  );
}

export default App;
```

## API

| 属性               | 描述                                            | 类型                                              | 默认值        |
| ---------------- | --------------------------------------------- | ----------------------------------------------- | ---------- |
| `children`       | 消息正文                                          | `ReactNode`                                     | —          |
| `type`           | 消息类型（非法值回退 `notice`）                          | `'notice' \| 'error' \| 'warning' \| 'success'` | `'notice'` |
| `icon`           | 自定义图标，覆盖类型默认图标                                | `string`                                        | 类型默认       |
| `inline`         | 内联展示（`false` 时为带边框的块级消息）                      | `boolean`                                       | `false`    |
| `showClose`      | 是否显示关闭按钮（`inline` 时不渲染）                       | `boolean`                                       | `false`    |
| `onClose`        | 点击关闭按钮的回调；组件不自行隐藏，须在此卸载/隐藏消息                  | `() => void`                                    | —          |
| `invisibleLabel` | 正文视觉隐藏但保留可访问名称                                | `boolean`                                       | `false`    |
| `disabled`       | 是否禁用（输出 `aria-disabled`）                      | `boolean`                                       | `false`    |
| `...rest`        | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素 | `HTMLAttributes<HTMLDivElement>`                | —          |

无障碍：`type="error"` 渲染为 `role="alert"` 打断式播报，其余类型为 `aria-live="polite"`。

## 另见

- 错误面板中的错误渲染：[ProcessDialog](https://ooui-react.pages.dev/components/process-dialog/index.md)
- 传值约定（`onClose` 只通知关闭、显隐由调用方负责）：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)



---
url: https://ooui-react.pages.dev/components/text-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# TextInput 文本输入

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/TextInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TextInputWidget.html "OO.ui.TextInputWidget")

单行文本输入框，同时也是 [MultilineTextInput](https://ooui-react.pages.dev/components/multiline-text-input/index.md)、[NumberInput](https://ooui-react.pages.dev/components/number-input/index.md)、[SearchInput](https://ooui-react.pages.dev/components/search-input/index.md) 等输入组件的基础。

## 基本用法

传入 `value` 后即进入受控模式，否则组件自行维护输入状态，`defaultValue` 只作初始值。`onChange` 为值优先签名，第一个参数就是新的字符串值。

```tsx preview
import { useState } from "react";
import { TextInput } from "ooui-react";

function App() {
  const [text, setText] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput value={text} onChange={setText} placeholder="受控输入" />
      <div>当前值：{text || "（空）"}</div>
      <TextInput defaultValue="非受控，组件自己记住输入" />
    </div>
  );
}

export default App;
```

## 类型

`type` 同时决定 `<input>` 的 `type` 属性与根元素的 `oo-ui-textInputWidget-type-{type}` 类，取值限定在主题有样式的白名单 `text`、`password`、`email`、`url`、`number`、`search`，非法值回退为 `text`。

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput type="password" defaultValue="secret" labelPosition="before" label="密码" />
      <TextInput type="email" placeholder="you@example.com" />
    </div>
  );
}

export default App;
```

## 标签

`label` 是字段标签文本，`labelPosition` 控制在输入框前（`before`）还是后（`after`，默认）。标签视觉隐藏时打开 `invisibleLabel`：保留可访问名称，`title` 未显式给出时以标签文本兜底。

:::note 带标签的表单字段更推荐用 FieldLayout
把标签写在输入框自身上适合独立摆放的场景；在表单里，标签、对齐与「点标签聚焦输入框」的联动通常交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)，字段控件本身不写 `label`。
:::

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput label="用户名" labelPosition="before" defaultValue="alice" />
      <TextInput label="仅图标可读的标签" invisibleLabel icon="user" />
    </div>
  );
}

export default App;
```

## 图标与指示器

`icon` 渲染在输入框一侧（见 [Icon](https://ooui-react.pages.dev/components/icon/index.md)），`indicator` 渲染在另一侧（见 [Indicator](https://ooui-react.pages.dev/components/indicator/index.md)）。未显式给 `indicator` 且 `required` 为真时，自动回退为 `required` 指示器。

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput icon="search" placeholder="带图标" />
      <TextInput indicator="down" readOnly defaultValue="带指示器（只读）" />
      <TextInput required placeholder="必填，自动显示 required 指示器" />
    </div>
  );
}

export default App;
```

## 软校验

`validate` 是软反馈：值不满足时输入元素输出 `aria-invalid`、根元素叠加 invalid 标志类，**但不改写值**。缺省只有浏览器原生约束（如 `required`）参与提交校验。触发时机为值变更（防抖 250ms）、失焦后立即校验、聚焦时清除。

`validate` 接受的形态：正则（`test` 判定）、函数（返回布尔或 `Promise<boolean>`）、或符号名 `'non-empty'`（非空）、`'integer'`（纯数字）。

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput validate="non-empty" placeholder="清空后失焦会标红" />
      <TextInput validate="integer" placeholder="只接受纯数字" />
      <TextInput validate={(v) => v.length >= 6} placeholder="至少 6 个字符" />
    </div>
  );
}

export default App;
```

## 禁用与只读

`disabled` 输出 `oo-ui-widget-disabled` 与 `aria-disabled`（不写原生 `disabled`），输入框不可聚焦、不可输入。`readOnly` 保留聚焦与可选中复制，仅禁止修改。

```tsx preview
import { TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <TextInput disabled defaultValue="禁用" />
      <TextInput readOnly defaultValue="只读，可选中复制" />
    </div>
  );
}

export default App;
```

## 属性写入位置

组件根是 `<div>`、输入元素是 `<input>`，写入位置规则如下（输入类组件通用）：

- props 的 `...rest`（`id`、`className`、`data-*` 等未声明属性）写入根 div；要写到原生 `<input>` 上的属性（如 `role`、`aria-*`、`autoComplete`）必须通过 `inputProps` 传入。
- `inputRef` 指向内部 `<input>`（组件 `ref` 指向根 div），聚焦输入框用 `inputRef`。
- `tabIndex`、`title`、`dir`、`accessKey` 由组件接管，直接写入 `<input>`（对齐原版写入位置），不通过 `rest`。

`inputProps` 里的 `onChange` / `onBlur` / `onFocus` 会串联在组件自身逻辑之后，不会截断值的处理流程与软校验。

```tsx preview
import { useRef } from "react";
import { Button, TextInput } from "ooui-react";

function App() {
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <TextInput
        inputRef={inputRef}
        inputProps={{ autoComplete: "off", "aria-label": "自定义标签" }}
        placeholder="autoComplete 走 inputProps"
      />
      <Button onClick={() => inputRef.current?.focus()}>聚焦</Button>
    </div>
  );
}

export default App;
```

## API

| 属性                         | 描述                                                           | 类型                                                                                       | 默认值         |
| -------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ----------- |
| `value`                    | 输入值（受控，传入后即进入受控模式）                                           | `string`                                                                                 | —           |
| `defaultValue`             | 非受控初始值                                                       | `string`                                                                                 | —           |
| `onChange`                 | 值变化回调（值优先，含原生事件）                                             | `ChangeHandler<string, HTMLInputElement>`                                                | —           |
| `type`                     | 输入类型，见[类型](#类型)白名单，非法值回退 `text`                              | `string`                                                                                 | `'text'`    |
| `placeholder`              | 输入提示                                                         | `string`                                                                                 | —           |
| `maxLength`                | 最大长度                                                         | `number`                                                                                 | —           |
| `label` / `invisibleLabel` | 字段标签 / 标签视觉隐藏（保留可访问名称）                                       | `ReactNode` / `boolean`                                                                  | — / `false` |
| `labelPosition`            | 标签位置                                                         | `'before' \| 'after'`                                                                    | `'after'`   |
| `icon`                     | 图标名                                                          | `string`                                                                                 | —           |
| `indicator`                | 指示器（`required` 且未显式给时回退为 required）                           | `'up' \| 'down' \| 'clear' \| 'required'`                                                | —           |
| `required`                 | 必填（原生 `required` 属性，参与浏览器校验；同时输出 `aria-required`）            | `boolean`                                                                                | `false`     |
| `validate`                 | 软校验，见[软校验](#软校验)                                             | `RegExp \| ((value: string) => boolean \| Promise<boolean>) \| 'non-empty' \| 'integer'` | —           |
| `readOnly`                 | 只读                                                           | `boolean`                                                                                | `false`     |
| `disabled`                 | 是否禁用                                                         | `boolean`                                                                                | `false`     |
| `flags`                    | 根元素附加标志（软校验的 invalid 标志叠加其上）                                 | `string \| string[]`                                                                     | —           |
| `name`                     | 表单提交字段名（写入 `<input>`）                                        | `string`                                                                                 | —           |
| `accessKey`                | 快捷键（写入 `<input>`）                                            | `string`                                                                                 | —           |
| `inputRef`                 | 内部 `<input>` 的引用                                             | `Ref<HTMLInputElement>`                                                                  | —           |
| `inputProps`               | 原生 `<input>` 的附加属性通道；`onChange`/`onBlur`/`onFocus` 串联在组件逻辑之后 | `object`                                                                                 | —           |
| `indicatorProps`           | 指示器元素的附加属性                                                   | `object`                                                                                 | —           |
| `...rest`                  | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素                | `HTMLAttributes<HTMLDivElement>`                                                         | —           |

`required`
 为真时，本组件在原生 `<input>`
 上同时输出 `aria-required`
（原版只写原生 `required`
 属性）。该行为覆盖继承自 TextInput 的组件（MultilineTextInput、NumberInput、ComboBoxInput 同样如此）；非文本形态（Dropdown、Checkbox、Radio、SelectFile）不输出。
## 另见

- 值如何在组件与状态之间流动：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)
- 所有组件共有的透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)
- 多行、数字、搜索等形态：[MultilineTextInput](https://ooui-react.pages.dev/components/multiline-text-input/index.md)、[NumberInput](https://ooui-react.pages.dev/components/number-input/index.md)、`SearchInput`



---
url: https://ooui-react.pages.dev/components/multiline-text-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# MultilineTextInput 多行输入

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/MultilineTextInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MultilineTextInputWidget.html "OO.ui.MultilineTextInputWidget")

多行文本输入框，输入能力与 [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 一致。

## 基本用法

```tsx preview
import { useState } from "react";
import { MultilineTextInput } from "ooui-react";

function App() {
  const [text, setText] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <MultilineTextInput value={text} onChange={setText} placeholder="受控多行输入" />
      <div>当前 {text.length} 个字符</div>
      <MultilineTextInput defaultValue="非受控，组件自己记住输入" />
    </div>
  );
}

export default App;
```

## 行数与自动高度

`rows` 是最小行数（写入 `<textarea>` 的 `rows` 属性）。开启 `autosize` 后高度随内容自适应：到 `maxRows` 行封顶，超出转为内部滚动；`maxRows` 缺省为 `max(2 × rows, 10)`。

不开 `autosize` 时高度固定为 `rows` 行，内容超出直接出现滚动条。

自动高度的重测另有尺寸观察兜底：字体加载、容器或宽度变化后也会重算高度（原版只在输入时重测，高度会滞后）。
```tsx preview
import { MultilineTextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <MultilineTextInput autosize rows={2} placeholder="autosize：随内容长高" />
      <MultilineTextInput
        rows={3}
        defaultValue={"第一行\n第二行\n第三行\n第四行\n第五行"}
      />
    </div>
  );
}

export default App;
```

## 滚动条让位

出现垂直滚动条时，指示器与位于输入框之后的标签会自动偏移滚动条宽度让位，避免压在滚动条上（多行输入始终启用，无需配置）。当输入方向与页面方向不一致时（如 LTR 页面配 `dir='rtl'`
 输入），偏移会整体取消，避免原版在该场景下出现的标签拉伸变形。
## 换行与 Enter

Enter 始终插入换行。

:::note 与原版的差异
原版的 `allowLinebreaks`
 配置（阻止换行、把换行清洗为空格）与配套的 `enter`
 事件（Ctrl/Cmd+Enter 触发）在本工程不提供——需要限制换行时，在 `onChange`
 里清洗值即可。
:::
## 与 TextInput 同源的能力

以下行为与 TextInput 完全一致，不再重复展开：

- 标签：`label` / `labelPosition` / `invisibleLabel`；
- 图标与指示器：`icon`、`indicator`，未显式给 `indicator` 且 `required` 为真时自动回退 required 指示器；
- 软校验：`validate`（正则 / 函数 / `'non-empty'` / `'integer'`），标红不改值；
- 状态：`maxLength`、`readOnly`（可聚焦，可复制）、`disabled`。

```tsx preview
import { MultilineTextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <MultilineTextInput label="简介" labelPosition="before" placeholder="最多 20 字" maxLength={20} />
      <MultilineTextInput validate="non-empty" placeholder="清空后失焦会标红" />
    </div>
  );
}

export default App;
```

## 属性写入位置

组件根是不可聚焦的 `<div>`，输入元素是 `<textarea>`。写入规则与 [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 相同：

- props 的 `...rest` 写在根 div 上；要写到原生 `<textarea>` 的属性（如 `role`、`aria-*`）走 `inputProps` 通道，其 `onChange`/`onBlur`/`onFocus` 串联在组件自身逻辑之后。
- `inputRef` 指向内部 `<textarea>`（组件 `ref` 指向根 div），聚焦输入框用 `inputRef`。
- `tabIndex`、`title`、`dir`、`accessKey`、`name` 由组件接管，直接写在 `<textarea>` 上（与原版写入位置一致），不走 `rest`。

## API

| 属性                         | 描述                                                                                                                             | 类型                                                                                       | 默认值                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------- |
| `value`                    | 输入值（受控，传入后即进入受控模式）                                                                                                             | `string`                                                                                 | —                   |
| `defaultValue`             | 非受控初始值                                                                                                                         | `string`                                                                                 | —                   |
| `onChange`                 | 值变化回调（值优先，含原生事件）                                                                                                               | `ChangeHandler<string, HTMLTextAreaElement>`                                             | —                   |
| `rows`                     | 最小行数                                                                                                                           | `number`                                                                                 | —                   |
| `maxRows`                  | autosize 的高度上限（行）                                                                                                              | `number`                                                                                 | `max(2 × rows, 10)` |
| `autosize`                 | 是否随内容自动调高                                                                                                                      | `boolean`                                                                                | `false`             |
| `placeholder`              | 输入提示                                                                                                                           | `string`                                                                                 | —                   |
| `maxLength`                | 最大长度                                                                                                                           | `number`                                                                                 | —                   |
| `label` / `invisibleLabel` | 字段标签 / 标签视觉隐藏（保留可访问名称）                                                                                                         | `ReactNode` / `boolean`                                                                  | — / `false`         |
| `labelPosition`            | 标签位置                                                                                                                           | `'before' \| 'after'`                                                                    | `'after'`           |
| `icon`                     | 图标名                                                                                                                            | `string`                                                                                 | —                   |
| `indicator`                | 指示器（`required` 且未显式给时回退为 required）                                                                                             | `'up' \| 'down' \| 'clear' \| 'required'`                                                | —                   |
| `required`                 | 必填（原生 `required` 属性，参与浏览器校验）                                                                                                   | `boolean`                                                                                | `false`             |
| `validate`                 | 软校验（正则 / 函数 / 符号名），见 [TextInput 的软校验](https://ooui-react.pages.dev/components/text-input/index.md#%E8%BD%AF%E6%A0%A1%E9%AA%8C) | `RegExp \| ((value: string) => boolean \| Promise<boolean>) \| 'non-empty' \| 'integer'` | —                   |
| `readOnly`                 | 只读（保留聚焦，内容可选中复制）                                                                                                               | `boolean`                                                                                | `false`             |
| `disabled`                 | 是否禁用                                                                                                                           | `boolean`                                                                                | `false`             |
| `flags`                    | 根元素附加标志（invalid 标志叠加其上）                                                                                                        | `string \| string[]`                                                                     | —                   |
| `name`                     | 表单提交字段名（写在 `<textarea>`）                                                                                                       | `string`                                                                                 | —                   |
| `accessKey`                | 快捷键（写在 `<textarea>`）                                                                                                           | `string`                                                                                 | —                   |
| `inputRef`                 | 内部 `<textarea>` 的引用                                                                                                            | `Ref<HTMLTextAreaElement>`                                                               | —                   |
| `inputProps`               | 原生 `<textarea>` 的附加属性通道；`onChange`/`onBlur`/`onFocus` 串联在组件逻辑之后                                                                | `object`                                                                                 | —                   |
| `indicatorProps`           | 指示器元素的附加属性                                                                                                                     | `object`                                                                                 | —                   |
| `...rest`                  | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素                                                                                  | `HTMLAttributes<HTMLDivElement>`                                                         | —                   |

## 另见

- 单行形态与软校验的完整说明：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md)
- 值如何在组件与状态之间流动：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)
- 所有组件共有的透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/components/number-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# NumberInput 数字输入

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/NumberInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.NumberInputWidget.html "OO.ui.NumberInputWidget")

数字输入框，输入能力与 [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 一致。

## 基本用法

值类型为 `number | ''`——清空输入或键入非数字内容时即无值。

```tsx preview
import { useState } from "react";
import { NumberInput } from "ooui-react";

function App() {
  const [value, setValue] = useState<number | "">(5);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <NumberInput value={value} onChange={setValue} min={0} max={10} />
      <div>当前值：{value === "" ? "（空）" : value}</div>
      <NumberInput defaultValue={1} />
    </div>
  );
}

export default App;
```

## 步进

步进有以下通道，日常步距都是 `buttonStep`：

- **加减按钮**：`showButtons`（默认开启）渲染两侧按钮，是纯装饰元素（`aria-hidden`、不参与 Tab 序），点击不会抢走输入框焦点；`disabled` 或 `readOnly` 时一并禁用。
- **键盘**：↑/↓ 按 `buttonStep` 步进，PgUp/PgDn 按 `pageStep`（默认 `buttonStep` 的 10 倍）。
- **滚轮**：仅输入框聚焦时生效（上滚加、下滚减），并阻止页面滚动；悬停未聚焦时不拦截，避免滚动页面误改数值。

步进时数值会被规整：结果钳制到 `[min, max]` 区间并取 `step` 的倍数；当前无值（`''`）时步进从 0 起步。规整只发生在步进时——直接键入的越界值或非 `step` 倍数原样保留，由软校验标红。

## 范围与步距

- `min` / `max`：合法区间，同时写成 `<input>` 的 `min`/`max` 属性。
- `step`：合法性步距——值必须是它的倍数才算合法；缺省不限制小数（属性输出 `step="any"`）。
- `buttonStep`：按钮 / 方向键 / 滚轮的实际步距，缺省取 `step`（再缺省为 1）。
- `pageStep`：PgUp/PgDn 的步距，缺省为 `buttonStep` 的 10 倍。

## 软校验

内置合法性判定，值不满足时输入元素输出 `aria-invalid`、根元素叠加 invalid 标志类，**但不改写值**：

- 空值：`required` 时非法，且挂载时就校验（空值 + 必填，加载就标红）；
- 非有限数值、不是 `step` 的倍数、超出 `[min, max]` 区间。

触发时机与 TextInput 的软校验一致：值变更（防抖）、失焦即校验、聚焦时清除；`min`/`max`/`step`/`required` 变化后立即重新校验。

```tsx preview
import { NumberInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <NumberInput required placeholder="必填，空值加载即标红" />
      <NumberInput min={0} max={10} step={2} defaultValue={7} placeholder="step=2，7 不是 2 的倍数" />
    </div>
  );
}

export default App;
```

## 标签与图标

`label` / `labelPosition` / `invisibleLabel` 的用法与 TextInput 相同；未显式给 `indicator` 且 `required` 为真时，自动回退为 required 指示器。

```tsx preview
import { NumberInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <NumberInput label="数量" labelPosition="before" defaultValue={1} />
      <NumberInput required placeholder="必填，自动显示 required 指示器" />
    </div>
  );
}

export default App;
```

## 属性写入位置

组件根是不可聚焦的 `<div>`，输入元素是 `<input type="number">`（包在 `oo-ui-numberInputWidget-field` 容器里；开启按钮时根元素带 `oo-ui-numberInputWidget-buttoned` 类）。写入规则与 [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 相同：

- props 的 `...rest` 写在根 div 上；要写到原生 `<input>` 的属性（如 `role`、`aria-*`、`autoComplete`）走 `inputProps` 通道，其 `onChange`/`onBlur`/`onFocus` 串联在组件自身逻辑之后。
- `inputRef` 指向内部 `<input>`（组件 `ref` 指向根 div），聚焦输入框用 `inputRef`。
- `tabIndex`、`title`、`dir`、`accessKey`、`name` 由组件接管，直接写在 `<input>` 上（与原版写入位置一致），不走 `rest`。

## API

| 属性                           | 描述                                                           | 类型                                              | 默认值               |
| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | ----------------- |
| `value`                      | 输入值（受控，传入后即进入受控模式）；`''` 表示无值                                 | `number \| ''`                                  | —                 |
| `defaultValue`               | 非受控初始值                                                       | `number \| ''`                                  | —                 |
| `onChange`                   | 值变化回调（值优先，含原生事件）                                             | `ChangeHandler<number \| '', HTMLInputElement>` | —                 |
| `showButtons`                | 是否显示两侧步进按钮                                                   | `boolean`                                       | `true`            |
| `min` / `max`                | 最小值 / 最大值（步进钳制 + 软校验边界）                                      | `number`                                        | —                 |
| `step`                       | 合法性步距（值需为其倍数），缺省不限制小数                                        | `number`                                        | —                 |
| `buttonStep`                 | 按钮 / ↑↓ / 滚轮的步距                                              | `number`                                        | `step ?? 1`       |
| `pageStep`                   | PgUp/PgDn 的步距                                                | `number`                                        | `buttonStep × 10` |
| `allowInteger` / `isInteger` | 废弃兼容配置：仅允许整数（强制 `step={1}`），设置后有开发期告警                        | `boolean`                                       | —                 |
| `placeholder`                | 输入提示                                                         | `string`                                        | —                 |
| `label` / `invisibleLabel`   | 字段标签 / 标签视觉隐藏（保留可访问名称）                                       | `ReactNode` / `boolean`                         | — / `false`       |
| `labelPosition`              | 标签位置                                                         | `'before' \| 'after'`                           | `'after'`         |
| `icon`                       | 图标名                                                          | `string`                                        | —                 |
| `indicator`                  | 指示器（`required` 且未显式给时回退为 required）                           | `'up' \| 'down' \| 'clear' \| 'required'`       | —                 |
| `required`                   | 必填（原生 `required` 属性，空值即非法，参与浏览器校验）                           | `boolean`                                       | `false`           |
| `readOnly`                   | 只读（保留聚焦，禁止修改与步进）                                             | `boolean`                                       | `false`           |
| `disabled`                   | 是否禁用                                                         | `boolean`                                       | `false`           |
| `flags`                      | 根元素附加标志（invalid 标志叠加其上）                                      | `string \| string[]`                            | —                 |
| `name`                       | 表单提交字段名（写在 `<input>`）                                        | `string`                                        | —                 |
| `accessKey`                  | 快捷键（写在 `<input>`）                                            | `string`                                        | —                 |
| `inputRef`                   | 内部 `<input>` 的引用                                             | `Ref<HTMLInputElement>`                         | —                 |
| `inputProps`                 | 原生 `<input>` 的附加属性通道；`onChange`/`onBlur`/`onFocus` 串联在组件逻辑之后 | `object`                                        | —                 |
| `...rest`                    | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素                | `HTMLAttributes<HTMLDivElement>`                | —                 |

## 与原版的差异

- `step` / `buttonStep` / `pageStep` 传非正值时，原版在构造期直接抛错；本工程开发期告警一次，并按给定值照常渲染。{/* deviations: dev-numberinput-step */}
- `allowInteger` / `isInteger` 作为兼容项保留：设置后等价于强制 `step={1}`，开发期告警提示迁移（原版静默采纳），新代码请直接用 `step`。{/* deviations: dev-allow-integer */}

## 另见

- 单行输入的基础能力（类型白名单、`validate` 软校验等）：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md)
- 值如何在组件与状态之间流动：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)
- 所有组件共有的透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/components/search-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# SearchInput 搜索输入

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/SearchInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SearchInputWidget.html "OO.ui.SearchInputWidget")

搜索输入框：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 的搜索形态，值非空且可编辑时出现清除指示器，点击它就会清空并把焦点移回输入框。

## 基本用法

```tsx preview
import { useState } from "react";
import { SearchInput } from "ooui-react";

function App() {
  const [query, setQuery] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <SearchInput value={query} onChange={setQuery} placeholder="搜索条目……" />
      <div>查询词：{query || "（空）"}</div>
      <SearchInput defaultValue="OOUI 组件" />
    </div>
  );
}

export default App;
```

搜索框内已有值且可编辑（未禁用、非只读）时，右侧出现 × 清除指示器；清空后指示器消失，焦点回到输入框。

## 与标签、软校验配合

`label`、`labelPosition`、`invisibleLabel`、`validate` 等属性沿用 TextInput 的语义。

```tsx preview
import { SearchInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 320 }}>
      <SearchInput label="关键词" labelPosition="before" validate="non-empty" placeholder="必填示例" />
    </div>
  );
}

export default App;
```

:::note 若要“输入框 + 常驻结果列表”
本组件只是带清除能力的搜索框。若需要输入时实时展示下拉结果，请用 `SearchWidget`（搜索框 + 结果列表的组合）。
:::

## 属性写入位置

与 TextInput 相同：`...rest` 写在根 `<div>` 上，写到原生 `<input>` 的属性走 `inputProps`，聚焦输入框用 `inputRef`。清除指示器由组件接管，因此**不开放** `type`（始终为 `search`）、`indicator`、`indicatorProps`。

## API

只列出与 TextInput 的差异，其余属性见 [TextInput · API](https://ooui-react.pages.dev/components/text-input/index.md#api)。

| 属性             | 描述               | 类型                                        | 默认值        |
| -------------- | ---------------- | ----------------------------------------- | ---------- |
| `value`        | 查询文本（受控）         | `string`                                  | —          |
| `defaultValue` | 非受控初始值           | `string`                                  | —          |
| `onChange`     | 值变化回调（值优先）       | `ChangeHandler<string, HTMLInputElement>` | —          |
| `icon`         | 左侧图标名            | `string`                                  | `'search'` |
| `inputRef`     | 内部 `<input>` 的引用 | `Ref<HTMLInputElement>`                   | —          |

不支持的属性：`type`（始终为 `search`）、`indicator` / `indicatorProps`（指示器槽位由清除逻辑接管）。

## 另见

- 基础单行输入的全部能力（类型、软校验、属性写入位置）：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md)
- 带结果列表的搜索：`SearchWidget`
- 值如何在组件与状态之间流动：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)



---
url: https://ooui-react.pages.dev/components/search-widget/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# SearchWidget 搜索组件

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/SearchWidget) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SearchWidget.html "OO.ui.SearchWidget")

搜索组件：查询框配始终可见的结果列表。

## 基本用法

组件本身不设定高度：query 与 results 均为绝对定位，根元素没有高度样式。使用时建议为根元素提供高度（固定高度、`height: 100%` 或在 flex 列布局中 `flex: 1` 均可），否则结果列表会溢出组件盒子；示例同时给根元素加了 `position: relative`，让这些区域以组件自身为定位基准（缺省时会锚到外层最近的定位元素）。

```tsx preview
import { useState } from "react";
import { SearchWidget } from "ooui-react";

const data = ["苹果", "香蕉", "橙子", "葡萄", "西瓜"];

function App() {
  const [query, setQuery] = useState("");
  const [picked, setPicked] = useState("（未选定）");

  // 由调用方按查询过滤出结果集填入 results
  const results = data
    .filter((name) => name.includes(query))
    .map((name) => ({ value: name, children: name }));

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 320 }}>
      <SearchWidget
        value={query}
        onQueryChange={setQuery}
        onChoose={(v) => setPicked(String(v))}
        results={results}
        placeholder="搜索水果……"
        style={{ height: 280, position: "relative" }}
      />
      <div>已选定：{picked}</div>
    </div>
  );
}

export default App;
```

## 查询与选定

- `value` / `defaultValue` / `onQueryChange` 是查询框的受控/非受控通道（无 `onChange`，查询变化走 `onQueryChange`）。
- `results` 每项是标准的[选项数据](https://ooui-react.pages.dev/guide/options.md)（带 `value` 与 `children`）。
- `onChoose` 在选定结果时触发（Enter 选定高亮结果，或鼠标点击结果）。结果集或查询变化时高亮自动清除。
- 组件不实现检索，真实场景多为异步：在 `onQueryChange` 里发起请求，加载期间可先把 `results` 清空、就绪后再填入——结果集或查询每次变化高亮都会自动清除，无需手动复位。
- `inputProps` 是**双层通道**：SearchInput 组件层的属性直接写；要写到原生 `<input>` 的属性（`aria-*`、`autoComplete` 等）经 `inputProps.inputProps` 给入（TextInput 的输入元素通道）。`inputProps.inputRef` 会被合并——该 input 兼作结果列表 `aria-activedescendant` 的焦点归属元素。

## 键盘与焦点

焦点始终留在查询框：↑↓ 在结果间移动高亮（端点环绕）、Enter 选定当前高亮项。查询框右侧的清除指示器由 [SearchInput](https://ooui-react.pages.dev/components/search-input/index.md) 提供，有值即出现、点击清空。

## API

| 属性              | 描述                                                                                    | 类型                                | 默认值     |
| --------------- | ------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `results`       | 结果选项集，由调用方按查询填充                                                                       | `SelectOptionProps[]`             | `[]`    |
| `value`         | 查询文本（受控）                                                                              | `string`                          | —       |
| `defaultValue`  | 非受控初始查询                                                                               | `string`                          | `''`    |
| `onQueryChange` | 查询变化回调（据此重填 `results`）                                                                | `ChangeHandler<string>`           | —       |
| `onChoose`      | 选定结果回调                                                                                | `ChangeHandler<string \| number>` | —       |
| `placeholder`   | 查询框占位符                                                                                | `string`                          | —       |
| `inputProps`    | 查询框（SearchInput）的属性覆盖（双层通道，见[查询与选定](#查询与选定)）；`value`/`defaultValue`/`onChange` 由本组件接管 | `object`                          | —       |
| `disabled`      | 是否禁用                                                                                  | `boolean`                         | `false` |
| `...rest`       | 原生 `div` 属性直传根元素                                                                      | `HTMLAttributes<HTMLDivElement>`  | —       |

## 另见

- 带候选菜单、以标签呈现的查找：[MenuTagMultiselect](https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md)
- 可自由输入的下拉候选：[ComboBoxInput](https://ooui-react.pages.dev/components/combo-box-input/index.md)
- 查询框本身的能力：[SearchInput](https://ooui-react.pages.dev/components/search-input/index.md)



---
url: https://ooui-react.pages.dev/components/combo-box-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ComboBoxInput 组合框

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ComboBoxInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ComboBoxInputWidget.html "OO.ui.ComboBoxInputWidget")

可输入的下拉候选框：可自由编辑的输入框配下拉候选菜单，不强制输入必须是候选之一。

## 基本用法

```tsx preview
import { useState } from "react";
import { ComboBoxInput } from "ooui-react";

const options = [
  { value: "red", children: "红色" },
  { value: "green", children: "绿色" },
  { value: "blue", children: "蓝色" },
];

function App() {
  const [text, setText] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 260 }}>
      <ComboBoxInput
        options={options}
        value={text}
        onChange={setText}
        placeholder="输入或从下拉选择"
      />
      <div>当前文本：{text || "（空）"}</div>
      <ComboBoxInput options={options} defaultValue="绿色" label="颜色" labelPosition="before" />
    </div>
  );
}

export default App;
```

## 标签、图标与软校验

`label` / `labelPosition` / `invisibleLabel`、`icon` / `indicator`、`validate`、`required` 等属性沿用 [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 的语义；`validate` 是软反馈（标红 `aria-invalid`，不改写值）。

```tsx preview
import { ComboBoxInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 260 }}>
      <ComboBoxInput
        icon="search"
        validate={(v) => v.length >= 2}
        placeholder="至少两个字符"
        options={[{ value: "ab", children: "AB" }, { value: "cd", children: "CD" }]}
      />
    </div>
  );
}

export default App;
```

## 键盘与选定

键入只**展开菜单**
并把高亮重定位到与输入精确匹配的项（无匹配则清高亮），候选列表本身不随输入过滤——要「边输入边筛」需自行收窄 `options`
。点击输入框也会重新展开菜单。`readOnly`
 时是完全只读：方向键、下拉按钮、点击输入框都无法展开（原版点击输入框仍会展开一个全部禁用的菜单，本工程改为不展开）。
选定（点击选项、Enter、下拉按钮）把选项文本写入输入框，值始终是字符串：**数值型 `value` 的选项不会呈现选中态**（对齐原版按序列化文本比较，`1` 与 `'1'` 不等价），需要选中态时选项值请用字符串。

| 按键                 | 行为                                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| ↑ / ↓              | 展开菜单并移动高亮（未展开时分别自首 / 末项起步）                                                                                                       |
| Enter              | 选定高亮项（无高亮时选定与输入精确匹配的选项）并收起；菜单展开时阻止默认行为，处于 [FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md) 内回车不会顺带提交表单 |
| Tab                | 仅菜单展开时占用：有未选定的高亮项则提交该高亮项并阻止焦点移出，否则收起菜单、放行焦点移出                                                                                    |
| PageUp / PageDown  | ±10 翻页（仅菜单展开时占用）                                                                                                                 |
| Home / End / ← / → | 不占用，交还输入框光标                                                                                                                      |

高亮到端点后不环绕（区别于 `SearchWidget` 的端点环绕）；Escape 或点击外部收起菜单（捕获阶段处理，嵌套于 [Dialog](https://ooui-react.pages.dev/components/dialog/index.md) 不误关弹窗）。焦点保持在输入框、高亮项经 `aria-activedescendant` 关联，通用模型见[选择与选项](https://ooui-react.pages.dev/guide/options.md)。

## 属性写入位置

与 [TextInput](https://ooui-react.pages.dev/components/text-input/index.md) 一致：`...rest` 写在根 `<div>` 上，写到原生 `<input>` 的属性通过 `inputProps` 传递，聚焦输入框用 `inputRef`；`tabIndex`、`title`、`dir`、`accessKey`、`name` 由组件接管，写入 `<input>`。

## API

只列 ComboBoxInput 特有属性；输入框通用属性见 [TextInput · API](https://ooui-react.pages.dev/components/text-input/index.md#api)。

| 属性                                                             | 描述                                                                                                  | 类型                                                                                   | 默认值                     |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------- |
| `options`                                                      | 候选选项集（**必填**），书写约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md)                           | `DropdownOptionProps[]`                                                              | —                       |
| `value`                                                        | 输入框文本（受控）                                                                                           | `string`                                                                             | —                       |
| `defaultValue`                                                 | 非受控初始值                                                                                              | `string`                                                                             | `''`                    |
| `onChange`                                                     | 值变化回调（键入与选定菜单项均触发）                                                                                  | `ChangeHandler<string>`                                                              | —                       |
| `placeholder` / `name` / `maxLength` / `required` / `readOnly` | 输入框常规属性                                                                                             | —                                                                                    | —                       |
| `label` / `labelPosition` / `invisibleLabel`                   | 字段标签 / 位置 / 视觉隐藏                                                                                    | —                                                                                    | — / `'after'` / `false` |
| `icon` / `indicator`                                           | 图标名 / 指示器                                                                                           | `string` / `'up' \| 'down' \| 'clear' \| 'required'`                                 | —                       |
| `flags`                                                        | 根元素附加标志（invalid 叠加其上）                                                                               | `string \| string[]`                                                                 | —                       |
| `validate`                                                     | 软校验，见[软校验](https://ooui-react.pages.dev/components/text-input/index.md#%E8%BD%AF%E6%A0%A1%E9%AA%8C) | `RegExp \| ((v: string) => boolean \| Promise<boolean>) \| 'non-empty' \| 'integer'` | —                       |
| `inputRef`                                                     | 内部 `<input>` 的引用                                                                                    | `Ref<HTMLInputElement>`                                                              | —                       |
| `inputProps`                                                   | 原生 `<input>` 的附加属性；事件串联在组件逻辑之后                                                                      | `object`                                                                             | —                       |
| `disabled`                                                     | 是否禁用                                                                                                | `boolean`                                                                            | `false`                 |

## 另见

- 单行输入的基础能力：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md)
- 只能从候选里选（不给自由输入）：[Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md)
- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)



---
url: https://ooui-react.pages.dev/components/checkbox-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# CheckboxInput 复选框

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/CheckboxInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CheckboxInputWidget.html "OO.ui.CheckboxInputWidget")

单个复选框。本组件不自带文字标签，需要标签时交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 包裹。

## 基本用法

勾选状态用 `checked` / `defaultChecked` / `onChange` 控制，`onChange` 的第一个参数是新的勾选布尔值。

```tsx preview
import { useState } from "react";
import { CheckboxInput } from "ooui-react";

function App() {
  const [checked, setChecked] = useState(false);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <CheckboxInput checked={checked} onChange={setChecked} />
        已勾选：{String(checked)}
      </label>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <CheckboxInput defaultChecked />
        非受控，初始已勾选
      </label>
    </div>
  );
}

export default App;
```

## 半选状态

`indeterminate` 表示「半选」（部分选中），视觉上是一条横线而非对勾。它与勾选状态相互独立，常用于「全选」框表示子项部分选中。

```tsx preview
import { CheckboxInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <CheckboxInput indeterminate />
      <CheckboxInput checked indeterminate />
    </div>
  );
}

export default App;
```

「全选」框的标准做法：全选框的勾选态与半选态都从子项集合**派生**（全不选未勾选、全选勾选、其余半选），点击时把子项统一置为全选或全不选：

```tsx preview
import { useState } from "react";
import { CheckboxInput } from "ooui-react";

const ITEMS = ["苹果", "香蕉", "橙子"];

function App() {
  const [picked, setPicked] = useState<string[]>(["苹果"]);
  const allChecked = picked.length === ITEMS.length;

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <CheckboxInput
          checked={allChecked}
          indeterminate={picked.length > 0 && !allChecked}
          onChange={() => setPicked(allChecked ? [] : ITEMS)}
        />
        全选
      </label>
      {ITEMS.map((item) => (
        <label key={item} style={{ display: "flex", alignItems: "center", gap: 8 }}>
          <CheckboxInput
            checked={picked.includes(item)}
            onChange={() =>
              setPicked((prev) =>
                prev.includes(item) ? prev.filter((x) => x !== item) : [...prev, item],
              )
            }
          />
          {item}
        </label>
      ))}
    </div>
  );
}

export default App;
```

## 表单提交值

`value` 是**表单提交值**（写入原生 `<input>` 的 `value` 属性，缺省为空字符串），**不影响勾选状态**——勾选状态只由 `checked` 系通道决定。配合 `name`，勾选时该 `value` 随表单提交。

```tsx preview
import { CheckboxInput } from "ooui-react";

function App() {
  return (
    <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <CheckboxInput name="agree" value="yes" defaultChecked />
      同意条款（提交时字段 agree=yes）
    </label>
  );
}

export default App;
```

## 与 FieldLayout 配合

字段文字标签通常交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)。它会自动把标签与该复选框的原生 `<input>` 关联（点击标签即可切换勾选）；需要手动指定关联目标时，用 `inputId` 给出输入元素的 id。

```tsx preview
import { CheckboxInput, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="开启通知" align="inline">
        <CheckboxInput defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 禁用

`disabled` 输出 `aria-disabled` 并禁用原生 `<input>`，复选框不可再切换。放进 `FieldsetLayout` 等原生 `<fieldset>` 时，组级禁用会一并下发。

```tsx preview
import { CheckboxInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <CheckboxInput disabled />
      <CheckboxInput disabled defaultChecked />
    </div>
  );
}

export default App;
```

## API

| 属性               | 描述                                             | 类型                                         | 默认值     |
| ---------------- | ---------------------------------------------- | ------------------------------------------ | ------- |
| `checked`        | 勾选状态（受控，传入后即进入受控模式）                            | `boolean`                                  | —       |
| `defaultChecked` | 非受控初始勾选态                                       | `boolean`                                  | —       |
| `onChange`       | 勾选变化回调（新状态优先，含原生事件）                            | `ChangeHandler<boolean, HTMLInputElement>` | —       |
| `value`          | 表单提交值（写入 `<input>` 的 `value`，不影响勾选态）           | `string \| number`                         | `''`    |
| `indeterminate`  | 半选状态                                           | `boolean`                                  | `false` |
| `required`       | 必填（原生 `required`）                              | `boolean`                                  | `false` |
| `name`           | 表单字段名（写在 `<input>`）                            | `string`                                   | —       |
| `inputId`        | 内部 `<input>` 的 id（配合标签 `htmlFor`）              | `string`                                   | —       |
| `inputRef`       | 内部 `<input>` 的引用（组件 `ref` 指向外层 `<span>`）       | `Ref<HTMLInputElement>`                    | —       |
| `disabled`       | 是否禁用                                           | `boolean`                                  | `false` |
| `accessKey`      | 快捷键（写在 `<input>`）                              | `string`                                   | —       |
| `...rest`        | 原生 `span` 属性（`className`、`id`、`data-*` 等）直传根元素 | `HTMLAttributes<HTMLSpanElement>`          | —       |

`title`、`dir`、`tabIndex` 由组件接管、写在内部 `<input>` 上；`role` 同样写在内层 `<input>` 上（`role="presentation"` 一类语义须命中真实 input 才生效）。

## 另见

- 勾选通道在值通道中的位置：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)
- 带标签字段的排版：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 单选场景：[RadioInput](https://ooui-react.pages.dev/components/radio-input/index.md)（参数与本组件一致，无 `indeterminate`）



---
url: https://ooui-react.pages.dev/components/radio-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# RadioInput 单选框

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/RadioInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.RadioInputWidget.html "OO.ui.RadioInputWidget")

单个单选框。本组件不自带文字标签，需要标签时交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 包裹。

## 基本用法

勾选状态用 `checked` / `defaultChecked` / `onChange` 控制，`onChange` 的第一个参数是新的勾选布尔值。注意单选框选中后不能靠再次点击取消——互斥组的取消需要额外手段（如「清除」按钮重设状态）。

```tsx preview
import { useState } from "react";
import { Button, RadioInput } from "ooui-react";

function App() {
  const [checked, setChecked] = useState(true);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, alignItems: "flex-start" }}>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <RadioInput checked={checked} onChange={setChecked} />
        已勾选：{String(checked)}
      </label>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <RadioInput defaultChecked />
        非受控，初始已勾选
      </label>
      <Button onClick={() => setChecked(false)}>清除勾选</Button>
    </div>
  );
}

export default App;
```

## 同名互斥与表单提交值

多个 `RadioInput` 写同一个 `name`，浏览器原生机制即保证同组互斥、至多一项随表单提交。`value` 是**表单提交值**（写入原生 `<input>` 的 `value` 属性，缺省为空字符串），**不影响勾选状态**。

```tsx preview
import { useState } from "react";
import { RadioInput } from "ooui-react";

function App() {
  const [size, setSize] = useState("medium");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, alignItems: "flex-start" }}>
      {["small", "medium", "large"].map((item) => (
        <label key={item} style={{ display: "flex", alignItems: "center", gap: 8 }}>
          <RadioInput
            name="size"
            value={item}
            checked={size === item}
            onChange={(next) => next && setSize(item)}
          />
          {item}
        </label>
      ))}
      <div>当前选择：{size}</div>
    </div>
  );
}

export default App;
```

## 与 FieldLayout 配合

字段文字标签通常交给 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)。它会自动把标签与该单选框的原生 `<input>` 关联（点标签即选中）；需要手动指定关联目标时，用 `inputId` 给出输入元素的 id。

```tsx preview
import { FieldLayout, RadioInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="默认项" align="inline">
        <RadioInput defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 禁用

`disabled` 输出 `aria-disabled` 并禁用原生 `<input>`，单选框不可再选中。放进 `FieldsetLayout` 等原生 `<fieldset>` 时，组级禁用会一并下发。

```tsx preview
import { RadioInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      <RadioInput disabled />
      <RadioInput disabled defaultChecked />
    </div>
  );
}

export default App;
```

## API

| 属性               | 描述                                             | 类型                                         | 默认值     |
| ---------------- | ---------------------------------------------- | ------------------------------------------ | ------- |
| `checked`        | 勾选状态（受控，传入后即进入受控模式）                            | `boolean`                                  | —       |
| `defaultChecked` | 非受控初始勾选态                                       | `boolean`                                  | —       |
| `onChange`       | 勾选变化回调（新状态优先，含原生事件）                            | `ChangeHandler<boolean, HTMLInputElement>` | —       |
| `value`          | 表单提交值（写入 `<input>` 的 `value`，不影响勾选态）           | `string \| number`                         | `''`    |
| `name`           | 表单字段名（写在 `<input>` 上；同名即同组互斥）                  | `string`                                   | —       |
| `inputId`        | 内部 `<input>` 的 id（配合标签 `htmlFor`）              | `string`                                   | —       |
| `required`       | 必填（原生 `required`）                              | `boolean`                                  | `false` |
| `disabled`       | 是否禁用                                           | `boolean`                                  | `false` |
| `accessKey`      | 快捷键（写在 `<input>` 上）                            | `string`                                   | —       |
| `...rest`        | 原生 `span` 属性（`className`、`id`、`data-*` 等）直传根元素 | `HTMLAttributes<HTMLSpanElement>`          | —       |

`title`、`dir`、`tabIndex` 由组件接管、写在内部 `<input>` 上；`role` 同样写在内部 `<input>` 上（`role="presentation"` 一类语义须命中真实 input 才生效）。组件 `ref` 指向外层 `<span>`。

## 另见

- 勾选通道在值通道中的位置：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)
- 带标签字段的排版：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 单选组（互斥项排成一组、方向键直接改选）：[RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md)



---
url: https://ooui-react.pages.dev/components/select-file-input-widget/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# SelectFileInputWidget 文件选择

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/SelectFileInputWidget) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SelectFileInputWidget.html "OO.ui.SelectFileInputWidget")

文件选择输入框，提供拖放区、仅按钮等形态。

## 基本用法

文件集是**数组**，走 `value` / `defaultValue` / `onChange` 通道；非多选时只保留首个文件。信息框中的**清除指示器是唯一的清除入口**（点击或按 Enter 清空）。

```tsx preview
import { useState } from "react";
import { SelectFileInputWidget } from "ooui-react";

function App() {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <SelectFileInputWidget onChange={setFiles} />
      <SelectFileInputWidget defaultValue={[new File(["hello"], "hello.txt")]} />
      <div style={{ fontSize: 13 }}>
        {files.length ? `已选：${files.map((file) => file.name).join("、")}` : "未选择文件"}
      </div>
    </div>
  );
}

export default App;
```

## 多选与类型过滤

`multiple` 开启多选；`accept` 用 MIME 或 `image/*` 形态限定类型——同时写入 `accept` 属性、过滤系统选择器结果与拖入的文件（系统选择器已限类型，被过滤的多是拖放路径；文件没有 type 信息时放行）。

```tsx preview
import { SelectFileInputWidget } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <SelectFileInputWidget multiple />
      <SelectFileInputWidget accept={["image/*"]} />
    </div>
  );
}

export default App;
```

## 拖放区形态

`showDropTarget` 把整个组件变成拖放区：空态时整块可点击开选择器，拖入文件时按能否接收给出反馈，放下即选中。单选且选中图片文件时展示**缩略图**——`thumbnailSizeLimit`（MB，缺省 20）以内才加载，超限或解码失败时回退为附件图标。

拖放能力依赖浏览器的 `DataTransfer` 构造器（Safari 14.1+），不支持时拖放自动关闭、选择按钮照常可用；`droppable={false}` 可显式关闭拖放。

```tsx preview
import { useMemo } from "react";
import { SelectFileInputWidget } from "ooui-react";

const PNG_1PX =
  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";

function App() {
  // 1x1 PNG：初始为图片文件时，单选拖放区加载缩略图
  const imageFile = useMemo(() => {
    const bytes = Uint8Array.from(atob(PNG_1PX), (char) => char.charCodeAt(0));
    return new File([bytes], "logo.png", { type: "image/png" });
  }, []);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 420 }}>
      <SelectFileInputWidget showDropTarget />
      <SelectFileInputWidget showDropTarget defaultValue={[imageFile]} />
      {/* 上限设为 0：缩略图不加载，回退附件图标 */}
      <SelectFileInputWidget showDropTarget thumbnailSizeLimit={0} defaultValue={[imageFile]} />
    </div>
  );
}

export default App;
```

## 仅按钮形态

`buttonOnly` 只渲染选择按钮，不含信息框；需要自己展示文件名时用它。

```tsx preview
import { useState } from "react";
import { SelectFileInputWidget } from "ooui-react";

function App() {
  const [name, setName] = useState("");

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <SelectFileInputWidget
        buttonOnly
        buttonLabel="浏览…"
        onChange={(files) => setName(files[0]?.name ?? "")}
      />
      <span>{name || "未选择文件"}</span>
    </div>
  );
}

export default App;
```

## 受控与程序化设置

传 `value` 即进入受控模式，文件集完全由调用方驱动——下方演示外置「清空」按钮把文件集置回 `[]`。

:::note 与原版的差异
原版构造期传入的 `value`
 会被静默丢弃（构造时序缺陷），只能构造后再命令式 `setValue`
。本工程按受控惯例让 `value`
 / `defaultValue`
 直接生效，并把文件集写回内部 `<input type="file">`
，随表单原生提交不受影响。
:::
```tsx preview
import { useState } from "react";
import { Button, SelectFileInputWidget } from "ooui-react";

function App() {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 420 }}>
      <SelectFileInputWidget value={files} onChange={setFiles} />
      <div>
        <Button onClick={() => setFiles([])} disabled={files.length === 0}>
          清空
        </Button>
      </div>
    </div>
  );
}

export default App;
```

## 焦点与键盘

- 按 `Tab` 时焦点进入**选择按钮**，信息框不进入 Tab 顺序；清除指示器键盘可达（聚焦后按 Enter 清空）。
- 信息框是只读的 `type="search"` 输入框，手改文件名不会改变文件集——清空一律走清除指示器。
- `required`、`name` 写在内部文件 `<input>` 上，随 [FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md) 原生提交。

## API

| 属性                   | 描述                                                    | 类型                                                                                           | 默认值     |
| -------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------- |
| `value`              | 当前文件集（受控，传入后即进入受控模式；空数组表示未选择），非多选时只保留首个               | `File[]`                                                                                     | —       |
| `defaultValue`       | 非受控初始文件集                                              | `File[]`                                                                                     | `[]`    |
| `onChange`           | 文件集变化回调；文件集与原值等价（同名同大小同类型同修改时间）时不触发                   | `(files: File[]) => void`                                                                    | —       |
| `accept`             | 接受的文件类型（MIME 或 `image/*` 形态），写入 `accept` 属性并过滤选择结果与拖放 | `string[]`                                                                                   | —       |
| `multiple`           | 是否多选                                                  | `boolean`                                                                                    | `false` |
| `droppable`          | 是否可拖放（浏览器不支持 `DataTransfer` 时强制关闭）                    | `boolean`                                                                                    | `true`  |
| `showDropTarget`     | 拖放区形态：整块可拖放与点击（须 `droppable`）                         | `boolean`                                                                                    | `false` |
| `buttonOnly`         | 只渲染选择按钮（优先级高于 `showDropTarget`）                       | `boolean`                                                                                    | `false` |
| `thumbnailSizeLimit` | 缩略图大小上限（MB，超过则不加载）                                    | `number`                                                                                     | `20`    |
| `placeholder`        | 信息框占位文案（缺省取内建消息）                                      | `string`                                                                                     | —       |
| `icon`               | 信息框图标（缺省无图标）                                          | `string`                                                                                     | —       |
| `required`           | 必填（原生 `required`，写在文件 `<input>` 上）                    | `boolean`                                                                                    | `false` |
| `name`               | 文件字段名（写在文件 `<input>` 上，随表单提交）                         | `string`                                                                                     | —       |
| `buttonLabel`        | 选择按钮文案（缺省按 `multiple` 取内建消息）                          | `ReactNode`                                                                                  | —       |
| `buttonProps`        | 选择按钮属性覆盖（`disabled` / `onClick` 由组件接管）                | `Omit<ButtonProps, "children" \| "disabled" \| "onClick" \| "anchorContent" \| "anchorRef">` | —       |
| `inputRef`           | 内部文件 `<input>` 的引用                                    | `Ref<HTMLInputElement>`                                                                      | —       |
| `accessKey`          | 快捷键（写在文件 `<input>` 上）                                 | `string`                                                                                     | —       |
| `disabled`           | 是否禁用（按钮、信息框、拖放一并停用）                                   | `boolean`                                                                                    | `false` |
| `...rest`            | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素         | `HTMLAttributes<HTMLDivElement>`                                                             | —       |

`title` 写在文件 `<input>` 上，`tabIndex` 写在选择按钮上；组件 `ref` 指向根元素（`buttonOnly` 形态下根元素即按钮）。

## 另见

- 值通道约定：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)
- 内建文案的语言包替换：[全局配置](https://ooui-react.pages.dev/guide/configuration.md#%E6%96%87%E6%A1%88%E4%B8%8E%E5%9B%BD%E9%99%85%E5%8C%96)
- 表单提交容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)



---
url: https://ooui-react.pages.dev/components/select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Select 选择列表

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Select) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SelectWidget.html "OO.ui.SelectWidget")

选择列表：可点选的选项集合，既是 [Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md) 等浮层组件的内层列表，也可单独使用。选项数据约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md)。

:::note 单独使用时如何交互
对齐原版 `SelectWidget`
，本组件根元素**缺省不可聚焦**
（不进 Tab 序），因此更适合鼠标点选。需要键盘可达的单选/多选，请优先使用 [Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md)
、[RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md)
、`ButtonSelect`
 等把焦点管理做好的组件，它们都以 `Select`
 为内层。作为浮层内层时，键盘导航由外层触发元素统一管理，无需你操心。
:::
## 基本用法

```tsx preview
import { useState } from "react";
import { Select } from "ooui-react";

const options = [
  { value: "apple", children: "苹果" },
  { value: "orange", children: "橙子" },
  { value: "banana", children: "香蕉", disabled: true },
  { value: "grape", children: "葡萄" },
];

function App() {
  const [value, setValue] = useState<string | number>("apple");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 200 }}>
      <Select options={options} value={value} onChange={setValue} aria-label="水果" />
      <div>当前值：{String(value)}</div>
    </div>
  );
}

export default App;
```

## onChange 与 onChoose

两个“选定”回调分工不同：

- `onChange`：**选中值发生变化**时触发，重复点选当前项不触发。
- `onChoose`：**每一次选定**（点击 / 拖拽 / Enter）都触发，含重复选定。浮层组件用它来实现“选定后立即收起”。

```tsx
<Select options={options} onChange={setValue} onChoose={() => setOpen(false)} />
```

## 命令菜单形态

`clearOnChoose` 为 `true` 时，选定只触发 `onChoose`、不改变选中值——展示上从不出现“已选中某项”，适合做点了就执行、不保留选中态的命令菜单。

```tsx preview
import { useState } from "react";
import { Select } from "ooui-react";

function App() {
  const [log, setLog] = useState<string[]>([]);

  return (
    <div style={{ display: "flex", gap: 16, alignItems: "flex-start" }}>
      <Select
        aria-label="命令"
        clearOnChoose
        options={[
          { value: "copy", children: "复制" },
          { value: "cut", children: "剪切" },
          { value: "paste", children: "粘贴" },
        ]}
        onChoose={(v) => setLog((prev) => [...prev, `执行 ${String(v)}`])}
      />
      <div style={{ fontSize: 14 }}>{log.length ? log.join(" → ") : "点击任意命令（不会有选中态）"}</div>
    </div>
  );
}

export default App;
```

## 分组标题

选项数组里不带 `value` 的项渲染为分组标题，不可选中、不参与键盘导航。

```tsx preview
import { Select } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 200 }}>
      <Select
        aria-label="带分组"
        defaultValue="cat"
        options={[
          { children: "猫科" },
          { value: "cat", children: "猫" },
          { value: "lion", children: "狮子" },
          { children: "犬科" },
          { value: "dog", children: "狗" },
        ]}
      />
    </div>
  );
}

export default App;
```

## 键盘导航开关

作为浮层内层时键盘导航由外层驱动。单独使用且已让列表获得焦点的场景下：

- `handleNavigationKeys`：是否处理 Home / End / PageUp / PageDown。
- `listWrapsAround`：方向键导航到端点后是否环绕（默认 `true`）。
- **前缀跳转**：列表获得焦点后直接键入字符，按选项文本的前缀循环跳转（1.5 秒缓冲）。
- **悬停高亮**：鼠标悬停的选项成为高亮项，鼠标移开后清除（与键盘高亮共用同一状态）。

## API

| 属性                     | 描述                                                              | 类型                                             | 默认值     |
| ---------------------- | --------------------------------------------------------------- | ---------------------------------------------- | ------- |
| `options`              | 选项集，书写约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md) | `SelectOptionProps[]`                          | —       |
| `value`                | 当前选中值（受控，传入后即进入受控模式）                                            | `string \| number`                             | —       |
| `defaultValue`         | 非受控初始选中值                                                        | `string \| number`                             | —       |
| `onChange`             | 选中值变化回调（值优先，仅变化时触发）                                             | `ChangeHandler<string \| number>`              | —       |
| `onChoose`             | 选定回调（每次选定都触发，含重复）                                               | `ChangeHandler<string \| number>`              | —       |
| `clearOnChoose`        | 命令菜单形态：选定只触发 `onChoose`、不改选中值                                   | `boolean`                                      | `false` |
| `outline`              | 以带层级缩进的 `OutlineOption` 渲染选项                                    | `boolean`                                      | `false` |
| `highlightedValue`     | 键盘导航高亮值（受控，传入即由上层管理；独立使用时组件内部维护）                                | `string \| number`                             | —       |
| `onHighlightedChange`  | 高亮变化回调；传入 `highlightedValue` 时须经此回写父级                           | `ChangeHandler<string \| number \| undefined>` | —       |
| `selectedValues`       | 多选展示的选中值集合（供标签多选等组合使用）                                          | `(string \| number)[]`                         | —       |
| `handleNavigationKeys` | 是否处理 Home/End/PageUp/PageDown                                   | `boolean`                                      | `false` |
| `listWrapsAround`      | 键盘导航到端点后是否环绕                                                    | `boolean`                                      | `true`  |
| `disabled`             | 是否禁用（一并禁用组内全部选项）                                                | `boolean`                                      | `false` |
| `...rest`              | 原生 `div` 属性（`className`、`id`、`aria-*` 等）直传根元素                   | `HTMLAttributes<HTMLDivElement>`               | —       |

组件没有 `children` 写入位置，选项全部由 `options` 声明。

## 另见

- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)
- 以 Select 为内层的浮层：[Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md)
- `onChange` 与 `onChoose` 的分工：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%9B%9E%E8%B0%83%E7%AD%BE%E5%90%8D)



---
url: https://ooui-react.pages.dev/components/dropdown/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Dropdown 下拉选择

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/Dropdown) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.DropdownWidget.html "OO.ui.DropdownWidget")

下拉选择框。选项数据的书写约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md)。

## 基本用法

不传 `value` 时组件自己记住选中项，`label` 作为尚未选中任何项时的占位文本。`onChange` 为值优先签名。

```tsx preview
import { useState } from "react";
import { Dropdown } from "ooui-react";

const options = [
  { value: "apple", children: "苹果" },
  { value: "orange", children: "橙子" },
  { value: "banana", children: "香蕉" },
];

function App() {
  const [value, setValue] = useState<string | number>("apple");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 200 }}>
      <Dropdown options={options} value={value} onChange={setValue} label="选择水果" />
      <div>当前值：{String(value)}</div>
      <Dropdown options={options} defaultValue="orange" label="非受控" />
    </div>
  );
}

export default App;
```

## 图标与标签

`icon` 渲染在 handle 前端。`label` 有两种作用：无选中项时作为 handle 的显示文本，同时也是组合框可访问名称的一部分。

```tsx preview
import { Dropdown } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 220 }}>
      <Dropdown
        icon="attachment"
        label="附件类型"
        options={[
          { value: "image", children: "图片" },
          { value: "video", children: "视频" },
        ]}
      />
    </div>
  );
}

export default App;
```

## 分组与禁用项

选项数组里不带 `value` 的项渲染为分组标题，带 `disabled` 的项不可选。菜单类组件的 `disabled` 禁用的是**触发端**（handle 不可展开、键盘不可用），菜单内各项是否禁用由选项自身的 `disabled` 决定，详见[选择与选项 · 禁用](https://ooui-react.pages.dev/guide/options.md#%E7%A6%81%E7%94%A8)。

```tsx preview
import { Dropdown } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, maxWidth: 220 }}>
      <Dropdown
        label="分组示例"
        options={[
          { children: "常见" },
          { value: "apple", children: "苹果" },
          { value: "banana", children: "香蕉", disabled: true },
          { children: "其他" },
          { value: "durian", children: "榴莲" },
        ]}
      />
      <Dropdown label="整体禁用" disabled options={[{ value: "a", children: "A" }]} />
    </div>
  );
}

export default App;
```

## 键盘与焦点

- Tab 聚焦到 handle，Enter / 空格展开菜单；展开时 ↑↓←→ 移动高亮，Enter / 空格选定并收起，Escape 收起不改变选中值。
- 收起但处于聚焦态时，导航键与前缀跳转**直接改选而不展开菜单**（屏幕阅读器友好，与原版一致）。
- 直接键入字符按选项文本前缀跳转（1.5 秒缓冲）。
- 焦点始终停留在 handle 上，高亮项经 `aria-activedescendant` 关联，菜单本身不进 Tab 序。

:::note 与原版的差异
展开态按**空格**
：原版不把空格交给菜单消费，只会经按键模拟点击关闭菜单；本工程空格与 Enter 同分支，直接选定当前高亮项（与按钮以空格激活的 ARIA 惯例一致）。前缀缓冲活跃时空格仍属于前缀搜索，不会选定。
:::
## API

| 属性             | 描述                                                              | 类型                                | 默认值     |
| -------------- | --------------------------------------------------------------- | --------------------------------- | ------- |
| `options`      | 选项集，书写约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md) | `DropdownOptionProps[]`           | —       |
| `value`        | 当前选中值（受控，传入后即进入受控模式）                                            | `string \| number`                | —       |
| `defaultValue` | 非受控初始选中值                                                        | `string \| number`                | —       |
| `onChange`     | 选中值变更回调（值变化时触发）                                                 | `ChangeHandler<string \| number>` | —       |
| `label`        | 无选中项时的占位文本，并参与可访问名称                                             | `ReactNode`                       | —       |
| `icon`         | handle 前端的图标名                                                   | `string`                          | —       |
| `disabled`     | 是否禁用触发端（不可展开、键盘不可用）                                             | `boolean`                         | `false` |
| `tabIndex`     | Tab 序，写在 handle 上（根元素不可聚焦）                                      | `number \| null`                  | `0`     |
| `...rest`      | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素                   | `HTMLAttributes<HTMLDivElement>`  | —       |

组件没有 `children` 的写入位置——handle 与菜单是固定结构，显示文本取自选中项或 `label`。

## 另见

- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)
- 菜单的内层列表：[Select](https://ooui-react.pages.dev/components/select/index.md)
- 值如何在组件与状态之间流动：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)



---
url: https://ooui-react.pages.dev/components/outline-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# OutlineSelect 大纲选择

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/OutlineSelect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.OutlineSelectWidget.html "OO.ui.OutlineSelectWidget")

大纲样式的选择列表：用 `level`（0–2）表达层级缩进，适合目录这类有从属关系的列表。

## 基本用法

```tsx preview
import { useState } from "react";
import { OutlineSelect } from "ooui-react";

function App() {
  const [value, setValue] = useState<string | number>("intro");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 240 }}>
      <OutlineSelect
        aria-label="文档大纲"
        value={value}
        onChange={setValue}
        options={[
          { value: "intro", children: "引言", level: 0 },
          { value: "background", children: "背景", level: 1 },
          { value: "prior", children: "相关工作", level: 1 },
          { value: "method", children: "方法", level: 0 },
          { value: "dataset", children: "数据集", level: 2 },
        ]}
      />
      <div>当前项：{String(value)}</div>
    </div>
  );
}

export default App;
```

## 层级与分组

- `level` 取 0–2（超出钳制），主题仅提供三级缩进。
- 不带 `value` 的选项渲染为分组标题，与[选择与选项](https://ooui-react.pages.dev/guide/options.md)一致。
- 带图标槽位的选项支持 `icon` 与 `flags`（给图标着色，见[选择与选项 · 图标与标志](https://ooui-react.pages.dev/guide/options.md#%E5%9B%BE%E6%A0%87%E4%B8%8E%E6%A0%87%E5%BF%97)）。
- 键盘：聚焦整组后 ↑↓←→ 移动高亮、Enter 选定；Home/End/PageUp/PageDown 由 `handleNavigationKeys` 启用，`listWrapsAround` 控制是否环绕——与 [Select](https://ooui-react.pages.dev/components/select/index.md) 完全一致。

```tsx preview
import { useState } from "react";
import { OutlineSelect } from "ooui-react";

function App() {
  const [value, setValue] = useState<string | number>("getting-started");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 240 }}>
      <OutlineSelect
        aria-label="分组大纲"
        value={value}
        onChange={setValue}
        options={[
          { children: "入门" },
          { value: "getting-started", children: "快速上手", level: 1, icon: "book" },
          { value: "installation", children: "安装", level: 1 },
          { children: "进阶" },
          { value: "theming", children: "主题", level: 1, icon: "palette", flags: "progressive" },
          { value: "i18n", children: "国际化", level: 1 },
        ]}
      />
      <div>当前项：{String(value)}</div>
    </div>
  );
}

export default App;
```

## API

继承 [Select](https://ooui-react.pages.dev/components/select/index.md) 的属性（`value` / `defaultValue` / `onChange` / `disabled` / `handleNavigationKeys` / `listWrapsAround` 等），差异在于：

| 属性         | 描述                                                        | 类型                           | 默认值 |
| ---------- | --------------------------------------------------------- | ---------------------------- | --- |
| `options`  | 大纲选项集（**必填**），可选项额外支持 `level`（0–2 缩进层级）与 `icon` / `flags` | `OutlineSelectOptionProps[]` | —   |
| `tabIndex` | Tab 序，作用在整组（大纲列表可聚焦）                                      | `number \| null`             | `0` |

`outline` 由组件固定开启，不可覆盖。

## 另见

- 基础选择列表：[Select](https://ooui-react.pages.dev/components/select/index.md)
- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)



---
url: https://ooui-react.pages.dev/components/tab-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# TabSelect 页签选择

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/TabSelect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TabSelectWidget.html "OO.ui.TabSelectWidget")

页签式选择：把一组互斥选项呈现为一排页签。

## 基本用法

```tsx preview
import { useState } from "react";
import { TabSelect } from "ooui-react";

const options = [
  { value: "general", children: "常规" },
  { value: "advanced", children: "高级" },
  { value: "about", children: "关于" },
];

function App() {
  const [tab, setTab] = useState<string | number>("general");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <TabSelect options={options} value={tab} onChange={setTab} aria-label="视图" />
      <div>当前页签：{String(tab)}</div>
    </div>
  );
}

export default App;
```

## 带框与无框

`framed`（默认开）给页签条加边框底色；设为 `false` 则为更轻量的无框形态。

```tsx preview
import { TabSelect } from "ooui-react";

const options = [
  { value: "a", children: "甲" },
  { value: "b", children: "乙" },
  { value: "c", children: "丙", disabled: true },
];

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <TabSelect options={options} defaultValue="a" />
      <TabSelect options={options} defaultValue="a" framed={false} />
    </div>
  );
}

export default App;
```

## 键盘

点击页签后焦点自动移入整组（略优于原版：原版点击后焦点留在原处，方向键不响应），←→（及 ↑↓）随即在非禁用页签间**环绕移动并直接改选**，Enter 重新选定当前页签；也可以按 Tab 让焦点进入整组。属于“直选族”键盘模型，详见[选择与选项 · 键盘与焦点](https://ooui-react.pages.dev/guide/options.md#%E9%94%AE%E7%9B%98%E4%B8%8E%E7%84%A6%E7%82%B9)。

## API

| 属性             | 描述                                                     | 类型                                | 默认值     |
| -------------- | ------------------------------------------------------ | --------------------------------- | ------- |
| `options`      | 页签集（**必填**），每项含 `value` 与 `children`（文本），可选 `disabled` | `TabSelectOptionProps[]`          | —       |
| `value`        | 当前选中值（受控）                                              | `string \| number`                | —       |
| `defaultValue` | 非受控初始选中值                                               | `string \| number`                | —       |
| `onChange`     | 选中值变更回调（值优先）                                           | `ChangeHandler<string \| number>` | —       |
| `framed`       | 是否带边框                                                  | `boolean`                         | `true`  |
| `disabled`     | 是否禁用（一并禁用全部页签）                                         | `boolean`                         | `false` |
| `tabIndex`     | Tab 序（焦点停在整组）                                          | `number \| null`                  | `0`     |
| `...rest`      | 原生 `div` 属性（`className`、`id`、`aria-*` 等）直传根元素          | `HTMLAttributes<HTMLDivElement>`  | —       |

## 与原版的差异

- **`TabOption` 不支持 `href` 链接**：原版该能力仅 PHP 端在用；需要链接页签自行组合实现。{/* deviations: dev-taboption-href */}
- **拖拽中断时清理选择态**：原版拖出窗口丢失 mouseup 后选择态残留、再点击空白处会误提交旧选项；本工程在 mousedown 重置并监听 `pointercancel` 清理。{/* deviations: dev-tabselect-drag-fix */}

## 另见

- 按钮式直选：[ButtonSelect](https://ooui-react.pages.dev/components/button-select/index.md)
- 带页签的多面板：`BookletLayout`
- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)



---
url: https://ooui-react.pages.dev/components/button-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ButtonSelect 按钮选择

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonSelect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonSelectWidget.html "OO.ui.ButtonSelectWidget")

按钮式选择：把一组互斥选项呈现为一排按钮。选项数据约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md)。

## 基本用法

```tsx preview
import { useState } from "react";
import { ButtonSelect } from "ooui-react";

const options = [
  { value: "left", icon: "alignLeft", children: "左对齐" },
  { value: "center", icon: "alignCenter", children: "居中" },
  { value: "right", icon: "alignRight", children: "右对齐" },
];

function App() {
  const [align, setAlign] = useState<string | number>("left");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <ButtonSelect options={options} value={align} onChange={setAlign} aria-label="对齐" />
      <div>当前对齐：{String(align)}</div>
    </div>
  );
}

export default App;
```

## 无边框与禁用项

选项支持 `framed={false}`；带 `disabled` 的项不可选，组级 `disabled` 一并禁用全组（见[选择与选项 · 禁用](https://ooui-react.pages.dev/guide/options.md#%E7%A6%81%E7%94%A8)）。

```tsx preview
import { ButtonSelect } from "ooui-react";

function App() {
  return (
    <ButtonSelect
      defaultValue="a"
      options={[
        { value: "a", children: "可用" },
        { value: "b", children: "无边框", framed: false },
        { value: "c", children: "被禁用", disabled: true },
        { value: "d", children: "也可用" },
      ]}
    />
  );
}

export default App;
```

## 键盘

点击选项后焦点自动收进整组（略优于原版：原版点击后焦点留在原处，方向键不响应），↑↓←→ 随即在非禁用项间**环绕移动并直接改选**，Enter 重申当前项；也可以按 Tab 让焦点进入整组。这是“直选族”（与 [TabSelect](https://ooui-react.pages.dev/components/tab-select/index.md)、[RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md) 相同）的键盘模型。

## API

| 属性             | 描述                                                                                                 | 类型                                | 默认值     |
| -------------- | -------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `options`      | 选项集（**必填**），每项含 `value` 与 `children`（文本），可选 `icon` / `indicator` / `flags` / `framed` / `disabled` | `ButtonSelectOptionProps[]`       | —       |
| `value`        | 当前选中值（受控）                                                                                          | `string \| number`                | —       |
| `defaultValue` | 非受控初始选中值                                                                                           | `string \| number`                | —       |
| `onChange`     | 选中值变更回调（值优先）                                                                                       | `ChangeHandler<string \| number>` | —       |
| `disabled`     | 是否禁用（一并禁用组内全部选项）                                                                                   | `boolean`                         | `false` |
| `tabIndex`     | Tab 序（焦点停在整组）                                                                                      | `number \| null`                  | `0`     |
| `...rest`      | 原生 `div` 属性（`className`、`id`、`aria-*` 等）直传根元素                                                      | `HTMLAttributes<HTMLDivElement>`  | —       |

## 与原版的差异

- **初始选中的带边框选项同样反色**：原版「初始选中不反色、点选后才反色」，本工程按主题规则统一为激活或禁用即反色。{/* deviations: dev-buttonoption-invert */}

## 另见

- 页签式直选：[TabSelect](https://ooui-react.pages.dev/components/tab-select/index.md)
- 单选组（带原生 radio 语义）：[RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md)
- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)



---
url: https://ooui-react.pages.dev/components/button-menu-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ButtonMenuSelectWidget 命令菜单

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonMenuSelectWidget) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonMenuSelectWidget.html "OO.ui.ButtonMenuSelectWidget")

按钮触发的命令菜单：选定后立即执行并收起菜单。与 [Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md) 记“当前选中项”不同，适合工具栏里“点了就执行一项命令”的场景。

## 基本用法

```tsx preview
import { useState } from "react";
import { ButtonMenuSelectWidget } from "ooui-react";

function App() {
  const [log, setLog] = useState("尚未选择");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, padding: 8 }}>
      <ButtonMenuSelectWidget
        icon="menu"
        indicator="down"
        options={[
          { value: "copy", children: "复制" },
          { value: "cut", children: "剪切" },
          { value: "paste", children: "粘贴" },
          { children: "高级" },
          { value: "selectall", children: "全选" },
        ]}
        onChoose={(v) => setLog(`执行：${String(v)}`)}
      >
        操作
      </ButtonMenuSelectWidget>
      <div>{log}</div>
    </div>
  );
}

export default App;
```

## 受控开合与保留选中态

- `open` / `defaultOpen` / `onOpenChange` 控制菜单开合（点按钮、点外部、Escape、选定均会触发 `onOpenChange`）。
- `clearOnSelect` 默认 `true`：菜单为纯命令菜单，选过的项不留选中态；置 `false` 会保留最后选定项。
- 不带 `value` 的选项渲染为分组标题（见上方“高级”）。选项数据约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md)。

```tsx preview
import { useState } from "react";
import { ButtonMenuSelectWidget } from "ooui-react";

function App() {
  const [chosen, setChosen] = useState<string | number>("share");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 260 }}>
      <ButtonMenuSelectWidget
        icon="share"
        clearOnSelect={false}
        onChoose={(value) => setChosen(value)}
        options={[
          { value: "share", children: "分享链接" },
          { value: "move", children: "移动页面" },
          { value: "protect", children: "保护页面" },
        ]}
      >
        分享
      </ButtonMenuSelectWidget>
      <div>最后选定：{String(chosen)}（菜单里保留选中态）</div>
    </div>
  );
}

export default App;
```

## 键盘

焦点在按钮上：Enter / 空格展开菜单；展开后 ↑↓ 移动高亮、Enter / 空格选定，键入字符按前缀跳转；Escape 或点外部收起。注意与 [Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md) 不同——本组件收起态聚焦时键入不会直接改选。

与原版有以下差异：

- 键盘展开同样输出按钮按压态——原版经键盘展开时按压态类会被复位流程清除。
- 前缀缓冲活跃时空格属于继续搜索，不会误开合菜单；展开态的空格与 Enter 同分支，直接选定高亮项（与按钮以空格激活的 ARIA 惯例一致）。{/* deviations: dev-bmsw-pressed dev-bmsw-gesture-guard dev-menu-space-select */}

## API

继承 [Button](https://ooui-react.pages.dev/components/button/index.md) 的按钮属性（`icon` / `indicator` / `flags` / `framed` / `disabled` 等，`onClick` 为“切换开合前触发”），另有：

| 属性              | 描述                                                                        | 类型                                    | 默认值     |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------- | ------- |
| `options`       | 菜单选项集（**必填**），书写约定见[选择与选项](https://ooui-react.pages.dev/guide/options.md) | `ButtonMenuSelectWidgetOptionProps[]` | —       |
| `open`          | 菜单是否打开（受控）                                                                | `boolean`                             | —       |
| `defaultOpen`   | 非受控初始打开态                                                                  | `boolean`                             | `false` |
| `onOpenChange`  | 菜单开合回调                                                                    | `(open: boolean) => void`             | —       |
| `onChoose`      | 选定回调（每次选定都触发，含重复）                                                         | `ChangeHandler<string \| number>`     | —       |
| `clearOnSelect` | 选定后是否清除菜单选中态                                                              | `boolean`                             | `true`  |
| `menuSpacing`   | 菜单与按钮的间距（px）                                                              | `number`                              | `4`     |
| `menuProps`     | 菜单属性覆盖（`open`/`container`/`options`/`onChoose` 等由本组件接管）                   | `object`                              | —       |

## 另见

- 记录当前选中值的下拉：[Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md)
- 触发浮层的通用按钮：[PopupButton](https://ooui-react.pages.dev/components/popup-button/index.md)
- 命令菜单的更多形态：工具栏的 `MenuToolGroup`



---
url: https://ooui-react.pages.dev/components/checkbox-multiselect/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# CheckboxMultiselect 复选组

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/CheckboxMultiselect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CheckboxMultiselectWidget.html "OO.ui.CheckboxMultiselectWidget")

复选组：若干复选项排成一组，可同时选中多项。

## 基本用法

选中值是**数组**，通过 `value` / `defaultValue` / `onChange` 传递，`onChange` 携带完整的值数组。传 `name` 时每个选项的 checkbox 同名，勾选项随表单以多个同名字段提交。

```tsx preview
import { useState } from "react";
import { CheckboxMultiselect } from "ooui-react";

const options = [
  { value: "apple", children: "苹果" },
  { value: "banana", children: "香蕉" },
  { value: "cherry", children: "樱桃" },
];

function App() {
  const [value, setValue] = useState<Array<string | number>>(["banana"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <CheckboxMultiselect options={options} value={value} onChange={setValue} name="fruits" />
      <div>当前选中：{value.join("、") || "（无）"}</div>
      <CheckboxMultiselect options={options} defaultValue={["apple", "cherry"]} />
    </div>
  );
}

export default App;
```

## Shift+点击范围选择

先点击一项，再按住 `Shift` 点击另一项：两次点击之间的区间（含两端）统一置为**后一项**翻转后的状态，区间内的禁用项保持原状。这对应表格列表里批量勾选的场景。

```tsx preview
import { useState } from "react";
import { CheckboxMultiselect } from "ooui-react";

const options = ["一", "二", "三", "四", "五"].map((text, index) => ({
  value: index + 1,
  children: `第 ${text} 项`,
}));

function App() {
  const [value, setValue] = useState<Array<string | number>>([]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <CheckboxMultiselect options={options} value={value} onChange={setValue} />
      <div style={{ fontSize: 13 }}>
        当前选中：{value.join("、") || "（无）"}
      </div>
      <div style={{ color: "#54595d", fontSize: 13 }}>
        先点击一项，再按住 Shift 点击另一项，观察范围选择
      </div>
    </div>
  );
}

export default App;
```

## 与 FieldLayout 配合

给整组加字段标签时，用 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 包裹。点击字段标签会把焦点移到首个可用选项的复选框上（不像复选框那样直接切换勾选——组内没有「整组一个值」的语义）。

```tsx preview
import { CheckboxMultiselect, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="订阅的栏目">
        <CheckboxMultiselect
          defaultValue={["news"]}
          options={[
            { value: "news", children: "新闻" },
            { value: "sports", children: "体育" },
            { value: "tech", children: "科技" },
          ]}
        />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 禁用

- 选项对象自己的 `disabled` 禁用该项（跳过、不可勾选）。
- 组件级 `disabled` 会一并禁用组内全部选项，且组禁用优先。详见[选择与选项 · 禁用](https://ooui-react.pages.dev/guide/options.md#%E7%A6%81%E7%94%A8)。

```tsx preview
import { CheckboxMultiselect } from "ooui-react";

function App() {
  return (
    <CheckboxMultiselect
      defaultValue={["a"]}
      options={[
        { value: "a", children: "可用" },
        { value: "b", children: "被禁用项", disabled: true },
        { value: "c", children: "也可用" },
      ]}
    />
  );
}

export default App;
```

## 键盘与焦点

- 每个选项的原生 `<input type="checkbox">` 都在 Tab 序中；↑↓←→ 提供组内快捷移动——在**非禁用项**之间环绕移动焦点（与 `RadioSelect` 不同，只移动焦点、**不直接改选**），空格切换当前项勾选。
- `Shift+点击` 的范围选择以「上一次点击（或空格切换）的项」为起点。
- `onChange` 的第二个参数是触发本次变化的原生 `change` 事件。
- 选项根元素带 `role='checkbox'` 与 `aria-checked`（原版选项根无 role、仅以选中类表达），读屏器可直接读到各选项状态。{/* deviations: dev-multioption-role */}

## API

| 属性             | 描述                                                                                                                                               | 类型                                                      | 默认值     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------- |
| `options`      | 选项集，按展示顺序渲染；每项含 `value` 与 `children`（选项文本），支持 `disabled`，另有 `inputRef`（内层 checkbox 引用）、`checkboxProps`（透传内层 checkbox，如 `inputId`）与选项级 `onChange` | `CheckboxMultiselectOptionProps[]`                      | —       |
| `value`        | 当前选中值集合（受控，传入后即进入受控模式）                                                                                                                           | `(string \| number)[]`                                  | —       |
| `defaultValue` | 非受控初始选中值集合                                                                                                                                       | `(string \| number)[]`                                  | `[]`    |
| `onChange`     | 选中值集合变更回调，携带完整的值数组与原生事件                                                                                                                          | `ChangeHandler<(string \| number)[], HTMLInputElement>` | —       |
| `name`         | 表单字段名，透传给每个选项的 `checkbox`                                                                                                                        | `string`                                                | —       |
| `disabled`     | 是否禁用（一并禁用组内全部选项）                                                                                                                                 | `boolean`                                               | `false` |
| `...rest`      | 原生 `div` 属性（`className`、`id`、`aria-*` 等）直传分组容器                                                                                                   | `HTMLAttributes<HTMLDivElement>`                        | —       |

## 另见

- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)
- 单个复选框：[CheckboxInput](https://ooui-react.pages.dev/components/checkbox-input/index.md)
- 随表单提交的复选组字段：`CheckboxMultiselectInput`



---
url: https://ooui-react.pages.dev/components/radio-select/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# RadioSelect 单选组

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/RadioSelect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.RadioSelectWidget.html "OO.ui.RadioSelectWidget")

单选组：若干单选项排成一组，同组互斥、至多选中一项。

## 基本用法

选中值走 `value` / `defaultValue` / `onChange` 通道。取消当前选中不会自动产生新值——`onChange` 的参数始终是新的选中项 `value`。

```tsx preview
import { useState } from "react";
import { RadioSelect } from "ooui-react";

const options = [
  { value: "small", children: "小" },
  { value: "medium", children: "中" },
  { value: "large", children: "大" },
];

function App() {
  const [size, setSize] = useState<string | number>("medium");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <RadioSelect options={options} value={size} onChange={setSize} name="size" />
      <div>当前选择：{String(size)}</div>
      <RadioSelect options={options} defaultValue="large" />
    </div>
  );
}

export default App;
```

## 与 FieldLayout 配合

给整组加字段标签时，用 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 包裹；标签会关联到分组容器，点击标签聚焦整组。

```tsx preview
import { RadioSelect, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 320 }}>
      <FieldLayout label="通知方式">
        <RadioSelect
          name="notify"
          defaultValue="email"
          options={[
            { value: "email", children: "邮件" },
            { value: "sms", children: "短信" },
            { value: "none", children: "不通知" },
          ]}
        />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 禁用

- 选项对象自己的 `disabled` 禁用该项（跳过、不可选）。
- 组件级 `disabled` 会一并禁用组内全部选项，且组禁用优先。详见[选择与选项 · 禁用](https://ooui-react.pages.dev/guide/options.md#%E7%A6%81%E7%94%A8)。

```tsx preview
import { RadioSelect } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <RadioSelect
        defaultValue="a"
        options={[
          { value: "a", children: "可用" },
          { value: "b", children: "被禁用项", disabled: true },
          { value: "c", children: "也可用" },
        ]}
      />
    </div>
  );
}

export default App;
```

## 键盘与焦点

- 焦点停在**整组**上（各选项本身不进入 Tab 顺序）。↑↓←→ 在非禁用项间**环绕移动并直接改选**，Enter 重申当前项。
- 首次以 Tab 聚焦到组、且当前无任何选中项时，自动选中首个非禁用项（与原生单选组行为一致）。
- `onChange` 的第二个参数是原生 `change` 事件；经键盘方向键改选时不发原生 `change`（对齐原版），因此第二参数可能缺省。

## API

| 属性             | 描述                                             | 类型                                                               | 默认值     |
| -------------- | ---------------------------------------------- | ---------------------------------------------------------------- | ------- |
| `options`      | 选项集，每项含 `value` 与 `children`（选项文本）             | `RadioSelectOptionProps[]`                                       | —       |
| `value`        | 当前选中值（受控，传入后即进入受控模式）                           | `string \| number`                                               | —       |
| `defaultValue` | 非受控初始选中值                                       | `string \| number`                                               | —       |
| `onChange`     | 选中值变更回调（值优先，含原生事件）                             | `ChangeHandler<string \| number \| undefined, HTMLInputElement>` | —       |
| `name`         | 表单提交字段名，透传给每个选项的原生 `radio`（同名即互斥）              | `string`                                                         | —       |
| `disabled`     | 是否禁用（一并禁用组内全部选项）                               | `boolean`                                                        | `false` |
| `...rest`      | 原生 `div` 属性（`className`、`id`、`aria-*` 等）直传分组容器 | `HTMLAttributes<HTMLDivElement>`                                 | —       |

## 另见

- 单个单选框：[RadioInput](https://ooui-react.pages.dev/components/radio-input/index.md)（本组件由它逐项构成，需要自绘排版时单独使用）
- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)
- 复选版本：[CheckboxMultiselect](https://ooui-react.pages.dev/components/checkbox-multiselect/index.md)



---
url: https://ooui-react.pages.dev/components/tag-multiselect/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# TagMultiselect 标签输入

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/TagMultiselect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TagMultiselectWidget.html "OO.ui.TagMultiselectWidget")

标签输入：把值以可移除的标签（chip）呈现。自由输入形态，需要“输入过滤 + 下拉候选”时用 [MenuTagMultiselect](https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md)。

## 基本用法

在输入框内输入文本，按 **Enter**
 提交为一个标签；标签末尾按 **Backspace**
（输入框为空时）移除前一个标签；**点击标签**
把它移回输入框编辑。标签上的关闭按钮**仅移除标签**
，不会连带触发选中/编辑（菜单形态下开菜单、编辑形态下回填文本）——原版的关闭按钮点击会冒泡触发这些流程，此处有意偏离。
自由输入需要 `allowArbitrary`：与原版一致，未开启它且没有给出 `allowedValues` 时，输入的任何值都不在合法值域内，Enter 会被拒绝（不报错，但不生成标签）。白名单形态见下一节。

```tsx preview
import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["React", "TypeScript"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        allowArbitrary
        placeholder="回车添加标签"
      />
      <div>当前标签：{tags.join("、") || "（空）"}</div>
    </div>
  );
}

export default App;
```

## 键盘编辑

- **Enter** 提交输入文本为标签；**Backspace**（inline 输入框为空时）移除末尾标签并**把其文本回填输入框**以便编辑——按住 Ctrl / Cmd 则只移除、不回填。
- **← / →**：光标处于输入框两端时转入标签间导航，向前越过末项后焦点交还输入框（RTL 布局方向随之反转）；**Escape** 清空输入框中的未提交文本。

## 白名单与限制

- `allowedValues` 给出合法值域，超出其范围的标签被判为非法（除非 `allowArbitrary`）。
- `allowDuplicates` 允许重复值；`tagLimit` 限制标签数量，达到后输入禁用。
- `allowDisplayInvalidTags` 让非法值仍以标签呈现并标 invalid；不开启时会直接拒绝添加。

```tsx preview
import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>([]);

  return (
    <div style={{ maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        allowedValues={["红", "绿", "蓝"]}
        allowDisplayInvalidTags
        tagLimit={2}
        placeholder="只能输入 红 / 绿 / 蓝（非法值保留并标红），最多 2 个"
      />
    </div>
  );
}

export default App;
```

输入 `紫` 这类值域外的文本并回车，标签仍会生成并带 invalid 标记（开启 `allowDisplayInvalidTags` 的效果；不开启时直接拒绝添加）；`tagLimit` 达到 2 个后输入框禁用。注意：组件整体的 invalid 标志（红框）比 `onInvalidTagsChange` 的判定范围更宽——失焦时输入框里还留着未提交文本也会标红。看到红框却没收到 `onInvalidTagsChange`，先检查输入框是否残留文本。

## 外部值清洗：pickValidTags

导出的纯函数 `pickValidTags(values, { options?, allowedValues?, allowDuplicates? })`
 返回传入值集合中**合法的子集**
——剔除值域外的值与 `allowDuplicates`
 为假时的重复项，与组件用同一套规则（传组件同款 props 即可得到与 `onInvalidTagsChange`
 互补的集合）。外部数据回填 `value`
 之前、或提交之前清洗标签时用它。
## 输入框位置与重排

`inputPosition`
 取 `inline`
（缺省，输入框接在标签末尾）、`outline`
（输入框在标签区下方）、`none`
（无输入，纯展示，配合受控值使用）。`allowReordering`
（默认开）允许拖拽调整标签顺序，关闭时新增按 `allowedValues`
 的给定顺序插入。原版可经 `config.input`
 / `inputWidget`
 替换内部输入控件，本工程输入框内置、不可替换。
```tsx preview
import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["ooui", "react"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        inputPosition="outline"
        placeholder="输入框独立在标签区下方"
      />
      <TagMultiselect defaultValue={["只", "读", "形", "态"]} inputPosition="none" />
    </div>
  );
}

export default App;
```

## API

| 属性                             | 描述                   | 类型                                              | 默认值        |
| ------------------------------ | -------------------- | ----------------------------------------------- | ---------- |
| `value`                        | 标签值集合（受控，传入后即进入受控模式） | `(string \| number)[]`                          | —          |
| `defaultValue`                 | 非受控初始值               | `(string \| number)[]`                          | —          |
| `onChange`                     | 标签增删回调（值优先，回传标量数组）   | `ChangeHandler<(string \| number)[]>`           | —          |
| `allowedValues`                | 合法值白名单（无菜单时的取值约束）    | `(string \| number)[]`                          | —          |
| `allowArbitrary`               | 允许任意值（跳过值域判定）        | `boolean`                                       | `false`    |
| `allowDuplicates`              | 允许重复值                | `boolean`                                       | `false`    |
| `allowReordering`              | 允许拖拽重排               | `boolean`                                       | `true`     |
| `allowEditTags`                | 允许点击标签回填编辑           | `boolean`                                       | `true`     |
| `allowDisplayInvalidTags`      | 非法值仍以标签呈现（标 invalid） | `boolean`                                       | `false`    |
| `tagLimit`                     | 标签数量上限               | `number`                                        | —          |
| `inputPosition`                | 输入框位置                | `'inline' \| 'outline' \| 'none'`               | `'inline'` |
| `onInvalidTagsChange`          | 非法标签集变化回调（只读派生，不改值）  | `(invalidValues: (string \| number)[]) => void` | —          |
| `placeholder` / `name`         | 输入框占位符 / `name`      | `string`                                        | —          |
| `icon` / `indicator` / `flags` | 图标 / 指示器 / 标志        | —                                               | —          |
| `disabled`                     | 是否禁用                 | `boolean`                                       | `false`    |
| `...rest`                      | 原生 `div` 属性直传根元素     | `HTMLAttributes<HTMLDivElement>`                | —          |

:::note 与原版的差异
原版的 `tag.data`
 可为任意对象；在本工程中，标签的标识始终是标量 `value`
，以便受控数组可序列化、可比对。需要随标签携带对象时，改用 [MenuTagMultiselect](https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md)
 的选项 `data`
 字段，按 `value`
 在自己的 `options`
 里反查。
:::
## 另见

- 带候选菜单的标签输入：[MenuTagMultiselect](https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md)
- 选项数据的 `label` / `labelText` / `data` 约定：[选择与选项](https://ooui-react.pages.dev/guide/options.md#%E6%A0%87%E7%AD%BE%E5%A4%9A%E9%80%89%E7%9A%84%E9%80%89%E9%A1%B9)



---
url: https://ooui-react.pages.dev/components/menu-tag-multiselect/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# MenuTagMultiselect 菜单标签输入

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/MenuTagMultiselect) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MenuTagMultiselectWidget.html "OO.ui.MenuTagMultiselectWidget")

带候选菜单的标签输入，属性与 [TagMultiselect](https://ooui-react.pages.dev/components/tag-multiselect/index.md) 一致，另增必填的 `options`。

## 基本用法

输入即过滤候选，↑↓ 在候选间移动高亮，Enter 选定高亮项（无高亮时提交输入文本）；未开启 `allowArbitrary` 时，输入文本不在候选值域内会被拒绝（不报错，但不生成标签），需要自由输入见下节。候选自身的 `disabled` 表示禁用项——不可添加为标签。

```tsx preview
import { useState } from "react";
import { MenuTagMultiselect } from "ooui-react";

const options = [
  { value: "bold", label: "加粗", icon: "bold" },
  { value: "italic", label: "斜体", icon: "italic" },
  { value: "link", label: "链接", icon: "link" },
  { value: "image", label: "图片", icon: "image" },
];

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["bold"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 360 }}>
      <MenuTagMultiselect
        options={options}
        value={tags}
        onChange={setTags}
        placeholder="输入以过滤，或从菜单挑选"
      />
      <div>已选：{tags.join("、") || "（空）"}</div>
    </div>
  );
}

export default App;
```

## 切换语义与标签编辑

菜单候选是**切换语义**
：对已选中的候选再次 Enter / 点击会**移除**
对应标签——同一候选既是添加入口也是移除入口，已添加标签对应的菜单项呈选中态（键入添加的标签同样同步选中态）。
点击标签的行为取决于 `allowArbitrary`：未开启时点击标签是在菜单中定位（打开菜单并高亮对应候选），[TagMultiselect](https://ooui-react.pages.dev/components/tag-multiselect/index.md) 的 `allowEditTags` 回填编辑不生效；开启 `allowArbitrary` 后点击标签才把标签文本移回输入框编辑。

:::note 与原版的差异
`inputPosition='none'`
（无输入框）形态下点击标签同样能展开菜单并高亮被点项——原版该形态没有任何展开菜单的路径；展开后暂无键盘导航。
:::
## 值域与任意值

未开启 `allowArbitrary` 时，标签的合法值域是 `allowedValues` 与 `options` 各项 `value` 的并集——通常只给 `options`，即只能添加候选里的值。开启 `allowArbitrary` 后，还可输入候选之外的自由文本作为标签。`clearInputOnChoose`（默认开）决定选定菜单项后是否清空输入框里的过滤文本。

```tsx preview
import { useState } from "react";
import { MenuTagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>([]);

  return (
    <div style={{ maxWidth: 360 }}>
      <MenuTagMultiselect
        allowArbitrary
        options={[
          { value: "cat", label: "猫" },
          { value: "dog", label: "狗" },
        ]}
        value={tags}
        onChange={setTags}
        placeholder="可从候选选，也可自由输入回车添加"
      />
    </div>
  );
}

export default App;
```

## 富内容标签

选项 `label` 收 `ReactNode`；当它是富内容（非纯字符串）时，前缀过滤与回填需要的纯文本要经 `labelText` 显式给出，否则该选项不参与前缀过滤（详见[选择与选项 · 标签多选的选项](https://ooui-react.pages.dev/guide/options.md#%E6%A0%87%E7%AD%BE%E5%A4%9A%E9%80%89%E7%9A%84%E9%80%89%E9%A1%B9)）。`fixed: true` 的标签固定、不可移除。

```tsx preview
import { useState } from "react";
import { MenuTagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["template"]);

  return (
    <div style={{ maxWidth: 320 }}>
      <MenuTagMultiselect
        value={tags}
        onChange={setTags}
        placeholder="试试输入「重」按前缀过滤"
        options={[
          {
            value: "template",
            label: (
              <>
                <b>模板</b>（常规页面）
              </>
            ),
            labelText: "模板",
            fixed: true,
          },
          {
            value: "redirect",
            label: (
              <>
                <b>重定向</b>（指向其他页面）
              </>
            ),
            labelText: "重定向",
          },
        ]}
      />
    </div>
  );
}

export default App;
```

标签「模板」来自 `fixed: true` 的候选，带固定标记（无关闭按钮）；键入「重」能按 `labelText` 过滤到「重定向」候选并回填纯文本。

## API

在 [TagMultiselect](https://ooui-react.pages.dev/components/tag-multiselect/index.md) 全部属性之上：

| 属性                   | 描述                                                                                                                                        | 类型                                | 默认值    |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------ |
| `options`            | 候选菜单选项集（**必填**），字段见[选择与选项](https://ooui-react.pages.dev/guide/options.md#%E6%A0%87%E7%AD%BE%E5%A4%9A%E9%80%89%E7%9A%84%E9%80%89%E9%A1%B9) | `MenuTagMultiselectOptionProps[]` | —      |
| `clearInputOnChoose` | 选定菜单项后是否清空过滤文本                                                                                                                            | `boolean`                         | `true` |

## 另见

- 无候选菜单的自由输入：[TagMultiselect](https://ooui-react.pages.dev/components/tag-multiselect/index.md)
- 选项数据与键盘焦点模型：[选择与选项](https://ooui-react.pages.dev/guide/options.md)



---
url: https://ooui-react.pages.dev/components/button-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ButtonInput 提交按钮

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/ButtonInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonInputWidget.html "OO.ui.ButtonInputWidget")

表单按钮：渲染真实的 `<button>` / `<input>` 元素，`type` / `name` / `value` / `formNoValidate` 参与表单原生提交。没有提交需求时用 [Button](https://ooui-react.pages.dev/components/button/index.md)。

## 基本用法

放进 [FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md) 即可触发原生提交；`type="submit"` 的按钮携带自身的 `name` / `value`，点哪个提交哪个。

```tsx preview
import { useState } from "react";
import { ButtonInput, FormLayout, HiddenInputWidget } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        const pairs: string[] = [];
        new FormData(event.currentTarget).forEach((value, key) => {
          pairs.push(`${key}=${value}`);
        });
        setSubmitted(pairs.join(" & "));
      }}
    >
      <HiddenInputWidget name="source" value="demo" />
      <ButtonInput type="submit" flags={["primary", "progressive"]}>
        保存
      </ButtonInput>
      <ButtonInput type="submit" name="action" value="draft" formNoValidate>
        存草稿（跳过校验）
      </ButtonInput>
      {submitted && <div>提交内容：{submitted}</div>}
    </FormLayout>
  );
}

export default App;
```

## input 形态

`useInputTag` 渲染为 `<input>` 而非 `<button>`：标签文本就是提交值，不支持图标、指示器与 `value` 属性（标签仅支持纯文本）。

```tsx preview
import { ButtonInput } from "ooui-react";

function App() {
  return (
    <ButtonInput type="submit" useInputTag flags={["primary", "progressive"]}>
      保存
    </ButtonInput>
  );
}

export default App;
```

## API

| 属性                          | 描述                                           | 类型                                                   | 默认值        |
| --------------------------- | -------------------------------------------- | ---------------------------------------------------- | ---------- |
| `children`                  | 按钮文本                                         | `ReactNode`                                          | —          |
| `type`                      | 原生 `type` 属性                                 | `'button' \| 'submit' \| 'reset'`                    | `'button'` |
| `name` / `value`            | 提交字段名与值（`useInputTag` 时无效，`<input>` 的值为标签文本） | `string`                                             | —          |
| `formNoValidate`            | 提交时跳过表单校验                                    | `boolean`                                            | `false`    |
| `useInputTag`               | 渲染为 `<input>` 而非 `<button>`                  | `boolean`                                            | `false`    |
| `flags`                     | 附加标志（色彩与形态）                                  | `ButtonFlag \| ButtonFlag[]`                         | `[]`       |
| `framed`                    | 是否带边框                                        | `boolean`                                            | `true`     |
| `active`                    | 是否为激活状态                                      | `boolean`                                            | `false`    |
| `icon` / `indicator`        | 图标 / 指示器（`useInputTag` 时不支持）                 | `string` / `'clear' \| 'up' \| 'down' \| 'required'` | —          |
| `invisibleLabel`            | 标签视觉隐藏但保留可访问名称                               | `boolean`                                            | `false`    |
| `onClick`                   | 点击回调（键盘 Enter/空格同样触发）                        | `(ev) => void`                                       | —          |
| `onMouseDown` / `onMouseUp` | 鼠标按下 / 松开回调；按下进入、松开复位按压态（禁用时不进入）             | `(ev) => void`                                       | —          |
| `onKeyDown` / `onKeyUp`     | 按键按下 / 松开回调；Enter / 空格进入与复位按压态，其余键仅转发事件      | `(ev) => void`                                       | —          |
| `accessKey`                 | 快捷键（写在真实 `button` / `input` 上）               | `string`                                             | —          |
| `disabled`                  | 是否禁用                                         | `boolean`                                            | `false`    |
| `...rest`                   | 原生 `span` 属性直传根元素                            | `HTMLAttributes<HTMLSpanElement>`                    | —          |

键盘与鼠标按压期间输出按压态类（`oo-ui-buttonElement-pressed`），与原版一致。

## 另见

- 无表单提交需求的按钮：[Button](https://ooui-react.pages.dev/components/button/index.md)
- 表单容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)
- 随表单提交的选择字段：[DropdownInput](https://ooui-react.pages.dev/components/dropdown-input/index.md)



---
url: https://ooui-react.pages.dev/components/dropdown-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# DropdownInput 下拉字段

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/DropdownInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.DropdownInputWidget.html "OO.ui.DropdownInputWidget")

表单下拉选择：Dropdown 负责展示与交互，内嵌的隐藏 `<select>` 承载表单提交（`name` 写在它上面）。

## 基本用法

值通过 `value` / `defaultValue` / `onChange` 传递。传入的值不在可选项内时回退为第一个可选值，组件始终有有效值。

```tsx preview
import { useState } from "react";
import { ButtonInput, DropdownInput, FormLayout } from "ooui-react";

function App() {
  const [size, setSize] = useState<string | number>("m");
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("size")?.toString() ?? "");
      }}
    >
      <DropdownInput
        name="size"
        value={size}
        onChange={setSize}
        options={[
          { value: "s", children: "小" },
          { value: "m", children: "中" },
          { value: "l", children: "大" },
        ]}
      />
      <ButtonInput type="submit">提交</ButtonInput>
      <div>当前值：{String(size)}；已提交：{submitted}</div>
    </FormLayout>
  );
}

export default App;
```

传入的值不在可选项内时回退为第一个可选值——下面的示例初值 `xl` 是非法值，下拉框显示「小」，照常提交 `s`：

```tsx preview
import { useState } from "react";
import { ButtonInput, DropdownInput, FormLayout } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("size")?.toString() ?? "");
      }}
    >
      <DropdownInput
        name="size"
        defaultValue="xl"
        options={[
          { value: "s", children: "小" },
          { value: "m", children: "中" },
          { value: "l", children: "大" },
        ]}
      />
      <ButtonInput type="submit">提交</ButtonInput>
      <div>已提交：{submitted || "（未提交）"}</div>
    </FormLayout>
  );
}

export default App;
```

## 分组选项

不带 `value` 的选项是分组标题，映射为隐藏 `<select>` 的 `<optgroup>`（`disabled` 可禁用整组）。

```tsx preview
import { DropdownInput } from "ooui-react";

function App() {
  return (
    <DropdownInput
      defaultValue="apple"
      options={[
        { children: "水果" },
        { value: "apple", children: "苹果" },
        { value: "banana", children: "香蕉" },
        { children: "蔬菜" },
        { value: "carrot", children: "胡萝卜" },
      ]}
    />
  );
}

export default App;
```

:::note
移动端形态（[OOUIProvider](https://ooui-react.pages.dev/guide/configuration.md#%E7%A7%BB%E5%8A%A8%E7%AB%AF%E5%BD%A2%E6%80%81) 的 `isMobile`）下主题 CSS 隐藏 Dropdown、改用原生 `<select>` 交互，对齐原版分支。
:::

## API

| 属性             | 描述                                                                         | 类型                                                   | 默认值     |
| -------------- | -------------------------------------------------------------------------- | ---------------------------------------------------- | ------- |
| `options`      | 选项集：带 `value` 的为可选项（`children` 为显示文本，`disabled` 可禁用），不带的为分组标题              | `DropdownInputOptionProps[]`                         | —       |
| `value`        | 当前选中值（受控，传入后即进入受控模式）                                                       | `string \| number`                                   | —       |
| `defaultValue` | 非受控初始选中值                                                                   | `string \| number`                                   | —       |
| `onChange`     | 选中值变化回调（第二参数为原生 change 事件：移动端原生 `<select>` 路径携带；桌面菜单选定无原生事件，为 `undefined`） | `ChangeHandler<string \| number, HTMLSelectElement>` | —       |
| `name`         | 表单字段名（写在隐藏 `<select>` 上）                                                   | `string`                                             | —       |
| `required`     | 必填（原生 `required`，由隐藏 `<select>` 承载）                                        | `boolean`                                            | `false` |
| `disabled`     | 是否禁用                                                                       | `boolean`                                            | `false` |
| `tabIndex`     | 转发给内部的 Dropdown（最终写在 handle 上）                                             | `number`                                             | —       |
| `...rest`      | 原生 `div` 属性直传根元素                                                           | `HTMLAttributes<HTMLDivElement>`                     | —       |

## 另见

- 交互层的下拉选择：[Dropdown](https://ooui-react.pages.dev/components/dropdown/index.md)
- 表单容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)
- 单选组字段：[RadioSelectInput](https://ooui-react.pages.dev/components/radio-select-input/index.md)



---
url: https://ooui-react.pages.dev/components/checkbox-multiselect-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# CheckboxMultiselectInput 复选组字段

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/CheckboxMultiselectInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CheckboxMultiselectInputWidget.html "OO.ui.CheckboxMultiselectInputWidget")

表单复选组：[CheckboxMultiselect](https://ooui-react.pages.dev/components/checkbox-multiselect/index.md) 的表单形态——展示与交互不变，各选项的 checkbox 写入 `name` 与自身 `value`，勾选项随表单以多个同名字段原生提交。

## 基本用法

值通道与 [CheckboxMultiselect](https://ooui-react.pages.dev/components/checkbox-multiselect/index.md) 一致：数组形式的 `value` / `defaultValue` / `onChange`。

```tsx preview
import { useState } from "react";
import { ButtonInput, CheckboxMultiselectInput, FormLayout } from "ooui-react";

const FRUITS = [
  { value: "apple", children: "苹果" },
  { value: "banana", children: "香蕉" },
  { value: "cherry", children: "樱桃" },
];

function App() {
  const [fruits, setFruits] = useState<Array<string | number>>(["apple"]);
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        const values: string[] = [];
        new FormData(event.currentTarget).forEach((value, key) => {
          if (key === "fruits") {
            values.push(String(value));
          }
        });
        setSubmitted(values.join("、") || "（未勾选）");
      }}
    >
      <CheckboxMultiselectInput
        name="fruits"
        value={fruits}
        onChange={setFruits}
        options={FRUITS}
      />
      <ButtonInput type="submit">提交</ButtonInput>
      <div>已提交：{submitted}</div>
    </FormLayout>
  );
}

export default App;
```

:::note 性能
映射后的选项集仅在 `options` 引用变化时重算：热点路径请传稳定引用（模块常量或 `useMemo`），不要内联数组字面量。
:::

## API

继承 [CheckboxMultiselect](https://ooui-react.pages.dev/components/checkbox-multiselect/index.md) 的全部属性（`options` / `value` / `defaultValue` / `onChange` / `name` / `disabled` 等），无新增字段。

:::note
选项 checkbox 的 `value` 由本组件接管（写入选项自身 `value` 供表单提交），调用方经 `options[].checkboxProps.value` 传入的值会被覆盖。
:::

## 另见

- 交互层的复选组（Shift+点击范围选择等）：[CheckboxMultiselect](https://ooui-react.pages.dev/components/checkbox-multiselect/index.md)
- 单选组字段：[RadioSelectInput](https://ooui-react.pages.dev/components/radio-select-input/index.md)
- 表单容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)



---
url: https://ooui-react.pages.dev/components/radio-select-input/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# RadioSelectInput 单选组字段

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/RadioSelectInput) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.RadioSelectInputWidget.html "OO.ui.RadioSelectInputWidget")

表单单选组：[RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md) 负责展示与键盘交互，内嵌的隐藏 `<input>` 承载表单提交。

## 基本用法

与 [RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md) 的区别：`name` 不写在各 `radio` 上（互斥由受控状态保证），且组件**始终有选中项**——传入的值不在可选项内时回退为第一个可选值，与 HTML 单选表单「必有选中项」的语义一致。

```tsx preview
import { useState } from "react";
import { ButtonInput, FormLayout, RadioSelectInput } from "ooui-react";

function App() {
  const [notify, setNotify] = useState<string | number>("email");
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("notify")?.toString() ?? "");
      }}
    >
      <RadioSelectInput
        name="notify"
        value={notify}
        onChange={setNotify}
        options={[
          { value: "email", children: "邮件" },
          { value: "sms", children: "短信" },
          { value: "none", children: "不通知" },
        ]}
      />
      <ButtonInput type="submit">提交</ButtonInput>
      <div>当前值：{String(notify)}；已提交：{submitted}</div>
    </FormLayout>
  );
}

export default App;
```

值失效回退：下面的示例初值 `fax` 不在选项内，回退为第一个可选值「邮件」且照常提交 `email`：

```tsx preview
import { useState } from "react";
import { ButtonInput, FormLayout, RadioSelectInput } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <FormLayout
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(new FormData(event.currentTarget).get("notify")?.toString() ?? "");
      }}
    >
      <RadioSelectInput
        name="notify"
        defaultValue="fax"
        options={[
          { value: "email", children: "邮件" },
          { value: "sms", children: "短信" },
          { value: "none", children: "不通知" },
        ]}
      />
      <ButtonInput type="submit">提交</ButtonInput>
      <div>已提交：{submitted || "（未提交）"}</div>
    </FormLayout>
  );
}

export default App;
```

## API

| 属性             | 描述                                                                 | 类型                                                  | 默认值     |
| -------------- | ------------------------------------------------------------------ | --------------------------------------------------- | ------- |
| `options`      | 选项集，每项含 `value` 与 `children`（选项文本），支持 `disabled`                   | `RadioSelectInputOptionProps[]`                     | —       |
| `value`        | 当前选中值（受控，传入后即进入受控模式）                                               | `string \| number`                                  | —       |
| `defaultValue` | 非受控初始选中值                                                           | `string \| number`                                  | —       |
| `onChange`     | 选中值变化回调（第二参数为 radio 原生 change 事件，点击改选时携带；键盘改选与聚焦自动选中对应原版的静默更新，无事件） | `ChangeHandler<string \| number, HTMLInputElement>` | —       |
| `name`         | 表单字段名（只写在隐藏 `input` 上）                                             | `string`                                            | —       |
| `disabled`     | 是否禁用（隐藏 `input` 一并禁用，退出提交）                                         | `boolean`                                           | `false` |
| `tabIndex`     | 转发给内部 RadioSelect 的根                                               | `number`                                            | —       |
| `...rest`      | 原生 `div` 属性直传根元素                                                   | `HTMLAttributes<HTMLDivElement>`                    | —       |

原版构造选项时只转发 `data`
 与 `label`
，`options[].disabled`
 被静默丢弃；本工程按声明采纳 `disabled`
，与 [CheckboxMultiselectInput](https://ooui-react.pages.dev/components/checkbox-multiselect-input/index.md)
、[DropdownInput](https://ooui-react.pages.dev/components/dropdown-input/index.md)
 的做法一致。
## 另见

- 交互层的单选组：[RadioSelect](https://ooui-react.pages.dev/components/radio-select/index.md)
- 下拉字段形态：[DropdownInput](https://ooui-react.pages.dev/components/dropdown-input/index.md)
- 复选组字段：[CheckboxMultiselectInput](https://ooui-react.pages.dev/components/checkbox-multiselect-input/index.md)



---
url: https://ooui-react.pages.dev/components/hidden-input-widget/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# HiddenInputWidget 隐藏字段

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/widgets/HiddenInputWidget) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.HiddenInputWidget.html "OO.ui.HiddenInputWidget")

隐藏输入：不显示、只在 `<form>` 提交时携带固定值的字段。

## 基本用法

`value` 是受控值（随 props 更新），`name` 是提交时的字段名。下面的演示把表单提交拦截下来打印字段，可以看到禁用的隐藏字段不随提交输出。

```tsx preview
import { useState } from "react";
import { ButtonInput, FieldLayout, FormLayout, HiddenInputWidget } from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState("");

  return (
    <div style={{ maxWidth: 420 }}>
      <FormLayout
        onSubmit={(event) => {
          event.preventDefault();
          const pairs: string[] = [];
          new FormData(event.currentTarget).forEach((value, key) => {
            pairs.push(`${key}=${value}`);
          });
          setSubmitted(pairs.join(" & "));
        }}
      >
        <HiddenInputWidget name="pageId" value="4711" />
        <HiddenInputWidget name="traceId" value="keep-me" />
        {/* 禁用的隐藏字段不随表单提交 */}
        <HiddenInputWidget name="draft" value="ignored" disabled />
        <FieldLayout label=" ">
          <ButtonInput type="submit">提交</ButtonInput>
        </FieldLayout>
        {submitted && <div>提交内容：{submitted}</div>}
      </FormLayout>
    </div>
  );
}

export default App;
```

## 禁用

与原版不同：原版的「禁用」只切换样式类，隐藏字段**仍会**
随表单提交；本工程把 `disabled`
 写在原生属性上，禁用后该字段退出提交（如上方演示）。没有需要屏蔽的提交场景时，不必传 `disabled`
。
## API

| 属性         | 描述                                                | 类型                                      | 默认值     |
| ---------- | ------------------------------------------------- | --------------------------------------- | ------- |
| `value`    | 隐藏输入的值（受控，随 props 更新）                             | `string`                                | `''`    |
| `name`     | 提交时的字段名                                           | `string`                                | —       |
| `disabled` | 是否禁用（禁用后退出表单提交）                                   | `boolean`                               | `false` |
| `...rest`  | 原生 `<input>` 属性（`id`、`className`、`data-*` 等）直传根元素 | `InputHTMLAttributes<HTMLInputElement>` | —       |

本组件没有包裹元素：组件 `ref` 与属性都写在 `<input type="hidden">` 本身。

## 另见

- 表单容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)
- 值通道约定：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)



---
url: https://ooui-react.pages.dev/components/layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Layout 布局基类

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/Layout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Layout.html "OO.ui.Layout")

布局基类：其余布局组件的共同根。单独使用时只提供 `oo-ui-layout` 根类与 `hidden` 三态控制。

## 隐藏的三态

`hidden` 有三态：`true` 完全隐藏（`hidden` 属性 + `aria-hidden`）；`'until-found'` 视觉隐藏但对浏览器页内查找（Ctrl+F）可见——查找命中时浏览器自动显示该元素并派发 `beforematch` 事件，可在元素上监听做自定义联动（[IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md) 的 `openMatchedPanels` 就是这种用法）；不传则不隐藏。

```tsx preview
import { useState } from "react";
import { Button, Layout } from "ooui-react";

function App() {
  const [hidden, setHidden] = useState<boolean | "until-found">(false);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <Layout hidden={hidden}>
        <p>
          {hidden === "until-found"
            ? "对查找可见：用浏览器 Ctrl+F 搜本段文字，浏览器会自动定位并显示"
            : "当前可见"}
        </p>
      </Layout>
      <div style={{ display: "flex", gap: 8 }}>
        <Button onClick={() => setHidden(true)}>hidden</Button>
        <Button onClick={() => setHidden("until-found")}>until-found</Button>
        <Button onClick={() => setHidden(false)}>取消隐藏</Button>
      </div>
    </div>
  );
}

export default App;
```

:::note
React 18 会把 `'until-found'` 一并写成布尔 `hidden`，组件在提交后手动补写属性使其生效；React 19 起类型原生支持后即不再需要。
:::

## API

| 属性        | 描述                                                                                                  | 类型                               | 默认值 |
| --------- | --------------------------------------------------------------------------------------------------- | -------------------------------- | --- |
| `hidden`  | 是否隐藏：`true` 完全隐藏；`'until-found'` 视觉隐藏但对页内查找可见                                                       | `boolean \| 'until-found'`       | —   |
| `...rest` | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素；需要监听 `beforematch` 时经 ref 添加原生监听（React 18 的类型尚未收录该事件） | `HTMLAttributes<HTMLDivElement>` | —   |

## 另见

- 在其上的形态开关：[PanelLayout](https://ooui-react.pages.dev/components/panel-layout/index.md)
- `until-found` 的完整应用：[IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md) 的 `openMatchedPanels`



---
url: https://ooui-react.pages.dev/components/panel-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# PanelLayout 面板

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/PanelLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PanelLayout.html "OO.ui.PanelLayout")

面板：带一组形态开关（内边距、滚动、铺满、边框）的内容容器，也是 [StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md) 等布局组件的基础。

## 基本用法

```tsx preview
import { PanelLayout } from "ooui-react";

function App() {
  return (
    <div style={{ position: "relative", height: 120 }}>
      <PanelLayout padded scrollable framed>
        <p>带内边距与边框的面板；内容超高时出现滚动条。</p>
        <p>第二段。</p>
        <p>第三段。</p>
        <p>第四段。</p>
        <p>第五段。</p>
      </PanelLayout>
    </div>
  );
}

export default App;
```

`expanded`（缺省开启）形态按绝对定位铺满父元素，父元素需自行定位并给定尺寸——上面外层 `div` 的 `position: relative` 与 `height` 即为此而设；父元素不定位、不给尺寸时，面板会以更外层的定位祖先（乃至视口）为基准铺开，看起来像「消失」。`expanded={false}` 为 static 形态、按内容收缩排列：

```tsx preview
import { PanelLayout } from "ooui-react";

function App() {
  return (
    <PanelLayout padded framed expanded={false}>
      static 形态：不铺满父元素、按内容收缩，无需定位与给定尺寸的容器。
    </PanelLayout>
  );
}

export default App;
```

以本组件为基础的 [StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md) 等布局继承该前提。

## API

| 属性           | 描述                                                                            | 类型                               | 默认值     |
| ------------ | ----------------------------------------------------------------------------- | -------------------------------- | ------- |
| `padded`     | 是否留出内边距                                                                       | `boolean`                        | `false` |
| `scrollable` | 是否可滚动                                                                         | `boolean`                        | `false` |
| `expanded`   | 是否铺满父元素                                                                       | `boolean`                        | `true`  |
| `framed`     | 是否带边框                                                                         | `boolean`                        | `false` |
| `hidden`     | 是否隐藏（三态语义见 [Layout](https://ooui-react.pages.dev/components/layout/index.md)） | `boolean \| 'until-found'`       | —       |
| `...rest`    | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素                                 | `HTMLAttributes<HTMLDivElement>` | —       |

## 另见

- 基类的 `hidden` 三态语义：[Layout](https://ooui-react.pages.dev/components/layout/index.md)
- 由它驱动的分页容器：[StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md)



---
url: https://ooui-react.pages.dev/components/page-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# PageLayout 页面布局

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/PageLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PageLayout.html "OO.ui.PageLayout")

分页面板：[StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md) 的 `options` 数组项。一般不直接渲染，把它写进 StackLayout 的 `options` 即可。

## 单独使用

单独使用时，激活态由 `active` 声明；未声明 `active` 时按「非 `hidden` 即激活」派生，并输出 `oo-ui-pageLayout-active` 类。`label` / `value` 是随页签集对象传入的字段，组件会接收、不会写成 DOM 属性。

```tsx preview
import { StackLayout } from "ooui-react";

function App() {
  return (
    <StackLayout
      value="a"
      options={[
        { value: "a", label: "第一页", padded: true, children: "第一页内容" },
        { value: "b", label: "第二页", padded: true, children: "第二页内容" },
      ]}
    />
  );
}

export default App;
```

不经 StackLayout 直接渲染时，`active` 与 `hidden` 显式声明激活态（面板缺省 `expanded` 铺满已定位的父元素，static 摆放传 `expanded={false}`）：

```tsx preview
import { PageLayout } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <PageLayout active padded expanded={false}>
        激活页：声明 active，根元素输出 oo-ui-pageLayout-active 类
      </PageLayout>
      <PageLayout padded expanded={false} hidden>
        隐藏页：hidden 派生为非激活
      </PageLayout>
    </div>
  );
}

export default App;
```

## API

继承 [PanelLayout](https://ooui-react.pages.dev/components/panel-layout/index.md) 全部属性，另有：

| 属性                | 描述                                                                              | 类型                               | 默认值           |
| ----------------- | ------------------------------------------------------------------------------- | -------------------------------- | ------------- |
| `active`          | 是否为激活页；缺省时由 `hidden` 派生（非 `hidden` 即激活）——continuous 模式下所有页均可见、该派生失效，需显式传入以区分激活态 | `boolean`                        | 由 `hidden` 派生 |
| `scrollable`      | 是否可滚动（分页缺省可滚）                                                                   | `boolean`                        | `true`        |
| `label` / `value` | 随页签集对象传入，仅供组件接收，不写成 DOM 属性                                                      | `ReactNode` / `string \| number` | —             |

## 另见

- 分页容器：[StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md)



---
url: https://ooui-react.pages.dev/components/menu-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# MenuLayout 菜单布局

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/MenuLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MenuLayout.html "OO.ui.MenuLayout")

菜单布局：`menu`（菜单区）与 `children`（内容区）两块，按 `menuPosition` 决定菜单位置。收起菜单时菜单子树不渲染，避免隐形焦点陷阱。

## 基本用法

```tsx preview
import { useState } from "react";
import { MenuLayout, OutlineSelect } from "ooui-react";

function App() {
  const [section, setSection] = useState("intro");

  return (
    <div style={{ height: 200 }}>
      <MenuLayout
        menuPosition="before"
        expanded={false}
        menu={
          <OutlineSelect
            value={section}
            onChange={(value) => setSection(String(value))}
            options={[
              { value: "intro", children: "简介" },
              { value: "usage", children: "用法" },
            ]}
          />
        }
      >
        <div style={{ padding: 12 }}>
          {section === "intro" ? "这是「简介」内容。" : "这是「用法」内容。"}
        </div>
      </MenuLayout>
    </div>
  );
}

export default App;
```

## 菜单位置与收起

`menuPosition` 取 `before`（左，缺省）/ `after`（右）/ `top` / `bottom`；`showMenu={false}` 收起菜单。`expanded` 决定铺满父元素（`true`，缺省）还是按内容收缩（`static`）。

```tsx preview
import { useState } from "react";
import { MenuLayout } from "ooui-react";

const positions = ["before", "after", "top", "bottom"] as const;

function App() {
  const [position, setPosition] = useState<(typeof positions)[number]>("before");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <div style={{ display: "flex", gap: 8 }}>
        {positions.map((item) => (
          <button key={item} onClick={() => setPosition(item)}>
            {item}
          </button>
        ))}
      </div>
      <div style={{ height: 160 }}>
        <MenuLayout
          menuPosition={position}
          expanded={false}
          menu={<div style={{ padding: 12 }}>菜单区</div>}
        >
          <div style={{ padding: 12 }}>内容区</div>
        </MenuLayout>
      </div>
    </div>
  );
}

export default App;
```

:::note
`expanded`（缺省）形态按绝对定位铺满父元素，父元素需自行定位并给定尺寸；`expanded={false}` 为 static 形态、按内容收缩排列（上面的演示就是该形态）。菜单的宽度与位置细节由主题 CSS 决定；带完整菜单交互的成品见 [BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md) 与 [IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md)。
:::

## API

继承 [Layout](https://ooui-react.pages.dev/components/layout/index.md) 全部属性（含 `hidden` 三态），另有：

| 属性             | 描述                           | 类型                                         | 默认值        |
| -------------- | ---------------------------- | ------------------------------------------ | ---------- |
| `menu`         | 菜单区内容                        | `ReactNode`                                | —          |
| `menuPosition` | 菜单位置（非法值回退 `before`）         | `'before' \| 'after' \| 'top' \| 'bottom'` | `'before'` |
| `showMenu`     | 是否显示菜单（收起时菜单子树不渲染）           | `boolean`                                  | `true`     |
| `expanded`     | 是否铺满父元素（`false` 为 static 形态） | `boolean`                                  | `true`     |

## 另见

- 用它组装的成品：[BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md)、[IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md)
- `hidden` 三态语义：[Layout](https://ooui-react.pages.dev/components/layout/index.md)



---
url: https://ooui-react.pages.dev/components/stack-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# StackLayout 堆叠面板

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/StackLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.StackLayout.html "OO.ui.StackLayout")

堆叠布局：按 `options` 渲染一组[分页](https://ooui-react.pages.dev/components/page-layout/index.md)，同一时间只显示激活页；`continuous` 开启后全部可见、整体滚动。也是 [BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md) 的内层面板栈。

## 基本用法

激活页由 `value` / `defaultValue` / `onChange` 控制；选项即 [PageLayout](https://ooui-react.pages.dev/components/page-layout/index.md) 的字段加 `value`（兼作激活匹配与列表 key）。

```tsx preview
import { useState } from "react";
import { Button, StackLayout } from "ooui-react";

const options = [
  { value: "a", label: "第一页", padded: true, children: "第一页内容" },
  { value: "b", label: "第二页", padded: true, children: "第二页内容" },
];

function App() {
  const [page, setPage] = useState<string | number>("a");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <div style={{ display: "flex", gap: 8 }}>
        <Button onClick={() => setPage("a")}>第一页</Button>
        <Button onClick={() => setPage("b")}>第二页</Button>
      </div>
      <div style={{ position: "relative", height: 120 }}>
        <StackLayout value={page} onChange={setPage} options={options} framed />
      </div>
    </div>
  );
}

export default App;
```

:::note 形态要求
`expanded`（缺省开启）形态按绝对定位铺满父元素，父元素需已定位并给定尺寸（上面的示例容器即为此而设）；`continuous` 的整体滚动同样依赖该前提。`expanded={false}` 的 static 形态只有 [MenuLayout](https://ooui-react.pages.dev/components/menu-layout/index.md) 自身的流式内容可用——本组件的分页都是绝对定位面板，static 下没有内容高度，不要使用。
:::

激活值缺失或失效（如页被移除）时自动补选：取下一个未被移除的页，末页被移除则取新末页；从未给值或值不在选项内时取首个可用页。

## 连续模式

`continuous` 使所有页同时可见、容器整体滚动；`onPageFocus` 在焦点进入某页时触发（不改激活值），可据此做滚动联动选页。

```tsx preview
import { useState } from "react";
import { StackLayout } from "ooui-react";

function App() {
  const [focused, setFocused] = useState("");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <div style={{ height: 140 }}>
        <StackLayout
          continuous
          framed
          onPageFocus={(value) => setFocused(String(value))}
          options={[
            { value: "a", label: "第一页", padded: true, children: "第一页内容" },
            { value: "b", label: "第二页", padded: true, children: "第二页内容" },
            { value: "c", label: "第三页", padded: true, children: "第三页内容" },
          ]}
        />
      </div>
      <div>最后聚焦的页：{focused || "（点击页面内容试试）"}</div>
    </div>
  );
}

export default App;
```

## API

继承 [PanelLayout](https://ooui-react.pages.dev/components/panel-layout/index.md) 全部属性，另有：

| 属性             | 描述                                                                                        | 类型                                                                     | 默认值          |
| -------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------ |
| `options`      | 页集，[PageLayout](https://ooui-react.pages.dev/components/page-layout/index.md) 字段加 `value` | `(PageLayoutProps & { value: string \| number })[]`                    | —            |
| `value`        | 当前激活页（受控，传入后即进入受控模式）                                                                      | `string \| number`                                                     | —            |
| `defaultValue` | 非受控初始激活页                                                                                  | `string \| number`                                                     | —            |
| `onChange`     | 激活页变化回调                                                                                   | `ChangeHandler<string \| number>`                                      | —            |
| `onPageFocus`  | 焦点进入某页时触发（携带页 value；焦点联动用，不改激活值）                                                          | `(value: string \| number, event: FocusEvent<HTMLDivElement>) => void` | —            |
| `continuous`   | 是否全显示（`true` 时忽略 `value`，所有页同时可见）                                                         | `boolean`                                                              | `false`      |
| `scrollable`   | 是否可滚动（缺省随 `continuous`：连续模式容器整体滚动，非连续由页面自行滚动）                                             | `boolean`                                                              | `continuous` |

## 另见

- 单个分页的字段：[PageLayout](https://ooui-react.pages.dev/components/page-layout/index.md)
- 带大纲菜单的封装：[BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md)
- 受控值约定：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md)



---
url: https://ooui-react.pages.dev/components/booklet-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# BookletLayout 手册布局

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/BookletLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.BookletLayout.html "OO.ui.BookletLayout")

手册式布局：`outlined` 时左侧是[大纲选择](https://ooui-react.pages.dev/components/outline-select/index.md)、右侧是[页面栈](https://ooui-react.pages.dev/components/stack-layout/index.md)；不开大纲时就是纯堆叠面板。适合设置页、多节向导等内容分节的场景。

## 基本用法

`options` 数组项为 `{ value, label, children }` 加 [PageLayout](https://ooui-react.pages.dev/components/page-layout/index.md) 的面板字段；激活页由 `value` / `defaultValue` / `onChange` 控制。

```tsx preview
import { useState } from "react";
import { BookletLayout } from "ooui-react";

function App() {
  const [page, setPage] = useState<string | number>("intro");

  return (
    <div style={{ position: "relative", height: 180 }}>
      <BookletLayout
        outlined
        value={page}
        onChange={setPage}
        options={[
          { value: "intro", label: "简介", padded: true, children: "这是「简介」页。" },
          { value: "usage", label: "用法", padded: true, children: "这是「用法」页。" },
          { value: "faq", label: "常见问题", padded: true, children: "这是「常见问题」页。" },
        ]}
      />
    </div>
  );
}

export default App;
```

:::note 形态前提
`expanded`（缺省开启）形态按绝对定位铺满父元素，父元素需已定位并给定尺寸（上面的示例容器即为此而设）。`expanded={false}` 的 static 形态只有 [MenuLayout](https://ooui-react.pages.dev/components/menu-layout/index.md) 自身的流式内容可用——页面栈里的面板都是绝对定位面板，static 下没有内容高度，不要使用。`editable` 大纲的选择器与控制区在主题 CSS 中为绝对定位设计，同样只在 expanded 形态下可用。
:::

## 可编辑大纲

`editable`
 在大纲底部显示上移/下移/移除控件：选项按 `movable`
 / `removable`
 逐项声明可用性，操作结果经 `onMoveOption`
 / `onRemoveOption`
 交回调用方更新 `options`
；`outlineControlsExtra`
 可在大纲控件旁追加按钮（如「添加」）。
```tsx preview
import { useState } from "react";
import { BookletLayout, Button } from "ooui-react";

function App() {
  const [pages, setPages] = useState([
    { value: "a", label: "第一节", movable: true, removable: true, padded: true, children: "第一节内容" },
    { value: "b", label: "第二节", movable: true, removable: true, padded: true, children: "第二节内容" },
    { value: "c", label: "第三节", movable: true, removable: true, padded: true, children: "第三节内容" },
  ]);

  const move = (value: string | number, direction: -1 | 1) => {
    setPages((prev) => {
      const index = prev.findIndex((item) => item.value === value);
      const target = index + direction;
      if (target < 0 || target >= prev.length) {
        return prev;
      }
      const next = [...prev];
      [next[index], next[target]] = [next[target], next[index]];
      return next;
    });
  };

  return (
    <div style={{ position: "relative", height: 220 }}>
      <BookletLayout
        outlined
        editable
        defaultValue="a"
        options={pages}
        onMoveOption={move}
        onRemoveOption={(value) =>
          setPages((prev) => prev.filter((item) => item.value !== value))
        }
        outlineControlsExtra={
          <Button
            framed={false}
            icon="add"
            title="添加节"
            onClick={() =>
              setPages((prev) => [
                ...prev,
                {
                  value: `page-${prev.length + 1}`,
                  label: `新增节 ${prev.length + 1}`,
                  movable: true,
                  removable: true,
                  padded: true,
                  children: "新节内容",
                },
              ])
            }
          />
        }
      />
    </div>
  );
}

export default App;
```

## 连续模式与自动聚焦

`continuous` 使所有页同时可见、切页时平滑滚动到目标页；连续模式下焦点进入某页（Tab 或点击页内可聚焦元素）会反过来把该页选为激活页。`autoFocus`（缺省 `true`）在每次切页后聚焦页内第一个可聚焦元素（首帧不聚焦；焦点已在页内时不重复聚焦，移动端形态下抑制）。两者均可关。

激活页被移除时自动补选：取下一个未被移除的页，末页被移除则取新末页——大纲与页面栈保持同步。

## API

继承 [MenuLayout](https://ooui-react.pages.dev/components/menu-layout/index.md) 全部属性（`menu` / `children` 除外），另有：

| 属性                     | 描述                                                                                                                       | 类型                                                      | 默认值     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------- |
| `options`              | 页集：`value`、`label`、`movable`、`removable` 加 [PageLayout](https://ooui-react.pages.dev/components/page-layout/index.md) 字段 | 数组                                                      | —       |
| `value`                | 当前激活页（受控，传入后即进入受控模式）                                                                                                     | `string \| number`                                      | —       |
| `defaultValue`         | 非受控初始激活页                                                                                                                 | `string \| number`                                      | —       |
| `onChange`             | 激活页变化回调                                                                                                                  | `ChangeHandler<string \| number>`                       | —       |
| `outlined`             | 是否显示大纲（`false` 为纯堆叠模式）                                                                                                   | `boolean`                                               | `false` |
| `continuous`           | 是否连续显示所有页面，切页时滚动至目标页                                                                                                     | `boolean`                                               | `false` |
| `autoFocus`            | 切页后自动聚焦页内第一个可聚焦元素（首帧不聚焦）                                                                                                 | `boolean`                                               | `true`  |
| `editable`             | 是否在大纲底部显示操作控件（须 `outlined`）                                                                                              | `boolean`                                               | `false` |
| `onMoveOption`         | editable 下点击上移/下移时触发，`direction` 为 `-1`（上移）或 `1`（下移）                                                                     | `(value: string \| number, direction: -1 \| 1) => void` | —       |
| `onRemoveOption`       | editable 下点击移除时触发                                                                                                        | `(value: string \| number) => void`                     | —       |
| `outlineControlsExtra` | editable 下大纲控件左侧的额外按钮区                                                                                                   | `ReactNode`                                             | —       |

## 另见

- 右侧的页面栈：[StackLayout](https://ooui-react.pages.dev/components/stack-layout/index.md)
- 左侧的大纲选择：[OutlineSelect](https://ooui-react.pages.dev/components/outline-select/index.md)
- 顶部页签的变体：[IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md)



---
url: https://ooui-react.pages.dev/components/index-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# IndexLayout 索引布局

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/IndexLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.IndexLayout.html "OO.ui.IndexLayout")

页签布局：顶部是[页签选择](https://ooui-react.pages.dev/components/tab-select/index.md)，下方是[页签面板](https://ooui-react.pages.dev/components/tab-panel-layout/index.md)栈。适合设置页这类「顶部页签 + 分块内容」的场景；侧边大纲的变体见 [BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md)。

## 基本用法

`options` 数组项为 `{ value, label, children }` 加 [TabPanelLayout](https://ooui-react.pages.dev/components/tab-panel-layout/index.md) 的面板字段（可带 `disabled` 禁用页签）；激活页由 `value` / `defaultValue` / `onChange` 控制。页签与面板自动建立 `aria-controls` / `aria-labelledby` 关联。

```tsx preview
import { useState } from "react";
import { IndexLayout } from "ooui-react";

function App() {
  const [tab, setTab] = useState<string | number>("general");

  return (
    <div style={{ position: "relative", height: 180 }}>
      <IndexLayout
        framed
        value={tab}
        onChange={setTab}
        options={[
          { value: "general", label: "常规", padded: true, children: "常规设置内容" },
          { value: "appearance", label: "外观", padded: true, children: "外观设置内容" },
          { value: "advanced", label: "高级", padded: true, disabled: true, children: "高级设置内容" },
        ]}
      />
    </div>
  );
}

export default App;
```

:::note 形态前提
`expanded`（缺省开启）形态按绝对定位铺满父元素，父元素需已定位并给定尺寸（上面的示例容器即为此而设）。`expanded={false}` 的 static 形态只有 [MenuLayout](https://ooui-react.pages.dev/components/menu-layout/index.md) 自身的流式内容可用——本组件与 BookletLayout 的页面栈都是绝对定位面板，static 下没有内容高度，不要使用。
:::

## 浏览器查找联动

`openMatchedPanels`（缺省 `true`）让未激活面板以 `hidden="until-found"` 隐藏：用浏览器页内查找（Ctrl+F）命中隐藏面板的内容时，自动切换到对应页签。**`continuous` 使所有面板同时可见，该模式下 `openMatchedPanels` 停用**——面板不再以 until-found 隐藏，查找联动随之失效。`autoFocus`（缺省 `true`）切页后聚焦面板内第一个可聚焦元素（移动端形态下抑制）。

激活页签被移除时自动选中首个可用（非禁用）页签。

`continuous` 模式：所有面板同时可见、纵向堆叠（常用于打印与全文浏览场景）：

```tsx preview
import { useState } from "react";
import { IndexLayout } from "ooui-react";

function App() {
  const [tab, setTab] = useState<string | number>("intro");

  return (
    <div style={{ position: "relative", height: 220 }}>
      <IndexLayout
        framed
        continuous
        value={tab}
        onChange={setTab}
        options={[
          { value: "intro", label: "简介", padded: true, children: "简介内容……" },
          { value: "usage", label: "用法", padded: true, children: "用法内容……" },
          { value: "faq", label: "FAQ", padded: true, children: "常见问题……" },
        ]}
      />
    </div>
  );
}

export default App;
```

## API

继承 [MenuLayout](https://ooui-react.pages.dev/components/menu-layout/index.md) 全部属性（`menu` / `menuPosition` / `children` 除外），另有：

| 属性                  | 描述                                                                                                                                                                            | 类型                                | 默认值     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `options`           | 页签集：`value`、`label`、`disabled` 加 [TabPanelLayout](https://ooui-react.pages.dev/components/tab-panel-layout/index.md) 字段（禁用页签对应的面板始终以 `hidden` 完全隐藏，不受 `openMatchedPanels` 影响） | `IndexLayoutTabProps[]`           | —       |
| `value`             | 当前激活页签（受控，传入后即进入受控模式）                                                                                                                                                         | `string \| number`                | —       |
| `defaultValue`      | 非受控初始激活页签                                                                                                                                                                     | `string \| number`                | —       |
| `onChange`          | 激活页签变化回调                                                                                                                                                                      | `ChangeHandler<string \| number>` | —       |
| `framed`            | 页签是否有边框                                                                                                                                                                       | `boolean`                         | `true`  |
| `continuous`        | 是否显示全部面板                                                                                                                                                                      | `boolean`                         | `false` |
| `autoFocus`         | 切换面板后自动聚焦面板内第一个可聚焦元素                                                                                                                                                          | `boolean`                         | `true`  |
| `openMatchedPanels` | 未激活面板以 `hidden="until-found"` 隐藏，浏览器查找命中后自动切换页签（`continuous` 下停用）                                                                                                             | `boolean`                         | `true`  |

## 另见

- 单个页签面板的字段：[TabPanelLayout](https://ooui-react.pages.dev/components/tab-panel-layout/index.md)
- 侧边大纲的变体：[BookletLayout](https://ooui-react.pages.dev/components/booklet-layout/index.md)
- `hidden="until-found"` 三态：[Layout](https://ooui-react.pages.dev/components/layout/index.md)



---
url: https://ooui-react.pages.dev/components/tab-panel-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# TabPanelLayout 页签面板

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/TabPanelLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TabPanelLayout.html "OO.ui.TabPanelLayout")

页签面板：[IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md) 的 `options` 数组项，根元素声明 `role="tabpanel"`。一般不直接渲染。

## 单独使用

`active` 声明激活态（输出 `oo-ui-tabPanelLayout-active` 类）。`label` / `value` / `disabled` 是随页签集对象传入的字段，组件会接收这些字段，但不会写成 DOM 属性。面板缺省 `expanded`（绝对定位铺满父元素），单独摆放时需要已定位并给定尺寸的父元素。

```tsx preview
import { IndexLayout } from "ooui-react";

function App() {
  return (
    <div style={{ position: "relative", height: 180 }}>
      <IndexLayout
        defaultValue="general"
        options={[
          { value: "general", label: "常规", padded: true, children: "常规设置内容" },
          { value: "advanced", label: "高级", padded: true, children: "高级设置内容" },
        ]}
      />
    </div>
  );
}

export default App;
```

不经 IndexLayout 直接渲染时，`active` 显式声明激活态（输出 `oo-ui-tabPanelLayout-active` 类；面板缺省 `expanded` 铺满已定位的父元素，static 摆放传 `expanded={false}`）：

```tsx preview
import { TabPanelLayout } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <TabPanelLayout active padded expanded={false}>
        常规面板：声明 active，根元素输出 oo-ui-tabPanelLayout-active 类
      </TabPanelLayout>
      <TabPanelLayout padded expanded={false} hidden>
        高级面板：hidden 时整面板隐藏
      </TabPanelLayout>
    </div>
  );
}

export default App;
```

## API

继承 [PanelLayout](https://ooui-react.pages.dev/components/panel-layout/index.md) 全部属性，另有：

| 属性                             | 描述                         | 类型                                           | 默认值     |
| ------------------------------ | -------------------------- | -------------------------------------------- | ------- |
| `active`                       | 是否为当前激活面板                  | `boolean`                                    | `false` |
| `scrollable`                   | 是否可滚动（面板缺省可滚）              | `boolean`                                    | `true`  |
| `label` / `value` / `disabled` | 随页签集对象传入，仅供组件接收，不写成 DOM 属性 | `ReactNode` / `string \| number` / `boolean` | —       |

## 另见

- 页签容器（含 tabpanel 关联）：[IndexLayout](https://ooui-react.pages.dev/components/index-layout/index.md)



---
url: https://ooui-react.pages.dev/components/field-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# FieldLayout 字段布局

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/FieldLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.FieldLayout.html "OO.ui.FieldLayout")

字段布局：把一个字段控件与它的标签排在一起，是 [FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md) 里的基本单元。

## 基本用法

标签与控件的关联由组件自动完成：放进 `FieldLayout` 的输入类控件会认领一个 `id`，标签的 `htmlFor` 指向它，因此点击标签可以聚焦控件，也便于读屏器朗读。字段控件自身不需要再写 `label`。

```tsx preview
import { TextInput, FieldLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="用户名">
        <TextInput placeholder="点击左侧标签会聚焦到这里" />
      </FieldLayout>
      <FieldLayout label="邮箱">
        <TextInput type="email" placeholder="you@example.com" />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 对齐方向

`align`
 决定标签与控件的排布：`left`
（默认，标签在左）、`right`
（标签在右）、`top`
（标签在上）、`inline`
（标签与控件同行，常用于复选框、单选框）。传 `inline`
 不会自动降级（原版在字段根元素非 span 时会降级为 `top`
），传入前保证字段根元素为内联形态。
```tsx preview
import { CheckboxInput, FieldLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="标签在左" align="left">
        <TextInput />
      </FieldLayout>
      <FieldLayout label="标签在上" align="top">
        <TextInput />
      </FieldLayout>
      <FieldLayout label="同行（复选框）" align="inline">
        <CheckboxInput defaultChecked />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 标签与提示

- `label` 是标签内容（`ReactNode`）。
- `invisibleLabel` 把标签视觉隐藏，但保留可访问名称；此时 `title` 未显式给出会以标签文本兜底。
- `title` 写在标签元素上（对齐原版 `$titled = $label`），不写在布局根上。
- 字段控件登记了自己的 `accessKey` 时，标签提示末尾附上键位（组合键文案可经 [OOUIProvider](https://ooui-react.pages.dev/guide/configuration.md) 本地化）。

```tsx preview
import { FieldLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="带提示" title="这一项会被保留">
        <TextInput defaultValue="悬停标签查看提示" />
      </FieldLayout>
      <FieldLayout label="隐藏标签" invisibleLabel>
        <TextInput placeholder="视觉无标签，读屏器仍可读" />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## 禁用

`FieldLayout` 的 `disabled` 只给布局根加 `oo-ui-fieldLayout-disabled` 样式类，让字段区域呈禁用态外观，不会替你禁用 `children` 里的控件。要真正禁用，请在控件自身设置 `disabled`；需要整组一起禁用时改用基于原生 `<fieldset disabled>` 的 `FieldsetLayout`。

```tsx preview
import { FieldLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 360 }}>
      <FieldLayout label="字段名" disabled>
        <TextInput disabled defaultValue="控件需自行禁用" />
      </FieldLayout>
    </div>
  );
}

export default App;
```

## API

| 属性               | 描述                                            | 类型                                       | 默认值      |
| ---------------- | --------------------------------------------- | ---------------------------------------- | -------- |
| `children`       | 字段控件                                          | `ReactNode`                              | —        |
| `label`          | 标签内容                                          | `ReactNode`                              | —        |
| `invisibleLabel` | 标签视觉隐藏（保留可访问名称）                               | `boolean`                                | `false`  |
| `align`          | 标签对齐方向                                        | `'left' \| 'right' \| 'top' \| 'inline'` | `'left'` |
| `title`          | 标签的提示文本（写在标签元素上）                              | `string`                                 | —        |
| `disabled`       | 给布局加禁用样式类（不下发给控件）                             | `boolean`                                | `false`  |
| `...rest`        | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素 | `HTMLAttributes<HTMLDivElement>`         | —        |

## 另见

- 包裹多个 `FieldLayout` 的表单容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)
- 各控件的属性与写入位置：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md)、[CheckboxInput](https://ooui-react.pages.dev/components/checkbox-input/index.md)
- 所有组件共有的 `disabled`、`title`、`accessKey` 语义：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/components/fieldset-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# FieldsetLayout 字段分组

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/FieldsetLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.FieldsetLayout.html "OO.ui.FieldsetLayout")

字段集：原生 `<fieldset>` 加 `<legend>` 头部（标题、图标与帮助入口），字段项排在分组容器内。根是原生 `fieldset`，其 `disabled` 会原生地下发禁用组内全部输入控件。

## 基本用法

```tsx preview
import { FieldLayout, FieldsetLayout, TextInput } from "ooui-react";

function App() {
  return (
    <FieldsetLayout label="账户信息" icon="userAvatar">
      <FieldLayout label="用户名">
        <TextInput />
      </FieldLayout>
      <FieldLayout label="邮箱">
        <TextInput type="email" />
      </FieldLayout>
    </FieldsetLayout>
  );
}

export default App;
```

## 帮助文本

`help` 的呈现方式由 `helpInline` 决定：`helpInline={false}`（缺省）在头部渲染 ⓘ 图标，点击弹出说明；`helpInline={true}` 以内联文本显示在头部之后。

```tsx preview
import { CheckboxInput, FieldLayout, FieldsetLayout } from "ooui-react";

function App() {
  return (
    <FieldsetLayout
      label="通知偏好"
      help="关闭后仍会收到系统安全类通知。"
    >
      <FieldLayout label="产品动态" align="inline">
        <CheckboxInput defaultChecked />
      </FieldLayout>
      <FieldLayout label="社区活动" align="inline">
        <CheckboxInput />
      </FieldLayout>
    </FieldsetLayout>
  );
}

export default App;
```

下面把缺省的 ⓘ 弹出说明与 `helpInline={true}` 的内联文本并排放在一起：

```tsx preview
import { FieldLayout, FieldsetLayout, TextInput } from "ooui-react";

function App() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16, maxWidth: 420 }}>
      <FieldsetLayout label="弹出帮助" help="点击头部的 ⓘ 图标弹出这段说明。">
        <FieldLayout label="用户名">
          <TextInput />
        </FieldLayout>
      </FieldsetLayout>
      <FieldsetLayout
        label="内联帮助"
        helpInline
        help="这段说明直接显示在标题之后，适合一句话能讲清的场合。"
      >
        <FieldLayout label="邮箱">
          <TextInput type="email" />
        </FieldLayout>
      </FieldsetLayout>
    </div>
  );
}

export default App;
```

## 组级禁用

`disabled` 写在原生 `<fieldset>` 上，组内所有输入控件随浏览器机制一并禁用，无需逐项传递。

```tsx preview
import { CheckboxInput, FieldLayout, FieldsetLayout, TextInput } from "ooui-react";

function App() {
  return (
    <FieldsetLayout label="只读分组" disabled>
      <FieldLayout label="姓名">
        <TextInput defaultValue="不可编辑" />
      </FieldLayout>
      <FieldLayout label="已启用" align="inline">
        <CheckboxInput checked />
      </FieldLayout>
    </FieldsetLayout>
  );
}

export default App;
```

## API

| 属性               | 描述                         | 类型                                    | 默认值     |
| ---------------- | -------------------------- | ------------------------------------- | ------- |
| `label`          | 分组标题（legend 头部）            | `ReactNode`                           | —       |
| `icon`           | 头部图标                       | `string`                              | —       |
| `help`           | 帮助文本                       | `ReactNode`                           | —       |
| `helpInline`     | 帮助是否内联（`false` 渲染为 ⓘ 弹出说明） | `boolean`                             | `false` |
| `invisibleLabel` | 标题视觉隐藏但保留可访问名称             | `boolean`                             | `false` |
| `disabled`       | 组级禁用（原生下发到组内全部输入控件）        | `boolean`                             | `false` |
| `...rest`        | 原生 `fieldset` 属性直传根元素      | `HTMLAttributes<HTMLFieldSetElement>` | —       |

## 另见

- 单个字段的标签与提示：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 表单容器：[FormLayout](https://ooui-react.pages.dev/components/form-layout/index.md)



---
url: https://ooui-react.pages.dev/components/form-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# FormLayout 表单容器

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/FormLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.FormLayout.html "OO.ui.FormLayout")

表单容器：渲染一个 `<form>`，把若干 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 包起来。它本身不做数据管理，带 `name` 的输入控件随原生 `<form>` 一起提交。不需要原生提交语义时，直接把控件摆在自己的容器里即可，不必套这层。

## 基本用法

`onSubmit` 里按 React 惯例调用 `event.preventDefault()` 阻止真实跳转（原版是事件监听器返回 `false` 时阻止默认提交）。提交动作由 `type="submit"` 的 `ButtonInput` 触发。

```tsx preview
import { useState } from "react";
import {
  ButtonInput,
  CheckboxInput,
  FieldLayout,
  FormLayout,
  TextInput,
} from "ooui-react";

function App() {
  const [submitted, setSubmitted] = useState(false);

  return (
    <FormLayout
      method="post"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(true);
      }}
    >
      <FieldLayout label="用户名">
        <TextInput name="username" placeholder="必填" required />
      </FieldLayout>
      <FieldLayout label="同意条款" align="inline">
        <CheckboxInput name="agree" value="yes" required />
      </FieldLayout>
      <FieldLayout label=" " invisibleLabel>
        <ButtonInput type="submit" flags={["primary", "progressive"]}>
          提交
        </ButtonInput>
      </FieldLayout>
      {submitted && <div style={{ marginTop: 8 }}>已提交（已阻止页面跳转）</div>}
    </FormLayout>
  );
}

export default App;
```

## 提交属性

`method`、`action`、`enctype` 直通原生 `<form>` 的同名属性：

| 属性        | 说明                                                        |
| --------- | --------------------------------------------------------- |
| `method`  | 提交方法，原生 `method`（缺省 GET）                                  |
| `action`  | 提交地址，原生 `action`                                          |
| `enctype` | 编码类型，原生 `enctype`（缺省 `application/x-www-form-urlencoded`） |

:::warning 安全提示
本组件不对 `action`
 做 URL 净化（未采用原版的 `OO.ui.isSafeUrl`
）。`<form action="javascript:...">`
 会在提交时执行脚本，浏览器与 React 运行期都不拦截。来源不可信的 `action`
（如由用户输入拼接）必须先自行校验协议，否则构成 XSS；需要组件层净化时可用导出的方法 `sanitizeUrl`
。
:::
## 随表单提交的控件

原生提交只携带**真实表单控件**的值：输入框系（`TextInput`、`MultilineTextInput`、`NumberInput`、`ComboBoxInput`、`SearchInput`）、勾选系（`CheckboxInput`、`RadioInput`）与 `SelectFileInputWidget`、`HiddenInputWidget` 渲染真实控件，带 `name` 即随表单提交。

选择类的展示形态（`Select`、`Dropdown`、`RadioSelect`、`CheckboxMultiselect`、`TagMultiselect`、`TabSelect` 等）不渲染真实表单控件，放进 `FormLayout` 会在提交时**静默丢值**——要提交选择值，改用对应的表单字段形态 [DropdownInput](https://ooui-react.pages.dev/components/dropdown-input/index.md)、[RadioSelectInput](https://ooui-react.pages.dev/components/radio-select-input/index.md)、[CheckboxMultiselectInput](https://ooui-react.pages.dev/components/checkbox-multiselect-input/index.md)，或用 [HiddenInputWidget](https://ooui-react.pages.dev/components/hidden-input-widget/index.md) 携带任意自定义值。

## API

| 属性         | 描述                                                    | 类型                                  | 默认值 |
| ---------- | ----------------------------------------------------- | ----------------------------------- | --- |
| `children` | 字段集（通常为若干 `FieldLayout`）                              | `ReactNode`                         | —   |
| `method`   | 提交方法（原生 `method`）                                     | `string`                            | —   |
| `action`   | 提交地址（原生 `action`，不做净化）                                | `string`                            | —   |
| `enctype`  | 编码类型（原生 `enctype`）                                    | `string`                            | —   |
| `onSubmit` | 提交回调；需阻止默认跳转时在回调内 `event.preventDefault()`            | `FormEventHandler<HTMLFormElement>` | —   |
| `...rest`  | 原生 `form` 属性（`className`、`id`、`name`、`aria-*` 等）直传根元素 | `HTMLAttributes<HTMLFormElement>`   | —   |

## 另见

- 字段与标签的排版：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 随表单提交的输入控件：[TextInput](https://ooui-react.pages.dev/components/text-input/index.md)、[CheckboxInput](https://ooui-react.pages.dev/components/checkbox-input/index.md)
- 组件的产物形态与 SSR 限制：见[使用方式](https://ooui-react.pages.dev/guide/usage.md)



---
url: https://ooui-react.pages.dev/components/action-field-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ActionFieldLayout 动作字段

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/ActionFieldLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ActionFieldLayout.html "OO.ui.ActionFieldLayout")

带操作按钮的字段布局：在 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 的基础上，字段控件旁多一个 `button` 槽位（通常放 [Button](https://ooui-react.pages.dev/components/button/index.md) 或 [ButtonInput](https://ooui-react.pages.dev/components/button-input/index.md)）。

## 基本用法

```tsx preview
import { useState } from "react";
import { ActionFieldLayout, Button, TextInput } from "ooui-react";

function App() {
  const [tags, setTags] = useState<string[]>(["ooui"]);

  return (
    <div style={{ maxWidth: 420 }}>
      <ActionFieldLayout
        label="添加标签"
        button={
          <Button
            flags={["primary", "progressive"]}
            onClick={() => setTags((prev) => [...prev, prev.length.toString()])}
          >
            添加
          </Button>
        }
      >
        <TextInput placeholder="输入后添加" />
      </ActionFieldLayout>
      <div style={{ marginTop: 8 }}>已添加：{tags.join("、")}</div>
    </div>
  );
}

export default App;
```

## 内联控件

字段控件是 `span`
 根的内联控件（如 `CheckboxInput`
、`ButtonInput`
）时传 `fieldInline`
，输入区包装元素随之用 `span`
 渲染。传错不会有视觉影响（主题 CSS 让两种包装的布局一致），只影响 DOM 形态是否与原版一致。
## API

继承 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 全部属性（`label` / `align` / `title` 等），另有：

| 属性            | 描述                                            | 类型          | 默认值     |
| ------------- | --------------------------------------------- | ----------- | ------- |
| `button`      | 输入字段旁的按钮控件                                    | `ReactNode` | —       |
| `fieldInline` | 字段控件是否为 span 根的内联控件（决定输入区包装为 `span` 还是 `div`） | `boolean`   | `false` |

## 另见

- 字段排布与标签关联：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 只读文本框加复制按钮的成品：[CopyTextLayout](https://ooui-react.pages.dev/components/copy-text-layout/index.md)



---
url: https://ooui-react.pages.dev/components/copy-text-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# CopyTextLayout 复制文本

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/CopyTextLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.CopyTextLayout.html "OO.ui.CopyTextLayout")

复制文本布局：只读文本框加复制按钮，聚焦文本框或点击按钮时自动全选文本。适合展示链接、引用标识等需要用户复制的只读内容。

## 基本用法

`copyText` 是待复制文本（作为文本框初始值）；`onCopyResult` 在复制结束后触发，入参为是否成功。

```tsx preview
import { useState } from "react";
import { CopyTextLayout } from "ooui-react";

function App() {
  const [result, setResult] = useState("");

  return (
    <div style={{ maxWidth: 460 }}>
      <CopyTextLayout
        label="分享链接"
        copyText="https://example.com/invite/9f3k"
        onCopyResult={(copied) => setResult(copied ? "已复制" : "复制失败")}
      />
      <div style={{ marginTop: 8 }}>{result}</div>
    </div>
  );
}

export default App;
```

## 动态文本

`copyText` 只作为文本框**初始值**，复制时复制的也是文本框当前值。分享链接随用户选择变化这类场景，把受控值经 `textInputProps={{ value }}` 传入（优先于 `copyText`）——只改 `copyText` 不会更新文本框。

```tsx preview
import { useState } from "react";
import { Button, CopyTextLayout } from "ooui-react";

function App() {
  const [id, setId] = useState("9f3k");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 460 }}>
      <CopyTextLayout label="分享链接" textInputProps={{ value: `https://example.com/invite/${id}` }} />
      <Button onClick={() => setId(Math.random().toString(36).slice(2, 6))}>换一个链接</Button>
    </div>
  );
}

export default App;
```

## 多行

`multiline` 把文本框换成多行形态，复制按钮移到下方右侧。

```tsx preview
import { CopyTextLayout } from "ooui-react";

function App() {
  return (
    <div style={{ maxWidth: 460 }}>
      <CopyTextLayout
        label="嵌入代码"
        multiline
        copyText={"<script src=\"https://example.com/widget.js\"></script>"}
        textInputProps={{ rows: 3 }}
      />
    </div>
  );
}

export default App;
```

:::note 与原版的差异
复制优先使用 `navigator.clipboard`
，不可用或被权限拒绝时回退到 `document.execCommand('copy')`
（原版只用后者，该 API 已废弃、失败时无从感知）。
:::
## API

继承 [FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md) 全部属性（`label` / `align` / `title` 等），另有：

| 属性               | 描述                                                               | 类型                             | 默认值     |
| ---------------- | ---------------------------------------------------------------- | ------------------------------ | ------- |
| `copyText`       | 待复制文本（作为文本框初始值；`textInputProps.value` 给定时以后者为准）                  | `string`                       | —       |
| `multiline`      | 是否多行（文本框换用 MultilineTextInput，按钮移到下方右侧）                          | `boolean`                      | `false` |
| `textInputProps` | 文本框属性覆盖：`value` 为受控值、`readOnly` 缺省 `true`，其余透传（`inputRef` 由布局占用） | `CopyTextLayoutTextInputProps` | —       |
| `buttonProps`    | 复制按钮属性覆盖（`children` 为按钮文本，`icon` 缺省 `'copy'`）                    | `Partial<ButtonProps>`         | —       |
| `onCopyResult`   | 复制结束回调，入参为是否成功                                                   | `(copied: boolean) => void`    | —       |

## 另见

- 字段排布与标签关联：[FieldLayout](https://ooui-react.pages.dev/components/field-layout/index.md)
- 输入字段旁放普通操作按钮：[ActionFieldLayout](https://ooui-react.pages.dev/components/action-field-layout/index.md)



---
url: https://ooui-react.pages.dev/components/horizontal-layout/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# HorizontalLayout 横向布局

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/layouts/HorizontalLayout) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.HorizontalLayout.html "OO.ui.HorizontalLayout")

横向容器：仅输出 `oo-ui-horizontalLayout` 根类，排布交由主题 CSS；需要精确控制间距时自己写样式或换用普通 `div`。

## 基本用法

```tsx preview
import { Button, HorizontalLayout, TextInput } from "ooui-react";

function App() {
  return (
    <HorizontalLayout>
      <TextInput placeholder="搜索…" />
      <Button flags="primary">搜索</Button>
    </HorizontalLayout>
  );
}

export default App;
```

## API

继承 [Layout](https://ooui-react.pages.dev/components/layout/index.md) 的全部属性（含 `hidden` 三态）。

## 另见

- 基类的 `hidden` 三态语义：[Layout](https://ooui-react.pages.dev/components/layout/index.md)



---
url: https://ooui-react.pages.dev/components/dialog/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Dialog 弹窗

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/dialogs) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Dialog.html "OO.ui.Dialog") · [OO.ui.MessageDialog](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MessageDialog.html "OO.ui.MessageDialog")

弹窗组件，提供 `MessageDialog`、`ProcessDialog` 等变体。

另有不依赖 React 树的命令式 `confirm` / `alert` / `prompt`，见[命令式弹窗](https://ooui-react.pages.dev/components/imperative-dialogs/index.md)。

## MessageDialog

一段消息（`children`）加底部“确定 / 取消”两个按钮。`open` 由你控制，`onOk` / `onCancel` 里负责把它关掉。`cancelLabel={null}` 隐藏取消按钮（即自制一个受控 `alert`）。动作区横向装不下时自动切竖向布局。

```tsx preview
import { useState } from "react";
import { Button, MessageDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button flags="destructive" onClick={() => setOpen(true)}>
        删除
      </Button>
      <MessageDialog
        open={open}
        title="删除页面"
        size="small"
        okLabel="删除"
        cancelLabel="保留"
        onOk={() => setOpen(false)}
        onCancel={() => setOpen(false)}
      >
        删除后无法撤销，确定要继续吗？
      </MessageDialog>
    </>
  );
}

export default App;
```

`MessageDialog` 就绪后自动聚焦“确定”按钮；按 Ctrl / Cmd + Enter 等效点击“确定”。

`cancelLabel={null}` 隐藏取消按钮后即得单按钮形态——自制一个受控 `alert`（ESC 记得接上 `onEscape`）：

```tsx preview
import { useState } from "react";
import { Button, MessageDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>显示结果</Button>
      <MessageDialog
        open={open}
        title="操作完成"
        okLabel="知道了"
        cancelLabel={null}
        onOk={() => setOpen(false)}
        onEscape={() => setOpen(false)}
      >
        页面已移动到回收站。
      </MessageDialog>
    </>
  );
}

export default App;
```

**按 ESC 只触发 `onEscape`**（`escapable` 默认开启）：只接上 `onOk` / `onCancel` 时按 ESC 不会关闭弹窗，需自行在 `onEscape` 里处理（命令式 `confirm` 内部就是把 `onEscape` 当作「取消」处理）。

需要三个及以上动作（如「确定 / 取消 / 稍后提醒」）时传 `foot` 整体替换默认动作区：动作布局与关闭逻辑全部自理；此时不再自动聚焦“确定”按钮，可在 `onReady` 里自行聚焦。

## Dialog 基类

需要完全自定义内容时用 `Dialog`：`children` 是正文区、`foot` 是底部动作区（`head` 头部主要供带布局类的子类使用，裸基类的正文从顶部开始排布，不会自动为 `head` 让位）。它不预设任何按钮，关闭时机与回调都由你负责；有底部动作时用 `bodyFitFoot` 让正文为 `foot` 让出高度。

:::warning 与原版的差异
裸 `Dialog`
 没有内置标题槽位：自行渲染标题后把它以 `aria-labelledby`
 关联到弹窗，漏传即得到无名 `role="dialog"`
（原版基类会自动建立该关联）。
:::
```tsx preview
import { useState } from "react";
import { Button, Dialog, FieldLayout, TextInput } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState("");

  return (
    <>
      <Button onClick={() => setOpen(true)}>打开自定义弹窗</Button>
      <Dialog
        open={open}
        size="medium"
        bodyFitFoot
        onEscape={() => setOpen(false)}
        foot={
          <div style={{ display: "flex", gap: 8 }}>
            <Button onClick={() => setOpen(false)}>取消</Button>
            <Button flags="primary" onClick={() => setOpen(false)}>
              确定
            </Button>
          </div>
        }
      >
        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
          <strong>重命名条目</strong>
          <FieldLayout label="新名称">
            <TextInput value={name} onChange={setName} />
          </FieldLayout>
        </div>
      </Dialog>
    </>
  );
}

export default App;
```

## 尺寸

`size` 取 `small` / `medium` / `large` / `larger` / `full`（`Dialog` 缺省 `medium`，`MessageDialog` 缺省 `small`）。非 `full` 时弹窗按内容撑高、垂直居中；当设定宽度容不进当前视口时自动满屏。`full` 始终是满屏。

## 多窗与背景隔离

同时打开多个弹窗**不需要排队**：每个弹窗自带独立的管理器容器，叠放层次按 DOM 顺序（后开的在上），关谁由各自的 `open` 状态决定——流程弹窗之上再叠一个 confirm 是合法的。

弹窗打开期间，最上层弹窗路径以外的兄弟节点会被加上 `aria-hidden="true"`
 与 `inert`
，屏幕阅读器与指针 / 焦点都被挡在弹窗内，关闭后撤销。**不要在自己渲染的背景节点上声明 React 的 `inert` prop**
（React 19 起支持该 prop）：隔离撤销时按 DOM 属性直接移除，会与 React 的 DOM 失同步。弹窗内打开的浮层（`Popup`
、工具栏面板）会 portal 进所属弹窗的容器、与弹窗同层，层级因此保持正确。
## API

### MessageDialog

继承 `Dialog` 的 `open` / `size` / `escapable` / `onEscape` / `onReady` 等，另有：

| 属性                        | 描述                                        | 类型                    | 默认值       |
| ------------------------- | ----------------------------------------- | --------------------- | --------- |
| `children`                | 正文消息                                      | `ReactNode`           | —         |
| `title`                   | 标题                                        | `ReactNode`           | —         |
| `okLabel` / `cancelLabel` | 确定 / 取消按钮文本（`cancelLabel={null}` 隐藏取消）    | `ReactNode`           | 本地化缺省文案   |
| `foot`                    | 自定义底部动作区，整体替换默认“确定 / 取消”按钮（传入后不再自动聚焦“确定”） | `ReactNode`           | —         |
| `onOk` / `onCancel`       | 点确定（或 Ctrl/Cmd+Enter）/ 点取消时触发             | `() => void`          | —         |
| `size`                    | 弹窗大小                                      | `DialogProps["size"]` | `'small'` |

### Dialog

| 属性                 | 描述                        | 类型                                                     | 默认值        |
| ------------------ | ------------------------- | ------------------------------------------------------ | ---------- |
| `open`             | 是否打开（受控，必填）               | `boolean`                                              | —          |
| `size`             | 弹窗大小                      | `'small' \| 'medium' \| 'large' \| 'larger' \| 'full'` | `'medium'` |
| `children`         | 正文区内容                     | `ReactNode`                                            | —          |
| `head` / `foot`    | 头部 / 底部动作区                | `ReactNode`                                            | —          |
| `overlay`          | 覆盖整个弹窗的浮层内容（如错误面板）        | `ReactNode`                                            | —          |
| `contentClassName` | `children` 正文容器的附加类       | `string`                                               | —          |
| `escapable`        | 是否允许 ESC 触发关闭             | `boolean`                                              | `true`     |
| `onEscape`         | 按下 ESC 时触发（由调用方负责关闭）      | `() => void`                                           | —          |
| `onPrimaryAction`  | 按下 Ctrl / Cmd + Enter 时触发 | `() => void`                                           | —          |
| `onReady`          | 打开动画结束后触发（可执行聚焦等）         | `() => void`                                           | —          |
| `...rest`          | 原生 `div` 属性直传弹窗根元素        | `HTMLAttributes<HTMLDivElement>`                       | —          |

`ProcessDialog`（带多步流程、错误面板与自定义动作按钮）在 `Dialog` 之上扩展，见其组件页。

## 另见

- 不依赖 React 树的函数式调用：[命令式弹窗](https://ooui-react.pages.dev/components/imperative-dialogs/index.md)
- 弹窗为何只能受控、回调分工：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%BC%B9%E7%AA%97%E5%BF%85%E9%A1%BB%E5%8F%97%E6%8E%A7)
- 多步流程弹窗：[ProcessDialog](https://ooui-react.pages.dev/components/process-dialog/index.md)
- 全局配置（语言、方向、浮层容器）：[OOUIProvider](https://ooui-react.pages.dev/guide/configuration.md)



---
url: https://ooui-react.pages.dev/components/imperative-dialogs/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# 命令式弹窗

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/dialogs) | [原版 API](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.html "OO.ui.confirm / alert / prompt")

`confirm` / `alert` / `prompt` 三个独立函数，import 后从任意事件回调里 `await` 即可——无需 hook、无需挂载组件、不依赖 React 树。需要完整自定义内容的弹窗用 [Dialog](https://ooui-react.pages.dev/components/dialog/index.md) 组件。

## 基本用法

`confirm` 返回 `Promise<boolean>`（确定 `true`，取消 / ESC `false`）；`alert` 返回 `Promise<void>`；`prompt` 返回 `Promise<string | null>`（取消 / ESC 为 `null`）。

```tsx preview
import { useState } from "react";
import { Button, alert, confirm, prompt } from "ooui-react";

function App() {
  const [log, setLog] = useState("尚未操作");
  const note = (s: string) => setLog(s);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
        <Button onClick={() => alert("已保存你的更改。", { title: "完成" })}>
          alert
        </Button>
        <Button
          onClick={() =>
            confirm("确定要删除这条记录吗？", { title: "确认删除" }).then((ok) =>
              note(ok ? "已确认" : "已取消"),
            )
          }
        >
          confirm
        </Button>
        <Button
          onClick={() =>
            prompt("请输入你的名字：", { textInput: { defaultValue: "" } }).then((v) =>
              note(v === null ? "已取消" : `你好，${v}`),
            )
          }
        >
          prompt
        </Button>
      </div>
      <div>{log}</div>
    </div>
  );
}

export default App;
```

## 配置继承

弹窗若被包在 `OOUIProvider`
 子树内，会继承该 Provider 的语言、方向与浮层容器等配置；未包裹时按缺省值渲染。消息文案的覆盖方式见 [OOUIProvider · 命令式弹窗](https://ooui-react.pages.dev/guide/configuration.md#%E5%91%BD%E4%BB%A4%E5%BC%8F%E5%BC%B9%E7%AA%97)
。
## 运行时语义

- **Promise 在关闭动画播完后才兑现**（另加约 50ms 裕量），不是点击按钮的瞬间——`await confirm(...)` 后立即读 DOM 或跳转，会先等动画播完。
- 弹窗渲染在应用 React 树内，继承所在子树的全部 context；**嵌套 `OOUIProvider` 时由最外层的宿主统一渲染全部命令式弹窗**。
- 重复调用会**层叠出多个弹窗**、逐个可交互；原版三个 API 共用单窗口管理器，已有窗口打开时第二次调用被拒绝、返回的 Promise 永不兑现。{/* deviations: dev-imperative-no-queue */}
- `prompt` 的输入框内按 Enter 等同于点「确定」（IME 合成期的确认 Enter 除外，`textInput.onKeyDown` 可 `preventDefault` 否决）；弹窗就绪后自动聚焦输入框（`textInput.inputRef` 由内部占用、传入无效，`textInput.value` 只作初始值）。{/* deviations: dev-prompt-textinput-value */}

## API

| 函数                           | 返回                        | 说明                         |
| ---------------------------- | ------------------------- | -------------------------- |
| `confirm(message, options?)` | `Promise<boolean>`        | 确定 `true`，取消 / ESC `false` |
| `alert(message, options?)`   | `Promise<void>`           | 仅“确定”按钮，关闭之后就兑现            |
| `prompt(message, options?)`  | `Promise<string \| null>` | 确定兑现输入值，取消 / ESC 兑现 `null` |

`options`（`ConfirmAlertOptions` / `AlertOptions` / `PromptOptions`）：

| 属性            | 描述                              | 类型                    |
| ------------- | ------------------------------- | --------------------- |
| `title`       | 弹窗标题                            | `ReactNode`           |
| `okLabel`     | 确定按钮文本                          | `ReactNode`           |
| `cancelLabel` | 取消按钮文本（仅 `confirm` / `prompt`）  | `ReactNode`           |
| `size`        | 弹窗大小                            | `DialogProps["size"]` |
| `textInput`   | 输入框属性（仅 `prompt`），`value` 只作初始值 | `TextInputProps`      |

## 另见

- 弹窗组件本身（`open` 受控、动作区、多窗隔离）：[Dialog](https://ooui-react.pages.dev/components/dialog/index.md)
- 命令式弹窗如何继承 Provider 配置：[OOUIProvider](https://ooui-react.pages.dev/guide/configuration.md#%E5%91%BD%E4%BB%A4%E5%BC%8F%E5%BC%B9%E7%AA%97)
- 多步流程弹窗：[ProcessDialog](https://ooui-react.pages.dev/components/process-dialog/index.md)



---
url: https://ooui-react.pages.dev/components/process-dialog/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ProcessDialog 流程弹窗

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/dialogs/ProcessDialog) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ProcessDialog.html "OO.ui.ProcessDialog")

带动作区与错误面板的多步流程弹窗，在 [Dialog](https://ooui-react.pages.dev/components/dialog/index.md) 基类之上扩展。

## 基本用法

动作经 `actions` 数组声明：**每类特殊动作只取第一个可见的动作**——`flags` 含 `safe` 的第一个可见动作位于头部左侧（取消/关闭一类），含 `primary` 的第一个可见动作位于头部右侧（继续/保存一类），其余动作（含第二个及以后的 `safe` / `primary`）都排在底部动作区；`flags` 含 `close` / `back` 的动作渲染为纯图标按钮。

`onAction` 收到动作的 `action` 符号名；返回 `Promise` 期间头部显示 pending 条纹，Promise 结束后流程即结束。

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [savedAt, setSavedAt] = useState("");

  return (
    <>
      <Button onClick={() => setOpen(true)}>打开流程弹窗</Button>
      <ProcessDialog
        open={open}
        title="编辑条目"
        onEscape={() => setOpen(false)}
        actions={[
          { action: "cancel", label: "取消", flags: "safe" },
          { action: "save", label: "保存", flags: ["primary", "progressive"] },
        ]}
        onAction={(action) => {
          if (action === "cancel") {
            setOpen(false);
            return;
          }
          // 返回 Promise：执行期间头部显示 pending 条纹
          return new Promise<void>((resolve) => {
            setTimeout(() => {
              setSavedAt(new Date().toLocaleTimeString());
              setOpen(false);
              resolve();
            }, 1200);
          });
        }}
      >
        <div style={{ padding: 12 }}>正文区放你的表单或内容。{savedAt && `上次保存于 ${savedAt}`}</div>
      </ProcessDialog>
    </>
  );
}

export default App;
```

## 多步流程

其余动作排在底部动作区；`flags` 含 `close` / `back` 的动作渲染为纯图标按钮：

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [log, setLog] = useState<string[]>([]);

  return (
    <>
      <Button onClick={() => setOpen(true)}>打开多动作弹窗</Button>
      <ProcessDialog
        open={open}
        title="编辑条目"
        onEscape={() => setOpen(false)}
        actions={[
          { action: "cancel", label: "取消", flags: "safe" },
          { action: "save", label: "保存", flags: ["primary", "progressive"] },
          { action: "preview", label: "预览" },
          { action: "discard", label: "放弃更改", flags: "destructive" },
          { action: "back", label: "返回上一步", flags: "back" },
        ]}
        onAction={(action) => {
          if (action === "cancel" || action === "save") {
            setOpen(false);
            return;
          }
          setLog((prev) => [`点击了 ${action}`, ...prev].slice(0, 3));
        }}
      >
        <div style={{ padding: 12 }}>safe / primary 在头部，其余动作与图标按钮在底部。</div>
      </ProcessDialog>
      <div>最近点击：{log.join("、") || "（无）"}</div>
    </>
  );
}

export default App;
```

传 `mode` 后，只有声明了含当前模式的 `modes` 的动作可见（未声明 `modes` 的动作同样隐藏）；不传 `mode` 则全部动作可见。配合状态切换即得向导。

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [mode, setMode] = useState("edit");

  return (
    <>
      <Button onClick={() => setOpen(true)}>打开向导弹窗</Button>
      <ProcessDialog
        open={open}
        mode={mode}
        title={mode === "edit" ? "编辑" : "预览"}
        onEscape={() => setOpen(false)}
        actions={[
          { action: "back", label: "返回", flags: "back", modes: ["preview"] },
          { action: "cancel", label: "取消", flags: "safe", modes: ["edit"] },
          {
            action: "next",
            label: "下一步",
            flags: ["primary", "progressive"],
            modes: ["edit"],
          },
          { action: "save", label: "保存", flags: ["primary", "progressive"], modes: ["preview"] },
        ]}
        onAction={(action) => {
          if (action === "next") {
            setMode("preview");
          } else if (action === "back") {
            setMode("edit");
          } else if (action === "cancel") {
            setOpen(false);
          }
        }}
      >
        <div style={{ padding: 12 }}>
          {mode === "edit" ? "第 1 步：填写内容" : "第 2 步：确认后保存"}
        </div>
      </ProcessDialog>
    </>
  );
}

export default App;
```

## 错误面板

`onAction` 返回的 Promise 以错误对象（或其数组）reject 时，弹出覆盖整个弹窗的错误面板（reject 其他值——如普通 `Error` 或字符串——按仅含 `message` 的可恢复错误处理）：

- 错误对象为 `{ message, recoverable?, warning? }`（类型 `ProcessDialogErrorProps`）；`recoverable` 缺省 `true`，面板显示**重试**按钮（重跑最近一次执行的动作）。
- `warning: true` 的错误渲染为警告消息，按钮显示 Continue。
- `recoverable: false` 时触发的动作被禁用（持续到弹窗关闭），面板只能经 Dismiss 退出。
- 每次动作执行前错误面板自动收起。

```tsx preview
import { useState } from "react";
import { Button, ProcessDialog } from "ooui-react";

function App() {
  const [open, setOpen] = useState(false);
  const [failNext, setFailNext] = useState(true);

  return (
    <>
      <Button
        onClick={() => {
          setFailNext(true);
          setOpen(true);
        }}
      >
        打开（首次保存会失败）
      </Button>
      <ProcessDialog
        open={open}
        title="上传附件"
        onEscape={() => setOpen(false)}
        actions={[
          { action: "cancel", label: "取消", flags: "safe" },
          { action: "save", label: "保存", flags: ["primary", "progressive"] },
        ]}
        onAction={(action) => {
          if (action === "cancel") {
            setOpen(false);
            return;
          }
          return new Promise<void>((resolve, reject) => {
            setTimeout(() => {
              if (failNext) {
                setFailNext(false);
                reject([{ message: "保存失败：网络超时，请重试", recoverable: true }]);
              } else {
                setOpen(false);
                resolve();
              }
            }, 800);
          });
        }}
      >
        <div style={{ padding: 12 }}>点「保存」触发一次失败，面板里重试一次即成功。</div>
      </ProcessDialog>
    </>
  );
}

export default App;
```

## 键盘

- `Ctrl` / `Cmd` + `Enter` 执行 primary 动作。
- `ESC` 触发 `onEscape`，关闭由调用方处理。

## API

继承 [Dialog](https://ooui-react.pages.dev/components/dialog/index.md) 的 `open` / `size` / `escapable` / `onReady` 等；`title` / `head` / `foot` / `bodyFitFoot` 由本组件接管，`onPrimaryAction` 被接管为「执行 primary 动作」。

| 属性          | 描述                                                         | 类型                                          | 默认值    |
| ----------- | ---------------------------------------------------------- | ------------------------------------------- | ------ |
| `open`      | 是否打开（受控，必填）                                                | `boolean`                                   | —      |
| `title`     | 弹窗标题（自动关联 `aria-labelledby`）                               | `ReactNode`                                 | —      |
| `actions`   | 动作集                                                        | `ProcessDialogActionProps[]`                | `[]`   |
| `mode`      | 当前模式；置位后仅声明了含该模式 `modes` 的动作可见                             | `string`                                    | —      |
| `onAction`  | 动作执行回调；返回 `Promise` 期间头部显示 pending 条纹，以错误对象 reject 时展示错误面板 | `(action: string) => Promise<void> \| void` | —      |
| `onEscape`  | 按 `ESC` 时触发（由调用方负责关闭）                                      | `() => void`                                | —      |
| `escapable` | 是否允许 `ESC` 触发关闭                                            | `boolean`                                   | `true` |
| `children`  | 正文区内容                                                      | `ReactNode`                                 | —      |
| `...rest`   | 其余 `Dialog` 属性（`size`、`onReady` 等）与原生 `div` 属性             | —                                           | —      |

`actions` 数组项（`ProcessDialogActionProps`）：

| 属性         | 描述                                      | 类型                           | 默认值     |
| ---------- | --------------------------------------- | ---------------------------- | ------- |
| `action`   | 动作符号名（`onAction` 的入参）                   | `string`                     | —       |
| `label`    | 按钮文本（`flags` 含 `close` / `back` 时被图标替代） | `ReactNode`                  | —       |
| `flags`    | 按钮标志；`safe` / `primary` 同时决定动作在头部的特殊位置  | `ButtonFlag \| ButtonFlag[]` | —       |
| `modes`    | 可见模式集；声明后仅 `mode` 命中时可见                 | `string[]`                   | —       |
| `disabled` | 是否禁用                                    | `boolean`                    | `false` |
| `pending`  | 该动作按钮是否处于 pending 态（叠加条纹动画）             | `boolean`                    | `false` |
| `title`    | 按钮 tooltip                              | `string`                     | —       |

错误对象（`ProcessDialogErrorProps`）：

| 属性            | 描述                                    | 类型          | 默认值     |
| ------------- | ------------------------------------- | ----------- | ------- |
| `message`     | 错误信息                                  | `ReactNode` | —       |
| `recoverable` | 是否可恢复；`false` 时禁用触发动作，面板仅能 Dismiss 退出 | `boolean`   | `true`  |
| `warning`     | 警告错误（渲染为警告消息，按钮显示 Continue）           | `boolean`   | `false` |

## 与原版的差异

- **动作编排归并为一个 `onAction` 异步回调**：原版经 `getActionProcess` 串联 `OO.ui.Process` 多步链；本工程在回调内串联流程，步骤内部抛错（reject）即结束并进入错误面板。{/* deviations: dev-onaction */}
- **`ActionWidget` / `ActionSet` / `OO.ui.Error` 不作为独立类提供**：能力归并进 `actions` 数组（`action` / `flags` / `modes` / `pending` 等字段）与错误对象，由错误面板渲染。{/* deviations: dev-actionset-inline */}
- **「特殊动作」标志固定为 `safe` / `primary`**：原版允许子类扩展 `ActionSet.static.specialFlags`，本工程没有类继承，动作只要经 `flags` 声明为 `safe` 或 `primary` 即可出现在头部。{/* deviations: dev-special-flags */}
- **传 `mode` 即从首帧按 `modes` 过滤**（原版首次 `setMode` 前混显全部动作）。{/* deviations: dev-processdialog-mode */}

## 另见

- 弹窗基类与消息弹窗：[Dialog](https://ooui-react.pages.dev/components/dialog/index.md)
- 错误面板中的消息渲染：[Message](https://ooui-react.pages.dev/components/message/index.md)
- 弹窗为何只能受控：[受控与非受控](https://ooui-react.pages.dev/guide/controlled.md#%E5%BC%B9%E7%AA%97%E5%BF%85%E9%A1%BB%E5%8F%97%E6%8E%A7)



---
url: https://ooui-react.pages.dev/components/toolbar/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# Toolbar 工具栏

> [源代码](https://github.com/BearBin1215/ooui-react/tree/main/src/toolbars) | [原版组件](https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Toolbar.html "OO.ui.Toolbar")

工具栏：一条横栏容器，内部排列若干工具组，工具由工具组承载：

- `BarToolGroup`：工具以图标按钮横向平铺（最常用）。
- `ListToolGroup` / `MenuToolGroup`：工具收进下拉面板，点 handle 展开。
- `LabelToolGroup`：工具栏内的一段静态标签，不可交互、可带图标与指示器。

## 基本用法

```tsx preview
import { useState } from "react";
import { Toolbar, BarToolGroup } from "ooui-react";

function App() {
  const [marks, setMarks] = useState<string[]>([]);
  const toggle = (name: string) =>
    setMarks((prev) =>
      prev.includes(name) ? prev.filter((x) => x !== name) : [...prev, name],
    );

  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          {
            name: "bold",
            icon: "bold",
            label: "加粗",
            title: "加粗",
            active: marks.includes("bold"),
            onSelect: () => toggle("bold"),
          },
          {
            name: "italic",
            icon: "italic",
            label: "斜体",
            title: "斜体",
            active: marks.includes("italic"),
            onSelect: () => toggle("italic"),
          },
          {
            name: "link",
            icon: "link",
            label: "插入链接",
            title: "插入链接",
            onSelect: () => setMarks((p) => [...p, "link"]),
          },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## 工具组分区与动作区

工具组按自身 `align` 排到左侧（`before`，缺省）或右侧（`after`）：

```tsx preview
import { Toolbar, BarToolGroup } from "ooui-react";

function App() {
  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          { name: "undo", icon: "undo", label: "撤销", onSelect: () => {} },
          { name: "redo", icon: "redo", label: "重做", onSelect: () => {} },
        ]}
      />
      <BarToolGroup
        align="after"
        tools={[
          { name: "settings", icon: "settings", label: "设置", onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

`actions` 渲染在最右侧的独立动作区，接受任意 ReactNode（原生按钮、开关等非工具内容）。原生按钮的高度基线与工具位不同（无框按钮 32px、工具位 42px，顶部对齐），原版也按同样的结构渲染，作为独立操作件使用即可：

```tsx preview
import { Toolbar, BarToolGroup, Button } from "ooui-react";

function App() {
  return (
    <Toolbar
      actions={
        <Button icon="check" flags={["primary", "progressive"]}>
          完成编辑
        </Button>
      }
    >
      <BarToolGroup
        tools={[
          { name: "undo", icon: "undo", label: "撤销", onSelect: () => {} },
          { name: "redo", icon: "redo", label: "重做", onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## Bar 组的图标文本与快捷键

Bar 组的工具位缺省只显示图标，`displayBothIconAndLabel` 让单个工具显示文本（有图标时为图标 + 文本；无图标时为纯文本按钮——不开则无图标工具会呈现为原版带图标槽的原始形态）；`accelerator` 是快捷键提示文案，Bar 组把它拼进链接的 tooltip（List / Menu 组则渲染为面板内可见的 accel 槽位）。

```tsx preview
import { useState } from "react";
import { BarToolGroup, Toolbar } from "ooui-react";

function App() {
  const [marks, setMarks] = useState<string[]>([]);
  const toggle = (name: string) =>
    setMarks((prev) =>
      prev.includes(name) ? prev.filter((x) => x !== name) : [...prev, name],
    );

  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          {
            name: "bold",
            icon: "bold",
            label: "加粗",
            title: "加粗",
            accelerator: "Ctrl+B",
            displayBothIconAndLabel: true,
            active: marks.includes("bold"),
            onSelect: () => toggle("bold"),
          },
          {
            name: "italic",
            icon: "italic",
            label: "斜体",
            title: "斜体",
            accelerator: "Ctrl+I",
            onSelect: () => toggle("italic"),
          },
          { name: "clear", label: "清除格式", title: "清除格式", displayBothIconAndLabel: true, onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

示例里的工具位依次展示了这几种形态：`bold` 图标 + 文本、`italic` 仅图标（缺省）、`clear` 无图标仅文本（同样经 `displayBothIconAndLabel`）。悬停前两个工具可见 tooltip 里的快捷键提示。

## 弹出工具

工具带 `popup` 配置时成为“弹出工具”：点击工具会开合浮层，浮层展开期间工具呈激活态。浮层内容由 `popup.popupContent` 给出，显隐可用 `open` / `defaultOpen` / `onOpenChange` 受控。`onSelect` 仍在每次选中时触发（与开合独立，不会因配了 `popup` 而失效）；浮层方位固定在工具下方（bottom 工具栏为上方），`autoFlip` 缺省关闭、可显式开启；`container` / `autoClose` / `position` 由工具自身接管，不可覆盖。

:::warning 与原版的差异
弹出工具不要放进 `ListToolGroup`
 / `MenuToolGroup`
 组内：选中工具会先收起组面板，浮层锚点随之失效——原版表现为浮层不显示，本工程浮层仍会渲染但错位到视口左上角。弹出工具请放 Bar 组。
:::
```tsx preview
import { Toolbar, BarToolGroup } from "ooui-react";

function App() {
  return (
    <Toolbar>
      <BarToolGroup
        tools={[
          {
            name: "color",
            icon: "palette",
            label: "颜色",
            popup: {
              popupContent: (
                <div style={{ padding: 12 }}>在这里放颜色选择面板</div>
              ),
            },
          },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## List 与 Menu 工具组

两者都由一个 handle 加下拉面板构成（handle 的图标/标签/指示器可配，指示器缺省随 `position` 翻转：bottom 时朝上），面板顶部可放 `header` 说明文字。

**ListToolGroup** 以标签文本纵向列表承载工具，支持折叠体系：`allowCollapse` 名单内的工具默认折叠（展开面板后才可见），面板尾部自动出现 More / Fewer 切换项（选中它不收起面板，文案与图标随状态切换）；`forceExpand` 反向声明——列出的工具始终可见、其余均可折叠。名单与实际 `tools` 取交集，无效名不产生切换项。展开态经 `expanded`（受控）/ `defaultExpanded`（非受控初值，缺省折叠）管理。

**MenuToolGroup**
 以标签横向列表承载工具，handle 的标签由**激活工具**
（`active: true`
）的可见文本用「, 」连接而成，无激活工具时回退 `label`
——适合段落格式、对齐方式一类「显示当前选择」的互斥菜单。
两个组共享同一套约定：面板开合统一通过 `open`
 / `defaultOpen`
 / `onOpenChange`
 控制（handle 切换、选中收起、点外部、Escape 均回调）；`onToolSelect`
 在任意工具被选中时收到该工具定义，可统一分发；选中工具后面板自动收起。组级 `disabled`
 禁用全部工具；**全部工具禁用时组自动禁用**
、`tools`
 为空的组整体隐藏——按权限动态清空 `tools`
 的场景无需额外处理。Escape 在捕获阶段关闭面板，工具栏嵌在 Dialog 里不会误关弹窗。
```tsx preview
import { useState } from "react";
import { ListToolGroup, Toolbar } from "ooui-react";

function App() {
  const [active, setActive] = useState("p");

  return (
    <Toolbar>
      <ListToolGroup
        label="段落"
        allowCollapse={["pre", "blockquote"]}
        tools={[
          { name: "p", label: "正文", active: active === "p", onSelect: () => setActive("p") },
          { name: "h", label: "标题", active: active === "h", onSelect: () => setActive("h") },
          { name: "pre", label: "预格式", onSelect: () => {} },
          { name: "blockquote", label: "引用", onSelect: () => {} },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

下例把三块拼进同一条工具栏：**Menu 组**（handle 文本随激活工具合成——选中不同对齐方式后 handle 跟随变化，无激活工具时回退到 `label`）、**Label 组**（静态文字段，用作视觉分隔）与**内嵌工具组**（Bar 组的工具位经 `group` 渲染整个 List 组，做「嵌套下拉」）。

```tsx preview
import { useState } from "react";
import {
  BarToolGroup,
  LabelToolGroup,
  ListToolGroup,
  MenuToolGroup,
  Toolbar,
} from "ooui-react";

function App() {
  const [align, setAlign] = useState("left");

  return (
    <Toolbar>
      <MenuToolGroup
        label="对齐"
        tools={[
          {
            name: "left",
            icon: "alignLeft",
            label: "左对齐",
            active: align === "left",
            onSelect: () => setAlign("left"),
          },
          {
            name: "center",
            icon: "alignCenter",
            label: "居中",
            active: align === "center",
            onSelect: () => setAlign("center"),
          },
          {
            name: "right",
            icon: "alignRight",
            label: "右对齐",
            active: align === "right",
            onSelect: () => setAlign("right"),
          },
        ]}
      />
      <LabelToolGroup icon="article" label="插入" />
      <BarToolGroup
        tools={[
          {
            name: "insert",
            group: (
              <ListToolGroup
                label="插入"
                icon="add"
                tools={[
                  { name: "link", icon: "link", label: "链接", onSelect: () => {} },
                  { name: "image", icon: "image", label: "图片", onSelect: () => {} },
                  {
                    name: "gallery",
                    icon: "imageGallery",
                    label: "画廊",
                    onSelect: () => {},
                  },
                ]}
              />
            ),
          },
        ]}
      />
    </Toolbar>
  );
}

export default App;
```

## 窄栏与位置

工具栏宽度不足以平铺全部内容时自动进入**窄栏**：主题 CSS 收紧整体间距；工具与 handle 可按 `narrowConfig` 定制窄栏形态（收起标签、替换图标或文本，退出窄栏还原）。`position` 取 `top`（缺省）或 `bottom`，决定弹出面板朝下还是朝上展开。

下例用定宽容器把工具栏压进窄栏：`bold` 与 List 组的 handle 各经 `narrowConfig` 在窄栏收起文本（退出窄栏还原）；工具栏同时置于底部（`position="bottom"`），打开 List 面板可见它朝上展开、handle 的指示器朝上。

```tsx preview
import { useState } from "react";
import { BarToolGroup, ListToolGroup, Toolbar } from "ooui-react";

function App() {
  const [active, setActive] = useState("p");

  return (
    <div style={{ maxWidth: 230 }}>
      <Toolbar position="bottom">
        <BarToolGroup
          tools={[
            {
              name: "bold",
              icon: "bold",
              label: "加粗",
              title: "加粗",
              displayBothIconAndLabel: true,
              narrowConfig: { displayBothIconAndLabel: false },
            },
            { name: "italic", icon: "italic", label: "斜体", title: "斜体" },
            { name: "link", icon: "link", label: "链接", title: "链接" },
            { name: "clear", icon: "clear", label: "清除", title: "清除" },
          ]}
        />
        <ListToolGroup
          align="after"
          label="更多"
          icon="menu"
          narrowConfig={{ invisibleLabel: true }}
          tools={[
            {
              name: "p",
              label: "正文",
              active: active === "p",
              onSelect: () => setActive("p"),
            },
            {
              name: "h",
              label: "标题",
              active: active === "h",
              onSelect: () => setActive("h"),
            },
          ]}
        />
      </Toolbar>
    </div>
  );
}

export default App;
```

## API

| 属性         | 描述                                                    | 类型                               | 默认值     |
| ---------- | ----------------------------------------------------- | -------------------------------- | ------- |
| `children` | 工具组（`BarToolGroup`、`ListToolGroup`、`MenuToolGroup` 等） | `ReactNode`                      | —       |
| `position` | 工具栏位置，影响弹出面板展开方向与类名                                   | `'top' \| 'bottom'`              | `'top'` |
| `actions`  | 右侧独立动作区内容                                             | `ReactNode`                      | —       |
| `...rest`  | 原生 `div` 属性（`className`、`id`、`data-*` 等）直传根元素         | `HTMLAttributes<HTMLDivElement>` | —       |

工具项（`tools` 数组元素）的常用字段：

- `name`（符号名，必填）：生成 `oo-ui-tool-name-{name}` 类（路径形式 `'a/b/c'` 取前两段），可作样式与测试钩子。
- `label`（可见文本）与 `icon`：Bar 组缺省仅显示图标；文本经 `displayBothIconAndLabel: true` 显示（有图标时为图标 + 文本，无图标时为纯文本按钮——不开则无图标工具会呈现为原版带图标槽的原始形态）；List / Menu 组始终显示标签。`title` 始终是 tooltip（Bar 组把 `title` 与 `accelerator` 拼进链接 title；List / Menu 组只渲染 accelerator 槽位、不拼 tooltip）。{/* deviations: dev-tool-accelerator */}
- `active`（受控激活态）、`onSelect`（点击或键盘 Enter / 空格触发）、`disabled`。
- `narrowConfig`：窄栏时以其**已定义**字段替换该工具的图标 / 标签形态，退出窄栏还原。
- `popup`：弹出工具（见上节）。
- `group`：内嵌工具组——工具位渲染为整个工具组而非工具链接（做「嵌套下拉」），handle 与选中态都由内嵌组承担，`title` / `icon` / `active` / `onSelect` 对本工具不生效，只有 `disabled` 同步为禁用态；与 `popup` 同给时 `group` 优先。{/* deviations: dev-toolgroup-tool-element */}

完整说明见各工具组与 `ToolProps` 类型。

## 与原版的差异

- **工具不再经 `ToolFactory` 注册**：工具直接以声明式 `tools` 数组交给工具组，激活态由调用方持有。{/* deviations: dev-tool-factory */}
- **工具栏与工具组无事件面**：原版监听 `Toolbar.active` 事件的等价物是按 `active` 声明重渲染 `tools` 数组；浮层与面板的开合同样通过受控 props 与回调控制。{/* deviations: dev-toolbar-events */}
- **弹出工具的 `onSelect` 仍会触发**：原版它被浮层开合占用、调用方收不到选中通知；本工程选中回调与开合独立，显隐变化另经 `popup.onOpenChange` 通知。{/* deviations: dev-popup-tool-onselect */}
- **弹出工具的 `autoFlip` 缺省关闭、可显式开启**。{/* deviations: dev-popup-tool-autoflip */}
- **工具的可见文本与 tooltip 从单一的 `title` 拆为 `label` + `title`**：`label` 是可见文本、`title` 始终是 tooltip；迁移时原 `narrowConfig.title` 的值应改传 `label`。{/* deviations: dev-tool-label-title */}
- **窄栏下 handle 的 tooltip 始终按生效的 `label` 兜底**。{/* deviations: dev-popuptoolgroup-title */}
- **面板铺满容器宽时纵向仍按可视区限制高度并内部滚动**（工具始终可达）。{/* deviations: dev-panel-maxheight */}
- **工具组增减后窄栏判定基准自动重测**，动态增减工具组的场景窄栏判定保持正确。{/* deviations: dev-narrow-threshold-reset */}
- **工具栏置于底部（`position="bottom"`）时 More / Fewer 的箭头方向与原版相反**，功能不受影响。{/* deviations: dev-listtoolgroup-icons */}

## 另见

- 平铺图标按钮的工具组：`BarToolGroup`
- 收进下拉面板的工具组：`ListToolGroup`、`MenuToolGroup`
- 静态标签工具组：`LabelToolGroup`
- 通用透传与 `ref` 规则：[通用属性](https://ooui-react.pages.dev/guide/basics.md)



---
url: https://ooui-react.pages.dev/index.md
---

> For AI agents: the complete documentation index is available at https://ooui-react.pages.dev/llms.txt, the full documentation bundle is available at https://ooui-react.pages.dev/llms-full.txt.

# ooui-react

> OOUI 的 React 实现

[快速开始](/guide/usage) | [组件](/components/)

## Features

- /feature-icons/code-xml.svg **结构匹配**: 输出的 DOM 结构、类名、属性与原版一致，样式由调用方从 OOUI 引入，适配 MediaWiki 站点。
- /feature-icons/keyboard.svg **行为一致**: 键盘、焦点、a11y 与边界值逐项对照原版，交互语义一致。
- /feature-icons/react.svg **声明式 API**: 原版的命令式 setter 与事件改写为 value、onChange 等受控 props，贴合 React 使用习惯。
- /feature-icons/typescript.svg **类型支持**: 完全使用 TypeScript 开发，类型定义完整。
- /feature-icons/preact.svg **兼容 Preact**: 可运行在 Preact 兼容层下，有效减小产物体积。
- /feature-icons/package.svg **Tree Shaking**: 支持按需引入。
## 快速体验

```tsx file="<root>/demos/zh/advanced-search.tsx"
import { useState } from "react";
import { Button, Dropdown, TextInput } from "ooui-react";
import "./advanced-search.css";

const SEARCH_CODES = {
  none: "无",
  intitle: "标题包含",
  incategory: "属于分类",
  hastemplate: "嵌入模板",
  linksto: "链接到",
  insource: "源码包含",
};

const OPTIONS = Object.entries(SEARCH_CODES).map(([value, label]) => ({
  value,
  children: label,
}));

function AdvancedSearchDemo() {
  const [rows, setRows] = useState([{ code: "none", value: "" }]);
  const addRow = () => setRows((prev) => [...prev, { code: "none", value: "" }]);
  const setRow = (index: number, patch: { code?: string; value?: string }) =>
    setRows((prev) => prev.map((row, i) => (i === index ? { ...row, ...patch } : row)));

  return (
    <div className="advsearch">
      <div className="advsearch-header">高级搜索</div>
      {rows.map(({ code, value }, index) => {
        const pending = index === rows.length - 1;
        return (
          <div
            key={index}
            className={`advsearch-line${pending ? " advsearch-line-pending" : ""}`}
          >
            <Dropdown
              className="advsearch-code"
              value={code}
              onChange={(next) => setRow(index, { code: String(next) })}
              onFocus={pending ? addRow : undefined}
              options={OPTIONS}
            />
            <TextInput
              className="advsearch-value"
              value={value}
              onChange={(next) => setRow(index, { value: next })}
              onFocus={pending ? addRow : undefined}
            />
            <Button
              className="advsearch-remove"
              icon="subtract"
              tabIndex={-1}
              disabled={pending}
              onClick={() => setRows((prev) => prev.filter((_, i) => i !== index))}
            />
          </div>
        );
      })}
    </div>
  );
}

export default AdvancedSearchDemo;

```
```css file="<root>/demos/zh/advanced-search.css"
.advsearch {
  max-width: 50em;
  box-sizing: border-box;
  padding: 0.5em 0.75em;
  border: 1px solid #c8ccd1;
  background-color: #f8f9fa;
}
.advsearch-header {
  font-size: 1.2em;
  font-weight: 600;
}
.advsearch .advsearch-line {
  display: flex;
  gap: 8px;
  margin-top: 0.4em;
}
.advsearch .advsearch-line-pending {
  opacity: 0.4;
  transition: opacity ease-out 0.3s;
}
.advsearch .advsearch-line-pending:hover {
  opacity: 1;
}
.advsearch .advsearch-line-pending .advsearch-remove {
  opacity: 0;
}
.advsearch .advsearch-code {
  flex: 0 0 10em;
}
.advsearch .advsearch-value {
  flex: 1 1 40em;
  max-width: none;
}

```

聚焦末尾的空行会自动追加一行，行尾的减号移除所在行。

## 安装


```sh [npm]
npm install ooui-react
```

```sh [yarn]
yarn add ooui-react
```

```sh [pnpm]
pnpm add ooui-react
```

```sh [bun]
bun add ooui-react
```

```sh [deno]
deno add npm:ooui-react
```

需 React 版本 ≥ 18，暂不支持 SSR。样式引入、在 MediaWiki 站点接入与 Preact 兼容等完整步骤见[使用方式](https://ooui-react.pages.dev/guide/usage.md)。

## 为什么会有这个组件库？

2023 年，我在编写[自己的萌娘百科小工具](https://github.com/BearBin1215/MoegirlPedia)时，有些较复杂的场景仅靠 JQuery 很难把状态管理清楚，就想引入一个现代的框架。当时情况是这样：

- MediaWiki 版本为 1.31，没有自带 Vue、Codex。
- 如果自行打包完整的 Vue，构建产物从 60KB 起步，稍微多写一点就会导致产物太大、提交到站内超时。
- 成熟的组件库多数会引入样式表，产物同样很大。
- 我美术水平太差不会设计样式~~（重要！）~~。

因此，我选择了 [Preact](https://preactjs.com/) 结合自建 OOUI 组件库的方案，框架体积小、无样式表，只需要渲染 DOM。

随着 AI 编程的兴起，本工程得以较为系统化地开发成一个完整的组件库。虽然如今萌百已经升级了 MediaWiki 版本并且支持了 Vue + Codex 的方案，但我觉得这个组件库应当还是有其意义的。