# @ecopages/radiant 中文文档

规范地址：https://npmcn.com/package/%40ecopages/radiant/

版本：0\.8\.4
npm 元数据更新时间：2026-11-13T14:14:07.964Z
中文译文更新时间：2026-11-13T14:21:16.968Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ecopages/radiant
原文对照：https://npmcn.com/package/%40ecopages/radiant/?lang=original
源码仓库：https://github.com/ecopages/radiant

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

- 包体积（解压后）：2.7 MB，261 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@ecopages/jsx \>=0\.8\.4
- 首次发布：2024-05-31T21:45:45.673Z
- 最新版本发布：2026-11-13T14:14:07.622Z
- 近 30 天下载量：6524（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 59 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @ecopages/radiant
```

也可以使用：`pnpm add @ecopages/radiant`、`yarn add @ecopages/radiant`、`bun add @ecopages/radiant`

## README

# 半径

Radiant是一个用于自定义元素和DOM相接控制器的光-DOM平台.

它保持了浏览器原始的能见度,而不是用合成组件模型来包装. 你的工作与真实的自定义元素,真实的DOM事件,真实的属性,以及真实的光-DOM孩子. 使用 `RadiantElement` 当你想要反应字段, JSX 支持的渲染, SSR 主机序列化, 和水合在真正的自定义元素。 使用 `RadiantController` 当您想要将行为附在现有的 DOM 上而不是定义自定义元素时.

拉迪安特故意只将 DOM 制成光;它没有阴影渲染模式. 这保持了造型,DOM检查,作者儿童内容,以及ARIA在主机拥有和作者节点之间的id引用简单,同时放弃了常规自定义元素指导通常喜欢的封装.

关于完整的文件网址,见 [光辉的. ecopages.app](https://radiant.ecopages.app/)。 。 。 .

## 安装

`@ecopages/radiant` 是核心软件包. `@ecopages/jsx` 提供TSX渲染,以及 `@ecopages/signals` 提供Radiant下方的渲染器不可知的反应层.

`@ecopages/radiant` 取决于 `@ecopages/signals` 直接宣布 `@ecopages/jsx` 作为同伴的依赖。 安装发光器可以传递信号,这也满足了jsx对信号的对等依赖.

对于标准radiant设置,安装光和jsx:

```sh
bun add @ecopages/radiant @ecopages/jsx
```

应用程序代码不需要直接导入 JSX 辅助器或信号原始器用于每个特性, 但当前发布的 Radiant 表面预期 `@ecopages/jsx` 被安装在一起。 安装 `@ecopages/signals` 明确指定仅在您想要在 Radiant 外单独反应层时,或者在使用 `@ecopages/jsx` 没有光泽.

## 神经元心理模型

`RadiantElement` 是反应自定义元素的结构基础类.

`@customElement(name, options)` 仅登记自定义元素。 传递定义 `options.extends` 定义自定义内置值的值 `TypeError` 在类定义时间,和 `extends` 从 TypeScript 选项类型中排除.

`options.hostAttributes` 给出一个 `RadiantElement` 主机固定属性, 如 `{ role: 'complementary' }`. 服务器渲染在它准备主机时写出它们,从而达到服务器输出,客户端在每次连接开始时写出它们之前 `onConnected()`。在主机上已经存在的属性永远不会被覆盖。 一个子类继承它们,并按名称来覆盖它们. 国家依赖属性 `@bindTo` 财务报告和审定财务报表 `@onUpdated`。 。 。 .

-   `render()` 返回当前 JSX 视图.
-   首先连接会自动选择水合和新客户端渲染之间.
-   `update()` 运行当前更新周期:已批量 `@onUpdated` 回调, 主机覆盖时的渲染 `render()`,则 `updated()`它在每个主机上工作,所以它也冲出 `@onUpdated` 在没有主机的情况下同步 `render()`。 。 。 .
-   `requestUpdate()` 在微任务中循环并串联重复请求的时间表. `updateComplete` 当循环结束时解决,当循环结束时拒绝 `@onUpdated` 召回、制作或 `updated()` 扔进去 一个失败的循环会丢弃它剩下的队列所完成的工作;一个后来的写入会开始一个新的循环.
-   主机只在连接时观察其反应成员. 连接前或脱落时的更改在下一个连接上报告,所以共享 `@signal` 源头从不让删除的主机活着. 服务器渲染从不连接主机; 它排出待处理 `@onUpdated` 在主机准备中召回, 绝不召回 `updated()`。 。 。 .
-   `@prop(...)`, (中文(简体) ), `@state`,以及 `@signal(...)` 界定反应成员。 A 类 `@prop` 属性默认为 kebab- case 属性名称(`minWidth` 地图到 `min-width`(三); `@attr` 其源属性使用相同的转换,连续下划线崩溃为一条连字符. `attribute` 打开 `@prop` 财务报告和审定财务报表 `source` 打开 `@attr` 覆盖默认并保留明确的名称。 JSX继续使用骆驼Case财产. HTML 小写属性名称,因此在消费者在HTML中作者时选择小写显式名称. 过 `transform` 打开 `@prop` 覆盖默认转换器( e)`type: Array` jSON 除非你提供 `fromAttribute` 编号 : `toAttribute`) (中文(简体) ). `fromProperty` 使JS/JSX写作正常化. `toAttribute` 返回时 `null` 或者说 `''` 省略所反映属性,而不改变所分配的属性.
-   所声明的字段类型是真实的来源 `@prop(...)`, (中文(简体) ), `@attr(...)`, (中文(简体) ), `@signal(...)`, (中文(简体) ), `@state`, (中文(简体) ), `@bindTo(...)`, (中文(简体) ), `@query(...)`, (中文(简体) ), `@event(...)` 和上下文装饰器:含有值的选项(`defaultValue`, (中文(简体) ), `initial`, (中文(简体) ), `transform`, (中文(简体) ), `converter`, (中文(简体) ), `type`,以及 `source` 打开 `@signal`)必须同意它,在标准装饰器下,不匹配就是装饰器上的编译错误. `@prop({ type: Number, defaultValue: 0 }) label: string` 不编译,而且 `@attr({ defaultValue: 'a' }) mode: 'a' | 'b'` 已经 单元素 `@query(...)` 字段为 `T | null` (单位:千美元)`T[]` 与 `all: true`注意每个用途 写一个装饰地 与初始化器, `?` 或者说 `!`数字 : `declare` 财务报告和审定财务报表 `accessor` 字段不编译。 遗产装饰者`experimentalDecorators: true`) 从未收到字段类型,所以这些检查都没有在那里运行,也没有一个召回,例如: `@bindTo`是因为 `map` 看见了 `unknown` 除非你通过整个球场类型, `undefined` 作为类型参数列入(`@bindTo<number>(...)`, (中文(简体) ), `@bindTo<WritableSignal<number>>(...)` 编号 `@signal` 页:1 每个装饰者的规则 `type` 常数和解析器在 [打入装饰字段](https://radiant.ecopages.app/docs/decorators#typing-decorated-fields)。 。 。 .
-   作者属性在升级后保留在主机上, 是否反映 : `reflect` 只控制写入属性回转,所以一个非反射属性在升级时被读取,之后不同步.
-   提升安全性:一个在定义一个主机标记之前分配给它的值会成为未升级元素的自有属性. `@prop` 成员采纳它,它胜过一个作者属性,因此消费者从不需要推迟一个要素定义来避免失去输入. `@state` 财务报告和审定财务报表 `@signal` 它们是内部成员,而不是公共投入:它们保留其初始化器并丢弃这样一个值。 在开发中,一个升级的宿主,每个标记和成员一个警告一次,给成员取名并指向 `@prop`; 生产结构降低警告和 `setDevWarningsEnabled(false)` 从 `@ecopages/jsx/jsx-dev-runtime` 安静 升级前的任务也暗指班级访问者(手写) `get`编号 :`set`,一个 `accessor` 字段,或者像 MobX 这样的库访问器装饰器 `@observable accessor`)),因此访问者从未看到它;它警告每个标记一次,成员也一样;在升级后恢复,保存值,删除自有地产并再次分配,从而通过设置器. 将库状态保存在经过的商店中 `@prop` 或上下文,而不是主机上的存取成员.
-   `@prop({ attribute: false })` 使道具属性仅:没有被观察到的属性,该名称的作者属性被忽略,它从未被反映,也从未被服务器渲染所串行. 用于诸如类例之类的活物体,否则会将其球场渗入加分,失去方法,如果是循环,则在SSA期间投出; `reflect: true` 用它掷出。 串行道具是公用标记,因此在保持其属性的道具中保留私有或大数据. 在开发中,当保持其属性的道具拥有类实例,功能或循环时,服务器渲染每标记和道具都会发出一次警告.
-   反射属性序列化每个写入的当前值 。 同步调用( N)`@bindTo`, (中文(简体) ), `registerUpdateCallback`)也反映了使任务正常化.
-   `@bindTo(...)` 当主机不拥有时,将被动字段复制到现有的 DOM `render()` 树.
-   `@onUpdated(...)` 在做出判决之前,同一批成员变更一次。 如果它的回调会改变一个被监视的成员,它可以在同一周期内再次运行,直到状态平息. 用于程序和要求拥有该软件的 `update()` 编号 : `requestUpdate()` 当视图结构必须改变时. `updated()` 工作需要 坚定的DOM.
-   `this.bindings.key`, (中文(简体) ), `this.$.key`,以及 `this.bind('key')` 暴露出针对反应性成员的稳定的JSX约束.
-   若为 `render()` 被省略,作者的光-DOM儿童通过不变。 复制字段到 DOM `@bindTo(...)`。 。 。 .
-   `registerConnectedCallback()` 是一个预同步钩:在连接开始时,在先连接属性补真之前,它会同步运行. 仅用于不读取作者属性值的设置 . `onConnected()` 运行在每次连接之后, 一旦属性补正和( 当 `render()` 已覆盖)初始水合物/更新已完成; 使用它代替 `connectedCallback` + 键 `queueMicrotask(sync)` 当工作需要同步主机时.
-   `FormAssociatedElement` 扩展 `RadiantElement` 用于本地形态控制。 每个混凝土子类都继承了固定的FACE旗并拥有一面 `ElementInternals`; 执行 `formValue()` 财务报告和审定财务报表 `restoreFormState()`覆盖 `formState()` 当提交可以 `null` 在指定或使用多个条目之前 `FormData`,因此重置保留了作者的值。 第一个形式值同步,通常在第一个连接周期,记录重置状态.
-   `{this.slotted}` 安置宿主的子女 `{this.slotted ?? fallback}` 倒计时,因为它 `null` 当没有。 一种观点使 `<x-card>{children}</x-card>` 手执a **儿童价值** 到主机,只有主机的渲染器触碰了节点. 命名区域是属性( R)`<x-card header={<h2 />}>` 执行 `{this.header}`) (中文(简体) ). **儿童作者** (b) 以后附上的节点没有排定档期. `this.slottedElements` 读取所提供内容的顶级元素. `<slot>` 是一个普通元素。 见 [槽数](https://radiant.ecopages.app/docs/components/slots)。 。 。 .

主要的区别是:

-   使用 `@bindTo` 当主机保留了作者的 DOM 和一个字段应该作为属性,属性,或文本出现时.
-   使用诸如 `this.$.count` 当主机拥有 `render()`,视图的形状保持不变,只有孩子的价值需要改变.
-   使用 `update()` 或者说 `requestUpdate()` 当反应性变化影响JSX树的结构时.

直接在内部进行信号和存储读取 `render()` 也参与重递无效, 因此共享的反应数据可以驱动 `RadiantElement` 视图中没有额外的包层.

## 对话框

这个柜台显示 `RadiantElement` 用于稳定模板的样式:公共道具保持清晰,内部状态保持本地状态,绑定的孩子值更新而不强制整个模板完全重置.

```tsx
/** @jsxImportSource @ecopages/jsx */

