# @astral/ui 中文文档

规范地址：https://npmcn.com/package/%40astral/ui/

版本：4\.120\.1
npm 元数据更新时间：2026-11-06T13:34:19.386Z
中文译文更新时间：2026-11-07T00:53:36.272Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40astral/ui
原文对照：https://npmcn.com/package/%40astral/ui/?lang=original
源码仓库：https://git.astralnalog.ru/frontend.shared/ui

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

- 包体积（解压后）：11.1 MB，17186 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：21 个
- peer 依赖：react ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，@types/react ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，@astral/validations ^4\.24\.0
- 首次发布：2022-02-02T12:53:24.965Z
- 最新版本发布：2026-11-06T13:34:19.207Z
- 近 30 天下载量：3393（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：1362（近 12 个月 276 个）

## 中文简介

`@astral/ui` {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1} - 额...

## 安装

```sh
npm install @astral/ui
```

也可以使用：`pnpm add @astral/ui`、`yarn add @astral/ui`、`bun add @astral/ui`

## README

# @ astral/ ui (英语)

`@astral/ui` {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1} - 额...

# 目录

-   [故事书](https://npmcn.com/package/%40astral/ui/#readme-storybook)
-   [导言](https://npmcn.com/package/%40astral/ui/#readme-introduction)
-   [游戏场](https://npmcn.com/package/%40astral/ui/#readme-playground)
-   [从 Next.js 开始](https://npmcn.com/package/%40astral/ui/#readme-getting-started-with-nextjs)
-   [移徙指南](https://npmcn.com/package/%40astral/ui/#readme-migration-guide)
-   [解决问题](https://npmcn.com/package/%40astral/ui/#readme-troubleshooting)
    -   [{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢](https://npmcn.com/package/%40astral/ui/#readme-%D0%BC%D0%B5%D0%B4%D0%BB%D0%B5%D0%BD%D0%BD%D0%BE-%D0%B2%D1%8B%D0%BF%D0%BE%D0%BB%D0%BD%D1%8F%D1%8E%D1%82%D1%81%D1%8F-vitest-%D1%82%D0%B5%D1%81%D1%82%D1%8B-%D0%BF%D1%80%D0%B8-%D0%B8%D0%BC%D0%BF%D0%BE%D1%80%D1%82%D0%B5-%D0%BF%D0%B0%D0%BA%D0%B5%D1%82%D0%B0)
-   [倾斜](https://npmcn.com/package/%40astral/ui/#readme-utils)

# [故事书](https://main--61baeff6f06230003a88ef8a.chromatic.com/)

[故事书](https://main--61baeff6f06230003a88ef8a.chromatic.com/) {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢 `@astral/ui`。 。 。 .

# 导言

`@astral/ui` -=YTET -伊甸园字幕组=- 翻译:.

`@astral/ui` экспортирует:

-   反应 - , , , , ,
-   反应-hook-form,
-   {\\fn黑体\\fs20\\shad2\\2ah82\\3ah20\\4ah33\\fscx95\\3ch592001\\be1}你觉得怎么样.

# 游戏场

Доступен [密码框](https://codesandbox.io/p/sandbox/sleepy-chatterjee-8mv9ml?file=%2Fsrc%2FPlayground%2FPlayground.tsx%3A12%2C1) для.

# 从 Next.js 开始

## 示例

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `@astral/ui` находится [здесь](https://git.astralnalog.ru/frontend.shared/project-starter)。 。 。 .

## 安装

```shell
npm --save @astral/ui
```

## 环球.d.ts

```ts
/// <reference types="@astral/ui/declarations" />

```

## 下一个。配置

```js
const nextConfig = {
  ...
  transpilePackages: [
    '@astral/ui'
  ],
  webpack(config) {
    config.module.rules.push({
      test: /\.(woff|woff2)$/i,
      issuer: { and: [/\.(js|ts)x?$/] },
      type: 'asset/resource',
    });

    return config;
  },
  ...
};

module.exports = nextConfig;
```

## 应用程序tsx

```tsx
import { AppProps } from 'next/app';
import Head from 'next/head';
import * as monitoringErrorService from '@sentry/nextjs';
import {
  type BrandPalette,
  ConfigProvider,
  NotificationContainer,
  StylesCacheProvider,
  ThemeProvider,
  createTheme,
} from '@astral/ui';
import { createStylesCache as createStylesServerCache } from '@astral/ui/server';

import { MainLayout } from '@example/modules/LayoutModule';

const brandPalette: BrandPalette = {
  primary: {
    900: '#5D3FD4',
    800: '#6746EB',
    700: '#8566FF',
    600: '#9075FF',
    500: '#9D85FF',
    400: '#B29EFF',
    300: '#C2B2FF',
    200: '#E0D9FF',
    100: '#EFEBFF',
  },
  secondary: {
    800: '#5653FF',
  },
  brand: {
    800: '#6746EB',
    background: '#FAFBFC',
  },
};

export const theme = createTheme({ palette: brandPalette });

const stylesCache = createStylesServerCache({ key: 'next' });

export const App = ({ Component, pageProps }: AppProps) => {
  return (
    <>
      <Head>
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1, shrink-to-fit=no"
        />
        <title>Astral.Example</title>
      </Head>
      <StylesCacheProvider value={stylesCache}>
        <ConfigProvider
          captureException={monitoringErrorService.captureException}
        >
          <ThemeProvider theme={theme}>
            <NotificationContainer />
            <MainLayout>
              <Component {...pageProps} />
            </MainLayout>
          </ThemeProvider>
        </ConfigProvider>
      </StylesCacheProvider>
    </>
  );
};

export default App;
```

# 移徙指南

## 3.0.0 - > 4.0.0 (中文(简体) )

### 字体

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `theme` больше.

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 [{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢](https://frontend-static.astral.ru/)

[{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢](https://main--61baeff6f06230003a88ef8a.chromatic.com/?path=/docs/getting-started-fonts--docs)

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 **内容安全政策**。 。 。 .

## 2.0.0 - > 3.0.0 (中文(简体) )

### 配置

配置 prof `imagesMap`数字 :

```ts
type ImagesMap = {
  /**
   * изображение при отсутствии данных (используется в DataGrid)
   */
  noDataImgSrc: string;
  /**
   * изображение при ошибке (используется в ContentState)
   */
  defaultErrorImgSrc: string;
  /**
   * изображение при ошибке при обновлении продукта (используется в ContentState/ErrorBoundary)
   */
  outdatedReleaseErrorImgSrc: string;
};
```

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我还不知道你是谁 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}.

中断更改 :

-   (原始内容存档于2018-09-26). DataGrid. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}======================================================================================================================================================================================================================================= `imagesMap.noDataImgSrc`
-   \* 内容状态 \* \* \* \* \* \* 需要道具 `errorState.imgSrc`。 。 。
-   {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}======================================================================================================================================================================================================================================= `images.outdatedReleaseErrorImgSrc`

```tsx
import noDataImgSrc from '@astral/ui/illustrations/no-data.svg';
import outdatedReleaseErrorImgSrc from '@astral/ui/illustrations/outdated-release.svg';

/* cspell:disable-next-line */
import errorImgSrc from 'static/erorr-inmg.png';

const App = () => {
  return (
      <ConfigProvider
          imagesMap={{
              defaultErrorImgSrc: errorImgSrc,
              noDataImgSrc,
              outdatedReleaseErrorImgSrc,
          }}
      >
          <ThemeProvider>
              <Layout />
          </ThemeProvider>
      </ConfigProvider>
  );
};
```

### 类型

中断更改 :

-   (边疆,边疆,先生. )
-   Prop `color` принимает `string`颜色

Актуальные道具находятся [здесь](https://main--61baeff6f06230003a88ef8a.chromatic.com/?path=/docs/typography-typography--docs)。 。 。 .

### 网格

@astral/ui v2 ######### 遗产Grid #########################################################################################################################################################################################################################################.

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我.. [故事书](https://main--61baeff6f06230003a88ef8a.chromatic.com/?path=/docs/layouts-grid--docs)。 。 。 .

### 表单

中断更改 :

-   说吧 `FormDatePicker`, (中文(简体) ), `FormMobilePhoneField`
-   {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `rules`{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你还不知道吗 [@ astral/验证](https://www.npmjs.com/package/@astral/validations)

## 1.0.0 - > 2.0.0 (中文(简体) )

### 选项

Теперь `@astral/ui` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢

-   `@astral/fonts`
-   `@astral/illustrations`
-   `@astral/icons`
-   `@astral/form`
-   `@astral/components`

说吧

```json
{
  ...
  "@astral/icons": "^1.19.4",
  "@astral/form": "^1.19.4",
  "@astral/fonts": "^1.19.4",
  "@astral/ui": "^1.19.4",
  ...
}
```

На:

```json
{
  ...
  "@astral/ui": "^1.19.4",
  ...
}
```

### 环球.d.ts

Заменить `global.d.ts`数字 :  
`global.d.ts`

```ts
/// <reference types="@astral/ui/declaration/emotion" />
/// <reference types="@astral/ui/declaration/mui-material" />
/// <reference types="@emotion/react/types/css-prop" />
```

На:  
`global.d.ts`

```ts
/// <reference types="@astral/ui/declarations" />
```

### 字体

Пакет `@astral/fonts` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢 `@astral/ui`。 。 。 .

说吧

```ts
import UbuntuBoldWoff from '@astral/fonts/UbuntuBold.woff';
import UbuntuBoldWoff2 from '@astral/fonts/UbuntuBold.woff2';
```

На:

```ts
import UbuntuBoldWoff from '@astral/ui/fonts/UbuntuBold.woff';
import UbuntuBoldWoff2 from '@astral/ui/fonts/UbuntuBold.woff2';
```

@astral/ui/fonts # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # ########### # # # # #######################################################################################.

### 插图

Пакет `@astral/illustrations` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢 `@astral/ui`。 。 。 .

说吧

```ts
import certImgSrc from '@astral/illustrations/cert.svg';
```

На:

```ts
import certImgSrc from '@astral/ui/illustrations/cert.svg';
```

@astral/ui/fonts # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # ########### # # # # #######################################################################################.

### @ astral/ 窗体

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `@astral/form` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢. Весь `@astral/form` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢 `@astral/ui`。 。 。 .

```ts
import { useForm, useFormWatch, useFormController } from '@astral/ui';
```

### @ astral/缩写

Весь `@astral/icons` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢 `@astral/ui`。 。 。 .

```ts
import { QuitOutlineMd } from '@astral/ui';
```

### 日期选择器提供器

\======================================================================================================================================================================================== (=================== (============================= (====================.

# 解决问题

## {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我对你的爱很感兴趣 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我对你的爱很感兴趣 `conditions` 用户 `vitest.config.ts`数字 :

```ts
/// <reference types="vitest" />

import react from '@vitejs/plugin-react-swc';
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  resolve: {
    conditions: ['vitest'],
  },
  test: {
    environment: 'happy-dom',
  },
});
```

? В `exports.vitest`说得没错. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}=========================================================================================== ===========================================================================================================================================.

# 倾斜

目录

-   [重定向到链接](https://npmcn.com/package/%40astral/ui/#readme-redirectToLink)

## 重定向到链接

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢

```ts
import { redirectToLink } from '@astral/ui';

// Открытие ссылки в текущей вкладке или фрейме
redirectToLink('/');

// Открытие ссылки в новой вкладке
redirectToLink('/', '_blank')

```

## 常见问题

### @astral/ui 是什么？

@astral/ui \{\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1\} - 额\.\.\.

### 如何安装 @astral/ui？

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

### @astral/ui 支持 TypeScript 吗？

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

### @astral/ui 支持 ESM 还是 CommonJS？

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

### @astral/ui 可以商用吗？

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

### @astral/ui 的下载量有多少？

根据 npm 官方下载统计，@astral/ui 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,393 次，日均约 113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @astral/ui 还在维护吗？

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