HzzSandComponents

基于 Angular 12 和 ng-zorro-antd 的一些在四川省河长制采砂平台中常用的组件。

安装与使用

1、npm i hzz-sand-components@latest

2、app.modules.ts 中 import { HzzSandModule } from 'hzz-sand-components' ；

3、app.modules.ts 中 @NgModule 中 imports 数组中添加 HzzSandModule ；

4、如果需要使用 common-data.service，在需要使用的模块中 import { CommonDataService } from 'hzz-sand-components'; ，在构造函数中 constructor(public cs: CommonDataService) { } 即可。

！！！注意事项！！！

需要自行在全局 style.css/style.less 中引入 ant 的样式！

实在是懒得研究怎么把ant样式引入到项目里了……

自行在style.css/style.less中引入ant的样式！

如下：（css的就换成css）

@import "../node_modules/ng-zorro-antd/ng-zorro-antd.less";

需要在全局 style.css/style.less 中加入以下内容

.mapboxgl-ctrl-bottom-left {
    display: none;
}

用来隐藏 mapbox 的水印。

组件列表

• hzz-basic-map - 基础地图组件
• hzz-search-box - 搜索框（级联选择器版本）
• hzz-search-box-cross - 搜索框（交叉筛选版本）
• hzz-search-bar - 关键字搜索条
• hzz-sand-pagination - 分页组件（小）
• hzz-big-pagination - 分页组件（大）
• hzz-approval-line - 审批流程组件
• hzz-region-tree - 行政区划树
• hzz-placeholder-pic - 占位图组件
• hzz-video-player - 视频播放组件
• hzz-map-model - 轨迹地图弹窗组件
• hzz-weight-model - 历史开采量弹窗组件
• common-data.service - 公共方法服务

hzz-basic-map

基础地图组件，封装 mapbox-gl，支持底图切换、测量工具、坐标定位、影像底图错误自动降级等功能。

<hzz-basic-map style="width: 100%;height: 100%;"
    [mapToken]="'pk.e………………GWVumZLq7Hw'" [poiToken]="'111……………………0e26f'"
    [showTool]="false" [showMapSwitcher]="true" [mapSwitcherStyle]="{'top': '10px','right': '10px'}"
    [dependencePath]="baseUrl" [mapId]='"map1"'
    [imageryErrorMonitoring]="true"
    (mapLoaded)='planMapLoaded1($event)'></hzz-basic-map>

参数说明

| 参数 | 类型 | 默认值 | 说明 | | ------------------------ | -------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | mapToken | string | '' | mapbox 的 token | | poiToken | string | '' | 高德地图 POI 的 token(如果不传的话，就读取 mapConfig.json 里的 poiConfigs，实现poi搜索的降级机制) | | dependencePath | string | '' | 依赖所在路径（需包括 mapbox-gl.css, mapbox-gl.js, turf.min.js, mapStyle.json, mapConfig.json） | | mapId | string | 'map' | 地图容器的 DOM ID，多个地图时需不同 | | showTool | boolean | false | 是否显示工具条（测量、定位打点、坐标定位等） | | showMapSwitcher | boolean | false | 是否显示地图切换工具（右上角那个方方） | | mapSwitcherStyle | object | {top:'85px',right:'10px'} | 底图切换工具的定位样式 | | toolStyle | object | {top:'170px',right:'10px'} | 工具条的定位样式 | | poiStyle | object | {right:'100px',top:'85px'} | POI 搜索框的定位样式 | | needLegend | boolean | false | 是否显示图例 | | darkModel | boolean | false | 是否暗黑模式（初始底图为暗色底图-线划） | | lightModel | boolean | false | 是否亮色模式（初始底图为国家天地图-线划） | | threeD | boolean | false | 是否开启 3D 地形 | | isModalMap | boolean | false | 是否弹窗中使用的小地图（如果是，默认 zoom=16） | | initCenter | any | [102.63, 30.449] | 初始化中心经纬度 | | theseAmapIsOpen | string[] | [] | 初始化打开的专题图层名称数组 | | pointerClass | string | '' | 鼠标坐标显示位置，'center' 放到底部中央 | | pointerMaxSize | string | '25%' | 鼠标坐标显示区域的最大宽度 | | imageryErrorMonitoring | boolean | false | 是否启用影像底图错误自动监测和降级 |

