@ dedesign.estate/dees-dometools (英语)

浏览器-侧式TypeScript用于拖曳 DOM 工作的功能,应答风格,主题处理,滚动,元数据设置,以及基于Lit的网络组件.

它给你一个单通式 DomTools 运行时加上若干重点出口,用于CSS断点、基元构型和低水平集成 design.estate 财务报告和审定财务报表 push.rocks 软件包.

问题报告和安全

关于报告错误、问题或安全弱点,请访问 社区. fos.global/这是所有问题报告的中央社区中心。 签署和遵守我们缴款协议并经过身份验证的开发者也可获得 代码.fos.global/ 账户直接提交 Pull 请求.

安装

pnpm add @design.estate/dees-domtools

内容包括

• DomTools 用于一次性应用靴和共享浏览器服务
• ThemeManager (后面的班级) domtools.themeManager) 及其定义 TThemePreference 类型,用于遵循系统的亮度/暗度主题,直到读者选择一个
• breakpoints 用于取景口和集装箱取水的Lit CSS的助手
• css.cssGridColumns() 用于简单的网格模板生成
• elementBasic lit 基础样式和一次性全球 CSS 设置的助手
• TypedRequest 从 @api.global/typedrequest 第9条
• plugins 直接进入内部使用的一揽子生态系统

这个 plugins 导出时保留常用下游命名空间,包括 plugins.smartstate, (中文(简体) ), plugins.smartpromise (延迟和 delayFor编号 :Timeout, (中文(简体) ), plugins.smartrouter, (中文(简体) ), plugins.smartrx, (中文(简体) ), plugins.smarturl,以及 plugins.typedrequest。 。 。 . plugins.typedrequest 财务报告和审定财务报表 convenience.typedrequest 为: @api.global/typedrequest 9; 将自己的打出请求路由器或目标连接到 deesComms 必须使用键入请求 9 .

快速启动

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();
await domtools.domReady.promise;

console.log(domtools.elements.headElement);
console.log(domtools.elements.bodyElement);

setupDomTools() 这是安全的,反复打电话。 默认情况下,它返回一个共享的全球实例并避免重复初始化工作.

如果您需要单独实例进行测试或使用时间短, 请通过 ignoreGlobal: true。孤立的情况也一样 domToolsReady 财务报告和审定财务报表 domReady 作为共享单子的生命周期.

DomTools 生命周期

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools({
  ignoreGlobal: false,
});

await domtools.domToolsReady.promise;
await domtools.domReady.promise;

setupDomTools() 一旦实例初始化并安装了其准备状态的听众,即可解决. domReady 以后解决,一次 document.head 财务报告和审定财务报表 document.body 备有.

主要实例属性 :

• elements.headElement 财务报告和审定财务报表 elements.bodyElement
• router 从 @push.rocks/smartrouter
• websetup 从 @push.rocks/websetup
• smartstate 财务报告和审定财务报表 domToolsStatePart
• themeManager
• scroller
• keyboard 之后 domReady
• deesComms页:1 @design.estate/dees-comms 2个实例
• convenience.typedrequest, (中文(简体) ), convenience.smartjson, (中文(简体) ), convenience.smartpromise, (中文(简体) ), convenience.smarturl

如果您需要同步创建的全局实例, 请使用 DomTools.getGlobalDomToolsSync() 启动完成后.

清理

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools({
  ignoreGlobal: true,
});

// ...use the instance

domtools.dispose();

dispose() 删除其拥有的收听器、 DOM 资源和所采纳的样式表 DomTools 实例中,并保留样式表所采纳的其他代码。 对于共享的全球用法,您通常在页面的寿命期间保持单子活性,但处置对于测试和有意短命的孤立实例是有用的.

DOM、CSS和外部资源

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();

await domtools.setGlobalStyles(`
  body {
    margin: 0;
    font-family: Inter, sans-serif;
  }
`);

await domtools.setExternalCss(
  'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap'
);

await domtools.setExternalScript('https://cdn.example.com/some-script.js');

setGlobalStyles() 采用中央支助系统 document.adoptedStyleSheets 作为构建的样式表而不是添加 <style> 因此,它适用于一项内容-安全政策 style-src 没有 'unsafe-inline',例如 style-src 'self'。每张被收养的表格之后 <style> 财务报告和审定财务报表 <link> 文档的页,因此其规则比文档规则具有同等特殊性,构造的页会下降 @import 规则. setExternalCss() 添加a <link rel="stylesheet">,当策略允许样式表的出处时,它允许.

页面元数据和外观:

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();

await domtools.setWebsiteInfo({
  metaObject: {
    title: 'Example App',
    description: 'A browser app bootstrapped with DomTools',
  },
  faviconUrl: '/favicon.ico',
});

主题管理

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();
const { themeManager } = domtools;

themeManager.themeObservable.subscribe((isBright) => {
  console.log('bright mode?', isBright);
});

themeManager.goDark();
themeManager.goBright();
themeManager.toggleDarkBright();

await themeManager.enableAutomaticGlobalThemeChange();

主题管理器起始于 prefers-color-scheme 并通过 RxJS 发布更新 ReplaySubject<boolean>。 。 。 .

主题偏好

一个切换主题设定了读者的偏好而不是当前的主题:

themeManager.preference; // 'system' | 'bright' | 'dark' (TThemePreference)
themeManager.setPreference(themeManager.goBrightBoolean ? 'dark' : 'bright'); // true when kept
themeManager.setPreference('system'); // follow prefers-color-scheme again

'system' 如下 prefers-color-scheme· ; 'bright' 财务报告和审定财务报表 'dark' 在系统方案改变时保留这个主题。 选择的偏好保留在 localStorage 下级 ThemeManager.preferenceStorageKey (单位:千美元)dees-domtools:theme-preference,每个浏览器和来源; 'system' 删除密钥),并在主题管理器第一次放出前被读取,因此在其中开始重载,而不首先显示系统主题. 另一个标签的取号通过 storage 活动. setPreference() 返回时 false 当浏览器拒绝页面存储时: 选择仅保留此页面, 并投放一个值为否 TThemePreference。未知的存储值计数为不取. goBright(), (中文(简体) ), goDark() 财务报告和审定财务报表 toggleDarkBright() 设置当前的主题, 并且不要偏好 .

