Proxy

Baseline

Widely available

This feature is well established and works across many devices and browser versions. Its been available across browsers since setembro de 2016.

See full compatibility
Learn more

O objeto Proxy usado para definir comportamentos customizados para operaes fundamentais (por exemplo, pesquisa de propriedade, atribuio, enumerao, invocao de funo, etc.).

Terminologia

handler: Objeto marcador que contm traps.
traps: Mtodos que fornecem acesso propriedade. Isto anlogo ao conceito de traps (armadilhas) em sistemas operacionais
target: Objeto que o proxy virtualiza. frequentemente utilizado como back-end de armazenamento para o proxy. Os invariantes (semnticas que permanecem inalterados) em relao no-extensibilidade do objeto ou propriedades no-configurveis so verificados em relao ao target.

Sintaxe

var p = new Proxy(target, handler);

Parmetros

target: Um objeto target (pode ser qualquer tipo de objeto, incluindo um array, uma funo ou at mesmo outro Proxy) a ser envolvido com o Proxy.
handler: Um objeto cujas propriedades so funes que definem o comportamento do proxy quando uma operao realizada sobre ele.

Mtodos

Proxy.revocable(): Cria um objeto Proxy revogvel.

Mtodos para manipular objetos

O objeto manipulado um objeto reservado que contm traps para Proxy.

Exemplos

Exemplo bsico

Neste exemplo simples, o nmero 37 retornado como o valor padro quando o nome da propriedade no est no objeto. Usa-se o manipulador get.

var handler = {
  get: function (target, name) {
    return name in target ? target[name] : 37;
  },
};

var p = new Proxy({}, handler);
p.a = 1;
p.b = undefined;

console.log(p.a, p.b); // 1, undefined
console.log("c" in p, p.c); // false, 37

Encaminhamento de Proxy

Neste exemplo, estamos usando um objeto JavaScript nativo ao qual nosso proxy ir encaminhar todas as operaes que so aplicadas para ele.

var target = {};
var p = new Proxy(target, {});

p.a = 37; // Operao encaminhada para o alvo

console.log(target.a); // 37. A operao foi devidamente encaminhada

Validao

Com um Proxy, voc pode validar facilmente o valor passado para um objeto. Este exemplo usa o manipulador set.

let validator = {
  set: function (obj, prop, value) {
    if (prop === "age") {
      if (!Number.isInteger(value)) {
        throw new TypeError("The age is not an integer");
      }
      if (value > 200) {
        throw new RangeError("The age seems invalid");
      }
    }

    //O comportamento padro para armazenar o valor
    obj[prop] = value;

    // Indique o sucesso
    return true;
  },
};

let person = new Proxy({}, validator);

person.age = 100;
console.log(person.age); // 100
person.age = "young"; // Lana uma exceo
person.age = 300; // Lana uma exceo

Construtor de extenso

Um proxy de funo poderia facilmente estender um construtor com um novo construtor. Este exemplo usa os manipuladores construct e apply.

function extend(sup, base) {
  var descriptor = Object.getOwnPropertyDescriptor(
    base.prototype,
    "constructor",
  );
  base.prototype = Object.create(sup.prototype);
  var handler = {
    construct: function (target, args) {
      var obj = Object.create(base.prototype);
      this.apply(target, obj, args);
      return obj;
    },
    apply: function (target, that, args) {
      sup.apply(that, args);
      base.apply(that, args);
    },
  };
  var proxy = new Proxy(base, handler);
  descriptor.value = proxy;
  Object.defineProperty(base.prototype, "constructor", descriptor);
  return proxy;
}

var Person = function (name) {
  this.name = name;
};

var Boy = extend(Person, function (name, age) {
  this.age = age;
});

Boy.prototype.sex = "M";

var Peter = new Boy("Peter", 13);
console.log(Peter.sex); // "M"
console.log(Peter.name); // "Peter"
console.log(Peter.age); // 13

DOM manipulao de ns

s vezes, voc deseja alternar o atributo ou o nome da classe de dois elementos diferentes. Veja como usar o manipulador set.

let view = new Proxy(
  {
    selected: null,
  },
  {
    set: function (obj, prop, newval) {
      let oldval = obj[prop];

      if (prop === "selected") {
        if (oldval) {
          oldval.setAttribute("aria-selected", "false");
        }
        if (newval) {
          newval.setAttribute("aria-selected", "true");
        }
      }

      // O comportamento para armazenar o valor padro
      obj[prop] = newval;

      // Indica o sucesso
      return true;
    },
  },
);

let i1 = (view.selected = document.getElementById("item-1"));
console.log(i1.getAttribute("aria-selected")); // 'true'

let i2 = (view.selected = document.getElementById("item-2"));
console.log(i1.getAttribute("aria-selected")); // 'false'
console.log(i2.getAttribute("aria-selected")); // 'true'

Correo de valor e uma propriedade extra

O objeto de proxy produtos avalia o valor passado e converte-o em uma matriz, se necessrio. O objeto tambm suporta uma propriedade adicional chamada latestBrowser tanto em getters como em setters.

let products = new Proxy(
  {
    browsers: ["Internet Explorer", "Netscape"],
  },
  {
    get: function (obj, prop) {
      // An extra property
      if (prop === "latestBrowser") {
        return obj.browsers[obj.browsers.length - 1];
      }

      //  O comportamento para armazenar o valor padro
      return obj[prop];
    },
    set: function (obj, prop, value) {
      // An extra property
      if (prop === "latestBrowser") {
        obj.browsers.push(value);
        return true;
      }

      // Converta o valor se no for uma matriz
      if (typeof value === "string") {
        value = [value];
      }

      //  O comportamento para armazenar o valor padro
      obj[prop] = value;

      // Indicate success
      return true;
    },
  },
);

