site `globe` | ArcBlock

这是 Web Device layout component（本站），不是 AUP primitive，不是 AUP Web-only widget，也不是 Markdown 指令。

站点包：blocklets/arcblock/.web/components/globe/。解析：site override > theme default。

本站今天就在用这份包。同样四个文件正在加入 ARC default theme（providers/runtime/web-device/themes/default/components/globe/，ArcBlock/arc#5329）。在本站跑到带该 theme 包的 arc 之前，以站点副本为真源。本站追踪：#464。

用途

最小的 COBE WebGL 地球。用作栏内 figure、大舞台 scene，或衬在其他 layout section 后面的 backdrop。

地球静帧 PNG 是示意图。会转、还能拖的地球，让页面有位置，人也更愿意停。首页 backdrop、产品页、或长文段落之间的 figure：同一个组件。

Live

空白舞台上的 figure 和 scene（本站 lab）：

文章栏内的 figure、scene 和具名 look：介绍文章。首页 backdrop：/zh/。

不是这个组件

对象	区别
AUP primitive `globe`（deck）	渲染 `aup-globe-shell`。地图壳，不是 COBE。
Markdown `::globe`	通用 / 未知 document type。不会加载这个包。
GIS / 分级设色	这个组件画陆地点、可选 marker、可选 arc。不会按表格给区域上色。

作者入口只有 layout.aup（或 layouts/ 下的具名 layout）里的 component=globe。

什么时候用

首页或 landing 的 backdrop：页面像落在某个地方，不像打进空白栏的字。
文章里的 figure：讲网络、团队、航线时。可拖。
具名 look（builders、users、ai、chain），脚本可以运行中切换，不必换图。

什么时候不用

需要真地图（瓦片、标注、区域填充）。
Markdown ::globe 是 AUP deck primitive，不是这个组件。正文里要 demo：在页面 layout 里挂一次 component=globe（加载 script + CSS），再写 render.js 吐出的同一套 markup。见介绍文章源码。
只做手机、还用 variant=backdrop：脚本在 760px 以下不绑定 backdrop，首页 #xy-globe 除外。

作者入口

layout.aup

最小 backdrop（首页写法）

component globe slot=xy-globe component=globe
    variant=backdrop
    effect=builders

figure 或 scene（lab / 文章写法）

component scene slot=cobe-scene component=globe
    variant=scene
    size=560
    preset=cities
component figure slot=cobe-figure component=globe
    variant=figure
    size=360
    preset=cities

本站 live：

首页：/zh/（variant=backdrop effect=builders）
Lab：/zh/globe-lab/
介绍文章：/zh/articles/globe-on-the-page/

Props

来自 manifest.json。发明的名字不可移植。

Prop	类型	默认	作用
`variant`	string	`figure`	`figure`（栏内，可拖）· `scene`（大舞台）· `backdrop`（衬后，不可拖）
`size`	number	figure 360 · scene 560 · backdrop 720	方形 canvas 的 CSS 像素边长
`theme`	string	`auto`	`auto` 跟 `html[data-mode]` · `light` · `dark`
`rotate`	string/boolean	`true`	自转。`prefers-reduced-motion: reduce` 时强制关
`speed`	number	`0.0025`（脚本 look 用 `0.0026`）	每帧转角
`theta`	number	`0.22`	垂直倾角，弧度
`scale`	number	`1`	地球缩放
`samples`	number	`16000`	陆地点密度
`drag`	string/boolean	figure 为 `true`，backdrop 为 `false`	指针拖转
`effect`	string	空 → 若无其它设置则 `builders`	具名 look：`builders` · `users` · `ai` · `chain` · `cjk` · `already`（别名 `late`、`new-year`、`year-end`）
`preset`	string	空	marker preset：`cities`
`markers`	array	`[]`	`[{ lat, lon, size? }]` 或 `{ location: [lat, lon], size? }`。`size` 相对地球半径
`arcs`	array	`[]`	`[{ from: [lat, lon], to: [lat, lon] }]` 或 `{ fromLat, fromLon, toLat, toLon }`

字符串也能解析：JSON 文本，或 marker 的 lat,lon,size;lat,lon,size。

markers / arcs 非空时覆盖 effect / preset。

运行中切换

在 document 上派发：

document.dispatchEvent(new CustomEvent("site-globe:effect", { detail: { effect: "users" } }));

页面上每个暴露了 __globeSetEffect 的 .site-globe 会换 look。从其它页面脚本调用。不要自己改 canvas uniform。

表面

layout。不是 document Markdown 指令表面。

公共状态

本站 released（首页、lab、介绍文章）。theme 提升在 ArcBlock/arc 进行中；不要把 theme 包写成当前这台 arc 二进制已经带上的能力。

Fallback

情形	结果
无 WebGL	空方块；正文仍可读
`prefers-reduced-motion: reduce`	不自转、不可拖
`variant=backdrop` 且宽度 ≤ 760，且不是 `#xy-globe`	脚本不绑定
无 markers 也无 preset/effect	`builders` look

Sample 诚实边界

本页无独立 docs-safe mock（WebGL）。合同由 /zh/、/zh/globe-lab/ 和介绍文章 layout layouts/globe-on-the-page.aup 证明。从那些文件抄 AUP；不要发明 props。

证据

项	路径
站点包	`blocklets/arcblock/.web/components/globe/`
Manifest	`…/globe/manifest.json`
Renderer	`…/globe/render.js`
Script	`…/globe/script.js`（COBE 2.0.1，MIT，Shu Ding）
Style	`…/globe/style.css`
首页挂载	`pages/index/layout.aup` · `#xy-globe`
Lab	`pages/globe-lab/layout.aup`
文章 layout	`layouts/globe-on-the-page.aup`
内部矩阵	`docs/aup/capability-matrix.md` §5

备注

class 名是 site-globe / site-globe-canvas（历史名字）。选这些，不要选 aup-globe-shell。
marker / arc 的强调色来自 --color-accent。
暗色读 html[data-mode="dark"]。

用途