> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# App

配置`@rockshin/tao-ui`

[API](#api)

提供继承应用上下文的 message、notification 和 modal 实例。

## 何时使用

用 App 包裹业务子树，在后代组件内调用 App.useApp()。TaoProvider 和自定义 Context Provider 放在 App 外部，使反馈内容继承它们。各示例在隔离预览内运行。

## 示例


### 作用域消息
Hook 必须在 App 下方使用。每个实例独立管理自身消息。
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';

function Actions() {
  const { message } = App.useApp();
  return (
    <Stack direction="horizontal" gap="sm" style={{ flexWrap: 'wrap' }}>
      <Button onClick={() => message.success('Changes saved')}>Success</Button>
      <Button
        variant="secondary"
        onClick={() => message.info('A new version is ready')}
      >
        Info
      </Button>
      <Button
        variant="secondary"
        onClick={() => message.warning('Storage is almost full')}
      >
        Warning
      </Button>
      <Button
        variant="secondary"
        onClick={() => message.error('Unable to save changes')}
      >
        Error
      </Button>
      <Button variant="secondary" onClick={() => message.destroy()}>
        Clear messages
      </Button>
    </Stack>
  );
}
export default function Example() {
  return (
    <App message={{ maxCount: 3 }}>
      <Actions />
    </App>
  );
}
```

### 通过 key 更新与等待关闭
消息返回值既可调用关闭，也支持 then。复用 key 更新已有消息。
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { App, Button, Stack } from '@rockshin/tao-ui';
import type { AppMessageType } from '@rockshin/tao-ui';

function Actions() {
  const { message } = App.useApp();
  const close = useRef<AppMessageType | null>(null);
  const [status, setStatus] = useState('Idle');
  return (
    <Stack gap="md">
      <Stack direction="horizontal" gap="sm" style={{ flexWrap: 'wrap' }}>
        <Button
          onClick={() => {
            setStatus('Running');
            close.current = message.loading({
              key: 'job',
              content: 'Preparing local preview…',
              duration: 0,
            });
            close.current.then(() => setStatus('Message closed'));
          }}
        >
          Start
        </Button>
        <Button
          variant="secondary"
          onClick={() =>
            message.success({
              key: 'job',
              content: 'Preview ready',
              duration: 0,
            })
          }
        >
          Update
        </Button>
        <Button variant="secondary" onClick={() => close.current?.()}>
          Close
        </Button>
      </Stack>
      <output>{status}</output>
    </Stack>
  );
}
export default function Example() {
  return (
    <App>
      <Actions />
    </App>
  );
}
```

### 带操作与倒计时的通知
duration 单位为秒。showProgress 展示自动关闭倒计时，默认悬停时暂停。
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';

function Actions() {
  const { notification } = App.useApp();
  return (
    <Stack direction="horizontal" gap="sm" style={{ flexWrap: 'wrap' }}>
      <Button
        onClick={() =>
          notification.success({
            key: 'export',
            title: 'Export ready',
            description: 'The sample report is ready to review.',
            duration: 8,
            showProgress: true,
            actions: (
              <Button
                size="small"
                onClick={() => notification.destroy('export')}
              >
                Dismiss
              </Button>
            ),
          })
        }
      >
        Timed notification
      </Button>
      <Button
        variant="secondary"
        onClick={() =>
          notification.info({
            title: 'Review needed',
            description: 'This notification stays open until dismissed.',
            duration: 0,
            placement: 'bottomRight',
          })
        }
      >
        Persistent notification
      </Button>
    </Stack>
  );
}
export default function Example() {
  return (
    <App notification={{ placement: 'topRight', stack: { threshold: 3 } }}>
      <Actions />
    </App>
  );
}
```

### 等待确认结果
确认时结果为 true，取消时为 false。此例只修改本地状态。
```tsx preview="iframe-follow"
import { useState } from 'react';
import { App, Button, Stack } from '@rockshin/tao-ui';

function Actions() {
  const { modal } = App.useApp();
  const [status, setStatus] = useState('Project is active');
  return (
    <Stack gap="md">
      <Button
        onClick={async () => {
          const accepted = await modal.confirm({
            title: 'Archive this project?',
            content: 'You can restore it from archived projects.',
            okText: 'Archive',
            cancelText: 'Keep project',
          });
          setStatus(
            accepted ? 'Project archived in this demo' : 'Project is active',
          );
        }}
      >
        Archive project
      </Button>
      <output>{status}</output>
    </Stack>
  );
}
export default function Example() {
  return (
    <App>
      <Actions />
    </App>
  );
}
```

### 异步确认与重试
返回 Promise 时操作保持加载状态；拒绝会保留弹窗。此本地模拟第一次失败，第二次成功。
```tsx preview="iframe-follow"
import { App, Button } from '@rockshin/tao-ui';

function Actions() {
  const { modal } = App.useApp();
  return (
    <Button
      onClick={() => {
        let attempts = 0;
        const dialog = modal.confirm({
          title: 'Save sample changes?',
          content:
            'The first attempt demonstrates an error. Try again to finish.',
          onOk: async () => {
            await new Promise((resolve) => window.setTimeout(resolve, 700));
            attempts += 1;
            if (attempts === 1) {
              dialog.update({
                content: 'The simulated save failed. Choose OK to retry.',
              });
              throw new Error('Simulated save failure');
            }
          },
        });
      }}
    >
      Try async confirmation
    </Button>
  );
}
export default function Example() {
  return (
    <App>
      <Actions />
    </App>
  );
}
```

### 更新与销毁弹窗
返回句柄可更新内容或关闭弹窗。自定义页脚可保留提供的 OkBtn 与 CancelBtn。
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';

function Actions() {
  const { modal } = App.useApp();
  return (
    <Button
      onClick={() => {
        const dialog = modal.info({
          title: 'Preview version 1',
          content: 'Review the current draft.',
          footer: (_, { OkBtn }) => (
            <Stack
              direction="horizontal"
              gap="sm"
              style={{ justifyContent: 'flex-end', flexWrap: 'wrap' }}
            >
              <Button
                variant="secondary"
                onClick={() =>
                  dialog.update({
                    title: 'Preview version 2',
                    content: 'The draft has been updated.',
                  })
                }
              >
                Update
              </Button>
              <Button variant="secondary" onClick={() => dialog.destroy()}>
                Close
              </Button>
              <OkBtn />
            </Stack>
          ),
        });
      }}
    >
      Open editable preview
    </Button>
  );
}
export default function Example() {
  return (
    <App>
      <Actions />
    </App>
  );
}
```

### 主题、语言与自定义上下文
反馈浮层保留 Provider 主题变量和 React 上下文，语言配置提供默认确认、取消与关闭文字。
```tsx preview="iframe-follow"
import { createContext, useContext } from 'react';
import { App, Button, Stack, TaoProvider, zhCN } from '@rockshin/tao-ui';

const Workspace = createContext('');
function Details() {
  return <span>Workspace: {useContext(Workspace)}</span>;
}
function Actions() {
  const { notification, modal } = App.useApp();
  return (
    <Stack direction="horizontal" gap="sm" style={{ flexWrap: 'wrap' }}>
      <Button
        onClick={() =>
          notification.info({
            title: 'Workspace context',
            description: <Details />,
          })
        }
      >
        Show notification
      </Button>
      <Button
        variant="secondary"
        onClick={() =>
          modal.confirm({ title: 'Continue?', content: <Details /> })
        }
      >
        Show confirmation
      </Button>
    </Stack>
  );
}
export default function Example() {
  return (
    <TaoProvider
      locale={zhCN}
      theme={{
        token: { colorPrimary: '#315de2' },
        components: { Button: { primaryColor: '#fff' } },
      }}
    >
      <Workspace.Provider value="Northstar">
        <App>
          <Actions />
        </App>
      </Workspace.Provider>
    </TaoProvider>
  );
}
```

### 独立作用域与自定义根节点
两个 App 实例分别管理消息。component 可替换根元素，component={false} 仅省略包装元素。
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';

function Actions({ name }: { name: string }) {
  const { message } = App.useApp();
  return (
    <Stack direction="horizontal" gap="sm" style={{ flexWrap: 'wrap' }}>
      <Button
        onClick={() =>
          message.info({
            key: 'status',
            content: `${name} workspace ready`,
            duration: 0,
          })
        }
      >
        Show {name}
      </Button>
      <Button variant="secondary" onClick={() => message.destroy()}>
        Clear {name}
      </Button>
    </Stack>
  );
}
export default function Example() {
  return (
    <Stack gap="md">
      <App
        component="section"
        message={{ top: 16 }}
        styles={{ root: { padding: 12 } }}
      >
        <Actions name="First" />
      </App>
      <App component={false} message={{ top: 80 }}>
        <Actions name="Second" />
      </App>
    </Stack>
  );
}
```

## API


### [#](#app)App



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

