# @amazon/vinyl-tsx 中文文档

规范地址：https://npmcn.com/package/%40amazon/vinyl-tsx/

版本：5\.0\.0
npm 元数据更新时间：2026-11-16T02:15:02.572Z
中文译文更新时间：2026-11-16T03:09:02.998Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40amazon/vinyl-tsx
原文对照：https://npmcn.com/package/%40amazon/vinyl-tsx/?lang=original
项目主页：https://github.com/amazonmusic/vinyl#readme
源码仓库：https://github.com/amazonmusic/vinyl

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

- 包体积（解压后）：491 kB，78 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-05-27T23:27:19.443Z
- 最新版本发布：2026-11-16T02:15:01.983Z
- 近 30 天下载量：2062（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

创建 UI 的 TSX 声明标记

## 安装

```sh
npm install @amazon/vinyl-tsx
```

也可以使用：`pnpm add @amazon/vinyl-tsx`、`yarn add @amazon/vinyl-tsx`、`bun add @amazon/vinyl-tsx`

## README

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

[![Website](https://img.shields.io/badge/website-amazonmusic.github.io%2Fvinyl-blue)](https://amazonmusic.github.io/vinyl) [![npm](https://img.shields.io/npm/v/@amazon/vinyl-tsx.svg)](https://www.npmjs.com/package/@amazon/vinyl-tsx) [![size](https://img.shields.io/bundlejs/size/@amazon/vinyl-tsx.svg?label=size)](https://bundlejs.com/?q=@amazon/vinyl-tsx)

轻而易举的 JSX 运行时间,用于创建动态 DOM 元素 类型脚本支持. 提供构建用户界面的宣示方式 通过 [`@amazon/vinyl-observable`](https://npmcn.com/package/%40amazon/vinyl-observable)。 。 。 .

## 特征

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

## 安装

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

## 基本用途

### 建立联合来文十

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

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

### 创建元素

```tsx
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`,字符串,可观察到其中之一或数组 孩子们 包括嵌入式阵列在内的阵列被平整,所以列表不需要 已分发 :

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

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

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

```tsx
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`,数字和其他值正在编译出错; 明确转换:

```tsx
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:

```tsx
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 样式 :

```tsx
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` 属性 :

```tsx
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 类 值 :

```tsx
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 连接或断开时执行代码 :

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

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

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

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

### 事件处理器

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

```tsx
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`数字 :

```tsx
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>
    </>
)
```

## 自定义组件

```tsx
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!')} />
```

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

```tsx
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` 钩到被动显示或隐藏内容 :

```tsx
const showDetails = data(false)

const userCard = (
    <div>
        <h3>John</h3>
        <div visible={showDetails}>
            <p>Email: john@example.com</p>
        </div>
        <button onclick={() => (showDetails.value = !showDetails.value)}>
            Toggle Details
        </button>
    </div>
)
```

## 最佳做法

1.  **初始化连接的观察员** 在您的应用程序中启用一次 生命周期管理:
    
    ```tsx
    import { initializeConnectedObserver } from '@amazon/vinyl-tsx'
    
    const cleanup = initializeConnectedObserver()
    ```
    
2.  **对动态内容使用可观察值** - 偏好观测值 属性随时间变化.
    
3.  **杠杆钩子扩展** —— 说 `style`, (中文(简体) ), `visible`,以及 `classList` 覆盖大部分 常见的DOM操纵.
    
4.  **类型安全** 让TypeScript检查你的道具和孩子.
    
5.  **内存管理** ——可观察订阅自动清理 当元素断开时.
    

## 许可证

阿帕奇 - 2.0

## 常见问题

### @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 和提交记录判断。

