系统

系统分类包含调用设备或客户端能力的行为。不同客户端支持的能力不同，配置前请先查看各行为的“平台限制”。

地理位置

地理位置行为用于获取、选择和展示位置，或将经纬度解析为行政区域。

获取位置

获取用户当前位置的经纬度，并将结果写入“经纬度”类型的页面变量。结果可绑定到地图组件，也可以继续传给获取行政区域名称行为。

该行为支持微信小程序和 Web 应用。

运行结果

• latitude：纬度。
• longitude：经度。

该行为只会返回 WGS84 坐标系的地理位置。在绑定到地图组件或传给打开位置、获取行政区域名称时，系统会自动转成 GCJ-02 坐标系，保证位置的精确；若要把坐标送给国内地图服务或第三方系统，需要开发者自行转换，详见坐标系与坐标转换。

首次执行时，客户端会请求位置权限。用户拒绝后，需要在浏览器或微信设置中重新开启位置权限。

坐标系与坐标转换

同一个地点在不同坐标系里有不同的经纬度数值。Zion 对外提供的经纬度统一使用 WGS84：获取位置 和 选择位置 写入页面变量的值、GET_VALUE_FROM_GEO_POINT 公式提取的值、数据库「经纬度」字段存储的值（对应 PostgreSQL 的 geography(Point, 4326)，4326 即 WGS84），都是同一个坐标系，不需要按客户端分别处理。

国内地图服务商使用的是 GCJ-02（国测局坐标系，也叫火星坐标系）。它在 WGS84 基础上叠加了一层非线性保密偏移，偏移量随地点变化——东部城市通常 300～600 米，西部较小，因此无法用减去固定值的方式校正。高德地图、腾讯地图、微信及其生态（含部分第三方表单、工单系统的定位字段）都要求 GCJ-02；百度地图使用在 GCJ-02 上再偏移一次的 BD-09。

哪些场景需要自己转换

用运行代码节点转换

运行代码节点可以直接完成转换：声明两个无限精度小数的输入 longitude、latitude（用 GET_VALUE_FROM_GEO_POINT 公式提取后绑定），声明数字输出 gcjLongitude、gcjLatitude，代码如下：

const A = 6378245.0;               // 椭球长半轴
const EE = 0.00669342162296594323; // 偏心率平方
 
function outOfChina(lng, lat) {
  return lng < 72.004 || lng > 137.8347 || lat < 0.8293 || lat > 55.8271;
}
 
function transformLat(lng, lat) {
  let ret = -100 + 2 * lng + 3 * lat + 0.2 * lat * lat
    + 0.1 * lng * lat + 0.2 * Math.sqrt(Math.abs(lng));
  ret += (20 * Math.sin(6 * lng * Math.PI) + 20 * Math.sin(2 * lng * Math.PI)) * 2 / 3;
  ret += (20 * Math.sin(lat * Math.PI) + 40 * Math.sin(lat / 3 * Math.PI)) * 2 / 3;
  ret += (160 * Math.sin(lat / 12 * Math.PI) + 320 * Math.sin(lat * Math.PI / 30)) * 2 / 3;
  return ret;
}
 
function transformLng(lng, lat) {
  let ret = 300 + lng + 2 * lat + 0.1 * lng * lng
    + 0.1 * lng * lat + 0.1 * Math.sqrt(Math.abs(lng));
  ret += (20 * Math.sin(6 * lng * Math.PI) + 20 * Math.sin(2 * lng * Math.PI)) * 2 / 3;
  ret += (20 * Math.sin(lng * Math.PI) + 40 * Math.sin(lng / 3 * Math.PI)) * 2 / 3;
  ret += (150 * Math.sin(lng / 12 * Math.PI) + 300 * Math.sin(lng / 30 * Math.PI)) * 2 / 3;
  return ret;
}
 
// 计算该点在两个坐标系之间的偏移量
function delta(lng, lat) {
  let dLat = transformLat(lng - 105.0, lat - 35.0);
  let dLng = transformLng(lng - 105.0, lat - 35.0);
  const radLat = lat / 180.0 * Math.PI;
  let magic = Math.sin(radLat);
  magic = 1 - EE * magic * magic;
  const sqrtMagic = Math.sqrt(magic);
  dLat = (dLat * 180.0) / ((A * (1 - EE)) / (magic * sqrtMagic) * Math.PI);
  dLng = (dLng * 180.0) / (A / sqrtMagic * Math.cos(radLat) * Math.PI);
  return [dLng, dLat];
}
 
// WGS84 转 GCJ-02：把 Zion 的坐标送给国内地图服务或第三方系统时用
function wgs84ToGcj02(lng, lat) {
  if (outOfChina(lng, lat)) return [lng, lat];
  const d = delta(lng, lat);
  return [lng + d[0], lat + d[1]];
}
 
// GCJ-02 转 WGS84：把国内地图服务返回的坐标存进 Zion 时用
function gcj02ToWgs84(lng, lat) {
  if (outOfChina(lng, lat)) return [lng, lat];
  const d = delta(lng, lat);
  return [lng - d[0], lat - d[1]];
}
 
const longitude = context.getArg('longitude');
const latitude = context.getArg('latitude');
 
const converted = wgs84ToGcj02(longitude, latitude);
 
context.setReturn('gcjLongitude', converted[0]);
context.setReturn('gcjLatitude', converted[1]);

用第三方接口转换

不想在项目里维护代码时，也可以集成第三方 API，调用地图服务商提供的坐标转换接口，例如高德地图的坐标转换 。请求参数和响应格式以对方文档为准。

