WordPress,Interactivity API,watch,state.url,state.navigation,WordPress 7.0,前端开发

WordPress 6.5 引入 Interactivity API 之后，我已经用它做了购物车、即时搜索、虚拟导航三套交互。WordPress 7.0 在 2026-05-20 正式发布时，官方 dev note 把这个 API 又往前推了一步：3 个改动（watch() / state.url 服务端预填 / state.navigation 弃用）会直接影响你生产代码里的状态订阅、analytics 接入和错误日志。这篇文章就是把这 3 个改动 + 升级到 7.0 之后我踩到的 2 个真实坑 + 迁移 checklist 全部交底。

⏳ 太长不看版 (TL;DR)

• **3 个 7.0 新变化**：`watch()` 函数（响应式订阅，可返回 unwatch + cleanup）/ `state.url` 在服务端就预填（不再 `undefined`）/ `state.navigation.hasStarted`/`hasFinished` 在 SCRIPT_DEBUG 下 console warning。
• **影响范围**：用 Interactivity API 做虚拟导航/购物车/即时搜索的站点全部中招，老插件 `useNavigationStatus()` 这类代码会在 7.1 之后彻底失效。
• **最低版本门槛**：WP 6.5+（已有 Interactivity API）→ WP 7.0（才有 `watch()` 和 SSR state.url）。
• **典型坑**：升级 7.0 后 analytics 抓不到虚拟导航（之前用 `window.addEventListener('popstate')` 替补失效）、老插件 deprecation warning 把日志刷屏。
• **迁移收益**：服务端预填 state.url → 首屏 LCP 提升 50-150ms（不再等 `window.location.href` 异步初始化）。

为什么 Interactivity API 在 7.0 变了？先看背景

Interactivity API 从 6.5 (2024-02 merge announcement) 开始就是 WordPress 的"轻量级 React 替代"——不用打包、不用 virtual DOM、用 data-wp-* 指令在前端做响应式状态绑定。6.5-6.8 这两年它在 Search/Query/Navigation/File 四个 Core 块里被大量使用，但是有一个长期被吐槽的硬伤：**所有响应式状态都得等客户端 JS 加载完才能初始化**。这意味着服务端渲染的 HTML 拿不到 URL、拿不到导航进度，window.location.href 永远是 undefined until first paint。

7.0 的修复思路是：

1. **新增 watch() 函数**（gutenberg #75563）→ 让你脱离 DOM 直接订阅 store 状态变化，比如 analytics、logger、跨 store 同步。

2. **state.url 移到服务端**（wordpress-develop #10944）→ 指令处理阶段就把 core/router 的 state.url 填好，首屏即可读。

3. **state.navigation 弃用**（gutenberg #70882）→ 之前一直当作内部实现细节（loading bar 用），现在公开 API 用就 console warning，7.1 起彻底移除。

🛠️ 前置准备 (Prerequisites)

在写 watch() 代码之前，先确认环境：

如果你还在 WP 6.5-6.8，那本文的 watch() 用不了，state.url 服务端预填也用不了——升级到 7.0 之后所有例子都能直接跑。

🚀 核心改动一：`watch()` 函数响应式订阅

watch() 是从 @wordpress/interactivity 7.0 开始新增的导出。它的语义是：传入的回调里访问了哪些响应式状态，那些状态变化时回调就会重新执行。这弥补了 data-wp-watch 必须挂在 DOM 上的限制——你现在可以在 store 级别做 side effects。

基础用法：counter 监控

import { store, watch } from '@wordpress/interactivity';

const { state } = store( 'myPlugin', {
    state: {
        counter: 0,
    },
} );

// 立即执行 + 每次 state.counter 变化时重新执行
watch( () => {
    console.log( 'Counter is ' + state.counter );
} );

返回值是 unwatch 回调，调用后停止监听：

const unwatch = watch( () => {
    console.log( 'Counter is ' + state.counter );
} );

// 后续停止监听
unwatch();

返回 cleanup 函数可以在每次重跑前/销毁时执行清理（典型场景：绑定 document 事件）：

const unwatch = watch( () => {
    const handler = () => { /* ... */ };
    document.addEventListener( 'click', handler );

    return () => {
        document.removeEventListener( 'click', handler );
    };
} );

实战场景 1：购物车 store + localStorage 同步

import { store, watch, getContext } from '@wordpress/interactivity';

const { state } = store( 'myPlugin/cart', {
    state: {
        items: [],
        total: 0,
    },
    actions: {
        addItem: ( { context } ) => {
            state.items.push( context.product );
            state.total += context.product.price;
        },
    },
} );

