Crowdin 应用程序 JS

Crowdin Apps JS 是一个 JavaScript 库，可实现您的应用与 Crowdin UI 之间的通信。由于所有 Crowdin 应用都在沙盒 \<iframe> 中运行，它们是隔离的，无法直接访问 Crowdin 主页面的内容或代码。

该库通过提供安全的跨窗口消息传递（postMessage()）桥接来解决这一问题。引入库后，您将可以访问全局 AP（App Project）对象。该对象是调用方法（如 AP.getContext()）和订阅事件（如 AP.events.on()）的唯一入口点。

入门

要使用 AP 对象，必须在应用 HTML 页面的 \<head> 中引入 iframe.js 脚本。

<script src="https://cdn.crowdin.com/apps/dist/iframe.js"></script>

AP.getContext(function(contextData) {
  if (contextData) {
    console.log("Current project ID:", contextData.project_id);
    if(contextData.editor) {
      console.log("Current file name:", contextData.editor.fileData.name);
    }
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：ContextDataObject 或 null。

响应有效载荷示例

{
  "project_id": 123,
  "organization_id": 100001,
  "editor": {
    "mode": "translate",
    "theme": "dark",
    "source_language_id": "en",
    "target_language_id": "fr",          // Present in "translate" and "proofread"
    "target_language_ids": ["fr", "uk"], // Present only in "multilingual"
    "active_target_language_id": "fr",   // The currently active target language in the Editor
    "task_id": 327,                      // Present only if Task-based access control is enabled
10 collapsed lines
    "task": {
      "id": 327,
      "type": 2,
      "status": 0,
      "title": "New task",
      "description": "Task description",
      "created": "2025-01-01 10:30:00",
      "to_language": "French",
      "workflow_step_id": 0,
      "workflow_step_title": "",
      "language_id": "fr"
    },
    "file": 987,
35 collapsed lines
    "fileData": {
      "id": "987",
      "is_plain_text": true,
      "type": "android",
      "status": "1",
      "parent_id": "0",
      "node_type": "1",
      "created": "2025-01-01 10:30:00",
      "extension": "xml",
      "priority": "1",
      "name": "example_file.xml",
      "upload_ready": 1,
      "export_ready": 1,
      "export_xliff_ready": 1,
      "can_change": 1,
      "plural_support": 1,
      "excluded_languages": [],
      "html_preview": 0,
      "identifier_required": 1,
      "total": 50,
      "translated": 10,
      "approved": 5,
      "preTranslated": 0,
      "translated_percent": 20,
      "approved_percent": 10,
      "progress": {
          "total": 50,
          "translated": 10,
          "approved": 5,
          "translated_percent": 20,
          "approved_percent": 10,
          "pre_translated": 0,
          "file_id": 987,
          "language_id": 2,
          "translation_link": "/editor/project-name/987/en-fr"
      }
    },
3 collapsed lines
    "workflow_step": {
      "id": 7777,
      "title": "Translation",
      "type": "Translate"
    }
  }
}

响应对象结构

`project_id`	类型： `integer` 描述：当前项目的唯一数字 ID。
`organization_id`	类型： `integer` 描述：组织的唯一数字 ID（仅限 Crowdin Enterprise）。
`editor`	类型： `object` \| `null` 描述：包含编辑器上下文的对象。如果应用不在编辑器中，则为 `null`。
`editor.mode`	类型： `string` 允许值： `translate`、`proofread`、`multilingual` 描述：编辑器的当前模式。
`editor.theme`	类型： `string` 允许值： `light`、`dark`、`auto` 描述：编辑器当前的 UI 主题。
`editor.source_language_id`	类型： `string` 描述：源语言的 ID（例如，`“en”`）。
`editor.target_language_id`	类型： `string` 描述：当前目标语言的 ID（例如，`“fr”`）。
`editor.target_language_ids`	类型： `array` 描述：目标语言 ID 的数组。当 `editor.mode` 设置为 `multilingual` 时，此字段将替换 `editor.target_language_id`。
`editor.active_target_language_id`	类型： `string` 描述：编辑器中当前活动目标语言的 ID（例如，`“fr”`）。在 `multilingual` 模式下，该值根据光标位置动态更新。
`editor.task_id`	类型： `integer` 描述：当前任务的数字 ID。仅当在项目设置中启用了基于任务的访问控制时，才会出现此字段。
`editor.task`	类型： `object` 描述：包含当前任务元数据的详细对象（例如标题、状态、描述）。仅与 `editor.task_id` 一起出现。
`editor.file`	类型： `integer` 描述：编辑器中当前打开文件的数字 ID。
`editor.fileData`	类型： `object` 描述：包含已打开文件数据的详细对象。（此对象与 `AP.editor.getSelectedFiles` 中返回的对象相同）。
`editor.fileData.id`	类型： `string` 描述：文件 ID（字符串形式）。
`editor.fileData.name`	类型： `string` 描述：文件名称。
`editor.fileData.node_type`	类型： `string` 描述：节点类型（`“1”` 表示文件，`“0”` 表示文件夹）。
`editor.fileData.total`	类型： `integer` 描述：文件中字符串的总数。
`editor.fileData.progress`	类型： `object` 描述：包含当前语言翻译进度数据的对象。
`editor.fileData.progress.translation_link`	类型： `string` 描述：编辑器中文件的相对 URL 路径。
`editor.workflow_step`	类型： `object` \| `null` 描述：仅限 Crowdin Enterprise。当前工作流步骤的详细信息。如果没有活动的工作流，则为 `null`。
`editor.workflow_step.id`	类型： `integer` 描述：工作流步骤的数字 ID。
`editor.workflow_step.title`	类型： `string` 描述：工作流步骤的显示名称。
`editor.workflow_step.type`	类型： `string` 描述：工作流步骤的类型（例如，`“Translate”`、`“Proofread”`）。

AP.getTheme(callback)

检索当前活动用户界面（UI）主题的名称。

示例：

AP.getTheme(function(themeName) {
  console.log("Current theme:", themeName);
  // e.g., 'light', 'dark', or 'auto'
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：string（主题名称）。

响应有效载荷示例

此方法返回纯 string。

"light"

响应对象结构

类型： string

允许值： light、dark、auto

AP.getCssVariables(callback)

检索包含所有活动 Crowdin CSS 变量的对象。这允许您的应用将其元素样式设置为与用户的 UI 主题匹配，以实现无缝的外观和体验。

示例：

AP.getCssVariables(function(variables) {
  if (variables) {
    // Set our app's text color to match Crowdin's
    document.body.style.color = variables['--crowdin-body-color'];
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：object。

响应有效载荷示例

{
  "--crowdin-level-1-bg": "#f5f7f8",
  "--crowdin-level-2-bg": "#ffffff",
  "--crowdin-body-bg": "#f5f7f8",
  "--crowdin-title-color": "rgba(38, 50, 56, 1)",
  "--crowdin-body-color": "rgba(38, 50, 56, 0.87)",
  "--crowdin-text-muted": "rgba(38, 50, 56, 0.54)",
  "--crowdin-primary": "rgba(67, 160, 71, 1)",
  "..." : "..."
}

响应对象结构

返回一个对象，其中每个键是 CSS 变量名（例如，"--crowdin-primary"），值是其当前计算值（例如，"rgba(67, 160, 71, 1)"）。

AP.getJwtToken(callback)

检索当前用户的身份验证 JWT 令牌。此令牌可用于代表用户发出 Crowdin API v2 请求。

示例：

AP.getJwtToken(function(token) {
  if (token) {
    console.log("My JWT:", token);
  } else {
    console.log("Token is not available in this context.");
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：string（JWT 令牌）或 null。

响应有效载荷示例

此方法返回纯 string，即 JWT 令牌，或 null。

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkw...SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

视口与尺寸

这组方法允许您的应用获取有关其 iframe 尺寸和位置的信息，并请求尺寸变更。

AP.getViewportSize(callback)

检索应用 iframe 的当前可见尺寸。这对于了解用户滚动时实际可见的应用内容非常有用。

示例：

AP.getViewportSize(function(viewport) {
  console.log("Visible iframe width:", viewport.width);
  console.log("Visible iframe height:", viewport.height);
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 ViewportObject。

响应有效载荷示例

{
  "width": 800,
  "height": 250
}

响应对象结构

width

类型： integer

描述： iframe 的可见宽度，以像素为单位。

height

类型： integer

描述： iframe 的可见高度，以像素为单位，已针对 Crowdin 主标题和滚动进行调整。

AP.getWindowSize(callback)

检索整个浏览器窗口（top 窗口）的尺寸，而不仅仅是应用的 iframe。

示例：

AP.getWindowSize(function(windowSize) {
  console.log("Browser window width:", windowSize.width);
  console.log("Browser window height:", windowSize.height);
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 WindowSizeObject。

响应有效载荷示例

{
  "width": 1440,
  "height": 900
}

响应对象结构

width

类型： integer

描述： 浏览器窗口的总宽度，以像素为单位。

height

类型： integer

描述： 浏览器窗口的总高度，以像素为单位。

AP.getScrollPosition(callback)

检索应用 iframe 相对于主窗口视口顶部的垂直滚动位置。

如果应用顶部可见，则返回 0。如果用户向下滚动页面，该值将是一个正数，表示应用有多少像素滚出了视野。

示例：

AP.getScrollPosition(function(scrollPosition) {
  console.log("App is scrolled by:", scrollPosition, "pixels");
  // Example output: 150
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 integer 参数。

响应有效载荷示例

此方法返回纯 integer，表示像素数。

AP.resize(width, height)

更新应用 iframe 的尺寸。这是控制应用视图大小的主要方法。

示例：

// Request to resize the iframe to 400px wide and 500px tall
AP.resize('400px', '500px');

// You can also use percentages
AP.resize('100%', '300px')；

参数

width

类型： string

必填： 是

描述： 所需宽度（例如，500px、80%）。

height

类型： string

必填： 是

描述： 所需高度（例如，300px、100vh）。

AP.size()

检索应用 iframe 的当前尺寸。

示例：

const currentSize = AP.size();
console.log("Current width:", currentSize.w);
console.log("Current height:", currentSize.h)；

响应有效载荷示例

{
  "w": "100%",
  "h": 926
}

响应对象结构

w

类型： string | integer

描述： iframe 的当前宽度（例如，“100%” 或 800）。

h

类型： integer

描述： iframe 的当前高度，以像素为单位。

AP.registerIntersectionObserver(elementId, callback)

为应用 iframe 中的某个元素注册交叉观察器。这允许您检测当用户滚动时元素何时变为可见或隐藏。

示例：

// Assuming you have an element: <div id="my-element"></div>
AP.registerIntersectionObserver('my-element', function(entry) {
  if (entry.isIntersecting) {
    console.log('Element is now visible!');
  } else {
    console.log('Element is hidden.');
  }
})；

参数

elementId

类型： string

必填： 是

描述： 要观察的 DOM 元素的 id。

callback

类型： function

必填： 是

描述： 当元素可见性改变时触发的回调函数。该函数接收一个 IntersectionObserverEntry 对象。

表单与数据

这些方法由渲染自定义表单或需要基于 schema 数据的应用使用，例如 Crowdin Enterprise 中的自定义工作流步骤。

AP.getFormData(callback)

检索应用表单中的当前数据。当用户尝试从自定义应用界面继续时，Crowdin 通常会调用此方法。

示例：

AP.getFormData(function(formData) {
  if (formData) {
    console.log("Current form data:", formData);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收表单数据对象或 undefined/null。

响应有效载荷示例

有效载荷完全取决于应用的表单数据。

{
  "custom_field": "some-value",
  "another_setting": true
}

响应对象结构

此对象的结构由您的应用定义。

AP.formDataUpdated(detail)

通知 Crowdin 应用表单中的数据已更改。

示例：

// Call this inside your app when a form field changes
const myFormData = { custom_field: "new-value" };
AP.formDataUpdated(myFormData)；

参数

detail

类型： object

必填： 是

描述： 包含表单数据新状态的对象。

AP.getRenderData(callback)

检索 Crowdin 提供的用于渲染应用 UI 的初始数据。这通常用于需要任务特定数据的自定义工作流步骤。

示例：

AP.getRenderData(function(renderData) {
  if (renderData) {
    console.log("Initial data for rendering:", renderData);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收渲染数据对象或空对象。

响应有效载荷示例

有效载荷是动态的，取决于应用的上下文。

{
  "task_id": 123,
  "file_ids": [10, 11, 12]
}

响应对象结构

此对象的结构是动态的，由启动应用的上下文定义。

AP.getSchema(callback)

检索为应用定义的表单 schema。这通常由基于 Crowdin 提供的 schema 渲染 UI 的应用使用。

示例：

AP.getSchema(function(schema) {
  if (schema) {
    console.log("Form schema:", schema);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 schema 对象或 undefined/null。

响应有效载荷示例

有效载荷是表单 schema 对象，通常采用 JSON Schema 格式。

{
  "type": "object",
  "properties": {
    "custom_field": {
      "type": "string",
      "title": "Custom Field"
    }
  }
}

AP.editor.getString(function(stringData) {
  if (stringData) {
    console.log("Active string ID:", stringData.id);
  } else {
    console.log("No string is currently active.");
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 StringDataObject，如果没有活动字符串则为 null。

响应有效载荷示例

{
  "id": 1568759,
  "identifier": "welcome.key",
  "text": "Welcome!",
  "context": "Main screen welcome message",
  "max_length": 0,
  "file": {
    "id": 15385,
    "name": "google_play.xml"
  }
}

响应对象结构

`id`	类型： `integer` 描述：源字符串的唯一数字 ID。
`identifier`	类型： `string` 描述：字符串的键或标识符（例如，`“app.title”`）。可以为空。
`text`	类型： `string` 描述：源字符串的完整文本。
`context`	类型： `string` \| `null` 描述：与字符串关联的上下文。
`max_length`	类型： `integer` 描述：翻译允许的最大长度（`0` 表示无限制）。
`file`	类型： `object` 描述：包含此字符串所属文件信息的对象。
`file.id`	类型： `integer` 描述：文件的唯一 ID。
`file.name`	类型： `string` 描述：文件名称。

AP.editor.getStringsList(callback)

检索当前字符串列表中所有可见字符串的数据对象数组（遵循当前文件、过滤器和页面设置）。

示例：

AP.editor.getStringsList(function(strings) {
  if (strings && strings.length > 0) {
    console.log("Total strings in list:", strings.length);
    console.log("First string:", strings[0]);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 StringListObject 项的数组。

响应有效载荷示例

[
  {
    "id": 1569759,
    "project_id": "844514",
    "text": "Welcome!",
    "key": "welcome",
    "file_id": 15411
  },
  {
    "id": 1569761,
    "project_id": "844514",
    "text": "Save as...",
    "key": "save_as",
    "file_id": 15411
  }
]

响应对象结构

`id`	类型： `integer` 描述：源字符串的唯一数字 ID。
`project_id`	类型： `string` 描述：此字符串所属项目的 ID。
`text`	类型： `string` 描述：源字符串的文本。
`key`	类型： `string` 描述：字符串的键或标识符。
`file_id`	类型： `integer` 描述：此字符串所属文件的唯一 ID。

AP.editor.getSelectedStrings(callback)

检索用户在编辑器列表中当前选中（勾选）的字符串的相关信息。

示例：

AP.editor.getSelectedStrings(function(selectedData, selectedCount) {
  if (selectedData === 'all') {
    console.log(`All ${selectedCount} strings are selected.`);
  } else {
    console.log(`Selected ${selectedCount} individual strings:`, selectedData);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收两个参数（按此顺序）：

selectedData（Array|String）：SelectedStringObject 项的数组或字符串 “all”。
selectedCount（Integer）：所选字符串的总数。

响应有效载荷示例（已选择特定字符串）

[
  {
    "string": {
      "id": 1569759,
      "identifier": "welcome",
      "text": "Welcome!",
      "context": "welcome",
      "max_length": 0,
      "file": {
        "id": 15411,
        "name": "crowdin_sample_android.xml"
      }
    },
    "translations": {
      "fr": []
    }
  },
  {
    "string": {
      "id": 1569761,
      "identifier": "save_as",
      "text": "Save as...",
      "context": "save_as",
      "max_length": 0,
      "file": {
        "id": 15411,
        "name": "crowdin_sample_android.xml"
      }
    },
    "translations": {
      "fr": [
        {
          "id": 690949,
          "text": "Sauvegarder sous..."
        }
      ]
    }
  }
]

响应有效载荷示例（已选择所有字符串）

如果项目中的所有字符串都被选中，回调的第一个参数返回：

"all"

响应对象结构

当 selectedData 为数组时，以下字段适用于返回的 SelectedStringObject 项：

string

类型： object

描述： 源字符串对象。请参阅 AP.editor.getString 中的结构。

translations

类型： object

描述： 包含字符串翻译的对象，以语言 ID 为键。

translations.[language_id]

类型： array

描述： 指定目标语言（例如，“fr”）的翻译对象数组。请参阅 AP.editor.getTranslations 了解 TranslationObject 结构。

AP.editor.getSelectedFiles(callback)

检索文件树中当前选中（勾选）的所有文件的数据对象数组。

示例：

AP.editor.getSelectedFiles(function(files) {
  if (files && files.length > 0) {
    console.log("Selected files count:", files.length);
    console.log("First selected file:", files[0].name);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 FileObject 项的数组。

响应有效载荷示例

[
  {
    "id": "15411",
    "is_plain_text": true,
    "type": "android10",
    "status": "1",
    "parent_id": "0",
    "node_type": "1",
    "created": "2025-11-07 14:53:28",
    "extension": "xml",
    "priority": "1",
    "name": "crowdin_sample_android.xml",
    "upload_ready": 1,
    "export_ready": 1,
    "export_xliff_ready": 1,
    "can_change": 1,
    "plural_support": 1,
    "excluded_languages": [],
    "html_preview": false,
    "identifier_required": 1,
    "total": 45,
    "translated": 0,
    "approved": 0,
    "preTranslated": 0,
    "translated_percent": 0,
    "approved_percent": 0
  }
]

响应对象结构

`id`	类型： `string` 描述：文件的唯一 ID。
`name`	类型： `string` 描述：文件名称。
`type`	类型： `string` 描述：文件类型标识符（例如，`“android10”`、`“html32”`）。
`node_type`	类型： `string` 描述：文件树中节点的类型（例如，`“1”` 表示文件，`“0”` 表示文件夹）。
`total`	类型： `integer` 描述：文件中字符串的总数。
`translated`	类型： `integer` 描述：文件中已翻译的字符串数（针对当前语言）。
`approved`	类型： `integer` 描述：文件中已审核的字符串数（针对当前语言）。

AP.editor.isMultipleFilesSelected(callback)

检查文件树中当前是否有多个文件被选中（勾选）。

示例：

AP.editor.isMultipleFilesSelected(function(isMultiple) {
  if (isMultiple) {
    console.log("Multiple files are selected.");
  } else {
    console.log("Only one file (or no files) is selected.");
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 boolean（true 或 false）。

响应有效载荷示例

此方法返回纯 boolean。

true

AP.editor.changeFile(fileId)

更改编辑器视图以聚焦于单个不同的文件。

示例：

// Switch the Editor to show strings from file with ID 15409
AP.editor.changeFile('15409')；

参数

fileId

类型： string | integer

必填： 是

描述： 要切换到的文件的 ID。

AP.editor.changeFiles(fileIds)

在文件树中选择多个文件。这是用户勾选多个文件复选框的程序等效操作。

示例：

// Select two specific files in the file list
AP.editor.changeFiles(['15409', '15411'])；

参数

fileIds

类型： array

必填： 是

描述： 要选择的文件 ID 数组（字符串或整数形式）。

AP.editor.getUnsavedSourceStrings(callback)

检索有未保存更改的源字符串列表。

示例：

AP.editor.getUnsavedSourceStrings(function(unsavedStrings) {
  if (unsavedStrings) {
    console.log("Unsaved strings:", unsavedStrings);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收未保存字符串对象的数组或 null。

翻译

这组方法允许您读取翻译建议，以及在编辑器翻译区域中写入或修改文本。

AP.editor.getTranslations(callback)

检索当前活动源字符串的所有翻译和建议（来自用户、翻译记忆和 MT）的数组。

示例：

AP.editor.getTranslations(function(translations) {
  if (translations && translations.length > 0) {
    console.log("Total translations/suggestions:", translations.length);
    console.log("First translation author:", translations[0].author.login);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 TranslationObject 项的数组。

响应有效载荷示例

[
  {
    "id": 690949,
    "string_id": 1569689,
    "text": "Translation text",
    "target_language_id": "fr",
    "votes_rating": 0,
    "approved": false,
    "author": {
      "id": "12729493",
      "login": "example_user",
      "name": "Example User",
      "avatar_url": "https://.../avatar.png"
    },
    "created_at": "2025-11-07T08:19:10-05:00"
  }
]

响应对象结构

`id`	类型： `integer` 描述：翻译的唯一数字 ID。
`string_id`	类型： `integer` 描述：此翻译所属源字符串的 ID。
`text`	类型： `string` 描述：翻译文本。
`target_language_id`	类型： `string` 描述：此翻译所针对语言的 ID（例如，`“fr”`）。
`votes_rating`	类型： `integer` 描述：此翻译当前的投票得分。
`approved`	类型： `boolean` 描述：如果翻译已审核，则为 `true`，否则为 `false`。
`author`	类型： `object` 描述：包含翻译作者用户信息的对象。
`author.id`	类型： `string` 描述：作者的唯一 ID。
`author.login`	类型： `string` 描述：作者的登录名。
`created_at`	类型： `string` 描述：翻译创建时间的 ISO 8601 时间戳。

AP.editor.getTopTranslation(callback)

检索当前活动字符串”顶部”翻译的单个 TranslationObject（例如，已批准的翻译或获得最多票数的翻译）。

示例：

AP.editor.getTopTranslation(function(topTranslation) {
  if (topTranslation) {
    console.log("Top translation text:", topTranslation.text);
  } else {
    console.log("No translations exist for this string yet.");
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 TranslationObject 或 null。

响应有效载荷示例

{
  "id": 690949,
  "string_id": 1569689,
  "text": "This is the top translation.",
  "target_language_id": "fr",
  "votes_rating": 1,
  "approved": true,
  "author": {
    "id": "12729493",
    "login": "example_user"
  },
  "created_at": "2025-11-07T08:19:10-05:00"
}

响应对象结构

此方法返回单个 TranslationObject。完整属性列表请参阅 AP.editor.getTranslations 的结构表。

AP.editor.setTranslation(text)

为活动字符串设置或覆盖编辑器主翻译文本区域中的文本。

示例：

// Set the translation text to "Hello world"
AP.editor.setTranslation("Hello world")；

参数

text

类型： string

必填： 是

描述： 要插入翻译区域的文本。

AP.editor.appendTranslation(text)

将文本追加到编辑器翻译文本区域中现有文本的末尾。

示例：

// If the text area contains "Hello", this will change it to "Hello world"
AP.editor.appendTranslation(" world")；

参数

text

类型： string

必填： 是

描述： 要追加的文本。

AP.editor.clearTranslation()

清除活动字符串编辑器翻译文本区域中的所有文本。

示例：

AP.editor.clearTranslation()；

AP.editor.setFocus()

将浏览器焦点设置到编辑器的翻译文本区域。

示例：

AP.editor.setFocus()；

AP.editor.setUnsavedSuggestion(suggestion)

为特定字符串设置”未保存的建议”。这用于以编程方式添加翻译而不保存，通常在多语言视图中使用。

示例：

AP.editor.setUnsavedSuggestion({
  id: 1569759,                   // The numeric or string ID of the phrase
  text: 'My unsaved suggestion', // The translation text
  languageId: 'fr',              // Target language code
  pluralId: 1,                   // Optional: Specific plural form ID
  translationId: 45678           // Optional: ID if editing an existing translation
})；

参数

suggestion

类型： object

必填： 是

描述： 包含建议详细信息的对象。请参阅下方的 输入对象结构。

输入对象结构

`id`	类型： `integer` \| `string` 必填：是描述：源字符串（短语）的数字或字符串 ID。
`text`	类型： `string` 必填：是描述：翻译文本。
`languageId`	类型： `string` 必填：是描述：目标语言的 ID（例如，`“fr”`）。
`pluralId`	类型： `integer` \| `null` 必填：否描述：复数形式的 ID（例如，`1`），对于非复数字符串则为 `null`。
`translationId`	类型： `integer` 必填：否描述：如果您正在编辑现有翻译，则为该翻译的 ID。

AP.editor.setUnsavedSuggestions(suggestions)

一次设置多个”未保存的建议”。

示例：

AP.editor.setUnsavedSuggestions([
  {
    id: 1569759,
    text: 'Suggestion 1',
    languageId: 'fr',
    pluralId: '1'
  },
  {
    id: 1569761,
    text: 'Suggestion 2',
    languageId: 'fr',
    pluralId: null
  }
])；

参数

suggestions

类型： array

必填： 是

描述： 建议对象的数组。请参阅 setUnsavedSuggestion 中的 Input Object Structure。

AP.editor.removeUnsavedSuggestions(suggestions)

删除一个或多个”未保存的建议”。

示例：

// Remove a specific unsaved suggestion
AP.editor.removeUnsavedSuggestions([
  {
    id: 1569759,
    text: 'Suggestion 1',
    languageId: 'fr',
    pluralId: '1'
  }
])；

参数

suggestions

类型： array

必填： 是

描述： 要删除的建议对象数组。格式与 setUnsavedSuggestions 相同。

AP.editor.applyUnsavedTranslations(method, data)

根据提供的方法应用（保存）所有未保存的翻译。

示例：

// Apply unsaved translations only for the selected strings
AP.editor.applyUnsavedTranslations('selectedStrings', null);

// Apply unsaved translations for a specific list of string IDs
AP.editor.applyUnsavedTranslations('providedStrings', [1569759, 1569761])；

参数

method

类型： string

必填： 是

描述： 用于应用翻译的方法。

允许值： all（页面上所有未保存的），selectedStrings（仅针对选中的字符串），providedStrings（针对 data 参数中提供的字符串 ID）。

data

类型： array | null

必填： 是

描述： 数字字符串 ID 的数组。仅当 method 设置为 providedStrings 时使用。否则，传入 null。

过滤器管理

这组方法允许您的应用读取和控制编辑器中使用的字符串过滤器，包括基本过滤器、高级筛选器和 CroQL 查询。

AP.editor.getFiltersList(callback)

检索所有可用基本过滤器的完整列表，包括其名称和数字 ID。

示例：

AP.editor.getFiltersList(function(filters) {
  console.log("Available filters:", filters);
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 FilterObject 项的数组。

响应有效载荷示例

[
  {
    "name": "Show All",
    "value": 3
  },
  {
    "name": "Untranslated",
    "value": 2
  },
  {
    "name": "Not Approved",
    "value": 5
  },
  {
    "name": "Approved",
    "value": 4
  },
  {
    "name": "Machine Translations"
  },
  {
    "name": "All",
    "value": 10
  },
  {
    "name": "All, Untranslated First",
    "value": 0
  }
]

响应对象结构

name

类型： string

描述： 过滤器的显示名称（例如，“Untranslated”）。

value

类型： integer

描述： 过滤器的数字 ID。此值供 AP.editor.setFilter 使用。某些项目是分节标题，没有 value。

AP.editor.getFilter(callback)

检索当前活动基本筛选器的数字 ID（例如，“未翻译”、“已批准”）。

示例：

AP.editor.getFilter(function(filterId) {
  console.log("Current filter ID:", filterId);
  // Example output: 0 (for "All, Untranslated First")
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：integer（过滤器 ID）。

响应有效载荷示例

此方法返回纯 integer。

AP.editor.setFilter(filterNumber)

使用数字 ID 将基本过滤器应用于字符串列表。

示例：

// Filter the list to show only "Untranslated" strings (ID 2)
AP.editor.setFilter(2)；

参数

filterNumber

类型： integer

必填： 是

描述： 要应用的过滤器的数字 ID。请参阅 AP.editor.getFiltersList 获取所有可用 ID。

常用过滤器 ID

以下是一些最常用的默认过滤器 ID：

0：全部，未翻译优先
2：未翻译
3：显示全部
4：已审核
5：已翻译，未审核
7：有评论
10：由翻译记忆或 MT 翻译
12：高级筛选器
30：由翻译记忆翻译
31：由 MT 翻译

AP.editor.getCustomFilter(callback)

检索表示”高级筛选器”当前状态的对象。

示例：

AP.editor.getCustomFilter(function(customFilter) {
  if (customFilter) {
    console.log("Current advanced filter settings:", customFilter);
    console.log("Filtering by translation status:", customFilter.translations);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 CustomFilterObject 或 null。

响应有效载荷示例

{
  "translations": "untranslated",
  "labels": [123, 456],
  "label_match_rule": "any",
  "comments": "have_comments",
  "croql_expression": "",
  "ai_query": ""
}

响应对象结构

CustomFilterObject 包含编辑器高级筛选器对话框中所有可用字段。以下是一些关键属性：

`translations`	类型： `string` 允许值： `“translated”`、`“untranslated”`、`""` 描述：根据翻译状态过滤字符串。
`comments`	类型： `string` 允许值： `“have_comments”`、`“no_comments”`、`""` 描述：根据是否有评论过滤字符串。
`labels`	类型： `array` 描述：要过滤的标签 ID 数组。
`croql_expression`	类型： `string` 描述：用于高级过滤的自定义 CroQL 表达式。

AP.editor.setCustomFilter(customFilter)

通过提供筛选器对象，将”高级筛选器”应用于字符串列表。

示例：

// Filter for untranslated strings with specific labels
AP.editor.setCustomFilter({
  translations: 'untranslated',
  labels: [123, 456],
  label_match_rule: 'any'
})；

参数

customFilter

类型： object

必填： 是

描述： 包含过滤条件的 CustomFilterObject。请参阅 AP.editor.getCustomFilter 获取所有可用属性的完整列表。

完整有效载荷参考

点击查看所有可用的过滤器属性

{
  added_from: '',
  added_to: '',
  updated_from: '',
  updated_to: '',
  translations: '', // 'translated', 'untranslated'
  duplicates: '',
  tm_and_mt: '',
  pre_translation: '',
  approvals: '',
  comments: '', // 'have_comments', 'no_comments'
  screenshots: '',
  visibility: '',
  qa_issues: '',
  labels: [],
  label_match_rule: 'any', // 'all', 'any'
  exclude_labels: [],
  exclude_label_match_rule: 'all',
  string_type: '',
  votes: '',
  votes_count: null,
  approvals_count_select: '',
  approvals_count: null,
  translated_by_user: '',
  not_translated_by_user: '',
  approved_by_user: '',
  not_approved_by_user: '',
  sort_method: 0,
  sort_ascending: 1,
  croql_expression: '',
  ai_query: ''
}

AP.editor.resetCustomFilter()

将”高级筛选器”重置为默认（空）状态。

示例：

AP.editor.resetCustomFilter()；

AP.editor.getCroqlFilter(callback)

以字符串形式检索当前活动的 CroQL 过滤器查询。

示例：

AP.editor.getCroqlFilter(function(croqlQuery) {
  if (croqlQuery) {
    console.log("Current CroQL query:", croqlQuery);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 string（CroQL 查询）或 null。

响应有效载荷示例

此方法返回纯 string。

"text = "Welcome!""

AP.editor.setCroqlFilter(croql)

将 CroQL 过滤器应用于字符串列表。

示例：

// Filter strings where the text is "Welcome!"
AP.editor.setCroqlFilter("text = 'Welcome!'")；

参数

croql

类型： string

必填： 是

描述： 有效的 CroQL 查询字符串。

AP.editor.resetCroqlFilter()

将 CroQL 过滤器重置为默认（空）状态。

示例：

AP.editor.resetCroqlFilter()；

编辑器状态管理

这组方法允许您读取和控制编辑器的状态，例如当前视图模式、页面、选定语言或搜索查询。

AP.editor.getMode(callback)

检索当前活动编辑器模式的名称。

示例：

AP.editor.getMode(function(modeName) {
  console.log("Current mode:", modeName);
  // Example output: "translate"
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：string（模式名称）。

响应有效载荷示例

此方法返回纯 string。

"translate"

响应对象结构

类型： string

允许值： translate、proofread、review、multilingual

AP.editor.setMode(modeName)

将编辑器切换到不同的模式。

示例：

// Switch the Editor to Proofreading mode
AP.editor.setMode('proofread')；

参数

modeName

类型： string

必填： 是

描述： 要切换到的模式名称。允许值：translate、proofread、review、multilingual。

AP.editor.getPage(callback)

检索字符串列表的当前页码。

示例：

AP.editor.getPage(function(pageNumber) {
  console.log("Current page:", pageNumber);
  // Example output: 1
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：integer（页码）。

响应有效载荷示例

此方法返回纯 integer。

AP.editor.setPage(pageNumber)

将字符串列表切换到特定页码。

示例：

// Go to the second page of strings
AP.editor.setPage(2)；

参数

pageNumber

类型： integer

必填： 是

描述： 要导航到的页码。

AP.editor.getProjectTargetLanguages(callback)

检索编辑器中当前用户可用的项目目标语言列表。

示例：

AP.editor.getProjectTargetLanguages(function(languages) {
  if (languages && languages.length > 0) {
    console.log("Available languages:", languages);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 LanguageObject 项的数组。

响应有效载荷示例

[
  {
    "id": "2",
    "name": "French",
    "internal_code": "fr",
    "code": "fr",
    "preferred": false
  },
  {
    "id": "3",
    "name": "German",
    "internal_code": "de",
    "code": "de",
    "preferred": true
  }
]

响应对象结构

id

类型： string

描述： 语言的唯一 ID（例如，“2”）。

name

类型： string

描述： 语言的显示名称（例如，“French”）。

code

类型： string

描述： 语言代码（例如，“fr”）。

AP.editor.setTargetLanguage(languageIds, [callback])

在并排和舒适模式下将编辑器切换到不同的目标语言，或在多语言模式下设置活动语言。

示例（并排和舒适模式）：

// Switch the Editor to German (ID "11")
AP.editor.setTargetLanguage('11')；

示例（多语言模式）：

// Set the active languages to German (ID "11") and French (ID "2")
AP.editor.setTargetLanguage(['11', '2'])；

参数

languageIds

类型： string | array

必填： 是

描述： 字符串 ID（例如，“11”）用于设置单一语言，或字符串 ID 数组（例如，[“11”, “2”]）用于在多语言模式下设置多种语言。

callback

类型： function

必填： 否

描述： 可选回调，如果任何请求的语言 ID 未找到，则返回错误消息。

AP.editor.search(text, [options])

在编辑器中对指定文本执行搜索。

示例：

// Perform a simple search for the word "Welcome"
AP.editor.search("Welcome");

// Perform a case-sensitive search
AP.editor.search("Welcome", { caseSensitive: true, search_option: 1 })；

参数

text

类型： string

必填： 是

描述： 要搜索的文本。

options

类型： object

必填： 否

描述： 包含搜索选项的对象。请参阅下方的 输入对象结构。

输入对象结构

`searchStrict`	类型： `boolean` 描述：如果为 `true`，则执行严格搜索。默认值为 `false`。
`searchFullMatch`	类型： `boolean` 描述：如果为 `true`，则搜索完全匹配。默认值为 `false`。
`caseSensitive`	类型： `boolean` 描述：如果为 `true`，则搜索区分大小写。默认值为 `false`。
`search_option`	类型： `integer` 描述：定义搜索范围。 `0`：全部，`1`：字符串，`2`：上下文，`3`：翻译，`4`：标识符（键）。

通知

这组方法允许您的应用向用户显示反馈消息（例如通知、成功或错误消息），并管理应用图标上的通知徽章。

AP.editor.noticeMessage(message)

在编辑器顶部显示黄色”通知”消息栏。

示例：

AP.editor.noticeMessage("This is a test notification.")；

参数

message

类型： string

必填： 是

描述： 要在消息栏中显示的文本。

AP.editor.successMessage(message)

在编辑器顶部显示绿色”成功”消息栏。

示例：

AP.editor.successMessage("The operation was successful!")；

参数

message

类型： string

必填： 是

描述： 要在消息栏中显示的文本。

AP.editor.errorMessage(message)

在编辑器顶部显示红色”错误”消息栏。

示例：

AP.editor.errorMessage("An error occurred. Please try again.")；

参数

message

类型： string

必填： 是

描述： 要在消息栏中显示的文本。

AP.editor.setApplicationNotification(count)

在编辑器侧边面板中应用图标上设置带有数字的蓝色通知徽章。

示例：

AP.editor.setApplicationNotification(2)；

参数

count

类型： integer

必填： 是

描述： 要在通知徽章中显示的数字。

AP.editor.clearApplicationNotification()

从应用图标上移除通知徽章。

示例：

AP.editor.clearApplicationNotification()；

工作流动作（Enterprise）

这组方法允许您的应用读取有关项目工作流的信息，并控制用户在该工作流中的状态。

AP.editor.getWorkflowSteps(callback)

检索当前项目中用户可用的所有工作流步骤列表。

示例：

AP.editor.getWorkflowSteps(function(steps) {
  if (steps && steps.length > 0) {
    console.log("Available workflow steps:", steps);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收 WorkflowStepObject 项的数组，如果未配置工作流则为 undefined。

响应有效载荷示例

[
  {
    "id": 752,
    "title": "Translation",
    "type": "Translate",
    "editor_mode": "translate",
    "approving_available": true,
    "source_language": {
      "id": 52,
      "name": "English",
      "code": "en"
    }
  },
  {
    "id": 753,
    "title": "Proofreading",
    "type": "Proofread",
    "editor_mode": "proofread",
    "approving_available": true,
    "source_language": {
      "id": 52,
      "name": "English",
      "code": "en"
    }
  }
]

响应对象结构

`id`	类型： `integer` 描述：工作流步骤的唯一数字 ID。
`title`	类型： `string` 描述：工作流步骤的显示名称（例如，“Translation”）。
`type`	类型： `string` 描述：步骤的类型（例如，“Translate”、“Proofread”）。
`editor_mode`	类型： `string` 描述：此步骤对应的编辑器模式。
`approving_available`	类型： `boolean` 描述：如果可以在此步骤审核翻译，则为 `true`。
`source_language`	类型： `object` 描述：包含源语言详细信息的对象。

AP.editor.getWorkflowStepStatusFilter(callback)

检索当前工作流步骤处于当前状态的活动过滤器。

示例：

AP.editor.getWorkflowStepStatusFilter(function(status) {
  console.log("Current step status filter:", status);
  // Example output: "ALL"
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个 string 参数。

响应有效载荷示例

此方法返回纯 string。

"ALL"

响应对象结构

类型： string

允许值： ALL、ToDo、Pending、Done

AP.editor.setWorkflowStep(stepId)

将编辑器切换到不同的工作流步骤。

示例：

// Switch the Editor to workflow step with ID 753
AP.editor.setWorkflowStep(753)；

参数

stepId

类型： integer

必填： 是

描述： 要切换到的工作流步骤的 ID。请参阅 AP.editor.getWorkflowSteps 获取可用 ID。

AP.editor.setWorkflowStepStatusFilter(status)

设置当前工作流步骤的状态过滤器。

示例：

// Filter to show only strings that are "DONE"
AP.editor.setWorkflowStepStatusFilter('DONE')；

参数

status

类型： string

必填： 是

描述： 要过滤的状态。

允许值： ALL、TODO、PENDING、DONE

文本选择动作

这些方法允许您的应用获取用户光标在源字符串区域或翻译文本区域中当前选中的文本。

AP.editor.source.getSelectedText(callback)

检索用户光标在源字符串区域中当前选中的文本。

示例：

AP.editor.source.getSelectedText(function(selectedText) {
  if (selectedText) {
    console.log("User selected this source text:", selectedText);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：string（选中的文本）或 null。

响应有效载荷示例

此方法返回选中文本的纯 string，如果未选中任何文本则返回 null。

"Selected source text"

AP.editor.textarea.getSelectedText(callback)

检索用户光标在翻译文本区域中当前选中的文本。

示例：

AP.editor.textarea.getSelectedText(function(selectedText) {
  if (selectedText) {
    console.log("User selected this translation text:", selectedText);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：string（选中的文本）或 null。

响应有效载荷示例

此方法返回选中文本的纯 string，如果未选中任何文本则返回 null。

"My selected translation"

编辑器自定义

这组方法提供了用于自定义编辑器原生行为的高级集成点，例如添加自定义上下文菜单、管理快捷键以及应用自定义样式。

在编辑器的上下文菜单中注册一个自定义项目（右键单击时出现的菜单）。

您必须定义 action 对象，callback 将返回同一对象，并附加 eventSubscriptionId。然后使用 AP.events.on 监听该 ID 上的点击事件。

示例：

// 1. Define and register the context menu item
AP.editor.registerContextMenuAction({
  type: 'textarea-context-menu',
  name: 'My Custom Action'
}, function(action) {

  // 2. Listen for clicks on this specific item
  AP.events.on(action.eventSubscriptionId, function() {
    console.log(`'${action.name}' was clicked!`);
    AP.editor.noticeMessage("Custom action triggered!");
  });
})；

参数

action

类型： object

必填： 是

描述： 动作的配置对象。请参阅下方的 输入对象结构。

callback

类型： function

必填： 是

描述： 一个回调函数，接收返回的动作对象，现在包含用于事件处理的 eventSubscriptionId。

输入对象结构

type

类型： string

必填： 是

描述： 将显示该动作的上下文菜单类型。可能的值：

textarea-context-menu：翻译输入区域的上下文菜单。
source-string-context-menu：源字符串的上下文菜单。
source-string-selected-text-context-menu：源字符串中选定文本的上下文菜单。

name

类型： string

必填： 是

描述： 将在上下文菜单中显示的文本标签。

children

类型： array

必填： 否

描述： 可选的子 ActionObject 项数组，用于创建嵌套子菜单。

响应有效载荷示例（在回调中）

回调接收返回的 action 对象，并附加 eventSubscriptionId。

{
  "type": "textarea-context-menu",
  "name": "My Test Action",
  "eventSubscriptionId": "context.menu.click:GGChNhE"
}

响应对象结构

eventSubscriptionId

类型： string

描述： 此菜单项的唯一 ID。使用此 ID 配合 AP.events.on 监听点击事件。

…加上您提供的 输入对象结构 中的所有属性。

其他示例

源字符串上下文菜单的简单动作

AP.editor.registerContextMenuAction({
  type: 'source-string-context-menu',
  name: 'Run custom action'
}, function(action) {
  AP.events.on(action.eventSubscriptionId, () => {
    // Run custom logic when clicked
    console.log('Custom action triggered.');
  });
})；

带子菜单的动作

AP.editor.registerContextMenuAction({
  type: 'source-string-context-menu',
  name: 'My Actions',
  children: [
    {
      name: 'Explain selection'
    },
    {
      name: 'Check grammar'
    }
  ]
}, function(action) {
  // Handle the child menu items
  if (action.children) {
    action.children.forEach((childAction) => {
      AP.events.on(childAction.eventSubscriptionId, () => {
        // Add the logic that should happen on click
        console.log(`'${childAction.name}' was clicked.`);
      });
    });
  }
})；

翻译区域中选定文本的动作

AP.editor.registerContextMenuAction({
  type: 'textarea-context-menu',
  name: 'Log selected text'
}, function(action) {
  AP.events.on(action.eventSubscriptionId, () => {
    // Get the selected text and process it
    AP.editor.textarea.getSelectedText(function(text) {
      if (text) {
        console.log('Selected text:', text);
      }
    });
  });
})；

AP.editor.getHotKeys(callback)

检索包含编辑器中当前活动所有快捷键的字符串。

示例：

AP.editor.getHotKeys(function(hotkeys) {
  console.log("Active hotkeys:", hotkeys);
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收一个参数：string。

响应有效载荷示例

此方法返回纯 string，快捷键以逗号分隔。

"Command+Enter,Command+[,Command+],Control+Shift+C,……"

AP.editor.propagateHotKeyPress(hotKeyPressed)

手动将快捷键按下事件从应用的 iframe 传播到主编辑器。如果您的应用捕获了某个按键事件（例如”Enter”），并且您也希望编辑器对此作出响应，此功能将非常有用。

示例：

// Tell the Editor that the "Command+Enter" hotkey was pressed
AP.editor.propagateHotKeyPress('Command+Enter')；

参数

hotKeyPressed

类型： string

必填： 是

描述： 被按下的快捷键字符串（例如，Command+Enter）。

AP.editor.applyCustomThemeStyle(theme, callback)

将自定义主题配置应用于编辑器 UI。这允许对颜色、背景和元素高亮进行深度自定义。

示例：

AP.editor.applyCustomThemeStyle({
  themeMode: 'dark',                    // Context mode ('light' or 'dark')
  primaryAccent: '#35a1ff',
  base: {
    baseBackground: '#16191d',
    stringStatus: {
      translated: '#74bb02',
      approved: '#35a1ff'
    },
    highlights: {
      placeholderColor: '#35a1ff',
      placeholderBg: 'rgba(53, 161, 255, 0.1)',
      tagColor: '#74bb02',
      tagBg: 'rgba(116, 187, 2, 0.1)',
      nonePrintableCharacterColor: '#3eb17f',
      findAndReplaceHighlightBg: '#cc9a06',
      specialLightColor: '#35a1ff',
      specialLightBg: 'rgba(53, 161, 255, 0.05)'
    }
  },
  accents: {
    info: { accentColor: '#35a1ff' },
    danger: { accentColor: '#ff4444' },
    warning: { accentColor: '#cc9a06' },
    success: { accentColor: '#74bb02' }
  }
}, (result) => {
  if (result) {
    console.error('Error applying theme:', result);
  } else {
    console.log('Theme applied successfully');
  }
})；

参数

theme

类型： object

必填： 是

描述： 包含 UI 颜色和样式配置的 ThemeObject。请参阅上面的示例了解所需结构。

callback

类型： function

必填： 否

描述： 处理响应的回调函数。如果应用失败，则接收错误消息字符串；成功时接收 null。

AP.editor.resetCustomThemeStyle()

移除 AP.editor.applyCustomThemeStyle 应用的所有自定义 CSS。

示例：

AP.editor.resetCustomThemeStyle()；

编辑器模态框动作

这些方法允许您的应用在编辑器中打开和关闭模态窗口。

打开应用中已定义的某个”模态”模块。

示例：

// Open a modal module
AP.editor.openModal({
  resource: 'my-modal-key',
  size: 'medium'
}, function(success) {
  if (success) {
    console.log("Modal opened successfully.");
  }
})；

参数

options

类型： object

必填： 是

描述： 模态框的配置对象。请参阅下方的 输入对象结构。

callback

类型： function

必填： 否

描述： 可选回调函数，成功时接收 boolean（true）。

输入对象结构

resource

类型： string

必填： 是

描述： 要打开的模态模块的 key（在您的 manifest.json 中定义）。

size

类型： string

必填： 否

描述： 模态窗口的大小。

允许值： small、medium、large、xlarge。默认值为 medium。

onClose

类型： function

必填： 否

描述： 模态框关闭时将执行的可选回调函数。

关闭当前打开的模态框，但仅当它是由您的应用使用 AP.editor.openModal 打开时。

示例：

// Close the modal
AP.editor.closeModal()；

项目动作

这组方法允许您的应用与 Crowdin 项目进行交互，例如导航到不同的项目页面或打开编辑器。所有方法均通过 AP.project 对象调用。

AP.project.redirect(path, hardRedirect)

将用户重定向到当前项目中的不同页面。

示例：

// Redirects to the project's Activity tab
AP.project.redirect('/activity-stream');

// Forces a full-page reload to the project's root
AP.project.redirect('/', true)；

参数

path

类型： string

必填： 是

描述： 项目内要重定向到的相对路径（例如，/、/translations、/activity-stream）。

hardRedirect

类型： boolean

必填： 否

描述： 如果设置为 true，则强制进行完整的浏览器页面加载。如果为 false（默认），则使用内部路由。

打开内置的 Crowdin 模态对话框。

示例：

// Open the "Pre-translation via MT" modal
AP.project.openModal('mt-pre-translation')；

参数

modalName

类型： string

必填： 是

描述： 要打开的内置模态框的名称。

允许值： mt-pre-translation、ai-pre-translation、marketplace-store

AP.project.openEditor(fileId, [view], [languageCode])

为特定文件打开 Crowdin 编辑器。

示例：

// Open a specific file in the default view
AP.project.openEditor('15411');

// Open a file in Multilingual mode for a specific language
AP.project.openEditor('15411', 'multilingual', 'de')；

参数

fileId

类型： string | integer

必填： 是

描述： 要打开的文件的 ID。

view

类型： string

必填： 否

描述： 要打开的编辑器模式（例如，“multilingual”）。

languageCode

类型： string

必填： 否

描述： 要打开的语言代码（例如，“de”）。如果 view 为 multilingual，这可以是逗号分隔的列表。

AP.project.previewTranslations(action)

根据项目类型将用户导航到相应的选项卡（文件型项目的翻译或字符串型项目的下载），并触发预览下载（CSV 或 XLSX 格式）。

示例：

// Trigger a preview download in CSV format
AP.project.previewTranslations('csv')；

参数

action

类型： string

必填： 是

描述： 要下载的预览格式。

允许值： csv、xlsx

AP.project.getTabsConfiguration(callback)

检索项目选项卡的配置对象，指示项目上下文中哪些选项卡当前可见或隐藏。

示例：

AP.project.getTabsConfiguration(function(config) {
  if (config) {
    console.log("Current tabs configuration:", config);
  }
})；

参数

callback

类型： function

必填： 是

描述： 处理响应的回调函数。该函数接收选项卡配置对象的array。

响应有效载荷示例

此方法返回对象的 array。

[
  {
    "identifier": "home",
    "visible": true
  },
  {
    "identifier": "sources",
    "visible": true
  },
41 collapsed lines
  {
    "identifier": "translations",
    "visible": true
  },
  {
    "identifier": "screenshots",
    "visible": true
  },
  {
    "identifier": "tasks",
    "visible": true
  },
  {
    "identifier": "members",
    "visible": true
  },
  {
    "identifier": "integrations",
    "visible": true
  },
  {
    "identifier": "reports",
    "visible": false
  },
  {
    "identifier": "activity-stream",
    "visible": true
  },
  {
    "identifier": "discussions",
    "visible": true
  },
  {
    "identifier": "tools",
    "visible": true
  },
  {
    "identifier": "test_app¦test_app-project-menu",
    "visible": true
  },
  {
    "identifier": "settings",
    "visible": true
  }
]

AP.project.saveTabsConfiguration(params, callback)

保存项目选项卡的新配置。这允许您以编程方式在项目上下文中显示或隐藏特定选项卡。

示例：

const newConfig = [
  {
    "identifier": "home",
    "visible": true
  },
  {
    "identifier": "sources",
    "visible": true
  },
40 collapsed lines
  {
    "identifier": "translations",
    "visible": true
  },
  {
    "identifier": "screenshots",
    "visible": true
  },
  {
    "identifier": "tasks",
    "visible": false
  },
  {
    "identifier": "members",
    "visible": false
  },
  {
    "identifier": "integrations",
    "visible": true
  },
  {
    "identifier": "reports",
    "visible": false
  },
  {
    "identifier": "activity-stream",
    "visible": true
  },
  {
    "identifier": "discussions",
    "visible": true
  },
  {
    "identifier": "tools",
    "visible": true
  },
  {
    "identifier": "test_app¦test_app-project-menu",
    "visible": true
  },
  {
    "identifier": "settings",
    "visible": true
  }
]；

AP.project.saveTabsConfiguration({ tabs_configuration: newConfig }, function(success) {
  if (success) {
    console.log("Configuration saved successfully.");
  }
})；

参数

params

类型： object

必填： 是

描述： 包含新配置的对象。请参阅下方的 输入对象结构。

callback

类型： function

必填： 否

描述： 可选回调函数，成功时接收 boolean（true）。

输入对象结构

tabs_configuration

类型： array

必填： 是

描述： 选项卡配置对象的数组。请参阅 AP.project.getTabsConfiguration 了解单个选项卡对象的结构。

个人资料动作

这组方法允许您的应用与用户的账户个人资料页面进行交互，在项目之外。所有方法均通过 AP.profile 对象调用。

AP.profile.redirect(path)

将用户重定向到其”个人资料”区域内的其他页面。

示例：

// Redirects the user to their "Tasks" page
AP.profile.redirect('/tasks')；

参数

path

类型： string

必填： 是

描述： 用户个人资料中要重定向到的相对路径（例如，/tasks、/managers、/glossaries）。

模态框动作

这些方法用于控制模态窗口（例如，从模态框自身的 iframe 内设置模态框的大小）。

更新应用当前运行所在模态窗口的尺寸和滚动行为。

示例：

// Update the modal size and scroll behavior
AP.modal.setSize({
  width: "600px",
  height: "600px",
  hideXScrolls: true,  // Optional, default: true
  hideYScrolls: false  // Optional, default: false
})；

参数

options

类型： object

必填： 是

描述： 包含尺寸和滚动设置的对象。请参阅下方的 输入对象结构。

输入对象结构

`width`	类型： `string` 必填：是描述：所需宽度（例如，`600px`、`80%`）。
`height`	类型： `string` 必填：是描述：所需高度（例如，`500px`、`90vh`）。
`hideXScrolls`	类型： `boolean` 必填：否描述：是否隐藏水平滚动条。默认值为 `true`。
`hideYScrolls`	类型： `boolean` 必填：否描述：是否隐藏垂直滚动条。默认值为 `false`。

事件处理

这些方法允许您的应用监听并响应 Crowdin UI 中发生的事件（例如，当用户更改字符串或保存翻译时），以及触发自己的自定义事件。所有方法均通过 AP.events 对象调用。

详细了解支持的事件。

AP.events.on(eventName, callback)

为事件订阅一个监听器。这是监听 Crowdin UI 事件（例如 string.change）以及应用或库发出的自定义内部事件的主要方法。

示例：

// Listen for the 'string.change' event from Crowdin
AP.events.on('string.change', function(stringData) {
  console.log("User switched to string ID:", stringData.id);
})；

参数

eventName

类型： string

Required: 是

描述： 要监听的事件名称（例如，string.change）。请参阅支持的事件部分获取完整列表。

callback

类型： function

必填： 是

描述： 事件触发时执行的函数。该函数接收特定于事件的数据有效载荷对象。

AP.events.once(eventName, callback)

为事件订阅一个监听器，但该监听器在执行一次后会自动移除。

示例：

// Run this code only the next time a translation is added
AP.events.once('translation.added', function(translation) {
  console.log("A translation was added:", translation.text);
})；

参数

eventName

类型： string

必填： 是

描述： 要监听的事件名称。

callback

类型： function

必填： 是

描述： 事件触发时执行一次的函数。

AP.events.off(eventName, callback)

移除之前通过 AP.events.on 或 AP.events.once 注册的特定事件监听器。

示例：

const myListener = function(data) { console.log(data); }；

// Start listening
AP.events.on('string.change', myListener);

// Stop listening
AP.events.off('string.change', myListener)；

参数

eventName

类型： string

必填： 是

描述： 要取消订阅的事件名称。

callback

类型： function

必填： 是

描述： 用于注册监听器的完全相同的函数对象。

AP.events.offAll(eventName)

移除特定事件的所有事件监听器。

示例：

// Stop all listeners for the 'string.change' event
AP.events.offAll('string.change')；

参数

eventName

类型： string

必填： 是

描述： 要移除所有监听器的事件名称。

AP.events.onAny(callback)

订阅一个针对任何事件都会触发的监听器。这对于调试以查看通过系统传递的所有事件非常有用。

示例：

AP.events.onAny(function(eventName, eventData) {
  console.log("Event fired:", eventName, "with data:", eventData);
})；

参数

callback

类型： function

必填： 是

描述： 接收两个参数的回调函数：eventName（字符串）和 eventData（对象）。

AP.events.offAny(callback)

移除通过 AP.events.onAny 注册的特定监听器。

示例：

const myDebugListener = function(eventName, eventData) { /* ... */ };
AP.events.onAny(myDebugListener);

// Later, to stop listening
AP.events.offAny(myDebugListener);

参数

callback

类型： function

必填： 是

描述： 用于注册监听器的完全相同的函数对象。

AP.events.emit(eventName, [data])

在您的应用中触发自定义事件。所有通过 AP.events.on 注册的监听器都将被触发。

示例：

// Fire a custom event with some data
AP.events.emit('my-custom-event', { status: 'updated' });

参数

eventName

类型： string

必填： 是

描述： 要触发的自定义事件的名称。

data

类型： any

必填： 否

描述： 发送给事件监听器的可选数据负载。

支持的事件

使用这些事件名称与 AP.events.on() 方法，以监听 Crowdin UI 中发生的操作。

事件	详情与负载
`string.change`	当用户从一个原文字符串切换到另一个时触发。负载：一个 `StringDataObject`（如果未选择字符串则为 `null`）。对象结构请参阅 `AP.editor.getString`。 `{ "id": 1568759, "text": "Welcome!", "context": "Main screen" }`
`string.selected`	当用户选择或取消选择字符串时触发（使用并排视图中的复选框）。负载：一个由 `SelectedStringObject` 项组成的数组。对象结构请参阅 `AP.editor.getSelectedStrings`。 `[ { "string": { "id": 1569759, "text": "Welcome!" }, "translations": { "fr": [] } } ]`
`textarea.edited`	当用户在译文文本区域进行任何更改（输入、删除、粘贴）时触发。负载：一个包含字符串数据、`oldText` 和 `newText` 的对象。 `{ "id": 1569759, "text": "Welcome!", "oldText": "Welcom", "newText": "Welcome" }`
`translation.added`	当用户保存新译文时触发。负载：新保存译文的 `TranslationObject`。对象结构请参阅 `AP.editor.getTranslations`。 `{ "id": 690950, "string_id": 1569759, "text": "Bienvenue!", "author": { "id": "12729493", "login": "example_user" } }`
`translation.deleted`	当用户删除译文时触发。负载：一个包含已删除译文的 `id` 及其 `string_id` 的对象。 `{ "id": 690950, "string_id": 1569759 }`
`translation.restored`	当用户恢复已删除的译文时触发。负载：已恢复的 `TranslationObject`。对象结构请参阅 `AP.editor.getTranslations`。
`translation.vote`	当用户对译文进行投票（赞或踩）时触发。负载：更新后的 `TranslationObject`，包含新的 `votes_rating`。
`translation.approve`	当用户批准译文时触发。负载：更新后的 `TranslationObject`，现在包含 `“approved”: true` 和 `approver` 详情。 `{ "id": 690950, "string_id": 1569759, "approved": true, "approver": { "id": "12729494", "login": "proofreader" } }`
`translation.disapprove`	当用户撤销对译文的批准时触发。负载：更新后的 `TranslationObject`，现在包含 `“approved”: false`。
`language.change`	当用户在编辑器中更改目标语言时触发。负载：完整的 `ContextDataObject`。对象结构请参阅 `AP.getContext`。
`file.change`	当用户在编辑器中切换到不同文件时触发。负载：完整的 `ContextDataObject`。对象结构请参阅 `AP.getContext`。
`theme.changed`	当用户更改 UI 主题时触发。负载：一个包含新主题名称的 `string`（例如 `“light”`、`“dark”`）。
`asset.source.preview`	当在编辑器中选择源资源文件时触发（适用于基于资源的项目）。负载： `ContextDataObject`。对象结构请参阅 `AP.getContext`。
`asset.suggestion.preview`	当在编辑器中选择建议资源文件时触发（适用于基于资源的项目）。负载：一个包含 `editor` 上下文和 `suggestion` 数据的对象。

本页面对你有帮助吗？