@amazon/vinyl-tsx

中文文档
5.0.0发布于 2026/11/16Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 2062

创建 UI 的 TSX 声明标记

中文使用文档
文档目录18 节
  1. 特征
  2. 安装
  3. 基本用途
  4. 建立联合来文十
  5. 创建元素
  6. 儿童
  7. 反应属性
  8. Hook 扩展
  9. 样式钩
  10. 可见钩
  11. 阶级胡克
  12. 连接钩
  13. 事件处理器
  14. 碎片
  15. 自定义组件
  16. 有条件渲染
  17. 最佳做法
  18. 许可证

@amazon/ vinyl-tsx (中文(简体) )

Website npm size

轻而易举的 JSX 运行时间,用于创建动态 DOM 元素 类型脚本支持. 提供构建用户界面的宣示方式 通过 @amazon/vinyl-observable。 。 。 .

特征

  • 反应属性 ——将可观测值绑定为更新的 DOM 属性 自动.
  • 钩子扩展 通过自定义钩子加强DOM操作(style, (中文(简体) ), visible, (中文(简体) ), classList) (中文(简体) ).
  • 生命周期管理 ——DOM自动清理和连接跟踪 要素.
  • 类型脚本支持 ——财产有公用设施类型的全型安全 提取.
  • 零依赖关系 无外部框架的轻量级运行时间 依赖性.
  • 业绩得到优化 与被动事件处理者进行高效更新 选择性渲染.

安装

npm install @amazon/vinyl-tsx @amazon/vinyl-util @amazon/vinyl-observable

基本用途

建立联合来文十

配置您的 TypeScript 编译器以使用 venyl-tsx JSX 厂:

// tsconfig.json
{
    "compilerOptions": {
        "jsx": "preserve",
        "jsxFactory": "jsx",
        "jsxFragmentFactory": "Fragment"
    }
}

创建元素

import { jsx } from '@amazon/vinyl-tsx'

// Basic element creation
const button = <button>Click me</button>

// With properties
const input = <input type="text" placeholder="Enter text" disabled={false} />

// With children
const container = (
    <div className="container">
        <h1>Title</h1>
        <p>Content goes here</p>
    </div>
)

儿童

一个孩子可以是一个 Node,字符串,可观察到其中之一或数组 孩子们 包括嵌入式阵列在内的阵列被平整,所以列表不需要 已分发 :

const items = ['One', 'Two', 'Three']

const list = (
    <ul>
        {items.map((item) => (
            <li>{item}</li>
        ))}
    </ul>
)

null, (中文(简体) ), undefined,以及 false 儿童被省略并创建节点,所以 可选内容可以内入:

function Greeting(props: { readonly user?: { readonly name: string } }) {
    return (
        <p>
            Hello{props.user && `, ${props.user.name}`}
            {props.user === undefined && <a href="/login">Sign in</a>}
        </p>
    )
}

儿童被打字检查. true,数字和其他值正在编译出错; 明确转换:

const count = 3
const enabled = false as boolean

<p>{count}</p> // Error: number is not a valid child
<p>{String(count)}</p> // OK
<p>{enabled}</p> // Error: boolean may be true
<p>{enabled && 'Enabled'}</p> // OK

类型脚本拓宽字元 false 儿时直接写给 boolean这样 <p>{false}</p> 也是一个错误.

反应属性

使用 @amazon/vinyl-observable 以自动创建被动特性 更新DOM:

import { data } from '@amazon/vinyl-observable'
import { jsx } from '@amazon/vinyl-tsx'

const count = data(0)
const isVisible = data(true)

const counter = (
    <div>
        <span>Count: {count}</span>
        <button onclick={() => count.value++}>Increment</button>
        <button visible={isVisible}>Toggle me</button>
    </div>
)

count.value = 5 // DOM updates to show "Count: 5"
isVisible.value = false // Button becomes hidden

Hook 扩展

样式钩

对静态值和可观测值都支持应用 CSS 样式 :

import { data } from '@amazon/vinyl-observable'

const color = data('red')
const fontSize = data('16px')

const styledDiv = (
    <div
        style={{
            color, // Observable value
            fontSize, // Observable value
            backgroundColor: 'blue', // Static value
            padding: '10px', // Static value
        }}
    >
        Styled content
    </div>
)

color.value = 'green' // Text color changes to green

可见钩

控制元素可见度与 visible 属性 :

const isVisible = data(true)

const conditionalElement = (
    <div visible={isVisible}>This element can be hidden/shown</div>
)

isVisible.value = false // Sets display: none
isVisible.value = true // Removes display property

阶级胡克

以静态字符串和/或可观察到的数组动态管理 CSS 类 值 :

const theme = data<string | null>('dark')

const element = <div classList={['base-class', theme]}>Content</div>

// Element has classes: base-class dark
theme.value = 'light' // Updates to: base-class light
theme.value = null // Updates to: base-class

连接钩