// 状态变化时持久化到 localStorage
watch( () => {
    localStorage.setItem( 'cart', JSON.stringify( state.items ) );
} );

之前 6.x 实现这个需要监听一个隐藏 DOM 元素 data-wp-watch="callbacks.persistCart"，现在直接在 JS 模块顶层写 watch()，代码读起来更线性。

实战场景 2：分析埋点（虚拟导航 PV）

把 watch() 和 state.url 配合（见下节）就能在客户端导航时发 PV，不需要再 hack popstate：

import { store, watch } from '@wordpress/interactivity';

const { state } = store( 'core/router' );

watch( () => {
    // 每次客户端导航 state.url 变化就触发
    sendAnalyticsPageView( state.url );
} );

🚀 核心改动二：`state.url` 服务端预填（SSR）

6.x 的旧坑

Interactivity API 在 6.5-6.8 里，core/router store 的 state.url 是在客户端通过 window.location.href 赋值的。这有两个问题：

1. **首屏永远是 undefined**：HTML 已经渲染完了，但 JS 还没加载，组件拿到的是空字符串。

2. **必须 guard**：所有读 state.url 的代码都得写 state.url ?? window.location.href，不然 SSR/CSR 不一致会触发 hydration warning。

7.0 的修复

state.url 现在在服务端指令处理阶段就预填（PR #10944）。它只在客户端第一次虚拟导航时改变。换句话说，**首屏 HTML 已经包含正确的 URL**。

具体效果——以下 view.php 模板：

7.0 渲染出的 HTML 直接是：

    https://example.com/shop/

7.0 之前你会拿到空 href。

踩坑实录 1：升级后 navigation analytics 抓不到 PV

我的 blog 在 7.0 之前用这段代码抓虚拟导航：

window.addEventListener( 'popstate', () => {
    sendPV( window.location.href );
} );

升级到 7.0 之后 client-side 路由（点击 site logo 回到首页）**不触发 popstate**，导致 GA4 少了一半的 PV。修复：换成 watch() + state.url：

import { store, watch } from '@wordpress/interactivity';

const { state } = store( 'core/router' );

watch( () => {
    sendPV( state.url );
} );

注意：只在客户端运行时挂载——服务端预填的 state.url 在第一次客户端导航前不会变化，所以这段代码服务端跑一次、客户端每次导航再跑一次，正好。

性能数据

我做的小 benchmark（Vultr 1 vCPU 2GB RAM + WP 7.0 + Twenty Twenty-Five）：

LCP 提升主要来自"不再等 JS 异步模块"——6.8 时代 @wordpress/interactivity-router 是异步 import 的，state.url 初始化延后，hydration 阶段会触发一次"重画"。7.0 之后这一步被绕过。

🚀 核心改动三：`state.navigation` 弃用迁移

弃用范围

7.0 起，以下两个属性在 SCRIPT_DEBUG 模式下读会触发 console warning：

import { store } from '@wordpress/interactivity';

const { state } = store( 'core/router' );

console.log( state.navigation.hasStarted );   // ⚠️ deprecation warning
console.log( state.navigation.hasFinished );  // ⚠️ deprecation warning

它们本来就是 loading bar 动画用的内部状态，从未是公开 API。WordPress 7.1 会添加官方的 navigation state 追踪机制（具体形式 dev note 没公布）。

谁会被影响

如果你站点使用了以下任一情况：

• 自己写过 `useNavigationStatus()` 这类自定义 hook → 需要改成 watch + state.url 或等待 7.1 官方 API
• 用了第三方插件（例如某 SEO 插件的"导航进度条"模块）→ 升级 7.0 后会在控制台看到 `state.navigation` deprecation warning
• 直接读 `state.navigation.hasStarted` 做 IntersectionObserver 替代 → 拆掉那段代码

踩坑实录 2：升级后日志被 deprecation warning 刷屏

我把客户站从 6.9 升到 7.0，WordPress debug.log 突然多了 200+ 条：

[info] state.navigation.hasStarted is deprecated since WordPress 7.0...
[info] state.navigation.hasFinished is deprecated since WordPress 7.0...

根因是 wp-content/plugins/super-navigation-progress-bar/super-navigation-progress-bar.js 在每个 page 都读一次这两个属性。修复方案（生产站临时止血）：在 wp-config.php 里设 define( 'SCRIPT_DEBUG', false );（生产环境本来就不该开 debug）。永久修复：升级该插件到 7.0+ 版本，或写个 mu-plugin 把那两个属性的读取 mock 成返回 false。