WebCell

简体中文 | English

基于 VDOM、JSX、MobX 和 TypeScript 的 Web 组件 引擎

特性

引擎比较

特性	WebCell 3	WebCell 2	React	Vue
JS 语言	TypeScript 5	TypeScript 4	ECMAScript 或 TypeScript	ECMAScript 或 TypeScript
JS 语法	ES 装饰器 stage-3	ES 装饰器 stage-2
XML 语法	JSX import	JSX factory	JSX factory/import	HTML/Vue 模板或 JSX（可选）
DOM API	Web 组件	Web 组件	HTML 5+	HTML 5+
视图渲染器	DOM Renderer 2	SnabbDOM	（内置）	SnabbDOM（分叉）
state API	MobX @observable	this.state	this.state 或 useState()	this.$data 或 ref()
props API	MobX @observable	@watch	this.props 或 props => {}	this.$props 或 defineProps()
状态管理	MobX 6+	MobX 4/5	Redux	VueX
页面路由器	JSX 标签	JSX 标签 + JSON 数据	JSX 标签	JSON 数据
资源打包工具	Parcel 2	Parcel 1	webpack	Vite

安装

npm install dom-renderer mobx web-cell
Copy

Web 浏览器用法

演示和 GitHub 模板

项目引导

工具链

npm install parcel @parcel/config-default @parcel/transformer-typescript-tsc -D
Copy

package.json

{
    "scripts": {
        "start": "parcel source/index.html --open",
        "build": "parcel build source/index.html --public-url ."
    }
}
Copy

tsconfig.json

{
    "compilerOptions": {
        "target": "ES6",
        "module": "ES2020",
        "moduleResolution": "Node",
        "useDefineForClassFields": true,
        "jsx": "react-jsx",
        "jsxImportSource": "dom-renderer"
    }
}
Copy

.parcelrc

{
    "extends": "@parcel/config-default",
    "transformers": {
        "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc"]
    }
}
Copy

source/index.html

<script src="https://polyfill.web-cell.dev/feature/ECMAScript.js"></script>
<script src="https://polyfill.web-cell.dev/feature/WebComponents.js"></script>
<script src="https://polyfill.web-cell.dev/feature/ElementInternals.js"></script>

<script src="source/MyTag.tsx"></script>

<my-tag></my-tag>
Copy

函数组件

import { DOMRenderer } from 'dom-renderer';
import { FC, PropsWithChildren } from 'web-cell';

const Hello: FC<PropsWithChildren> = ({ children = '世界' }) => (
    <h1>你好，{children}！</h1>
);

new DOMRenderer().render(<Hello>WebCell</Hello>);
Copy

类组件

子元素插槽

import { DOMRenderer } from 'dom-renderer';
import { component } from 'web-cell';

@component({
    tagName: 'hello-world',
    mode: 'open'
})
class Hello extends HTMLElement {
    render() {
        return (
            <h1>
                你好, <slot />!
            </h1>
        );
    }
}

new DOMRenderer().render(
    <>
        <Hello>WebCell</Hello>
        {/* 或 */}
        <hello-world>WebCell</hello-world>
    </>
);
Copy

DOM 属性

import { DOMRenderer } from 'dom-renderer';
import { observable } from 'mobx';
import { WebCell, component, attribute, observer } from 'web-cell';

interface HelloProps {
    name?: string;
}

interface Hello extends WebCell<HelloProps> {}

@component({ tagName: 'hello-world' })
@observer
class Hello extends HTMLElement implements WebCell<HelloProps> {
    @attribute
    @observable
    accessor name = '';

    render() {
        return <h1>你好，{this.name}!</h1>;
    }
}

new DOMRenderer().render(<Hello name="WebCell" />);

// 或在 TypeScript 中提示 HTML 标签属性

declare global {
    namespace JSX {
        interface IntrinsicElements {
            'hello-world': HelloProps;
        }
    }
}
new DOMRenderer().render(<hello-world name="WebCell" />);
Copy

内部状态

函数组件

import { DOMRenderer } from 'dom-renderer';
import { observable } from 'mobx';
import { FC, observer } from 'web-cell';

class CounterModel {
    @observable
    accessor times = 0;
}

const couterStore = new CounterModel();

const Counter: FC = observer(() => (
    <button onClick={() => (couterStore.times += 1)}>
        计数：{couterStore.times}
    </button>
));

new DOMRenderer().render(<Counter />);
Copy

类组件

import { DOMRenderer } from 'dom-renderer';
import { observable } from 'mobx';
import { component, observer } from 'web-cell';

@component({ tagName: 'my-counter' })
@observer
class Counter extends HTMLElement {
    @observable
    accessor times = 0;

    handleClick = () => (this.times += 1);

    render() {
        return <button onClick={this.handleClick}>计数：{this.times}</button>;
    }
}

new DOMRenderer().render(<Counter />);
Copy

CSS 作用域

内联样式

import { component } from 'web-cell';
import { stringifyCSS } from 'web-utility';

@component({
    tagName: 'my-button',
    mode: 'open'
})
export class MyButton extends HTMLElement {
    style = stringifyCSS({
        '.btn': {
            color: 'white',
            background: 'lightblue'
        }
    });

    render() {
        return (
            <>
                <style>{this.style}</style>

                <a className="btn">
                    <slot />
                </a>
            </>
        );
    }
}
Copy

