ofa.js Documentation Guide

<span title="{{$data.appId}}">{{$data.appId}}</span>
<a href="{{url}}">链接</a>
<img alt="{{name}}" src="/x.png">
<div data-id="{{id}}"></div>

<span attr:title="$data.appId">{{$data.appId}}</span>
<a attr:href="url">链接</a>
<img attr:alt="name" src="/x.png">
<div attr:data-id="id"></div>

<p-button color="primary" :disabled="analyzing">AI 识别</p-button>
<!-- analyzing === false 时渲染出 disabled="false"，照样禁用 -->

<p-button color="primary" attr:disabled="analyzing">AI 识别</p-button>
<!-- analyzing === false → 不设置 disabled 属性；analyzing === true → 属性存在，禁用 -->

<div class="message" :class="$data.type">
  {{$data.text}}
</div>

<style>
.message.sent { color: blue; }
.message.received { color: green; }
</style>

<div class="message" attr:type="$data.type">
  {{$data.text}}
</div>

<style>
.message[type="sent"] { color: blue; }
.message[type="received"] { color: green; }
</style>

const messagesDiv = this.shadow.getElementById("messages");
const element = this.shadow.querySelector(".class");

const messagesDiv = this.shadow.$("#messages");
const element = this.shadow.$(".class");

const messagesDiv = this.shadow.$("#messages");
messagesDiv.scrollTop = messagesDiv.scrollHeight;  // scrollTop 是原生属性

const messagesDiv = this.shadow.$("#messages");
messagesDiv.ele.scrollTop = messagesDiv.ele.scrollHeight;

// Playwright 测试或浏览器控制台中
const cur = $("o-app").current;
cur.shadowRoot                    // → undefined（shadowRoot 是原生属性）
cur.shadowRoot.querySelector(...) // → 报错 not a function

const cur = $("o-app").current;
cur.ele.shadowRoot                          // ✅ 通过 .ele 访问原生 shadowRoot
cur.ele.shadowRoot.querySelector(".item")   // ✅ 原生查询
cur.src                                     // ✅ ofa.js 包装对象的属性可直接访问
cur.data                                    // ✅ ofa.js data 可直接访问

export default async () => {
  return {
    tag: "my-component",
    data: { size: 1024 },
    proto: {
      $formatBytes(val) {
        return (val / 1024).toFixed(2) + " KB";
      }
    }
  };
};

<span>{{$formatBytes(size)}}</span>

export default async () => {
  return {
    tag: "my-component",
    data: { size: 1024 },
    proto: {
      formatBytes(val) {
        return (val / 1024).toFixed(2) + " KB";
      }
    }
  };
};

<span>{{formatBytes(size)}}</span>

<o-fill :value="files" fill-key="id">
  <span>{{$host.formatBytes($data.size)}}</span>
</o-fill>

页面 http://.../xxx.html 的注册参数有误，'proto'上的'back'已被占用，请将'back'改为其他名字。

export default async () => ({
  data: { dialogOpen: false },
  proto: {
    back() {           // ❌ 与内置后退导航 back() 重名
      this.phase = "input";
    },
  },
});

export default async () => ({
  data: { dialogOpen: false },
  proto: {
    backToInput() {    // ✅ 语义化命名，避免与内置 back() 冲突
      this.phase = "input";
    },
  },
});

<div attr:style="width: {{pct}}%"></div>

<div :style.width="pct + '%'"></div>

Error: Error evaluating text expression: 'roleText'

export default async ({ query }) => {
  return {
    data: {
      userInfo: {},  // 初始为空对象
    },
    get roleText() {
      // 模板初始化时立刻求值，此时 userInfo 还是 {}
      // 若 userInfo 是 null/undefined 或做深层链式访问就会 TypeError
      return ROLE_TEXT[this.userInfo.role] || "";
    },
    ready() {
      this.loadInfo(); // 异步赋值 userInfo，但来不及
    },
    proto: {
      async loadInfo() { /* ... */ }
    }
  };
};
// 模板：{{roleText}}

export default async ({ query }) => {
  return {
    data: {
      userInfo: {},
      roleText: "",  // 预定义为安全默认值
    },
    ready() {
      this.loadInfo();
    },
    proto: {
      async loadInfo() {
        const info = await api.getInfo();
        this.userInfo = info;
        this.roleText = ROLE_TEXT[info.role] || info.role || ""; // 异步回调中赋值
      },
    },
  };
};
// 模板：{{roleText}}

Error: Error evaluating element expression: ':value="flag"', from file: ...
Caused by: ReferenceError: flag is not defined

<x-if :value="noBg === 'off'">...</x-if>
<p-switch sync:value="noBg">无底色</p-switch>

<script>
  export default async () => ({
    data: { dialogOpen: false }, // ❌ 缺 noBg 声明
  });
</script>

<script>
  export default async () => ({
    data: { dialogOpen: false, noBg: "off" }, // ✅ 模板引用的键全部声明
  });
</script>

const link = location.origin + location.pathname + "#./pages/set-password.html?token=xxx";
// 结果：http://host/index.html#./pages/set-password.html?token=xxx  ← 错误

const link = location.origin + "/#/pages/set-password.html?token=xxx";
// 结果：http://host/#/pages/set-password.html?token=xxx  ← 正确

<o-page :src="'./form.html?id=' + editingId"></o-page>

<!-- 宿主页面 -->
<template page>
  <o-page id="form-page" src="./form.html" on:form-save="onSave"></o-page>
  <script>
    export default async () => ({
      proto: {
        openForm(item) {
          // $() 拿到的是 ofa.js 包装对象，可直接调用子页面方法
          this.shadow.$("#form-page")?.openForm(item);
        },
        onSave(event) {
          console.log(event.data); // 子页面上抛的表单值
        },
      },
    });
  </script>
</template>

<!-- 子页面 form.html：自带 p-dialog，暴露 openForm 供宿主打开 -->
<template page>
  <p-dialog sync:open="dialogOpen" auto-close><!-- 表单控件 sync:value="form.xxx" --></p-dialog>
  <script>
    export default async () => ({
      data: { dialogOpen: false, form: {} },
      proto: {
        openForm(params) {
          Object.assign(this.form, params); // 回填参数
          this.dialogOpen = true;
        },
        save() {
          if (!this.form.name.trim()) return; // 子页面只管非空校验
          this.emit("form-save", {
            data: { ...this.form },
            bubbles: true,
            composed: true, // 穿透 Shadow DOM，宿主才能监听
          });
          this.dialogOpen = false;
        },
      },
    });
  </script>
</template>