快速上手#

HTML 的所有标签都可以在 Lessjs HTML 中使用，但有些标签我们可以用 Lessjs 组件来替换使用，功能更加强大。例如 <img> 标签可以用 spz-img 组件来替换。

#先读结论

• 想快速跑通页面，先掌握三个点：layout、模板渲染、@tap 交互。
• 若组件不渲染或布局异常，优先检查是否配置了 layout 与尺寸。
• 若交互不生效，优先检查目标 id 和动作表达式（如 hello.hide）是否匹配。

#最小可运行路径（3 步）

1. 用 spz-img 渲染一个固定尺寸图片，确认布局配置正确。
2. 用 spz-render + <template> 渲染一段数据，确认模板与数据源可用。
3. 给按钮加 @tap 动作，确认事件和方法链路可执行。

#预备知识

文档接下来的内容会假设你对 HTML、CSS、JavaScript 和 Web Components 已经有所了解。如果你对前端开发完全陌生，最好是掌握了基础知识再回到这里。如果之前有其他框架的经验会很有帮助，但也不是必须的。

#了解布局

在网页上放置元素时，Lessjs 遵循更严格的规则。在常规 HTML 网页上，你几乎完全使用 CSS 来放置元素。但是，出于性能原因考虑，Lessjs 要求所有元素从一开始就必需设置显示大小，所以每个组件元素都必需要配置 layout 属性。

#添加图片

大多数 HTML 标记都可以直接在 Lessjs HTML 中使用，但某些标记（例如 <img> 标记）被替换为性能更优的 spz-img 组件使用。

在下面例子中，我们使用固定宽高的布局来对图片元素进行占位。在 fixed 布局中，必需配置确定的宽度和高度。这时图片展示的宽度和高度与我们布局配置的宽度和高度一致。

<spz-img
  layout="fixed"
  height="300"
  width="300"
  src="https://img.staticdj.com/5236bc0a95a0196e21bc3b52fcabab3f.jpeg"
  alt="Landscape image"
  class="rounded-xl"
></spz-img>

在上面例子中，除了 layout 属性还配置了 src 属性，它包含了你想要嵌入的图片路径，这是必要的。

#使用模板

页面中有些内容是需要通过接口请求后返回数据来渲染 DOM 元素的，这时候我们需要使用到模板来编写不在页面中呈现的标记模板，让数据请求成功后，才渲染模板内容，将渲染结果展示到页面中。

在下面例子中，spz-render 使用本地的 JSON 数据来渲染模板内容。

在页面中使用 application/json 类型的脚本生成一个 JSON 数据。

<script id="render-data" type="application/json">
  {
    "name": "John von Neumann",
    "brief": "He was a Hungarian-American mathematician, physicist, computer scientist, engineer and polymath.",
    "imageSrc": "https://img.staticdj.com/5da228ddd934fd6ffecb3f95e985ee5a.gif"
  }
</script>

然后，在 spz-render 中使用生成的 JSON 数据作为数据来源。

<spz-render layout="container" src="script:render-data">
</spz-render>

然后，在 spz-render 中使用模板，在模板内，只能有一个根元素。使用 ${} 来获取模板的数据。

<spz-render layout="container" src="script:render-data">
  <template>
    <div>
      ${data.name}
    </div>
  </template>
</spz-render>

最后，将所有数据取出呈现在页面中。

<script id="render-data" type="application/json">
  {
    "name": "John von Neumann",
    "brief": "He was a Hungarian-American mathematician, physicist, computer scientist, engineer and polymath.",
    "imageSrc": "https://img.staticdj.com/5da228ddd934fd6ffecb3f95e985ee5a.gif"
  }
</script>

<spz-render layout="container" src="script:render-data">
  <template>
    <div class="m-flex m-p-4 m-mx-auto m-bg-white m-shadow-sm m-rounded-xl" style="width: 480px;">
      <spz-img
        layout="fixed"
        width="80"
        height="80"
        src="${data.imageSrc}"
        alt="${data.name}"
        object-fit="cover"
        auto-fit
        class="m-flex-shrink-0 m-rounded-full m-overflow-hidden"
      ></spz-img>
      <div class="m-ml-6 m-text-left">
        <p class="m-font-bold m-pb-2">${data.name}</p>
        <div>${data.brief}</div>
      </div>
    </div>
  </template>
</spz-render>

#方法和事件

Lessjs 支持交互式用户体验。但是，为了保证页面性能和用户体验，它与非 Lessjs 页面的做法略有不同。

Lessjs 使用 @eventName 在元素上安装事件处理程序。与属性一样，一些事件和方法可用于所有元素，而另一些则专门用于某些组件。以下我们将注册一个基本事件，既用户的点击，然后使用隐藏操作进行响应。

在页面中添加一个按钮，并为其赋予 @tap 属性：

<button @tap="">
  Goodbye Lessjs HTML!
</button>

然后，我们添加定义的 id（我们希望我们的动作对其产生影响的目标）。我们将隐藏我们的 <h3 id="hello"> 元素，所以我们在属性值中添加"hello"。

<button @tap="hello">
  Goodbye Lessjs HTML!
</button>

最后添加一个英文句号（.），然后定义动作。在当前情况下，它是 hide。

<button @tap="hello.hide">
  Goodbye Lessjs HTML!
</button>

现在，如果我们点击我们的按钮，<h3> 元素就会被隐藏。

<h3 id="hello">Hello Lessjs HTML!</h3>

<button @tap="hello.hide">
  Goodbye Lessjs HTML!
</button>

#常见误区

• 把 layout 当成可选项：在 Lessjs 里，组件布局信息通常是必需的。
• 模板写多个根节点：<template> 内必须只有一个根元素。
• 只写目标 id 不写动作：@tap="hello" 不会执行，需要写成 @tap="hello.hide" 这类完整表达式。

#AI 使用建议（LLM Ready）

• 章节密度：检测到 5 个二级标题。
• 示例密度：检测到 9 个代码块。
• 先读结论：优先提取本页“定义、约束、边界条件”。
• 再读证据：根据代码示例确认可执行写法，不直接依赖自然语言段落。
• 最后联动：涉及组件时同步查看对应组件页，避免文档与实现偏差。