# @design\.estate/dees-domtools 中文文档

规范地址：https://npmcn.com/package/%40design.estate/dees-domtools/

版本：5\.3\.0
npm 元数据更新时间：2026-10-26T19:33:24.015Z
中文译文更新时间：2026-11-12T01:07:01.724Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40design.estate/dees-domtools
原文对照：https://npmcn.com/package/%40design.estate/dees-domtools/?lang=original

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

- 包体积（解压后）：5.5 MB，49 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：16 个
- 首次发布：2023-08-06T17:57:44.928Z
- 最新版本发布：2026-10-26T19:33:23.663Z
- 近 30 天下载量：10586（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 22 个）

## 中文简介

提供简化复杂CSS结构和网络开发任务的工具包,以TypeScript支持和与各种网络技术相融合为特色.

## 安装

```sh
npm install @design.estate/dees-domtools
```

也可以使用：`pnpm add @design.estate/dees-domtools`、`yarn add @design.estate/dees-domtools`、`bun add @design.estate/dees-domtools`

## README

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

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

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

## 问题报告和安全

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

## 安装

```bash
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 .

## 快速启动

```ts
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 生命周期

```ts
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()` 启动完成后.

## 清理

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

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

// ...use the instance

domtools.dispose();
```

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

## DOM、CSS和外部资源

```ts
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">`,当策略允许样式表的出处时,它允许.

页面元数据和外观:

```ts
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',
});
```

## 主题管理

```ts
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>`。 。 。 .

### 主题偏好

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

```ts
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>` 重放当前状态,并在首选的每次更改、系统的颜色方案或主题上发布,同样当主题停留时(从系统已经显示的主题中选择,系统在选择时改变,另一个标签选择):

```ts
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` 在使用它之前.

```ts
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]);
```

## 滚动

```ts
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和船舶设计的,既有预设的断点,也有下级的帮助.

```ts
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 设备

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

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

console.log(columns);
```

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

## Lit 元素设置

```ts
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`。 。 。 .

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

```ts
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` 从此形状开始 :

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

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

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

const domtools = await DomTools.setupDomTools();

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

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

## 额外出口

```ts
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起得到支持

## 许可证和法律资料

这个寄存器包含根据麻省理工学院许可证许可的开源代码. 许可证副本可在 [许可证](https://npmcn.com/package/%40design.estate/dees-domtools/license.md) 文档.

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

### 商标

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

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

### 企业信息

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

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

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

## 常见问题

### @design\.estate/dees-domtools 是什么？

提供简化复杂CSS结构和网络开发任务的工具包,以TypeScript支持和与各种网络技术相融合为特色\.

### 如何安装 @design\.estate/dees-domtools？

在项目目录运行 npm install @design\.estate/dees-domtools，或使用 pnpm add / yarn add / bun add。

### @design\.estate/dees-domtools 支持 TypeScript 吗？

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

### @design\.estate/dees-domtools 支持 ESM 还是 CommonJS？

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

### @design\.estate/dees-domtools 可以商用吗？

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

### @design\.estate/dees-domtools 的下载量有多少？

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

### @design\.estate/dees-domtools 还在维护吗？

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