编码规范

export default function Notice( { children, onRemove } ) {
    return (
        <div className="components-notice">
            <div className="components-notice__content">{ children }</div>
            <Button
                className="components-notice__dismiss"
                icon={ check }
                label={ __( 'Dismiss this notice' ) }
                onClick={ onRemove }
            />
        </div>
    );
}

import clsx from 'clsx';

export default function Notice( { children, onRemove, isDismissible } ) {
    const classes = clsx( 'components-notice', {
        'is-dismissible': isDismissible,
    } );

    return <div className={ classes }>{ /* ... */ }</div>;
}

/**
 * External dependencies
 */
import moment from 'moment';

/**
 * WordPress 依赖项
 */
import { __ } from '@wordpress/i18n';

/**
 * 内部依赖
 */
import VisualEditor from '../visual-editor';

// 使用 globalThis.IS_GUTENBERG_PLUGIN 允许 Webpack 将此导出
// 从 WordPress 核心中排除：
if ( globalThis.IS_GUTENBERG_PLUGIN ) {
    export { doSomethingExciting } from './api';
}

// 在 packages/block-editor/private-apis.js 中：
import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
export const { lock, unlock } =
    __dangerousOptInToUnstableAPIsOnlyForCoreModules(
        '我确认私有功能不适用于主题或插件，否则将在下一版 WordPress 中失效。',
        '@wordpress/block-editor' // 调用 __dangerousOptInToUnstableAPIsOnlyForCoreModules 的包名称，
        //（不是你想访问其 API 的包名称）
    );

// 假设这个对象是从包中导出的：
export const publicObject = {};

// 但这个字符串是内部的，不应公开可用：
const privateString = '私有信息';

// 解决方案：将字符串“锁定”在对象内部：
lock( publicObject, privateString );

// 字符串未嵌套在对象中，也无法从中提取：
console.log( publicObject );
// {}

// 访问字符串的唯一方式是“解锁”对象：
console.log( unlock( publicObject ) );
// "私有信息"

// lock() 接受所有数据类型，不仅仅是字符串：
export const anotherObject = {};
lock( anotherObject, function privateFn() {} );
console.log( unlock( anotherObject ) );
// function privateFn() {}

// In packages/package1/store.js:
import { privateHasContentRoleAttribute } from './private-selectors';
import { privateToggleFeature } from './private-actions';
// The `lock` function is exported from the internal private-apis.js file where
// the opt-in function was called.
import { lock, unlock } from './lock-unlock';

export const store = registerStore( /* ... */ );
// Attach a private action to the exported store:
unlock( store ).registerPrivateActions( {
    privateToggleFeature,
} );

// Attach a private action to the exported store:
unlock( store ).registerPrivateSelectors( {
    privateHasContentRoleAttribute,
} );

// In packages/package2/MyComponent.js:
import { store } from '@wordpress/package1';
import { useSelect } from '@wordpress/data';
// The `unlock` function is exported from the internal private-apis.js file where
// the opt-in function was called.
import { unlock } from './lock-unlock';

function MyComponent() {
    const hasRole = useSelect(
        ( select ) =>
            // Use the private selector:
            unlock( select( store ) ).privateHasContentRoleAttribute()
        // Note the unlock() is required. This line wouldn't work:
        // select( store ).privateHasContentRoleAttribute()
    );

    // Use the private action:
    unlock( useDispatch( store ) ).privateToggleFeature();

    // ...
}

// 在 packages/package1/index.js 中：
import { lock } from './lock-unlock';

export const privateApis = {};
/* 将私有数据附加到导出的对象上 */
lock( privateApis, {
    privateCallback: function () {},
    privateReactComponent: function PrivateComponent() {
        return <div />;
    },
    privateClass: class PrivateClass {},
    privateVariable: 5,
} );

// 在 packages/package2/index.js 中：
import { privateApis } from '@wordpress/package1';
import { unlock } from './lock-unlock';

const {
    privateCallback,
    privateReactComponent,
    privateClass,
    privateVariable,
} = unlock( privateApis );

