点字段(坐标)

点字段会在数据库中保存一对坐标,并为位置相关查询建立索引。数据库中的数据结构与表示点的 GeoJSON 结构相匹配。Payload API 将对象数据简化为仅包含 [经度, 纬度] 位置信息。

展示 Payload 管理面板中的 Point 字段
管理面板中的 Point 字段截图

要添加 Point 字段,请在 字段配置 中将 type 设置为 point

import type { Field } from 'payload'

export const MyPointField: Field = {
  // ...
  type: 'point', // highlight-line
}

重要提示: Point 字段目前不支持 SQLite 数据库。

配置

选项描述
name *作为属性名用于数据库存储和检索。了解更多
label在 Admin Panel 中作为字段标签使用,并用于命名生成的 GraphQL 类型。
unique强制集合中每个条目对该字段具有唯一值。
index为该字段构建索引以加快查询速度。对于地理位置查询,point 索引默认为 2dsphere,要禁用索引可设置为 false
validate提供自定义验证函数,该函数将在 Admin Panel 和后台执行。了解更多
saveToJWT如果该字段是顶级字段且嵌套在支持身份验证的配置中,则将其数据包含在用户 JWT 中。
hooks提供字段钩子来控制该字段的逻辑。更多详情
access提供字段访问控制,指定用户可以查看和操作该字段数据的权限。更多详情
hidden完全限制该字段在所有 API 中的可见性。仍会保存到数据库,但不会出现在任何 API 或 Admin Panel 中。
defaultValue提供用于该字段默认值的数据。了解更多
localized启用该字段的本地化功能。需要在基础配置中启用本地化
required要求该字段必须有值。
admin特定于 Admin 的配置。更多详情
custom用于添加自定义数据的扩展点(例如插件使用)。
typescriptSchema通过提供 JSON schema 来覆盖字段类型生成。
virtual设置为 true 可禁用数据库中的字段,或提供字符串路径以将字段与关系链接。参见虚拟字段

* 星号表示该属性为必填项。

示例

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'location',
      type: 'point',
      label: 'Location',
    },
  ],
}

查询 - near

要根据与另一个点的距离进行查询,可以使用 near 操作符。使用 near 操作符查询时,返回的文档会按照从近到远的顺序排序。

查询 - within

要根据点是否位于 GeoJSON 定义的特定区域内进行查询,可以使用 within 操作符。 示例:

const polygon: Point[] = [
  [9.0, 19.0], // 左下角
  [9.0, 21.0], // 左上角
  [11.0, 21.0], // 右上角
  [11.0, 19.0], // 右下角
  [9.0, 19.0], // 回到起点闭合多边形
]

payload.find({
  collection: 'points',
  where: {
    point: {
      within: {
        type: 'Polygon',
        coordinates: [polygon],
      },
    },
  },
})

查询 - intersects

要根据点是否与 GeoJSON 定义的特定区域相交进行查询,可以使用 intersects 操作符。 示例:

const polygon: Point[] = [
  [9.0, 19.0], // 左下角
  [9.0, 21.0], // 左上角
  [11.0, 21.0], // 右上角
  [11.0, 19.0], // 右下角
  [9.0, 19.0], // 回到起点闭合多边形
]

payload.find({
  collection: 'points',
  where: {
    point: {
      intersects: {
        type: 'Polygon',
        coordinates: [polygon],
      },
    },
  },
})

自定义组件

Field

服务器组件

import type React from 'react'
import { PointField } from '@payloadcms/ui'
import type { PointFieldServerComponent } from 'payload'

export const CustomPointFieldServer: PointFieldServerComponent = ({
  clientField,
  path,
  schemaPath,
  permissions,
}) => {
  return (
    <PointField
      field={clientField}
      path={path}
      schemaPath={schemaPath}
      permissions={permissions}
    />
  )
}

客户端组件

'use client'
import React from 'react'
import { PointField } from '@payloadcms/ui'
import type { PointFieldClientComponent } from 'payload'

export const CustomPointFieldClient: PointFieldClientComponent = (props) => {
  return <PointField {...props} />
}

标签

服务器组件

import React from 'react'
import { FieldLabel } from '@payloadcms/ui'
import type { PointFieldLabelServerComponent } from 'payload'

export const CustomPointFieldLabelServer: PointFieldLabelServerComponent = ({
  clientField,
  path,
}) => {
  return (
    <FieldLabel
      label={clientField?.label || clientField?.name}
      path={path}
      required={clientField?.required}
    />
  )
}

客户端组件

'use client'
import React from 'react'
import { FieldLabel } from '@payloadcms/ui'
import type { PointFieldLabelClientComponent } from 'payload'

export const CustomPointFieldLabelClient: PointFieldLabelClientComponent = ({
  field,
  path,
}) => {
  return (
    <FieldLabel
      label={field?.label || field?.name}
      path={path}
      required={field?.required}
    />
  )
}