切换显示偏好, 而不仅仅是主题, 订阅 stateObservable页:1 ReplaySubject<IThemeState> 重放当前状态,并在首选的每次更改、系统的颜色方案或主题上发布,同样当主题停留时(从系统已经显示的主题中选择,系统在选择时改变,另一个标签选择):

themeManager.stateObservable.subscribe(({ preference, systemBright, goBright }) => {
  // e.g. offer "follow the system" while a pick holds the theme the system shows
});
themeManager.systemBright; // the system's colour scheme is light, as prefers-color-scheme last reported it

这页 DomTools 是一个实例 globalThis 这个软件包的每个副本都共享,所以是复制件创建了它 ThemeManager 服务页面: 捆绑的每份副本必须是版本 setPreference() 来依靠它.

enableAutomaticGlobalThemeChange() 等待时间 domReady,所以它是安全的打电话之前 document.body 已存在.

键盘快捷键

键盘助手创建于 document.body 存在, 因此等待 domReady 在使用它之前.

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();
await domtools.domReady.promise;

const keyboard = domtools.keyboard!;
const { keyEnum } = keyboard;

keyboard.on([keyEnum.Ctrl, keyEnum.S]).subscribe(() => {
  console.log('save triggered');
});

keyboard.triggerKeyPress([keyEnum.Ctrl, keyEnum.S]);

滚动

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();
const { scroller } = domtools;

scroller.onScroll(() => {
  console.log('scroll event');
});

await scroller.enableLenisScroll({
  disableOnNativeSmoothScroll: true,
});

const section = document.querySelector('#details') as HTMLElement;
await scroller.toElement(section, { duration: 600 });

滚动器默认使用本土滚动收听器,启用时切换到Lenis.

响应式 CSS 助手

breakpoints 是为Lit CSS和船舶设计的,既有预设的断点,也有下级的帮助.

import { breakpoints } from '@design.estate/dees-domtools';
import { css } from 'lit';

const styles = css`
  :host {
    display: block;
    padding: 24px;
  }

  ${breakpoints.cssForTablet(css`
    :host {
      padding: 16px;
    }
  `)}

  ${breakpoints.cssForPhone(css`
    :host {
      padding: 10px;
    }
  `)}
`;

可用值 :

• breakpoints.desktop => 1600
• breakpoints.notebook => 1240
• breakpoints.tablet => 1024
• breakpoints.phablet => 600
• breakpoints.phone => 400

可用的助手 :

• cssForDesktop()
• cssForNotebook()
• cssForTablet()
• cssForPhablet()
• cssForPhone()
• cssForViewport()
• cssForContainer()
• cssForConstraint()
• cssForConstraintContainer()
• containerContextStyles()

查看端口帮助器同时发送 @media 财务报告和审定财务报表 @container wccToolsViewport 规则。 集装箱助手只瞄准一个叫CSS的集装箱.

CSS 设备

import { css } from '@design.estate/dees-domtools';

const columns = css.cssGridColumns(3, 24);

console.log(columns);

此返回一个可准备插入 grid-template-columns 绳子.

Lit 元素设置

import { elementBasic } from '@design.estate/dees-domtools';
import { LitElement, html } from 'lit';

class DemoElement extends LitElement {
  static styles = [elementBasic.staticStyles];

  async connectedCallback() {
    super.connectedCallback();
    await elementBasic.setup(this);
  }

  render() {
    return html`<p>Hello DOM tools</p>`;
  }
}

elementBasic.staticStyles 是组件的基准样式表,以及 elementBasic.styles 使元素默认为 <style> 模板中的元素。 每一个元素的组件的阴影树得到 box-sizing: border-box,每个内置元素(HTML, SVG, MathML)会逐渐消失 background 财务报告和审定财务报表 color 超过0.1秒。 淡出从未到达组件中嵌入自定义元素的宿主:该宿主会保留自已的样式所声明的过渡,因此一个被嵌入的组件仍能使宿主动起来,例如侧边栏会崩溃其宽度. 默认带有零特异性,因此组件的任何规则都会凌驾于它们之上.

