weapp-share-timeline

WeChat Mini Program Share to Moments Development Guide

Supported in base library 2.11.3+, Android/iOS WeChat 8.0.24+

Quick Configuration

Enable Share to Moments

A page must satisfy both conditions to be shared to Moments:

1. First enable "Send to Friends": implement onShareAppMessage
2. Then enable "Share to Moments": implement onShareTimeline

Native Mini Program Example

Page({
  // 1. 必须先启用"发送给朋友"
  onShareAppMessage() {
    return {
      title: '分享标题',
      path: '/pages/article/index?id=123',
      imageUrl: '/images/share.png'
    }
  },

  // 2. 再启用"分享到朋友圈"
  onShareTimeline() {
    return {
      title: '朋友圈分享标题',
      query: 'id=123',  // 注意：不是 path，是 query
      imageUrl: '/images/timeline-share.png'
    }
  }
})

Taro Example

import Taro, { useShareAppMessage, useShareTimeline } from '@tarojs/taro'

function ArticlePage() {
  // 1. 必须先启用"发送给朋友"
  useShareAppMessage(() => ({
    title: '分享标题',
    path: '/pages/article/index?id=123',
    imageUrl: '/images/share.png'
  }))

  // 2. 再启用"分享到朋友圈"
  useShareTimeline(() => ({
    title: '朋友圈分享标题',
    query: 'id=123',
    imageUrl: '/images/timeline-share.png'
  }))

  return <View>文章内容</View>
}

export default ArticlePage

onShareTimeline Return Parameters

Property	Type	Description
title	string	Share title, defaults to the Mini Program name
query	string	Parameters carried in the custom page path, such as id=123&type=news
imageUrl	string	Share image URL, supports local or network images

Note：onShareTimeline use query rather than path, custom page paths are not supported.

Single Page Mode (Single Page Mode)

When a user opens a shared Mini Program page from Moments, they enter "Single Page Mode", which is a special restricted runtime environment.

Single Page Mode Features

1. Fixed Navigation Bar: the top displays the title configured in the page JSON, which cannot be customized
2. Fixed Action Bar: there is a "Go to Mini Program" button at the bottom
3. Scene Value：scene === 1154
4. No Login State: the user is not logged in, and user information cannot be obtained
5. Storage Isolation: local storage is not shared with normal mode

Detect Single Page Mode

// 原生小程序
const scene = wx.getLaunchOptionsSync().scene
const isSinglePage = scene === 1154

// Taro
import Taro from '@tarojs/taro'

const launchOptions = Taro.getLaunchOptionsSync()
const isSinglePage = launchOptions.scene === 1154

// 或使用 wx.getApiCategory (基础库 2.22.1+)
const apiCategory = wx.getApiCategory()
const isBrowseOnly = apiCategory === 'browseOnly'  // 朋友圈快照页

Page Adaptation Example

import Taro, { useLoad } from '@tarojs/taro'
import { View, Text, Button } from '@tarojs/components'
import { useState } from 'react'

function ArticlePage() {
  const [isSinglePage, setIsSinglePage] = useState(false)
  const [article, setArticle] = useState(null)

  useLoad(() => {
    const scene = Taro.getLaunchOptionsSync().scene
    setIsSinglePage(scene === 1154)

    // 单页模式下使用未登录访问方式获取数据
    fetchArticle()
  })

  const fetchArticle = async () => {
    // 单页模式下无登录态，需使用公开接口
    const res = await Taro.request({
      url: 'https://api.example.com/public/article',
      data: { id: articleId }
    })
    setArticle(res.data)
  }

  return (
    <View className="article-page">
      <View className="content">
        <Text>{article?.title}</Text>
        <RichText nodes={article?.content} />
      </View>

      {/* 单页模式下隐藏需要登录的交互 */}
      {!isSinglePage && (
        <View className="actions">
          <Button onClick={handleLike}>点赞</Button>
          <Button onClick={handleComment}>评论</Button>
        </View>
      )}
    </View>
  )
}

navigationBarFit Configuration

Configure in the page JSON navigationBarFit to adjust the intersecting state between the top navigation bar and the page:

{
  "navigationBarTitleText": "文章详情",
  "navigationBarFit": "squeezed"
}

Value	Description
float	The navigation bar floats above the page (default)
squeezed	The page is squeezed by the navigation bar and starts layout below the navigation bar

Disabled Capabilities in Single Page Mode

Disabled Components

