---
title: 符号库
source: https://vjmap.com/guide/service/api/10-symbols.html
---

# 符号库

> 分类代号：C.10  本章共 **3 个接口（只读）**

vjmap 自带一个"常用图块/图符"库，按分类组织。二开场景里最常见的用法是：

- 前端工具条展示"符号面板"，用户选一个图符，拖到图上
- 拖放后前端本地生成图元并调后端 `updatemap` 持久化
- 导出 DWG 时把符号实例替换为 DXF BlockRef

> 本章只覆盖**只读**三接口（分类列表 / 符号列表 / 符号详情）。写操作（增 / 改 / 删分类与符号）SDK 暂不封装；如果你用 root token，可按 `POST /symbol/category`、`PUT /symbol/:id` 等直接 `svc._request(...)` 调。

---

## 快速索引

| 序号 | SDK 方法 | URL |
|----:|---------|-----|
| 61 | `symbol_categories` / `symbolCategories` | `GET /api/v1/service/symbol/categories` |
| 62 | `symbol_list` / `symbolList` | `GET /api/v1/service/symbol/list/{categoryId}` |
| 63 | `symbol_get` / `symbolGet` | `GET /api/v1/service/symbol/{id}` |


---

## 61 · 分类列表 `symbol/categories`

### 响应（实采）

```json
{
  "data": [
    { "id": "default",     "name": "默认分类",  "createTime": "2026-04-10 11:29:15" },
    { "id": "user_custom", "name": "用户自定义", "createTime": "2026-04-10 11:29:15" }
  ],
  "status": "ok"
}
```

### Python

```python
cats = svc.symbol_categories()["data"]
for c in cats:
    print(c["id"], c["name"])
```

### Node.js

```javascript
const cats = (await svc.symbolCategories()).data;
```

---

## 62 · 符号列表 `symbol/list/{categoryId}`

按分类分页列出符号。

### 查询参数

| 字段 | 默认 | 说明 |
|------|-----:|------|
| `page` | 1 | 分页起始（1-based） |
| `pageSize` | 20 | 每页 |
| `keyword` | - | 名称模糊匹配 |

### 响应（实采：分类为空）

```json
{
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 3
  },
  "status": "ok"
}
```

有数据时 `list` 元素形如：

```jsonc
{
  "id":         "symbol_abc",
  "categoryId": "default",
  "name":       "消防栓",
  "basePoint":  [0, 0],
  "thumbnail":  "data:image/png;base64,...",
  "data":       "...DWG/SVG 原始数据..."
}
```

### Python

```python
page = svc.symbol_list("default", page=1, page_size=20, keyword="栓")
for it in page["data"]["list"]:
    print(it["id"], it["name"])
```

### Node.js

```javascript
const page = await svc.symbolList('default', { page: 1, pageSize: 20 });
```

---

## 63 · 符号详情 `symbol/{id}`

### 响应

- 成功：`{ "status": "ok", "data": { ...同上"有数据时"结构... } }`
- 未找到：HTTP **404** + `{ "status": "error", "message": "not found" }`

### Python

```python
try:
    sym = svc.symbol_get("symbol_abc")["data"]
except vjmap.VjmapError as e:
    if e.status == 404:
        ...  # 符号不存在
    else:
        raise
```

---

## 使用范式

下面是一个"前端面板"级别的整合：

```python
def list_all_symbols():
    for cat in svc.symbol_categories()["data"]:
        page = 1
        while True:
            bundle = svc.symbol_list(cat["id"], page=page, page_size=50)["data"]
            for sym in bundle.get("list", []):
                yield cat, sym
            if page * bundle["pageSize"] >= bundle["total"]:
                break
            page += 1
```

---