# ooui-react

> OOUI 的 React 实现

## 指南

- [使用方式](/ooui-react/guide/usage.md): ooui-react 的安装命令、运行环境与样式引入，以及在 MediaWiki 站点、Preact 兼容层下的使用方式。
- [OOUI 对照](/ooui-react/guide/ooui.md): 面向熟悉 OOUI 的使用者：心智模型映射、按原版类名找组件、能力舍弃清单、行为差异速查。
- [通用属性](/ooui-react/guide/basics.md): ooui-react 所有组件共有的属性规则：未声明属性透传到根元素、内部元素走 inputProps 一类通道，以及 disabled、flags、title、accessKey、tabIndex 的通用语义。
- [受控与非受控](/ooui-react/guide/controlled.md): ooui-react 的值契约：value、open、checked 三条通道，受控判定与回调签名，以及弹窗为受控 only 的约定。
- [选择与选项](/ooui-react/guide/options.md): Select 系组件共用的选项数据约定：value 与分组标题、children/label 文本、标签多选的 labelText 与 data、禁用下发、图标标志与键盘焦点模型。
- [全局配置](/ooui-react/guide/configuration.md): OOUIProvider 的全局配置：消息与国际化、浮层容器、移动端形态、文本方向、视口留白、快捷键文案，以及命令式弹窗的双通道。

## 组件