import type { JSX_PROPS } from '@ecopages/jsx';
import { RadiantElement, customElement, prop, state } from '@ecopages/radiant';

type CounterCardBindings = {
    count: number;
    label: string;
};

type CounterCardProps = {
    label?: string;
};

@customElement('counter-card')
export class CounterCard extends RadiantElement<CounterCardBindings> {
    declare readonly [JSX_PROPS]?: CounterCardProps;

    @prop({ type: String, defaultValue: 'Clicks' }) label!: string;
    @state count = 0;

    private readonly increment = () => {
        this.count += 1;
    };

    override render() {
        return (
            <section>
                <h2>{this.$.label}</h2>
                <p>Count: {this.$.count}</p>
                <button type="button" on:click={this.increment}>
                    Increment
                </button>
            </section>
        );
    }
}

<CounterCard label="Clicks" />;
```

如何运作:

-   `@prop(...)` 制造 `label` 部分组件的公共反应属性和属性表面.
-   `@state` 是内部可变状态.
-   `this.$.label` 财务报告和审定财务报表 `this.$.count` 被缓存 JSX 绑定,所以当潜在的反应成员改变时,这些文本位置可以直接更新.
-   此示例不要求 `update()` 因为视图结构是稳定的。 只有绑定的孩子价值才会改变.
-   `JSX_PROPS` 声明一个比内部绑定形状更窄的公共类型。 这通常是正确的拆分.

如果同一型号真正代表了内部约束性和公共JSX属性,则可以对两者重新使用. 否则,将这些合同分开.

### 何时呼叫 `update()`

打电话 `update()` 或者说 `requestUpdate()` 当反应性变化影响哪些要素应该存在,而不只是其儿童价值.

```ts
import { RadiantElement, onUpdated, state } from '@ecopages/radiant';

