---
url: 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/development/api'
title: 'API 参考 | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T00:45:31+00:00'
updated: '2026-10-24T09:09:48+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: 'DXPR Builder 定义的 PHP 服务、JavaScript 扩展点和路由。服务 ID 来自 dxpr_builder.services.yml，路由来自 dxpr_builder.routing.yml。各路由的请求和响应详情请参阅 API 端点。'
tags:
  - 'Architectuur en API’s'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-24T09:09:48+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'API 参考'
      description: 'DXPR Builder 定义的 PHP 服务、JavaScript 扩展点和路由。服务 ID 来自 dxpr_builder.services.yml，路由来自 dxpr_builder.routing.yml。各路由的请求和响应详情请参阅 API 端点。'
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-24T00:45:31+0000'
      dateModified: '2026-10-24T09:09:48+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/development/api'
      articleSection: 'Architectuur en API’s'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/development/api'
      description: 'DXPR Builder 定义的 PHP 服务、JavaScript 扩展点和路由。服务 ID 来自 dxpr_builder.services.yml，路由来自 dxpr_builder.routing.yml。各路由的请求和响应详情请参阅 API 端点。'
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: 首页
            item: 'https://dxpr.com/zh-hans'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: zh-hans
---
[Help Center](/zh-hans/node/75)/[Documentation](/zh-hans/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Extend](/hc/documentation/learn-dxpr-builder/extend) /[Architectuur en API’s](/hc/documentation/learn-dxpr-builder/extend/architecture) # API 参考.

 Learn DXPR BuilderExtendArchitectuur en API’s

   ## In this guide

DXPR Builder 定义的 PHP 服务、JavaScript 扩展点和路由。服务 ID 来自 `dxpr_builder.services.yml`，路由来自 `dxpr_builder.routing.yml`。各路由的请求和响应详情请参阅 [API 端点](/zh-hans/hc/documentation/learn-dxpr-builder/reference/api-endpoints)。

## PHP 服务

| 服务 ID | 类（位于 `src/`） | 用途 |
|---|---|---|
| `dxpr_builder.service` | `Service\DxprBuilderService` | 为输出准备构建器内容，处理路径令牌，构建图标集注册表 |
| `dxpr_builder.license_service` | `Service\DxprBuilderLicenseService` | 许可证状态、计费用户、与 DXPR 的编辑人员同步 |
| `dxpr_builder.key_service` | `Service\DxprBuilderKeyService` | 读取和存放产品密钥 |
| `dxpr_builder.jwt_decoder` | `Service\DxprBuilderJWTDecoder` | 解码产品密钥载荷 |
| `dxpr_builder.user_settings` | `Service\UserSettings` | 每位编辑人员自己的编辑器设置，存放在用户数据中 |
| `dxpr_builder.content_lock` | `Service\ContentLock` | 记录哪位用户正在编辑实体修订 |
| `dxpr_builder.content_migration` | `Service\ContentMigrationService` | 运行内容迁移；收集服务项，其标签为 `dxpr_builder.content_migration` |
| `dxpr_builder.profile_handler` | `Service\Handler\ProfileHandler` | 将档案转为编辑器设置 |
| `dxpr_builder.handler.block` | `Service\Handler\BlockHandler` | 渲染作为元素放置的 Drupal 区块 |
| `dxpr_builder.handler.view` | `Service\Handler\ViewHandler` | 渲染作为元素放置的视图显示 |
| `dxpr_builder.template_image_validator` | `Service\TemplateImageValidator` | 验证模板预览图片 |
| `dxpr_builder.rl_variant.extractor`、`dxpr_builder.rl_variant.registrar` | `RlIntegration\Service\*` | A/B 测试变体；没有 RL 模块时不活动 |
| `dxpr_builder.rl_sort.extractor`、`dxpr_builder.rl_sort.registrar` | `RlIntegration\Service\*` | 智能排序实验；没有 RL 模块时不活动 |
| `logger.channel.dxpr_builder` | 核心日志通道 | 日志通道 `dxpr_builder` |

### DxprBuilderServiceInterface

由 `dxpr_builder.service` 实现。您最可能调用的方法：

- `insertBaseTokens($content)`：将本站基本 URL、文件目录和模块路径替换为令牌。编辑器以这种形式存放内容。
- `replaceBaseTokens(&$content): void`：将令牌展开回当前环境的 URL。
- `stripHtmlElementPersists(string $markup): string`：移除 `data-az-persist` 属性。对编辑器外写的标记运行它；编辑器加载时重建它们。
- `getCmsElementNames()`：作为元素提供的区块和视图显示，带缓存。
- `getIconSets(): array`：YAML 发现和 `hook_dxpr_builder_icon_sets_alter()` 之后的图标集注册表。

```php
$markup = \Drupal::service('dxpr_builder.service')->insertBaseTokens($html);

```

### DxprBuilderLicenseServiceInterface

由 `dxpr_builder.license_service` 实现。

