Cuttlefish Docs
  • 简体中文

    • 方法和事件

    {% from 'components/codeblock.macro.html' import codeblock %}

    方法通常是指通过组件元素的ID来调用该组件的方法去执行一些行为，例如 spz-lightbox 默认不在页面中展示，当我们想要它在页面中展示时，需要调用它的 open 方法来打开它。

    事件通常是指当组件内执行了某种操作完成后，组件内自动抛出完成某种行为后的事件。我们可以监听该事件来在某些行为完成后做一些其他逻辑。例如当 spz-lightbox 打开后，可以通过监听 @open 事件来调用组件的方法或全局方法来实现一些逻辑。

    先读结论

    • 你在 HTML 上写的 @tap、@open 等，是把“事件”映射到“动作/方法”的一段 DSL。
    • 最常见的三种用法：显示/隐藏、切换 class、滚动到某个元素。
    • 如果动作不生效，优先检查：目标 id 是否存在、方法名是否正确、是否写成了完整表达式（如 hello.hide）。

    最常用的 3 个例子

    1) 点击隐藏/显示

    <h3 id="hello">Hello Lessjs!</h3>
<button @tap="hello.hide">Hide</button>
<button @tap="hello.show">Show</button>

    2) 点击切换 class

    <div id="box" class="rounded-xl">Box</div>
<button @tap="box.toggleClass(class='m-bg-black')">Toggle background</button>

    3) 点击滚动到指定元素

    <div id="target">Target</div>
<button @tap="target.scrollTo(position='top')">Scroll to target</button>

    用法

    @eventName 通常用来监听元素的事件处理器。支持的事件取决于元素。

    语法的值时一种简单的域特定语言，形式为：

    @eventName="targetId.methodName[(arg1=value, arg2=value2, ...)]"

    有关语法中各个部分的说明，请参见下表。

    语法 描述 是否必需
    eventName 元素公开的事件名称 是
    targetId 元素的 DOM ID，或者是全局的 SPZ 对象 是
    methodName 适用于具有默认方法的元素。这是由目标元素（targetId 引用）公开并且您要在事件被触发时执行的方法 是
    arg=value 有些方法可以接受参数。这些参数的定义方式是使用括号将 key=value 表示法括起来，接受的值包括：
    • 带引号的字符串："string value" 或 'string value'
    • 布尔值：true 或 false
    • 数值：11 或 1.1
    • 以句点语法形式对事件数据的引用：event 或 event.someDataPropertyName
    		 否

    一个事件处理多个方法

    使用分号（;）将各个方法分隔开，按顺序对同一事件执行多个方法。

    @eventName="targetId.methodName(arg1=value);targetId2.methodName;"

    全局定义的事件和方法

    Lessjs 定义了全局 tap 事件，您可以在任何 HTML 元素（包括 Lessjs 元素 或 原生 HTML 元素）上监听事件。

    Lessjs 还定义了全局 show、hide、scrollTo、toggleClass 和 toggleAttribute 方法，您可以在任何 HTML 元素上触发这些方法。

    元素特有的事件

    *-所有元素

    事件说明
    tap点击/点按元素时触发

    输入元素

    事件 说明 元素 数据
    change 更改和提交元素时触发。 input
    event.min
    event.max
    event.value
    event.valueAsNumber
    input[type="radio"]
    input[type="checkbox"]
    		 event.checked
    select
    event.min
    event.max
    event.value
    input-debounced 在元素的值发生更改时触发。该事件与标准的 change 事件类似，但它仅在输入值停止更改并且经过 300ms 后才会触发。 可触发 input 事件的元素 与 change 事件数据相同
    input-throttled 在元素的值发生更改时触发。该事件与标准的 change 事件类似，但它仅在输入值发生更改时每 100ms 最多触发一次。 可触发 input 事件的元素 与 change 事件数据相同
    input-smooth 在元素的值发生更改时触发。该事件与标准的 input 事件类似。 可触发 input 事件的元素 与 input 事件数据相同

    元素特有的方法

    *(所有元素)

    方法说明
    show显示目标元素（移除目标元素的 hidden 属性）
    hide隐藏目标元素（给目标元素添加 hidden 属性）
    toggleClass(class=string, force=boolean)切换目标元素的类。force 为可选项，如果定义该属性，可确保在该属性设置为 true 时仅添加类而不移除类；在该属性设置为 false 时移除类而不添加类。
    toggleAttribute(key=string, value=string, force=boolean)切换目标元素的属性。force 为 true 时仅添加属性而不移除属性；在该属性设置为 false 时移除属性而不添加属性。
    scrollTo(position=string, duration=integer, target-id=string)将元素滚动到显示流畅的动画。duration 和 target-id 为可选项。duration 用于指定动画的时长（单位：毫秒）。如果未指定此属性，将使用相对于滚动差值不大于 500 毫秒的量。target-id DOM元素的 ID，用于指定滚动到某个元素的指定位置，如果未指定，默认元素在滚动后相对于视口的位置。position 可选值为 top、center 或 bottom 之一（默认值为 top）。
    focus使目标元素获得焦点。

    示例：

    {{ codeblock('actions-and-events', 'show-and-hide') }}

    全局方法

    全局的方法挂载在 SPZ 上，通过使用 SPZ.methodName 形式来调用。

    方法说明
    copy(text=string)将内容复制到粘贴板上。
    scrollTo(id=string)滚动到指定的元素位置。
    replaceUrlState([customName=string], reload=boolean)替换或添加URL参数。除了 reload 参数外，其余参数可以自定义。reload 为可选项，用于指定参数更新完后是否刷新页面。
    navigateTo(url=string)跳转到指定的页面。
    postMessage(id=string, data=any)给指定的 iframe 框架发送消息。
    history(type='back', defaultUrl=string)返回上一级页面，当不存在上一层页面时返回至defaultUrl

    示例：

    {{ codeblock('actions-and-events', 'copy') }}

    AI 使用建议（LLM Ready）

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