imageryErrorMonitoring 启用后，地图加载完成后会自动探测当前影像底图瓦片是否可用。如果当前影像底图（国家天地图）不可用，会自动切换到备选影像底图（四川天地图）；如果所有影像底图都不可用，会静默降级到暗色底图（线划）。用户手动切换底图时探测会自动中止。

注意：darkModel 和 lightModel 不可同时为 true，否则会抛出错误。

事件

| 事件 | 说明 | | -------------- | -------------------------------------- | | mapLoaded | 地图加载完成后的事件，返回 map 对象 | | drawEnd | 绘制完成后的事件，返回 GeoJSON Feature | | resetClicked | 点击复位按钮的事件 |

map 对象上挂载的方法

通过 mapLoaded 事件拿到的 map 对象上额外挂载了以下方法：

• map.mapHighlight(geom, color, fitBounds, width, name?, layerGroupname?) - 高亮线段
• map.mapHighlightPoly(geom, color, fitBounds, name?, layerGroupname?) - 高亮面
• map.clearMapHighlight(layerGroupname?) - 清除高亮
• map.drawGeometry(type) - 绘制几何图形（draw_point, draw_line_string, draw_polygon, clear）
• map.switchAreas(geojson) - fitBounds 到指定区域
• map.mapResize(time) - 延时重新计算地图大小
• map.toggleDmal() - 切换管理范围线显示

hzz-search-box

搜索框组件（级联选择器版本），包含行政区划、河流、流域下拉框和搜索按钮。

<hzz-search-box [region]="ds.schRegion" [rivers]="ds.schRivers"
    [basins]="ds.schBasins" (paramChange)="ds.schChange($event)" (onSearch)="ds.search()"></hzz-search-box>

| 参数 | 类型 | 说明 | | ------------- | ------------ | -------------------------------------------------------------------------- | | region | any | 行政区划数据，每个节点需含 value、label 字段，叶子节点需 isLeaf=true | | rivers | any | 河流数据，格式同上 | | basins | any | 流域数据，格式同上 | | paramChange | EventEmitter | 搜索参数改变时的回调，用来联动更新下拉框 | | onSearch | EventEmitter | 点击搜索按钮后的事件 |

hzz-search-box-cross

搜索框组件（交叉筛选版本），支持行政区划树选择、河流和流域下拉筛选。切换行政区划时会自动清空流域和河流选择；切换流域时会自动清空河流选择。

<hzz-search-box-cross [region]="regionTree" [rivers]="rivers" [basins]="basins"
    [isDark]="true" (onSearch)="search($event)" (paramChange)="paramChanged($event)"></hzz-search-box-cross>

| 参数 | 类型 | 默认值 | 说明 | | ------------- | ------------ | ------- | ------------------------------------------------- | | region | any | - | 行政区划树数据（对象或数组） | | rivers | string[] | [] | 河流名称列表 | | basins | string[] | [] | 流域名称列表 | | noRiver | boolean | false | 是否隐藏河流选择框 | | noRegion | boolean | false | 是否隐藏行政区划选择框 | | isDark | boolean | true | 暗色模式开关 | | onSearch | EventEmitter | - | 搜索事件，返回 {river, pac, basin, keyword} | | paramChange | EventEmitter | - | 参数变化事件，返回 {river, pac, basin, keyword} |

hzz-search-bar

精简的关键字搜索条组件，支持暗色/亮色模式。

<hzz-search-bar [(keyword)]="keyword" [placeholder]="'请输入关键字'" [isDark]="true"
    (search)="doSearch($event)"></hzz-search-bar>

| 参数 | 类型 | 默认值 | 说明 | | ------------- | ---------------------- | ---------------- | ------------------------ | | keyword | string | '' | 搜索关键字，支持双向绑定 | | placeholder | string | '请输入关键字' | 输入框占位文字 | | isDark | boolean | true | 暗色模式开关 | | search | EventEmitter<string> | - | 搜索事件，返回当前关键字 |

hzz-sand-pagination

分页组件（小版本）。

<hzz-sand-pagination [(pageIndex)]="index" (pageChange)="search()" [total]="total"></hzz-sand-pagination>