export const store = createReduxStore( STORE_NAME, storeConfig() );
// `register` 使用与 `createReduxStore` 创建的相同的 `store` 对象。
register( store );
unlock( store ).registerPrivateActions( {
    // ...
} );

export const store = createReduxStore( STORE_NAME, {
    ...storeConfig,
    persist: [ 'preferences' ],
} );
const registeredStore = registerStore( STORE_NAME, {
    ...storeConfig,
    persist: [ 'preferences' ],
} );
unlock( registeredStore ).registerPrivateActions( {
    // ...
} );

// In @wordpress/package1/index.js:
import { lock } from './lock-unlock';

// A private function contains all the logic
function privateValidateBlocks( formula, privateIsStrict ) {
    let isValid = false;
    // ...complex logic we don't want to duplicate...
    if ( privateIsStrict ) {
        // ...
    }
    // ...complex logic we don't want to duplicate...

    return isValid;
}

// The stable public function is a thin wrapper that calls the
// private function with the private features disabled
export function validateBlocks( blocks ) {
    privateValidateBlocks( blocks, false );
}

export const privateApis = {};
lock( privateApis, { privateValidateBlocks } );

// In @wordpress/package2/index.js:
import { privateApis as package1PrivateApis } from '@wordpress/package1';
import { unlock } from './lock-unlock';

// The private function may be "unlocked" given the stable function:
const { privateValidateBlocks } = unlock( package1PrivateApis );
privateValidateBlocks( blocks, true );

// In @wordpress/package1/index.js:
import { lock } from './lock-unlock';

// The private component contains all the logic
const PrivateMyButton = ( { title, privateShowIcon = true } ) => {
    // ...complex logic we don't want to duplicate...

    return (
        <button>
            { privateShowIcon && <Icon src={ someIcon } /> } { title }
        </button>
    );
};

// The stable public component is a thin wrapper that calls the
// private component with the private features disabled
export const MyButton = ( { title } ) => (
    <PrivateMyButton title={ title } privateShowIcon={ false } />
);

export const privateApis = {};
lock( privateApis, { PrivateMyButton } );

// In @wordpress/package2/index.js:
import { privateApis } from '@wordpress/package1';
import { unlock } from './lock-unlock';

// The private component may be "unlocked" given the stable component:
const { PrivateMyButton } = unlock( privateApis );
export function MyComponent() {
    return <PrivateMyButton data={ data } privateShowIcon={ true } />;
}

const privateSettings = [
    'inserterMediaCategories',
    // 在此处列出区块编辑器设置以使其私有化
];

export function toggleFeature( scope, featureName ) {
    return function ( { dispatch } ) {
        dispatch( { type: '__private_BEFORE_TOGGLE' } );
        // ...
    };
}

// 此函数在任何上下文中都不能被扩展开发者使用：
function privateEverywhere() {}

// 此函数可以在 Gutenberg 插件中被扩展开发者使用，但不能在原生 WordPress 核心中使用：
function privateInCorePublicInPlugin() {}

// Gutenberg 在内部将这两个函数都视为私有 API：
const privateApis = {};
lock( privateApis, { privateEverywhere, privateInCorePublicInPlugin } );

// privateInCorePublicInPlugin 函数被显式导出，
// 但由于 globalThis.IS_GUTENBERG_PLUGIN 检查，此导出不会合并到 WordPress 核心中。
if ( globalThis.IS_GUTENBERG_PLUGIN ) {
    export const privateInCorePublicInPlugin =
        unlock( privateApis ).privateInCorePublicInPlugin;
}

const a = 10;

// 不推荐：
const object = {
    a: a,
    performAction: function () {
        // ...
    },
};

// 推荐：
const object = {
    a,
    performAction() {
        // ...
    },
};

// 错误：
const name = "Matt";
// 正确：
const name = 'Matt';

// 错误：
const pet = "Matt's dog";
// 同样错误（未使用撇号）：
const pet = "Matt's dog";
// 正确：
const pet = 'Matt’s dog';
// 同样正确：
const oddString = "She said 'This is odd.'";