链接样式表

import { component } from 'web-cell';

@component({
    tagName: 'my-button',
    mode: 'open'
})
export class MyButton extends HTMLElement {
    render() {
        return (
            <>
                <link
                    rel="stylesheet"
                    href="https://unpkg.com/bootstrap@5.3.3/dist/css/bootstrap.min.css"
                />
                <a className="btn">
                    <slot />
                </a>
            </>
        );
    }
}
Copy

CSS 模块

scoped.css

.btn {
    color: white;
    background: lightblue;
}
Copy

MyButton.tsx

import { WebCell, component } from 'web-cell';

import styles from './scoped.css' assert { type: 'css' };

interface MyButton extends WebCell {}

@component({
    tagName: 'my-button',
    mode: 'open'
})
export class MyButton extends HTMLElement implements WebCell {
    connectedCallback() {
        this.root.adoptedStyleSheets = [styles];
    }

    render() {
        return (
            <a className="btn">
                <slot />
            </a>
        );
    }
}
Copy

事件委托

import { component, on } from 'web-cell';

@component({ tagName: 'my-table' })
export class MyTable extends HTMLElement {
    @on('click', ':host td > button')
    handleEdit(event: MouseEvent, { dataset: { id } }: HTMLButtonElement) {
        console.log(`编辑行：${id}`);
    }

    render() {
        return (
            <table>
                <tr>
                    <td>1</td>
                    <td>A</td>
                    <td>
                        <button data-id="1">编辑</button>
                    </td>
                </tr>
                <tr>
                    <td>2</td>
                    <td>B</td>
                    <td>
                        <button data-id="2">编辑</button>
                    </td>
                </tr>
                <tr>
                    <td>3</td>
                    <td>C</td>
                    <td>
                        <button data-id="3">编辑</button>
                    </td>
                </tr>
            </table>
        );
    }
}
Copy

MobX reaction

import { observable } from 'mobx';
import { component, observer, reaction } from 'web-cell';

@component({ tagName: 'my-counter' })
@observer
export class Counter extends HTMLElement {
    @observable
    accessor times = 0;

    handleClick = () => (this.times += 1);

    @reaction(({ times }) => times)
    echoTimes(newValue: number, oldValue: number) {
        console.log(`新值：${newValue}，旧值：${oldValue}`);
    }

    render() {
        return <button onClick={this.handleClick}>计数：{this.times}</button>;
    }
}
Copy

表单关联

import { DOMRenderer } from 'dom-renderer';
import { WebField, component, formField, observer } from 'web-cell';

interface MyField extends WebField {}

@component({
    tagName: 'my-field',
    mode: 'open'
})
@formField
@observer
class MyField extends HTMLElement implements WebField {
    render() {
        const { name } = this;

        return (
            <input
                name={name}
                onChange={({ currentTarget: { value } }) =>
                    (this.value = value)
                }
            />
        );
    }
}

new DOMRenderer().render(
    <form method="POST" action="/api/data">
        <MyField name="test" />

        <button>提交</button>
    </form>
);
Copy

异步组件

AsyncTag.tsx

import { FC } from 'web-cell';

const AsyncTag: FC = () => <div>异步</div>;

export default AsyncTag;
Copy

index.tsx

import { DOMRenderer } from 'dom-renderer';
import { lazy } from 'web-cell';

const AsyncTag = lazy(() => import('./AsyncTag'));

new DOMRenderer().render(<AsyncTag />);
Copy

Animate CSS 组件

import { DOMRenderer } from 'dom-renderer';
import { AnimateCSS } from 'web-cell';

new DOMRenderer().render(
    <AnimateCSS type="fadeIn" component={props => <h1 {...props}>淡入</h1>} />
);
Copy

Node.js 用法

工具链

npm install jsdom
Copy

Polyfill

import 'web-cell/polyfill';
Copy

服务端渲染

https://github.com/EasyWebApp/DOM-Renderer?tab=readme-ov-file#nodejs--bun

基础知识

• Web 组件
• 自定义元素
• 虚拟 DOM
• Element Internals
• CSS 变量
• 视图渐变
• ECMAScript 6+
• TypeScript 5+

生命周期钩子

1. connectedCallback
2. disconnectedCallback
3. attributeChangedCallback
4. adoptedCallback
5. updatedCallback
6. mountedCallback
7. formAssociatedCallback
8. formDisabledCallback
9. formResetCallback
10. formStateRestoreCallback

脚手架

1. 基础
2. 仪表盘
3. 移动端
4. 静态网站

生态系统

我们建议将这些库与 WebCell 一起使用：

• 状态管理：MobX（也由 TypeScript 和 Decorator 提供支持）

• 路由：Cell Router

• UI 组件

  • BootCell（基于 BootStrap v5）
  • MDUI（基于 Material Design v3）
  • GitHub Web Widget

• HTTP 请求：KoAJAX（基于类 Koa 中间件）

• 实用程序：Web utility 方法和类型

• 事件流：Iterable Observer（Observable 提案）

• MarkDown 集成：Parcel MDX transformer（MDX 编译器插件）

路线图

• [x] 服务器端渲染
• [x] 异步组件加载

v2 到 v3 迁移

更多指南

1. 开发贡献