@jx3box/jx3box-map
v1.1.12
Published
JX3BOX Game Map
Readme
@jx3box/jx3box-map
用于各种需要在地图上展示点位的场合
QuickStart
import Jx3boxMap from "@jx3box/jx3box-map";<jx3box-map :map-id="8" :datas="datas"></jx3box-map>PVX 风格与响应式总览：
<jx3box-map
:map-id="8"
:datas="datas"
mode="responsive"
locale="zh-CN"
:trim-border="true"
:zoomable="true"
/>export default {
name: "App",
components: {
Jx3boxMap,
},
data: () => ({
datas: [
{
x: 9655,
y: 13231,
title: "测试",
content: "测试内容11<br />22",
},
],
}),
};props
组件props作用。
mapId
当前所展示的地图
datas
在地图上的点位，是一个对象数组。其中的对象的属性如表所示
| 属性名 | 描述 | 必填 | 栗子 | 备注 | | ------- | ---------------- | ---- | ------- | ---------------------------------------------- | | x | 坐标x点 | 是 | 114514 | | | y | 坐标y点 | 是 | 1919810 | | | title | 悬浮框标题 | 否 | | | content | 悬浮框显示的内容 | 否 | | | focus | 是否展示这个点 | 否 | true | Boolean，多个数据focus都为true时只会展示第一个 |
overview 总览模式
默认情况下，overview为true。
当overview为true时：
组件会把整个地图缩放以适应容器大小，尝试展示完整的地图与点位。
当overview为false时：
组件会以地图的原尺寸展示地图，仅展示以特定点位为中心的周围一部分点位。
可以在datas内的对应对象设置focus为true指定中心点位。
或者给组件传入focus属性，值是要展示的点位在datas内的索引。
如果不通过任何方式指定要展示的点位会直接取第一个。
mode
新版布局模式，可选：
overview：完整总览；responsive：完整总览并随容器宽度重新计算，推荐普通 Web 和手机使用；focus：使用 1024 × 896 内部画布展示点位附近区域。
未传入 mode 时继续读取旧的 overview，旧调用无需迁移。
locale / messages / translator / labels
组件内置 zh-CN、zh-TW、en-US、vi 四语言，并统一回退到 zh-CN。
<jx3box-map locale="en-US" />locale 未传入时会读取宿主 vue-i18n 的当前 locale，再读取 <html lang>。
可以通过 messages 覆盖内置语言：
const messages = {
"en-US": {
loadError: "Custom map error",
},
};也可以传入 translator(key, params, locale) 对接宿主翻译函数，或通过 labels 直接覆盖单个固定文案。组件固定词条位于 jx3boxMap 命名空间；地图名、NPC、点位标题和说明仍由业务数据提供。
trim-border / trim-ratio
trim-border 用于裁去地图图片上下透明边，默认关闭；trim-ratio 默认 0.05。裁边在公共组件内部完成，宿主不需要监听 resize 后反向修改轮播高度。
zoomable / wheel-zoom
zoomable：是否允许缩放；wheel-zoom：是否允许鼠标滚轮缩放，只有同时启用zoomable才生效；
普通总览地图的滚轮缩放默认关闭，避免地图阻断页面正常滚动。为兼容旧版地图工具，启用 map-draggable 的焦点地图继续保留滚轮和双指缩放；业务也可以通过 zoomable / wheel-zoom 显式控制。
aspect-ratio
响应式总览比例，默认 1024 / 896。容器宽度变化由 ResizeObserver 监听，同一帧内合并测量，并且只有尺寸实际改变时才触发 resize。
map-label / point-label-key
用于无障碍名称和点位交互：
map-label：地图区域与图片替代文本；point-label-key：点位对象中作为可访问名称的字段，默认title。
map-draggable
是否允许用户拖动地图，仅在overview为false时生效。
此时用户可以通过拖动地图来改变可见区域
即默认会以focus点为中心，但是用户可以拖动来改变展示的区域
point-draggable
是否允许用户移动点位。
此时用户可以通过拖动点位来改变点位的坐标。
map-follow
用户拖拽点位之后是否让地图跟随被拖拽的点居中。
show-toolbar
是否展示地图控制条，默认不展示。
地图只有默认子图时，控制条展示当前地图名称；存在多个子图时，控制条展示当前子图名称和当前索引。
allow-switch-sub
是否允许通过控制条切换子图，默认不允许。
只有在show-toolbar为true、当前地图存在多个子图且没有通过lock-sub-id锁定子图时，才会展示左右切换按钮。
auto-switch-sub-by-points
是否允许组件根据传入点位自动推断子图，默认允许。
如果业务侧会临时隐藏、筛选或清空点位，但不希望当前子图因此改变，可以设为false。
事件
map-move
用户拖拽地图之后触发
point-move
用户拖拽点位之后触发
resize
容器尺寸实际变化后触发，保持兼容数组参数：[width, height]。
error
比例数据或地图图片加载失败时触发：
{
type: "scales" | "image",
error,
}原有 sub-switch 保持不变。
方法
pointPosition(point) -> {left: ..., bottom: ...}
获得一个坐标（游戏坐标）在当前地图的中地图偏移（像素）
gamePosition(left, bottom) -> {x: ..., y: ...}
和上面相反
initInnerOffset(point)
移动inner，使得一个点尽可能居
slots
允许一些部分的自定义slot。
title
地图上方的名称部分
point
地图上的点位元素，默认是一个带popover的小红点，如果需要替换的话需要自己给上popover
popover
如果使用默认的point，可以用popover这个slot来替换的默认的popover里的内容
error
替换默认错误状态，插槽参数为 { error, retry }。
响应式建议
- 桌面焦点浏览使用
mode="focus"并给宿主容器明确高度； - 平板和手机使用
mode="responsive"； - 手机触控按钮按
720px断点增大，页面不会产生横向滚动； - 组件遵循
prefers-reduced-motion； - 宿主应设置
min-width: 0，不要再覆盖.c-map__inner等内部结构。