canvas-component-push

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Push to Canvas

推送至Canvas

Before pushing, confirm the user has Drupal Canvas CLI installed and configured for their target site.

在推送前，确认用户已为目标站点安装并配置了Drupal Canvas CLI。

Setup gate

前置检查

Before running any push command:

Check that a
```
.env
```
file exists in the project root.

.env

exists, verify these values are set:

```
CANVAS_SITE_URL
```
```
CANVAS_CLIENT_ID
```
```
CANVAS_CLIENT_SECRET
```

If
```
.env
```
is missing, or any required value is missing, stop and ask the user to complete setup first.
Do not guess setup steps. Point the user to the official docs:
- Drupal Canvas OAuth module setup: https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
- Drupal Canvas CLI package/docs: https://www.npmjs.com/package/@drupal-canvas/cli
Continue only after the user confirms setup is complete.

在运行任何推送命令前：

检查项目根目录下是否存在
```
.env
```
文件。

如果

.env

存在，验证以下值已设置：

```
CANVAS_SITE_URL
```
```
CANVAS_CLIENT_ID
```
```
CANVAS_CLIENT_SECRET
```

如果
```
.env
```
缺失，或任何必填值未设置，停止操作并要求用户先完成配置。
不要自行猜测配置步骤。引导用户查看官方文档：
- Drupal Canvas OAuth模块配置： https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
- Drupal Canvas CLI包/文档： https://www.npmjs.com/package/@drupal-canvas/cli
仅在用户确认配置完成后再继续。

Run push

执行推送

When component work is complete and validated, ask the user if they would like to push the current Canvas changes to Canvas.

canvas push --yes

will push all current changes; it does not support selecting specific components. If there are unrelated or unvalidated Canvas changes in the working tree, stop and ask the user how they want to proceed. Make sure to use the right package manager. For example, if using npm, run the following command:

bash

npx canvas push --yes

当组件开发完成并验证后，询问用户是否要将当前Canvas变更推送至Canvas。

canvas push --yes

会推送所有当前变更；该命令不支持选择特定组件。如果工作区中存在无关或未验证的Canvas变更，停止操作并询问用户如何处理。确保使用正确的包管理器。例如，若使用npm，运行以下命令：

bash

npx canvas push --yes

Handling push failures

处理推送失败

Default behavior: always retry failed pushes unless the error is clearly a connection/setup failure.

Retry pushes when the failure indicates the Canvas app connection is already working (for example, dependency/order-related component errors). Do not retry connection/setup failures.

默认行为：始终重试失败的推送，除非错误明确是连接/配置问题。

当失败表明Canvas应用连接正常时（例如，依赖/顺序相关的组件错误），重试推送。不要重试连接/配置失败的情况。

Connection/setup failures: Stop, do not retry

连接/配置失败：停止操作，不重试

If push fails with authentication, authorization, or network/connection errors, stop and ask the user to complete or verify setup first. This includes errors like invalid credentials, unauthorized/forbidden responses, DNS issues, connection refused, host unreachable, request timeout before reaching Canvas, or TLS/SSL handshake/certificate failures.

Point the user to the official setup docs:

Drupal Canvas OAuth module setup: https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
Drupal Canvas CLI package/docs: https://www.npmjs.com/package/@drupal-canvas/cli

Ask them to verify and update

.env

values (

CANVAS_SITE_URL

CANVAS_CLIENT_ID

CANVAS_CLIENT_SECRET

) and OAuth/CLI setup, then retry the push only after they confirm setup updates are complete.

如果推送因认证、授权或网络/连接错误失败，停止操作并要求用户先完成或验证配置。这类错误包括无效凭据、未授权/禁止访问响应、DNS问题、连接被拒绝、主机不可达、请求在到达Canvas前超时，或TLS/SSL握手/证书失败。

引导用户查看官方配置文档：

Drupal Canvas OAuth模块配置： https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
Drupal Canvas CLI包/文档： https://www.npmjs.com/package/@drupal-canvas/cli

要求用户验证并更新

.env

中的值（

CANVAS_SITE_URL

、

CANVAS_CLIENT_ID

、

CANVAS_CLIENT_SECRET

）以及OAuth/CLI配置，仅在用户确认配置更新完成后再重试推送。

Dependency-related failures

依赖相关失败

When pushing multiple new components where one component depends on another (e.g.,

hero

imports

heading

), the push may fail with a message indicating that a component doesn't exist. This happens when a component that includes another gets pushed before its dependency.

This is expected behavior. Simply retry the push command. On subsequent attempts, the dependencies that were successfully pushed in the previous run will already exist, allowing the dependent components to push successfully.

Example scenario:

First push attempt:
```
hero
```
fails because
```
heading
```
doesn't exist yet, but
```
heading
```
pushes successfully.
Second push attempt:
```
hero
```
now succeeds because
```
heading
```
exists.

If pushes continue to fail after multiple retries, check that all required dependency components are part of the current local changes or already exist in Canvas.

当推送多个新组件且其中一个组件依赖于另一个组件时（例如，

hero

导入

heading

），推送可能会失败并提示某个组件不存在。这是因为包含依赖项的组件在其依赖组件之前被推送导致的。

这是预期行为。只需重试推送命令。在后续尝试中，前一次运行中已成功推送的依赖项已存在，从而允许依赖组件成功推送。

示例场景：

第一次推送尝试：
```
hero
```
失败，因为
```
heading
```
尚未存在，但
```
heading
```
推送成功。
第二次推送尝试：
```
hero
```
现在可以成功推送，因为
```
heading
```
已存在。

如果多次重试后推送仍失败，检查所有必需的依赖组件是否属于当前本地变更，或是否已存在于Canvas中。