For AI agents: the complete documentation index is available at /ooui-react/llms.txt, the full documentation bundle is available at /ooui-react/llms-full.txt, and this page is available as Markdown at /ooui-react/components/button-select/index.md.
  • 中文
  • ButtonSelect 按钮选择

    源代码 | 原版组件

    按钮式选择:把一组互斥选项呈现为一排按钮。选项数据约定见选择与选项。

    基本用法

    当前对齐:left
    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 一并禁用全组(见选择与选项 · 禁用)。

    import { ButtonSelect } from "ooui-react";
    
    function App() {
      return (
        <ButtonSelect
          defaultValue="a"
          options={[
            { value: "a", children: "可用" },
            { value: "b", children: "被禁用", disabled: true },
            { value: "c", children: "也可用" },
          ]}
        />
      );
    }
    
    export default App;

    键盘

    点击选项后焦点自动收进整组(略优于原版:原版点击后焦点留在原处,方向键不响应),↑↓←→ 随即在非禁用项间环绕移动并直接改选,Enter 重申当前项;也可以按 Tab 让焦点进入整组。这是“直选族”(与 TabSelect、RadioSelect 相同)的键盘模型。

    API

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

    与原版的差异

    • 初始选中的带边框选项同样反色:原版「初始选中不反色、点选后才反色」,本工程按主题规则统一为激活或禁用即反色。

    另见