FAQ

2025-08-29 03:32

Can I use an embedded webview on a specific page while integrating it with a component?

No, this is not supported.

How can I listen for the keyboard show/hide events?

You can listen for the keyboard show/hide events through either of the following two methods:

Monitor input field focus changes. See the following code sample for details:

.axml

copy
<input bindfocus="onInputFocus" bindblur="onInputBlur" />

.js

copy
Page({
  onInputFocus() {
    console.log('keyboard show');
  },
  onInputBlur() {
    console.log('keyboard hide');
  }
});

Use the onKeyboardHeight event listener. See the following code sample for details:

copy
events: {
  onBack() {
    console.log('onBack');
},
  
onKeyboardHeight(e) {
    // Triggers when the keyboard height changes
    console.log('Keyboard height:', e.height);
    // Use height > 0 to detect keyboard display
 }
}

How can I track a scroll event after scrolling a specific distance (e.g., 20 pixels)?

You can track scroll events by using the onPageScroll method provided by the mini program framework. For example, the following code checks if the scroll distance (scrollTop) exceeds 20 pixels and updates the navigation bar title accordingly:

copy
onPageScroll(e) {
  const { scrollTop } = e;
  let titleOpacity = 1 - scrollTop * 0.02;
  let shadow = false;

  if (scrollTop > 20) {
    my.setNavigationBar({
      title: 'Miniprogram test demo',
    });
  } else {
    my.setNavigationBar({
      title: ' ',
    });
  }
},

Can mini programs customize system-level keyboards provided by the operating system, such as iOS and Android?

No, this feature is not supported.

How can I fix the issue where my mini program works on iOS but reports an error on Android when useDynamicPlugins is enabled?

The error occurs because Android does not support the useDynamicPlugins configuration. To fix this, remove the useDynamicPlugins setting from your configuration file.

Can I use Jest for unit testing of mini programs?

Yes, the Jest unit testing framework is supported for testing mini programs.

How do I resolve the `my is not defined` error in HTML5 mini programs?

This error occurs if the JavaScript bridge (JS bridge) is not fully loaded before calling JSAPIs. To ensure the bridge is ready, add an event listener to delay JSAPI execution as follows:

