# @duskmoon-dev/el-base 中文文档

规范地址：https://npmcn.com/package/%40duskmoon-dev/el-base/

版本：1\.10\.3
npm 元数据更新时间：2026-11-11T10:48:17.043Z
中文译文更新时间：2026-11-13T00:43:18.048Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：262 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-21T02:20:44.946Z
- 最新版本发布：2026-11-11T10:48:16.590Z
- 近 30 天下载量：8612（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

DuskMoon定制要素的核心公用事业和基础课程.

## 安装

```sh
npm install @duskmoon-dev/el-base
```

也可以使用：`pnpm add @duskmoon-dev/el-base`、`yarn add @duskmoon-dev/el-base`、`bun add @duskmoon-dev/el-base`

## README

# @duskmoon-dev/el-base (日语)

DuskMoon定制要素的核心公用事业和基础课程.

## 安装

```bash
bun add @duskmoon-dev/el-base
```

## 使用量

### 基础元素

这个 `BaseElement` 类为创建自定义元素提供了基础:

-   阴影 DOM 设置 `adoptedStyleSheets`
-   带有属性反射的反应属性
-   使用微任务队列校正更新
-   样式注入工具
-   事件排放助手

```typescript
import { BaseElement, css } from '@duskmoon-dev/el-base';

const styles = css`
  :host {
    display: block;
  }
  .greeting {
    color: var(--dm-primary);
  }
`;

class MyGreeting extends BaseElement {
  static properties = {
    name: { type: String, reflect: true, default: 'World' },
  };

  declare name: string;

  constructor() {
    super();
    this.attachStyles(styles);
  }

  render() {
    return `<div class="greeting">Hello, ${this.name}!</div>`;
  }
}

customElements.define('my-greeting', MyGreeting);
```

### CSS 公用事业

#### `css` 模板标签

创建一个 `CSSStyleSheet` 从模板正文中:

```typescript
import { css } from '@duskmoon-dev/el-base';

const styles = css`
  :host {
    display: inline-flex;
  }
  button {
    padding: 0.5rem 1rem;
  }
`;
```

#### `combineStyles`

组合多个样式表 :

```typescript
import { combineStyles } from '@duskmoon-dev/el-base';

const combinedStyles = combineStyles(baseStyles, themeStyles, componentStyles);
```

#### `cssVars`

创建 CSS 自定义属性声明 :

```typescript
import { cssVars } from '@duskmoon-dev/el-base';

const vars = cssVars({
  'dm-primary': '#3b82f6',
  'dm-spacing': '1rem',
});
// Returns: '--dm-primary: #3b82f6; --dm-spacing: 1rem;'
```

### 默认主题

该软件包包括用于主题的默认 CSS 自定义属性. 导入主题样式表 :

```typescript
import { defaultTheme, resetStyles } from '@duskmoon-dev/el-base';

// Apply to shadow root
this.shadowRoot.adoptedStyleSheets = [resetStyles, defaultTheme, componentStyles];
```

#### 颜色

| 变量 | 说明 |
| --- | --- |
| `--dm-primary` | 主要品牌颜色 |
| `--dm-secondary` | 次要颜色 |
| `--dm-success` | 成功/正色 |
| `--dm-warning` | 警告颜色 |
| `--dm-error` | 错误/ 危险颜色 |
| `--dm-info` | 信息颜色 |

#### 灰度缩放

| 变量 | 说明 |
| --- | --- |
| `--dm-gray-50` | 最浅的灰色 |
| `--dm-gray-100` 结束 `--dm-gray-800` | 灰度缩放 |
| `--dm-gray-900` | 最暗的灰色 |

#### 类型

| 变量 | 说明 |
| --- | --- |
| `--dm-font-family` | 基本字体家族 |
| `--dm-font-size-xs` 结束 `--dm-font-size-2xl` | 字体大小 |
| `--dm-font-weight-normal`, (中文(简体) ), `--dm-font-weight-medium`, (中文(简体) ), `--dm-font-weight-semibold`, (中文(简体) ), `--dm-font-weight-bold` | 字体权重 |
| `--dm-line-height-tight`, (中文(简体) ), `--dm-line-height-normal`, (中文(简体) ), `--dm-line-height-relaxed` | 线高 |

#### 间距

| 变量 | 说明 |
| --- | --- |
| `--dm-spacing-xs` | 额外小(0.25雷姆) |
| `--dm-spacing-sm` | 小型(0.5雷姆) |
| `--dm-spacing-md` | 中型(1雷姆) |
| `--dm-spacing-lg` | 大型(1.5雷姆) |
| `--dm-spacing-xl` | 额外大(2雷姆) |

#### 边框半径

| 变量 | 说明 |
| --- | --- |
| `--dm-radius-sm` | 小半径 |
| `--dm-radius-md` | 中半径 |
| `--dm-radius-lg` | 大半径 |
| `--dm-radius-full` | 全/溢出半径 |

#### 阴影

| 变量 | 说明 |
| --- | --- |
| `--dm-shadow-sm` | 小阴影 |
| `--dm-shadow-md` | 中阴影 |
| `--dm-shadow-lg` | 大阴影 |

#### 过渡

| 变量 | 说明 |
| --- | --- |
| `--dm-transition-fast` | 快速过渡(150ms) |
| `--dm-transition-normal` | 正常过渡( 200ms) |
| `--dm-transition-slow` | 缓慢过渡( 300ms) |