console.log(products.browsers); // ['Internet Explorer', 'Netscape']
products.browsers = "Firefox"; // pass a string (by mistake)
console.log(products.browsers); // ['Firefox'] <- no problem, the value is an array

products.latestBrowser = "Chrome";
console.log(products.browsers); // ['Firefox', 'Chrome']
console.log(products.latestBrowser); // 'Chrome'

Encontrando um item de objeto em uma matriz por propriedade

Esta proxy estende uma matriz com alguns recursos de utilidade. Como voc v, voc pode "definir" propriedades flexveis sem usar Object.defineProperties. Este exemplo pode ser adaptado para encontrar uma linha de tabela por sua clula. Nesse caso, o alvo ser table.rows

let products = new Proxy(
  [
    { name: "Firefox", type: "browser" },
    { name: "SeaMonkey", type: "browser" },
    { name: "Thunderbird", type: "mailer" },
  ],
  {
    get: function (obj, prop) {
      // O comportamento para retornar o valor; Prop geralmente  um inteiro
      if (prop in obj) {
        return obj[prop];
      }

      // Obter o nmero de produtos; Com products.length
      if (prop === "number") {
        return obj.length;
      }

      let result,
        types = {};

      for (let product of obj) {
        if (product.name === prop) {
          result = product;
        }
        if (types[product.type]) {
          types[product.type].push(product);
        } else {
          types[product.type] = [product];
        }
      }

      // Obtm um produto por nome
      if (result) {
        return result;
      }

      // Obtm produtos por tipo
      if (prop in types) {
        return types[prop];
      }

      // Obtm tipos de produto
      if (prop === "types") {
        return Object.keys(types);
      }

      return undefined;
    },
  },
);

console.log(products[0]); // { name: 'Firefox', type: 'browser' }
console.log(products["Firefox"]); // { name: 'Firefox', type: 'browser' }
console.log(products["Chrome"]); // undefined
console.log(products.browser); // [{ name: 'Firefox', type: 'browser' }, { name: 'SeaMonkey', type: 'browser' }]
console.log(products.types); // ['browser', 'mailer']
console.log(products.number); // 3

Um exemplo completo de lista de `traps`

Agora, para criar uma lista completa de amostra de traps, para fins didticos, tentaremos propor um objeto no nativo que seja particularmente adequado para este tipo de operao: o objeto global docCookies criado por a "little framework" publicada na pginadocument.cookie.

/*
  var docCookies = ... get the "docCookies" object here:
  https://developer.mozilla.org/pt-BR/docs/DOM/document.cookie#A_little_framework.3A_a_complete_cookies_reader.2Fwriter_with_full_unicode_support
*/

var docCookies = new Proxy(docCookies, {
  get: function (oTarget, sKey) {
    return oTarget[sKey] || oTarget.getItem(sKey) || undefined;
  },
  set: function (oTarget, sKey, vValue) {
    if (sKey in oTarget) {
      return false;
    }
    return oTarget.setItem(sKey, vValue);
  },
  deleteProperty: function (oTarget, sKey) {
    if (sKey in oTarget) {
      return false;
    }
    return oTarget.removeItem(sKey);
  },
  enumerate: function (oTarget, sKey) {
    return oTarget.keys();
  },
  ownKeys: function (oTarget, sKey) {
    return oTarget.keys();
  },
  has: function (oTarget, sKey) {
    return sKey in oTarget || oTarget.hasItem(sKey);
  },
  defineProperty: function (oTarget, sKey, oDesc) {
    if (oDesc && "value" in oDesc) {
      oTarget.setItem(sKey, oDesc.value);
    }
    return oTarget;
  },
  getOwnPropertyDescriptor: function (oTarget, sKey) {
    var vValue = oTarget.getItem(sKey);
    return vValue
      ? {
          value: vValue,
          writable: true,
          enumerable: true,
          configurable: false,
        }
      : undefined;
  },
});

/* Teste Cookies */

console.log((docCookies.my_cookie1 = "First value"));
console.log(docCookies.getItem("my_cookie1"));

docCookies.setItem("my_cookie1", "Changed value");
console.log(docCookies.my_cookie1);

Especificaes

Specification
ECMAScript 2027 LanguageSpecification # sec-proxy-objects

Navegadores Compatveis

Notas Especificas Gecko

No momento, Object.getPrototypeOf(proxy) retorna incondicionalmente um Object.getPrototypeOf(target), porque a trap ES2015 getPrototypeOf no foi implementada (Erro do Firefox 795904, Erro do Firefox 888969).
Array.isArray(proxy) retorna incondicionalmente um Array.isArray(target) (Erro do Firefox 1096753, Erro do Firefox 1111785).
Object.prototype.toString.call(proxy) retorna incondicionalmente Object.prototype.toString.call(target), porque ES2015 Symbol.toStringTag no foi implementado (Erro do Firefox 1114580).

Veja tambm

"Proxies are awesome" Brendan Eich presentation at JSConf (slides)
ECMAScript Harmony Proxy proposal page e ECMAScript pgina de semntica de proxy Harmony
Tutorial em proxies
SpiderMonkey specific Old Proxy API
Object.watch() um recurso no padro, mas foi suportado no Gecko h muito tempo.

`Nota de licena`

Alguns contedos (texto, exemplos) nesta pgina foram copiados ou adaptados do ECMAScript wiki que contm licena de contedo CC 2.0 BY-NC-SA.

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 17 de jul. de 2026 by MDN contributors.

View this page on GitHub Report a problem with this content

Proxy

In this article

Help improve MDN