export class ResultsPanel extends RadiantElement<{ expanded: boolean }> {
    @state expanded = false;

    @onUpdated('expanded')
    protected rerenderView(): void {
        this.requestUpdate();
    }
}
```

使用 `update()` 当你想要立即投降时 使用 `requestUpdate()` 当在同一转弯中可能发生数起变化,而一次最后折返就足够了.

## 反应 JSX 装订

约束是API中不明显的部分,值得明确阐述.

`RadiantElement<Bindings>` 采用专用绑定形状,而非全类类型. 这使得绑定的命名空间仅限于你希望JSX消耗的反应道具或字段.

这三种形式是等同的:

-   `this.bindings.count`
-   `this.$.count`
-   `this.bind('count')`

它们都通过相同的缓存绑定对象解决.

当 :

-   制成的元素结构保持不变
-   只需修改文本、属性或子值位置
-   您想要渲染器补丁自有的孩子区域, 而不是重运行整个组件视图

使用 `@onUpdated(...)` 与 `update()` 或者说 `requestUpdate()` 当反应性变化应该重建JSX树时.

## 安全部门改革 还有水分

选择主机 HTML 的服务器管道 :

-   导入 `@ecopages/radiant/server/install-ssr-runtime` 一次在服务器后缀(shim + ALS 瞄准镜适配器)
-   `renderComponent(...)` 编号 : `renderComponentToString(...)` 从 `@ecopages/radiant/server/render-component` 适配器和碎片
-   `renderRadiantElementHostToString(...)` 从 `@ecopages/radiant/server/radiant-element-ssr` 用于低级主机序列化
-   `renderRadiantElementViewToString(host, options)` 从 `@ecopages/radiant/server/radiant-element-ssr` 只序列化 JSX 视图

没有持久元素主机实例 API 命名 `renderHostToString()`。 。 。 . `renderComponent()` 序列化每个主机一次,并将标记为 `preview`;它不序列化主机第二次.

`mode: 'hydrate'` 增加组件视图的水分标记,并加盖每个串行主机的邮票 `data-radiant-ssr` 属性。 一个主机读了该邮票一次,一开始连接,进入 `isServerRendered`使用它,没有 `hasHydrationMarkers`,以说明一个主机的内容是否来自服务器:标记只存在于视图有约束的地方,JSX儿童应用到自定义元素上,因为光 DOM 没有携带. 普通模式主机没有被盖章并报告 `false`· ; `renderRadiantElementViewToString(host, options)` 只返回已准备的视图,所以写主机标签本身的呼叫者必须添加 `SERVER_RENDERED_HOST_ATTRIBUTE` (从 `@ecopages/radiant/server/radiant-element-ssr`) (中文(简体) ). 主机读取后会取出印章,因为水分标记被取出,所以连接的主机不再携带. 服务器内发送的分档内容会保留服务器的节点,或者来自带有其印章的分档模板,所以它会报告 `true`。在另一个主机的视图中,一个渲染所有主机保持其服务器节点、状态和焦点,当母机水合物出现时,它会报告 `true` ; 其中一个父视图重建( 其标签只在母视图水合后定义, 或者服务器标记与视图不符) 报告 `false`。一个没有自己绑定的页面根在这样的嵌入式主机被水化或自制后仍然可以重新连接,即使从此更新,当该页面的静态标记匹配时. 首通水分明确: SSR 页面应导入 `@ecopages/radiant/client/install-hydrator` 在装入组件模块之前, 或调用 `installRadiantHydrator()` 从 `@ecopages/radiant/client/hydrator` 在自定义元素升级前。 没有那个客户端的水合器门,SSR主机会回到第一个连接上的新客户端渲染.

因为拉迪安特的苏维埃 `window` 财务报告和审定财务报表 `document`,全球检查像 `typeof window !== 'undefined'` 或者说 `typeof document !== 'undefined'` 评估到 `true` 在服务器上。 守护顶级活动听众 `document` 或者说 `window` 与 `!isServer` 从 `@ecopages/radiant/is-server` 因此浏览器导航和事件听众在SSY期间不附加. 此旗帜遵循软件包导出条件, 所以它读作 `true` 节点工人、德诺工人、邦工人、云浮工人(`workerd`)和Vercel Edge (英语:`edge-light`即便安装了DOM shim `false` 在浏览器捆绑中( `browser` 在任何未规定任何条件的运行时间内。 使用一个DOM能力检查代码,这取决于特定的DOM方法.

`createResource(...)` 在作者属性同步后,从 Element 主机客户端开始连接通过。 SSR 序列化从不启动资源获取,无论活跃的软件包出口条件如何. 对于服务器传输的数据,在渲染前获取并通过 `initialize`, (中文(简体) ), `prepareHost`,或主机属性.

服务器运行时间设置、碎片渲染辅助器和针对 SSR 的导入指导均在 [弧形/服务器/README.md](https://npmcn.com/package/%40ecopages/radiant/src/server/README.md)。 。 。 .

关于客户使用寿命周期和水分流量图,见 [弧度/分数/README.md](https://npmcn.com/package/%40ecopages/radiant/src/core/README.md)。 。 。 .

## 事件处理

Radiant不发明合成事件层. JSX处理器和装饰器直接与本地浏览器事件对象合作.

| 使用这个 | 你想什么时候 | 运行时形状 |
| --- | --- | --- |
| `on:*` 在联合来文十中 | 一般事件 API | 自动指定一个固定的缓冲事件授权列表,然后回到直接听众那里 |
| `on-native:*` 在联合来文十中 | 精确元素级浏览器听取语义 | 总是打电话 `addEventListener(...)` 关于该要件 |
| `@onEvent(...)` | 班级听从 `RadiantElement` | 支助 `selector`, (中文(简体) ), `ref`, (中文(简体) ), `window`,以及 `document` 目标 |
| `@event(...)` | 组件所属的自定义事件发送器 | 发送一个真实 `CustomEvent` 从主机元素 |

### JSX事件如何约束工作

`on:*` 是默认 JSX 事件 API。 对于一个固定的缓冲事件允许列表,Radiant在渲染根上附加每个事件类型的一个收听器并发送到匹配的元素上. 对于所有其他事件, `on:*` 直接附在元素上.

今天,授权的许可名单是:

-   `beforeinput`
-   `click`
-   `contextmenu`
-   `dblclick`
-   `focusin`
-   `focusout`
-   `input`
-   `keydown`
-   `keyup`
-   `mousedown`
-   `mouseout`
-   `mouseover`
-   `mouseup`
-   `pointerdown`
-   `pointerout`
-   `pointerover`
-   `pointerup`
-   `touchend`
-   `touchmove`
-   `touchstart`

使用 `on-native:*` 当精确的附加语义关系,例如当一个祖先在委托的根听器运行之前可能停止传播,或者当您要选择不授权进行一个支持的起伏事件时.

许可列表以外的事件,例如 `focus`, (中文(简体) ), `blur`, (中文(简体) ), `scroll`, (中文(简体) ), `load`, (中文(简体) ), `invalid`,或 `dragstart`时,已直接附加 `on:*`。 。 。 .

### `@onEvent(...)`

在班级一级, `@onEvent(...)` 是 DOM 事件的主要装饰者。 它可以听:

-   匹配 CSS 选择器的后人
-   以 `data-ref`
-   主办方本身(`host: true`),包括非突发事件,例如: `pointerenter` 财务报告和审定财务报表 `pointerleave`
-   全球 `window` 事件
-   全球 `document` 事件

```tsx
/** @jsxImportSource @ecopages/jsx */

