Web 组件将 Axiom 设计系统的所有层组合在一起.
安装
// with npm
npm install @ax-design/surface
// with bun
bun add @ax-design/surface
并导入:
import { register } from '@ax-design/surface';
register();
使用量
一个表面是Axiom设计系统每个视觉效果所借鉴的盒子. 它拥有整页的外形,倾斜和一帧调度器,并用分层来绘制内容.
为了给元素一个形状,把它包起来 ax-surface 并选择你需要的层次.
举个例子:
<ax-surface layers="fill">
<button class="my-button">Hello</button>
</ax-surface>
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数字 :
<ax-surface layers="elevation fill reveal">
<button class="my-button">Hello</button>
</ax-surface>
想试试属性吗? 运行 bun install && bun run demo 在此寄存器中打开打印的页面。 它有一个游乐场,形状在材料3外形集和几块瓷砖后.
表面只在可见时工作,只在某事被改变后读取其样式,并降低页面开始下放帧时相距相距和相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相.
图像和其他内容的形状
添加数据 clip 属性和表面内容被切成外形,因此一幅图像或一幅视频会填充出任何形状的瓦片. 切口在变化时会跟随外形,在按住表面时会随内容倾斜:
<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 属性不剪切它们.
<ax-surface layers="fill reveal focus">
<button class="my-button">Hello</button>
</ax-surface>
/* 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当你更清楚:
import { setAlwaysUseFallback } from '@ax-design/surface';
setAlwaysUseFallback(true);
- 高对比度 (单位:千美元)
prefers-contrast: more,例如macOS"增加对比":表面本身不会改变,因为Windows没有这样的设置. 提高边界和焦点的对比度:
@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和减速运动)。 在画出一个框架后阅读
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)会消去.
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"数字 :
<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 诸如此类,除非一方自行设置。 这些属性的过渡和动画将四面移动.
.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
说明 : 倾斜的视角,看看 此教程。 。 。 .
- -- -- -- 斜向
类型 : normal | inverted
默认 : normal
说明 : inverted 抬起被压住的一面,而不是沉入一地.
Schema 组
上面的属性分为三组,一个仅需要其中一组的组件并不需要 余取取来. 每个组被导出为捆:
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 属性 :
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]数字 :
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: stickyFirefox在变了的祖先 错误的背景之下 做了个背景过滤器.
非表面代码的框架
排程器是整页的,任何对象都使用 read, (中文(简体) ), compute, (中文(简体) ), write 财务报告和审定财务报表 priority 可以为客户端 : services().scheduler.request(client) 它在下一个框架中运行 每一个表面,先读,然后读数学,然后写, 所以没有客户端阅读 后另一个写。 客户又自问了 write 当它移动时,而当它处于休止状态时,它不会动,所以一个闲置的页面会要求没有任何框架. PRIORITY_PRESSED, (中文(简体) ), PRIORITY_POINTER 财务报告和审定财务报表 PRIORITY_IDLE 是表面使用的优先级;它们之间的任何数字都是分数.
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() 读取倾斜 :
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 和指针事件,并在控制台上告诉你,当其中之一缺失时,你就可以装入多填充器.
更改日志
见 变动情况。 。 。 .