## API 密码

### 基础元素

| 方法 | 说明 |
| --- | --- |
| `attachStyles(styles)` | 在阴影 DOM 中附加一个或多个样式表 |
| `render()` | 覆盖以返回 HTML 内容字符串 |
| `update()` | 当反应属性变化时调用( 有争议) |
| `emit(name, detail?)` | 从元素中删除自定义事件 |
| `query(selector)` | 在阴影 DOM 中查询单元素 |
| `queryAll(selector)` | 查询阴影 DOM 中的所有匹配元素 |

### 财产定义

定义自动属性反射的反应性 :

```typescript
static properties = {
  // Simple string property
  label: { type: String },

  // Boolean with attribute reflection
  disabled: { type: Boolean, reflect: true },

  // Number with default value
  count: { type: Number, default: 0 },

  // Custom attribute name (kebab-case)
  maxItems: { type: Number, attribute: 'max-items' },

  // Object/Array (not reflected to attributes)
  data: { type: Object },
  items: { type: Array, default: [] },
};
```

属性定义选项 :

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `Function` | 类型构造器 : `String`, (中文(简体) ), `Number`, (中文(简体) ), `Boolean`, (中文(简体) ), `Object`, (中文(简体) ), `Array` |
| `reflect` | `boolean` | 是否反映属性 |
| `attribute` | `string` | 自定义属性名称( 小写属性名称的默认值) |
| `default` | `any` | 财产的默认值 |

### 生命周期

```typescript
class MyElement extends BaseElement {
  // Called when element is added to DOM
  connectedCallback() {
    super.connectedCallback();
    // Setup code
  }

  // Called when element is removed from DOM
  disconnectedCallback() {
    super.disconnectedCallback();
    // Cleanup code
  }

  // Called when properties change (batched)
  update() {
    // Re-render or update DOM
    this.shadowRoot.innerHTML = this.render();
  }

  // Return HTML string for Shadow DOM content
  render() {
    return `<div>Content</div>`;
  }
}
```

### 类型脚本

```typescript
import type {
  PropertyDefinition,
  PropertyDefinitions,
  Size,
  Variant,
  ValidationState,
  BaseElementProps,
  SizableProps,
  VariantProps,
  FormElementProps,
  ValidatableProps,
  ValueChangeEventDetail,
} from '@duskmoon-dev/el-base';
```

## 创建自定义元素

自定义元素的全部示例 :

```typescript
import { BaseElement, css, defaultTheme, resetStyles } from '@duskmoon-dev/el-base';

const styles = css`
  :host {
    display: inline-block;
  }

  .counter {
    display: flex;
    align-items: center;
    gap: var(--dm-spacing-sm);
  }

  button {
    padding: var(--dm-spacing-xs) var(--dm-spacing-sm);
    border-radius: var(--dm-radius-sm);
    background: var(--dm-primary);
    color: white;
    border: none;
    cursor: pointer;
    transition: opacity var(--dm-transition-fast);
  }

  button:hover {
    opacity: 0.9;
  }

  .value {
    min-width: 2rem;
    text-align: center;
    font-weight: var(--dm-font-weight-medium);
  }
`;

export class MyCounter extends BaseElement {
  static properties = {
    value: { type: Number, reflect: true, default: 0 },
    min: { type: Number, default: 0 },
    max: { type: Number, default: 100 },
  };

  declare value: number;
  declare min: number;
  declare max: number;

  constructor() {
    super();
    this.attachStyles(resetStyles, defaultTheme, styles);
  }

  connectedCallback() {
    super.connectedCallback();
    this.shadowRoot?.addEventListener('click', this.handleClick.bind(this));
  }

  private handleClick(e: Event) {
    const target = e.target as HTMLElement;
    if (target.matches('[data-action="decrement"]')) {
      this.decrement();
    } else if (target.matches('[data-action="increment"]')) {
      this.increment();
    }
  }

  private decrement() {
    if (this.value > this.min) {
      this.value--;
      this.emit('change', { value: this.value });
    }
  }

  private increment() {
    if (this.value < this.max) {
      this.value++;
      this.emit('change', { value: this.value });
    }
  }

  render() {
    return `
      <div class="counter">
        <button data-action="decrement" ${this.value <= this.min ? 'disabled' : ''}>-</button>
        <span class="value">${this.value}</span>
        <button data-action="increment" ${this.value >= this.max ? 'disabled' : ''}>+</button>
      </div>
    `;
  }
}

export function register() {
  if (!customElements.get('my-counter')) {
    customElements.define('my-counter', MyCounter);
  }
}
```

## 许可证

麻省理工学院

## 常见问题

### @duskmoon-dev/el-base 是什么？

DuskMoon定制要素的核心公用事业和基础课程\.

### 如何安装 @duskmoon-dev/el-base？

在项目目录运行 npm install @duskmoon-dev/el-base，或使用 pnpm add / yarn add / bun add。

### @duskmoon-dev/el-base 支持 TypeScript 吗？

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

### @duskmoon-dev/el-base 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @duskmoon-dev/el-base 可以商用吗？

@duskmoon-dev/el-base 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @duskmoon-dev/el-base 的下载量有多少？

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

### @duskmoon-dev/el-base 还在维护吗？

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