arcgis-coding-components

Name: arcgis-coding-components
Author: saschabrunnerch

github.com/saschabrunnerch开发2343 次安装29 周前更新

代码仓库

关于 arcgis-coding-components

arcgis-coding-components 技能指导开发者在 Web 应用中嵌入 Arcade 表达式编辑器。其核心是 `arcgis-arcade-editor` Web 组件，提供代码编辑、诊断、建议和文档侧栏。

主要功能

01嵌入 Arcade 表达式编辑器
02提供语法高亮与诊断
03支持代码建议和自定义片段
04通过配置文件和测试数据校验表达式
05监听脚本变更事件

适用场景

01在 Web 应用中构建 Arcade 编辑面板
02根据配置文件提供编辑上下文
03使用测试数据验证表达式
04在表达式编辑后触发应用处理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/saschabrunnerch/arcgis-maps-sdk-js-ai-context --skill arcgis-coding-components

安装后在 Claude Code 中输入/arcgis-coding-components确认已加载。

附带文件AGENTS.md

详细介绍

ArcGIS 编码组件

在 Web 应用中嵌入 Arcade 表达式编辑器时，请使用此技能。@arcgis/coding-components 包提供了 arcgis-arcade-editor Web 组件，这是一个功能齐全的代码编辑器，可用于编写、测试和调试 Arcade 表达式。这是 5.0 中新增的组件包，在 4.x 中没有对应版本。

导入方式

CDN（无需构建工具）


<script src="https://js.arcgis.com/5.0/"></script>

<script
  type="module"
  src="https://js.arcgis.com/5.0/coding-components/"
></script>

直接导入 ESM（使用构建工具）

import "@arcgis/coding-components/components/arcgis-arcade-editor";

arcgis-arcade-editor 组件

用于编写 Arcade 表达式的代码编辑器，支持语法高亮、诊断、代码建议和文档侧边栏。

属性

Property	Attribute	Type	Default	Description
`script`	`script`	`string`	`""`	Arcade 脚本内容（可读写）
`profile`	-	`IEditorProfileDefinition`	-	定义编辑上下文的配置元数据（通过 JS 设置）
`testData`	-	`IEditorTestContext`	-	用于验证表达式的测试数据上下文（通过 JS 设置）
`snippets`	-	`ApiSnippet[]`	-	要在代码片段面板中显示的代码片段集合（通过 JS 设置）
`suggestions`	-	`IEditorCodeSuggestion[]`	-	向用户显示的代码建议（通过 JS 设置）
`editorOptions`	-	`IEditorOptions & IGlobalEditorOptions`	-	Monaco 风格的编辑器选项（通过 JS 设置）
`hideSideBar`	`hide-side-bar`	`boolean`	`false`	隐藏侧边操作栏，使用精简界面
`hideDocumentationActions`	-	`boolean`	`false`	隐藏侧边面板中的文档操作
`openedSidePanel`	`opened-side-panel`	`string`	`"none"`	当前打开的侧边面板名称
`sideActionBarExpanded`	`side-action-bar-expanded`	`boolean`	`false`	侧边操作栏是否展开

方法

Method	Returns	Description
`setFocus()`	`void`	将焦点设到编辑器
`componentOnReady()`	`Promise<void>`	组件完全加载后解析

事件

Event	Detail	Description
`arcgisScriptChange`	`string`	脚本内容更改时触发（经过防抖处理）
`arcgisDiagnosticsChange`	`Diagnostic[]`	诊断信息（错误/警告）更改时触发

基本用法

最简编辑器

<arcgis-arcade-editor
  script="return $feature.Population * 2;"
  style="width: 600px; height: 400px;"
>
</arcgis-arcade-editor>

监听脚本更改

<arcgis-arcade-editor id="editor" style="width: 600px; height: 400px;">
</arcgis-arcade-editor>

<script type="module">
  const editor = document.querySelector("#editor");
  editor.script = "return $feature.Name;";

  editor.addEventListener("arcgisScriptChange", (event) => {
    const newScript = event.detail;
    console.log("Script updated:", newScript);
  });

  editor.addEventListener("arcgisDiagnosticsChange", (event) => {
    const diagnostics = event.detail;
    const errors = diagnostics.filter((d) => d.severity === "error");
    if (errors.length > 0) {
      console.warn("Script has errors:", errors);
    }
  });
</script>

带配置上下文的编辑器

const editor = document.querySelector("arcgis-arcade-editor");

// Define the editing profile - tells the editor what variables are available
editor.profile = {
  id: "popup",
  title: "Popup Expression",
  description: "Expression for popup content",
  variables: [
    {
      name: "$feature",
      type: "Feature",
      description: "The current feature",
    },
    {
      name: "$layer",
      type: "FeatureSet",
      description: "The feature's parent layer",
    },
  ],
};

带测试数据的编辑器

const editor = document.querySelector("arcgis-arcade-editor");