选择位置

打开地图，由用户选择一个位置。该行为支持微信小程序和 Web 应用。

用户完成选择后进入“成功时”分支；未授予位置权限时进入“授权失败时”分支。

打开位置

在腾讯地图中打开指定位置，可用于展示地点或开始导航。

该行为仅支持微信小程序。

该行为没有数据输出。地址和名称为空时不会报错，但地图中不会显示对应信息。

获取行政区域名称

将经纬度解析为行政区域信息。

该行为仅支持微信小程序。

结果包含 country（国家）、province（省）、city（市）、district（区/县）和 township（街道/乡镇）等字段，可绑定到文字或输入框组件。

文件操作

上传文件

让用户选择并上传一个文件，上传结果写入“文件”类型的页面变量。

平台差异

• 微信小程序：可选择微信聊天中的文件，单个文件最大 20 MB；不支持从手机文件系统直接选择，也不支持在 PC 微信小程序中使用。
• Web 应用：从系统文件选择器中选择文件。

每次只能上传一个文件，再次上传会覆盖页面变量中的上一个结果。需要长期保存时，可在“成功时”分支中将文件写入数据库。

查看文件

在微信小程序中打开文件预览。文件可以来自页面变量，也可以来自页面数据源。

该行为仅支持微信小程序，一次只能查看一个不超过 20 MB 的文件。保存方式受微信和操作系统限制；iOS 通常需要先转发到微信聊天，再从聊天中保存。

下载文件

将页面数据源中的文件下载到本地。

该行为仅支持 Web 应用，没有数据输出，执行后由浏览器开始下载。

下载图片

将绑定的图片下载到本地，仅支持 Web 应用。

该行为没有数据输出。执行后，浏览器开始下载图片。

如果需要下载页面中的某个视图，可以组合使用以下行为：

1. 添加“组件 > 视图 > 视图转图片”，并选择目标视图。
2. 在其“成功时”分支添加“系统 > 文件操作 > 下载图片”。
3. 将“下载图片”的“图片”参数绑定为“视图转图片”的行为结果。

使用“视图转图片”时，应确保目标视图已经完成渲染，否则生成的图片可能不完整。

二维码

生成二维码

根据纯文本或一组参数生成二维码，并将生成的图片写入“图片”类型页面变量。

生成成功后进入“成功时”分支，生成失败后进入“失败时”分支。可将接收结果的页面变量绑定到图片组件或弹窗中展示。

该行为支持微信小程序和 Web 应用。

扫描二维码

调用设备相机扫描二维码，并将识别出的文本、URL 或 JSON 内容写入页面变量。该行为无需输入参数，仅支持微信小程序。

页面变量的类型应与二维码内容相匹配。如果结果还要参与后续逻辑，建议先确认二维码内容格式保持一致。

生成小程序码

生成可进入当前微信小程序指定页面的小程序码，并将图片写入页面变量。

仅已审核通过的小程序可以生成正式可用的小程序码。页面路径和参数需要与目标页面的配置保持一致。

设备

拍照

调用相机视图组件拍照，并将图片写入“图片”类型的页面变量。

前置条件

• 页面中已添加相机视图组件。
• 页面中已创建用于保存结果的图片页面变量。

该行为仅支持微信小程序。拍照结果不会自动保存到手机相册；如需持久化，应在“成功时”分支中写入数据库。

设置相机

调整页面中相机视图组件的摄像头和闪光灯设置。

该行为仅支持微信小程序，没有数据输出。

设置剪贴板

将文本复制到系统剪贴板，供用户在当前应用或其他应用中粘贴。

该行为支持微信小程序和 Web 应用。

该行为没有数据输出。建议在执行后添加“显示提示”行为，例如“已复制到剪贴板”，让用户确认操作已经完成。

通讯

通讯行为仅支持微信小程序。

拨打电话

调用系统拨号功能拨打指定号码。电话号码支持固定文本和数据绑定。

该行为没有数据输出。

Web 应用如需调起拨号应用，请使用“打开外部链接”行为，并将链接配置为 tel://电话号码。实际调用的拨号应用由操作系统决定。

添加手机通讯录联系人

打开微信小程序的联系人保存界面，将联系人信息添加到用户的手机通讯录。姓名和电话号码为主要信息，还可以配置职位、地址、备注、网址和邮箱。

该行为没有数据输出。联系人是否最终保存，由用户在微信小程序弹出的联系人界面中确认。

分享

分享小程序

在微信小程序中分享指定页面。

组件上的分享行为只能直接配置在“点击时”事件下，不能放入其他行为的嵌套分支。

分享到朋友圈

分享到朋友圈需要在小程序页面上开启，不能通过组件点击行为触发。朋友圈中打开的是微信的“小程序单页模式”，并非完整的小程序运行环境。

单页模式有以下主要限制：

• 页面没有登录态，依赖登录态的数据和接口不可用。
• 不能继续发起分享，也不能跳转到其他页面、小程序或微信原生页面。
• 自定义分享内容时不能自定义页面路径。
• 包含 web-view 的页面不支持发起分享。
• 不支持横屏，tabBar 也不会渲染。

请确保页面在无登录态和固定顶部、底部操作栏的情况下仍能完整展示。更多限制见微信小程序分享到朋友圈文档 。

分享至微博

将链接、文本和图片预填入微博发布页面，仅支持 Web 应用。

行为执行后会打开微博网页或应用，内容是否最终发布由用户决定。用户需要登录微博，分享内容也受微博平台的格式和字数限制。