copy
window.document.addEventListener('AlipayJSBridgeReady', function() {
// Safely call JSAPIs here
}

How do I fix script errors in HTML5 mini programs?

To fix this error, add the following meta tag to your HTTP header. Replace https://example.com with your trusted domains to specify allowed script sources:

copy
<meta http-equiv="Content-Security-Policy" content="script-src 'self' https://example.com 'unsafe-eval'">

Can I create user groups to assign different levels of access in the documentation center, such as granting a specific third-party merchant access to a particular document?

No, this feature is not supported.

How do I restrict input to numbers only on Android's numeric keyboard?

To enforce numeric input on Android, configure the following two files of the page:

The .axml file

On the <input> component, set enableNative to true and type to number. This ensures the native Android's numeric keyboard is used. See the following code sample for details:

copy
<input enableNative= "{{true}}" type= "number" onInput="bindKeyInput" value="{{inputValue}}" controlled={{true}}>

The .js file

Use a regular expression to filter non-digit characters from the user input. See the following code sample for details:

copy
bindKeyInput(e) {

  let value = e.detail.value;
  if (value && !/^\d*$/.test(value)) {
    value = value.replace(/[^\d]/g, '');
  }
  this.setData({
    inputValue: value
  });

}

How do I reset a form programmatically by calling the `form.reset` method instead of clicking a button?

You cannot use the form.reset method in this case, because the my.createSelectorQuery JSAPI's SelectorQuery.select('#userForm') method cannot obtain the form node. To reset a form without a button click, you can bind the UI elements to your JavaScript data and update their values dynamically. The following code samples show how to reset an input field when a radio button selection changes:

.axml

copy
<view>
    <radio-group onChange="radioChange">
      <view>
        <radio id="phone" value="phone number" />
        <label >phone number</label>
      </view>
      <view>
        <radio id="account" value="account" />
        <label for="account">Account number</label>
      </view>
    </radio-group>
  
    <input type="text" value="{{inputValue}}" onInput="inputChange"/>
  </view>

.js

copy
Page({
  data: {
    inputValue: ''
  },
  radioChange: function(e) {

    this.setData({
      inputValue: '' 
    });
  },

  inputChange: function(e) {
    this.setData({
      inputValue: e.detail.value
    });
  }
});

Why does the `crypto.getRandomValues` method throw an error when using `uuidv4` to generate UUIDs?

This error occurs because uuidv4 relies on crypto.getRandomValues, which is incompatible with mini programs. To bypass the crypto.getRandomValues issue, use uuidv5 instead of uuidv4 to generate UUIDs. The following figure shows the uuidv5 syntax:

Based on the syntax, uuidv5 generates a UUID based on a name and a namespace. This means the same namespace and name combination will always produce the same UUID. To ensure the uniqueness of the UUIDs, you must guarantee that the name values are unique. You can achieve this by combining a timestamp with a random number to generate the name value. See the following code sample for details:

copy
import { v5 as uuidv5 } from 'uuid'

...
onShow() {
    console.log('App Show');
    this.generateUUID();
  },

  generateUUID() {
    const MY_NAMESPACE = '1b671a64-5d3d-476c-9bc3-69d489546b1b';
    console.log('Generated UUID: ', uuidv5(this.generateUniqueRandom(), MY_NAMESPACE));
    console.log('Generated UUID: ', uuidv5(this.generateUniqueRandom(), MY_NAMESPACE));
    console.log('Generated UUID: ', uuidv5(this.generateUniqueRandom(), MY_NAMESPACE));
    console.log('Generated UUID: ', uuidv5(this.generateUniqueRandom(), MY_NAMESPACE)); 
  },

  generateUniqueRandom() {
    const timestamp = new Date().getTime();
    const randomPart = Math.floor(Math.random() * 1000);
    const uniqueRandom = timestamp + '' + randomPart;
    return uniqueRandom;
  },

The console output is as follows:

copy
App Show
Generated UUID:  ef52cd45-a45b-5045-a4c9-bf4262f9fdc4
Generated UUID:  c6ec36fc-7e4c-5149-8a8a-f6c53c7baf8b
Generated UUID:  5f54a68f-d358-5314-ae65-a48bbb5c22aa
Generated UUID:  d2bdb13b-65fe-5258-9197-c4461b5970af

Note that reusing the same name value generates duplicate UUIDs. The following code sample shows an incorrect example:

copy
import { v5 as uuidv5 } from 'uuid'

...
onShow() {
  console.log('App Show');
  this.generateUUID();
},

generateUUID() {
  const MY_NAMESPACE = '1b671a64-5d3d-476c-9bc3-69d489546b1b';
  // The first and last entries reuses the name value "hello world"
  console.log('Generated UUID: ', uuidv5('hello world', MY_NAMESPACE));
  console.log('Generated UUID: ', uuidv5('hello', MY_NAMESPACE));
  console.log('Generated UUID: ', uuidv5('123', MY_NAMESPACE));
  console.log('Generated UUID: ', uuidv5('hello world', MY_NAMESPACE));

In this case, the console output shows identical UUIDs for the first and last entries:

copy
App Show
Generated UUID:  871db4e1-16fe-5487-983e-66db413517c5
Generated UUID:  a27d140c-fe69-5870-9d92-9e0b640b8ef9
Generated UUID:  4caed476-b846-5fce-a0c4-29333565d9c8
Generated UUID:  871db4e1-16fe-5487-983e-66db413517c5

How do I configure the transparency and alignment of a mini program's title bar?

For mini program developers:

You can configure the transparency of the title bar using the following attributes in the global or page-specific configuration:

window.titleBarColor: Sets the title bar's background color.
window.transparentTitle: Sets the title bar's background mode (e.g., transparent or opaque).

For more information, refer to the Global configuration.

For super apps:

You can set both the transparency and alignment of the mini program's title bar using startup parameters when calling the SDK's methods to open the mini program:

For Android, refer to the following documents:

For iOS, refer to the following documents:

Why does the No Privilege error occur when using the WebView component?

You can try to solve the problem by the following checklist:

Add required H5 domains to the whitelist under Mini Program > Configuration > Authorization List > WAP URLs.
Release the mini program in your environment, which can be sandbox environment, test environment, or development environment. Otherwise, the updated configuration does not take effect.

If you can't solve the problem with the provided solution, contact the technical support team of your site.

Does the mini program support SVG and gradient?

Yes. Progressive web apps (also referred to as H5) and the image component in native mini programs support SVG. Progressive web apps support gradient. SVG is used in user authentication, such as sliding the verification picture.

FAQ