当元素与 DOM 连接或断开时执行代码 :

const element = (
    <div
        onConnect={(el) => {
            console.log('Element connected:', el)
            return () => {
                console.log('Element disconnected:', el)
            }
        }}
    >
        Content
    </div>
)

调用后接收其标记输入的元素, 因此元素特定 API 是 可用无铸模 :

const player = <video onConnect={(el) => void el.play()} /> // el: HTMLVideoElement

JSX 表达式本身总是被键入 JSX.Element (单位:千美元)HTMLElement(三); TypeScript不能按标签键入. 使用 onConnect,或打电话 jsx('video', {}) 直接,当您需要特定元素类型时.

事件处理器

触摸和滚动事件自动使用被动收听器:

const element = (
    <div
        ontouchstart={(e) => console.log('Touch start')}
        ontouchmove={(e) => console.log('Touch move')}
        onwheel={(e) => console.log('Wheel')}
        onmousedown={(e) => console.log('Mouse down')}
    >
        Interactive content
    </div>
)

碎片

将片段用于带包装器的组合元素 div 使用 display: contents数字 :

import { Fragment } from '@amazon/vinyl-tsx'

const list = (
    <Fragment>
        <li>Item 1</li>
        <li>Item 2</li>
    </Fragment>
)

const list2 = (
    <>
        <li>Item 1</li>
        <li>Item 2</li>
    </>
)

自定义组件

interface ButtonProps {
    text: string
    onClick: () => void
    variant?: 'primary' | 'secondary'
}

function Button({ text, onClick, variant = 'primary' }: ButtonProps) {
    return (
        <button className={`btn btn-${variant}`} onclick={onClick}>
            {text}
        </button>
    )
}

const myButton = <Button text="Click me" onClick={() => alert('Clicked!')} />

组成部分接受他们的子女作为第二个论点,如书面,无 平地取来. 该参数的类型决定了组件中哪些孩子 接受加价; 没有一个组件接受无:

import { type JsxChild } from '@amazon/vinyl-tsx'

function Card(props: { readonly title: string }, children: JsxChild[]) {
    return (
        <section className="card">
            <h2>{props.title}</h2>
            {children}
        </section>
    )
}

const card = (
    <Card title="Details">
        <p>Body</p>
    </Card>
)

<Button text="Hi" onClick={() => {}}>Child</Button> // Error: Button takes no children

有条件渲染

与React不同的是, vinyl-tsx 不重交——JSX表达式被评价一次 在创建时间。 使用 visible 钩到被动显示或隐藏内容 :

const showDetails = data(false)

const userCard = (
    <div>
        <h3>John</h3>
        <div visible={showDetails}>
            <p>Email: [email protected]</p>
        </div>
        <button onclick={() => (showDetails.value = !showDetails.value)}>
            Toggle Details
        </button>
    </div>
)

最佳做法

  1. 初始化连接的观察员 在您的应用程序中启用一次 生命周期管理:

    import { initializeConnectedObserver } from '@amazon/vinyl-tsx'
    
    const cleanup = initializeConnectedObserver()
    
  2. 对动态内容使用可观察值 - 偏好观测值 属性随时间变化.

  3. 杠杆钩子扩展 —— 说 style, (中文(简体) ), visible,以及 classList 覆盖大部分 常见的DOM操纵.

  4. 类型安全 让TypeScript检查你的道具和孩子.

  5. 内存管理 ——可观察订阅自动清理 当元素断开时.

许可证

阿帕奇 - 2.0

版本与发布记录

@amazon/vinyl-tsx 共发布 44 个版本,首次发布于 2026/05/28;过去 12 个月发布了 44 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/11/16今天
4.1.1-next.20261115174554next2026/11/16今天
4.1.1-next.202611151724472026/11/16今天
4.1.1-next.202611151644392026/11/16今天
4.1.1-next.202611150013552026/11/151 天前
4.1.1-next.202611131749092026/11/142 天前

其他发布通道:hotfix-chromos → 1.2.1,hotfix-close-drm-sessions → 1.2.2,next → 4.1.1-next.20261115174554。

关于 @amazon/vinyl-tsx 的常见问题

@amazon/vinyl-tsx 是什么?

创建 UI 的 TSX 声明标记

如何安装 @amazon/vinyl-tsx?

在项目目录运行 npm install @amazon/vinyl-tsx,或使用 pnpm add / yarn add / bun add。

@amazon/vinyl-tsx 支持 TypeScript 吗?

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

@amazon/vinyl-tsx 支持 ESM 还是 CommonJS?

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

@amazon/vinyl-tsx 可以商用吗?

@amazon/vinyl-tsx 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@amazon/vinyl-tsx 的下载量有多少?

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

@amazon/vinyl-tsx 还在维护吗?

最新版本 5.0.0 发布于 2026/11/16(今天);至今共发布 44 个版本,其中过去 12 个月发布了 44 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。