import { RadiantElement, customElement, onEvent, state } from '@ecopages/radiant';

@customElement('keyboard-panel')
export class KeyboardPanel extends RadiantElement<{ lastKey: string }> {
    @state lastKey = 'none';

    @onEvent({ document: true, type: 'keydown' })
    protected onKeydown(event: KeyboardEvent): void {
        this.lastKey = event.key;
    }

    override render() {
        return <p>Last key: {this.$.lastKey}</p>;
    }
}
```

基于选择器和参考器 `@onEvent(...)` 处理者,以及 `subscribeEvent(...)` 编号 : `subscribeEvents(...)`,与 `Element.closest(...)` 从事件目标,所以点击一个被嵌入的图标仍然会得到包接 `button[data-ref]` 或选择者匹配。 他们仍然依赖出血,所以使用 `focusin` 财务报告和审定财务报表 `focusout` 改为 `focus` 财务报告和审定财务报表 `blur` 对于这个模式.

每个 `subscribeEvent(...)` 登记是独立的,包括重复 `type` 财务报告和审定财务报表 `selector` 双人 不订阅一个收听器不会去除另一个收听器,断开会去除所有剩余的注册.

### `@event(...)`

使用未执行的组件活动 `@event(...)`,使该类得到一个键入 `EventEmitter`调用 `.emit(detail)` 发送一个真实 `CustomEvent` 从主机元素.

```ts
import type { EventEmitter } from '@ecopages/radiant/tools/event-emitter';
import { RadiantElement, customElement, event } from '@ecopages/radiant';

