# @datalayer/primer-addons 中文文档

规范地址：https://npmcn.com/package/%40datalayer/primer-addons/

版本：1\.0\.48
npm 元数据更新时间：2026-10-31T13:04:56.778Z
中文译文更新时间：2026-11-11T14:48:14.876Z
软件包许可：BSD-3-Clause

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

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

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

- 包体积（解压后）：1.4 MB，305 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，react-dom ^18\.3\.1 \|\| ^19\.0\.0
- 首次发布：2023-05-15T08:35:31.867Z
- 最新版本发布：2026-10-31T13:04:56.474Z
- 近 30 天下载量：17531（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 41 个）

## 中文简介

[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai/)

## 安装

```sh
npm install @datalayer/primer-addons
```

也可以使用：`pnpm add @datalayer/primer-addons`、`yarn add @datalayer/primer-addons`、`bun add @datalayer/primer-addons`

## README

[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai/)

[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)

# ++++ 初级Addons

> Primer React 的额外组件 .

此寄存器包含额外的 React.js 组件 [@ primer/ 反应](https://github.com/primer/react) 工具包。 这些组成部分符合初级主题框架,旨在尊重 [初级设计系统](https://primer.style/)。 。 。 .

看到他们活着:

-   **图片库** ——其页面的每个组件,每个主题和颜色模式: [https://primer-addons.datalayer.tech 互联网档案馆的存檔,存档日期2014-12-21](https://primer-addons.datalayer.tech/) (单位:千美元)`make deploy-gallery` 发表).
-   **故事书** ——每个组件的选择,故事逐个故事: [https://primer-addons.datalayer.tech/storybook/ 页面存档备份,存于互联网档案馆](https://primer-addons.datalayer.tech/storybook/) (单位:千美元)`make deploy-storybook`) (中文(简体) ).

这个项目一直是 [共同讨论](https://github.com/primer/react/discussions/3297) 在 Primer React 主存储器上.

## 当前添加

-   [x] 外观控件、菜单、主题预览和协作调色板
-   [x] 方框
-   [x] 日历拾取器
-   [x] 纸牌
-   [x] 圆形图标
-   [x] 可关闭闪光
-   [x] 彩色监视和取色器
-   [x] 内容加载器
-   [x] 约会拾取器
-   [x] 实体神通
-   [x] 贺卡
-   [x] 数据层标志和文字标记
-   [x] 工作表
-   [x] 侧面重叠
-   [x] 幻灯片
-   [x] 滑动面板
-   [x] 工具栏和浮动工具栏

组件使用活动主题的语义符号而不是固定 视觉价值. 例如,工具栏图标按钮和下拉触发器读取 `--theme-radius-control`: 默认情况下保留正则首页角 并成为全圆形控件 `loop`。 。 。 .

## 反应堆插件

用于主机的 三个插件 [`@datalayer/reactor`](https://github.com/datalayer/reactor),通过路径导入,所以没有反应堆的一页从不拉入:

```ts
import { AppearancePlugin, PageLayoutPlugin, ThemePlugin } from '@datalayer/primer-addons/lib/reactor';
```

-   `ThemePlugin` 将Primer的门户保留在应用程序的颜色模式中,并按命令切换该模式(`Mod+Alt+C`) (中文(简体) ).
-   `AppearancePlugin` 将外观菜单——颜色模式,主题,主题的描述和预览,Datalayer头部所戴的控制——放入一个插槽, `header` 默认,并带来 `ThemePlugin` 作为依赖.
-   `PageLayoutPlugin` 将主机的槽安排为页面:插件放入的内容 `page` 躺在一张圆形的被子上, `page-band` 被靠在工作表的宽度上方(或作为卡片浮起), `page-chips` 坐在乐队下面,和 `page-panel` 是一个从头部切换器打开的侧面板。 版式( A)`PageLayout`、其切换及其信号(`pageLayoutPanelOpen`, (中文(简体) ), `openPagePanel()`(......)也出口,因为主机将部件本身接通,即Loop `@datalayer/agent-runtimes` 做,以笔记本作为页面 和对话作为面板.

这个 [图片库实例](https://npmcn.com/package/%40datalayer/primer-addons/examples/gallery) 是一个反应堆应用软件,基于三: `npm run gallery` 当地,住在 [https://primer-addons.datalayer.tech 互联网档案馆的存檔,存档日期2014-12-21](https://primer-addons.datalayer.tech/)。 。 。 .

![Primer React Addons](https://assets.datalayer.tech/primer-addons-example.png)

## `Box`

`Box` 是这个软件包自己的,而不是Primer被贬值的: 相同的道具名称——空格(`p`, (中文(简体) ), `mx`, (中文(简体) ), `gap`...),颜色 (`color`, (中文(简体) ), `bg`),边界(`border`, (中文(简体) ), `borderColor`, (中文(简体) ), `borderRadius`, (中文(简体) ), `borderTop`),布局,弹性和网格,位置,类型, `boxShadow`, (中文(简体) ), `opacity`, (中文(简体) ), `cursor`, (中文(简体) ), `transition`, (中文(简体) ), `transform`, (中文(简体) ), `listStyle`,以及 `as` ——没有有风格的组件.

```tsx
import { Box } from '@datalayer/primer-addons';

<Box as="section" display="flex" flexDirection="column" gap={2} p={3}
  bg="canvas.default" border="1px solid" borderColor="border.default" borderRadius="large"
  gridTemplateColumns={['1fr', null, 'repeat(3, 1fr)']}
  hover={{ bg: 'canvas.subtle' }} focusVisible={{ outline: '2px solid' }}>
  …
</Box>
```

-   **Tokens是Primer的CSS变量,没有倒计时.** 颜色路径是变量Primer自己的主题首先读取(`bg="canvas.subtle"` 实值 `var(--bgColor-muted)`, (中文(简体) ), `borderColor="border.default"` 实值 `var(--borderColor-default)`, (中文(简体) ), `boxShadow="shadow.medium"` 实值 `var(--shadow-resting-medium)`); 以名称命名的半径为Primer's(`small`, (中文(简体) ), `medium`, (中文(简体) ), `large`, (中文(简体) ), `full`)或主题的形状(`control`, (中文(简体) ), `card`, (中文(简体) ), `bubble`, (中文(简体) ), `frame`; 以名称表示的重量是主题的重量变量. 空间,字体大小,以索引和大小表示的弧度,是Primer以像素表示的主题尺度(`p={3}` 为 16px)。 主题提供者设置每个变量 `Box` 发布,在每个主题中——一个测试持有它——所以一个想要另一个发线或角的主题将其设置在Primer的变量上(即: `loop` 主题的发线是它的 `--borderColor-default`,它的卡片角 它的 `--borderRadius-large`),从来没有一个呼叫网站 `var(--loop-…, var(--…))`。 。 。 .
-   **响应值** 每个断点一个,Primer's(544,768,1012,1280px), `null` 跳过一个.
-   **国家** 采取他们自己的风格: `hover`, (中文(简体) ), `focus`, (中文(简体) ), `focusVisible`, (中文(简体) ), `focusWithin`, (中文(简体) ), `active`,以及 `reducedMotion`。 。 。 .
-   **每作一课.** 道具被解析后散列成一个类,其规则被插入文档的样式表,或者元素所在的阴影根. 没有样式组件:这个包的复制件曾经在Primer的旁边被运出,无论哪个捆绑者没有去除它们, `Box` 没有主题.
-   **`sx` 还行**,键入,同时调用站点移动到道具上:其键被读取为道具(同为道具)和被嵌入的块- `'&:hover'`, (中文(简体) ), `'& svg'`, (中文(简体) ), `'@media (…)'`, (中文(简体) ), `'@keyframes …'` 成为同一阶级的规则,在道具之后. 上面没有样式组件: 首页 `Box` 6 通过 `sx` 开始DOM。 无法移动到道具的编码器( 已取消的选择器、 键框) 中 `sx`。 。 。 .

资料来源: `src/components/box/Box.tsx` (设计), `boxCss.ts` (道具和仪表,样式表), `boxTokens.ts` (由Primer主题生成的标志), `src/theme/css/primerBaseVars.ts` (Primer的变量没有主题集).

## 主题口音

6个轻口音,一个应用需要1个—— **覆盖任何主题**数字 : `datalayer`, (中文(简体) ), `spatial`, (中文(简体) ), `lovely`, (中文(简体) ), `matrix`, (中文(简体) ), `earth`, (中文(简体) ), `sand`, (中文(简体) ), `ivory`, (中文(简体) ), `sun` 财务报告和审定财务报表 `loop` 相同(决定2026-10-07;彩色) `loop` 独自一人 这个 [画廊](https://npmcn.com/package/%40datalayer/primer-addons/examples/gallery)是因为 _主题角_ 页面显示画廊所使用主题和颜色模式的六位, 每个值都是5个值——口音,坐在上面的文字 **阶段** (主机应用程序的后缀), a **安静** (代理发泡,草稿)和口音 **作为文本** (一个链接,一个建议的问题)——后三个各有光和暗值.

| 名称 | 百分点 | 上面写着 | 阶段( 浅/ 暗) | 安静( 轻/ 暗) | 作为文本( 浅/ 暗) |
| --- | --- | --- | --- | --- | --- |
| `green` (薄荷,默认值) | `#7ADBB8` | `#06281E` | `#DDF5EC` 编号 : `#10261F` | `#F0FAF6` 编号 : `#17211D` | `#248462` 编号 : `#8FE5C6` |
| `rose` | `#F6A5C1` | `#3A0A1C` | `#FCE3EC` 编号 : `#2B141C` | `#FDF2F6` 编号 : `#22181C` | `#B83A6B` 编号 : `#F6A5C1` |
| `sky` | `#8CCBF9` | `#06243B` | `#DFF0FD` 编号 : `#0F2333` | `#F0F8FE` 编号 : `#161E25` | `#1F6FB0` 编号 : `#8CCBF9` |
| `lime` | `#BEDC55` | `#1F2A00` | `#EEF6CC` 编号 : `#1E2609` | `#F7FBE6` 编号 : `#1C2014` | `#5F7A00` 编号 : `#BEDC55` |
| `sun` | `#F8D469` | `#2E2200` | `#FDF3CD` 编号 : `#2A2209` | `#FEF9E7` 编号 : `#221F14` | `#8A6A00` 编号 : `#F8D469` |
| `violet` | `#C0AEF6` | `#1C0F47` | `#ECE7FD` 编号 : `#1B1533` | `#F6F3FE` 编号 : `#1C1A27` | `#6B53C9` 编号 : `#C0AEF6` |

`themeAccents` 拿着他们, `themeAccentNames` 按拾取者显示的顺序列出(类型) `ThemeAccentName`),以及 `themeAccentVars(name, mode)` 当一个应用程序设置在它的根上时, 将它变成它的所有颜色 :

-   口音是自己的,哪个 **每个主题集** (它从自己的颜色中默认——它的口音填充,它所填充的按钮的文字,它的细微口音为舞台,它的细微的画布为静静的花纹;); `loop`'是薄荷': `--theme-accent`, (中文(简体) ), `--theme-accent-on`, (中文(简体) ), `--theme-stage`, (中文(简体) ), `--theme-quiet`,以及 `--theme-stage-gradient`舞台从舞台上点起 从舞台上点起 舞台上点起;
-   初标口音: `--bgColor-accent-emphasis`, (中文(简体) ), `--borderColor-accent-emphasis`, (中文(简体) ), `--fgColor-accent`, (中文(简体) ), `--fgColor-link`, (中文(简体) ), `--borderColor-accent-muted`, (中文(简体) ), `--bgColor-accent-muted`,以及 `--datalayer-icon-fg`· ;
-   已填入的按钮 : `--button-primary-bgColor-rest`, (中文(简体) ), `-hover`, (中文(简体) ), `-active`他们的边界, `--button-primary-fgColor-rest`, (中文(简体) ), `--button-primary-iconColor-rest`, (中文(简体) ), `--buttonCounter-primary-fgColor-rest`和遗产 `--color-btn-primary-bg`, (中文(简体) ), `--color-btn-primary-hover-bg`· ;
-   已选中的开关 : `--control-checked-bgColor-rest`, (中文(简体) ), `-hover`, (中文(简体) ), `-active`, (中文(简体) ), `--control-checked-fgColor-rest`, (中文(简体) ), `--controlKnob-borderColor-checked`· ;
-   选中标签下划线, `--underlineNav-borderColor-active`。 。 。 .

所以一个应用程序的页面上没有任何东西 保留主题的默认口音 除了自己的。 主题焦点环( C)`--focus-outlineColor`)被保存:它被绘制来显示每个口音. 姓名不详者被拒.

应用程序在其缩写中将其重音命名为 `interface.accent` (6个名字之一),其主机应用,无论应用程序穿什么主题. 一个名字没有重新命名的应用程序: 它会穿戴它主题的自有颜色——薄荷英寸 `loop` (决定2026-10-07).

```tsx
import { getThemeConfig, themeAccentVars } from '@datalayer/primer-addons';

const config = getThemeConfig(app.interface.theme.variant);
<DatalayerThemeProvider theme={config.primerTheme} themeStyles={config.themeStyles}
  baseStyles={app.interface.accent ? themeAccentVars(app.interface.accent, mode) : undefined}>
```

来源: `src/theme/colors/themeAccents.ts`。 。 。 .

## 调色板

`useColorPalette()` 返回一个 `ColorPalette` 对象,为当前主题和颜色模式所解析(任何一种变化时为新模式); `getColorPalette(theme, mode)` 给同样的,没有钩子。 它有两种颜色,和 `isLight`,无论模式是否轻。 这个 [画廊](https://npmcn.com/package/%40datalayer/primer-addons/examples/gallery)是因为 _颜色调色板_ 页面以任何主题和方式显示画廊.

-   **作用**,每个主题自己的设计用什么,按角色(`paletteRoleNames`类型 `PaletteRoleName`: `bg`, (中文(简体) ), `bgPanel`, (中文(简体) ), `bgAlt`, (中文(简体) ), `primary`, (中文(简体) ), `secondary`, (中文(简体) ), `accent`, (中文(简体) ), `glow`, (中文(简体) ), `pop`, (中文(简体) ), `spark`, (中文(简体) ), `blaze`, (中文(简体) ), `surge`, (中文(简体) ), `flame`, (中文(简体) ), `gold`, (中文(简体) ), `textLight`, (中文(简体) ), `textMuted`. 主题改变的作用是什么(`surge` 一个主题为蓝色,另一个主题为贤者。 用它们来设计网页.
-   **色调**,命名一个规格或个人选择的颜色,每个主题中的名称相同(`hueNames`类型 `HueName`: `red`, (中文(简体) ), `orange`, (中文(简体) ), `amber`, (中文(简体) ), `yellow`, (中文(简体) ), `lime`, (中文(简体) ), `green`, (中文(简体) ), `emerald`, (中文(简体) ), `teal`, (中文(简体) ), `cyan`, (中文(简体) ), `sky`, (中文(简体) ), `blue`, (中文(简体) ), `indigo`, (中文(简体) ), `violet`, (中文(简体) ), `purple`, (中文(简体) ), `fuchsia`, (中文(简体) ), `pink`, (中文(简体) ), `rose`, (中文(简体) ), `slate`, (中文(简体) ), `gray`, (中文(简体) ), `stone`. . . . . . . 用来作一分色或人取取取的颜色,如代理人取取的颜色.

`paletteColorNames` 列出这两个角色(类型) `PaletteColorName`) (中文(简体) ).

角色,一个页面本身的设计:

```tsx
import { useColorPalette } from '@datalayer/primer-addons';

const palette = useColorPalette();
<Box style={{ background: palette.bgPanel, color: palette.textLight }}>
  <Text style={{ color: palette.primary }}>Title</Text>
</Box>
```

取出色调的色调: spec 给出调色板名称( 代理) `color: indigo`),或者一个无名无姓的"六合". `usePaletteColor()` 返回在当前主题和模式下解决的函数; `resolvePaletteColor(value, palette)` 手持调色板也这样做。 调色板名称给出了它的价值,一个六角形像现在一样被还原,没有其它东西 `undefined`,所以调用者自行提取默认值. `isPaletteColorName` 财务报告和审定财务报表 `isHexColor` (单位:千美元)`#RGB` 或者说 `#RRGGBB`)先检查一个值.

```tsx
import { isHexColor, isPaletteColorName, resolvePaletteColor, usePaletteColor } from '@datalayer/primer-addons';

const colorOf = usePaletteColor();
const agentColor = colorOf(agent.color) ?? 'var(--fgColor-accent)';
// 'indigo' -> the theme's indigo, '#0969da' -> '#0969da', 'nope' -> undefined

resolvePaletteColor('teal', palette);
isPaletteColorName('rose'); // true
isHexColor('#abc');         // true
```

来源: `src/theme/palettes/ColorPalette.tsx` 财务报告和审定财务报表 `src/theme/colors/hueColors.ts`。 。 。 .

## 这个 `loop` 主题

`loop` )是主题登记簿的变种之一(`ThemeVariant`, (中文(简体) ), `themeConfigs`页:1 `datalayer`, (中文(简体) ), `spatial`, (中文(简体) ), `lovely`, (中文(简体) ), `matrix`, (中文(简体) ), `earth`, (中文(简体) ), `sand`, (中文(简体) ), `ivory` 财务报告和审定财务报表 `sun`: LOOP中构建的应用程序外观 - **一个口音, 中和其他一切**. 白色(在暗模式下近黑)帆布,深灰色墨水,发线,柔软的影子,圆角和口音中一个填充的按钮. 成功、注意力和危险只用于判决和规则。 这个 [画廊](https://npmcn.com/package/%40datalayer/primer-addons/examples/gallery) 显示在 _主题角_ 页面,当画廊穿它。 它的口音是薄荷糖, `green` 会 议 日 程 和 议 程 [主题口音](https://npmcn.com/package/%40datalayer/primer-addons/#readme-theme-accents)。 。 。 .

```tsx
import { DatalayerThemeProvider, loopTheme, loopThemeStyles } from '@datalayer/primer-addons';

<DatalayerThemeProvider theme={loopTheme} themeStyles={loopThemeStyles} colorMode="auto">
  {app}
</DatalayerThemeProvider>
```

资料来源: `src/theme/colors/loopColors.ts` (颜色), `src/theme/themes/loopTheme.ts` (主题), `src/theme/css/createThemeCSSVars.ts` (每个主题集), `src/theme/DatalayerThemeProvider.tsx` 财务报告和审定财务报表 `src/utils/Portals.tsx` (主题的样式表是如何应用的).

### 形状、阴影、类型和运动

**每个主题** 设置这些,使组件能够读取其形状——以及链接如何读取信息——读取其颜色的方式(`shapeVars`, (中文(简体) ), `DEFAULT_THEME_SHAPE`) (中文(简体) ). 其他8个主题采用默认——今天的角落,完全不动——并保留它们拥有的所有其他价值 `themeShape.test.ts` 由每一张照片的快照支撑.

| 脚本 | 默认( 每个其它主题) | `loop` |
| --- | --- | --- |
| `--theme-radius-control` | `var(--borderRadius-medium, 6px)` | `999px` |
| `--theme-radius-card` | `var(--borderRadius-medium, 6px)` | `20px` |
| `--theme-radius-bubble` | `var(--borderRadius-large, 12px)` | `22px` |
| `--theme-radius-frame` | `var(--borderRadius-large, 12px)` | `28px` |
| `--theme-hairline` | `var(--borderWidth-thin, 1px)` | 同样的 |
| `--theme-shadow` | `var(--shadow-resting-small, none)` | 框的阴影,每个模式 |
| `--theme-motion-status` | `0ms` | `120ms` |
| `--theme-motion-message` | `0ms` | `200ms` |
| `--theme-motion-pane` | `0ms` | `320ms` |
| `--theme-motion-easing` | `ease` | `cubic-bezier(0.2, 0, 0, 1)` |
| `--theme-message-link` | `var(--fgColor-accent, #0969da)` | `currentColor`:一个信息中的链接是简单的,其文字的颜色,并下划线 |

**这个 `loop` 主题本身**在他们旁边`loopShapeVars`, (中文(简体) ), `loopShadows`, (中文(简体) ), `loopMotionVars`, (中文(简体) ), `loopTypeVars`:

-   **半径**数字 : `--loop-radius-control` (999px), (中文(简体) ), `--loop-radius-card` (20px), (中文(简体) ), `--loop-radius-bubble` (22页x), `--loop-radius-frame` (28px); 初级产品本身 `--borderRadius-small`, (中文(简体) ), `-medium`, (中文(简体) ), `-large` 改为圆形(10, 14, 20px).
-   **脸** 应用,大小为三而无其他: `--loop-face-large` (72px,一页), `--loop-face-medium` (40px,指头或卡),, `--loop-face-small` (20px,列表的一行).
-   **阴影**: 一个级别, `--loop-shadow-frame`. 在光线模式下,一地表浮起于柔软而低的阴影上;在暗色模式下,一地影显示得很少,在一地光线和更深的阴影上. 初级 `--shadow-resting-*` 财务报告和审定财务报表 `--shadow-floating-*` 抓同手,所以菜单或对话框会像帧一样浮出水面. `--loop-hairline` 是两个表面之间的线条(光线为墨水的7%,暗线为白色的10%).
-   **动议**:持续了三件事—— `--loop-motion-status` (情况变化), `--loop-motion-message` (信息到达), `--loop-motion-pane` (一个窗帘开口) - 和一放松, `--loop-motion-easing`。其他任何动作;组件荣誉 `prefers-reduced-motion` 自己来.
-   **类型**:一面相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相相相接相相接相相相相接相接相接相相接相相相相接相相相相相接相接相相相相相相相接相相相相相相相相`loopFontFamily`数字 : `"Inter Variable", "Inter Fallback", ui-sans-serif, system-ui, …`) (中文(简体) ). 2个重量,400和600(`loopFontWeights`;Primer的轻重为400个而中重为600个),并有5个尺寸,每个尺寸为一行高`loopTypeScale`,每行相乘为4px:2rem/1.25(显示,标题为大),1.25rem/1.4(标题为中,字幕为中),1rem/1.5(标题为小,体为大),0.875rem/1.4286(身体为中,主题为正体),0.75rem/1.333(体为小,标题为正体)——设定在Primer的短手上,大小和行高的标志上,由他持有 `loopType.test.ts`。标题设置更加紧凑,跟踪是一个符号组件: `--loop-tracking-display` (-0.02m), (中文(简体) ), `--loop-tracking-title` (-0.012毫米), `--loop-tracking-body` (0个).
-   **面相,从页面的本源**: 含有主题导入的页面 `@datalayer/primer-addons/style/loop-face.css` 一次 一次吗 它宣布 `Inter Variable` 从 `@fontsource-variable/inter` 右上方的可变文件,只有拉丁和拉丁, `font-display: swap` ——该页的捆绑者释放出它自己的资产,所以从该页的出处取出面相,从不从第三方取出;和 `Inter Fallback`,一个当地Arial(或Liberation Sans或Arimo,与它相匹配的)被引入Inter的量度—— `size-adjust: 107.4%`, (中文(简体) ), `ascent-override: 90.2%`, (中文(简体) ), `descent-override: 22.48%`, (中文(简体) ), `line-gap-override: 0%`中,下一个/font的 Inter 值,由 Capsize 计算 —— 因此, 文本在倒数后先画出, 当 Inter 到达时不移动 。 不导入的页面显示系统面相 .
-   **空间**:没有其自身的尺度——首级,分4和8级(`sx` 1到6是4,8,16,24,32,40px),外观的空气出自其所花之处:从舞台边缘放出一帧24px,在对话(标题,信息,作曲)内放出一帧16px,在工作平板上放出一圈24px,在两片药丸之间放出一束8px,并放出一条发线(发线)`--theme-hairline`) 二相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.
-   **舞台,点燃**数字 : `--theme-stage-gradient`从最上端的舞台锡到最下端的静态锡, 两者的口音——薄荷在 `loop` (每个主题设置,见 [主题口音](https://npmcn.com/package/%40datalayer/primer-addons/#readme-theme-accents)) (中文(简体) ).
-   **焦点环**数字 : `--focus-outlineColor`薄荷深处 `#0F6B4F` 以光线模式和中灰色 `#636363` 在黑暗模式下.

### 参考屏幕

上面的符文被用四个参考屏幕(LOOP T-01)一起绘制—— **谈话**, (中文(简体) ), **一个谈话 除了工作**, (中文(简体) ), **工人的活动** 财务报告和审定财务报表 **核准** ——在登记册的九个主题和两种模式中各有其分. 它们是从真正的聊天组件中构建的 `@datalayer/agent-runtimes`,这取决于这个包, 所以他们住在那里:作为故事(`src/stories/loop/LoopReference.stories.tsx`, (中文(简体) ), _循环/参考屏幕_),作为测试在Chrome(`npm run test:pictures` (一) 代理运行时间,T-16; `TESTING.md` 上面写着如何运行和如何接受变化)。 这里的代号更改显示为不同的图片:接受,或修正.

### 控制器,作为药丸

每个初级控制器都从一个符号上取出角, `--borderRadius-medium`,哪些牌和列表项目也取取——所以"控制单是药"不能用自定义属性说出. 因此,主题可能包括: **它自己的样式表**, (中文(简体) ), `ThemeStyles.css`相对 `:scope` (单位:千美元)`buildThemeStyles(light, dark, { css })`) (中文(简体) ). `loop` 是唯一有一个主题(`loopControlsCss`:按钮、文本输入、选择、分块控件、按钮组(其两端),切换开关和下划线标签为丸;多行文本区域保存 `--borderRadius-medium`,且菜单和上覆保留了卡片的半径. 选择者与Primer的类名的稳定前缀相匹配(`loopControlsSelectors`),每个测试从安装中读取 `@primer/react`,因此重命名一个失败的构建.

怎么样 `DatalayerThemeProvider` 应用:

-   它用它独特的元素来纪念它 `data-datalayer-theme-scope` 并注入一个 `<style data-datalayer-theme-stylesheet>` 将主题样式表包入文档头 `@scope (<its element>) to (<any other provider's element>)` ——所以规则停在了内部嵌入的提供商身上,一个自有主题的部件保持了它的外形`scopeThemeCss`, (中文(简体) ), `injectThemeStylesheet`) (中文(简体) ).
-   这个 **最外侧** 提供者拥有 Primer 的门户根 (`__primerPortalRoot__`,在其中绘制菜单、覆盖和对话框),并将样式表也瞄准它;一个被嵌入的提供者将门户根留下.
-   样式表在主题变化和提供者卸载时被去除;它被注入到布局效果中,所以第一种颜料已经在主题形状中了. 一个主题没有一个 没有得到任何注入.

`themeStylesheet.test.tsx` 测试每个这些.

### 干净的规矩

外观由八条规则保持,在这里写过一次,并应用于每条被审查的屏幕(LOOP T-17,Q-09)——一个打破了一条的屏幕被更改了,或者这个规则永远不能作为例外通过:

1.  **每个申请一个口音.** 其本身(`interface.accent`),每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每`themeAccentVars`; 从来没有一秒钟的呼声旁边。 成功,注意和危险是判决的色彩,只有判决的色彩.
2.  **表面没有梯度.** 相框,相克相克,相克相克相克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 一个梯度是框后起的舞台,被口音本身的两个线条所点燃(相接而来)`--theme-stage-gradient`),一个舞台可能同样平坦(`--theme-stage`) (中文(简体) ).
3.  **空间分开的地方没有边框 .** 空气第一;两地相会之处,有一条到发线(`--theme-hairline`, (中文(简体) ), `--loop-hairline`),从不设空隙和边框,从不划出一个框来环绕一个已设空隙的组.
4.  **无影出一等.** `--loop-shadow-frame` (单位:千美元)`--theme-shadow`:一个框架,一个菜单和一个对话框浮出水面;没有别的东西有它自己的影子.
5.  **两重.** 400和600个`loopFontWeights`),在5个大小的 `loopTypeScale` ——按名称输入 `sx` 也在这里 `loopTheme.fontWeights` 使初级 `light` 财务报告和审定财务报表 `normal` 这400, `semibold` 财务报告和审定财务报表 `bold` 六百块.
6.  **每个屏幕一个装满的按钮.** 重要的动作是口音中填充的药丸;其他的都安静地——概述,或隐形地活到徘徊.
7.  **控制是行图标 .** 八分相克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克.
8.  **身份是爱莫吉.** 一个应用程序,一个代理和一个字符都用他们的脸来显示(emoji或图出T-19),从不用行图标来显示.

动议遵从同一种精神: 三事一动——信息到来,状态变化,面板开口——在..... `--theme-motion-message`, (中文(简体) ), `-status` 财务报告和审定财务报表 `-pane`,没有别的了.

一个测试能进行什么,一个测试能进行: 没有梯度,但舞台的, 一个组件要问的主题的阴影, 两个重量(符号和 `sx`名称)和消息中的链接平面(`loopClean.test.ts`);大小(`loopType.test.ts`; 三个期限(`loopContrast.test.ts`; 药丸(`themeStylesheet.test.tsx`);在穿戴主题的产品中,屏幕的颜色也会被扫描出与这些规则相悖(登陆的) `studioVerdictColors.spec.ts`) (中文(简体) ). 其余的——对边框的空间,一个被填充的按钮——是审查员的空间,对准参考屏幕(T-16).

### 经测试的对比度

`src/theme/__tests__/loopContrast.test.ts` 当六口音中的任何一种都以两种方式出现时, 构建失败:

-   泡泡和被填药的文字(口音: `on` 口音上) 已经下 **4.5至1岁** (AA为正文);
-   舞台上或静静的锡、光和暗的墨水不足4.5至1;
-   焦点环在下面 **3至1岁** 背对一页或一粒口音的药丸——但在微妙的黑暗地表上,暗指环落出的一个地方,它持有2.7到1;
-   所填充的按钮——休息,徘徊,按下,或者口音的白文本在4.5到1以下,或者口音的填充和所填充的按钮停止为一色; 3;
-   次级文本在白色或近黑色上低于4.5至1;
-   作为文字的口音在4.5到1以下,在白色上,在近黑上,或在其黑暗的静锡上——但对于薄荷来说,其主题首先是薄荷,在淡锡上.

同样的考验使运动维持到三个持续时间和一个放松.

### 哪个主机可以覆盖

今天一个主机通过提供者覆盖: `baseStyles` 在主题属性上合并,所以可以设置重音(`themeAccentVars`),或任意 `--loop-*` 或者说 `--theme-*` 属性,对于元素和——对于最外层的提供者——门户根;并且它可能将自己的主题传递给 `themeStyles`,与 `buildThemeStyles`一个人在外观菜单中的选择(`useThemeStore`)是东道主的荣誉.

**尚未建立** (LOOP T-13):在嵌入式应用程序的网络组件内作为CSS变量与主机页面样式相隔离而运行的主题,其口音,相貌和模式是主机所覆盖的唯一事物. 在此之前,一个嵌入式应用程序作为任何反应树在下面 `DatalayerThemeProvider` ,而且主机页面本身的 CSS 不被保留.

## 开发

安装依赖关系 .

```bash
npm i
```

开始写故事书.

```bash
npm run storybook
```

开始游乐场.

```bash
npm dev
```

## 关于初级设计

-   设计系统 [https://primer.style (英语)](https://primer.style/)

## 关于初级线图标

-   图标 [https://primer.style/design/foundations/icons (英语)](https://primer.style/design/foundations/icons)

## 关于Primer 反应

-   GitHub 仓库 [https://github.com/primer/resact. 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/primer/react)
-   文档 [https://primer.style/反应](https://primer.style/react)
-   故事书 [https://primer.style/resact/storybook 页面存档备份,存于互联网档案馆](https://primer.style/react/storybook)

## 关于初级品牌

-   GitHub 仓库 [https://github.com/primer/brand 互联网档案馆的存檔,存档日期2013-10-21](https://github.com/primer/brand)
-   文档 [https://primer.style/brand (英语)](https://primer.style/brand)
-   故事书 [页:1](https://primer.style/brand/storybook)

## 释放

Primer Addons 发布于 [国家](https://www.npmjs.com/package/@datalayer/primer-addons)。 。 。 .

每个版本都带了LOOP盒子 [更改日志](https://npmcn.com/package/%40datalayer/primer-addons/CHANGELOG.md)。 。 。 .

## 常见问题

### 如何安装 @datalayer/primer-addons？

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

### @datalayer/primer-addons 支持 TypeScript 吗？

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

### @datalayer/primer-addons 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @datalayer/primer-addons 可以商用吗？

@datalayer/primer-addons 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @datalayer/primer-addons 的下载量有多少？

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

### @datalayer/primer-addons 还在维护吗？

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