@winner-fed/native-bridge-methods

v1.8.5

Published

4 months ago

Invest in the native bridging method provided by winner APP

0High
0Medium
0Low

winner-fed

native app bridge

Winner JS-API

为 APP 提供的原生桥接方法 JS-SDK，支持在 H5 页面中调用 APP 原生功能。

📦 安装

# 使用 npm
npm install @winner-fed/native-bridge-methods

# 使用 yarn
yarn add @winner-fed/native-bridge-methods

# 使用 pnpm
pnpm add @winner-fed/native-bridge-methods

⚠️ 重要依赖： 此 SDK 需要 light-sdk 作为对等依赖（peerDependency），请务必安装：
npm install light-sdk
# 或
yarn add light-sdk
# 或
pnpm add light-sdk

🚀 快速开始

import { nativeReady, getUserInfo, getStorage } from '@winner-fed/native-bridge-methods'

// 等待原生环境准备就绪
nativeReady({
  success: () => {
    console.log('原生环境已准备就绪')

    // 获取用户信息
    getUserInfo({
      success: (result) => {
        console.log('用户信息:', result)
      },
      fail: (error) => {
        console.error('获取用户信息失败:', error)
      },
    })
  },
})

// 使用 Promise 方式
async function demo() {
  try {
    const data = await getStorage({ key: 'userToken' })
    console.log('存储数据:', data)
  } catch (error) {
    console.error('读取存储失败:', error)
  }
}

📱 平台兼容性

LightOS 离线包：运行在 Light 容器中的 H5 应用
在线版本：运行在 App WebView 中的 H5 应用
Android & iOS：支持双平台原生功能调用

🔧 API 分类

基础功能

nativeReady / nativeReadySync - 原生环境准备检测
isLightOS - 检测是否为 LightOS 环境
isHarmonyOS - 检测是否为鸿蒙系统
getVersion - 获取 APP 版本信息

用户相关

getUserInfo - 获取用户信息
getUserMobile / getUserMobileSync - 获取用户手机号
getUserCorpRiskLevel / getUserCorpRiskLevelSync - 获取用户风险等级
getCorpRiskLevel - 获取企业风险等级

账户相关

getFundAccountInfo - 获取资金账户信息
getFundAccountAndPassword / getFundAccountAndPasswordSync - 获取资金账户和密码
getFundAccountLoginStatus / getFundAccountLoginStatusSync - 获取资金账户登录状态
getUserFundAccountToken / getUserFundAccountTokenSync - 获取用户资金账户 Token
getTradeLoginStatus - 获取交易登录状态

登录相关

evokeFundAccountLogin / evokeFundAccountLoginSync - 唤起资金账户登录
evokeMobileLogin / evokeMobileLoginSync - 唤起手机号登录
evokeRegister / evokeRegisterSync - 唤起注册

存储相关

setStorage / setStorageSync - 设置本地存储
getStorage / getStorageSync - 获取本地存储
removeStorage / removeStorageSync - 删除本地存储

导航相关

navigate / navigateTo - 页面导航
forwardPage / forwardPageSync - 页面跳转
openPage / openPageSync - 打开页面
nativeNavigateLink - 原生导航链接
navigateToStockDetail / navigateToStockDetailSync - 跳转到股票详情页
closeWebview - 关闭当前页面

股票相关

getStockInfo - 获取股票信息
getSelfStock / getSelfStockSync - 获取自选股
getHoldStockList - 获取持仓股票列表
checkIsMyStock - 检查是否为自选股

分享相关

socialSharing - 社交分享
shareSocialScreenShot / shareSocialScreenShotSync - 分享屏幕截图
shareSocialThirdParty / shareSocialThirdPartySync - 第三方分享

页面生命周期

viewAppearSync - 页面显示回调
viewDisappearSync - 页面隐藏回调
appAppearSync - 应用前台回调
appDisappearSync - 应用后台回调

其他功能

getClientId / getClientIdSync - 获取客户端 ID
getPhone - 获取手机号
getFinanceVisibility / getFinanceVisibilitySync - 获取财务可见性
setFinanceVisibility / setFinanceVisibilitySync - 设置财务可见性

📖 API 详细说明

回调函数模式

大部分 API 支持传统的回调函数模式：

import { getUserInfo } from '@winner-fed/native-bridge-methods'