type SaveDetail = {
    id: string;
};

@customElement('save-button')
export class SaveButton extends RadiantElement {
    @event({ name: 'save-requested', bubbles: true, composed: true })
    saveRequested!: EventEmitter<SaveDetail>;

    requestSave(): void {
        this.saveRequested.emit({ id: 'draft-1' });
    }
}
```

心理模式很简单:

-   DOM事件通过JSX处理器或 `@onEvent(...)`
-   活动组成部分 `@event(...)`
-   二者都是运行时的普通浏览器事件

## 发展警告

当授权时, radiant 日志记录开发警告 `@onEvent(...)` 听众使用非缓冲事件类型, 例如 `focus`,当一个标签在视图显示后被定义时。 警告需要两个拉迪安 `process.env.NODE_ENV` 开发门和共享 `@ecopages/jsx` 切换 : `setDevWarningsEnabled(false)` 关闭两个软件包,同时 `true` 或者说 `undefined` 让他们再次。 已出版的文件保存 `process.env.NODE_ENV` 检查是否打开它们, 所以应用程序的构建决定了, 而不是Radiant的: 当捆绑者设置时警告显示 `process.env.NODE_ENV` 给除 `"production"`,一个生产建筑会把它们和文字一起删除。 生产建设取决于捆绑工: `"production"` 用于浏览器平台的构建,并带有微量化, Vite for `vite build` 除非 `NODE_ENV` 说不然,网络包装 `mode: "production"`,本为 `--production`。一个没有捆绑器加载文件的页面,其中 `process` 不存在,没有警告,也没有错误.

JSX水分和DOM主播警告来自: `@ecopages/jsx` ,并遵循自己的开关;见“Dev警告”中 [jSX读取](https://github.com/ecopages/radiant/blob/main/packages/jsx/README.md#dev-warnings)。 。 。 .

贡献者: 将开发警告封入 `try { if (process.env.NODE_ENV !== 'production' && areJsxDevWarningsEnabled()) { ... } } catch {}`编辑 `try` 保存一个没有 `process` 从投出, 并保持两个检查里面 它让每个捆绑者 投出块生产 `warnNonBubblingDelegatedEvent` 内 `src/helpers/create-event-listener.ts` 财务报告和审定财务报表 `setChildrenValue` 内 `src/core/render-runtime.ts`。 。 。 . `test/build/dist-dev-warnings.test.ts` 已建成时失败 `dist` 文件已读取 `process.env.NODE_ENV` 将一个应用程序捆绑起来 `dist` 用于发展,用于生产,而支票没有被替换. `test/build/dist-dev-warnings.browser.test.ts` 在Chromium中运行一个开发程序, 并生产一个应用程序, 并进行检查 `console.warn`。两者各自运行 `node-dist` 财务报告和审定财务报表 `browser-dist` vitest项目,项目 `globalSetup` (单位:千美元)`test/build/dist-global-setup.ts`)仅在一个 `test/build` 文件在运行中。 它会重建 `dist` 与 `build:lib` 当内容散列 `build.ts`, (中文(简体) ), `package.json`,两个 `tsconfig` 文档, `scripts` 财务报告和审定财务报表 `src` 与最后一栋楼记录的不一样(`node_modules/.cache/dist-source-hash`),所以一个白空间编辑不需要手动构建. 下 `CI` 它永远不会重建,只需要 `dist` ; 失败的重建点 `pnpm --filter @ecopages/radiant build:lib`。 。 。 .

## 公共条目

这些是软件包所暴露的有文献记载的公开进口路径.

| 路径 | 用于 |
| --- | --- |
| `@ecopages/radiant` | 主要客户入境点. 再出口 `RadiantElement`, (中文(简体) ), `RadiantController`,反应性的JSX绑定,常见的装饰器,以及控制器-注册辅助器,例如: `startControllers(...)` |
| `@ecopages/radiant/context` | 与背景有关的出口作为分组的切入点 |
| `@ecopages/radiant/context/create-context` | 创建上下文键 |
| `@ecopages/radiant/context/context-provider` | 低级上下文提供者类 |
| `@ecopages/radiant/context/consume-context` | `@consumeContext(...)` 装饰 |
| `@ecopages/radiant/context/provide-context` | `@provideContext(...)` 装饰 |
| `@ecopages/radiant/context/context-selector` | `@contextSelector(...)` 装饰者——将一个字段绑上上下文 |
| `@ecopages/radiant/context/on-context-update` | `@onContextUpdate(...)` 装饰器 — 运行上下文变化的方法 |
| `@ecopages/radiant/context/events` | 上下文请求/ 订阅事件类型 |
| `@ecopages/radiant/controller-registry` | 主计长登记和激活辅助人员 |
| `@ecopages/radiant/core/radiant-element` | 非JSX反应自定义元素基础 |
| `@ecopages/radiant/core/radiant-controller` | DOM 随附控制器基础 |
| `@ecopages/radiant/form-associated-element` | `FormAssociatedElement` 本地列表中主机的基数 `FormData` |
| `@ecopages/radiant/helpers/create-query` | 组件字段的低级查询帮助器 |
| `@ecopages/radiant/helpers/create-event` | 低级别自定义事件帮助器 |
| `@ecopages/radiant/helpers/create-event-listener` | 低级别 DOM 事件听众帮助器 |
| `@ecopages/radiant/helpers/debounce` | 没有装饰器表面的跳出助手 |
| `@ecopages/radiant/is-server` | 布尔旗( B)`isServer`用于服务器和浏览器环境之间的分支 |
| `@ecopages/radiant/client/hydrator` | SSR页面的明确客户端水合器安装器和状态帮助器 |
| `@ecopages/radiant/client/install-hydrator` | 副作用入口,在组件模块加载前允许先连接水分 |
| `@ecopages/radiant/client/app-bootstrap` | `prepareRadiantApp(...)` app- shell 靴子陷阱助手 |
| `@ecopages/radiant/signals/host-resource` | 低级 `HostResource`, (中文(简体) ), `createHostResource(...)`,以及 `createResource(...)` 帮助者 |
| `@ecopages/radiant/server/install-ssr-runtime` | 副作用服务器启动项:光-DOM shim 外加 JSX SSR 瞄准镜适配器 |
| `@ecopages/radiant/server/install-light-dom-shim` | 仅安装副作用 shim( 偏好) `install-ssr-runtime` 用于全苏维埃社会主义共和国) |
| `@ecopages/radiant/server/light-dom-shim` | 最小 SSR 窗口和主机准备助手 |
| `@ecopages/radiant/server/radiant-element-ssr` | 低级主机序列化( :`renderRadiantElementHostToString` 默认为普通模式;见 `src/server/README.md` 用于完整出口级) |
| `@ecopages/radiant/server/render-component` | Canonical 组件 SSR 帮助器; 默认水合物模式 |
| `@ecopages/radiant/server/render-controller` | 控制器- 主机 SSS 帮助器和特定控制器主机选项类型 |
| `@ecopages/radiant/server/project-root` | 用于服务器适配器的项目根解析器 |
| `@ecopages/radiant/decorators/attr` | `@attr(...)` |
| `@ecopages/radiant/decorators/bind-to` | `@bindTo(...)` |
| `@ecopages/radiant/decorators/bound` | `@bound` |
| `@ecopages/radiant/decorators/controller` | `@controller(...)` |
| `@ecopages/radiant/decorators/custom-element` | `@customElement(...)` |
| `@ecopages/radiant/decorators/debounce` | `@debounce(...)` |
| `@ecopages/radiant/decorators/event` | `@event(...)` |
| `@ecopages/radiant/decorators/on-event` | `@onEvent(...)` |
| `@ecopages/radiant/decorators/on-updated` | `@onUpdated(...)` |
| `@ecopages/radiant/decorators/prop` | `@prop(...)` |
| `@ecopages/radiant/decorators/query` | `@query(...)` |
| `@ecopages/radiant/decorators/signal` | `@signal(...)` |
| `@ecopages/radiant/decorators/state` | `@state` |
| `@ecopages/radiant/tools/escape-script-json` | 安全 JSON 序列化帮助工具 |
| `@ecopages/radiant/tools/event-emitter` | 低级 `EventEmitter` 帮助者 |

`ValueFieldDecorator`, (中文(简体) ), `BoundedFieldDecorator` 并导出它们命名的主机类型 `@ecopages/radiant` (单位:千美元)`ContextHostLike` 财务报告和审定财务报表 `ContextUpdateMethod` 从 `@ecopages/radiant/context`),因此是一个导出共享装饰器的库,例如 `export const count = prop({ type: Number })`,可以发出声明.

当捆绑大小重要或者当一个模块只需要一个狭窄的运行时间表面时,优先选择有焦点的公共子路径. 根入点仍然是通用应用代码的ergonomic默认值,但上下文,注册,帮助者,服务器,信号资源,和低级工具的导入则更好取自其明确的公共子路径.

对于控制器的编写,倾向于每个模块单导入表面. 如果一个文件混合 `RadiantController`, (中文(简体) ), `@controller(...)`, (中文(简体) ), `@state`, (中文(简体) ), `@attr(...)`,或 `startControllers(...)`默认为 `@ecopages/radiant` 因此,控制器注册和启动来自同一切入点.

重要:上下文 API,控制器注册帮助器,帮助器工厂,服务器 API,和低等工具都有明确的公共子路径. 偏好这些对库和适配器代码的有重点路径,或者当一个模块有意想要的仅仅是注册运行时间,而没有更广泛的客户端表面;根入点仍然是普通客户端表面的ergonomic App入点.

关于安全部门改革的具体指导和实例,见 [弧形/服务器/README.md](https://npmcn.com/package/%40ecopages/radiant/src/server/README.md)。 。 。 .

## 常见问题

### 如何安装 @ecopages/radiant？

在项目目录运行 npm install @ecopages/radiant，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@ecopages/jsx（\>=0\.8\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ecopages/radiant 支持 TypeScript 吗？

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

### @ecopages/radiant 支持 ESM 还是 CommonJS？

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

### @ecopages/radiant 可以商用吗？

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

### @ecopages/radiant 的下载量有多少？

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

### @ecopages/radiant 还在维护吗？

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