# ncomdev
**Repository Path**: weblabsw/ncomdev
## Basic Information
- **Project Name**: ncomdev
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# New Component（ncom）
New Component 是一套**原生 Web Component** 组件库：基于 **Custom Elements** 与 **Shadow DOM**，用 TypeScript 与 Vite 开发与构建，可在任意前端栈中以标准自定义元素方式使用。
> “Less framework, more web.”
## 环境要求
| 工具 | 版本 |
| ------- | ---------- |
| Node.js | >= 20.16.0 |
| pnpm | >= 10.26.1 |
建议使用 `npm i -g pnpm` 安装 pnpm，以与 `packageManager` 字段一致。
## 快速开始（本地开发）
```bash
# 安装依赖
pnpm install
# 变异
pnpm build
# 启动example站点
pnpm dev:example
```
_**example站点启动后，按提示访问站点**_
## 仓库结构（Monorepo）
本仓库为 **pnpm workspace**，主要目录如下：
| 路径 | 说明 |
| ------------------------------------------ | ------------------------------------ |
| [packages/core](packages/core) | 组件基类、事件与工具（`@ncom/core`） |
| [packages/components](packages/components) | UI 组件实现（`@ncom/components`） |
| [packages/locale](packages/locale) | 国际化（`@ncom/locale`） |
| [packages/extensions](packages/extensions) | 扩展能力如路由（`@ncom/extensions`） |
| [packages/theme](packages/theme) | 主题（`@ncom/theme`） |
| [packages/all](packages/all) | 聚合构建与对外入口（`@ncom/all`） |
| [example](example) | 示例 |
## 特性
- **标准 Web Components**：自定义元素 + Shadow DOM，样式与 DOM 边界清晰。
- **跨框架使用**：可在 Vue、React、原生 HTML 等环境中以标签形式使用。
- **TypeScript**：源码与类型定义便于在工程内获得提示。
- **组合能力**：表单、布局、数据展示与反馈类组件覆盖常见中后台场景。
- **开发与构建**：根目录脚本统一驱动 Vite 与各子包构建。
## 安装
### 全量安装
```bash
pnpm add @ncom/all -D
```
### 最小安装
```bash
pnpm add @ncom/core -D
```
## 第一个组件
```typescript
import { NComponent, defineComponent } from "@ncom/all";
export default class Hello extends NComponent {
template() {
return `Hello New Component
`;
}
}
defineComponent("my-hello", Hello);
```
## 基类与结构
- `NComponent`：所有组件需继承该类
- `template()`：返回 Shadow DOM 内的 HTML 模板串
- `defineComponent(tag, Class)`：注册自定义元素
- `this.root`：模板根节点（constructor 阶段可用）
- `this.contextRoot`：表达式与 `this.` 的解析上下文
## 组件生命周期
### constructor
1. 获取 `contextRoot`
2. 创建 template 节点，执行 `template` 方法
3. 获取 `root` 节点（尚未加入 shadowRoot）
### connectedCallback
1. 处理组件 attributes 和事件绑定
2. template 节点添加到 shadowRoot
3. 处理子节点，触发 `firstUpdated`
**_注意：如果在组件中重载了connectedCallback方法，必须加上`super.connectedCallback()`_**
### disconnectedCallback
1. 释放 `eventManager` 绑定的所有事件
### 编写技巧
1. 属性初始化、节点缓存放 `constructor`，通过 `this.root` 查询
2. 事件绑定放 `connectedCallback`，避免 `disconnectedCallback` 解绑后无法恢复
3. 属性响应：`observedAttributes` + `attributeChangedCallback`（参考 `nc-button`）
## 样式
```typescript
import css from "./style.scss?inline";
constructor() {
super();
this.addCss(css);
}
```
## 插槽 Slot
与标准 Web Components 一致，使用 `slot` 属性与 `` 分发内容。
### 初始化顺序
1. parent 创建 → constructor → attributeChangedCallback → connectedCallback
2. child 创建 → constructor → attributeChangedCallback → connectedCallback
## 表达式
表达式以 `{}` 包裹，只能以 attribute 方式使用。
### 规则
1. 支持算术、数组字面量及 `Math`、`String` 等内置对象
2. 支持 `this.` 开头的方法/属性引用（属于 context 组件）
3. 不支持 `this.` 与其它表达式`混用`
### 示例
```typescript
template() {
return `
`;
}
```
## 事件
- **组件自定义事件**：以 `nc-` 开头，模板中使用 `@nc-事件名` 绑定（如 `@nc-click={this.handler}`）
- **原生 HTML 事件**：使用 `@click` 绑定（如 `