- [组件总览](/ooui-react/components/index.md): ooui-react 的全部导出组件按控件、布局、弹窗、工具栏四族列出，附一句话用途；组件不自带样式，DOM 与原版 OOUI 一致。
- [Button 按钮](/ooui-react/components/button/index.md): Button 组件的属性说明：标签、图标、指示器、标志与边框形态、链接用法，以及点击、键盘与按压行为。
- [ToggleButton 切换按钮](/ooui-react/components/toggle-button/index.md): ToggleButton 组件的属性说明：在 Button 形态上叠加开/关状态，checked/defaultChecked/onChange 通道，aria-pressed 随状态输出，不支持链接形态。
- [ToggleSwitch 开关](/ooui-react/components/toggle-switch/index.md): ToggleSwitch 组件的属性说明：拨动开关（role=switch），checked/defaultChecked/onChange 通道，Space/Enter 切换，无自带标签，配 FieldLayout 使用。
- [ButtonGroup 按钮组](/ooui-react/components/button-group/index.md): ButtonGroup 组件的属性说明：把若干按钮并排成一组，视觉上连为一体，组级 disabled 一并下发到组内按钮。
- [Popup 浮层](/ooui-react/components/popup/index.md): Popup 组件的属性说明：锚定到容器并自动定位/翻转/裁剪的浮动面板，受控 open、点外部与 Escape 自动关闭、头部与底部区域；适合注解、Tooltip 等按需展示，按钮触发可用 PopupButton。
- [PopupButton 浮层按钮](/ooui-react/components/popup-button/index.md): PopupButton 组件的属性说明：点击按钮开合一个锚定到自身的浮层（Popup 的触发式封装），children 是按钮标签、popupContent 是浮层内容，内建点外部自动关闭。
- [Icon 图标](/ooui-react/components/icon/index.md): Icon 组件的属性说明与主题图标集索引：按原版分组列出全部可用图标，点击可复制图标名。
- [Indicator 指示器](/ooui-react/components/indicator/index.md): Indicator 组件的属性说明：up、down、clear、required 四种指示器，多为其它组件内嵌使用。
- [Label 标签](/ooui-react/components/label/index.md): Label 组件的属性说明：独立摆放的表单标签、htmlFor 关联原生控件、视觉隐藏与禁用态。
- [ProgressBar 进度条](/ooui-react/components/progress-bar/index.md): ProgressBar 组件的属性说明：0–100 的进度值、progress=false 的不定进度条纹形态，role=progressbar 的语义与范围钳制。
- [Message 消息](/ooui-react/components/message/index.md): Message 组件的属性说明：notice/error/warning/success 四种类型、内联形态、关闭按钮与 onClose 契约（组件不自隐，须在回调中卸载/隐藏）。
- [TextInput 文本输入](/ooui-react/components/text-input/index.md): TextInput 组件的属性说明：受控/非受控、类型白名单、标签与图标指示器、软校验，以及属性落点与 inputProps/inputRef 通道。
- [MultilineTextInput 多行输入](/ooui-react/components/multiline-text-input/index.md): MultilineTextInput 组件的属性说明：rows/maxRows 行数、autosize 自动高度、滚动条让位，以及与 TextInput 同源的标签、图标与软校验能力。
- [NumberInput 数字输入](/ooui-react/components/number-input/index.md): NumberInput 组件的属性说明：number | '' 值形态、按钮/键盘/滚轮步进、min/max/step 约束与软校验，以及与 TextInput 同源的标签、图标能力。
- [SearchInput 搜索输入](/ooui-react/components/search-input/index.md): SearchInput 组件的属性说明：搜索用单行输入框，缺省 search 图标、值非空且可编辑时出现可点击的清除指示器，其余能力与 TextInput 同源。
- [SearchWidget 搜索组件](/ooui-react/components/search-widget/index.md): SearchWidget 组件的属性说明：搜索框 + 常驻结果列表的组合；本组件不实现检索，查询变化经 onQueryChange 回调、由调用方填入 results，↑↓ 在结果间移动高亮、Enter 选定。
- [ComboBoxInput 组合框](/ooui-react/components/combo-box-input/index.md): ComboBoxInput 组件的属性说明：可自由输入的文本框 + 下拉候选菜单，选定写入文本但不限定取值；输入能力与 TextInput 同源，含键盘与选定语义、软校验与标签。
- [CheckboxInput 复选框](/ooui-react/components/checkbox-input/index.md): CheckboxInput 组件的属性说明：勾选态走 checked/defaultChecked/onChange，value 是表单提交值，含半选 indeterminate 与 inputId/inputRef 通道。
- [RadioInput 单选框](/ooui-react/components/radio-input/index.md): RadioInput 组件的属性说明：勾选态走 checked/defaultChecked/onChange，value 是表单提交值，同 name 的单选框天然互斥；无 indeterminate。
- [SelectFileInputWidget 文件选择](/ooui-react/components/select-file-input-widget/index.md): SelectFileInputWidget 组件的属性说明：文件集走 value/defaultValue/onChange 数组通道，accept 类型过滤，showDropTarget 拖放区形态（含缩略图）与 buttonOnly 仅按钮形态。
- [Select 选择列表](/ooui-react/components/select/index.md): Select 组件的属性说明：作为下拉/菜单内层的选择列表（listbox），可选中的选项集、onChange/onChoose 分工、命令菜单形态 clearOnChoose，以及键盘导航开关。
- [Dropdown 下拉选择](/ooui-react/components/dropdown/index.md): Dropdown 组件的属性说明：options 选项集、受控/非受控选中值、标签占位与图标，以及展开、键盘导航与前缀跳转行为。
- [OutlineSelect 大纲选择](/ooui-react/components/outline-select/index.md): OutlineSelect 组件的属性说明：带层级缩进的选择列表（Select 的大纲形态），options 每项以 level 表达缩进层级，整组可聚焦、方向键移动高亮。
- [TabSelect 页签选择](/ooui-react/components/tab-select/index.md): TabSelect 组件的属性说明：页签式单选（role=tablist），←→在页签间环绕直选，选中项滚动进视野，framed 控制带框/无框形态。
- [ButtonSelect 按钮选择](/ooui-react/components/button-select/index.md): ButtonSelect 组件的属性说明：一排互斥的按钮式选项（选中项即按钮激活态），方向键环绕直选，value/defaultValue/onChange 通道与带图标的 options。
- [ButtonMenuSelectWidget 命令菜单](/ooui-react/components/button-menu-select/index.md): ButtonMenuSelectWidget 组件的属性说明：由按钮触发的命令菜单（浮层菜单浮于按钮下方），每次选定回调 onChoose 并收起，clearOnSelect 决定是否保留选中态。
- [CheckboxMultiselect 复选组](/ooui-react/components/checkbox-multiselect/index.md): CheckboxMultiselect 组件的属性说明：复选组的 value/defaultValue/onChange 数组通道、Shift+点击范围选择、方向键焦点导航与禁用下发。
- [RadioSelect 单选组](/ooui-react/components/radio-select/index.md): RadioSelect 组件的属性说明：单选组（role=radiogroup），整组以方向键在选项间环绕移动并直接改选，value/onChange 通道与 options 选项集。
- [TagMultiselect 标签输入](/ooui-react/components/tag-multiselect/index.md): TagMultiselect 组件的属性说明：以标签（chip）呈现多值的输入框，支持自由输入、白名单与数量限制、拖拽重排、点击回填编辑；带候选菜单请用 MenuTagMultiselect。
- [MenuTagMultiselect 菜单标签输入](/ooui-react/components/menu-tag-multiselect/index.md): MenuTagMultiselect 组件的属性说明：带候选菜单的标签输入（TagMultiselect + 必填 options），输入即过滤菜单、↑↓/Enter 选定、点击切换标签；未开 allowArbitrary 时值域为 allowedValues 与 options 的并集。
- [ButtonInput 提交按钮](/ooui-react/components/button-input/index.md): ButtonInput 组件的属性说明：真实 <button>/<input> 元素的表单按钮，type/name/value/formNoValidate 参与原生提交，useInputTag 切换 input 形态。
- [DropdownInput 下拉字段](/ooui-react/components/dropdown-input/index.md): DropdownInput 组件的属性说明：Dropdown 展示加隐藏 select 承载原生提交，options 分组标题映射 optgroup，值失效回退首个可选值。
- [CheckboxMultiselectInput 复选组字段](/ooui-react/components/checkbox-multiselect-input/index.md): CheckboxMultiselectInput 组件的属性说明：CheckboxMultiselect 的表单形态，各选项 checkbox 写入 name/value 承载原生提交，勾选集合走数组值通道。
- [RadioSelectInput 单选组字段](/ooui-react/components/radio-select-input/index.md): RadioSelectInput 组件的属性说明：RadioSelect 展示加隐藏 input 承载原生提交，组件始终有选中项（值失效回退首个可选），name 仅落隐藏 input。
- [HiddenInputWidget 隐藏字段](/ooui-react/components/hidden-input-widget/index.md): HiddenInputWidget 组件的属性说明：以原生 <input type=hidden> 为根，承载随表单提交但不显示的值；disabled 使其退出提交。
- [Layout 布局基类](/ooui-react/components/layout/index.md): Layout 组件的属性说明：布局基类，输出 oo-ui-layout 根类并统一 hidden 三态（true / 'until-found'）与 aria-hidden 落点。
- [PanelLayout 面板](/ooui-react/components/panel-layout/index.md): PanelLayout 组件的属性说明：padded/scrollable/expanded/framed 四个形态开关，作为各类布局与自绘面板的基座。
- [PageLayout 页面布局](/ooui-react/components/page-layout/index.md): PageLayout 组件的属性说明：堆叠布局的单个分页，active 激活态与 hidden 派生关系；通常经 StackLayout 的 options 间接使用。
- [MenuLayout 菜单布局](/ooui-react/components/menu-layout/index.md): MenuLayout 组件的属性说明：menu 与 content 两块区域，menuPosition 四向定位、showMenu 收起与 expanded 铺满。
- [StackLayout 堆叠面板](/ooui-react/components/stack-layout/index.md): StackLayout 组件的属性说明：按 options 渲染分页、value/defaultValue/onChange 激活页通道、continuous 连续模式与 onPageFocus 焦点联动。
- [BookletLayout 手册布局](/ooui-react/components/booklet-layout/index.md): BookletLayout 组件的属性说明：左侧大纲加右侧页面栈的手册式布局，outlined 大纲开关、editable 大纲编辑、continuous 连续滚动与 autoFocus 自动聚焦。
- [IndexLayout 索引布局](/ooui-react/components/index-layout/index.md): IndexLayout 组件的属性说明：顶部页签加下方面板栈，openMatchedPanels 浏览器查找命中自动切页、continuous 连续显示与 autoFocus 自动聚焦。
- [TabPanelLayout 页签面板](/ooui-react/components/tab-panel-layout/index.md): TabPanelLayout 组件的属性说明：IndexLayout 的单个页签面板（role=tabpanel），active 激活态与吞掉的页签字段；通常经 IndexLayout 的 options 间接使用。
- [FieldLayout 字段布局](/ooui-react/components/field-layout/index.md): FieldLayout 组件的属性说明：给字段控件配标签的对齐方向、标签与控件的点击/聚焦联动、title 落点，以及 disabled 的样式语义。
- [FieldsetLayout 字段分组](/ooui-react/components/fieldset-layout/index.md): FieldsetLayout 组件的属性说明：原生 fieldset 字段分组，label/icon 头部、help 弹出与内联帮助、组级禁用随 fieldset 原生下发。
- [FormLayout 表单容器](/ooui-react/components/form-layout/index.md): FormLayout 组件的属性说明：包裹字段集的原生 <form> 容器，配合带 name 的输入控件做浏览器原生提交，含 method、action、enctype 与 onSubmit。
- [ActionFieldLayout 动作字段](/ooui-react/components/action-field-layout/index.md): ActionFieldLayout 组件的属性说明：FieldLayout 加输入区旁的操作按钮，fieldInline 声明内联控件形态，align 继承字段排布。
- [CopyTextLayout 复制文本](/ooui-react/components/copy-text-layout/index.md): CopyTextLayout 组件的属性说明：只读文本框加复制按钮，聚焦自动全选，copyText 待复制文本、multiline 多行形态与 onCopyResult 结果回调。
- [HorizontalLayout 横向布局](/ooui-react/components/horizontal-layout/index.md): HorizontalLayout 组件的属性说明：仅输出 oo-ui-horizontalLayout 根类的横向容器，排布交主题 CSS。
- [Dialog 弹窗](/ooui-react/components/dialog/index.md): 弹窗族总览：声明式 MessageDialog 与 Dialog 基类，受控 open 通道、尺寸、动作区与背景隔离等行为；命令式 confirm / alert / prompt 另见专页。
- [命令式弹窗](/ooui-react/components/imperative-dialogs/index.md): confirm / alert / prompt 三个命令式弹窗函数：不依赖 React 树的 Promise 调用，含返回值、options、Provider 配置继承与运行时语义。
- [ProcessDialog 流程弹窗](/ooui-react/components/process-dialog/index.md): ProcessDialog 组件的属性说明：actions 动作集与 safe/primary/other 布局、onAction 异步编排（pending 条纹与错误面板）、mode 多步模式与键盘快捷键。
- [Toolbar 工具栏](/ooui-react/components/toolbar/index.md): Toolbar 组件的属性说明：横栏容器承载若干工具组（Bar/List/Menu），工具以声明式 tools 数组传入、激活态由调用方受控，窄栏自动压缩。