- `isBillableUser(?AccountInterface $account = NULL): bool`：user 1 以及拥有 `edit with dxpr builder` 且未被排除 DXPR Builder 编辑的活动账户返回 TRUE。
- `getLicenseInfo()`：DXPR 许可证服务器的许可证状态，带缓存。没有产品密钥时返回免费套餐：一个用户和 100 个内容项。
- `syncAllUsersWithCentralStorage(string $operation, string $json_web_token = ''): void`： 将本站编辑人员发送到 DXPR。`$operation` 是接口常量之一：`DXPR_USER_SYNC_OPERATION`（`sync`）、`DXPR_USER_ADD_OPERATION`（`add`）或 `DXPR_USER_REMOVE_OPERATION`（`remove`）。

### DxprBuilderKeyService

- `getApiKey(): ?string`：产品密钥。`api_key_storage` 设置为 `key` 时读取 `key_provider` 命名的 Key 实体；否则读取 `json_web_token`。
- `setApiKey(string $key_value, string $storage_type = 'config', ?string $selected_key_id = NULL): void`： 将密钥存入配置或 Key 实体。

### DxprBuilderJWTDecoder

- `decodeJwt(string $access_token)`：返回产品密钥的 `sub`、`scope` 和 `dxpr_tier` 声明，令牌不可读时各项为 NULL。结果按令牌缓存。

## JavaScript 扩展点

编辑器脚本在 `window.dxprBuilder` 上共享两个数组。在创建数组的脚本与读取它们的 `dxpr_builder.js` 之间（它运行时读一次），将您自己的对象推入它们。

| 数组 | 创建方 | 该 `dxpr_builder.js` 的处理 |
|---|---|---|
| `dxpr_param_types` | `dxpr_param_types.js` | 将每个对象注册为参数类型，用 `register_param_type()` |
| `dxpr_elements` | `dxpr_elements.js` | `create_dxpr_elements()` 用 `register_animated_element()` 注册每个定义，转换其 `params` 用 `make_param_type()` |

模块注册的参数类型有 `boxmodel`、`checkbox`、`checkboxes`、`colorpicker`、`datetime`、`dropdown`、`dxb_slider`、`html`、`icon`、`image`、`images`、`link`、`links`、`numericfield`、`row_layout`、`saved_datetime`、`social_links`、`textarea`、`textfield` 和 `video`。`type` 未知的参数渲染为普通文本输入框。

[自定义元素](/zh-hans/hc/documentation/learn-dxpr-builder/development/custom-elements)展示了完整的元素定义，以及如何在正确的时机加载它。

## 编辑器路由

访问图例：**billable** 是 `_dxpr_builder_billable_user` 检查（user 1，或拥有 `edit with dxpr builder` 且未被排除的活动账户）；**CSRF** 是 `_csrf_token`。

| 路径 | 路由名 | 方法 | 访问 |
|---|---|---|---|
| `/dxpr_builder/ajax` | `dxpr_builder.ajax_callback` | any | billable、CSRF |
| `/dxpr_builder/ajax/file_upload` | `dxpr_builder.ajax_file_upload_callback` | POST、DELETE | billable、CSRF |
| `/dxpr_builder/ajax/ai/chat` | `dxpr_builder.ai_chat` | POST | `edit with dxpr builder`、billable、CSRF |
| `/dxpr_builder/ajax/ai/image` | `dxpr_builder.ai_image` | POST | `edit with dxpr builder`、billable、CSRF |
| `/dxpr_builder/ajax/ai/image/edit` | `dxpr_builder.ai_image_edit` | POST | `edit with dxpr builder`、billable、CSRF |
| `/dxpr_builder/csrf` | `dxpr_builder.csrf_refresh` | any | billable |
| `/dxpr_builder/ajax/help_link_validator` | `dxpr_builder.ajax_help_link_validator` | any | billable |
| `/dxpr_builder/media-library` | `dxpr_builder.media_library` | any | `view media` |
| `/dxpr_builder/entity-link-suggestions` | `dxpr_builder.entity_link_suggestions` | GET | `edit with dxpr builder`、CSRF |
| `/dxpr_builder/user-settings` | `dxpr_builder.user_settings` | POST | `edit with dxpr builder`、CSRF |

## 管理路由

所有管理页面都在 **DXPR Studio > DXPR Builder** 下。Tab 列显示管理菜单中的标签。

| 路径 | 选项卡 | 权限 |
|---|---|---|
| `/admin/dxpr_studio` | DXPR Studio | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder` | DXPR Builder | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/settings` | General Settings | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/ai_settings` | AI | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/content` | Content Items | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/migration-status` | Migrations (under Content Items) | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/page_template` | Page Templates | `administer site configuration` |
| `/admin/dxpr_studio/dxpr_builder/user_licenses` | User Licenses | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/profile` | User Profiles | `administer dxpr_builder_profile` |
| `/admin/dxpr_studio/dxpr_builder/user_templates` | User Templates | `administer site configuration` |