Cuttlefish Docs
  • English

    • Custom Components

    Lessjs supports custom components, allowing you to encapsulate reusable logic for use as a custom component.

    Custom components must be defined using spz-script, which requires a type="application/javascript" attribute to be used as a regular script. This is because, without configuring this attribute, spz-script scripts will be executed in a Web Worker, which currently cannot access SPZ-related global variables.

    Custom components are implemented based on ES6 class inheriting SPZ.BaseElement.

    Basic Usage

    In the example below, we define a spz-custom-component that only supports the container layout. In custom components, there are several functions to understand.

    Function NameDescription
    constructorThe class constructor, typically used to define some variables. It must use super(element); to correctly define the element by calling the parent class's constructor.
    isLayoutSupportedThe layouts supported by the component. It returns a boolean value, returning true if the current layout type is correct. The layout parameter value is the layout attribute configured when using the component. You can use layout-related functions and values defined by SPZCore to handle layout logic.
    buildCallbackBuild callback function. Triggered when the component starts building, usually used for initialization.
    mountCallbackBuild/Mount completion callback function. Triggered when the component has finished mounting, usually used for data requests.
    unmountCallbackCallback function before unmounting. Usually used to unload event listeners, reset variables, etc.
    <spz-custom-component layout="container"></spz-custom-component>

<spz-script layout="logic" type="application/javascript">
  class SpzCustomComponent extends SPZ.BaseElement {
    constructor(element) {
      super(element);
    }

    isLayoutSupported(layout) {
      return layout == SPZCore.Layout.CONTAINER;
    }

    buildCallback() {
      // ...
    }

    mountCallback() {
      // ...
    }

    unmountCallback() {
      // ...
    }
  }

  SPZ.defineElement('spz-custom-component', SpzCustomComponent);
</spz-script>

    Inside custom components, we can directly use the SPZCore object, SPZUtils object, and SPZServices object.

    Naming Convention

    Custom components must follow these naming conventions:

    • Custom component names must start with spz-custom-.
    • Private variables and functions end with _.
    • API methods thrown do not end with _.

    The this Object

    The this object in custom components is not exactly the same as in ordinary classes. The this object in custom components is an enhanced version of the this object in ordinary classes. We can access and get the following content through this:

    ParameterDescription
    this.elementGet the current component DOM element
    this.winGet the window object
    this.getViewport()Refer to Viewport Service

    AI Usage Notes (LLM Ready)

    • Section density: detected 2 level-2 headings.
    • Example density: detected 1 code blocks.
    • Read conclusions first: extract definitions, constraints, and boundary conditions.
    • Then verify with examples: rely on executable snippets rather than prose only.
    • Finally cross-check: open related component pages to avoid doc/runtime drift.