@dgtwin/map3d

SDK bản đồ 3D và quản trị nội dung 3D của MDS. Một package, không cần cài engine 3D riêng, không cần import file CSS.

Khung tối thiểu để dùng được ngay. Tài liệu bàn giao đầy đủ nằm ở thư mục docs/ của bộ mã nguồn — gói npm chỉ chứa dist/, nên các đường dẫn docs/... bên dưới là để tra trong bộ mã nguồn, không mở được từ trang npm.

Cài đặt

npm install @dgtwin/map3d

Gói đã có trên registry công khai, không cần cấu hình registry hay token. Bản thử nghiệm phát hành ở dist-tag dev:

npm install @dgtwin/map3d@dev

Cách chạy test và xem demo chạy thật nằm trong docs/local-development.md của bộ mã nguồn bàn giao (không kèm trong gói npm).

react là peer dependency tuỳ chọn — chỉ cần khi dùng @dgtwin/map3d/react.

Dùng nhanh

import { createMap } from '@dgtwin/map3d';

const map = await createMap(document.getElementById('map')!, {
  basemap: 'satellite',
  center: [105.8542, 21.0285],
  zoom: 14,
});

map.on('featureClick', (event) => {
  console.log(event.feature.buildingId, event.feature.attributes);
});

React:

import { MDSMapView, useMDSMap } from '@dgtwin/map3d/react';

<MDSMapView options={{ basemap: 'satellite' }} onReady={(map) => console.log(map)}>
  <MyOverlay /> {/* dùng useMDSMap() bên trong */}
</MDSMapView>;

Thẻ <script> (không bundler) — bản UMD, global MDSMap3D:

<script src="/path/to/@dgtwin/map3d/dist/mds-map3d.umd.js"></script>
<script>
  MDSMap3D.createMap(document.getElementById('map'), { basemap: 'satellite' });
</script>

⚠️ Assets của engine 3D — ĐỌC TRƯỚC KHI DEPLOY

Engine 3D cần một tập file tĩnh (web worker, bảng dữ liệu địa hình, decoder .wasm, texture bầu trời) mà không bundler nào nhét vào JS được. SDK đã đóng gói sẵn chúng trong dist/engine-assets/, nhưng app của bạn phải phục vụ được thư mục đó qua HTTP. Thiếu bước này: quả địa cầu vẫn hiện nhưng địa hình, tileset nén Draco và skybox hỏng im lặng, console đầy 404 Workers/*, Assets/*.

SDK tự dò dist/engine-assets/ từ URL của chính bundle. Tự dò ĐÚNG khi trình duyệt nạp thẳng file trong dist/; SAI khi bundler của app đóng gói lại SDK (file JS bị di chuyển, engine-assets/ thì không đi theo).

Vite

Thêm một dòng để Vite không pre-bundle SDK (giữ nguyên đường dẫn thật của gói):

export default defineConfig({
  optimizeDeps: { exclude: ['@dgtwin/map3d'] },
});

Cho bản production build, copy assets vào thư mục tĩnh rồi trỏ assetsBaseUrl (xem mục dưới) — hoặc dùng vite-plugin-static-copy:

import { viteStaticCopy } from 'vite-plugin-static-copy';
import { createRequire } from 'node:module';
import path from 'node:path';

const pkgDir = path.dirname(createRequire(import.meta.url).resolve('@dgtwin/map3d/package.json'));

viteStaticCopy({
  targets: [{ src: path.join(pkgDir, 'dist/engine-assets'), dest: '' }],
});

Angular

angular.json → architect.build.options.assets:

{
  "glob": "**/*",
  "input": "node_modules/@dgtwin/map3d/dist/engine-assets",
  "output": "engine-assets"
}

Trỏ tay khi cần

Ba cách, ưu tiên từ trên xuống:

// 1. Tường minh cho từng map (thắng tất cả)
await createMap(el, { assetsBaseUrl: '/engine-assets/' });

<!-- 2. Toàn trang, không phải sửa code gọi createMap -->
<script>
  window.MDS_MAP3D_ASSETS_BASE_URL = '/engine-assets/';
</script>

3. Không khai gì → SDK tự dò; dò không ra thì in cảnh báo kèm hướng dẫn.

assetsBaseUrl là cấu hình theo trang, không theo map: map đầu tiên khoá giá trị, map sau khai khác sẽ nhận MDS_INVALID_OPTIONS.

Nội dung gói

| Đường dẫn | Vai trò | | -------------------------- | --------------------------------------------------------- | | dist/index.js / .cjs | Entry chính (ESM/CJS). Engine nằm ở chunk tải lười. | | dist/react/index.js | Bindings React (@dgtwin/map3d/react). | | dist/internal/index.js | Entry nội bộ MDS — không cam kết ổn định. | | dist/mds-map3d.umd.js | Bản UMD một file cho thẻ <script> (global MDSMap3D). | | dist/engine-assets/ | File tĩnh của engine — phải phục vụ được qua HTTP. | | THIRD_PARTY_LICENSES.txt | Giấy phép các thư viện được bundle (bắt buộc khi phân phối). |

Yêu cầu môi trường

• Node ≥ 18 để build/SSR; trình duyệt cần WebGL 2.
• TypeScript: dùng moduleResolution là bundler / node16 / nodenext. Chế độ node (node10) cũ chỉ resolve được entry chính @dgtwin/map3d, không resolve được subpath @dgtwin/map3d/react và @dgtwin/map3d/internal.
• SSR an toàn: import package ở Node không đụng window/document; createMap chỉ gọi được phía client.

Kiểm tra chất lượng gói

npm run build   # tsup → copy engine-assets → sinh licenses → gate .d.ts
npm run qa      # publint + are-the-types-wrong + ngân sách kích thước
npm test        # gate ranh giới + typecheck đầy đủ + Vitest

Tài liệu

Tài liệu bàn giao cho bên tích hợp — cùng bố cục VNPT Maps Web SDK: mục lục chuyên mục, tổng quan từng bước, rồi từng nhóm tính năng.

Bắt đầu từ docs/README.md.

| Tài liệu | Nội dung | | --- | --- | | docs/README.md | Mục lục Web SDK | | docs/tong-quan.md | Cài đặt môi trường, nhúng CDN / bundler, map lần đầu | | docs/ban-do.md | createMap, options, camera, sự kiện, bản đồ nền | | docs/layers.md | 5 loại layer | | docs/auth.md | Xác thực token / apiKey | | docs/citydb-catalog.md | Digital Twin 3DCityDB | | docs/upload-3d-model.md | Upload GLB pipeline MDS | | docs/widget-ui.md | Panel UI dựng sẵn | | docs/getting-started-react.md | MDSMapView / useMDSMap | | docs/getting-started-angular.md | Tích hợp Angular | | docs/trien-khai.md | Engine assets, Vite, Angular | | docs/xu-ly-loi.md | MDSMapError | | docs/api-reference.md | Tham chiếu type/API công khai | | docs/local-development.md | Chạy test, demo, npm pack |