接口 Ymx

只读inApp

只读isAndroid

只读isHarmony

只读isIos

只读isWeb

只读sdkVersionCode

只读sdkVersionName

只读versionCode

只读versionName

chooseMedia

• chooseMedia(data: ChooseMediaData): Promise<ChooseMediaResult>

  拍摄或从手机相册中选择图片或视频

  参数

  • data: ChooseMediaData

  返回 Promise<ChooseMediaResult>

  示例

  ymx.chooseMedia({
    // 相册
    sourceType: ['album'],
    // 选一个
    count: 1,
    mediaType: ['image']
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

  示例

  ymx.chooseMedia({
    // 相册
    sourceType: ['album'],
    // 选 3 个
    count: 3,
    mediaType: ['image']
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

  示例

  ymx.chooseMedia({
    // 拍照
    sourceType: ['camera'],
    // 后置摄像头
    camera: 'back',
    mediaType: ['image']
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

  示例

  ymx.chooseMedia({
    // 拍照
    sourceType: ['camera'],
    // 前置摄像头
    camera: 'front',
    mediaType: ['video']
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

clearLayouts

• clearLayouts(): Promise<void>

  清空布局规则

  返回 Promise<void>

clearStorage

• clearStorage(): Promise<void>

  清理本地数据缓存

  返回 Promise<void>

  示例

  ymx.clearStorage().then(() => {
    alert('success');
  });
  复制

close

• close(result?: any): Promise<void>

  关闭当前窗口

  参数

  • 可选result: any

    需要返回给父窗口的数据

  返回 Promise<void>

  示例

  ymx.close()
    .then(() => {
      console.log('成功');
    })
    .catch((e) => {
      alert(`失败 ${JSON.stringify(e)}`);
    });
  复制

  示例

  // 带返回值的关闭，在 ymx.open() 的 onResult 函数中接收处理返回值
  ymx.close({
    hello: 'world 世界',
    year: 2026
  }).then(() => {
    console.log('成功');
  }).catch((e) => {
    alert(`失败 ${JSON.stringify(e)}`);
  });
  复制

compressImage

• compressImage(data: CompressImageData): Promise<CompressImageResult>

  压缩图片接口，可选压缩质量。

  参数

  • data: CompressImageData

  返回 Promise<CompressImageResult>

  示例

  ymx.chooseMedia({
    mediaType: ['image'],
    count: 1
  }).then(async (choose) => {
    // 压缩图片
    const res = await ymx.compressImage({
      src: choose.tempFiles[0].tempFilePath,
      compressedWidth: 480
    });
    alert(JSON.stringify(res));
  });
  复制

compressVideo

• compressVideo(data: CompressVideoData): Promise<CompressVideoResult>

  压缩视频接口。开发者可指定压缩质量 quality 进行压缩。当需要更精细的控制时，可指定 bitrate、fps、和 resolution，当 quality 传入时，这三个参数将被忽略。原视频的相关信息可通过 getVideoInfo 获取。

  参数

  • data: CompressVideoData

  返回 Promise<CompressVideoResult>

  示例

  ymx.chooseMedia({
    mediaType: ['video'],
    count: 1
  }).then(async (choose) => {
    // 压缩视频
    const res = await ymx.compressVideo({
      src: choose.tempFiles[0].tempFilePath,
      quality: 'medium'
    });
    alert(JSON.stringify(res));
  });
  复制

downloadFile

• downloadFile(data: DownloadFileData): Promise<DownloadFileResult>

  下载文件

  参数

  • data: DownloadFileData

  返回 Promise<DownloadFileResult>

  示例

  ymx.downloadFile({
    url: 'https://www.yimenapp.com/doc/doc.pdf'
  }).then(res => {
    alert(JSON.stringify(res));
  }).catch((err) => {
    alert(`download error: ${JSON.stringify(err)}`);
  });
  复制

emit

• emit(data: EmitData): Promise<void>

  触发一个事件

  参数

  • data: EmitData

  返回 Promise<void>

  示例

  ymx.emit({
    eventName: 'my-on',
    data: 'hello on'
  });
  复制

  示例

  ymx.emit({
    eventName: 'my-once',
    data: 'hello once'
  });
  复制

exit

• exit(): Promise<void>

  退出应用

  返回 Promise<void>

  示例

  ymx.exit();
  复制

getBatteryInfo

• getBatteryInfo(): Promise<GetBatteryInfoResult>

  获取设备电池信息

  返回 Promise<GetBatteryInfoResult>

  示例

  ymx.getBatteryInfo()
    .then(res => {
      alert(JSON.stringify(res));
    });
  复制

getDeclaredPermissions

• getDeclaredPermissions(): Promise<DeclaredPermissionsResult>

  获取应用已申明的权限清单

  返回 Promise<DeclaredPermissionsResult>

  示例

  ymx.getDeclaredPermissions()
    .then(res => {
      alert(JSON.stringify(res));
    });
  复制

getImageInfo

• getImageInfo(data: GetImageInfoData): Promise<GetImageInfoResult>

  获取图片信息。

  参数

  • data: GetImageInfoData

  返回 Promise<GetImageInfoResult>

  示例

  ymx.chooseMedia({
    mediaType: ['image'],
    count: 1
  }).then(async (choose) => {
    // 获取图片信息
    const res = await ymx.getImageInfo({
      src: choose.tempFiles[0].tempFilePath
    });
    alert(JSON.stringify(res));
  });
  复制

  示例

  ymx.getImageInfo({
    src: 'https://i.cdn.yimenapp.com/sys/1.jpg'
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

getKeepScreenOn

• getKeepScreenOn(): Promise<KeepScreenOnResult>

  获取是否保持常亮状态

  返回 Promise<KeepScreenOnResult>

  示例

  ymx.getKeepScreenOn()
    .then(res => {
      alert(res.isKeepScreenOn ? '常亮' : '非常亮');
    });
  复制

getLayout

• getLayout(): Promise<Layout>

  获取当前布局选项

  返回 Promise<Layout>

getLayouts

• getLayouts(): Promise<LayoutPattern[]>

  获取基于 URL 正则匹配模式的 UI 布局规则列表

  按顺序匹配 url，使用成功匹配项的 layout 设置，如果全部匹配失败则使用最后一项配置。

  返回 Promise<LayoutPattern[]>

getNavigationBar

• getNavigationBar(): Promise<NavigationBar>

  获取导航栏（底部虚拟按键区）

  返回 Promise<NavigationBar>

getScreenBrightness

• getScreenBrightness(): Promise<ScreenBrightness>

  获取屏幕亮度

  返回 Promise<ScreenBrightness>

  示例

  ymx.getScreenBrightness()
    .then(res => {
      alert(JSON.stringify(res));
    });
  复制

getScreenOrientation

• getScreenOrientation(): Promise<ScreenOrientation>

  获取屏幕方向

  返回 Promise<ScreenOrientation>

getStatusBar

• getStatusBar(): Promise<StatusBar>

  获取状态栏

  返回 Promise<StatusBar>

getStorage

• getStorage(data: StorageKey): Promise<StorageResult>

  从本地缓存中异步获取指定 key 的内容

  参数

  • data: StorageKey

  返回 Promise<StorageResult>

  示例

  ymx.getStorage({
    key: 'key1'
  }).then(res => {
    alert(res.data);
  });
  复制

  示例

  ymx.getStorage({
    key: 'key2'
  }).then(res => {
    alert(JSON.stringify(res.data));
  });
  复制

getStorageInfo

• getStorageInfo(): Promise<StorageInfoResult>

  异步获取当前 storage 的相关信息

  返回 Promise<StorageInfoResult>

  示例

  ymx.getStorageInfo().then(res => {
    alert(JSON.stringify(res));
  });
  复制

getTheme

• getTheme(): Promise<Theme>

  获取主题

  返回 Promise<Theme>

getTitleBar

• getTitleBar(): Promise<TitleBar>

  获取标题栏

  返回 Promise<TitleBar>

getVideoInfo

• getVideoInfo(data: GetVideoInfoData): Promise<GetVideoInfoResult>

  获取视频详细信息。

  参数

  • data: GetVideoInfoData

  返回 Promise<GetVideoInfoResult>

  示例

  ymx.chooseMedia({
    mediaType: ['video'],
    count: 1
  }).then(async (choose) => {
    // 获取视频信息
    const res = await ymx.getVideoInfo({
      src: choose.tempFiles[0].tempFilePath
    });
    alert(JSON.stringify(res));
  });
  复制

hasPermissionDeclared

• hasPermissionDeclared(
      permission: PermissionData,
  ): Promise<PermissionDeclaredResult>

  指定的权限是否存在于权限清单中

  参数

  • permission: PermissionData

  返回 Promise<PermissionDeclaredResult>

  示例

  ymx.hasPermissionDeclared({
    permission: 'ohos.permission.LOCATION'
  }).then(res => {
      alert(JSON.stringify(res));
    });
  复制

hasPermissionGranted

• hasPermissionGranted(permission: PermissionData): Promise<PermissionResult>

  是否已获得指定的权限

  参数

  • permission: PermissionData

    权限

  返回 Promise<PermissionResult>

  示例

  ymx.hasPermissionGranted({
    permission: 'ohos.permission.LOCATION'
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

hideLoading

• hideLoading(): Promise<void>

  隐藏 loading 提示

  返回 Promise<void>

  示例

  ymx.hideLoading();
  复制

hideToast

• hideToast(): Promise<void>

  隐藏吐司提示

  返回 Promise<void>

  示例

  ymx.hideToast();
  复制

insertLayout

• insertLayout(layoutPatternIndex: LayoutPatternIndex): Promise<void>

  插入布局规则

  参数

  • layoutPatternIndex: LayoutPatternIndex

    布局规则

  返回 Promise<void>

launch

• launch(data: LaunchData): Promise<number>

  拉起第三方应用

  参数

  • data: LaunchData

  返回 Promise<number>

  成功的 urls 序号

  示例

  ymx.launch({
    url: 'https://xw.qq.com/'
  }).then(() => {
    console.log('成功');
  }).catch((e) => {
    alert(`失败 ${JSON.stringify(e)}`);
  });
  复制

  示例

  ymx.launch({
    url: 'weixin://'
  }).then(() => {
    console.log('成功');
  }).catch((e) => {
    alert(`失败 ${JSON.stringify(e)}`);
  });
  复制

  示例

  ymx.launch({
    url: 'tel://1801234'
  }).then(() => {
    console.log('成功');
  }).catch((e) => {
    alert(`失败 ${JSON.stringify(e)}`);
  });
  复制

makePhoneCall

• makePhoneCall(data: MakePhoneCallData): Promise<void>

  拨打电话

  参数

  • data: MakePhoneCallData

  返回 Promise<void>

  示例

  ymx.makePhoneCall({
    // 示例号码
    phoneNumber: '138001234'
  });
  复制

off

• off(data: UnsubscribeEvent): Promise<void>

  取消订阅监听

  参数

  • data: UnsubscribeEvent

  返回 Promise<void>

  示例

  ymx.off({
    eventName: 'my-on',
    listener: listener
  });
  复制

  示例

  ymx.off({
    eventName: 'my-on'
  });
  复制

offAppHide

• offAppHide(listener?: () => void): Promise<void>

  移除应用切换到后台监听器

  参数

  • 可选listener: () => void

    提供了 listener 则仅移除此监听器，为提供 listener 则全部移除

  返回 Promise<void>

  示例

  ymx.offAppHide();
  复制

offAppShow

• offAppShow(listener?: () => void): Promise<void>

  移除应用切换到前台监听器

  参数

  • 可选listener: () => void

    提供了 listener 则仅移除此监听器，为提供 listener 则全部移除

  返回 Promise<void>

  示例

  ymx.offAppShow(listener);
  复制

  示例

  ymx.offAppShow();
  复制

on

• on(data: SubscribeEvent): Promise<void>

  持续订阅监听一个事件

  参数

  • data: SubscribeEvent

  返回 Promise<void>

  示例

  const listener = (data) => {
    console.log('on data', data);
  }
  ymx.on({
    eventName: 'my-on',
    listener: listener
  });
  复制

onAppHide

• onAppHide(listener: () => void): Promise<void>

  订阅应用切换到后台时触发事件

  参数

  • listener: () => void

  返回 Promise<void>

  监听器

  示例

  ymx.onAppHide(() => {
    console.log('onAppHide');
  });
  复制

onAppShow

• onAppShow(listener: () => void): Promise<void>

  订阅应用切换到前台时触发事件

  参数

  • listener: () => void

    监听器

  返回 Promise<void>

  示例

  const listener = () => {
    console.log('onAppShow');
  };
  ymx.onAppShow(listener);
  复制

once

• once(data: SubscribeEvent): Promise<void>

  订阅监听一个事件，触发一次后失效。

  参数

  • data: SubscribeEvent

  返回 Promise<void>

  示例

  ymx.once({
    eventName: 'my-once',
    listener: (data) => {
      console.log('once data', data);
    }
  });
  复制

open

• open(data: OpenData): Promise<void>

  在新窗口中打开链接

  参数

  • data: OpenData

  返回 Promise<void>

  示例

  ymx.open({
    url: 'https://xw.qq.com/'
  }).then(() => {
    console.log('成功');
  }).catch((e) => {
    alert(`失败 ${JSON.stringify(e)}`);
  });
  复制

  示例

  ymx.open({
    url: 'https://xw.qq.com/',
    style: 'dialog',
    onResult: (result) => {
      // 关闭子窗口时返回的结果 ymx.close(result)
      console.log(result);
    }
  }).then(() => {
    console.log('成功');
  }).catch((e) => {
    alert(`失败 ${JSON.stringify(e)}`);
  });
  复制

openPermissionSetting

• openPermissionSetting(permissions: PermissionsData): Promise<PermissionsResult>

  打开权限设置界面，手动授权。

  • 鸿蒙 requestPermissionOnSetting

  1. 权限必需在应用的权限清单中
  2. 需要先调用 requestPermission 用户明确拒绝后能 requestPermissionOnSetting

  参数

  • permissions: PermissionsData

  返回 Promise<PermissionsResult>

  示例

  ymx.openPermissionSetting({
    permissions: ['ohos.permission.APPROXIMATELY_LOCATION']
  }).then(res => {
    alert(JSON.stringify(res));
  }).catch((err) => {
    alert(err.message);
  });
  复制

removeLayout

• removeLayout(index: number): Promise<void>

  删除布局规则

  参数

  • index: number

    从 0 开始的序号

  返回 Promise<void>

removeStorage

• removeStorage(data: StorageKey): Promise<void>

  从本地缓存中移除指定 key

  参数

  • data: StorageKey

  返回 Promise<void>

  示例

  ymx.removeStorage({
    key: 'key1'
  }).then(() => {
    alert('success');
  });
  复制

request

• request(data: RequestData): Promise<RequestResult>

  网络请求

  参数

  • data: RequestData

  返回 Promise<RequestResult>

  示例

  ymx.request({
    url: 'https://www.yimenapp.com/doc/echo2',
    method: 'POST',
    data: {
      key1: 'value 1',
      hello: '世界'
    }
  }).then(res => {
    alert(JSON.stringify(res));
  }).catch((err) => {
    alert(`request error: ${JSON.stringify(err)}`);
  });
  复制

  示例

  ymx.request({
    url: 'https://www.yimenapp.com/doc/echo2',
    method: 'GET'
  }).then(res => {
    alert(JSON.stringify(res));
  }).catch((err) => {
    alert(`request error: ${JSON.stringify(err)}`);
  });
  复制

requestPermission

• requestPermission(permission: RequestPermissionData): Promise<PermissionResult>

  请求单个权限

  参数

  • permission: RequestPermissionData

    权限

  返回 Promise<PermissionResult>

  是否已同意授权

  示例

  ymx.requestPermission({
    permission: 'ohos.permission.APPROXIMATELY_LOCATION'
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

requestPermissions

• requestPermissions(
      permissions: RequestPermissionsData,
  ): Promise<PermissionsResult>

  请求多个权限

  参数

  • permissions: RequestPermissionsData

    权限组

  返回 Promise<PermissionsResult>

  权限组参数的授权结果

  示例

  ymx.requestPermissions({
    permissions: ['ohos.permission.LOCATION', 'ohos.permission.APPROXIMATELY_LOCATION'],
    openSettingIfDenied: true
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

requirePlugin

• requirePlugin(pluginId: string): object

  构建插件 js API 接口实例

  此接口返回 object 类型，为获得接口类型验证和智能提示，请按如下操作：

  • 安装插件的 TypeScript 接口类型定义包，以 ymx-wechat 插件为例

  npm install --save-dev @ymxjs/ymx-wechat
  复制

  • 将 requirePlugin 返回值强制转换为插件的对应类型 YmxWechat

  const wechat = ymx.requirePlugin('ymx-wechat') as YmxWechat;
  // 至此，调用 wechat 下的接口即可获得开发环境类型验证和智能提示
  // wechat.login...
  复制

  参数

  • pluginId: string

    插件 ID

  返回 object

saveImageToPhotosAlbum

• saveImageToPhotosAlbum(data: SaveMediaToPhotosAlbumData): Promise<void>

  保存图片到系统相册

  参数

  • data: SaveMediaToPhotosAlbumData

  返回 Promise<void>

  示例

  ymx.downloadFile({
    url: 'https://i.cdn.yimenapp.com/sys/2.jpg'
  }).then(async (file) => {
    alert('已下载图片');
    // 保存图片到相册
    await ymx.saveImageToPhotosAlbum({
      filePath: file.tempFilePath
    });
    alert('已保存图片到相册');
  })
  复制

saveVideoToPhotosAlbum

• saveVideoToPhotosAlbum(data: SaveMediaToPhotosAlbumData): Promise<void>

  保存视频到系统相册

  参数

  • data: SaveMediaToPhotosAlbumData

  返回 Promise<void>

  示例

  ymx.downloadFile({
    url: 'https://cdn.myapp.ltd/sys/sunflower.mp4'
  }).then(async (file) => {
    alert('已下载视频');
    // 保存视频到相册
    await ymx.saveVideoToPhotosAlbum({
      filePath: file.tempFilePath
    });
    alert('已保存视频到相册');
  })
  复制

scanCode

• scanCode(data: ScanCodeData): Promise<ScanCodeResult>

  调起客户端扫码界面进行扫码

  参数

  • data: ScanCodeData

  返回 Promise<ScanCodeResult>

  示例

  ymx.scanCode({
    scanType: ['barCode', 'qrCode']
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

  示例

  ymx.scanCode({
    onlyFromCamera: true
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

setKeepScreenOn

• setKeepScreenOn(data: KeepScreenOnData): Promise<void>

  设置是否保持常亮状态

  参数

  • data: KeepScreenOnData

  返回 Promise<void>

  示例

  ymx.setKeepScreenOn({
    keepScreenOn: true
  }).then(() => {
    alert('已开启屏幕常亮');
  });
  复制

  示例

  ymx.setKeepScreenOn({
    keepScreenOn: false
  }).then(() => {
    alert('已关闭屏幕常亮');
  });
  复制

setLayout

• setLayout(layout: Layout): Promise<void>

  设置当前布局选项

  参数

  • layout: Layout

    布局选项

  返回 Promise<void>

setNavigationBar

• setNavigationBar(navigationBar: NavigationBar): Promise<void>

  设置导航栏（底部虚拟按键区）

  参数

  • navigationBar: NavigationBar

    导航栏

  返回 Promise<void>

setScreenBrightness

• setScreenBrightness(data: ScreenBrightness): Promise<void>

  设置屏幕亮度

  参数

  • data: ScreenBrightness

  返回 Promise<void>

  示例

  ymx.setScreenBrightness({
    value: 0.8
  }).then(() => {
    alert('已设置');
  });
  复制

setScreenOrientation

• setScreenOrientation(screenOrientation: ScreenOrientation): Promise<void>

  设置屏幕方向

  参数

  • screenOrientation: ScreenOrientation

    屏幕方向

  返回 Promise<void>

setStatusBar

• setStatusBar(statusBar: StatusBar): Promise<void>

  设置状态栏

  参数

  • statusBar: StatusBar

    状态栏

  返回 Promise<void>

setStorage

• setStorage(data: StorageData): Promise<void>

  将数据存储在本地缓存中指定的 key 中。会覆盖掉原来该 key 对应的内容。除非用户主动删除或因存储空间原因被系统清理，否则数据都一直可用。单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

  参数

  • data: StorageData

  返回 Promise<void>

  示例

  ymx.setStorage({
    key: 'key1',
    data: 'value 1'
  }).then(() => {
    alert('success');
  });
  复制

  示例

  ymx.setStorage({
    key: 'key2',
    data: {
      name: '张三',
      age: 26
    }
  }).then(() => {
    alert('success');
  });
  复制

setTheme

• setTheme(theme: Theme): Promise<void>

  设置主题

  参数

  • theme: Theme

    主题

  返回 Promise<void>

setTitleBar

• setTitleBar(titleBar: TitleBar): Promise<void>

  设置标题栏

  参数

  • titleBar: TitleBar

    标题栏

  返回 Promise<void>

showActionSheet

• showActionSheet(data: ShowActionSheetData): Promise<ShowActionSheetResult>

  显示操作菜单

  参数

  • data: ShowActionSheetData

  返回 Promise<ShowActionSheetResult>

  示例

  ymx.showActionSheet({
    alertText: '请选择',
    itemList: ['选项1', '选项2', '选项3'],
    itemColor: '#FF0000',
  }).then((res) => {
    alert(res.tapIndex);
  });
  复制

showLoading

• showLoading(data: ShowLoadingData): Promise<void>

  显示 loading 提示

  参数

  • data: ShowLoadingData

  返回 Promise<void>

  示例

  ymx.showLoading({
    title: '加载中...',
    mask: true
  });
  复制

showModal

• showModal(data: ShowModalData): Promise<ShowModalResult>

  显示模态弹框

  参数

  • data: ShowModalData

  返回 Promise<ShowModalResult>

  示例

  ymx.showModal({
    title: '确认',
    content: '确实退出吗？',
    confirmText: '退出',
    cancelText: '取消'
  }).then(res => {
    alert(JSON.stringify(res));
  });
  复制

showToast

• showToast(data: ShowToastData): Promise<void>

  吐司提示

  参数

  • data: ShowToastData

  返回 Promise<void>

  示例

  ymx.showToast({
    title: 'hello world',
    duration: 2000
  });
  复制

uploadFile

• uploadFile(data: UploadFileData): Promise<UploadFileResult>

  上传文件

  参数

  • data: UploadFileData

  返回 Promise<UploadFileResult>

  示例

  // 选文件
  ymx.chooseMedia({
    sourceType: ['album'],
    mediaType: ['image'],
    count: 1
  }).then(choose => {
    // 上传
    ymx.uploadFile({
      url: 'https://www.yimenapp.com/doc/echo2',
      filePath: choose.tempFiles[0].tempFilePath
    }).then(res => {
      alert(JSON.stringify(res));
    }).catch((uploadErr) => {
      alert(`upload error: ${JSON.stringify(uploadErr)}`);
    });
  }).catch((chooseErr) => {
    alert(`choose error: ${JSON.stringify(chooseErr)}`);
  });
  复制

vibrateLong

• vibrateLong(): Promise<void>

  使手机发生较长时间的振动（400 ms)

  返回 Promise<void>

  示例

  ymx.vibrateLong();
  复制

vibrateShort

• vibrateShort(data: VibrateShortData): Promise<void>

  使手机发生较短时间的振动（15 ms）

  参数

  • data: VibrateShortData

  返回 Promise<void>

  示例

  ymx.vibrateShort({
    type: 'medium'
  });
  复制