# @aglyn/shared-ui-theme 中文文档

规范地址：https://npmcn.com/package/%40aglyn/shared-ui-theme/

版本：1\.19\.0
npm 元数据更新时间：2026-11-07T14:01:05.074Z
中文译文更新时间：2026-11-05T21:20:13.152Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aglyn/shared-ui-theme
原文对照：https://npmcn.com/package/%40aglyn/shared-ui-theme/?lang=original
项目主页：https://aglyn.com/
源码仓库：https://github.com/aglyn/aglyn

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

- 包体积（解压后）：995 kB，108 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：react ^19\.2\.8，@mui/types ^9\.1\.1，@mui/utils ^9\.2\.0，@mui/styles ^6\.4\.8，@mui/system ^9\.2\.0，@mui/material ^9\.3\.1
- 首次发布：2026-09-20T23:54:31.477Z
- 最新版本发布：2026-11-07T14:01:04.702Z
- 近 30 天下载量：19372（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：161（近 12 个月 161 个）

## 中文简介

Aglyn 套件共享的材料 UI 主题层:一个响应性主题工厂,控制台和站点默认主题,一个使一个站点存储的主题文件成为带有光和暗方案的主题MUI主题的提供者,情感缓存助手,以及WCAG Con

## 安装

```sh
npm install @aglyn/shared-ui-theme
```

也可以使用：`pnpm add @aglyn/shared-ui-theme`、`yarn add @aglyn/shared-ui-theme`、`bun add @aglyn/shared-ui-theme`

## README

# @aglyn/shared-ui主题

Aglyn套件共享的材料 UI主题层:一个响应性的主题工厂,控制台和站点默认主题,一个使一个站点所存储的主题文件成为有光和暗方案的主题MUI,情感缓存帮助器,以及WCAG对比工具. 它主要是制造者、设计者和其他人的附属物 `@aglyn/shared-ui-*` 软件包; 公用设施可用于任何MUI应用程序.