| 参数 | 类型 | 默认值 | 说明 | | ------------ | ------------ | ------ | ---------------------- | | pageIndex | number | - | 当前页码，支持双向绑定 | | pageSize | number | 10 | 每页数据条数 | | total | number | - | 总数据条数 | | pageChange | EventEmitter | - | 翻页回调 |

hzz-big-pagination

分页组件（大版本），比 hzz-sand-pagination 多了跳转到第几页的功能，用法一致。

<hzz-big-pagination [(pageIndex)]="index" (pageChange)="search()" [total]="total"></hzz-big-pagination>

参数和 hzz-sand-pagination 完全一样。

hzz-approval-line

采砂审批流程组件，以流程图的形式展示审批节点。

<hzz-approval-line [approvalArr]="someArr" [data]="fakeApproval"></hzz-approval-line>

| 参数 | 类型 | 默认值 | 说明 | | ----------------- | ------ | --------------- | ---------------- | | approvalArr | object | 见下方 | 审批状态配置 | | data | array | - | 审批流程数据 | | stateFieldName | string | 'state' | 状态字段名称 | | regionFieldName | string | 'region' | 行政区划字段名称 | | personFieldName | string | 'approPerson' | 审批人字段名称 | | dateFieldName | string | 'approDate' | 审批日期字段名称 |

approvalArr 默认值：

{
    1: { name: '入库', color: '#409EFF', showLabel: false },
    2: { name: '通过', color: '#21A664', showLabel: true },
    3: { name: '驳回', color: '#FF5F40', showLabel: true },
    4: { name: '待审批', color: '#CCCCCC', showLabel: false }
}

其中 showLabel 为 true 时，节点下方会显示审批人、审批日期、行政区划信息。

data 示例：

[
    { state: 1, approPerson: '张三', approDate: '2023-12-28', region: '仪陇县' },
    { state: 2, approPerson: '李四', approDate: '2023-12-29', region: '南充市' },
    { state: 3, approPerson: '曹冲', approDate: '2023-12-30', region: '四川省' },
    { state: 4, region: '四川省' }
]

hzz-region-tree

行政区划树组件，支持搜索、外部展开选中、暗色模式、PAC 列表过滤和数据标记。

<hzz-region-tree [regionTree]="region" [regionNote]="region_note" [selectedNode]="selectedRegion"
    [search]="keyword" [isDark]="true" [pacList]="pacList" [dataPacList]="dataPacList"
    (titleClick)="titleClicked($event)" [isExpandOnClick]="false"></hzz-region-tree>

| 参数 | 类型 | 默认值 | 说明 | | ----------------- | ------------ | -------------- | ----------------------------------------------------------------------------- | | regionTree | any | - | 行政区划树数据 | | regionNote | object | {} | PAC → 附加信息的映射，如 {'5101': '我是成都市'} | | selectedNode | any | null | 当前选中的行政区划节点 | | search | string | '' | 搜索关键字 | | initOpenPac | string | - | 从外部传入，自动展开并选中对应 PAC 的节点 | | isExpandOnClick | boolean | false | true: 点击标题展开，到县级才可选中; false: 点击标题同时选中并切换展开状态 | | isDark | boolean | true | 暗色模式开关 | | pacList | string[] | [] | PAC 列表过滤，配合 toggleRegionsByPacList() 方法使用 | | dataPacList | string[] | [] | 有数据的行政区划 PAC 列表，匹配的节点会显示数据标记点 | | dataTitle | string | '有相关数据' | 数据标记点的提示文字 | | titleClick | EventEmitter | - | 点击标题的回调 |

公共方法

• toggleRegionsByPacList(show: boolean) - 根据 pacList 过滤/恢复行政区划树显示

hzz-placeholder-pic

空数据占位图组件，用于列表/页面无数据时展示。

<hzz-placeholder-pic [lineOne]="'找不到就算了'" [lineTwo]="'我也没办法你看着办吧'" [picSize]="200"></hzz-placeholder-pic>

| 参数 | 类型 | 默认值 | 说明 | | --------- | ------ | ------ | ------------------- | | lineOne | string | - | 第一行文字（加粗） | | lineTwo | string | - | 第二行文字（灰色） | | picSize | number | - | 图片宽高（单位 px） |

hzz-video-player

