Implementing WeChat Mini Program Share to Moments and Handling Single‑Page Mode

On July 7, 2020 WeChat Mini Program quietly opened a new capability – “Share to Moments”. This article introduces the feature, the associated “single‑page mode”, its limitations, and step‑by‑step implementation details.

Overview

Click the top‑right share button to open the Moments sharing UI (see screenshot below).

The shared Mini Program is displayed in a “single‑page mode” rather than the full Mini Program UI.

What is “single‑page mode”?

In single‑page mode the page has a fixed top navigation bar (title taken from the page’s JSON) and a fixed bottom operation bar with a “Go to Mini Program” button. Both bars do not support custom styling. The page content runs inside this container, which may affect layout, so developers need to adapt their UI accordingly.

Key restrictions in single‑page mode

Login state is unavailable; APIs such as wx.login cannot be used.

Navigation to other pages (including other Mini Programs or native WeChat pages) is prohibited.

Any tabBar (including custom tabBar) will not be rendered.

Local storage is isolated from the normal Mini Program mode.

Because of these limits, single‑page mode is suitable only for content display, not for heavy interaction.

Configuration

A new configuration field navigationBarFit is introduced to handle custom navigation bars. The default JSON looks like:

<span>{</span></code><code><span>  // ...</span></code><code><span>  "navigationStyle":"custom"</span></code><code><span>  // ...</span></code><code><span>}</span>

When a page uses a custom navigation bar, the single‑page mode will still render the custom bar, which conflicts with the fixed navigation bar requirement. Setting navigationBarFit to squeezed resolves the issue:

<span>{</span></code><code><span>  // ...</span></code><code><span>  "singlePage": {</span></code><code><span>    "navigationBarFit": "squeezed"</span></code><code><span>  }</span></code><code><span>  // ...</span></code><code><span>}</span>

After applying the setting, the UI adapts correctly (see screenshot below).

Implementation steps

1. Register the share button on the page that needs to be shared:

onShareAppMessage: function () {</code><code>  return {</code><code>    title: '转发标题',</code><code>    path: '/pages/home/index',</code><code>    imageUrl: '自定义图片路径'</code><code>  }</code><code>}

2. Register the Moments share API (available from base library 2.11.3):

onShareTimeline: function () {</code><code>  return {</code><code>    title: '转发标题',</code><code>    query: 'from=pyq',</code><code>    imageUrl: '自定义图片路径'</code><code>  }</code><code>}

Note: Moments sharing does not support a custom page path, so only the current page can be shared. If the current page relies heavily on restricted APIs, the display may be incorrect.

To handle this, two approaches are possible:

Modify the existing page to avoid calling restricted APIs when in single‑page mode.

Create a dedicated page/component for single‑page mode.

Detecting single‑page mode is done by checking the scene value (1154) in App.onLaunch:

// app.js
App({
  // ...
  onLaunch(options) {
    const { scene } = options;
    this.isSinglePage = scene === 1154;
  }
  // ...
})

Store the Boolean flag in the global App instance for easy access.

Solution 1 – Conditional logic

const app = getApp();
Page({
  // ...
  onLoad() {
    if (!app.isSinglePage) {
      wx.login({
        // ...
      })
    }
  }
  // ...
})

Solution 2 – Separate component

// pages/home/index.js
const app = getApp();
Page({
  data: {
    isSinglePage: app.isSinglePage,
  }
  // ...
})

// pages/home/index.json
{
  "usingComponents": {
    "home-single-page": "components/home-single-page/index"
  }
}

<!-- pages/home/index.wxml -->
<home-single-page wx:if="{{ isSinglePage }}" />
<view wx:else>
  <!-- Normal page content -->
</view>

When the page logic is complex, you can use an ExtendPage helper to disable all lifecycle methods in single‑page mode:

// common/extend-page/index.js
const app = getApp();
const PAGE_LIFE = [
  'onLoad','onReady','onShow','onHide','onError','onUnload',
  'onResize','onPullDownRefresh','onReachBottom','onPageScroll'
];
export default function(option) {
  let newOption = {};
  if (app.isSinglePage) {
    newOption = PAGE_LIFE.reduce((res, lifeKey) => {
      if (option[lifeKey]) {
        res[lifeKey] = undefined;
      }
      return res;
    }, {});
  }
  return Page({ ...option, ...newOption });
}

If you still need some lifecycle handling in single‑page mode, define a singlePageLife object and let ExtendPage map the appropriate methods:

// pages/home/index.js
import ExtendPage from 'common/extend-page/index';
const app = getApp();
ExtendPage({
  data: { isSinglePage: app.isSinglePage },
  singlePageLife: {
    onLoad() { /* ... */ }
  }
});

// common/extend-page/index.js (updated)
const app = getApp();
const PAGE_LIFE = [
  'onLoad','onReady','onShow','onHide','onError','onUnload',
  'onResize','onPullDownRefresh','onReachBottom','onPageScroll'
];
export default function(option) {
  let newOption = {};
  if (app.isSinglePage) {
    const { singlePageLife } = option;
    newOption = PAGE_LIFE.reduce((res, lifeKey) => {
      if (singlePageLife && singlePageLife[lifeKey]) {
        res[lifeKey] = singlePageLife[lifeKey];
      } else if (option[lifeKey]) {
        res[lifeKey] = undefined;
      }
      return res;
    }, {});
  }
  return Page({ ...option, ...newOption });
}

These techniques allow the Mini Program to work correctly when opened from Moments while keeping the normal page behavior unchanged.

Any omissions or errors are welcome for feedback.