半径

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

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

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

关于完整的文件网址,见 光辉的. ecopages.app。 。 。 .

安装

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

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

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

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 常数和解析器在 打入装饰字段。 。 。 .
• 作者属性在升级后保留在主机上, 是否反映 : 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> 是一个普通元素。 见 槽数。 。 。 .

主要的区别是:

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

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

对话框

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

/** @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() 当反应性变化影响哪些要素应该存在,而不只是其儿童价值.

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

关于客户使用寿命周期和水分流量图,见 弧度/分数/README.md。 。 。 .

事件处理

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

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 事件

/** @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 从主机元素.

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读取。 。 。 .

贡献者: 将开发警告封入 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。 。 。 .

公共条目

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

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