Builtin Function Extension Guide

This document summarizes the recommended extension pattern for A2UI builtin functions.

Goal

When adding a new builtin function, keep three concerns separated:

• function metadata for catalog construction
• function runtime handler registration
• function-specific business logic

The current implementation follows the same idea as builtin component registration.

Current Structure

• a2ui_library/src/main/ets/engine/functions/BuiltinFunctionBase.ets
  • shared base class for builtin functions
  • provides default asCatalogItem() implementation
  • provides default schemaProvider() and promptProvider() hooks
• a2ui_library/src/main/ets/engine/functions/OpenUrlFunction.ets
  • example builtin function implementation
• a2ui_library/src/main/ets/engine/functions/A2UIBasicFunctions.ets
  • aggregates builtin function instances
  • exposes catalog items, host context injection, and handler registration
• a2ui_library/src/main/ets/engine/functions/FunctionBridge.ets
  • bridge only
  • does not contain concrete builtin business logic

Extension Steps

1. Create one file per builtin function

Add a dedicated file under:

• a2ui_library/src/main/ets/engine/functions/

Example:

• ToastFunction.ets
• ClipboardFunction.ets
• NavigateFunction.ets

Each builtin function should own its own:

• function name
• schema provider
• prompt provider
• runtime handler
• optional host context dependency

2. Inherit from BuiltinFunctionBase

Use BuiltinFunctionBase as the common template.

Recommended shape:

import { common } from '@kit.AbilityKit';

import { BuiltinFunctionBase } from './BuiltinFunctionBase';
import { LocalFunctionArgs, LocalFunctionContext, LocalFunctionHandler, LocalFunctionResult } from './LocalFunction';

class ToastFunction extends BuiltinFunctionBase {
  private hostContext?: common.UIAbilityContext;

  constructor() {
    super('toast');
  }

  public override setHostContext(hostContext: common.UIAbilityContext | undefined): void {
    this.hostContext = hostContext;
  }

  public override createHandler(): LocalFunctionHandler {
    return (args: LocalFunctionArgs, context: LocalFunctionContext): LocalFunctionResult => {
      return this.execute(args, context);
    };
  }

  protected override schemaProvider(): () => string {
    return () => '';
  }

  protected override promptProvider(): () => { mode: number; prompt: string } {
    return () => {
      return { mode: 1, prompt: '' };
    };
  }

  private execute(args: LocalFunctionArgs, context: LocalFunctionContext): LocalFunctionResult {
    return undefined;
  }
}

export const toastFunction: ToastFunction = new ToastFunction();

3. Keep asCatalogItem() generated by the base class

BuiltinFunctionBase already standardizes catalog item creation.

By default it will:

• build a CatalogItem.forFunction(...)
• attach the function name
• use the subclass schemaProvider()
• use the subclass promptProvider()
• mark category as A2UI_STANDARD unless overridden in the constructor

So most new builtin functions only need to focus on:

• constructor name
• runtime handler
• schema/prompt customization

4. Register the builtin in A2UIBasicFunctions.ets

After creating the function file, add its singleton instance into the builtin list.

Current pattern:

const builtinFunctions: BuiltinFunctionBase[] = [
  openUrlFunction
];

Extend it like:

const builtinFunctions: BuiltinFunctionBase[] = [
  openUrlFunction,
  toastFunction,
  clipboardFunction
];

Once the instance is added here, the function is automatically used in:

• allA2UIBasicFunctions() for catalog assembly
• applyHostContextToBuiltinFunctions(...) for host context injection
• registerA2UIBuiltinFunctionHandlers(...) for bridge handler registration

5. Decide whether host context is needed

If the builtin needs system ability APIs, override:

• setHostContext(hostContext)

If not needed, just use the base implementation.

This keeps simple functions lightweight while still supporting context-dependent functions like openUrl.

Design Rules

• one builtin function, one file, one class, one exported singleton
• do not place business logic inside FunctionBridge.ets
• do not build catalog items inline in aggregation code
• keep schema and prompt definitions with the function itself
• keep runtime dependencies owned by the function class itself
• use A2UIBasicFunctions.ets only as an aggregator

Recommended Checklist

When adding a new builtin function:

1. create <Name>Function.ets
2. extend BuiltinFunctionBase
3. implement createHandler()
4. add or override schemaProvider() if needed
5. add or override promptProvider() if needed
6. implement setHostContext() only if needed
7. export a singleton instance
8. add the instance to builtinFunctions in A2UIBasicFunctions.ets
9. verify assembleHar
10. verify assembleHap

Existing Reference

Use this file as the reference implementation:

• a2ui_library/src/main/ets/engine/functions/OpenUrlFunction.ets