> For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt.

# 组合元件

一个 Lynx 页面中可能包含了文字、图片不同的视觉要素，通过不同的布局方式，来呈现出不同的页面样式。本节希望帮助大家了解如何构建最基本的视图。

## 元素标签：界面的基础构建单元

Lynx 通过标记语言来定义内容和结构，其最基础的单元是一个[元素标签](/next/zh/guide/spec.md#element-tag)。元素标签的概念类似 [HTML 元素](https://developer.mozilla.org/en-US/docs/Glossary/Element)，元素标签可以用来包围不同部分的内容，使其以某种方式呈现或者工作。

与 HTML 不同的是，Lynx 中使用一些其独有的元素标签，如 [`<view>`](/next/zh/api/elements/built-in/view.md)、[`<text>`](/next/zh/api/elements/built-in/text.md) 和 [`<image>`](/next/zh/api/elements/built-in/image.md)，来展示不同的内容。
例如，在 Lynx 中，下面的源代码可以用于展示一段文字：

```html
<text>Hello Lynx</text>
```

### 元素标签的构成

元素标签的基本用法与 [HTML 元素](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content#anatomy_of_an_html_element)非常类似：

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_tags.png)
每一个元素标签都由以下几个部分组成：

1. **开始标签**：包含元素标签的名称（本例为 text），及一对包围名称的尖括号。表示元素标签从这里开始。
2. **结束标签**：与开始标签相似，只是其在元素名之前包含了一个正斜杠。这表示元素标签到这里结束。
3. **内容**：元素标签的内容，对于 `<text>` 元素标签来说就是所输入的文本本身。

开始标签、结束标签与内容相结合，便是一个完整的元素标签。

### 属性

每个元素标签都有自己的属性（Attribute），可以通过在元素标签标签中添加属性名和属性值来设置，用于描述其行为和外观。

例如，每个元素标签上可以使用 [`style`](/next/zh/api/elements/built-in/view.md#style)、[`class`](/next/zh/api/elements/built-in/view.md#class) 等属性来设置背景、圆角、阴影样式，支持部分 CSS 语法。下面的代码可以设置一个元素的背景色为红色：

```html
<text style="background:red;">Hello Lynx</text>
```

本例中，`style` 是属性名，`background:red` 是属性值。

更多属性可以查看 [API 参考](/next/zh/api/elements/built-in/view.md)。

### 空元素标签

有些元素标签没有内容，例如 `<image>` 元素标签：

```html
<image src="assets/logo.png" />
```

它没有使用 `</image>` 结束标签，元素标签里也没有内容。这是因为 `<image>` 元素标签使用属性 `src` 而非通过内容来达到展示图片的目的。

### 嵌套元素标签

元素标签可以被嵌套在其他元素标签中。例如，多个 `<text>` 元素标签可以被嵌套在一个 `<view>` 元素标签中：

```html
<view>
  <text>Hello</text>
  <text>Lynx</text>
</view>
```

### 元件树

在源代码中的元素标签会在运行时被 Lynx 引擎解析，翻译成用于渲染的[元件](/next/zh/guide/spec.md#element)。
嵌套的元素标签会形成由元件组成的一棵树，我们称之为[元件树](/next/zh/guide/spec.md#element-tree)，我们依赖这种树结构来构建和管理更加复杂的界面。

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_tree.png)
## 内置元件

Lynx Engine 默认内置一些最基础的元件来帮你快速构建页面。

### 视图

`<view>` 是一个最基础的元件，常用于包裹其他元件并承载一些绘制能力。例如，下面的代码将整个视图的背景色为灰色，并为其内部的文本留出一定的间距：

```html
<view style="padding:10px;background:gray;">
  <text>Hello Lynx</text>
</view>
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_hello_lynx_gray.png)
### 文本

刚才已经提到 `<text>` 元件用于展示文本内容。例如，下面的代码可以用于展示一段文字：

```html
<text>Hello Lynx</text>
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_hello_lynx.png)
### 图片

`<image>` 元件用于展示图片。例如，下面的代码可以用于展示一张图片：

```html
<image auto-size style="width:100px;" src="assets/logo.png" />
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_lynx_logo.png)
### 更多内置元件

更多内置元件可以参考[元件 API 参考](/next/zh/api/elements/built-in/view.md)。

### XElement

XElement 是由 Lynx 团队维护的扩展原生元件库，提供更丰富的组件能力，帮助在生产环境中更快地落地 Lynx，并促进 Lynx 生态的发展。

使用 XElement 前需要先将其集成到原生工程中，详见[接入现有应用](/next/zh/guide/start/integrate-with-existing-apps.md)。

## 元件的背后：原生渲染

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_2_na.png)
Lynx 元件是与平台无关的统一抽象。它们将被 Lynx 引擎原生渲染为平台各自的 UI 原语，比如 iOS 与 Android 中的原生视图，或 Web 中的 HTML 元素（包括[自定义元素](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)）。以下是 Lynx 一些内置元件和它们在不同的平台上的对应或类比：


| 元件                                                               | Android             | iOS                          | HarmonyOS        | Web 类比                         | 说明                                |
| :--------------------------------------------------------------- | :------------------ | :--------------------------- | :--------------- | :----------------------------- | :-------------------------------- |
| [`<view>`](/next/zh/api/elements/built-in/view.md)               | `ViewGroup`         | `UIView`                     | `Stack`          | 不可滚动的 `<div>`                  | 基础视图容器，多用于承载布局能力、进行样式绘制以及包裹其他元素   |
| [`<text>`](/next/zh/api/elements/built-in/text.md)               | `TextView`          | `UITextView`                 | `Text`           | `<p>`                          | 用于显示文本内容。可以对齐指定特定的文字样式            |
| [`<image>`](/next/zh/api/elements/built-in/image.md)             | `ImageView`         | `UIImageView`                | `Image`          | `<img>`                        | 用于显示不同类型的图，包括网络图片、静态资源、和来自本地磁盘的图片 |
| [`<scroll-view>`](/next/zh/api/elements/built-in/scroll-view.md) | `ScrollView`        | `UIScrollView`               | `Scroll`         | 指定 `overflow:scroll` 的 `<div>` | 基础的可滚动元件，支持横向和竖向。允许用户滚动以展示更多内容    |
| [`<list>`](/next/zh/api/elements/built-in/list.md)               | `RecyclerView`      | `UICollectionView`           | `List`           | 无                              | 高性能的可滚动元件，能通过自动懒加载和复用视图减轻内存压力     |
| [`<page>`](/next/zh/api/elements/built-in/page.md)               | 一个页面的`ViewRootImpl` | 一个页面的`UIViewController.view` | `@Entry`装饰的自定义组件 | 无法修改尺寸的 `<body>`               | 一个页面的根节点，大多数情况下无需手动添加             |

## 通过自定义元件拓展

如果内置元件无法满足你的需求，你可以通过自定义实现原生元件来扩展 Lynx 的能力。这是 Lynx 强大的特性之一。

具体内容请[参考扩展自定义元件文档](/next/zh/guide/custom-native-component.md)。

## 组件：将元件进行组合

在更复杂的 Lynx 视图结构中，各类不同种类的元件常常通过分层嵌套组合形成更加丰富多彩的界面单元。这正是前端框架中组件化开发的核心思想：通过可复用的封装单元实现界面的模块化构建。

在 ReactLynx 中，我们遵循 React 的开发范式，通过一个函数和 JSX 来对元件进行组装，并定义一个组件，其设计思路和基本原理都遵循了 [React 组件设计文档](https://react.dev/learn/describing-the-ui)，例如:


**下面是一个示例: composing-elements**

**Entry:** `src/App.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {7-10}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

export const App = ({ src }: { src: string }) => {
  return (
    <view>
      <image auto-size style="width:100px" src={src} />
      <text>Hello Lynx</text>
    </view>
  );
};

```



***

下一章，我们来给界面增加更丰富的样式。
