Velo 入门完全实战：从 $w 元素选择器到页面数据动态绑定

30秒核心速览 (Executive Summary)

当可视化拖拽无法满足复杂的业务逻辑（如多重表单联动校验、自定义货币换算器、外部 CRM 实时推送）时，Velo 就是 Wix Studio 的终极生产力引擎。

Velo 允许你在浏览器端直接编写现代化 ES6+ JavaScript，通过类似 jQuery 却具备完整 TypeScript 类型提示的 $w('#elementId') 语法操控页面上的任意按钮、输入框、文本与 Repeater，免去 Node.js 环境部署与 Webpack 构建打包的烦恼。

1. 开启 Dev Mode 开发人员模式与 Monaco IDE

在 Wix Studio 编辑器顶部导航栏中，点击 Dev Mode（开发模式） 开关并点击开启。

开启后界面发生的核心变化：

底部滑出集成 Monaco IDE 的代码编辑器窗口，支持智能代码补全、语法高亮与 ESLint 实时校验；
左侧导航栏新增代码资源管理器，包含 Page Code、Public、Backend 与 Database Collections 目录；
选中画布上的任何元素，右侧属性栏均会显示其唯一的 ID（例如 #submitButton, #heroHeading），可自由重命名。

2. 核心语法：$w 页面元素选择器与属性操控

在 Velo 中，$w 是用于获取页面 DOM 代理对象的全局函数：

// 1. 修改元素文字与样式状态

$w('#welcomeText').text = "欢迎回来，尊敬的企业 VIP 买家！";

$w('#promoBanner').show('fade', { 'duration': 400 });

// 2. 读取输入框数值

const userEmail = $w('#emailInput').value;

// 3. 折叠元素（不占空间）与隐藏元素（保留占位）

$w('#errorBox').collapse(); // 页面内容向上自动收缩

$w('#loadingSpinner').hide(); // 仅透明隐藏

3. 生命周期与事件监听：onReady & onClick

所有页面级别的代码都必须放在 $w.onReady() 回调函数中，确保视觉组件已在 DOM 树中解析就绪：

$w.onReady(function () {

// 页面就绪后，为计算按钮绑定点击事件监听器

$w('#calcButton').onClick(() => {

const amount = Number($w('#amountInput').value);

if (isNaN(amount) || amount <= 0) {

$w('#errorBox').expand();

return;

}

const total = amount * 1.08; // 加征 8% 运杂费预估

$w('#resultText').text = `离岸预估总额：${total.toFixed(2)}`;

});

4. wix-data API：零后端 SQL 数据库异步查询

无需手动编写复杂 SQL 或配置 Node.js ORM，通过原生 wix-data 模块即可对 CMS 数据库发起异步链式查询：

import wixData from 'wix-data';

async function loadFeaturedProjects() {

const results = await wixData.query("Portfolio")

.eq("isFeatured", true)

.descending("_createdDate")

.limit(6)

.find();

// 将查询返回的纯 JSON 数组直接赋值给 Repeater 渲染

$w('#portfolioRepeater').data = results.items;

}

5. 实战避坑指南：异步未 await 与选择器 ID 混淆

避坑 1：在 $w.onReady 之外调用 DOM 元素导致 undefined

若在页面脚本最顶层直接书写 $w('#button1').text = "..."，由于此时浏览器的 HTML 尚未解析完该元素，代码会直接抛出 Cannot read properties of undefined 错误。必须包裹在 $w.onReady() 内部。

避坑 2：Repeater 内部元素错误使用了全局 $w 选择器

在 Repeater 循环项中，直接使用 $w('#cardTitle').text = "..." 会导致所有列表卡片的标题变成一模一样的内容！正确做法是使用局部 item 选择器：$w('#repeater').onItemReady(($item, itemData) => { $item('#cardTitle').text = itemData.title; })。

6. Wix 官方 Support 权威参考文档

深入学习 Velo 框架的底层规范与完整 API：

Velo: About Velo by WixOfficial Support

官方关于 Velo 全栈开发平台的架构设计、前后端安全隔离与适用场景综述。

Velo Reference: $w Page Element Selector APIOfficial Support

官方关于 $w 选择器属性（.text, .value, .collapsed, .hidden）与交互事件的完整 API 参考。

Velo: Working in the Code PanelOfficial Support

如何在 Wix Studio 编辑器底部使用内置 Monaco IDE 进行语法高亮、断点调试与 Console 日志查看。

7. 高频常见问题解答 (FAQ)

Q：Velo 支持安装 npm 开源第三方库吗？

完全支持！在左侧代码面板中的 Packages (npm) 分类下，点击 + 即可一键搜索并安装 lodash, dayjs, axios, crypto-js 等海量主流 npm 库，直接在前端或后端 import 即可。

Q：Velo 前端代码对访客公开吗？密钥该存放在哪里？

Page Code 运行在用户浏览器中，访客可通过 F12 查看源码。涉及第三方 API 密钥（如 Stripe、OpenAI、ERP Token）严禁写在 Page Code，必须存放在 Backend Web Modules (.jsw) 并配合 Secrets Manager 加密管理。