db.Geo

该对象上含有地理位置构造器。为了使用基于地理位置的查询,必须为相应存放地理位置的地方添加地理位置索引。详见数据库指引中的地理位置章节。

在使用地理位置接口时,除了使用以下提供的各种地理位置构造器外,均可使用其等价的 GeoJSON 表示法。通过地理位置构造器构造的各个对象均可调用方法 toJSON 获得其等价的 GeoJSON 纯 JS 对象。在查询结果中如果含有地理位置字段,均返回地理位置对象而不是 GeoJSON 对象。

db.Geo 拥有字段如下:

字段 说明
Point
LineString 线段
Polygon 多边形
MultiPoint 点集合
MultiLineString 线段集合
MultiPolygon 多边形集合

db.Geo.Point

构造一个地理位置 ”点“。

方法签名如下:

function Point(longitude: number, latitude: number): Point

方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序。

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: db.Geo.Point(113, 23)
    }
  })
}

除了使用接口构造一个点外,也可以使用等价的 GeoJSON点 (Point) 的 JSON 表示,其格式如下:

{
  "type": "Point",
  "coordinates": [longitude, latitude] // 数字数组:[经度, 纬度]
}

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'Point',
        coordinates: [113, 23]
      }
    }
  })
}

db.Geo.LineString

构造一个地理位置的 ”线段“。一个线段由两个或更多的点有序连接组成。

方法签名如下:

function LineString(points: Point[]): LineString

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: db.Geo.LineString([
        db.Geo.Point(113, 23),
        db.Geo.Point(120, 50),
        // ... 可选更多点
      ])
    }
  })
}

除了使用接口构造一条线段外,也可以使用等价的 GeoJSON线段 (LineString) 的 JSON 表示,其格式如下:

{
  "type": "LineString",
  "coordinates": [
    [p1_lng, p1_lat],
    [p2_lng, p2_lng]
    // ... 可选更多点
  ]
}

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'LineString',
        coordinates: [
          [113, 23],
          [120, 50]
        ]
      }
    }
  })
}

db.Geo.Polygon

构造一个地理位置 ”多边形“。一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

多边形构造规则:

  1. 第一个线性环必须是外环
  2. 外环不能自交
  3. 所有内环必须完全在外环内
  4. 各个内环间不能相交或重叠,也不能有共同的边

方法签名如下:

function Polygon(lineStrings: LineString[]): Polygon

示例代码:单环多边形

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { Polygon, LineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: Polygon([
        LineString([
          Point(0, 0),
          Point(3, 2),
          Point(2, 3),
          Point(0, 0)
        ])
      ])
    }
  })
}

示例代码:含一个外环和一个内环的多边形

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { Polygon, LineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: Polygon([
        // 外环
        LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
        // 内环
        LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
      ])
    }
  })
}

除了使用接口构造一个点外,也可以使用等价的 GeoJSON多边形 (Polygon) 的 JSON 表示,其格式如下:

{
  "type": "Polygon",
  "coordinates": [
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 外环
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 1
    ...
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 n
  ]
}

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'Polygon',
        coordinates: [
          [ [0, 0], [30, 20], [20, 30], [0, 0] ],
          [ [10, 10], [16, 14], [14, 16], [10, 10]]
        ]
      }
    }
  })
}

db.Geo.MultiPoint

构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

方法签名如下:

function MultiPoint(points: Point[]): MultiPoint

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: db.Geo.MultiPoint([
        db.Geo.Point(113, 23),
        db.Geo.Point(120, 50),
        // ... 可选更多点
      ])
    }
  })
}

除了使用接口构造一条线段外,也可以使用等价的 GeoJSON点集合 (MultiPoint) 的 JSON 表示,其格式如下:

{
  "type": "MultiPoint",
  "coordinates": [
    [p1_lng, p1_lat],
    [p2_lng, p2_lng]
    // ... 可选更多点
  ]
}

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'MultiPoint',
        coordinates: [
          [113, 23],
          [120, 50]
        ]
      }
    }
  })
}

db.Geo.MultiLineString

构造一个地理位置 ”线段“ 集合。一个线段集合由多条线段组成。

方法签名如下:

function MultiLineString(lineStrings: LineString[]): MultiLineString

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { LineString, MultiLineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: MultiLineString([
        LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
        LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
      ])
    }
  })
}

除了使用接口构造一个点外,也可以使用等价的 GeoJSON线段集合 (MultiLineString) 的 JSON 表示,其格式如下:

{
  "type": "MultiLineString",
  "coordinates": [
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
    ...
    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
  ]
}

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'MultiLineString',
        coordinates: [
          [ [0, 0], [3, 3] ],
          [ [5, 10], [20, 30]]
        ]
      }
    }
  })
}

db.Geo.MultiLineString

构造一个地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

方法签名如下:

function MultiPolygon(polygons: Polygon[]): MultiPolygon

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const { MultiPolygon, Polygon, LineString, Point } = db.Geo
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: MultiPolygon([
        Polygon([
          LineString([ Point(50, 50), Point(60, 80), Point(80, 60), Point(50, 50) ]),
        ]),
        Polygon([
          LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
          LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
        ]),
      ])
    }
  })
}

除了使用接口构造一个点外,也可以使用等价的 GeoJSON线段集合 (MultiLineString) 的 JSON 表示,其格式如下:

{
  "type": "MultiPolygon",
  "coordinates": [
    // polygon 1
    [
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      ...
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
    ],
    ...
    // polygon n
    [
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
      ...
      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
    ],
  ]
}

示例代码

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
exports.main = async (event, context) => {
  return await db.collection('todos').add({
    data: {
      description: 'eat an apple',
      location: {
        type: 'MultiPolygon',
        coordinates: [
          [
            [ [50, 50], [60, 80], [80, 60], [50, 50] ]
          ],
          [
            [ [0, 0], [30, 20], [20, 30], [0, 0] ],
            [ [10, 10], [16, 14], [14, 16], [10, 10]]
          ]
        ]
      }
    }
  })
}