# @acedatacloud/core 中文文档
规范地址：https://npmcn.com/package/%40acedatacloud/core/
版本：0\.28\.3
npm 元数据更新时间：2026-10-07T05:28:29.503Z
中文译文更新时间：2026-11-07T04:19:36.572Z
软件包许可：UNLICENSED
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40acedatacloud/core
原文对照：https://npmcn.com/package/%40acedatacloud/core/?lang=original
项目主页：https://github.com/AceDataCloud/CommonFrontend
源码仓库：https://github.com/AceDataCloud/CommonFrontend
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：366 kB，266 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：6 个
- peer 依赖：vue \>=3\.2\.0 \<4，axios \>=1\.0\.0 \<2，mustache \>=4\.0\.0 \<5，vue-i18n \>=9\.1\.0 \<12，@lucide/vue \>=1\.23\.0 \<2，element-plus \>=2\.10\.4 \<3，aegis-web-sdk \*，json-logic-js \>=2\.0\.0 \<3，vue-advanced-cropper ^2\.8\.9
- 首次发布：2026-06-15T02:23:35.581Z
- 最新版本发布：2026-10-07T05:28:29.329Z
- 近 30 天下载量：2050（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 37 个）
## 中文简介
AceDataCloud的浏览器应用软件(AuthFrontend / Nexior / Platfrontend)共享前端核心:http客户端工厂,遥测,指纹,块重回收,locale +地表辅助器,并共享类型.
## 安装
```sh
npm install @acedatacloud/core
```
也可以使用：`pnpm add @acedatacloud/core`、`yarn add @acedatacloud/core`、`bun add @acedatacloud/core`
## README
# @ acedatacloud/ 核心
AceDataCloud 三款浏览器应用程序共享前端核心 :
- [`AuthFrontend`](https://github.com/AceDataCloud/AuthFrontend) —— 说 `auth.acedata.cloud`
- [`Nexior`](https://github.com/AceDataCloud/Nexior) —— 说 `studio.acedata.cloud` (消费者/聊天)
- [`PlatformFrontend`](https://github.com/AceDataCloud/PlatformFrontend) —— 说 `platform.acedata.cloud` (开发者/ 打开 API)
这些应用程序已经独立地重新执行同样的管道(轴截取器, 零载取回、遥测、指纹、地块分辨率) 细节。 这个包裹可以抬起 **正确性敏感的重复** 进入一个地方 应用程序停止在差异导致真实的认证/可观察性错误的部分出现分歧.
## 分发——已公布npm软件包
通过正常方式 `package.json` 依赖( 无子模块, 无) `@common` 别名 :
```bash
npm install @acedatacloud/core
```
软件包是简单的 `tsc` 因此任何消费者 捆接器(Vite 8 / 7 / 2) 转接干净. 中情局 **合并到的自动出版物 `main`**, (中文(简体) ), 版本定型:合并仅当 `package.json`'版本还没有在 npm 上 . 发售时,将版本撞入 `package.json` 在你的公关.
### 子路径入口
仅导入您需要的东西 —— 依赖对等模块是子路径的, 因此它们会树摇 :
```ts
import { createChunkLoadErrorHandler, makeGetLocale, isWechat } from '@acedatacloud/core/core';
import { createHttpClient } from '@acedatacloud/core/http'; // peer: axios
import { createTelemetry } from '@acedatacloud/core/telemetry'; // peer: aegis-web-sdk (optional)
import { createFingerprintResolver } from '@acedatacloud/core/fingerprint';
import type { IUser, IConnection } from '@acedatacloud/core/types';
import type { ITranslationEnableRequest, ITranslationEnableResponse } from '@acedatacloud/core/types';
import { CURRENCY_LABEL_MAPPING, LOCALE_CURRENCY_MAPPING } from '@acedatacloud/core/constants';
import { debug, getBaseUrlAuth } from '@acedatacloud/core/utils';
import { replaceBrandText } from '@acedatacloud/core/brand-spacing';
import { buildUsageAnalytics, formatUsageAmount, formatUsageElapsed } from '@acedatacloud/core/usage';
import { extractX402PaymentError, resolveX402PaymentError } from '@acedatacloud/core/x402';
```
根项`@acedatacloud/core`再出口无依赖表面 (单位:千美元)`core`, (中文(简体) ), `types`, (中文(简体) ), `constants`, (中文(简体) ), `utils`) (中文(简体) ).
### 用法分析
`@acedatacloud/core/usage` 将 API 聚合行转换为堆叠列系列, 甜甜圈切片,以及Platfrontend和PlainFrontend使用的完整API分解 涅盘. 它保留了重复的一行总和,日期订购,99%的支出 阈值、20号编上限和单左倾例外。 通过 翻译“其他”标题;帮助者添加了折叠的API计数。 留额 在信贷。 该模块没有图.js,Vue,HTTP,或存储依赖性.
消费者保留请求过滤器、地方选择、装入/误入状态, (原始内容存档于2013-10-12). Stale-response guards and Chart.js options. `formatUsageAmount` 财务报告和审定财务报表 `formatUsageElapsed` 保留其现有的表格和工具提示格式.
### 共享组件
在应用程序条目中导入共享样式表一次, 然后从专用子路径导入组件 :
```ts
import '@acedatacloud/core/styles.css';
import { Pagination } from '@acedatacloud/core/components';
```
`Pagination` 保存现有的 Nexior 和 Platfrontend 道具以及 `change` 事件合同。 它的圆控件使用共享 `--adc-radius-round` 符号在 `styles.css`。 。 。 .
共享的作物取景口保持了放大,旋转,翻转,替换控制,并贯穿了三个前端的作物框架一致. 应用程序仍然拥有文件选择、对话框、上传和品牌处理:
```ts
import { ImageCropperViewport } from '@acedatacloud/core/components/image-cropper-viewport';
import '@acedatacloud/core/image-cropper.css';
import 'vue-advanced-cropper/dist/style.css';
```
通过本地化 `labels`, (中文(简体) ), `src`, (中文(简体) ), `aspectRatio`,可选择 `shape`, (中文(简体) ), `imageRestriction`, (中文(简体) ), `controlSize`,或 `checkerboard`。接触者 `getResult()` 返回时 `null` 为一空收成. 设定 `--adc-image-cropper-height` 上方为视图高度的组件.
`BackNavigation`, (中文(简体) ), `StatusBadge`, (中文(简体) ), `MetaTag`, (中文(简体) ), `ActionChip`,以及 `FilterChip` 使用相同的样式表 :
```vue
All campaigns
Submitted
Vision
Manage key
Images
```
应用程序导入 `RouterLink`;共享组件没有路由器/存储依赖. `BackNavigation` 默认为未提交按钮,支持 `as="a"` 加号 `href`,并转发路径属性和事件。 父母通航,历史倒计时,向导出步,被解职,OAuth召回和脏后卫仍然属于应用程序所有. 仅需要图标的工作空间返回需求 `icon-only` 特定行动 `aria-label`· ; `variant="inverse"` 支持黑暗英雄表面.
显示徽章有软背景,8px半径,12px文本和24px高; 2; `density="compact"` 是 20px 表/列表变体。 音调是 `neutral / brand / info / success / warning / danger`现有 `primary` 解析器结果映射到 `brand`; 空/未知结果映射到 `neutral`. 国对地测绘仍为应用程序所有。 使用 `MetaTag` 供参考, `ActionChip` 一项行动 `FilterChip` 用于控制 `aria-pressed` 选择。 静态徽章不会产生活地区域. 导航/芯片有44px触控目标. 语义前缘/后缘对支持光/暗对比;中性/品牌跟随应用主题/tenant口音.
控制适配器还使现有的元素加标签,包括可分解/交互标记,与这种几何和柔和的语调处理正常化. `size="small"` 紧凑; 遗留 `round`, (中文(简体) ), `effect` 财务报告和审定财务报表 `large` 不创建相竞的形状或填充。 当显示徽章会丢失时, 请在 Elements 标签上保持应用程序特定交互 .
### 共享标记下
```ts
import {
MarkdownRenderer,
createMarkdownRenderer,
} from "@acedatacloud/core/markdown";
import "@acedatacloud/core/markdown.css";
```
`MarkdownRenderer` 带 `source`反应 `options`, (中文(简体) ), `anchor`, (中文(简体) ), `linkTarget`,以及 `htmlPolicy` 道具来. 默认 `sanitize` 政策支持本地音频/视频, 丰富的文本演示样式、任务列表、表格、高亮代码和 KaTeX (单位:千美元)`$`, (中文(简体) ), `$$`, (中文(简体) ), `\(`, (中文(简体) ), `\[`栅栏 `math`) (中文(简体) ). 媒体总是有控制和 `preload="none"`;脚本,事件处理器,帧和不安全的URL被删除. 样式遵循应用程序的 Element Plus 符号,包括暗模式.
使用 `htmlPolicy="escape"` 为正文生 HTML。 现有的匿名工作室 表面保留 `markdownSanitize` 注射数/ `sanitize` 道具出逃后卫. `trusted` 仅供现有可信、生成的文档内容使用. 标题主播是选入;页面链接保持当前浏览上下文. 引用卡、复制按钮、导航和应用程序专用型号停留 与消费者。 纯渲染器和Vue适配器也在SSF期间工作.
消费者使用正常发布的npm包. 合并并发布核心 在合并依赖寄存器中的收养PR之前释放.
### 设计符号
`styles.css` 还定义了没有全球样式应用要素的共享视觉基线:
- 具有主题意识的颜色、文字、表面和边框别名;
- 页:1 `4 / 8 / 12 / 16 / 20 / full` 半径比例 `small / control / card / dialog` 语义学;
- a 4px相距网格;
- 共享字体家族、大小、重量、行高和字母间隔符号.
- 按钮关卡 `xs/sm/md/lg/xl` ; 内置副本用途 `xs`, (中文(简体) ), 快速扩展用途 `sm`,且代码块 Copy 保留其 30px 特例; 元素加按钮保留其本地小/ 默认/ 大大小, 除非 单个组成部分选择加入;
- 焦点轮廓/环、高地、运动和堆积层符号;
- 减少运动时间超过.
消费者通过绘制其现有的根变量和组件样式来选择 `--adc-*`。运行时口音颜色和光/暗表面仍然为每个应用程序的Element Plus主题所拥有.
### 核心控制适配器
在供应商和应用风格之后导入控制适配器—— **包括尾风** 因此,它的变体安全Elements Plus合同获胜,没有 `!important`数字 :
```ts
import '@acedatacloud/core/styles.css';
import './assets/scss/style.scss';
import './assets/css/tailwind.css';
import '@acedatacloud/core/controls.css';
```
保存中 `controls.css` 最后一个是负载,不是化妆品。 它携带一个 `svg { display: inline-block }` 重置取消 Tailwind 预飞的 `svg { display: block }` (否则中断) `text-align: center` 图标。 两种选择器都有相同的特异性,所以重置只能通过后来取胜——在后来后导入 Tailwind `controls.css` 它静静地停止工作.
适配器将按钮,输入,选择,文本区域,卡片,对话框,和MessageBox标准化,同时保留Element的链接/文本/循环大小,错误状态,输入组接合,以及卡片阴影模式. 应用程序可以保留特定产品卡的样式 `--adc-control-card-border`, (中文(简体) ), `--adc-control-card-shadow`, (中文(简体) ), `--adc-control-card-shadow-hover`,以及 `--adc-control-dialog-shadow`; 因为对话框和信件框被传送, 设置覆盖钩 `:root` 或者说 `body`。 。 。 .
使用 `card-gap` 在卡片组和 `card-section-gap` 用于卡片区下方的空间。 双用 `--adc-card-gap`,默认为 20px 间隔符;一个应用程序可以设置自己的值 `:root`元素行保持自己的水平地沟 和地沟 `el-col.grid.card-gap` 保持一个网格.
对牌组,加 `card-gap` 至其网格、弹性容器,或 `el-row`。 。 。 . 它在牌之间保持一个共享的20px空格; 在 `el-row` 它保留了元素加的 水平地沟并仅添加列围时需要的垂直缺口.
### 语义图标
`@acedatacloud/core/icons` 定义每个产品语义学的 Lucide glyph 。 品牌标志仍然是官方的SVG/品牌资产,没有被映射给Lucide. `@acedatacloud/core/icons/components` 静态再导出完整的被审查的语义集;原有的单相子路径仍然可供兼容.
使用图标子路径的消费者必须在同一个领养PR中精确锁定测试的对等方:
```bash
npm install --save-exact @lucide/vue@1.23.0
```
清单是一个审查来源,而不是动态运行时间解析器。 例如,消费者代码使用指定的进口 `import { AddIcon, SearchIcon } from '@acedatacloud/core/icons/components'`; 捆绑树摇未用名再出口. 不使用 `import * as Icons`卢西德 `DynamicIcon`,或生产捆绑中的任意图标名称字符串。 遗产呼叫站点是按产品含义迁移的,从不通过全球取代Font Assoudy glyph来迁移.
## 版式
```
src/
├── core/ # Pure TS, zero framework deps
│ ├── chunkLoadError.ts createChunkLoadErrorHandler({ storagePrefix })
│ ├── surface.ts isWechat(), isMobile()
│ └── locale.ts makeGetLocale({ supportedLocales, defaultLocale })
├── http/ # peer: axios
│ └── createHttpClient.ts createHttpClient(config) — request/response interceptor contract
├── telemetry/ # peer: aegis-web-sdk (optional, dynamically imported)
│ └── createTelemetry.ts createTelemetry({ projectId, hostUrl }) — Tencent RUM glue
├── fingerprint/ # FingerprintJS loader injected (no SDK dep — v4/v5 both work)
│ └── createFingerprintResolver.ts
├── types/ # Pure TypeScript interfaces (user, connection, skill, oauthApp)
├── brand-spacing/ # Unicode-aware boundaries; consumers own source/replacement policy
├── constants/ # base URLs plus shared locale/currency mappings
├── utils/ # getBaseUrl* helpers plus the shared console.debug alias
└── index.ts # root re-export of the dependency-free surface
```
### 设计说明
- **工厂,不是单子.** 所有不同的应用程序( 超时、 标题) 外壳,指代/用户 Id/指印的出处,401做什么,RUM分机 映射,指印JS版本)通过配置来注入. 包裹从不进口商店, 路由器,或 `vuex`。 。 。 .
- **何谓 _没有_ 这里:** Vuex商店,应用专用的路由/自动助手, 品牌特性/政策,以及业务工作流程. `brand-spacing` 是一个无依赖的文本边界帮助器;每个消费者拥有其源变体和替换品牌. 元素加组件仅在 现有应用软件的实施和公共合同相同.
## 开发
```bash
npm install
npm run typecheck # tsc -p tsconfig.json (no emit)
npm test # vitest (jsdom)
npm run build # tsc -p tsconfig.build.json -> dist/
```
## 许可证
私人——AceDataCloud内部.
### 用户获取背景
`@acedatacloud/core/attribution` 提供创建 UTM标签和一个捕获时间戳. 它只读/写浏览器 cookie; 它有 没有获取、访问控件、身份约束、事件队列或认证依赖性. 明确标记的起落架取代了完整的起落架. 未标记导航保存 它不会延长它的七天期限。 注册读取上下文一次 Auth后端在已存在的User.metadata中将其冻结. 无遗赠饼干 时间戳仍然是遗留的证据,而不是得到一个发明的先触即发的时间.
浏览器上游尊重 DNT/GPC, 保存选择退出、 公开发票页和 初始方主机边界。 存储失败不影响页面导航. 收购规则由PlatfaceBackend/config/marketing atribution.json生成. 此软件包仅包含获取预测, 不包含服务条目或 频道盘点. 后端自有出口商生成被绑的JSON 和 TypeScript 常数; UTM KEYS 是从该常数衍生出来的. 添加 MCP 或 运动不需要核心释放。 字段/窗口更改需要版本 消费者收养前的核心释放。 见PlatfaceBackend/scripts/ECOSYSTEM CONTRACTS.md.
## 常见问题
### @acedatacloud/core 是什么？
AceDataCloud的浏览器应用软件\(AuthFrontend / Nexior / Platfrontend\)共享前端核心:http客户端工厂,遥测,指纹,块重回收,locale \+地表辅助器,并共享类型\.
### 如何安装 @acedatacloud/core？
在项目目录运行 npm install @acedatacloud/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@lucide/vue（\>=1\.23\.0 \<2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @acedatacloud/core 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @acedatacloud/core 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @acedatacloud/core 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @acedatacloud/core 可以商用吗？
@acedatacloud/core 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。
### @acedatacloud/core 的下载量有多少？
根据 npm 官方下载统计，@acedatacloud/core 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,050 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @acedatacloud/core 还在维护吗？
最新版本 0\.28\.3 发布于 2026/10/07（1 个月前）；至今共发布 37 个版本，其中过去 12 个月发布了 37 个；首次发布于 2026/06/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。