> 从Aglyn monorepo出版到npm. 随后的版本 [语义版本](https://semver.org/)。 。 。 .

## 安装

```
npm install @aglyn/shared-ui-theme
```

同伴依赖性 : `react`, (中文(简体) ), `@mui/material`, (中文(简体) ), `@mui/system`, (中文(简体) ), `@mui/utils`, (中文(简体) ), `@mui/types` 财务报告和审定财务报表 `@mui/styles`。 。 。 . `@emotion/react` 财务报告和审定财务报表 `@emotion/cache` 是正常的依赖关系.

## 里面有什么东西

从根入:

-   **主题工厂.** `createResponsiveTheme({ themeOptions, responsiveFontSizesOptions? })` 运行 `createTheme`,为额外的调色板颜色取出阴影,修理产生的阴影会错过AA对比度,并取出每个调色板颜色的悬浮阴影(C`hover`,一个被悬浮的 按钮或Fab 占据自己的 `contrastText`,以及 `hoverText`,并应用 `responsiveFontSizes` 跨越每一个断点. `createResponsiveCssVarTheme(light, dark, options?)` 将两个主题合并为一个CSS可变主题,按类切换.
-   **MUI模块增强.** 导入软件包会用调色板添加这些主题来扩展 MUI 的类型(`tertiary`, (中文(简体) ), `surface`, (中文(简体) ), `tint`,以及 `hover` 编号 : `hoverText` 在每种调色板颜色上,如 `displayXl`和匹配组件 `color` 超载 它还再出口一些MUI类型和帮助者(`Theme`, (中文(简体) ), `ThemeOptions`, (中文(简体) ), `SxProps`, (中文(简体) ), `darkScrollbar`, (中文(简体) ), `visuallyHidden`) (中文(简体) ).
-   **默认主题 .** `consoleThemeLight` 编号 : `consoleThemeDark` 编号 : `consoleThemeCssVar` 编号 : `getConsoleTheme(mode)` 财务报告和审定财务报表 `tenantThemeLight` 编号 : `tenantThemeDark`,与他们的 `ThemeOptions` (单位:千美元)`consoleOptions`, (中文(简体) ), `tenantOptions` 和暗变种. `siteFallbackTheme(host, scheme)` 财务报告和审定财务报表 `siteBaseOptions(host, scheme)` 在他们之间选择一个宿主.
-   **主持人主题.** A 类 `HostTheme` (该类型生活在 `@aglyn/shared-data-types`)是一个网站的主题定制,作为纯数据. `hostThemeToThemeOptions(theme, scheme)` 转换为 `ThemeOptions`· ; `sanitizeHostTheme`, (中文(简体) ), `mergeThemeOptions`, (中文(简体) ), `hasHostTheme` 财务报告和审定财务报表 `getGoogleFontsUrl` 支持这个计划. `HostThemeProvider` 将孩子置于其中,带走 `theme`, 要求 `fallback` 主题或 `[light, dark]` 双人, `baseOptions`,以及 `initialMode` 编号 : `initialDeviceMode` 因此服务器渲染器可以在水合之前选择方案.
-   **自行托管字体.** `util/self-hosted-fonts` 将 Google 字体 CSS2 样式表读入 `@font-face` 规则`parseGoogleFontFaces`),将每个文件写回网站 `/api/fonts` 路线 (`selfHostedFontFaceCss`),并取出一至两张值得预装的相貌(`selfHostedFontPreloads`) (中文(简体) ). 佃户取来并服务;这半是纯的.
-   **浅暗模式.** `createWithThemeProvider({ theme })` 返回提供主题和模式状态的更高顺序组件; `useThemeMode()` 阅读并切换。 选择存储在 `theme-color-mode` 饼干`COOKIE_THEME_KEY`) (中文(简体) ).
-   **情绪.** `createEmotionCache`, (中文(简体) ), `CacheProvider`, (中文(简体) ), `createLayeredEmotionCache`, (中文(简体) ), `createWithEmotionClientCache`常数 `EMOTION_CACHE_KEY`, (中文(简体) ), `APP_EMOTION_CACHE_OPTIONS`, (中文(简体) ), `MUI_CSS_LAYER_NAME`。 。 。 .
-   **相会相会.** `contrastRatio`, (中文(简体) ), `relativeLuminance`, (中文(简体) ), `meetsContrast`, (中文(简体) ), `accessibleShade`, (中文(简体) ), `accentTextColor`, (中文(简体) ), `accentFillColor`, (中文(简体) ), `accentHoverFillColor`, (中文(简体) ), `accentHoverTextColor`, (中文(简体) ), `hoverFillShade`, (中文(简体) ), `inkContrast`, (中文(简体) ), `auditPaletteContrast`,与 `AA_TEXT_CONTRAST` (4.5个)和 `AA_NON_TEXT_CONTRAST` (3) (3).
-   **小帮手.** `mergeSxProps` 编号 : `useMergeSxProps`, (中文(简体) ), `generateComponentClassKeys`, (中文(简体) ), `FontFamily`, (中文(简体) ), `buildFontFamilyList`。 。 。 .

仅通过子路径: `util/theme-editor-fields` 财务报告和审定财务报表 `util/theme-editor-defaults` (字段词汇和读者/写作员使用的主题编辑器超过 `HostTheme`, (中文(简体) ), `util/theme-mode-cookie`, (中文(简体) ), `util/color-scheme-hint` 财务报告和审定财务报表 `util/scheme-route-segment` (服务员-旁解决来访者计划).

## 使用量

```tsx
import {
  contrastRatio,
  createResponsiveTheme,
  createWithThemeProvider,
} from '@aglyn/shared-ui-theme'

const light = createResponsiveTheme({
  themeOptions: { palette: { primary: { main: '#1565c0' } } },
})
const dark = createResponsiveTheme({
  themeOptions: { palette: { mode: 'dark', primary: { main: '#90caf9' } } },
})

const withTheme = createWithThemeProvider({ theme: [light, dark] })

export const App = withTheme(function App() {
  return <main>Hello</main>
})

contrastRatio('#ffffff', '#1565c0') // a number; 4.5 or more passes AA for text
```

```ts
import { parseThemeModeCookie } from '@aglyn/shared-ui-theme/util/theme-mode-cookie'
```

## 怎样才合适

A 类 `shared` UI软件包. 这取决于 `@aglyn/shared-data-types`, (中文(简体) ), `@aglyn/shared-util-tools` 财务报告和审定财务报表 `@aglyn/shared-util-vendor`。 。 。 . `@aglyn/shared-ui-jsx`, (中文(简体) ), `@aglyn/shared-ui-jsx-forms`, (中文(简体) ), `@aglyn/shared-ui-next`,节点渲染器和相接器在它上再上. 共享软件包是通用的:它们只导入其他共享软件包并持有没有插件的域名.

## 许可证

阿帕奇2.0 (英语). 资料来源: [https://github.com/aglyn/aglyn/tree/main/libs/shared/ui/them 页面存档备份,存于互联网档案馆](https://github.com/aglyn/aglyn/tree/main/libs/shared/ui/theme)

## 常见问题

### @aglyn/shared-ui-theme 是什么？

Aglyn 套件共享的材料 UI 主题层:一个响应性主题工厂,控制台和站点默认主题,一个使一个站点存储的主题文件成为带有光和暗方案的主题MUI主题的提供者,情感缓存助手,以及WCAG Con

### 如何安装 @aglyn/shared-ui-theme？

在项目目录运行 npm install @aglyn/shared-ui-theme，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2\.8）、@mui/types（^9\.1\.1）、@mui/utils（^9\.2\.0）、@mui/styles（^6\.4\.8）、@mui/system（^9\.2\.0）、@mui/material（^9\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aglyn/shared-ui-theme 支持 TypeScript 吗？

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

### @aglyn/shared-ui-theme 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aglyn/shared-ui-theme 可以商用吗？

@aglyn/shared-ui-theme 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aglyn/shared-ui-theme 的下载量有多少？

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

### @aglyn/shared-ui-theme 还在维护吗？

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