视频播放组件，三次封装同事的二次封装的库。支持 flv、m3u8、mp4 格式，自动选择播放器。m3u8 格式会先检测流地址可用性（6 秒超时）。

<hzz-video-player [url]="url" [tip]="name" [autoplay]="playState"
    [videoId]="'video1'" [isTimeLimited]="false"
    (playing)="updateState($event)"></hzz-video-player>

| 参数 | 类型 | 默认值 | 说明 | | --------------- | ------------ | ------- | ---------------------------------------- | | url | string | '' | 视频播放链接（支持 .flv / .m3u8 / .mp4） | | tip | string | '' | 视频右上角提示文字 | | autoplay | boolean | false | 是否自动播放 | | videoId | string | '' | 视频唯一标识符（用于时间限制） | | isTimeLimited | boolean | false | 是否启用播放时间限制（2 分钟） | | playing | EventEmitter | - | 播放状态改变的回调 |

hzz-map-model

轨迹地图弹窗组件。在弹窗中展示采砂船/运输船/运输车的轨迹信息，包含折线图（速度-时间）和地图，支持轨迹回放、7 日内/外历史轨迹查看、时间区间筛选等功能。

<hzz-map-model
    [initLineChartStartEnd]="[startDate, endDate]"
    [initMapStartEnd]="[mapStart, mapEnd]"
    [getData]="getTrackData"
    [getHistoryDataByDate]="getHistoryData"
    [basicData]="basicData"
    [dataType]="'mining_ship'"
    [env]="env"
    [canSeeHistory]="true"
    [showWindow]="false"
    (close)="closeModel()">
</hzz-map-model>

| 参数 | 类型 | 默认值 | 说明 | | ----------------------- | ------------ | --------------- | ---------------------------------------------------------------------- | | initLineChartStartEnd | Date[] | [] | 初始化折线图的起止时间 | | initMapStartEnd | Date[] | [] | 初始化时在地图上显示的轨迹时间范围（前后半小时） | | getData | Function | - | 必传，获取速度轨迹数据的方法，签名 (start, end, env) => Promise | | getHistoryDataByDate | Function | - | 获取 7 日外历史轨迹的方法，签名 (date, env) => Promise | | basicData | object | {} | 地图上显示的基础信息（采区 geom、航道 shipGeom、运输路线 vehicleGeom） | | dataType | string | 'mining_ship' | 数据类型：mining_ship / trans_ship / car | | env | any | - | 传递给 getData 方法的环境参数 | | canSeeHistory | boolean | true | 是否可以查看历史轨迹（控制折线图 dataZoom 和点击事件） | | showWindow | boolean | false | 是否显示"查看空窗期"按钮 | | getWindowdata | Function | - | 获取空窗期数据的方法，签名 (env) => Promise | | close | EventEmitter | - | 关闭弹窗事件 |

hzz-weight-model

历史开采量弹窗组件。以折线图形式展示实时开采量和许可实施量的对比。

<hzz-weight-model
    [initLineChartStartEnd]="[startDate, endDate]"
    [getData]="getWeightData"
    [env]="env"
    (close)="closeModel()">
</hzz-weight-model>

| 参数 | 类型 | 默认值 | 说明 | | ----------------------- | ------------ | ------ | ----------------------------------------------------------------------- | | initLineChartStartEnd | Date[] | [] | 初始化折线图的起止时间 | | getData | Function | - | 必传，获取历史开采量数据的方法，签名 (start, end, env) => Promise | | env | any | - | 传递给 getData 方法的环境参数 | | close | EventEmitter | - | 关闭弹窗事件 |

getData 返回数据格式：

{
    allowTotal: 1000,  // 许可实施量（吨）
    historyData: [
        { time: '2024-01-01', total: 500 },
        { time: '2024-01-02', total: 600 },
        // ...
    ]
}

common-data.service

一些常用的方法，具体参考注释，这里的是通义千问整理的，有些不那么准确。

日期与时间处理

1. dateToString

   • 参数: datee(日期), con(可选，分隔符，默认 '-')
   • 返回值: 字符串 "YYYY-MM-DD"
   • 示例:

   const dateString = this.dateToString(new Date(), '-'); // "2023-04-01"

2. stringToDate

   • 参数: date(日期字符串), connet(可选，分隔符，默认 '-')
   • 返回值: Date 对象
   • 示例:

   const dateObj = this.stringToDate("2023-04-01");