// Provide test data for expression validation
editor.testData = {
  spatialReference: { wkid: 4326 },
  features: [
    {
      attributes: {
        Name: "Test Feature",
        Population: 50000,
        Area: 125.5,
      },
      geometry: {
        type: "point",
        x: -118.24,
        y: 34.05,
      },
    },
  ],
  fields: [
    { name: "Name", type: "esriFieldTypeString", alias: "Name" },
    { name: "Population", type: "esriFieldTypeInteger", alias: "Population" },
    { name: "Area", type: "esriFieldTypeDouble", alias: "Area" },
  ],
};

带自定义代码片段的编辑器

const editor = document.querySelector("arcgis-arcade-editor");

editor.snippets = [
  {
    name: "Format Currency",
    description: "Format a number as US currency",
    code: 'Text($feature.Value, "$#,###.00")',
  },
  {
    name: "Concatenate Fields",
    description: "Join two text fields with a separator",
    code: 'Concatenate([$feature.FirstName, $feature.LastName], " ")',
  },
];

最简编辑器（无侧边栏）

<arcgis-arcade-editor
  hide-side-bar
  script="return Round($feature.Value, 2);"
  style="width: 400px; height: 200px;"
>
</arcgis-arcade-editor>

地图集成完整示例

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Arcade Editor</title>
    <script src="https://js.arcgis.com/5.0/"></script>
    <script
      type="module"
      src="https://js.arcgis.com/5.0/coding-components/"
    ></script>
    <script
      type="module"
      src="https://js.arcgis.com/5.0/map-components/"
    ></script>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
        display: flex;
        flex-direction: column;
      }
      arcgis-map {
        flex: 1;
      }
      #editor-panel {
        height: 300px;
        border-top: 1px solid #ccc;
      }
    </style>
  </head>
  <body>
    <arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
      <arcgis-zoom slot="top-left"></arcgis-zoom>
    </arcgis-map>
    <div id="editor-panel">
      <arcgis-arcade-editor id="editor"></arcgis-arcade-editor>
    </div>

    <script type="module">
      const mapElement = document.querySelector("#map");
      const editor = document.querySelector("#editor");

      await mapElement.viewOnReady();
      const view = mapElement.view;
      const layer = view.map.layers.getItemAt(0);
      await layer.load();

      // Set initial script
      editor.script = 'return $feature.Name + " (" + $feature.Type + ")"';

      // Configure profile from layer fields
      editor.profile = {
        id: "popup",
        title: "Popup Expression",
        variables: [
          { name: "$feature", type: "Feature", description: "Current feature" },
        ],
      };

      // Listen for changes and apply to popup
      editor.addEventListener("arcgisScriptChange", (event) => {
        console.log("Expression:", event.detail);
      });
    </script>
  </body>
</html>

常见问题

缺少 coding-components 脚本：必须单独加载 arcgis-arcade-editor 元素，而不是仅加载核心 SDK。


<script src="https://js.arcgis.com/5.0/"></script>
<arcgis-arcade-editor></arcgis-arcade-editor>


<script src="https://js.arcgis.com/5.0/"></script>
<script
  type="module"
  src="https://js.arcgis.com/5.0/coding-components/"
></script>
<arcgis-arcade-editor></arcgis-arcade-editor>

**影响：**无法识别该元素，渲染结果为空。

未设置编辑器尺寸：必须为编辑器显式设置宽度和高度才能渲染。
```
<arcgis-arcade-editor></arcgis-arcade-editor>
```
```
<arcgis-arcade-editor
  style="width: 600px; height: 400px;"
></arcgis-arcade-editor>
```
**影响：**编辑器高度为零，因而不可见。
将 profile 或 testData 设置为 HTML 属性：这些属性接受复杂对象，必须通过 JavaScript 设置。

**影响：**值会被静默忽略；编辑器缺少自动补全和验证所需的上下文。

未对 arcgisScriptChange 进行防抖处理：每次按键都会触发此事件（内部已有防抖处理，但触发频率仍可能很高）。请勿在处理程序中执行开销较大的操作。

// Anti-pattern: expensive operation on every change
editor.addEventListener("arcgisScriptChange", async (event) => {
  await compileAndExecuteArcade(event.detail); // too frequent
});

// Correct: add your own debounce for expensive operations
let timeout;
editor.addEventListener("arcgisScriptChange", (event) => {
  clearTimeout(timeout);
  timeout = setTimeout(() => {
    compileAndExecuteArcade(event.detail);
  }, 500);
});

**影响：**输入时界面会卡顿，或发出过多服务请求。

参考示例

搜索演示表达式编辑工作流的 Arcade 相关示例。

基本信息

作者: saschabrunnerch
仓库: saschabrunnerch/arcgis-maps-sdk-js-ai-context
分类: 开发
安装次数: 43
GitHub Stars: 23

报告问题