elementBasic.styles 已贬值:内含 <style> 元素被一个内容-安全政策所屏蔽 style-src 没有 'unsafe-inline'启用 elementBasic.staticStyles,它作为已构建的样式表点出.

elementBasic.setup() 执行共享 DomTools 设置并采用软件包的全球工作表一次:基础 body 规则margin: 0,系统字体堆栈, box-sizing: border-box),然后是隐藏文档滚动条的工作表(setGlobalStyles(css, { hidesScrollbars: true })) (中文(简体) ). 全球表单在文档的每张表后出现,所以具有同等的特殊性 body 规则 margin, (中文(简体) ), font-family, (中文(简体) ), box-sizing 或者说 scrollbar-width,或一个 ::-webkit-scrollbar 规则,a <style> 或者说 <link> 放置在体内或后加,或之前通过的单子中 elementBasic.setup(),使其丧失; 给予这种规则更高的具体性,例如: html body。 。 。 .

滚动条默认隐藏. 在长的文档上,滚动条是读者唯一的位置指示器,所以这样的一页显示:

import { DomTools, elementBasic } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();
domtools.setScrollbarsHidden(false);
await elementBasic.setup();

选择权在于 DomTools 例如,它也是在生产之前 elementBasic.setup()因此滚动条从不先被隐藏; setScrollbarsHidden(true) 又藏起来 domtools.scrollbarsHidden 阅读选择。 组件阴影树内的滚动条保持隐藏 elementBasic.staticStyles。 。 。 .

这页 DomTools 是一个实例 globalThis 此软件包的每个副本共享, 所以 setScrollbarsHidden() 仅当创建它的副本是5.3或更晚时才存在,而且它只有在5.3或更晚时才切换任何东西 elementBasic.setup() 先跑的,我们先跑 旧的 setup() 隐藏在基底板内,没有关闭,或者,在更古老的例子中,插入 <style> 政策块的元素: 将捆绑到一个副本(pnpm why @design.estate/dees-domtools) (中文(简体) ).

返回的许诺在共享基础样式注入后解决 domtools.globalStylesReady 同一时间决定.

国家和一次性工作

domToolsStatePart 从此形状开始 :

{
  virtualViewport: 'native',
  jwt: '',
}

你也可以保护昂贵的Aync工作 runOnce()数字 :

import { DomTools } from '@design.estate/dees-domtools';

const domtools = await DomTools.setupDomTools();

const result = await domtools.runOnce('load-config', async () => {
  return { ok: true };
});

重复的呼叫者收到第一个结果,重复的失败则重推存储错误.

额外出口

import { TypedRequest, ThemeManager, type IThemeState, type TThemePreference, plugins } from '@design.estate/dees-domtools';

• ThemeManager 属于 domtools.themeManager导出为 ThemeManager.preferenceStorageKey 和打字;使用页面的例子而不是构建一个, TThemePreference (单位:千美元)'system' | 'bright' | 'dark'偏好,和 IThemeState 为了什么 stateObservable 发送( 参见主题偏好)
• TypedRequest 从 @api.global/typedrequest 输入请求流量 9
• plugins 披露软件包使用的基本模块,包括: smartrouter, (中文(简体) ), smartstate, (中文(简体) ), smartrx, (中文(简体) ), smartpromise,以及 typedrequest

运行时便笺

• 此软件包面向浏览器并触摸 window, (中文(简体) ), document, (中文(简体) ), navigator,以及 matchMedia
• keyboard 实值 null 直至 domReady 决定
• 出版的软件包针对最新的Chrome通过 browserslist
• 全局样式是采用样式表(document.adoptedStyleSheets自Chrome 73、Firefox 101和Safari 16.4起得到支持

许可证和法律资料

这个寄存器包含根据麻省理工学院许可证许可的开源代码. 许可证副本可在 许可证 文档.

请注意: 麻省理工学院许可证不准许使用该项目的商品名、商标、服务标记或产品名称,除非在描述作品来源和复制NOTICE文件内容时需要合理和习惯使用.

商标

这个项目由Task Venture Capital GmbH拥有和维护。 与Task Venture Capital GmbH相关的名称和标志以及任何相关的产品或服务是Task Venture Capital GmbH或第三方的商标,不属于本文授予的麻省理工学院许可证的范围.

使用这些商标必须符合Wasure Venture Capital GmbH的商标准则或各自的第三方所有者的准则,任何使用都必须获得书面批准。 此处使用的第三方商标是其各自所有者的财产并仅以描述方式使用,例如用于实施API或类似的.

企业信息

任务风险资本股份有限公司
在德国不来梅地区法院注册的HRB 35230 HB

如欲了解任何法律查询或进一步情况,请通过电子邮件与我们联系 你好@ task.vc。 。 。 .

通过使用这个寄存器,你承认你读过这个部分,同意遵守它的条款,并且明白代码的许可并不意味着Task Venture Capital GmbH认可任何衍生作品.