Component	Description
button open-type	Open capability buttons
camera	Camera component
form	Form components
navigator	Navigation components
web-view	Web container
live-pusher	Live streaming

Disabled APIs

Category	API
Login	wx.login、wx.checkSession、wx.getUserInfo、wx.getUserProfile
Routing	wx.navigateTo、wx.redirectTo、wx.reLaunch、wx.switchTab、wx.navigateBack
Media	wx.chooseImage、wx.chooseMedia、wx.chooseVideo、wx.saveImageToPhotosAlbum
Location	wx.openLocation、wx.chooseLocation、wx.startLocationUpdate
Payment	wx.requestPayment
Sharing	wx.showShareMenu、wx.hideShareMenu、wx.updateShareMenu、wx.getShareInfo
Device	Bluetooth, Wi-Fi, NFC, clipboard, scanning code, phone
Ads	ad component,wx.createRewardedVideoAd、wx.createInterstitialAd

Other Restrictions

• Landscape orientation is not allowed
• tabBar will not be rendered (including custom tabBar)
• Local storage is not shared with normal mode
• Cloud development requires enabling unauthenticated access

Best Practices

1. Content-type pages are preferred

Sharing to Moments is suitable forpure content displayscenarios:

// 推荐：文章、新闻、产品详情等内容页
function ArticlePage() {
  useShareTimeline(() => ({
    title: article.title,
    query: `id=${article.id}`,
    imageUrl: article.cover
  }))
  // ...
}

// 不推荐：需要大量交互的页面
function ShoppingCartPage() {
  // 购物车需要登录，不适合分享到朋友圈
}

2. Graceful degradation

function ContentPage() {
  const [isSinglePage, setIsSinglePage] = useState(false)

  useLoad(() => {
    setIsSinglePage(Taro.getLaunchOptionsSync().scene === 1154)
  })

  const handleAction = () => {
    if (isSinglePage) {
      // 单页模式下引导用户打开完整小程序
      Taro.showToast({
        title: '请点击下方"前往小程序"使用完整功能',
        icon: 'none',
        duration: 2000
      })
      return
    }
    // 正常模式下执行操作
    doSomething()
  }

  return (
    <View>
      <Button onClick={handleAction}>
        {isSinglePage ? '前往小程序操作' : '立即操作'}
      </Button>
    </View>
  )
}

3. Use public APIs

// 单页模式下无登录态，设计公开接口
const fetchData = async (articleId: string) => {
  // 使用不需要登录的公开接口
  const res = await Taro.request({
    url: `${API_BASE}/public/articles/${articleId}`,
    method: 'GET'
    // 不传 token
  })
  return res.data
}

4. Safe area adaptation

function ContentPage() {
  const [isSinglePage, setIsSinglePage] = useState(false)

  useLoad(() => {
    setIsSinglePage(Taro.getLaunchOptionsSync().scene === 1154)
  })

  return (
    <View
      className="page"
      style={{
        // 单页模式下底部有操作栏，需要额外 padding
        paddingBottom: isSinglePage ? '80px' : 'env(safe-area-inset-bottom)'
      }}
    >
      {/* 页面内容 */}
    </View>
  )
}

5. Unauthenticated access to Cloud Development

If you use Cloud Development, you need to enable unauthenticated access in cloud functions:

// 云函数 config.json
{
  "permissions": {
    "openapi": []
  },
  "overrideUserSecurityRules": {
    "allow": true  // 允许未登录访问
  }
}

Operational considerations

1. Inducing sharing is prohibited: Users must not be forced to share, and sharing must not immediately grant benefits
2. Content completeness: Single-page mode should present complete content, and users must not be forced to click "Open Mini Program"
3. Compliant use: Abuse of sharing capabilities for marketing, inducement, and similar behavior will be cracked down on by the platform

FAQ

Q: Why didn't the Share to Moments button appear?

A: Check the following points:

1. Whether both onShareAppMessage and onShareTimeline
2. Whether the WeChat version is >= 8.0.24
3. Whether the base library version is >= 2.11.3

Q: How do I obtain user data in single-page mode?

A: Single-page mode has no login state, so you need to:

1. Pass user-related information through the query parameter
2. Use public APIs to obtain data
3. Cloud Development requires unauthenticated access to be enabled

Q: What are the requirements for sharing images?

A:

• Supports local images or network images
• It is recommended to use square images (1:1 ratio)
• It is recommended that the image size not exceed 128KB

Complete documentation

See reference.md