# @ax-design/surface 中文文档

规范地址：https://npmcn.com/package/%40ax-design/surface/

版本：0\.4\.4
npm 元数据更新时间：2026-10-26T16:18:02.400Z
中文译文更新时间：2026-11-07T19:12:28.930Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ax-design/surface
原文对照：https://npmcn.com/package/%40ax-design/surface/?lang=original
项目主页：https://github.com/ax-design/surface#readme
源码仓库：https://github.com/ax-design/surface

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

- 包体积（解压后）：288 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-10-13T04:12:27.280Z
- 最新版本发布：2026-10-26T16:18:00.662Z
- 近 30 天下载量：3040（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

执行Axiom设计系统的Web组件:每个视觉层一个形状、一个倾斜和一个帧调度器.

## 安装

```sh
npm install @ax-design/surface
```

也可以使用：`pnpm add @ax-design/surface`、`yarn add @ax-design/surface`、`bun add @ax-design/surface`

## README

# ![Ax Surface](https://raw.githubusercontent.com/ax-design/surface/master/docs/logo.png)

Web 组件将 Axiom 设计系统的所有层组合在一起.

[![npm version](https://img.shields.io/npm/v/@ax-design/surface.svg)](https://www.npmjs.com/package/@ax-design/surface) [![CI Status](https://github.com/ax-design/surface/actions/workflows/ci.yml/badge.svg)](https://github.com/ax-design/surface/actions/workflows/ci.yml) ![MIT Licence](https://img.shields.io/badge/license-MIT-green.svg)

## 安装

```bash
// with npm
npm install @ax-design/surface

// with bun
bun add @ax-design/surface
```

并导入:

```javascript
import { register } from '@ax-design/surface';
register();
```

## 使用量

一个表面是Axiom设计系统每个视觉效果所借鉴的盒子. 它拥有整页的外形,倾斜和一帧调度器,并用分层来绘制内容. 为了给元素一个形状,把它包起来 `ax-surface` 并选择你需要的层次. 举个例子:

```html
<ax-surface layers="fill">
  <button class="my-button">Hello</button>
</ax-surface>
```

```css
ax-surface {
  --ax-radius: 12px;
  --ax-fill-color: white;
  --ax-border-color: #3b4252;
}
```

图层按您列出的顺序绘制,您的内容总是在顶部. `fill` 随此软件包而来,其他软件包会增加: `elevation` 从 `@ax-design/elevation` (一个沿着形状的阴影), `reveal` 从 `@ax-design/reveal-highlight` 财务报告和审定财务报表 `acrylic` 从 `@ax-design/acrylic`数字 :

```html
<ax-surface layers="elevation fill reveal">
  <button class="my-button">Hello</button>
</ax-surface>
```

想试试属性吗? 运行 `bun install && bun run demo` 在此寄存器中打开打印的页面。 它有一个游乐场,形状在材料3外形集和几块瓷砖后.

表面只在可见时工作,只在某事被改变后读取其样式,并降低页面开始下放帧时相距相距和相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相.

### 图像和其他内容的形状

添加数据 `clip` 属性和表面内容被切成外形,因此一幅图像或一幅视频会填充出任何形状的瓦片. 切口在变化时会跟随外形,在按住表面时会随内容倾斜:

```html
<ax-surface clip layers="reveal" style="--ax-radius: 24px">
  <img src="cover.jpg" alt="" style="display: block; width: 100%; height: 100%; object-fit: cover">
</ax-surface>
```

### 键盘焦点

添加数据 `focus` 地层和地表将Windows的焦点视觉画出在它的形状周围,而它或其中的一个元素具有键盘焦点(`:focus-visible`:一光一px环与外形相对并环绕有暗二px环. 与 `outline`环跟随形状的每一个角落和边缘 `clip` 属性不剪切它们.

```html
<ax-surface layers="fill reveal focus">
  <button class="my-button">Hello</button>
</ax-surface>
```

```css
/* The surface draws the ring now; keep the browser's own outline for the keyboard off. */
ax-surface .my-button:focus-visible { outline: none; }
```

环被画在元素外,所以有祖先 `overflow: hidden` 剪掉它们 就像剪掉一个大纲 改变他们与 `--ax-focus-ring-*` 属性.

### 无障碍优惠

Surface 遵循用户的显示偏好, 如 Windows 的效果 :

-   **强制颜色** (窗户高对比度, `forced-colors: active`: `fill` 层将填充变为 `Canvas` 边界进入 `CanvasText`,如浏览器有背景和边框,焦点环则取 `CanvasText` 财务报告和审定财务报表 `Canvas`. SVG和帆布画没有被浏览器所再涂色,所以每个图层都会自行处理.
-   **减少动议** (单位:千美元)`prefers-reduced-motion: reduce`:倾斜一时起起起姿势来取而代之,而不是放松入去. 表面仍然倾斜,因为当动画关闭时,Windows仍然播放被压的状态;只有过渡被跳过.
-   **透明度下降** (单位:千美元)`prefers-reduced-transparency: reduce`和 `setAlwaysUseFallback(true)`:有固态回落效果,如丙烯和显出,用之. 页面无法检测电池保护器或慢设备,其他时候Windows倒回,所以调用 `setAlwaysUseFallback` 当你更清楚:

```javascript
import { setAlwaysUseFallback } from '@ax-design/surface';

setAlwaysUseFallback(true);
```

-   **高对比度** (单位:千美元)`prefers-contrast: more`,例如macOS"增加对比":表面本身不会改变,因为Windows没有这样的设置. 提高边界和焦点的对比度:

```css
@media (prefers-contrast: more) {
  ax-surface {
    --ax-border-color: rgb(0, 0, 0);
    --ax-focus-ring-color: rgb(0, 0, 0);
    --ax-focus-ring-secondary-color: rgb(255, 255, 255);
  }
}
```

### 选择和拖曳

表面是一个控制,所以按下或拖动它不会选择它的文本,浏览器也不会将其中的链接和图像拖走(也不会显示iOS的长压呼号). 给它一个元素 `draggable="true"` 以浏览器的拖放来拖动它; 设置 `user-select: text` 使其文本可以再次选择.

### 按代码

`press()` 对键盘活化:倾斜会向点倾斜,层层会看到被压的指针。 没有争论,或与 `'center'`,它按排版框的中心(`pointerType` 实值 `'keyboard'`; 与 `{ x, y }`,在倾斜前从地表左上方按下px中的局部坐标,按下该点(`'api'`) (中文(简体) ). 前进中的指针媒体胜出.

`release()` 结束媒体:倾斜向后,层层可见 `pressed: false`,保留了点,以便释放效果能够发挥。 它还在指针上起之前结束一个指针按键,用于取出手势的容器(一瓦拖放). 这么早释放之后, `pressTakenOver` 实值 `true` 直到下一次按下开始,这样拖动后点击即可被吞噬.

`pressRemaining()` 返回毫秒,直到媒体反馈完成:层中最长的' `pressRemaining(now)` 和其余的倾斜扭矩(0和减速运动)。 在画出一个框架后阅读

```javascript
surface.press();
requestAnimationFrame(() => setTimeout(activate, surface.pressRemaining()));
```

### 从代码移动

`motion(state)` 以3D来移动表面并淡出它 对于一个帧:用帧的状态调用您动画的每个帧 `null` 结束它. `rotateX` 编号 : `rotateY` (分数), `translateZ` (px)和 (px) (中文(简体) ) `perspective` (px, 默认为1000) 翻转表面 `originX` 编号 : `originY` (当地px,默认其中心;出处可能位于地表外,如一行瓦片绕出其组的左边缘),上方为其压倒. `scale` (违约1)和 `x` 编号 : `y` (px) 扩展其来源, 并将其移出视角外, 如图片: 元素转出边缘时, 无论移动在哪里, 都会保持一行 . `opacity` (0到1)会消去.

```javascript
const start = performance.now();
const frame = (now) => {
  const t = Math.min(1, (now - start) / 600);
  surface.motion({ rotateY: 90 * (1 - t), originX: -surface.offsetLeft, opacity: t });
  if (t < 1) requestAnimationFrame(frame);
  else surface.motion(null);
};
requestAnimationFrame(frame);
```

没有书写在地层的祖先身上:地层自己画出运动,所以丙烯保持了它的背景(a `opacity` 它成为每个浏览器的背景根。 在Firefox中,没有3D变换可能坐落在丙烯上方,地层在3D运动时会用平面容器绘制出所预测的形状,内容被隐藏,一旦运动结束会回落.

### 缓解

`windowsEasing(id)` 提供Windows 8和8.1动画主题作为CSS的计时功能(`windowsEasing(54)` 启动屏幕要进来了, `'cubic-bezier(0, 0.5, 0.5, 1)'`(三); `WINDOWS_EASINGS` 持有全部20。 对于已脚本的动画 `requestAnimationFrame`, (中文(简体) ), `parseEasing(value)` 读取 CSS 计时函数(关键词和 `cubic-bezier()`和 `bezierAt(curve, t)` 进展情况 `t`。 。 。 .

### 监视样式变化

由类、属性引起的表面通知样式变化, `:hover`, (中文(简体) ), `:active`, (中文(简体) ), `:focus`,窗体状态,媒体查询,样式表和您自己的过渡。 如果您的样式取决于其它东西(例如另一个组件阴影根中的元素),则使用 `observe="precise"`数字 :

```html
<ax-surface layers="fill" observe="precise">...</ax-surface>
```

或打电话 `element.refresh()` (一个地表)或 `refreshAll()` (每个表面) 在变化之后.

### 表面内表面

倾斜地表内的地表( 例如) `ax-reveal` 内部 `ax-pressure`)跟随倾斜:你的指针通过上方的每个倾斜被映射出,所以其效果停留在你的指针下.

## 样式控制

表面组件使用自定义属性来管理其形状. 在下面的名字中, `{corner}` 这是其中之一 `top-left`, (中文(简体) ), `top-right`, (中文(简体) ), `bottom-right`, (中文(简体) ), `bottom-left`,以及 `{side}` 这是其中之一 `top`, (中文(简体) ), `right`, (中文(简体) ), `bottom`, (中文(简体) ), `left`。 。 。 .

形状属性不继承, 设置在 `ax-surface` 元素本身.

### \--轴射线

**类型 :** `<length-percentage>`

**默认 :** `0px`

**说明 :** 每个角落的半径。 百分比是相对较短的一面。 喜欢 `border-radius`,不相适应的弧度缩小.

### \--ax-{corner}-radius (韩语)

**类型 :** `<length-percentage>`

**默认 :** `-1px`

**说明 :** 一个角的半径。 负值表示“ 使用 `--ax-radius`" ..

### \-- 轴角形状

**类型 :** `round | bevel | scoop | notch`

**默认 :** `round`

**说明 :** 每个角的形状, 具有同样的含义 CSS `corner-shape` 关键词.

### \--ax- corner- {corner} - 形状

**类型 :** `round | bevel | scoop | notch | auto`

**默认 :** `auto`

**说明 :** 一个角的形状. `auto` 表示"使用" `--ax-corner-shape`" ..

### \- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

**类型 :** `<length>`· ; `<length> | auto`

**默认 :** `0px`· ; `auto`

**说明 :** 绕入一个 `bevel`, (中文(简体) ), `scoop` 或者说 `notch` 角相会相会. 每个角默认为 `auto`,表示“使用” `--ax-corner-shoulder-radius`" .. `round` 转角忽略它。 一般的地产设置每个角落 除非一个角落设置自己的角落。 与 `--ax-radius: 50%` 财务报告和审定财务报表 `scoop`相邻的角在两侧中间相接相接,而肩部半径将这些点绕入柔和的恒星;非常大的数值将其变成一圈.

### \-----------------------------------------------------------------

**类型 :** `<length-percentage>`

**默认 :** `0px`

**说明 :** 将一角点移入形状,百分比与宽度相对(`x`)或高(`y`) (中文(简体) ). 左上和右下角移动 `x` 你得到一个平行图。 负值从框中移出一角.

### \----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -----------------------

**说明 :** 每一边的特征都同时出现. 违约后的每个侧式财产 `auto`,意思是"使用同名的一般财产",所以 `--ax-edge-depth` 套装 `--ax-edge-top-depth`, (中文(简体) ), `--ax-edge-right-depth` 诸如此类,除非一方自行设置。 这些属性的过渡和动画将四面移动.

```css
.cookie {
  --ax-radius: 30%;
  --ax-edge-kind: cusp;
  --ax-edge-depth: -6px;
  --ax-edge-span: 100%;
  --ax-edge-tip-radius: 20px;
  /* The top side goes deeper than the others. */
  --ax-edge-top-depth: -12px;
}
```

侧向顺时针运行(参见 `--ax-edge-{side}-at`因此,一个 `--ax-edge-at` 远离了50%的特性,每个特征都以同样的方式围绕形状:结果有自转对称,而不是镜像对称.

### \--ax-dece-{side}-kind 类型

**类型 :** `flat | arc | rect | triangle | trapezoid | cusp | auto`

**默认 :** `auto`

**说明 :** 一边的特色. `auto` 表示"使用" `--ax-edge-kind`" .. `arc` 是圆形凸起还是圆形, `rect`, (中文(简体) ), `triangle` 财务报告和审定财务报表 `trapezoid` 他们是直的. `cusp` 是两道弧,在两端平稳地离开侧面,并在一分处相会:向内会捏出侧面(材料包的腰,花果的空隙),向外会形成一尖拱. 它不需要肩膀半径 `tip-radius` 环绕点.

### \--ax-edge-{side} -- deep

**类型 :** `<length> | auto`

**默认 :** `auto`

**说明 :** 特征走多远,正值出出外形,负值入外. `auto` 表示"使用" `--ax-edge-depth`" ..

### \--ax-dese-{side} - span (双向)

**类型 :** `<length-percentage> | auto`

**默认 :** `auto`

**说明 :** 沿边地物的宽度,百分比是相对于侧地的长度. `auto` 表示"使用" `--ax-edge-span`" ..

### \--ax-edge-{side} -at (中文(简体) )

**类型 :** `<length-percentage> | auto`

**默认 :** `auto`

**说明 :** 地物的中间沿边坐. 侧向顺时针运行 : `top` 从左到右, `right` 从上到下, `bottom` 从右到左 `left` 从下而上. 这么说吧 `--ax-edge-bottom-at: 20%` 靠近右下角处. `auto` 表示"使用" `--ax-edge-at`" ..

### \--ax-dece-{side}-ratio (韩语)

**类型 :** `<number> | auto`

**默认 :** `auto`

**说明 :** 对于 `trapezoid` 只有远端的宽度和底部的宽度. `1` 给一个矩形, `0` 一个三角形, 动画它变形到另一个. `auto` 表示"使用" `--ax-edge-ratio`" ..

### \--ax-edge-{side}-tip-radius,-ax-edge-{side}-肩-radius (英语)

**类型 :** `<length> | auto`

**默认 :** `auto`

**说明 :** 绕出最远的角(尖)和特征与侧相会的角(肩). `auto` 表示"使用" `--ax-edge-tip-radius`"或"使用 `--ax-edge-shoulder-radius`" ..

### \--ax- 边界宽度

**类型 :** `<length>`

**默认 :** `1px`

**说明 :** 每边边界的宽度. 表面在屏幕上保持同样厚的边界,同时倾斜.

### \--ax-边境-{侧}-width

**类型 :** `<length>`

**默认 :** `-1px`

**说明 :** 一侧的边界宽度。 负值表示“ 使用 `--ax-border-width`" ..

### \--x-tilt-mode (英语)

**类型 :** `off | absolute | relative`

**默认 :** `off`

**说明 :** 把表面倾斜到按下点. `absolute` 按下边的下沉 `--ax-tilt-depth`, (中文(简体) ), `relative` 倾斜它 `--ax-tilt-factor` 学位.

### \-- 轴- 斜拉深

**类型 :** `<length>`

**默认 :** `1px`

**说明 :** 当按下地表边缘时,一侧下沉的深度.

### \-

**类型 :** `<number>`

**默认 :** `2`

**说明 :** 以度为单位的角度 `relative` 模式.

### \--ax-tilt-zoom (英语)

**类型 :** `<length>`

**默认 :** `0.8px`

**说明 :** 当你按下中心时整个地表的倒下程度.

### \-- 轴斜视

**类型 :** `<length>`

**默认 :** `25px`

**说明 :** 倾斜的视角,看看 [此教程](https://www.w3schools.com/cssref/css3_pr_perspective.asp)。 。 。 .

### \- -- -- -- 斜向

**类型 :** `normal | inverted`

**默认 :** `normal`

**说明 :** `inverted` 抬起被压住的一面,而不是沉入一地.

## Schema 组

上面的属性分为三组,一个仅需要其中一组的组件并不需要 余取取来. 每个组被导出为捆:

```javascript
import { SHAPE } from '@ax-design/surface';
// or, without pulling the element, its scheduler and its layers into the build:
import { SHAPE } from '@ax-design/surface/schema';
```

-   `SHAPE.read` - 形状的属性,在每张画上读取。 这包括一般 属性( e)`--ax-edge-span` 将每个侧面或角一并设置: 每边或每角财产违约 `auto` 而表面读取一般值 当它做.
-   `BORDER.read`, (中文(简体) ), `TILT.read` - 边界和倾斜属性 他们没有将军 对应单位.

`CORE_SCHEMA` 是三个 `read` 按此顺序列出的消费者和层次,未作改动 想要整个合同.

### \-- 轴填色

**类型 :** `<color>`

**默认 :** `transparent`

**说明 :** 给 `fill` 层,形状内的颜色.

### \-- 轴- 边框- 颜色

**类型 :** `<color>`

**默认 :** `transparent`

**说明 :** 给 `fill` 层,边框的颜色.

### \--ax-焦点-环-width, --ax-焦点-环-二级 width

**类型 :** `<length>`

**默认 :** `2px`, (中文(简体) ), `1px`

**说明 :** 给 `focus` 地层,外(主)环和内(次)环的宽度.

### \--ax-焦点-环相抵

**类型 :** `<length>`

**默认 :** `0px`

**说明 :** 给 `focus` 层,外形与内环相隔.

### \--ax-焦点-环-颜色, --ax-焦点-次要-颜色

**类型 :** `<color>`

**默认 :** `black`, (中文(简体) ), `rgba(255, 255, 255, 0.6)`

**说明 :** 给 `focus` 层,外环和内环的颜色。 设定它们为暗主题; 在强制颜色模式下 `CanvasText` 财务报告和审定财务报表 `Canvas`。 。 。 .

## 写入一层

一层是表面画出一样东西的物体. 注册名称,然后在 `layers` 属性 :

```javascript
import { registerLayer } from '@ax-design/surface';

registerLayer('outline', () => ({
  attach(container) { /* create your canvas or SVG in container */ },
  detach() {},
  write(frame) {
    // frame.shape.outline, frame.pointer, frame.values, frame.changed ...
    return false; // true asks for another frame
  },
}));
```

图层画入漆框内(`frame.paint`:元素的盒子,被成长成适合外形的特征. 如果你的地层画出外形(一发光,一发阴影),告诉地表有多远 `overflow`,在px中,对每一边或作为 `[top, right, bottom, left]`数字 :

```javascript
registerLayer('glow', () => ({
  overflow(values, width, height) {
    return 16;
  },
  // ...
}));
```

一个大于元素的漆盒会与其相邻相重叠,而浏览器随后可能不得不将它们相分解. 唯问所取所取.

`frame.appearance` 持有用户的首选项( q)`forcedColors`, (中文(简体) ), `reducedTransparency`, (中文(简体) ), `reducedMotion`, (中文(简体) ), `alwaysUseFallback`),以及 `frame.changed.appearance` 设置在其中之一改变后的第一个框架上,即使没有样式值。 用 CSS 系统颜色以强制颜色模式绘制, 或根本不使用: 浏览器不重新显示 SVG 颜料或画布像素 . `useFallback(frame.appearance)` 说明是否应该使用有固体倒计时效应。 在一层外, `appearance()` 返回同一状态.

`frame.opacity` 是表面运动的不透明性: 应用到自己的画作( 画布或SVG 的不透明性) , 绝不应用到祖先 . `frame.tilt` 是媒体倾斜和运动在一起。 何时 `frame.projected` 真实( 三维运动时的Firefox),您的容器不带变换: 绘制形状通过 `frame.tilt` 自己,与 `projectContour(frame.shape.outline, frame.tilt)` 联 合 国 `@ax-design/shape` 财务报告和审定财务报表 `apply(frame.tilt, p)` 要点 `frame.ringInner()`· ; `frame.paint` 然后成长为保持预测形状. `frame.changed.motion` 被设定在动议改变的构架上.

`frame.pointer.pressed` 也是真实的,而 `press()` 保持表面,与 `pointerType` `'keyboard'` 或者说 `'api'`。按下需要时间的反馈,例如波浪,可以说明它还能玩多久 `pressRemaining(now)`,毫秒从 `now` (单位:千美元)`performance.now()`直到它完成为止。 地表的地层最长 没有方法的图层计为已完成 .

在地表倾斜的同时,会将倾斜放入每层容器上. 如果您的图层使用 `backdrop-filter`设置 `tiltsItself: true` 并适用 `frame.tiltTransform` 至您自己的元素, 围绕元素盒的中心: 内 `position: sticky`Firefox在变了的祖先 错误的背景之下 做了个背景过滤器.

## 非表面代码的框架

排程器是整页的,任何对象都使用 `read`, (中文(简体) ), `compute`, (中文(简体) ), `write` 财务报告和审定财务报表 `priority` 可以为客户端 : `services().scheduler.request(client)` 它在下一个框架中运行 每一个表面,先读,然后读数学,然后写, 所以没有客户端阅读 后另一个写。 客户又自问了 `write` 当它移动时,而当它处于休止状态时,它不会动,所以一个闲置的页面会要求没有任何框架. `PRIORITY_PRESSED`, (中文(简体) ), `PRIORITY_POINTER` 财务报告和审定财务报表 `PRIORITY_IDLE` 是表面使用的优先级;它们之间的任何数字都是分数.

```ts
import { PRIORITY_IDLE, services } from '@ax-design/surface';
import type { FrameClient } from '@ax-design/surface';

const client: FrameClient = {
    read: () => { /* measure */ },
    compute: () => { /* math */ },
    write: () => { /* change the DOM */ },
    priority: () => PRIORITY_IDLE,
};
services().scheduler.request(client);
```

一个在自己的盒子内有许多表面的组件可以让页面监视那个盒子的能见度: 覆盖 `visibilityTarget()` 以返回元素。 已知暂时无所事事的地表可以被暂停(`surface.paused = true`:然后它不运行框并读取任何风格,作为景点外的一个,直到它被放回 `false`。 。 。 .

## 写入元素

子类 `AxSurface` 使元素具有自己的财产名称. `layerNames_()` 选取地层, `shapeFor()` 财务报告和审定财务报表 `borderWidthsFor()` 读取形状 `tiltParams()` 财务报告和审定财务报表 `tiltPerspective()` 读取倾斜 :

```javascript
import { AxSurface } from '@ax-design/surface';

class MyCard extends AxSurface {
  static schemaKey = 'my-card';
  static extraSchema = [{ name: '--my-card-lean', syntax: { type: 'number' }, initial: '3', inherits: true }];

  layerNames_() { return ['fill']; }

  tiltParams(values, width, height, x, y) {
    const lean = values.number('--my-card-lean');
    return { width, height, perspective: 400, rotateX: (0.5 - y / height) * lean, rotateY: (x / width - 0.5) * lean, translateZ: 0 };
  }
}
customElements.define('my-card', MyCard);
```

表面本身的风格是每个表面都采用的一种构造的平面. 以自己的返回表来样式其阴影根的类 `static extraSheets()`,每个课都问过一次,而Surface's之后的被单(你的一条规则是比Surface的同一种特殊性). 不要在每个实例中添加样式元素: 一页有上百个表面将解析并匹配每页一个. (一个没有可构建的样式表的浏览器,如16.4前的Safari没有被采纳的样式表,其表面得到Surface的样式元素;然后将您添加到实例中

## 浏览器支持

几个软件包可以各自捆绑自己的Surface复制件(即: `build/` 文档 `@ax-design/reveal-highlight` 财务报告和审定财务报表 `@ax-design/acrylic` 他们分享自己的图层和排程器.

先装入的复制件 `<ax-surface>`. 较新的属性,例如一般 `--ax-edge-*` 属性,只有在该副本知道它们时才能工作,所以将副本保留在同一个版本的页面上.

Surface作品于自2018年起发行的浏览器(Chrome 70,Firefox 63,Safari 12. 这需要 `ResizeObserver`, (中文(简体) ), `IntersectionObserver` 和指针事件,并在控制台上告诉你,当其中之一缺失时,你就可以装入多填充器.

## 更改日志

见 [变动情况](https://npmcn.com/package/%40ax-design/surface/CHANGELOG.md)。 。 。 .

## 常见问题

### @ax-design/surface 是什么？

执行Axiom设计系统的Web组件:每个视觉层一个形状、一个倾斜和一个帧调度器\.

### 如何安装 @ax-design/surface？

在项目目录运行 npm install @ax-design/surface，或使用 pnpm add / yarn add / bun add。

### @ax-design/surface 支持 TypeScript 吗？

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

### @ax-design/surface 支持 ESM 还是 CommonJS？

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

### @ax-design/surface 可以商用吗？

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

### @ax-design/surface 的下载量有多少？

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

### @ax-design/surface 还在维护吗？

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