getUserInfo({
  success: (result) => {
    // 成功回调
    console.log('获取成功:', result)
  },
  fail: (error) => {
    // 失败回调
    console.error('获取失败:', error)
  },
  complete: (result) => {
    // 完成回调（无论成功或失败都会执行）
    console.log('操作完成:', result)
  },
})

Promise 模式

部分 API 同时支持 Promise 模式，方便使用 async/await：

import { getStorage, setStorage } from '@winner-fed/native-bridge-methods'

// Promise 模式
getStorage({ key: 'token' })
  .then((result) => {
    console.log('获取成功:', result)
  })
  .catch((error) => {
    console.error('获取失败:', error)
  })

// async/await 模式
async function handleStorage() {
  try {
    await setStorage({ key: 'token', value: 'abc123' })
    const result = await getStorage({ key: 'token' })
    console.log('存储结果:', result)
  } catch (error) {
    console.error('操作失败:', error)
  }
}

存储 API

import { setStorage, getStorage, removeStorage } from '@winner-fed/native-bridge-methods'

// 设置存储
await setStorage({
  key: 'userPreference',
  value: { theme: 'dark', language: 'zh-CN' },
  scope: 'user', // 存储域
  domain: 'file', // file: 持久化存储, memory: 内存存储
})

// 获取存储
const data = await getStorage({
  key: 'userPreference',
  scope: 'user',
})

// 批量获取
const multiData = await getStorage({
  multi_param: [
    { key: 'token', scope: 'auth' },
    { key: 'userId', scope: 'user' },
  ],
})

// 删除存储
await removeStorage({
  key: 'userPreference',
  scope: 'user',
})

分享 API

import { socialSharing } from '@winner-fed/native-bridge-methods'

// 分享网页
socialSharing({
  shareTitle: 'App',
  shareDescription: '专业的投资理财平台',
  shareUrl: 'https://example.com',
  shareType: '68', // 68: 分享web
  success: () => {
    console.log('分享成功')
  },
})

// 分享图片
socialSharing({
  shareTitle: '图片分享',
  shareDescription: '精彩图片',
  sharePicUrl: 'https://example.com/image.jpg',
  shareType: '66', // 66: 分享图片
  success: () => {
    console.log('图片分享成功')
  },
})

导航 API

import { navigateToStockDetail, forwardPage } from '@winner-fed/native-bridge-methods'

// 跳转到股票详情页
navigateToStockDetail({
  stockCode: '000001',
  stockType: '1', // 股票类型
  success: () => {
    console.log('跳转成功')
  },
})

// 通用页面跳转
forwardPage({
  url: 'native://page/trading',
  params: { tab: 'buy' },
  success: () => {
    console.log('页面跳转成功')
  },
})

🔗 接口参数说明

通用回调参数

| 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | ---- | ------------------------------------------ | | success | Function | 否 | 接口调用成功的回调函数 | | fail | Function | 否 | 接口调用失败的回调函数 | | complete | Function | 否 | 接口调用结束的回调函数（成功失败都会执行） |

存储接口参数

| 参数名 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ---------------------------------------- | | key | String | 是 | 存储数据的键名 | | value | Any | 否 | 存储的数据值（设置时需要） | | scope | String | 否 | 存储域 | | domain | String | 否 | 存储类型：file（持久化）、memory（内存） | | multi_param | Array | 否 | 批量操作参数 |

分享接口参数

| 参数名 | 类型 | 必填 | 说明 | | ---------------- | ------ | ---- | -------------------------------------------- | | shareTitle | String | 是 | 分享标题 | | shareDescription | String | 是 | 分享描述内容 | | shareUrl | String | 否 | 分享链接（网页分享时必填） | | sharePicUrl | String | 否 | 分享图片地址（图片分享时必填） | | shareType | String | 是 | 分享类型：65（文字）、66（图片）、68（网页） |

⚠️ 注意事项

版本兼容性：文档中标注 V7 的接口适用于 APP 7.x 版本
环境检测：建议在调用其他 API 前先使用 nativeReady 检测环境
错误处理：务必添加 fail 回调或 try-catch 来处理异常情况
数据加密：部分接口返回加密数据，需要使用相应的解密方法
性能考虑：避免频繁调用桥接方法，适当使用缓存

🔍 调试技巧

// 开启调试模式
import { isLightOS } from '@winner-fed/native-bridge-methods'

if (isLightOS()) {
  console.log('当前运行在 LightOS 原生 webview 环境')
} else {
  console.log('当前运行在浏览器环境')
}

📄 许可证

ISC License