const name = 'Stacey';

// 错误：
alert( 'My name is ' + name + '.' );
// 正确：
alert( `My name is ${ name }.` );

/**
 * 块选择对象。
 *
 * @typedef WPBlockSelection
 *
 * @property {string} clientId     块客户端 ID。
 * @property {string} attributeKey 块属性键。
 * @property {number} offset       属性值偏移量，基于富文本值。
 */

/**
 * 命名的断点尺寸。
 *
 * @typedef {'huge'|'wide'|'large'|'medium'|'small'|'mobile'} WPBreakpoint
 */

/** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */

// packages/data/src/index.js

/** @typedef {import('./registry').WPDataRegistry} WPDataRegistry */

// 错误示例：

/** @type {Object} */
/** @type {Function} */
/** @type {Promise} */

// 正确示例：

/** @type {Record<string,number>} */ /* 或 */ /** @type {{[setting:string]:any}} */
/** @type {(key:string)=>boolean} */
/** @type {Promise<string>} */

/**
 * apiFetch 中间件处理程序。传入 fetch 选项后，中间件应在完成处理后调用 `next` 中间件。
 *
 * @typedef {(options:WPAPIFetchOptions,next:WPAPIFetchMiddleware)=>void} WPAPIFetchMiddleware
 */

/**
 * 命名的断点尺寸。
 *
 * @typedef {"huge"|"wide"|"large"|"medium"|"small"|"mobile"} WPBreakpoint
 */

/**
 * 断点名称与生效像素宽度的哈希映射。
 *
 * @type {Record<WPBreakpoint,number>}
 */
const BREAKPOINTS = { huge: 1440 /* , ... */ };

/**
 * 返回给定键的配置值（如果存在）。如果没有配置值，则返回 null。
 *
 * @param {string} key 要检索的配置键。
 *
 * @return {?*} 配置值（如果存在）。
 */
function getConfigurationValue( key ) {
    return config.hasOwnProperty( key ) ? config[ key ] : null;
}

/**
 * 如果下一个 HTML 令牌关闭了当前令牌，则返回 true。
 *
 * @param {WPHTMLToken}           currentToken 要比较的当前令牌。
 * @param {WPHTMLToken|undefined} nextToken    要比较的下一个令牌。
 *
 * @return {boolean} 如果 `nextToken` 关闭了 `currentToken`，则为 true，否则为 false。
 */

/**
 * 渲染一个工具栏。
 *
 * @param {Object} props             组件属性。
 * @param {string} [props.className] 要设置在容器 `<div />` 上的类。
 */

/**
 * 返回给定键的配置值（如果存在）。
 *
 * @param {string} key 要检索的配置键。
 *
 * @return {*|void} 配置值（如果存在）。
 */
function getConfigurationValue( key ) {
    if ( config.hasOwnProperty( key ) ) {
        return config[ key ];
    }
}

/**
 * 一个 apiFetch 中间件处理程序。传递获取选项后，中间件应在完成其处理后调用 `next` 中间件。
 *
 * @typedef {(options:WPAPIFetchOptions,next:WPAPIFetchMiddleware)=>void} WPAPIFetchMiddleware
 */

/**
 * 给定已注册存储的名称，返回该存储选择器的对象。选择器函数已预先绑定，以自动传递当前状态。作为使用者，您只需传递选择器的参数（如果适用）。
 *
 * @param {string} name 存储名称。
 *
 * @example
 * ```js
 * select( 'my-shop' ).getPrice( 'hammer' );
 * ```
 *
 * @return {Record<string,WPDataSelector>} 包含该存储选择器的对象。
 */

/**
 * 将区块配置的标题渲染为字符串，如果无法确定标题，则渲染为空。
 *
 * @example
 *
 * ```jsx
 * <BlockTitle clientId="afd1cb17-2c08-4e7a-91be-007ba7ddc3a1" />
 * ```
 *
 * @param {Object} props
 * @param {string} props.clientId 区块的客户端 ID。
 *
 * @return {?string} 区块标题。
 */