3. convertToDate

   • 参数: dateStr(格式如 "3月1日")
   • 返回值: Date 对象
   • 示例:

   const date = this.convertToDate("3月1日"); // 当前年-03-01

4. dateAddYear

   • 参数: yearStr(年份字符串), date(Date 对象)
   • 返回值: Date 对象
   • 示例:

   const newDate = this.dateAddYear("2025", new Date());

5. isDateInRange

   • 参数: date(日期), range(范围数组 [start, end])
   • 返回值: boolean
   • 示例:

   isDateInRange(new Date(2023, 3, 15), [new Date(2023, 3, 1), new Date(2023, 3, 31)]) // true

6. getDaysBetween

   • 参数: dateString1, dateString2（格式 "YYYY-MM-DD"）
   • 返回值: 天数差（日期 1 晚于日期 2 返回 0，相同返回 1）
   • 示例:

   this.getDaysBetween("2023-01-01", "2023-01-10"); // 9

文件操作与下载

1. exportExcel

   • 参数: datas(二维数组), fileName(文件名), sheetNames(sheet 名称数组)
   • 示例:

   this.exportExcel([[{name: "张三"}]], "employees.xlsx", ["Staff"]);

2. triggerDownload

   • 参数: url(文件 URL), filename(文件名)
   • 功能: 创建隐藏 <a> 标签触发浏览器下载
   • 示例:

   this.triggerDownload("http://example.com/file.pdf", "myFile.pdf");

3. urlToFIle

   • 参数: downloadurl(URL), headers(HttpHeaders)
   • 返回值: Promise<string>
   • 功能: 从 URL 异步下载文件内容，返回文件 URL

消息与 UI 操作

1. showMessage

   • 参数: type(0:加载中, 1:成功, 2:失败, 3:警告, 4:提示), info(消息内容), duration(可选，毫秒)
   • 示例:

   this.showMessage(1, "操作成功", 2000);

2. showLoading / removeLoading

   • showLoading 参数: loadingText(加载提示文字)，返回消息 ID
   • removeLoading 参数: id(showLoading 返回的 ID)
   • 示例:

   const loadingId = this.showLoading("正在加载...");
   this.removeLoading(loadingId);

数据处理与验证

1. structuralClone

   • 参数: obj(待克隆对象)
   • 返回值: Promise，深拷贝后的对象
   • 示例:

   const clonedObj = await this.structuralClone(originalObj);

2. generateYears

   • 参数: startYearStr, endYearStr(起止年份字符串)
   • 返回值: 字符串数组
   • 示例:

   this.generateYears("2000", "2010"); // ["2000", "2001", ..., "2010"]

数学与字符串操作

1. random

   • 参数: x(长度)
   • 返回值: 指定长度的随机字符串

2. digitalToDegrees

   • 参数: digital(小数形式经纬度)
   • 返回值: 度分秒字符串
   • 示例:

   this.digitalToDegrees(109.86330555555556); // "109°51′47.9″"

其他实用功能

1. mergeAdjacentRanges

   • 参数: periods(二维数组，时间段列表)
   • 返回值: 合并后的二维数组
   • 示例:

   this.mergeAdjacentRanges([[1, 3], [2, 4], [5, 7]]); // [[1, 4], [5, 7]]

2. calculateAndRenderBlankRows

   • 参数: div(容器元素), data(表格数据), singleRowHeight(单行高度 px)
   • 返回值: 空白行数据数组

3. verifyFields

   • 参数: obj(对象或值), regular(验证规则)
   • 返回值: [是否合法, 错误信息]
   • 当 obj 为对象时，regular 格式：{ fieldName: [是否必填(0/1), 正则, '错误提示'] }

   var regu = {
       vol: [1, RegVer.number, '库容数值不合法'],
       hnnm: [1, RegVer.name, '河流名称非法'],
       tel: [0, RegVer.phone, '电话不合法'],
   };
   var v = verifyFields(obj, regu);
   if (!v[0]) {
       console.log(v[1]);
   }

字符串处理

1. trimObj(obj) - 去除对象中字符串属性值的前后空格
2. trimObj1(obj) - 去除对象中字符串属性值的前后空格和换行符
3. filterNull(obj) - 删除对象中值为 null 的属性